Cover Object Visit Gap Tool

Description

Select and sort times for selectedObject, subtract the reference from each adjacent gap, and return extremes with defined false and zero placeholders if fewer than two visits.

Wildlife survey effort can use observer-hours, trap-nights, observation windows, or repeated visits. Equivalent effort applies a declared reporting rule and does not automatically correct detection probability.

Select and sort times for selectedObject, subtract the reference from each adjacent gap, and return extremes with defined false and zero placeholders if fewer than two visits.

When to use this tool

Use Cover Object Visit Gap when you need one explicit herpetological survey-effort component.

How to use the tool and how it works

Enter objectIds, visitTimes, selectedObject, referenceInterval. Keep parallel arrays aligned. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read visitCount, shortestGap, longestGap, defined. Inspect defined before interpreting the associated values.

Require aligned objectIds and visitTimes and nonnegative referenceInterval. Select and sort times for selectedObject, subtract the reference from each adjacent gap, and return extremes with defined false and zero placeholders if fewer than two visits.^[1]

Input field	Meaning and units	Accepted input
objectIds	Object Ids	Required. Array of text; maximum UTF-16 length 8192; maximum items 256.
visitTimes	Visit Times	Required. Array of finite number; maximum items 256.
selectedObject	Selected Object	Required. Text; maximum UTF-16 length 8192.
referenceInterval	Reference Interval	Required. Finite number; minimum 0.

Output field	Interpretation	Returned shape
visitCount	Visit Count	Required. Safe integer.
shortestGap	Smallest adjacent-visit duration minus referenceInterval; zero placeholder when undefined.	Required. Finite number.
longestGap	Largest adjacent-visit duration minus referenceInterval; zero placeholder when undefined.	Required. Finite number.
defined	Whether the associated ratio has its required denominator; inspect before using a zero placeholder.	Required. Boolean.

json

{
  "input": {
    "objectIds": [
      "A",
      "B",
      "A",
      "A"
    ],
    "visitTimes": [
      0,
      1,
      5,
      8
    ],
    "selectedObject": "A",
    "referenceInterval": 4
  },
  "output": {
    "visitCount": 3,
    "shortestGap": -1,
    "longestGap": 1,
    "defined": true
  }
}

Limitations and assumptions

Returned gaps are deviations from the reference interval, not raw gaps; duplicate times are retained and actual object identity and survey adequacy are not verified.
Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Review the complete survey design, environmental conditions, detection methods, and appropriate wildlife protocols.

References

Calculation and input contract: herpetology/cover-object-visit-gap — tool.io

Similar or alternative tools

Survey Cover Object Exposure
Multiply nonnegative integer objects and visits with exact integer intermediates, require unavailableObjectVisits within that product, and subtract unavailable visits for usableObjectVisits.
Trap Night Partial Effort Term
Return full nights plus summed partial hours divided by hours per night.