terndata.ecoplots 1.1.2.dev11__tar.gz → 1.1.2.dev13__tar.gz

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: terndata.ecoplots
-Version: 1.1.2.dev11
+Version: 1.1.2.dev13
 Summary: Python client for discovering, filtering, and retrieving TERN EcoPlots observation and sample data
 Author-email: Avinash Chandra <avinash.chandra@uq.edu.au>
 Maintainer-email: "TERN Data Services and Analytics (TDSA)" <esupport@tern.org.au>

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/docs/changelog.rst

@@ -3,6 +3,14 @@ Change Log
 
 Changes over time for the EcoPlots Python library.
 
+v1.1.2 (2026-09-17)
+-------------------
+
+- Updated the spatial selector to use the key-free Esri World Shaded Relief basemap, removing the Carto watermark while retaining a subdued map style.
+- Fixed Parquet output for columns containing mixed numeric values and ``"N/A"`` placeholders by converting those placeholders to null values during Parquet serialization.
+- Fixed region type resolution for IBRA7 bioregions and subregions, including space-, hyphen-, and underscore-separated names and the legacy ``bioregions`` and ``subregions`` aliases.
+- Added a dedicated examples README with summaries and direct links to the Python notebooks and R examples.
+
 v1.1.1 (2026-06-26)
 -------------------
 

terndata_ecoplots-1.1.2.dev13/examples/R examples/ReadMe.md

@@ -0,0 +1,119 @@
+# 🌿 Accessing `terndata.ecoplots` in R with `reticulate`
+
+Seamlessly access, query, and download TERN ecosystem data directly within your R workflow.
+
+------------------------------------------------------------------------
+
+## ✨ Overview
+
+The Python integration provided by the `reticulate` package enables R users to access the full functionality of `terndata.ecoplots`.
+
+Using `reticulate`, you can:
+
+- 🔍 Search and filter TERN datasets
+- 🌏 Select regions and sampling criteria
+- ⬇️ Download data directly into R
+
+For more information on `reticulate`, see the official documentation:
+
+🔗 <https://rstudio.github.io/reticulate/>
+
+------------------------------------------------------------------------
+
+## 🚀 Example
+
+The example below downloads all **Plant Tissue Sample** records from the **TERN Ecosystem Surveillance** dataset for the **Northern Territory**.
+
+### Step 1 — Load required packages
+
+``` r
+library(reticulate)
+
+py_require("terndata.ecoplots")
+```
+
+### Step 2 — Query and download data using `terndata.ecoplots`
+
+``` r
+py_run_string("
+
+# Load package
+from terndata.ecoplots import EcoPlots
+
+# Create EcoPlots object
+ec = EcoPlots(mode='samples')
+
+# Select dataset and filters
+ec.select(
+    dataset='TERN Ecosystem Surveillance',
+    region_type='States and Territories',
+    region='Northern Territory',
+    material_sample_type='Plant Tissue Sample'
+)
+
+# Download data as pandas DataFrame
+nt_sample_data_py = ec.get_data(dformat='pandas')
+
+# Convert all columns to object type
+nt_sample_data_py = nt_sample_data_py.astype(object)
+
+")
+```
+
+### Step 3 — Import data into the R environment
+
+``` r
+nt_sample_data <- py$nt_sample_data_py
+```
+
+------------------------------------------------------------------------
+
+## ⚠️ Important Notes
+
+### 🐍 Running Python from R
+
+The example above executes Python code using:
+
+``` r
+reticulate::py_run_string()
+```
+
+For interactive exploration, you can launch a Python REPL directly from RStudio:
+
+``` r
+reticulate::repl_python()
+```
+
+This allows you to interact with `terndata.ecoplots` as if you were working in a native Python environment.
+
+#### 🔍 Previewing data
+
+RStudio does not fully render the dataframe preview generated by the `preview()` method.
+
+Instead, inspect available columns using:
+
+``` python
+ec.preview().columns
+```
+
+This allows dataset exploration before downloading data.
+
+------------------------------------------------------------------------
+
+### 📝 Missing Values (NA Handling)
+
+When pandas DataFrames are transferred from Python to R, missing values are not always translated automatically.
+
+As a result, missing values may appear as the literal string:
+
+``` r
+"N/A"
+```
+
+rather than R's native:
+
+``` r
+NA
+```
+
+If your dataset contains missing values, convert these strings to proper R `NA` values before analysis.

terndata_ecoplots-1.1.2.dev11/examples/terndata.ecoplots_QueenslandSoilColour.R → terndata_ecoplots-1.1.2.dev13/examples/R examples/terndata.ecoplots_QueenslandSoilColour.R

@@ -1,3 +1,11 @@
+####################################################################################################
+##
+## Example: Accessing terndata.ecoplots from within R using reticulate
+##   - Select and download soil colour from the QBEIS dataset 
+##   - Plot site coordinates and soil colours
+##
+####################################################################################################
+
 ## load libraries
 
     ## to run python from within R studio

terndata_ecoplots-1.1.2.dev11/examples/terndata.ecoplots_TrendsInSpeciesCover.R → terndata_ecoplots-1.1.2.dev13/examples/R examples/terndata.ecoplots_TrendsInSpeciesCover.R

@@ -1,3 +1,12 @@
+####################################################################################################
+##
+## Example: Accessing terndata.ecoplots from within R using reticulate
+##   - Select and download information for site "SAARIV0005" 
+##   - Visualize changes in species cover between first and second visit
+##
+####################################################################################################
+
+
 ## load libraries
 
     ## to run python from within R studio

terndata_ecoplots-1.1.2.dev13/examples/README.md

@@ -0,0 +1,31 @@
+# EcoPlots examples
+
+This directory contains practical Python and R examples for discovering, filtering,
+retrieving, and visualising TERN EcoPlots data.
+
+## Python examples
+
+- [Observations demo](demo.ipynb) — covers discovery, filters, summaries, previews,
+  data retrieval, GeoJSON output, and spatial selection.
+- [Samples demo](demo_samples.ipynb) — covers sample discovery and filtering, IGSN
+  identifiers, soil and species analysis, image viewing, and spatial selection.
+
+The Python examples are Jupyter notebooks. Install the GUI extra to use their
+interactive widgets:
+
+```bash
+pip install "terndata.ecoplots[gui]"
+```
+
+## R examples
+
+The R examples use
+[`reticulate`](https://rstudio.github.io/reticulate/) to call the EcoPlots Python
+package from R:
+
+- [R setup and usage guide](<R examples/ReadMe.md>)
+- [Queensland soil colour](<R examples/terndata.ecoplots_QueenslandSoilColour.R>) —
+  downloads QBEIS soil-colour observations and plots their site locations and colours.
+- [Trends in species cover](<R examples/terndata.ecoplots_TrendsInSpeciesCover.R>) —
+  retrieves observations for a site and visualises changes in species cover between
+  visits.

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata/ecoplots/_gui/spatial_selector.py

@@ -120,7 +120,7 @@ def spatial_selector(
     # Map
     m = Map(center=center, zoom=zoom, scroll_wheel_zoom=True, attribution_control=False)
     m.layout = Layout(width="100%", height="500px")
-    m.add_layer(basemap_to_tiles(basemaps.CartoDB.Positron))
+    m.add_layer(basemap_to_tiles(basemaps.Esri.WorldGrayCanvas))
     m.fit_bounds(_AU_BOUNDS)
     m.max_bounds = _AU_BOUNDS
 

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata/ecoplots/_nlp_utils.py

@@ -13,13 +13,16 @@ from ._config import MATERIAL_SAMPLE_TYPE_MAP
 ALL_FACETS = ["region_type", "region", "dataset", "feature_type", "observed_property"]
 
 REGION_TYPES_MAP = {
-    "subregions": "https://linked.data.gov.au/dataset/ibra7/subregions",
-    "bioregions": "https://linked.data.gov.au/dataset/ibra7",
+    "ibra7-subregions": "https://linked.data.gov.au/dataset/ibra7/subregions",
+    "ibra7-bioregions": "https://linked.data.gov.au/dataset/ibra7",
     "nrm-regions": "https://linked.data.gov.au/dataset/ausnrm2023",
     "states-and-territories": "https://linked.data.gov.au/dataset/asgsed3/STE",
     "local-government-areas": "https://linked.data.gov.au/dataset/asgsed3/LGA2023",
     "wwf-ecoregions": "https://linked.data.gov.au/dataset/wwf2011",
     "terrestrial-capad-regions": "https://linked.data.gov.au/dataset/auscapad2022",
+    "indigenous-areas": "https://linked.data.gov.au/dataset/asgsed3/IARE",
+    "indigenous-locations": "https://linked.data.gov.au/dataset/asgsed3/ILOC",
+    "indigenous-regions": "https://linked.data.gov.au/dataset/asgsed3/IREG",
 }
 
 REGION_TYPES = list(REGION_TYPES_MAP.keys())
@@ -127,10 +130,15 @@ def resolve_region_type(
 
     # --- Case 2: Input is label (not URL) ---
     # Normalize user input
-    user_input = re.sub(
-        r"\bibra7[-_ ]*", "", user_input, flags=re.IGNORECASE
-    )  # Remove 'ibra7' prefix if present
-    cleaned_input = user_input.strip().replace(" ", "-").lower()
+    cleaned_input = re.sub(r"[-_\s]+", "-", user_input.strip()).lower()
+    cleaned_input = {
+        "bioregions": "ibra7-bioregions",
+        "subregions": "ibra7-subregions",
+    }.get(cleaned_input, cleaned_input)
+
+    if cleaned_input in allowed_region_types:
+        return cleaned_input
+
     if cleaned_input.startswith("l"):
         threshold = 20
     result = process.extractOne(cleaned_input, allowed_region_types, scorer=fuzz.QRatio)  # type: ignore

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata/ecoplots/ecoplots.py

@@ -64,9 +64,14 @@ _FILE_FORMAT_SUFFIXES = {
 
 def _dataframe_to_parquet_bytes(df: pd.DataFrame) -> bytes:
     """Serialise a dataframe to parquet bytes."""
+    parquet_df = df.copy()
+    for column in parquet_df.select_dtypes(include=["object", "string"]).columns:
+        values = parquet_df[column].astype(object)
+        parquet_df[column] = values.mask(values.eq("N/A"), None)
+
     buffer = io.BytesIO()
     try:
-        df.to_parquet(buffer, index=False)
+        parquet_df.to_parquet(buffer, index=False)
     except (ImportError, ValueError) as exc:
         raise EcoPlotsError(
             "Parquet output requires pyarrow. Reinstall or upgrade with: "

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata/ecoplots/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.2.dev11'
-__version_tuple__ = version_tuple = (1, 1, 2, 'dev11')
+__version__ = version = '1.1.2.dev13'
+__version_tuple__ = version_tuple = (1, 1, 2, 'dev13')
 
 __commit_id__ = commit_id = None

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata.ecoplots.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: terndata.ecoplots
-Version: 1.1.2.dev11
+Version: 1.1.2.dev13
 Summary: Python client for discovering, filtering, and retrieving TERN EcoPlots observation and sample data
 Author-email: Avinash Chandra <avinash.chandra@uq.edu.au>
 Maintainer-email: "TERN Data Services and Analytics (TDSA)" <esupport@tern.org.au>

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/src/terndata.ecoplots.egg-info/SOURCES.txt

@@ -46,10 +46,12 @@ docs/api_internal/ecoplots._flatten_response.rst
 docs/api_internal/ecoplots._gui.rst
 docs/api_internal/ecoplots.rst
 docs/api_internal/modules.rst
+examples/README.md
 examples/demo.ipynb
 examples/demo_samples.ipynb
-examples/terndata.ecoplots_QueenslandSoilColour.R
-examples/terndata.ecoplots_TrendsInSpeciesCover.R
+examples/R examples/ReadMe.md
+examples/R examples/terndata.ecoplots_QueenslandSoilColour.R
+examples/R examples/terndata.ecoplots_TrendsInSpeciesCover.R
 src/terndata.ecoplots.egg-info/PKG-INFO
 src/terndata.ecoplots.egg-info/SOURCES.txt
 src/terndata.ecoplots.egg-info/dependency_links.txt

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/tests/test_data_retrieval.py

@@ -107,9 +107,11 @@ def test_get_data_rejects_invalid_format():
 
 def test_get_data_returns_parquet_bytes(monkeypatch):
     ec = MockEcoPlots(query_filters={"site_id": ["site-uri"]})
+    captured = {}
 
     def fake_to_parquet(self, path, index=False):
         assert index is False
+        captured["dataframe"] = self.copy()
         path.write(b"PARQUET")
 
     monkeypatch.setattr(pd.DataFrame, "to_parquet", fake_to_parquet)
@@ -117,6 +119,8 @@ def test_get_data_returns_parquet_bytes(monkeypatch):
     payload = ec.get_data(dformat="parquet")
 
     assert payload == b"PARQUET"
+    assert captured["dataframe"].loc[0, "b"] is None
+    assert captured["dataframe"].loc[1, "a"] is None
 
 
 def test_export_data_writes_nested_csv(tmp_path):

{terndata_ecoplots-1.1.2.dev11 → terndata_ecoplots-1.1.2.dev13}/tests/test_utils.py

@@ -2,6 +2,7 @@ import pandas as pd
 import pytest
 
 from terndata.ecoplots import EcoPlotsError
+from terndata.ecoplots._nlp_utils import resolve_region_type
 from terndata.ecoplots._utils import (
     _align_and_concat,
     _ensure_ecoproj_path,
@@ -11,6 +12,32 @@ from terndata.ecoplots._utils import (
 )
 
 
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "IBRA7 Bioregions",
+        "IBRA7-Bioregions",
+        "ibra7_bioregions",
+        "bioregions",
+    ],
+)
+def test_resolve_region_type_accepts_ibra7_bioregion_aliases(raw):
+    assert resolve_region_type(raw) == "ibra7-bioregions"
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "IBRA7 Subregions",
+        "IBRA7-Subregions",
+        "ibra7_subregions",
+        "subregions",
+    ],
+)
+def test_resolve_region_type_accepts_ibra7_subregion_aliases(raw):
+    assert resolve_region_type(raw) == "ibra7-subregions"
+
+
 @pytest.mark.parametrize(
     ("raw", "expected"),
     [