Metadata-Version: 2.4
Name: terndata.ecoplots
Version: 0.0.7b0
Summary: TERN ecoplots data access library
Author-email: Avinash Chandra <avinash.chandra@uq.edu.au>
Maintainer-email: "TERN Data Services and Analytics (TDSA)" <esupport@tern.org.au>
License-Expression: Apache-2.0
Project-URL: Home, https://github.com/ternaustralia/terndata.ecoplots
Project-URL: Documentation, https://terndata-ecoplots.readthedocs.io
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: typing-extensions
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: geopandas
Requires-Dist: requests
Requires-Dist: aiohttp<4.0.0,>=3.11.12
Requires-Dist: python-dateutil
Requires-Dist: pytz
Requires-Dist: rapidfuzz<4.0.0,>=3.13.0
Requires-Dist: orjson<4.0.0,>=3.10.15
Requires-Dist: diskcache<6.0.0,>=5.6.3
Requires-Dist: ijson<4.0.0,>=3.4.0
Requires-Dist: defusedxml<1.0.0,>=0.7.1
Requires-Dist: shapely<3.0.0,>=2.0.0
Requires-Dist: ipyleaflet<1.0.0,>=0.20.0
Requires-Dist: ipywidgets<9.0.0,>=8.1.7
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)"  srcset="docs/_static/img/ecoplots-logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/_static/img/ecoplots-logo-light.svg">
    <img src="docs/_static/img/ecoplots-logo-light.svg" height="70" alt="EcoPlots logo">
  </picture>
</p>

<h1 align="center"><span style="color:#F5A26C">EcoPlots</span> Python Library</h1>

<p align="center">
  <a href="https://pypi.org/project/terndata.ecoplots/"><img src="https://img.shields.io/pypi/v/terndata.ecoplots.svg?logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://pypi.org/project/terndata.ecoplots/"><img src="https://img.shields.io/pypi/pyversions/terndata.ecoplots.svg?logo=python&logoColor=white" alt="Python versions"></a>
  <a href="https://terndata-ecoplots.readthedocs.io/en/latest/"><img src="https://img.shields.io/readthedocs/terndata-ecoplots.svg?logo=readthedocs" alt="Docs"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/ternaustralia/terndata.ecoplots.svg" alt="License"></a>
  <a href="https://github.com/ternaustralia/terndata.ecoplots"><img src="https://img.shields.io/badge/GitHub-Repo-181717?logo=github&logoColor=white" alt="GitHub"></a>
  <a href="https://ecoplots.tern.org.au"><img src="https://img.shields.io/badge/EcoPlots-Portal-6EB3A6?labelColor=043E4F" alt="EcoPlots Portal"></a>
</p>

---

High-level Python clients for discovering, filtering, previewing, and retrieving
ecological field data from the **[TERN EcoPlots Portal](https://ecoplots.tern.org.au)**.
Supports two operational modes — **observations** and **samples** — and returns
tidy structures ready for analysis (`geojson`, `pandas.DataFrame`, `geopandas.GeoDataFrame`).

---

## Features

- 🔬 **Two modes**: observations (ecological plots) and samples (physical specimens)
- 🔎 Validated, human-friendly filters with fuzzy name resolution
- ⚡ Preview result pages before committing to full downloads
- 🗺️ Interactive spatial selection widget (draw a polygon on a map)
- 🧭 Two clients: synchronous `EcoPlots` and asynchronous `AsyncEcoPlots`
- 💾 Save / load projects via `.ecoproj` files for reproducible workflows

**Documentation:** https://terndata-ecoplots.readthedocs.io

---

## Installation

    pip install terndata.ecoplots

Supported Python: 3.10+

---

## Modes

### Observations (default)

Retrieve ecological observation data — site visits, feature types, and measured
properties — across Australia's TERN monitoring network.

```python
from terndata.ecoplots import EcoPlots

ec = EcoPlots()                           # mode="observations" by default
ec.select(dataset="TERN Surveillance",
          site_id="TCFTNS0002")
ec.preview()                              # quick look (first page)
gdf = ec.get_data()                       # full pull as GeoDataFrame
```

### Samples

Retrieve physical specimens — soil pit samples, plant voucher specimens, plant
tissue samples, and more — with access to IGSN identifiers and sample images.

```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")
```

> **Note:** In samples mode the *TERN Ecosystem Surveillance* dataset is applied
> automatically and cannot be removed.

---

## Interactive Widgets

Both modes provide notebook widgets for interactive data exploration:

| Widget | Mode | Method |
|---|---|---|
| Spatial selector | Both | `ec.select_spatial()` |
| IGSN viewer | Samples | `ec.view_sample_igsn()` |
| Sample image viewer | Samples | `ec.view_sample_images()` |

---

## Async client

```python
from terndata.ecoplots import AsyncEcoPlots

ec = AsyncEcoPlots()
ec.select(site_id="TCFTNS0002")
gdf = await ec.get_data()        # non-blocking fetch
```

---

## Demo Notebooks

| Mode | Notebook |
|---|---|
| Observations | [examples/demo.ipynb](examples/demo.ipynb) |
| Samples | [examples/demo_samples.ipynb](examples/demo_samples.ipynb) |

---

## Links

- 📚 Docs: https://terndata-ecoplots.readthedocs.io/en/latest/
- 🧭 EcoPlots Portal: https://ecoplots.tern.org.au
- 🧑‍💻 Source: https://github.com/ternaustralia/terndata.ecoplots
- 📦 PyPI: https://pypi.org/project/terndata.ecoplots/

---

## Contributing

Issues and pull requests are welcome — please open an issue to discuss substantial changes.

Build docs locally:

    pip install -r docs/requirements.txt
    make -C docs html

Run tests:

    make test

Build wheels locally:

    make build

---

## Support

For questions or issues, email **esupport@tern.org.au**.

---

## Citation

Terrestrial Ecosystem Research Network (2026). *terndata.ecoplots: A Python package for accessing TERN EcoPlots data*. https://pypi.org/project/terndata.ecoplots/

---

## License

Licensed under the terms in [LICENSE](LICENSE).  
Copyright © 2026 **TDSA (TERN Data Services and Analytics)**.  
Author: Avinash Chandra.
