troi

The shared core of the Borevitz Lab software ecosystem — one Troi (Time and Region Of Interest), one Config, used by every lab package.

from datetime import date
from troi import Troi

troi = Troi(
    bbox=[148.36265, -33.52606, 148.38265, -33.50606],  # [W, S, E, N]
    start=date(2024, 1, 1),
    end=date(2024, 12, 31),
    stub='my_farm',
)

Every downstream package takes a Troi and answers it — same identity, same caches, same reproducibility guarantees everywhere.

Troi — the identity layer

A frozen, hashable request: this region, this date range. Two queries with the same inputs are the same troi — they share every cached artefact on disk.

q.bbox_hash    # region identity  (bbox snapped to ~100 m, then SHA-256)
q.time_hash    # date-range identity
q.out_dir      # final outputs for this stub
q.tmp_dir      # scratch space for this stub

Storage layout is not Troi's concern — packages derive their own cache locations (usually from the hashes) in their own Paths class.

Three ways to build one:

Troi(bbox=[w, s, e, n], start=..., end=..., stub='site_a')

Troi.from_lat_lon(lat=-34.38, lon=148.48, buffer_km=2.0,
                   start=..., end=..., stub='site_b')

Troi.build_from_paddocks(paddocks_filepath='paddocks.gpkg',   # .gpkg / .shp / .geojson
                          start=..., end=..., stub='site_c')

Every constructed troi is recorded in a file-locked registry ({out_dir}/queries.json). Re-running an identical troi is a no-op; reusing a stub for different inputs raises ValueError — stubs uniquely name a troi, forever.

Config — the environment layer

Where data lives and which credentials to use. Loaded once, from the first source found:

Or bypass files entirely:

from troi import Config

cfg = Config(out_dir='/data/outputs', tmp_dir='/data/tmp')
q = Troi(..., config=cfg)

Design rules

The conventions every lab package follows:

• No inheritance. One generic Troi; packages compose with it (functions and small classes taking a Troi/Config), never subclass it.
• Config vs Paths. User-settable inputs live on Config; locations derived from a Troi or Config live on a per-package Paths class.
• Layered APIs. Data-layer functions are troi-agnostic (bbox, start, end); thin *_troi adapters connect them to the reproducibility layer.

📚 Reference documentation: docs/ — the Troi class, Config resolution, the registry, and the ecosystem conventions.

Install

Just this package

pip install pytroi           # from PyPI (distribution name pytroi, import troi)
# or straight from GitHub:
pip install git+https://github.com/thestochasticman/troi.git

(For the whole pipeline, install paddocktimeseries — its pip install . pulls troi and the five data stores from GitHub.)

From source

git clone https://github.com/thestochasticman/troi.git
cd troi
pip install -e .

Optional extra for Troi.build_from_paddocks:

pip install -e '.[paddocks]'   # adds geopandas

Test

python -m troi.troi     # True
python -m troi.config   # prints the resolved config

License

MIT · Borevitz Lab, Australian National University