bioamla.catalogs¶

bioamla.catalogs ¶

Catalog integrations for bioacoustic data sources.

This package provides access to external bioacoustic databases and services, each exposed as a submodule of plain functions that return data and raise exceptions on failure:

:mod:bioamla.catalogs.inat — iNaturalist citizen-science observations with audio
:mod:bioamla.catalogs.xeno_canto — Xeno-canto bird sound archive
:mod:bioamla.catalogs.macaulay — Cornell's Macaulay Library multimedia archive
:mod:bioamla.catalogs.ebird — eBird observation data and taxonomy
:mod:bioamla.catalogs.species — taxonomic name lookup / conversion
:mod:bioamla.catalogs.huggingface — HuggingFace Hub model & dataset publishing

All failures raise a :class:~bioamla.exceptions.CatalogError (or its subclass :class:~bioamla.exceptions.SpeciesError); bad arguments / missing API keys raise :class:~bioamla.exceptions.InvalidInputError.

Example

from bioamla.catalogs import species species.scientific_to_common("Turdus migratorius") 'American Robin'

CachedRepo `dataclass` ¶

Bases: ToDictMixin

A repo present in the local HuggingFace cache.

EBirdChecklist `dataclass` ¶

Bases: ToDictMixin

Information about an eBird checklist.

EBirdHotspot `dataclass` ¶

Bases: ToDictMixin

Information about an eBird hotspot.

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> EBirdHotspot

Create from eBird API response.

EBirdObservation `dataclass` ¶

Bases: ToDictMixin

Information about an eBird observation.

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> EBirdObservation

Create from eBird API response.

INaturalistDownloadResult `dataclass` ¶

Bases: ToDictMixin

Result of an iNaturalist download operation.

INaturalistSearchResult `dataclass` ¶

Bases: ToDictMixin

Result of an iNaturalist search.

MacaulayDownloadResult `dataclass` ¶

Bases: ToDictMixin

Result of a Macaulay Library download operation.

MacaulaySearchResult `dataclass` ¶

Bases: ToDictMixin

Result of a Macaulay Library search.

MLRecording `dataclass` ¶

Bases: ToDictMixin

Information about a Macaulay Library recording.

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> MLRecording

Create a recording from Macaulay Library API response data.

get_download_url ¶

get_download_url() -> str

Get the download URL for this recording.

NearbyResult `dataclass` ¶

Bases: ToDictMixin

Result of nearby observations query.

ObservationInfo `dataclass` ¶

Bases: ToDictMixin

Information about a single observation.

ProjectStats `dataclass` ¶

Bases: ToDictMixin

Statistics for an iNaturalist project.

PullResult `dataclass` ¶

Bases: ToDictMixin

Result of pulling a HuggingFace dataset into the local bioamla layout.

PurgeResult `dataclass` ¶

Bases: ToDictMixin

Outcome of purging cached HuggingFace repos.

PushResult `dataclass` ¶

Bases: ToDictMixin

Result of a HuggingFace Hub push operation.

RegionResult `dataclass` ¶

Bases: ToDictMixin

Result of regional observations query.

SearchMatch `dataclass` ¶

Bases: ToDictMixin

A species search match result with similarity score.

SpeciesInfo `dataclass` ¶

Bases: ToDictMixin

Information about a species (taxonomy record).

from_ebird_response `classmethod` ¶

from_ebird_response(data: dict[str, Any]) -> SpeciesInfo

Create SpeciesInfo from eBird taxonomy API response data.

from_inat_response `classmethod` ¶

from_inat_response(data: dict[str, Any]) -> SpeciesInfo

Create SpeciesInfo from iNaturalist taxa API response data.

TaxonInfo `dataclass` ¶

Bases: ToDictMixin

Information about a taxon.

ValidationResult `dataclass` ¶

Bases: ToDictMixin

Result of species validation at a location.

XCRecording `dataclass` ¶

Bases: ToDictMixin

Information about a Xeno-canto recording.

from_api_response `classmethod` ¶

from_api_response(data: dict[str, Any]) -> XCRecording

Create a recording from Xeno-canto API response data.

XenoCantoDownloadResult `dataclass` ¶

Bases: ToDictMixin

Result of a Xeno-canto download operation.

XenoCantoSearchResult `dataclass` ¶

Bases: ToDictMixin

Result of a Xeno-canto search.

EBirdService ¶

Client for eBird observation data and taxonomy.

Parameters:

Name	Type	Description	Default
`api_key`	`str \| None`	eBird API key. If omitted, the `EBIRD_API_KEY` environment variable is used. Missing keys raise :class:`InvalidInputError` on first request.	`None`

Example

service = EBirdService(api_key="your_key") result = service.get_recent_observations("US-CA") print(result.total_count)

get_recent_observations ¶

get_recent_observations(
    region_code: str,
    back: int = 14,
    max_results: int = 100,
    species_code: str | None = None,
) -> RegionResult

Get recent observations for a region.

Parameters:

Name	Type	Description	Default
`region_code`	`str`	eBird region code (e.g., "US-CA", "US-CA-037").	required
`back`	`int`	Days back to look (max 30).	`14`
`max_results`	`int`	Maximum observations to return.	`100`
`species_code`	`str \| None`	Optional species code to filter by.	`None`

Raises:

Type	Description
`CatalogError`	on API failure.

get_nearby ¶

get_nearby(
    lat: float,
    lng: float,
    distance_km: float = 25,
    days: int = 14,
    limit: int = 100,
) -> NearbyResult

Get recent eBird observations near a location.

Parameters:

Name	Type	Description	Default
`lat`	`float`	Latitude.	required
`lng`	`float`	Longitude.	required
`distance_km`	`float`	Search radius in km (max 50).	`25`
`days`	`int`	Days back to search (max 30).	`14`
`limit`	`int`	Maximum results.	`100`

Raises:

Type	Description
`CatalogError`	on API failure.

validate_species ¶

validate_species(
    species_code: str,
    lat: float,
    lng: float,
    distance_km: float = 50,
) -> ValidationResult

Validate whether a species is expected at a location.

Checks if the species has been recently observed near the given coordinates, which helps validate detection results.

Raises:

Type	Description
`CatalogError`	on API failure.

get_species_list ¶

get_species_list(region_code: str) -> list[str]

Get list of species codes observed in a region.

Raises:

Type	Description
`CatalogError`	on API failure.

get_taxonomy ¶

get_taxonomy(
    species_codes: list[str] | None = None,
    category: str = "species",
) -> list[dict[str, Any]]

Get eBird taxonomy data.

Parameters:

Name	Type	Description	Default
`species_codes`	`list[str] \| None`	Optional list of species codes to filter.	`None`
`category`	`str`	Taxonomic category filter.	`'species'`

Raises:

Type	Description
`CatalogError`	on API failure.

get_hotspots ¶

get_hotspots(
    region_code: str, back: int = 14
) -> list[EBirdHotspot]

Get eBird hotspots in a region.

Parameters:

Name	Type	Description	Default
`region_code`	`str`	eBird region code.	required
`back`	`int`	Only include hotspots with observations in last N days.	`14`

Raises:

Type	Description
`CatalogError`	on API failure.

get_checklist ¶

get_checklist(submission_id: str) -> EBirdChecklist

Get details of a specific checklist.

Raises:

Type	Description
`CatalogError`	on API failure.

CatalogError ¶

Bases: BioamlaError

External catalog / API failure (xeno-canto, iNaturalist, eBird, Macaulay, HF).

DependencyError ¶

Bases: BioamlaError

A required dependency is unavailable at runtime.

All Python dependencies ship in the base install, so this is reserved for genuine environment problems (e.g. a missing system library or a broken install).

InvalidInputError ¶

Bases: BioamlaError

Caller passed bad, contradictory, or out-of-range arguments.

SpeciesError ¶

Bases: CatalogError

Species lookup, name-conversion, or taxonomy-export failure.

match_detections_to_ebird ¶

match_detections_to_ebird(
    detections: list[dict[str, Any]],
    service: EBirdService,
    latitude: float,
    longitude: float,
    species_mapping: dict[str, str] | None = None,
) -> list[dict[str, Any]]

Match detection labels to eBird taxonomy and validate against nearby observations.

Parameters:

Name	Type	Description	Default
`detections`	`list[dict[str, Any]]`	List of detections with a `label` field.	required
`service`	`EBirdService`	An :class:`EBirdService` instance with a valid API key.	required
`latitude`	`float`	Location latitude.	required
`longitude`	`float`	Location longitude.	required
`species_mapping`	`dict[str, str] \| None`	Optional mapping from detection labels to eBird species codes.	`None`

Returns:

Type	Description
`list[dict[str, Any]]`	Detections with eBird validation fields added.

Raises:

Type	Description
`CatalogError`	if the nearby-observations query fails.

bioamla.catalogs¶