EcoPlots Python Library

Discover, filter, preview, and retrieve ecological observations and physical samples from the TERN EcoPlots Portal.

Observations Workflow Samples Workflow API Overview

GitHub GitHub PyPI PyPI EcoPlots EcoPlots EcoPlots Portal

Documentation version: 1.1.1

About EcoPlots

TERN EcoPlots is a platform designed for searching, discovering, and accessing ecological observations—both from systematic site-based surveys and opportunistic surveys—as well as specimen samples collected during field surveys from various data sources. With TERN EcoPlots, users can search for observation data and specimen samples from systematic surveys across Australia. The platform allows users to integrate data from multiple sources and access it as a comprehensive, ready-to-use data package. Additionally, users can search for specimen samples and request access to these samples for further research.

TERN EcoPlots is developed based on a semantic data integration approach. Datasets are generally received from custodians in various forms, including PostgreSQL databases and CSV file formats. In the data ingestion process, each source dataset is mapped to a TERN Plot ontology including the identification and mapping of domain feature types, parameters, and categorical values to controlled vocabularies, as well as the performance of data validation routines and the resolution of taxonomic names. All data are organised in Resource Description Framework (RDF) and stored in a triple store.

See also: EcoPlots Portal.

EcoPlots Python library

The terndata.ecoplots Python library provides a lightweight, Pythonic client for the EcoPlots REST API. It supports two operational modes:

Mode

What you can access

observations

Ecological observation data — site visits, feature types, measured properties — returned as pandas/geopandas tables.

samples

Physical specimens (soil, plant tissue, plant voucher) with IGSN identifiers, sample images, and associated metadata.

Key capabilities:

  • Human-friendly, validated filters with fuzzy name resolution

  • Preview results page-by-page before committing to a full download

  • Standard install includes observations and samples workflows, Parquet output, site/site-visit attribute data, and the synchronous EcoPlots client

  • Optional async runtime: AsyncEcoPlots with async get_data() and get_data_stream()

  • Optional GUI widgets: spatial selector, IGSN viewer, sample image viewer

  • Save and reload your filter selection via .ecoproj project files

Installation

pip install terndata.ecoplots

The standard install includes the synchronous client, both data modes, discovery and filtering, data retrieval, site/site-visit attribute data retrieval, and Parquet output.

Optional modules:

pip install "terndata.ecoplots[async]"  # AsyncEcoPlots + streaming transport
pip install "terndata.ecoplots[gui]"    # notebook widgets

Supported Python: 3.10+

Quick start

Observations

from terndata.ecoplots import EcoPlots

ec = EcoPlots()                          # observations mode by default
ec.select(dataset="TERN Surveillance")
gdf = ec.get_data()                      # GeoDataFrame
parquet_bytes = ec.get_data(dformat="pq")
site_attrs = ec.get_site_attributes_data()

Samples

from terndata.ecoplots import EcoPlots

ec = EcoPlots("samples")
ec.select(material_sample_type="Plant Voucher Specimen", has_image=True)
df = ec.get_data(dformat="pd")
sites = ec.get_sites(include_region=True)

Async streaming

from terndata.ecoplots import AsyncEcoPlots

ec = AsyncEcoPlots()
ec.select(site_id="TCFTNS0002")

async for chunk in ec.get_data_stream(dformat="gpd"):
    ...

Install with pip install "terndata.ecoplots[async]" before using async transport methods.

Next steps