tz-client 0.0.5

A Python Client for programmatic interactions with the platform by TransitionZero

TransitionZero Python Client

Documentation: https://docs.feo.transitionzero.org

API Reference: https://api.feo.transitionzero.org/latest/docs

Model Builder: https://feo.transitionzero.org

---

TransitionZero is building an open-access energy transition research platform. This Python Client gives programmatic access to all the functionality of the TransitionZero platform:

• Open Data: Asset-level and historical data free to access, forever.
• No-barriers Systems Modelling: Begin asking your energy transition research questions with a simple UI or a few lines of code.
• Transparent Data Provenance: Trace all data back to its origin.
• Reproduceable: Built with open-source systems modelling frameworks, with transparent or user-defined assumptions.
• Social and Shareable: Share systems models reports publicly and star your favourites.
• Analysis-Ready Outputs: Download analysis-ready spreadsheets.
• Flagship Analysis: Access premier research outputs prepared by TransitionZero researchers.

---

Installation

The latest release of the TZ Python Client can be installed via pip.

pip install tz-client

The client can also be installed from this repo, for any features not yet available via the Python Package Index:

pip install git+https://github.com/transition-zero/tz-client.git@main

Authentication

To access resources via the Python Client you must have a (free) account. An account can be created here.

To log in for programmatic access, use the tz command-line tool:

tz auth login

You'll be invited to login via a browser, verify a device code and then will be redirected to your terminal. An access token will be stored in your machine's home directory at .tz/token.json.

The tz login can also be called directly (for example via a Jupyter notebook):

from tz.client.auth import login
login()

Quickstart

The TZ client provides object-level interfaces to the main TZ building blocks. Users may also use the underlying API wrapper.

Accessing node-level data

In the TZ platform, all data is indexed to a Node. Nodes are used to represent useful physical and administrative boundaries - ranging from individual physical assets through to entire countries and continents. This flexibility allows TZ users to access data at all levels of aggregation via the TZ platform .

In the physics of systems modelling, Nodes are discrete units around which the continuity of energy and materials is constrained. In other words, at every node in a systems model, the input plus supply to the node must equal the output plus demand. To begin, import the Node client.

from tz.client import Node

The Node.search method can be used to search for Nodes.

Node.search("Bali")

Each search result is an instance of the Node object.

IDN = Node.search("indonesia")[0]
IDN

Nodes have an id which is unique. Nodes can have many names (or aliases), one of which is attached to the node as a primary English name.

IDN.id, IDN.name_primary_en

Accessing asset-level data

In the TZ platform, Assets are a subset of Nodes. Assets are Nodes which correspond to physical plant and equipment like power stations and steelworks.

To begin, import the Asset client.

from tz.client import Asset

Like nodes, assets can be searched for:

search_results = Asset.search("Banten Suralaya power", sector="power")
for asset in search_results:
    print(asset.id, asset.name_primary_en)

... or directly instantiated:

asset = Asset.from_id("PWRCOAIDNA0U0")
asset.id, asset.name_primary_en

Accessing historical data

Accessing systems models and reports

System Models are representations of energy and material flows, usually optimised by economic logic like least-costs-minimisation.

System models in the TransitionZero platform are composed of three objects - Models, Scenarios, and Runs.

• Models describe the geographic, temporal, and sectoral scope of the systems model.
• Scenarios are narrative counter-factuals of the future, which may be accompanied by numeric projections
• Runs are solutions to parameterised systems models, used to explore uncertainty

Models, Scenarios, and Runs can be imported from the client:

from tz.client import Model, Scenario, Run

The Model client can be used to search and retrieve model objects.

Model.search(model_slug='feo-global-indonesia')

Models can also be retrieved directly by id

idn_model = Model.from_id('feo-global-indonesia')

Scenarios associated can also be retrieved from the model object.

idn_model.scenarios

... as can the runs associated with scenarios

run = idn_model.scenarios[0].runs

Documentation

The full documentation for the TZ platform can be found here: https://docs.feo.transitionzero.org

Contributing

See the Contributing Guide and our Code of Conduct.

License

Apache license 2.0