# MRIO Toolbox

[![PyPI](https://img.shields.io/pypi/v/mrio_toolbox)](https://pypi.org/project/mrio_toolbox/)
[![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://tbeaufils.codeberg.page/mrio_toolbox)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17573558.svg)](https://doi.org/10.5281/zenodo.17573558)

Open-source Python package for handling Multi-Regional Input-Output (MRIO) tables with high flexibility.

## Overview

The `mrio_toolbox` is a Python library designed for manipulating Multi-Regional Input-Output tables. It provides tools for loading, processing, analyzing, and exporting MRIO data from various sources including EXIOBASE, WIOD, EORA, and custom datasets.

This package supports:
- Extraction and conversion routines for widely used MRIOs (EXIOBASE, WIOD, EORA, Gloria, GTAP, Emerging, Figaro)
- Fast and lightweight data storage
- Numpy-style indexing and selection
- Standardized manipulation routines for reproducible research: aggregation, cleaning pipelines, mathematical operations, mapping algorithms

In comparison to higher-level MRIO-handling packages such as [pyMRIO](https://pymrio.readthedocs.io/en/latest/index.html) and [MARIO](https://mario-suite.readthedocs.io/en/latest/intro.html), `mrio_toolbox` focuses on providing low-level routines for advanced MRIO users.

## Installation

Install the latest stable version using pip:

```bash
pip install mrio_toolbox
```

Or install from source:

```bash
git clone https://codeberg.org/tbeaufils/mrio_toolbox.git
cd mrio_toolbox
pip install -e .
```

## Documentation

The `mrio_toolbox` package builds on two major concepts: MRIO, and Parts. 

MRIO are high-level objects that can inherit an arbitrary number of Part instances.

Part instances contain the actual data. Each Part represent a different quadrant of the MRIO table. As a convention, we use t for the inter-industry matrix, a for the matrix of technical coefficients, y for the final demand and va for the value added. A Part can have any shape and more than two dimensions.
Parts support numpy-like indexing, on index and labels. They can be created in insolation or as part of an MRIO object. A new Part can be created by manipulating another Part.

Check the [example](https://tbeaufils.codeberg.page/mrio_toolbox/Example%20use.html) section of the documentation for hands-on examples.

The full documentation is available at [https://tbeaufils.codeberg.page/mrio_toolbox](https://tbeaufils.codeberg.page/mrio_toolbox)

## Contributing

The package is under development on the side of my main research activity. 
I appreciate contributions, in particular for extending the test coverage, improving the documentation and implementing new features.
Please see the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

## Citing

If you use this package in your research, you can cite it as:

> Beaufils, T., & Wirth, F. (2023). mrio_toolbox: Python package for Multi-Regional Input-Output analysis. Zenodo. https://doi.org/10.5281/zenodo.17573558

## License

This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
This means that you can use, modify and distribute this library as you want, but any product derived from this library must be released under the same term of license.

## Contact

For questions, bug reports, or feature requests, you can use the Issue page of the repository.
