forest-age-upscale

forest-age-upscale is a Python package to upscale forest age from heterogeneous observations using a machine-learning and biophysical fusion pipeline.
It also provides tools to access and process the GAMI (Global Age Mapping Integration) products.

The accompanying paper is:
“Global covariation of forest age transitions with the net carbon balance”
Nature Ecology & Evolution (2025). DOI: 10.1038/s41559-025-02821-5

---

Table of contents

• What’s inside
• Install
• Using GAMI data
• Reproducing paper figures
• Repository layout
• Cite
• Contributing
• License
• Contact

---

What’s inside

• Upscaling pipeline (ageUpscaling/): core modules for loading data, applying transformations, training models, and generating upscaled forest-age cubes.
• Analysis (analysis/): scripts to reproduce the figures and tables in the paper.

The package is tightly linked to the GAMI dataset — a global 100 m forest-age ensemble for 2010 and 2020 with quantified uncertainty.

---

Install

Requirements: Python ≥ 3.11

# clone
git clone https://github.com/simonbesnard1/forest-age-upscale.git
cd forest-age-upscale

# editable install
pip install -e .

It’s recommended to use a clean virtual environment (e.g. python -m venv .venv && source .venv/bin/activate).

---

Using GAMI data

Dataset: Global Age Mapping Integration (GAMI) (100 m, 2010 & 2020; 20-member ensemble with uncertainty).
DOI: 10.5880/GFZ.1.4.2023.006

Load with xarray:

import xarray as xr

ds = xr.open_dataset("/path/to/GAMI_v2.1/GAMIv2-1_2010-2020_100m.nc")
print(ds)

---

Reproducing paper figures

The folder analysis/generate_figures/ contains scripts to reproduce all figures from the paper.
Each script specifies required inputs in its header. Data are provided via the Nextcloud folder.

---

Repository layout

├─ ageUpscaling/                # Core package
│  ├─ core/
│  ├─ cubegen/
│  ├─ dataloaders/
│  ├─ diagnostic/
│  ├─ fidc_cube/
│  ├─ methods/
│  ├─ transformers/
│  ├─ upscaling/
│  └─ utils/
├─ analysis/                    # Analysis & figure generation
│  ├─ generate_figures/
│  └─ scripts/
├─ dev/
├─ setup.cfg
├─ setup.py
└─ README.md

---

Cite

If you use forest-age-upscale or GAMI, please cite both the dataset and the paper.

Dataset (GAMI v2.0):

@dataset{besnard_gami_v2_2024,
  title     = {Global Age Mapping Integration (GAMI) v2.0: Global Forest Age at 100 m for 2010 and 2020},
  author    = {Besnard, Simon and co-authors},
  year      = {2024},
  doi       = {10.5880/GFZ.1.4.2023.006},
  publisher = {GFZ Data Services}
}

Paper:

@article{besnard_nee_age_2025,
  title   = {Global covariation of forest age transitions with the net carbon balance},
  author  = {Besnard, S. and Heinrich, V.H.A. and Carvalhais, N. and Ciais, P. and Herold, M. and Luijkx, I. and others},
  journal = {Nature Ecology & Evolution},
  year    = {2025},
  doi     = {10.1038/s41559-025-02821-5}
}

---

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes (with clear code, tests, and docs).
4. Open a Pull Request.

---

License

This project is licensed under the EUROPEAN UNION PUBLIC LICENCE v.1.2 (EUPL-1.2). See LICENSE for details.

---

Contact

Simon Besnard — [email protected]