EcoPlots Observations Workflow¶

The EcoPlots client in observations mode (the default) lets you discover and retrieve ecological observation data across Australia — including site visits, feature types, and measured properties — all returned as tidy DataFrames ready for analysis.

from terndata.ecoplots import EcoPlots

ec = EcoPlots()                          # mode="observations" by default
ec.select(dataset="TERN Surveillance")   # add one or more filters
ec.preview()                             # quick look before full download
df = ec.get_data()                       # retrieve as GeoDataFrame

Note

All methods on this page are available on both EcoPlots (synchronous) and AsyncEcoPlots (asynchronous). For AsyncEcoPlots, use df = await ec.get_data() in the final step.

Note

A runnable walkthrough of all observations-mode features is available in the Observations Demo Notebook.

Creating the Client¶

from terndata.ecoplots import EcoPlots

# No arguments needed — all filters start empty
ec = EcoPlots()

# Or pre-load a saved project
ec = EcoPlots.load("my_project.ecoproj")

Selectables & Discoverable Facets¶

Filters passed to select() are called facets. The table below lists every facet available in observations mode, what it represents, and the discovery method you can call to see valid values for it.

Facet	Type	Description	Discover with
`dataset`	str / list	Dataset(s) to include in the query.	`get_datasources()`
`site_id`	str / list	One or more site identifiers.	`get_sites()`
`site_visit_id`	str / list	Specific site-visit identifiers.	`get_site_visit_attributes()`
`region_type`	str	Category of geographic region (e.g. `"bioregions"`, `"states"`). Must be provided before or alongside `region`.	`get_region_types()`
`region`	str / list	Region name(s) within the chosen `region_type`.	`get_regions()`
`feature_type`	str / list	Ecological feature type (e.g. plant individual, soil layer).	`get_feature_types()`
`observed_property`	str / list	Measured or observed property (e.g. basal area, soil pH).	`get_observed_properties()`
`spatial`	WKT / GeoJSON	Spatial bounding geometry to restrict results geographically. Set interactively via `select_spatial()`, or pass a WKT string or GeoJSON geometry `dict` directly.	`select_spatial()` (widget)
`project`	str / list	Project label associated with the observations.	—

Discovery Methods¶

Use these methods to explore what data is available before downloading. They all return pandas.DataFrame and respect your current filters, so you can narrow results step by step.

Datasets¶

EcoPlots.get_datasources()[source]

Get the data sources available for applied filters.

Returns:: A DataFrame containing the data sources.
Return type:: DataFrame

EcoPlots.get_datasources_attributes()[source]

Get the attributes of data sources from the applied filters.

Returns:: A DataFrame containing the attributes of the data sources.
Return type:: DataFrame

Example

ec.get_datasources()

Sites¶

EcoPlots.get_sites()[source]

Get the sites from the applied filters.

Returns:: A DataFrame containing the sites.
Return type:: DataFrame

EcoPlots.get_sites_attributes()[source]

Get the attributes of sites from the applied filters.

Returns:: A DataFrame containing the attributes of the sites.
Return type:: DataFrame

EcoPlots.get_site_visit_attributes()[source]

Get the attributes of site visits from the applied filters.

Returns:: A DataFrame containing the attributes of the site visits.
Return type:: DataFrame

Example

ec.get_sites()

Regions¶

EcoPlots.get_region_types()[source]

Get the available region types from the applied filters.

Returns:: A DataFrame containing the region types.
Return type:: DataFrame

EcoPlots.get_regions(region_type)[source]

Get the available regions for a specific region type from the applied filters.

Parameters:: region_type (str) – The region type to retrieve regions for.
Returns:: A DataFrame containing the regions for the specified region type.
Return type:: DataFrame

Example

# Step 1: see what region types are available
ec.get_region_types()

# Step 2: list regions within a type
ec.get_regions("bioregions")

Feature Types & Observed Properties¶

EcoPlots.get_feature_types()[source]

Get the feature types from the applied filters.

Returns:: A DataFrame containing the feature types.
Return type:: DataFrame

EcoPlots.get_observed_properties()[source]

Get the observed properties from the applied filters.

Returns:: A DataFrame containing the observed properties.
Return type:: DataFrame

EcoPlots.get_observation_attributes()[source]

Get the attributes of observations from the applied filters. Available only in “observations” mode.

Returns:: A DataFrame containing the attributes of the observations.
Raises:: EcoPlotsError – If called in a mode other than “observations”.
Return type:: DataFrame

Example

ec.get_feature_types()
ec.get_observed_properties()

Filter Methods¶

Once you know what data exists, use these methods to narrow your selection. All filter methods return self so they can be chained.

EcoPlots.select(filters=None, **kwargs)

Add/merge filters and validate them.

Accepts either a dict or keyword arguments.

Parameters:

filters (dict | None) – Mapping like {"site_id": [...], "dataset": [...]}.
**kwargs –
Alternative way to pass filters, e.g. site_id="ABC". Special keyword filters (handled separately from facet resolution):
- spatial: WKT string or GeoJSON geometry dict to spatially restrict results to a custom region.
- has_image (bool, samples mode only): Limit to samples that have attached images.
- soil_subsite_id (int or list[int], samples mode only): Restrict to specific soil sub-site identifiers.
- soil_depth_range ([min, max] or {"min": x, "max": y}, samples mode only): Filter samples by soil depth in metres.
- date_from (str): Earliest date (inclusive) in any recognisable format — "DD/MM/YYYY", "21 May 2020", "21st May 2020", "YYYY-MM-DD" etc. Normalised to "YYYY-MM-DD" internally. Day-first is assumed for all-numeric inputs (MM-DD-YYYY is never accepted).
- date_to (str): Latest date (inclusive), same format rules as date_from.
self (SelfType)

Raises:

EcoPlotsError – Unknown filter keys.
EcoPlotsError – region provided without current or new region_type.

Returns:

self for chaining.

Return type:

SelfType

EcoPlots.remove(filters=None, **kwargs)

Remove whole facets or specific values (same ergonomics as select).

Accepts either a dict or keyword arguments. For each facet:

value is None → remove the entire facet
value is a string → remove that single value
value is a list/tuple → remove those values

Parameters:

filters (dict | None) – Mapping like {"site_id": ["TCFTNS0002"], "dataset": None}.
**kwargs – Alternative way to pass removals, e.g. site_id="TCFTNS0002".
self (SelfType)

Raises:

EcoPlotsError – Unknown filter keys (not in QUERY_FACETS).
EcoPlotsError – If dataset is targeted while in samples mode (the TERN Ecosystem Surveillance dataset is protected).
KeyError – Facet not present in current filters.
EcoPlotsError – Specific values requested but not found for that facet.

Returns:

self (chainable)

Return type:

SelfType

EcoPlots.clear()

Clear all filters from the instance.

The method mutates the instance and returns it to allow fluent/chained calls.

Returns:: self (chainable)
Parameters:: self (SelfType)
Return type:: SelfType

Notes

In samples mode the TERN Ecosystem Surveillance dataset filter is preserved; only user-added filters are cleared.

EcoPlots.get_filter(facet=None)

Return the current filter values for a specific facet or all applied filters.

Parameters:: facet (str | None) – The facet to retrieve the filter for. Defaults to All.
Raises:: EcoPlotsError – If an invalid facet name is provided.
Returns:: A list of values for the specified facet, or None if the facet is not currently applied. If facet is None, returns a dict mapping each applied facet to its list of values.
Return type:: list | dict | None

EcoPlots.get_api_query_filters(facet=None)

Return the current query filters for ecoplots API for a specified facet or all facet.

Parameters:: facet (str | None) – The facet to retrieve the query filters for. Defaults to None.
Raises:: EcoPlotsError – If an invalid facet name is provided.
Returns:: A list of resolved API values for the specified facet, or None if the facet is not currently applied. If facet is None, returns a dict of all resolved query filters.
Return type:: list | dict | None

Example

# Add filters
ec.select(
    dataset="TERN Surveillance",
    site_id="TCFTNS0002",
)

# Inspect applied filters
ec.get_filter()              # all filters as a dict
ec.get_filter("site_id")     # single facet as a list

# Remove a specific value
ec.remove(site_id="TCFTNS0002")

# Reset everything
ec.clear()

Spatial Filter Widget¶

Draw a polygon or rectangle directly on a map to spatially restrict your query.

EcoPlots.select_spatial(**kwargs)[source]

Open the spatial selection widget.

A minimal map based spatial selector, similar to spatial selection tool in EcoPlots Portal.

Parameters:: **kwargs – Additional keyword arguments to pass to the widget.
Returns:: ipywidgets.VBox – The widget. Use it in a notebook cell to display.

Example

# Opens the interactive map widget in a notebook cell
ec.select_spatial()

Spatial selector widget showing a drawn polygon over Australia — The spatial selector widget. Draw a rectangle or polygon, then click **Confirm Selection** to apply the spatial filter.¶

Data Preview & Retrieval¶

EcoPlots.summary(dformat=None)[source]

Summarize the EcoPlots data.

Parameters:: dformat (str | None) – The desired format for the summary. If "json", returns the raw summary dict from the API. Defaults to None, which returns a pandas.DataFrame.
Returns:: When dformat is "json", returns the raw summary dict from the API. Otherwise, returns a pandas.DataFrame with columns metric and count summarising the current selection (e.g. total observations, unique sites, datasets).
Return type:: DataFrame | str

EcoPlots.preview(dformat=None)[source]

Fetch a small preview of EcoPlots data. # noqa: DAR401, D415

Mirrors get_data() but limits results to 10 records for a quick look.

In observations mode, fetches CSV from up to 2 feature types (5 rows each). In samples mode, calls the samples endpoint and returns the first 10 rows; "geojson"/"json" formats are not supported in this mode.

Parameters:

dformat (str | None) – Output format. - "geojson" or "json": returns a GeoJSON dict (observations only). - "pandas" (or "pd"): returns a pandas.DataFrame. - "geopandas" (or "gpd") (default): returns a GeoDataFrame.

Returns:

Preview data in the requested format.

Raises:

EcoPlotsError – If an invalid dformat is provided.
RuntimeError – If no feature types found (observations mode).

Return type:

geopandas.GeoDataFrame | dict | str

EcoPlots.get_data(allow_full_download=False, dformat='gpd')[source]

Retrieve EcoPlots data based on the current filters.

Parameters:

allow_full_download (bool | None) – If True, allows downloading the full dataset without filters. Defaults to False.
dformat (str | None) –
Output format. - “geojson” or “json”: returns a pretty-printed GeoJSON string. - “pandas” (or ‘pd’): returns a pandas DataFrame. - “geopandas” (or ‘gpd’) (default): returns a GeoDataFrame.

In “samples” mode, only “pandas”/”pd” and “geopandas”/”gpd” are supported (no “geojson”/”json”).

In “samples” mode, exactly one material_sample_type must be selected at a time.

Raises:

RuntimeError – If no filters are set and allow_full_download is False.
EcoPlotsError – If an invalid dformat is provided.

Returns:

Data in the requested format.

Return type:

geopandas.GeoDataFrame

Typical workflow

# 1. Check how many records match your filters
ec.summary()

# 2. Preview the first 10 rows before committing to a full download
ec.preview().head()

# 3. Download the full dataset as a GeoDataFrame
gdf = ec.get_data()

# 4. Or as a plain pandas DataFrame
df = ec.get_data(dformat="pd")

Project Save / Load¶

Serialise your current filter selection to a .ecoproj file so you can reproduce or share the exact query later.

EcoPlots.save(path=None)

Save project state to a single .ecoproj file (atomic, checksummed).

Writes the current filters and query_filters into a compact binary file with a small header and a JSON (orjson) payload. The filename resolution is:

If path is None: save as ./ecoplots_<UTCSTAMP>.ecoproj.
If path has no .ecoproj suffix and no parent directory: save as
./<name>.ecoproj in the current working directory.
If path ends with .ecoproj: save exactly to that location.

Parameters:: path (str | Path | None) – Optional target path or bare name. If omitted, a timestamped filename is created in the current working directory.
Returns:: Absolute path to the saved .ecoproj file.
Raises:: Exception – Any unexpected error during the write; temporary files are cleaned up best-effort before re-raising.
Return type:: str

classmethod EcoPlots.load(path)

Load a .ecoproj file, validate integrity, and return a new instance.

Parameters:

path (str | Path) – Path to a .ecoproj file previously created by save().

Returns:

A new instance of the calling class with filters and query_filters restored from the file.

Raises:

FileNotFoundError – If the file does not exist.
EcoPlotsError – If the file does not have a .ecoproj suffix, the magic header or version is invalid, the file is truncated, or the checksum does not match the payload.

Return type:

SelfType

Example

# Save current filters to a timestamped file
path = ec.save()

# Or save to a specific name
path = ec.save("my_survey.ecoproj")

# Reload later
ec2 = EcoPlots.load(path)
ec2.get_filter()   # filters are fully restored