.. raw:: html
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:
.. list-table::
:header-rows: 1
:widths: 18 82
* - 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
- Interactive widgets: spatial selector, IGSN viewer, sample image viewer
- Two runtimes: :class:`~terndata.ecoplots.ecoplots.EcoPlots` (sync) and
:class:`~terndata.ecoplots.ecoplots.AsyncEcoPlots` (async)
- Save and reload your filter selection via ``.ecoproj`` project files
Installation
============
.. code-block:: bash
pip install terndata.ecoplots
Supported Python: 3.10+
Quick start
===========
**Observations**
.. code-block:: python
from terndata.ecoplots import EcoPlots
ec = EcoPlots() # mode="observations" by default
ec.select(dataset="TERN Surveillance")
gdf = ec.get_data()
**Samples**
.. code-block:: python
from terndata.ecoplots import EcoPlots
ec = EcoPlots(mode="samples")
ec.select(material_sample_type="Plant Voucher Specimen", has_images=True)
df = ec.get_data(dformat="pd")
Supported Python: 3.10+
Quick start
===========
**Observations**
.. code-block:: python
from terndata.ecoplots import EcoPlots
ec = EcoPlots() # mode="observations" by default
ec.select(dataset="TERN Surveillance")
gdf = ec.get_data()
**Samples**
.. code-block:: python
from terndata.ecoplots import EcoPlots
ec = EcoPlots(mode="samples")
ec.select(material_sample_type="Plant Voucher Specimen", has_images=True)
df = ec.get_data(dformat="pd")
Next steps
==========
- :doc:`Observations Workflow ` — all methods available in observations mode
- :doc:`Samples Workflow ` — all methods available in samples mode
- :doc:`Workflow reference ` — end-to-end user guide for sync and async workflows
- :doc:`Package overview ` — constructor parameters, client comparison
- :doc:`EcoPlots Client ` — full API reference
- :doc:`Async EcoPlots client `
- `Observations Demo Notebook `_
- `Samples Demo Notebook `_
.. toctree::
:hidden:
:maxdepth: 2
api
.. toctree::
:hidden:
:maxdepth: 1
workflows
api/ecoplots_observations
api/ecoplots_samples
internals
changelog
EcoPlots Python Library
