cobwood 0.2.3

Python package that implements a Cobweb version of the Global Forest Trade Model

Cobwood is a Python package designed to analyse global forest products markets.

Key Features:

• Panel Data Structure: The package represents international forest products market data through 2 dimensional arrays with multiple years and countries, enabling time-series and cross-sectional analysis.

• Data Handling with Xarray: Utilizes Xarray datasets to efficiently manipulate multi-dimensional data structures. X array is tightly integrated with pandas. Conversion to and from pandas data frames is very straightforward. Xarray datasets are saved on disk using the NetCDF format. This format has the advantage of providing good metadata descriptors. NetCDF is a standard data format used in earth systems modelling, that will just help this model become a component of a greater modelling tool chain.

Documentation

• The package documentation (generated from function and method docstrings) is available at https://bioeconomy.gitlab.io/cobwood/cobwood/cobwood.html

• Instructions below explain how to install and run the model. They provide an overview of model formulation and data structure.

• The paper at paper describes the context and purpose of cobwood.

Installation

Install from the python package index:

pip install cobwood

Install optional development dependencies to run tests or build the documentation:

pip install cobwood[dev]

Input data

The cobwood package requires input data from the cobwood_data repository.

Default data location

By default, cobwood looks for data at ~/repos/cobwood_data/. Clone the repository to this location:

mkdir -p ~/repos
cd ~/repos
git clone https://gitlab.com/bioeconomy/cobwood/cobwood_data.git

To verify the current data directory location, start python and call:

from cobwood import cobwood_data_dir
print(cobwood_data_dir)

Custom data location (COBWOOD_DATA environment variable)

To use a different location for the data, set the COBWOOD_DATA environment variable before importing cobwood:

Linux/Mac:

export COBWOOD_DATA="/path/to/your/cobwood_data"

On windows you can set the environment variable in the system GUI, or use a command prompt as follows:

Windows (Command Prompt):

set COBWOOD_DATA=C:\path\to\your\cobwood_data

Windows (PowerShell):

$env:COBWOOD_DATA="C:\path\to\your\cobwood_data"

You can also set it directly in In Python (before importing cobwood):

import os
os.environ["COBWOOD_DATA"] = "/path/to/your/cobwood_data"
from cobwood import cobwood_data_dir
print(cobwood_data_dir)  # Should show your custom path

Then clone the data repository to your chosen location:

mkdir -p /path/to/your/cobwood_data
cd /path/to/your
git clone https://gitlab.com/bioeconomy/cobwood/cobwood_data.git

The input data is based on:

• A version of the GFPMx model that is no longer available online. More information in the data repository https://gitlab.com/bioeconomy/cobwood/cobwood_data

• The FAOSTAT forestry production and trade data set available at: http://www.fao.org/faostat/en/#data/FO/visualize

More details in the data repository https://gitlab.com/bioeconomy/cobwood/cobwood_data

Testing

After installing the development dependencies, you can run the test suite to verify the installation and ensure everything works correctly.

Run tests with pytest:

pytest

Doctests are embedded in function docstrings and serve as both documentation and tests. Run doctests through pytest:

pytest --doctest-modules cobwood/

Test coverage

pytest --cov

Type checking

mypy cobwood

Optional virtual environment

Optionally create a virtual environment and install the cobwood package and its dependencies inside this virtual environment:

mkdir -p /tmp/cobwoodenv
cd /tmp/cobwoodenv/
python3 -m venv /tmp/cobwoodenv/
source /tmp/cobwoodenv/bin/activate
pip install cobwood

Replace /tmp/cobwoodenv with whatever directory path you want to use on your computer. You can later on use the model inside this virtual environment by activating it each time with:

source /tmp/cobwoodenv/bin/activate

Run the model

Currently, only the GFFPMx model is available. We will now illustrate how to initiate a model instance for a given scenario. Scenarios are defined in the scenario input directory cobwood_data/scenarios as yaml files. They define variations of the model input, by changing some of the variables, such as the GDP projections for example. Here is how to run the model to reproduce a baseline scenario:

1. Load the input data into a GFPMX model object.

from cobwood.gfpmx import GFPMX
gfpmxb2021 = GFPMX(scenario="base_2021", rerun=True)

2. Run the model.At each step compare with the reference model run inside the Excel Sheet:

gfpmxb2021.run(compare=True, strict=False)

3. Explore the model output tables and make plots.

print(gfpmxb2021["sawn"])
print(gfpmxb2021["sawn"]["cons"])

4. Create plots

import matplotlib.pyplot as plt
gfpmxb2021.facet_plot_by_var("indround")
plt.show()

Model Formulation

The core implementation serves as a foundation for developing various versions of global forest sector models. A panel data structure based on N dimensional arrays enable users to extend, or customize the model to fit specific research questions.

The first model formulation is based on GFPMX: "A Cobweb Model of the Global Forest Sector, with an Application to the Impact of the COVID-19 Pandemic" by Joseph Buongiorno https://doi.org/10.3390/su13105507

The GFPMX input data and parameters are available as a spreadsheet at: https://buongiorno.russell.wisc.edu/gfpm/

Equations

Equations are defined using Xarray time and country indexes so that they appear similar to mathematical equations used in the papers describing the model. For example, the consumption equation in cobwood/gfpmx_equations.py takes a dataset and a specific time t as input and returns a data array as output. The input dataset ds contains price and GDP data for all time steps and all countries, as well as price and GDP elasticities. The computation at a given time and for a given set of countries is done by using the time index t and the country index ds.c (which represents all countries in the dataset) as follows:

def consumption(ds: xarray.Dataset, t: int) -> xarray.DataArray:
    """Compute consumption equation 1"""
    return (
        ds["cons_constant"]
        * pow(ds["price"].loc[ds.c, t - 1], ds["cons_price_elasticity"])
        * pow(ds["gdp"].loc[ds.c, t], ds["cons_gdp_elasticity"])
    )

Data structure

Cobwood implements simulations of the Global Forest Products Market (GFPM), covering data for 180 countries over 80 years. Each equation within the model is structured over two-dimensional Xarray data arrays, where:

• Countries form the first dimension (or coordinate), allowing for cross-sectional analysis.
• Years constitute the second dimension, facilitating time-series insights.

Data Manipulation and Export. Xarray data arrays can be converted to a format similar to the original GFPMx spreadsheet with countries in rows and years in columns. For example the following code uses DataArray.to_pandas() to convert the pulp import array to a csv file using the pandas to_csv() method:

from cobwood.gfpmx_data import GFPMXData
gfpmx_data = GFPMXData(data_dir="gfpmx_8_6_2021", base_year = 2018)
pulp = gfpmx_data.convert_sheets_to_dataset("pulp")
pulp["imp"].to_pandas().to_csv("/tmp/pulp_imp.csv")

Example table containing the first few lines and columns:

country	2019	2020	2021
Algeria	66	61	56
Angola	0	0	0
Benin	0	0	0

The DataArray.to_dataframe() method converts an array and its coordinates into a long format also called a tidy format with one observation per row.

pulp["imp"].to_dataframe().to_csv("/tmp/pulp_imp_long.csv")

Example table containing the first few lines and columns:

country	year	imp
Algeria	2019	66
Algeria	2020	61
Algeria	2021	56