sustax-client 0.4.0

Python client and CSV parser for the Sustax User API (SUA)

sustax-client

PyPI package: sustax-client · PyPI

A small Python package for the Sustax User API and for parsing the Sustax global climate models by means of CSV files exported by Sustax (see https://sustax.earth). This repository is prepared in a standard src/ layout so it can be:

• developed locally with pip install -e .
• installed from PyPI
• built as a source distribution and wheel

What is included

• SustaxClient for authentication, catalog lookup, pricing, purchases, downloads, status polling, coordinates, and balance checks
• load_sustax_file() to load Sustax CSV files into pandas DataFrames or nested numpy-friendly dictionaries
• parser, parsing, and reranking helpers for Sustax CSV outputs
• Python examples for catalog inspection, coordinate downloads, and postal-code downloads
• unit tests plus marked live API and purchase workflow tests

Repository layout

sustax-client/
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── MANIFEST.in
├── README.md
├── pytest.ini
├── pyproject.toml
├── src/
│   └── sustax_client/
│       ├── __init__.py
│       ├── client.py
│       ├── parser.R
│       ├── parser.py
│       ├── parsing.py
│       └── reranking.py
├── tests/
│   ├── test_reranking.py
│   ├── test_sustax_downloaded_csv_values.py
│   └── test_sustax_workflow.py
└── examples/
    ├── _helpers.py
    ├── download_coords.py
    ├── download_zip_code.py
    └── inspect_catalog.py

Installation

Local development

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]

From PyPI

Install the official package from sustax-client · PyPI:

pip install sustax-client

Quick start

1. Authenticate and inspect the catalog

from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    catalog = client.get_variables_id()
    print(catalog)

2. Preview pricing for a point request

from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    quote = client.view_price_request(
        lat=41.3874,
        lon=2.1686,
        year_from=2020,
        year_to=2030,
        sustax_code_ids=[12345],
    )
    print(quote)

3. Buy, download, and unzip a request

This example purchases data and may spend Sustax coins.

from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    request_info = client.buy_data(
        lat=41.3874,
        lon=2.1686,
        year_from=2020,
        year_to=2030,
        sustax_code_ids=[12345],
        acceptance_sustax_disclaimer=True,
    )
    zip_path = client.download_file(request_info["url"], dest_dir="downloads")
    extracted = client.unzip_download(dest_dir="downloads/unzipped")
    print(zip_path)
    print(extracted)

4. Load a Sustax CSV with pandas

from sustax_client import load_sustax_file

climate_df, metrics_df, metadata = load_sustax_file(
    "downloads/unzipped/example.csv",
    return_pandas_df=True,
    return_metadata=True,
)

print(climate_df.head())
print(metrics_df.head())
print(metadata)

Supported request modes

The packaged client supports the three location modes described in the Sustax documentation:

• point coordinates: lat, lon
• ROI / bounding box: lat=[north, south], lon=[west, east]
• postal code lookup: postal_code, country

CSV parser behavior

load_sustax_file() assumes the exported file is a Sustax CSV with three main blocks:

• metadata
• accuracy metrics
• climate payload time series

By default it returns two pandas DataFrames:

• climate payload indexed by time
• metrics indexed by scenario

Set return_pandas_df=False if you prefer nested dictionaries and a numpy datetime array.

Bivariate alignment structure

sustax-client also includes Python helpers for restructuring future Sustax scenario data using a historical bivariate rank relationship.

This is useful when two climate variables have a known historical dependency structure, for example:

• temperature and relative humidity
• temperature and precipitation

The workflow uses the historical reference column, usually ERA5, to learn how a target variable ranks relative to a driver variable. It then reorders the future target scenario values so that their rank relationship with the future driver follows the historical driver-target rank structure.

In practical terms:

historical driver variable + historical target variable
        ↓
learn historical bivariate rank relationship
        ↓
future driver variable + future target variable
        ↓
reorder future target values within time/season groups
        ↓
future target keeps its original distribution but follows the historical rank structure

The method is non-parametric. It does not fit a linear regression model and does not change the set of future target values. Instead, it reassigns the order of the future target values.

Development

Run tests:

pytest

Build distributions locally:

python -m build

License

MIT