TI-Forest-Sector-Modelling · tomkeH · Sep 16, 2025 · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## [v1.1.1] - 2025-09-16
+
+### Added
+
+- Automated FAO data download from FAOSTAT and FRA API
+- CLI as standalone and add-on module for TiMBA
+
 ## [v1.1.0] - 2025-09-03
 
 ### Added

diff --git a/CITATION.cff b/CITATION.cff
@@ -19,14 +19,17 @@ abstract: |-
   The Carbon Module (C-Module) tracks global carbon stocks and stock changes across pools in the forestry sector, based on
   either forest sector projections or historical forest sector statistics. In its current version, the module quantifies
   carbon stocks and stock changes in forest biomass (above- and below-ground), harvested wood products (HWP), forest soils,
-  dead wood, and litter for 180 countries. The Carbon Module was developed as an add-on to the Timber markets Model for policy-Based
+  dead wood, and litter for 180 countries. The C-Module enables users to interactively explore simulated data through its dashboard.
+  The Carbon Module was developed as an add-on to the Timber markets Model for policy-Based
   Analysis (TiMBA).
 keywords:
-  - research
+  - forestry
+  - climate change
   - carbon accounting
-  - Forest sector model
-  - Forest sector
-  - wood markets
+  - land use change
+  - climate change mitigation
+  - wood products
+  - forest sector modelling
 license: AGPL-3.0-or-later
-version: 1.1.0
+version: 1.1.1
 date-released: '03.09.2025'
diff --git a/COPYRIGHT b/COPYRIGHT
@@ -1,4 +1,4 @@
-Copyright ©, 2025, Thuenen Institute, TI-FSM, Tomke Honkomp, tomke.honkomp@thuenen.de
+Copyright ©, 2025, Thuenen Institute, Tomke Honkomp, tomke.honkomp@thuenen.de
 
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Affero General Public License as

diff --git a/README.md b/README.md
@@ -11,6 +11,8 @@
 
 - [Cite the C-Module](#cite-the-c-module)
 - [Install the C-Module](#install-the-c-module)
+  - [Installation via PyPI](#installation-via-pypi)
+  - [Installation via GitHub](#installation-via-github)
   - [Double check installation](#doublecheck-installation)
   - [Test suite and coverage](#test-suite-and-coverage-report)
 - [Use the C-Module](#use-the-c-module)
@@ -48,7 +50,7 @@ or as a standalone module (see [Use the C-Module](#use-the-c-module)).
 We are happy that you use the C-Module for your research. When publishing your work in articles, working paper, presentations
 or elsewhere, please cite the module as: 
 
-[Honkomp (2025) C-Module v1](CITATION.cff)
+[Honkomp (2025) C-Module v1.1.1](CITATION.cff)
 
 ## Install the C-Module
 
@@ -61,6 +63,14 @@ The following steps apply if the C-Module is used as a standalone module.
 Before proceeding, please ensure that Python is installed on your system. It can be downloaded and installed 
 from [Python.org](https://www.python.org/downloads/release/python-389/).
 
+The C-Module can be installed in two ways via PyPI or GitHub.
+
+### Installation via PyPI
+To install the newest version of the C-Module via PyPI, use following command in your terminal or PowerShell:
+   >pip install Carbon-Module
+   >
+
+### Installation via GitHub
 1. Clone the repository   
 Begin by cloning the repository to your local machine using the following command: 
     >git clone https://github.com/TI-Forest-Sector-Modelling/C-Module
@@ -163,8 +173,12 @@ mention is user input data that need to be imported from a selected folder. You
       |--additional_information_carbon.pkl
       |--additional_information_carbon.xlsx
     `-- historical_data
-      |-- 20250703_faostat_data.csv
-      |-- 20250703_fra_data.csv 
+      |-- Forestry_E_All_Data_NOFLAG.csv
+      |-- Forestry_E_All_Data_NOFLAG.pkl
+      |-- Forestry_E_All_Data_NOFLAG_processed.pkl
+      |-- FRA_Years_All_Data.csv
+      |-- FRA_Years_All_Data.pkl
+      |-- FRA_Years_All_Data_processed.pkl
     `-- projection_data
       |--default_Sc_forest.csv
       |--default_Sc_results.csv
@@ -176,15 +190,18 @@ automatically. If the C-Module is run as an add-on to TiMBA, the application ret
 while running.
 
 Following data from external sources ([FAOSTAT](https://www.fao.org/faostat/en/#data/FO) and [FRA](https://fra-data.fao.org/assessments/fra/2020)) are used:
-- The input data `20250703_faostat_data.csv` is a renamed copy of the file `Forestry_E_All_Data_NOFLAG.csv` provided by the [FAOSTAT bulk data
-download](https://bulks-faostat.fao.org/production/Forestry_E_All_Data.zip).
-- The input data `20250703_fra_data.csv` is a renamed copy of the file `FRA_Years_YYYY_MM_DD.csv` provided by the [FRA bulk data
-download](https://fra-data.fao.org/api/file/bulk-download?assessmentName=fra&cycleName=2020&countryIso=WO).
-
-The original FAOSTAT and FRA files are manually saved as CSV UTF-8 files. The most recent copy of the FAOSTAT and FRA datasets
-was downloaded on 2025-07-03 and contains data up to 2023 for FAOSTAT and up to 2020 for FRA. For production and trade, the module
-includes data from 1961 onwards. For forest area and stock, data are available from 1990 onwards. FAOSTAT and FRA data will be
-updated regularly; however, users of the C-Module should verify whether more recent FAOSTAT or FRA data are available before use.
+- The input data `Forestry_E_All_Data_NOFLAG.csv` is retrieved from the [FAOSTAT bulk data
+download](https://bulks-faostat.fao.org/production/Forestry_E_All_Data.zip). This data is serialized (`Forestry_E_All_Data_NOFLAG.pkl`)
+and processed (`Forestry_E_All_Data_NOFLAG_processed.pkl`).
+- The input data `FRA_Years_All_Data.csv` is retrieved from the [FRA bulk data
+download](https://fra-data.fao.org/api/file/bulk-download?assessmentName=fra&cycleName=2020&countryIso=WO). This data is serialized (`FRA_Years_All_Data.pkl`)
+and processed (`FRA_Years_All_Data_processed.pkl`).
+
+The update of the FAOSTAT and FRA files can be controlled using the parameter `fao_data_update = True` under `default_parameters.py`. Otherwise, the
+FAOSTAT and FRA data is automatically updated every 2 months. The data is downloaded when running the C-Module
+the first time. A stable internet connection is needed to execute the data update. Current copy contains data up to 2023 for FAOSTAT and up to 2020 for FRA. For production and trade, the module
+includes data from 1961 onwards. For forest area and stock, data are available from 1990 onwards. Users of the C-Module should
+verify whether more recent FAOSTAT or FRA data are available before use.
 
 The package will generate a results directory called `output` which is located inside the data folder. The final directory after one run will look something like this:
 ```bash
@@ -213,6 +230,7 @@ Basic module settings include:
 |            Setting            |                                                           Description                                                            |                                                                                                Options                                                                                                |  Default setting  |
 |:-----------------------------:|:--------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------------:|
 |      `add_on_activated`       |                                  Flag to activate if the C-Module is used as an add-on to TiMBA                                  |                                                                                                 Bool                                                                                                  |       True        |
+|           `sc_num`            |           Number of scenarios processed by the C-Module. If None, all scenarios in the scenario folder are processed.            |                                                                                              None or int                                                                                              |       None        |
 |         `start_year`          |        Year from which calculations of the C-Module are started. The value should be aligned with the provided input data        |                                                                                                  int                                                                                                  |       2020        |
 |          `end_year`           |       Year until which calculations of the C-Module are running. The value should be aligned with the provided input data        |                                                                                                  int                                                                                                  |       2050        |
 |         `read_in_pkl`         |                                  Flag to control which input files are used for projection data                                  |                                                                                                 Bool                                                                                                  |       True        |
@@ -226,7 +244,7 @@ Basic module settings include:
 |     `hist_hwp_start_year`     |                           Setting to control the year from which the historical HWP pool is calculated                           | "default": uses a uniform default reference year for all countries and products<br/> or<br/> "country-specific": uses country-specific reference year based on the data availability for each country |     "default"     |
 | `hist_hwp_start_year_default` | Setting to control the reference year for the historical HWP pool. <br/>Used in combination with `hist_hwp_start_year`="default" |                                                                                                  int                                                                                                  | 2020 (start year) |
 |    `show_carbon_dashboard`    |                        Setting to control if the dashboard for explorative result exploration is launched                        |                                                                                                 Bool                                                                                                  |       True        |
-
+|       `fao_data_update`       |                                Setting to control if FAO data (FRA and FAOSTAT) is updated or not                                |                                                                                                 Bool                                                                                                  |       False       |
 
 If the C-Module is used as an add-on to TiMBA, the start and end year parameters are automatically adjusted to match TiMBA's start and end years.
 The C-Module is delivered with a set of default settings, which were tested and validated. The default settings can be changed when executing the

diff --git a/c_module/cli/cli.py b/c_module/cli/cli.py
@@ -8,6 +8,9 @@
 @click.option('-ADD_ON', '--add_on_activated', "add_on_activated",
               default=user_input[ParamNames.add_on_activated.value], show_default=True, required=True, type=bool,
               help="Flag to use the carbon module as a standalone module or as a TiMBA add-on.")
+@click.option('-SC', '--sc_num', "sc_num",
+              default=user_input[ParamNames.sc_num.value], show_default=True, required=True, type=int,
+              help="Flag to control the number of processed scenarios.")
 @click.option('-SY', '--start_year', 'start_year', default=user_input[ParamNames.start_year.value],
               show_default=True, required=True, type=int,
               help="Start year of carbon calculations.")
@@ -38,11 +41,12 @@
 @click.option('-SD', '--show_carbon_dashboard', 'show_carbon_dashboard',
               default=user_input[ParamNames.show_carbon_dashboard.value], show_default=True, required=False, type=bool,
               help="Flag to launch carbon dashboard.")
-def cli(add_on_activated, start_year, end_year, calc_c_forest_agb, calc_c_forest_bgb, calc_c_forest_soil,
+def cli(add_on_activated, sc_num, start_year, end_year, calc_c_forest_agb, calc_c_forest_bgb, calc_c_forest_soil,
         calc_c_forest_dwl, calc_c_hwp, c_hwp_accounting_approach, read_in_pkl, show_carbon_dashboard):
 
     user_input_cli = {
         ParamNames.add_on_activated.value: add_on_activated,
+        ParamNames.sc_num.value: sc_num,
         ParamNames.start_year.value: start_year,
         ParamNames.end_year.value: end_year,
         ParamNames.read_in_pkl.value: read_in_pkl,