HydrophoneDeploymentChecker

Check deployment dates and data availability for ONC hydrophones.

Initialize the deployment checker.

Parameters:

Name	Type	Description	Default
onc_token	str	ONC API token	required
debug	bool	Enable debug logging	False

_archive_cache = {} instance-attribute

_deployments_cache = None instance-attribute

_deployments_cache_at = None instance-attribute

_device_deployments_cache = {} instance-attribute

_device_deployments_cache_at = {} instance-attribute

_location_cache = {} instance-attribute

_location_cache_built = False instance-attribute

_location_paths = {} instance-attribute

_location_paths_built = False instance-attribute

debug = debug instance-attribute

onc = ONC(onc_token, showInfo=debug, showWarning=debug) instance-attribute

_align_to_bin_start(dt_obj, bin_size)

_build_location_cache()

Build cache of location information and hierarchy paths.

_check_archive_availability_parallel(device_codes, start_date, end_date, max_workers=10)

Check archive file availability for multiple devices in parallel.

_check_product_availability_parallel(device_codes, max_workers=10)

Check data product availability for multiple devices in parallel.

_coerce_datetime(value, tz)

_extract_archive_file_intervals(archive_response)

_fetch_archive_intervals(device_code, start_utc, end_utc, *, max_days_per_request=60, progress=None, quiet=True, max_workers=4, request_delay_seconds=0.0)

_filter_inventory_by_devices(inventory, *, device_codes=None, device_ids=None)

_get_cached_deployments(max_age_minutes=30)

Return cached deployments if fresh, otherwise fetch new ones.

_get_deployments_parallel(hydrophones, max_workers=10)

Fetch deployments for multiple hydrophones in parallel.

_get_device_deployments(device_code, max_age_minutes=30)

Fetch deployments for a single device (cached) for faster queries.

_iter_bins(start_local, end_local, bin_size)

_merge_intervals(intervals)

_parse_deployment(deployment_dict)

Parse a deployment dictionary into a DeploymentInfo object.

_parse_duration_seconds(record)

_parse_timestamp(value)

_resolve_display_location(leaf_name, path)

Decide which human-friendly location name to show. For array elements where the leaf is "Hydrophone A/B/C...", prefer the parent site name.

check_data_availability(deployments, start_date, end_date, check_archive=False)

Check data availability for deployments in the specified time range.

Parameters:

Name	Type	Description	Default
deployments	List[DeploymentInfo]	List of deployments to check	required
start_date	datetime	Start date for data availability check	required
end_date	datetime	End date for data availability check	required
check_archive	bool	If True, check for archive files, otherwise check data products	False

Returns:

Type	Description
List[DeploymentInfo]	List of deployments with data availability marked

collect_hydrophone_inventory(*, include_inactive=True)

Collect hydrophone deployment inventory with current and history views.

Parameters:

Name	Type	Description	Default
include_inactive	bool	If True, include inactive devices in the per‑device summaries when building the inventory.	True

Returns:

Type	Description
Dict[str, Any]	Dict with current and history lists of records.

find_best_deployments_for_date_range(start_date, end_date, timezone_str='UTC', min_coverage_days=1)

Find the best deployments that cover a specific date range.

Parameters:

Name	Type	Description	Default
start_date	Union[str, datetime]	Desired start date	required
end_date	Union[str, datetime]	Desired end date	required
timezone_str	str	Timezone for date interpretation	'UTC'
min_coverage_days	int	Minimum days of coverage required	1

Returns:

Type	Description
List[DeploymentInfo]	List of best deployments sorted by coverage quality

find_deployments_by_time_range(start_date, end_date, timezone_str='UTC')

Find deployments that overlap with a specific time range.

Parameters:

Name	Type	Description	Default
start_date	Union[str, datetime]	Start date (string or datetime)	required
end_date	Union[str, datetime]	End date (string or datetime)	required
timezone_str	str	Timezone for date interpretation	'UTC'

Returns:

Type	Description
List[DeploymentInfo]	List of deployments that overlap with the time range

get_all_hydrophone_deployments()

Get all hydrophone deployments from ONC.

Returns:

Type	Description
List[DeploymentInfo]	List of DeploymentInfo objects for all deployments, including
List[DeploymentInfo]	location metadata (name/code, lat/lon, depth) and deployment dates.

get_deployment_date_ranges(device_codes=None)

Get deployment date ranges for specific device codes or all hydrophones.

Parameters:

Name	Type	Description	Default
device_codes	Optional[List[str]]	Optional list of device codes to check. If None, checks all.	None

Returns:

Type	Description
Dict[str, List[Tuple[datetime, Optional[datetime]]]]	Dict mapping device codes to lists of (start_date, end_date) tuples.

get_device_availability(device_code, *, start_date=None, end_date=None, timezone_str='UTC', bin_size='day', max_days_per_request=60, progress=None, quiet=True, max_workers=4, request_delay_seconds=0.0)

Build deployment-aware availability bins for a specific device.

Parameters:

Name	Type	Description	Default
device_code	str	ONC device code to evaluate.	required
start_date	Optional[Union[str, datetime]]	Optional start date for availability window.	None
end_date	Optional[Union[str, datetime]]	Optional end date for availability window.	None
timezone_str	str	Timezone for binning and display.	'UTC'
bin_size	str	"day" or "hour" binning for availability.	'day'
max_days_per_request	int	Chunk size for archive queries.	60

Returns:

Type	Description
Dict[str, Any]	Dict with device metadata, deployments, bins, and deployment_summary.
Dict[str, Any]	Bin records include: start, end, coverage (0-1), status, deployment_index.
Dict[str, Any]	Bins align to day/hour boundaries in the requested timezone.

plot_device_availability(device_code, *, start_date=None, end_date=None, timezone_str='UTC', bin_size='day', max_days_per_request=60, style='timeline', **plot_kwargs)

Plot availability for a device using timeline or calendar styles.

Parameters:

Name	Type	Description	Default
device_code	str	ONC device code to evaluate.	required
start_date	Optional[Union[str, datetime]]	Optional start date for availability window.	None
end_date	Optional[Union[str, datetime]]	Optional end date for availability window.	None
timezone_str	str	Timezone for binning and display.	'UTC'
bin_size	str	"day" or "hour" binning for availability.	'day'
max_days_per_request	int	Chunk size for archive queries.	60
style	str	"timeline" or "calendar" (calendar requires bin_size='day').	'timeline'
plot_kwargs	Any	Passed to plotting helper.	{}

Returns:

Type	Description
	Matplotlib (fig, ax) tuple.

print_deployment_summary(deployments, show_data_availability=True)

Print a formatted summary of deployments.

Parameters:

Name	Type	Description	Default
deployments	List[DeploymentInfo]	List of deployments to summarize	required
show_data_availability	bool	Whether to show data availability status	True

render_hydrophone_inventory_table(inventory, *, view='current', max_rows=50)

Render the inventory into a table (DataFrame if pandas is available).

Parameters:

Name	Type	Description	Default
inventory	Dict[str, Any]	Output of collect_hydrophone_inventory.	required
view	str	current or history.	'current'
max_rows	Optional[int]	Maximum number of rows to display (None = no limit).	50

Returns:

Type	Description
	A pandas DataFrame if pandas is installed, otherwise a Markdown string.

show_device_deployments(*, device_codes=None, device_ids=None, max_rows=50, inventory=None)

Show deployment history for specific device codes or device IDs.

Parameters:

Name	Type	Description	Default
device_codes	Optional[List[str]]	List of ONC device codes to filter by.	None
device_ids	Optional[List[Union[str, int]]]	List of numeric device IDs to filter by.	None
max_rows	Optional[int]	Maximum number of rows to display (None = no limit).	50
inventory	Optional[Dict[str, Any]]	Optional inventory output to reuse (avoids re-fetch).	None

Returns:

Type	Description
	The rendered table (DataFrame or Markdown string).

show_hydrophone_inventory_table(inventory, *, view='current', max_rows=50)

Display the inventory table in notebooks or print a Markdown fallback.

Parameters:

Name	Type	Description	Default
inventory	Dict[str, Any]	Output of collect_hydrophone_inventory.	required
view	str	current or history.	'current'
max_rows	Optional[int]	Maximum number of rows to display (None = no limit).	50

Returns:

Type	Description
	The rendered table (DataFrame or Markdown string).