TUTORIAL Prerequisites 0: set a workspace for pyaesa

[ ]:

from pyaesa import set_workspace
The first step for using pyaesa is to create a workspace, in which several projects can then be developped.
The workspace is the root directory in which prerequisites will be developped (downloads and processing) as a necessary basis for projects.
This first tutorial shows how to set a workspace.

Create a workspace with set_workspace(...)

Description

What the function does

set_workspace(...) creates or reuses the package workspace and imports the packaged prerequisite files that the rest of the workflow expects. It defines paths for outputs.

What it writes and what later functions reuse

It writes the project tree and packaged prerequisites under data_raw/. Every later public function assumes the repository exists first.

Imported prerequisites:

  • AESA workflow methodological PDFs in data_raw/methodological_notes/;

  • MRIO aggregation guide README_aggregation.txt, agg_reg_template.csv, agg_sec_template.csv, and packaged agg_reg_eu27.csv, agg_reg_world.csv, and OECD agg_reg_fr.csv examples under data_raw/mrio/<source>/aggregation/;

  • EXIOBASE LCIA characterization matrices with README_add_custom_lcia_characterization_matrices.txt, name_lcia_template.csv, and name_lcia_planetary_boundary_template.csv under data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/;

  • carbon consumption based accounts coefficients of variation CSVs for LCIA uncertainty under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/, including README_agg_reg_and_group_indices_lcia_covs.txt, reg_cbca_covs_agg_eu27.csv, reg_cbca_covs_agg_world.csv, reg_cbca_covs.csv, and sec_cbca_covs.csv;

  • static carrying capacity defaults and custom method inputs under data_raw/carrying_capacities/, including README_add_custom_carrying_capacities.txt, name_lcia_cc_steady_state_template.csv, and name_lcia_cc_steady_state_planetary_boundary_template.csv;

The repository methodological notes folder also contains methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf, methodological_notes/methodological_note__acc_uncertainty_sources.pdf, and methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

Public argument checklist

The table lists all arguments; the same definitions are available in the function docstring.

Green items = default if omitted.

Do not write green items when the default is intended.

set_workspace(…) arguments

Argument

Description

top_path

Parent directory where the repository root pyaesa/ is created or reused. Accepts a string path or pathlib.Path.

refresh

If True, overwrite the packaged prerequisite files copied by set_workspace(…) under the resolved workspace data_raw tree and rewrite the setup summary log. The scope is limited to package shipped prerequisite files such as default carrying capacities, methodological notes, aggregation templates, matching tables, LCIA templates, README_aggregation.txt, README_add_custom_lcia_characterization_matrices.txt, README_add_custom_lcia_responsibility_periods.txt, README_agg_reg_and_group_indices_lcia_covs.txt, and README_add_custom_carrying_capacities.txt. Raw downloads, processed outputs, and project outputs are not refreshed. Defaults to False.

Running set_workspace(...)

[ ]:

# Windows example; update this path before running.
set_workspace(r"C:\Users\username\Documents\aesa_workspace")

# macOS example; update this path before running.
# set_workspace("/Users/username/Documents/aesa_workspace")

Every tutorial notebook repeats set_workspace(...), as all function calls always assume it has already run in the current Python session.

What to do next

Continue with tutorials/core_prerequisites/1_download_data.ipynb to download necessary raw data for the proper use of pyaesa.