rex3handler 0.1.0

Download, extract, and convert the REX3 MRIO dataset to Zarr for further processing.

REX3Handler

REX3Handler is a Python toolkit to download, extract, and convert the highly resolved REX3 MRIO database into chunked, analysis-ready Zarr format. It enables seamless access and integration into Python workflows — no MATLAB required.

---

🌍 About the REX3 Database

REX3 (Resolved EXIOBASE version 3) is a high-resolution Multi-Regional Input-Output (MRIO) database developed by Livia Cabernard as part of the study:

“Biodiversity impacts of recent land-use change driven by increases in agri-food imports”
Published in Nature Sustainability — Read the article

🧬 What's inside REX3?

• 189 countries, 163 sectors
• Time series from 1995 to 2022
• Includes climate impacts, PM health, water stress, biodiversity impacts (land occupation, land-use change, eutrophication)
• Based on:
  • EXIOBASE 3.8
  • Eora26
  • FAOSTAT production data
  • BACI trade data
  • LUH2 land use harmonization
• Compliant with UNEP-SETAC environmental assessment guidelines

📦 File contents (per year)

Each REX3_YYYY.zip file contains:

• T_REX3.mat: Transaction matrix
• Y_REX3.mat: Final demand matrix
• Q_REX3.mat, Q_Y_REX3.mat: Satellite extensions (economic & final demand)

Labels for all matrices, countries, sectors, and extensions are provided in a separate REX3_Labels.zip.

---

💡 Why use REX3Handler?

The REX3 dataset is primarily provided in MATLAB .mat format, which may not be ideal for many researchers, particularly in the Earth system, environmental economics, or data science communities who work primarily in Python.

REX3Handler was built to:

• ✅ Automate downloading from Zenodo
• ✅ Unpack ZIP archives
• ✅ Convert .mat files into Python-native xarray.Dataset objects in .zarr format
• ✅ Enable fast, scalable, multi-year MRIO analysis
• ✅ Provide a foundation for future development: MRIO analytics, visualization, decomposition, and more (coming soon)

---

Quick‑start

# Install 
pip install rex3handler

Download options

1 Download the entire archive (all years + misc.) using 8 threads

rex3 download all --workers 8

2 Download a single year (1999) using 4 threads (~4GB per year)

rex3 download single --year 1999 --workers 4

3 Download a range of years (e.g., 2018–2023) using 8 threads

rex3 download range --start 2018 --end 2023 --workers 8

Extract and convert

Unzip all downloaded archives

rex3 extract

Convert all extracted .mat files into chunked Zarr format (~2GB per year)

rex3 convert

Load and explore in Python

import xarray as xr

# Open one year's data
ds = xr.open_zarr("REX3ZARR/1999.zarr", consolidated=True)

# Access the transaction matrix
T_array = ds["T"]

# Convert to NumPy array if needed
T_numpy = T_array.values

# Check dimensions and shape
print(T_array.dims)
print(T_array.shape)