MATER

Metabolic Analysis for Transdisciplinary Ecological Research

[TOC]

📋 Requirements

• Python 3.12 or higher

We recommend using one virtual environment per Python project to manage dependencies and maintain isolation. You can use a package manager like uv to help you with library dependencies and virtual environments.

Quick start

Use init-mater-project (recommended).
It provides a complete project structure, CLI tools, and data pipeline in minutes.

💡 Direct MATER usage is only recommended for:

• Custom integrations in existing codebases
• Advanced users building specialized tools
• Contributing to the MATER framework itself

Direct MATER usage

Install the mater package in your project via UV (recommended) or pip:

uv add mater
# Or
pip install mater

Example: Run a Simulation with an Excel file

Create a Python script in your working directory to run simulations. Ensure the required Excel input file (chose a compatible version) is located in the root of your working directory.

Create a file named simulate.py (or any name you prefer) with the following content:

"""
MATER simulation script.
"""

from mater import Mater

# === CONFIGURATION ===
INPUT_FILE = "your_file.xlsx"  # Name of your Excel input file
OUTPUT_FOLDER = "run0"  # Name of the folder where outputs are stored
START_TIME = 1901  # Initial time step
END_TIME = 2100  # Final time step
TIME_FREQUENCY = "YS"  # Time frequency
# === END CONFIGURATION ===


def main():
    """Run MATER simulation."""
    model = Mater()
    model.run_from_excel(
        OUTPUT_FOLDER,
        INPUT_FILE,
        simulation_start_time=START_TIME,
        simulation_end_time=END_TIME,
        time_frequency=TIME_FREQUENCY,
    )


if __name__ == "__main__":
    main()

To run your simulation:

1. Edit the configuration values at the top of the script

2. Save the file

3. Execute the script:

uv run simulate.py

Output variables description

Accessing the Results from a Python Script

Below is an example Python script using pandas and matplotlib to plot specific simulation results. Each folder in the output directory corresponds to a variable that can be loaded with pandas.

# Import the MATER package and matplotlib.pyplot
import matplotlib.pyplot as plt
from mater import Mater

# Create a Mater instance
model = Mater()

# Select the output directory where the run results are stored
model.set_output_dir()  # Defaults to the working directory

# Set the run directory name
model.set_run_name("run0")

# Get a variable
in_use_stock = model.get("in_use_stock")

# Transform the dataframe and plot the results
in_use_stock.groupby(level=["location", "object"]).sum().T.plot()
plt.show()

This example demonstrates how to access and plot variables from simulation outputs. Adjust the code to fit your analysis needs.

🤝 Contributing

We welcome contributions to the MATER project! To get started, please refer to the CONTRIBUTING file for detailed guidelines.

📚 Online Documentation

For more information, refer to the official MATER documentation.