Package: feo-client
Future Energy Outlook Python ClientDocumentation:https://docs.feo.transitionzero.orgAPI Reference:https://api.feo.transitionzero.org/latest/docsFuture Energy Outlook:https://feo.transitionzero.orgTheFuture Energy Outlook(FEO) is TransitionZero's open-access energy transition research platform.
This Python Client gives programmatic access to all the functionality of the FEO 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.InstallationThe latest release of the FEO Python Client can be installed viapip.pip install feo-clientThe 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/feo-client.git@mainAuthenticationTo access resources via the Python Client you must have a (free) FEO account. An account can be createdhere.To log in for programmatic access, use the feo command-line tool:feo auth loginYou'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-feo/token.json.The feo login can also be called directly (for example via a Jupyter notebook):from feo.client.auth import login
login()QuickstartThe FEO client provides object-level interfaces to the main FEO building blocks. Users may also use the underlying API wrapper.Accessing node-level dataIn the FEO platform, all data is indexed to aNode. Nodes are used to represent useful physical and administrative boundaries - ranging from individual physical assets through to entire countries and continents. This flexibility allows FEO users to access data at all levels of aggregation via the FEO 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 theNodeclient.from feo.client import NodeTheNode.searchmethod can be used to search for Nodes.Node.search("Bali")Each search result is an instance of theNodeobject.IDN = Node.search("indonesia")[0]
IDNNodes have anidwhich is unique. Nodes can have many names (oraliases), one of which is attached to the node as a primary English name.IDN.id, IDN.name_primary_enAccessing asset-level dataIn the FEO platform,Assetsare 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 feo.client import AssetLike 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_enAccessing historical dataAccessing systems models and reportsSystem Models are representations of energy and material flows, usually optimised by economic logic like least-costs-minimisation.System models in FEO are composed of three objects - Models, Scenarios, and Runs.Modelsdescribe the geographic, temporal, and sectoral scope of the systems model.Scenariosare narrative counter-factuals of the future, which may be accompanied by numeric projectionsRunsare solutions to parameterised systems models, used to explore uncertaintyModels, Scenarios, and Runs can be imported from the client:from feo.client import Model, Scenario, RunTheModelclient can be used to search and retrieve model objects.Model.search(model_slug='feo-global-indonesia')Models can also be retrieved directly by ididn_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 scenariosrun = idn_model.scenarios[0].runsDocumentationThe full documentation for FEO can be found here:https://docs.feo.transitionzero.orgContributingSee theContributing Guideand ourCode of Conduct.LicenseApache license 2.0