MARIO

Multifunctional Assessment of Regions through Input-Output

Contents:

https://img.shields.io/gitter/room/SESAM-Polimi/MARIO https://img.shields.io/badge/code%20style-black-000000.svg Documentation Status https://badge.fury.io/py/mariopy.svg https://raw.githubusercontent.com/SESAM-Polimi/MARIO/767d2c0e9e42ae0b6acf7c3a1cc379d7bcd367fa/doc/source/_static/images/polimi.svg https://zenodo.org/badge/421900437.svg

MARIO

Multifunctional Analysis of Regions through Input-Output. (Documents)

What is it

MARIO is a python package for handling input-output tables and models inspired by Pymrio . MARIO aims to provide a simple & intuitive API for common IO tasks without needing in-depth programming knowledge. MARIO supporst automatic parsing of different structured tables such EXIOBASE, EORA, EUROSTAT in different formats namely:

  • Single region

  • Multi region

  • Hybrid tables

  • Monetary tables

  • Input-Output tables

  • Supply-Use tables

When databases are not structured, MARIO supports parsing data from xlsx, csv, txt files or pandas.DataFrames.

More than parsing data, MARIO includes some basic functionalities:

  • Aggregation of databases

  • SUT to IOT transformation

  • Modifying database in terms of adding:
    • New sectors, activities or commodities to the database

    • Adding new extensions to the satellite account

  • Scneario and shock analysis

  • Backward and forward linkages analysis

  • Extracting single region database from multi region databases

  • Balance test

  • Productivity test

  • Exporting the databases into different formats for scenarios analyzed

  • Interactive visualization routines

Requirements

MARIO has been tested on macOS and Windows.

To run MARIO, a couple of things are needed:

  1. Being in love with Input-Output :-)

  2. The Python programming language, version 3.7 or higher

  3. A number of Python adds-on packages

  4. For some functionalities a solver may needed (optional)

  5. MARIO software itself

Quickstart

A simple test for Input-Output Table (IOT) and Supply-Use Table (SUT) is included in mario.

To use the IOT test, call

import mario
test_iot = mario.load_test('IOT')

and to use the SUT test, call

test_sut = mario.load_test('SUT')

To see the configurations of the data, you can print them:

print(test_iot)
print(test_sut)

To see specific sets of the tables like regions or value added, get_index function can be used:

print(test_iot.get_index('Region'))
print(test_sut.get_index('Factor of production'))

To visualize some data, various plot functions can be used:

test_iot.plot_matrix(....)

Specific modifications on the database can be done, such as SUT to IOT transformation:

reformed_iot = test.to_iot(method='B')

The changes can be tracked by metadata. The history can be checked by calling:

reformed_iot.meta_history

The new database can be saved into excel,txt or csv file:

reformed_iot.to_excel(path='a folder//database.xlsx')

Python module requirements

Some of the key packages the mario relies on are:

Testing MARIO

The current version of Mario has achieved a test coverage of 49%. This coverage includes a comprehensive 100% assessment of the fundamental mathematical engine. Additional tests are currently in active development to enhance the package’s reliability. Mario utilizes pytest as its primary tool for conducting unit tests. For a more detailed analysis of the test coverage pertaining to mario’s unit tests, you can execute the following command:

pytest --cov=mario tests/

Note

  • This project is under active development.

  • More examples will be uploaded through time to the gellery.

  • More parsers will be added to the next version.

  • The next version will cover some optimization models within the IO framework

  • For more tutorials on mario, check out our Input-Output analysis and modelling with MARIO Course

License

https://www.gnu.org/graphics/gplv3-or-later.png

This work is licensed under a GNU GENERAL PUBLIC LICENSE

Download and installation

Requirements

MARIO has been tested on macOS and Windows.

To run MARIO, a couple of things are needed:

  1. Being in love with Input-Output :-)

  2. The Python programming language, version 3.7 or higher

  3. A number of Python adds-on packages

  4. For some functionalities a solver may needed (optional)

  5. MARIO software itself

Contributors

mario has been initally developed within SESAM group in the Department of Energy at Politecnico di Milano under the scientific coordination of Emanuela Colombo and Matteo Vincenzo Rocco. The research activity of SESAM focuses on the use of mathematical models for the study of systems and components in the energy field and industrial ecology.

mario has been used for some research projects within the group, and now is available as an open source code for the Input-Output modelling communities.

Authors

Communication, issues, bugs and contributions

We use github for tracking bugs, issues and suggestions related to mario. Any communications thorugh email are welcomed.

You may also follow us on social media like twitter or our official website to follow last news on mario or our research. We are looking forward for future communications and contributions.

Terminology

In the lack of consistent terminology for IO systems in the scientific community, MARIO uses its own customized variable names. MARIO follows a thermodynamic way of nomencluture which:

  • Uppercase letters represents Flows

  • Lowercase lettters represents Coefficients

Following table represents the variables and their explanations in MARIO:

MARIO Terminology

variable name

also known as

extended name

Z

T

Intersectoral transaction flows matrix

z

A

Intersectoral transaction coefficients matrix

w

L

Leontief coefficient matrix

Y

F

Final demand matrix

X

x, q, g

Production vector

V

F

Factor of production transaction flows matrix

v

f, B, S

Factor of production transaction coefficients matrix

E

F, D_pba, terr

Satellite transaction flows matrix

U

T

Use transaction flow matrix

u

A

Use coefficients matrix

S

V, M, T

Supply transaction flow matrix

s

A

Supply coefficients matrix

EY

S_Y, F_hh, F_y

Satellite transaction flows matrix for final use

M

Economic impact matrix

m

M

Multipliers coefficient matrix

F

D_cba, con

Footprint matrix

e

f, B, S

Satellite transaction coefficients matrix

f

M

Footprint coefficients matrix

g

G

Gosh coefficients matrix

b

B

Intersectoral transaction direct-output coefficients matrix

p

Price index coefficients vector

Handling databases

Exiobase3 parser

exiobase3Parse

EORA parser

parseEORA

Multi regional monetary supply and use exiobase

exiobaseSUT

Parsing using pd.DataFrame

pd.DataFrameParser

Parsing EUROSTAT

parseEUROSTAT

Excel parser

excelParser

Plotting by plot_matrix

plotsExamples

API Reference

Analyzing database

CoreModel.is_balanced(method[, data_set, ...])

Checks if a specific data_set in the database is balance or not

CoreModel.is_productive(method[, data_set])

Checks the productivity of the system

CoreModel.is_multi_region

Defines if a database is single region or multi-region

CoreModel.is_hybrid

checks if the database is hybrid or monetary

CoreModel.sets

Returns a list of levels of info in the model

CoreModel.scenarios

Returns all the scenarios existed in the model

CoreModel.table_type

Returns the type of the database

CoreModel.get_index(index[, level])

Returns a list or a DataFrame of different levels of indeces in the database.

Database modification

Database.aggregate(io[, drop, levels, ...])

This function is in charge of reading data regarding the aggregation

Database.add_sectors(io, new_sectors, ...[, ...])

Adds a Sector/Activity/Commodity to the database

Database.to_single_region(region[, backup, ...])

Extracts a single region from multi-region databases

Database.to_iot(method[, inplace])

The function will transform a SUT table to a IOT table

Database.add_extensions(io, matrix, units[, ...])

Adding a new extension [Factor of production or Satellite account] to the database passing the coefficients or the absolute values.

Database.update_scenarios(scenario, **matrices)

Updates the matrices for a specific scenario.

Database.reset_to_flows(scenario[, backup])

Deletes the coefficients of a scenario and keeps only flows

Database.reset_to_coefficients(scenario[, ...])

Deletes the flows of a scenario and keeps only coefficients

Database.clone_scenario(scenario, name)

Creates a new scenario by cloning an existing scenario

Database.copy()

Returns a deepcopy of the instance

Database.backup()

The function creates a backup of the last configuration of database to be returned in case needed.

Database.reset_to_backup()

This function is in charge of reseting back the database to the last back-up.

Shock analysis

Database.shock_calc(io[, z, e, v, Y, notes, ...])

Implements shocks on different matrices with the possibility of defining clusters on every level of information.

Data visualization

mario.set_palette([mario_palettes, user_palette])

Sets the default palette of plots

Database.plot_gdp([path, plot, scenario, ...])

Plots sectoral GDP with additional info

Database.plot_bubble(x, y, size[, path, ...])

Creates bubble plots

Database.plot_linkages([scenarios, ...])

Plots linkages in different modes

Database.plot_matrix(matrix, x, color[, y, ...])

Generates a general html barplot giving the user certain degrees of freedom such as:

Get excels

mario has some functions providing automatic excel file generations for easing some of the functionalities such as aggrgeaton and adding sectors.

Database.get_aggregation_excel([path, levels])

Generates the Excel file for aggregation of the database

Database.get_extensions_excel(matrix[, path])

Generates an Excel file for easing the add extension functionality

Database.get_add_sectors_excel(new_sectors, ...)

Generates an Excel file to add a sector/activity/commodity to the database

Database.get_shock_excel([path, num_shock])

Creates an Excel file based on the shape and the format

Save data

Database.to_excel([path, flows, ...])

Saves the database into an Excel file

Database.to_txt([path, flows, coefficients, ...])

Saves the database multiple text file based on given inputs

Database.to_pymrio([satellite_account, ...])

Returns a pymrio.IOSystem from a mario.Database

Database parsers

Structured Databases

mario supports automatic parsing of following database:

  • Exiobase

  • Eurostat Supply and Use

  • Eora26

  • Eora single region

mario.parse_exiobase_3(path[, calc_all, ...])

Parsing exiobase3

mario.parse_exiobase_sut(path[, calc_all, ...])

Parsing exiobase mrsut

mario.parse_eurostat_sut(supply_path, use_path)

Parsing Eurostat databases

mario.parse_eora(path, multi_region, table)

Parsing eora databases

mario.parse_from_pymrio(io, value_added, ...)

Parsing a pymrio database

mario.hybrid_sut_exiobase(path[, ...])

reads hybrid supply and use exiobase

mario.parse_exiobase(table, unit, path[, ...])

A unique function for parsing all exiobase databases

Non-Structured Databases

When databases are not structured (coming from abovementioned sources), excel or text parsers can be used. The databases in this case, should follow specific rules:

mario.parse_from_excel(path, table, mode[, ...])

Parsing database from excel file

mario.parse_from_txt(path, table, mode[, ...])

Parsing database from text files

Calculations

High level matrix calculations

This function can be called inside a mario.Database object to call missing matrices for different scenarios.

CoreModel.calc_all([matrices, scenario, ...])

Calculates the input-output matrices for different scenarios.

CoreModel.GDP([exclude, scenario, total, share])

Return the value of the GDP based scenario.

Database.calc_linkages([scenario, ...])

Calculates the linkages in different modes

Low level matrix calculations

This functions are used to calculate the matrices in mario.Database while they can be used independently outside a mario.Databases object.

calc_X(Z, Y)

Calculates the production vector

calc_X_from_w(w, Y)

Calculates Production vector from Leontief coefficients matrix

calc_X_from_z(z, Y)

Calculates Production vector from Intersectoral transaction coefficients matrix

calc_Z(z, X)

Calculates Intersectoral transaction flows matrix

calc_E(e, X)

Calculates satellite transaction flows matrix

calc_V(v, X)

Calculates Factor of production transaction flows matrix

calc_M(m, Y)

Calculates Economic impact matrix

calc_F(f, Y)

Calculates Footprint flows matrix

calc_z(Z, X)

Calculates Intersectoral transaction coefficients matrix

calc_v(V, X)

Calculates Factor of production transaction coefficients matrix

calc_e(E, X)

Calculates Satellite transaction coefficients matrix

calc_m(v, w)

Calculates Multipliers coefficients matrix

calc_f(e, w)

Calculates Footprint coefficients matrix

calc_w(z)

Calculates Leontief coefficients matrix

calc_g(b)

Calculates Ghosh coefficients matrix

calc_b(X, Z)

Calculates Intersectoral transaction direct-output coefficients matrix (for Ghosh model)

calc_p(v, w)

Calculating Price index coefficients vector

calc_y(Y)

Calculates Final demand share coefficients matrix

Metadata

CoreModel.save_meta(path[, format])

Saves the metadata in different formats

CoreModel.meta_history

Returns the whole history of the metadata

CoreModel.add_note(notes)

Adds notes to the meta history

Test

For having a simple exmaple of mario, load_test can be used.

mario.load_test(table)

Loads an example of mario.Database

Directory

When mario needs to save an output of the model, if no path is given, files wil be saved in a default directory with subfolders based on the type of the output. By default, the directory is the working directory but user can change the default directory.

CoreModel.directory

The defualt directory of the database

Utilities

There are some useful functions in mario that may help the user for different purposes.

CoreModel.search(item, search[, ignore_case])

Searches for specific keywords in a given item

mario.slicer(matrix, axis, **levels)

Helps to slice the matrices

Logging

In case that logging is useful for the user, the following function can be used to set the level of verbosity.

mario.set_log_verbosity([verbosity, ...])

Sets the formatted logging level