Skip to content

About

This repository is operationnalising statisitcal entropy analysis on any kind of material flow data, even complex processes taken from process simulation softwares. The only inputs are: (1) Flows networks (links between flows, processes, and environment nodes and (2) flows mass flow rate and mass concentrations data.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

10 Commits

Folders and files

Repository files navigation

Statistical Entropy Analysis (SEA) Repository

This repository operationalizes Statistical Entropy Analysis (SEA) on material flow data, including complex processes from process simulation software. The analysis requires only two types of inputs: (1) flow networks (links between flows, processes, and environment nodes) and (2) flow mass flow rate and mass concentration data.

πŸ“ Repository Structure

statistical_entropy_analysis/
β”œβ”€β”€ main_sea.ipynb          # Main Jupyter notebook for SEA analysis
β”œβ”€β”€ sea.xlsx                # Input Excel file with process data
β”œβ”€β”€ LICENSE                  # MIT License
└── README.md               # This file

πŸ“Š Input Excel File: sea.xlsx

Overview

The sea.xlsx file contains multiple sheets, each representing a Unit Process in the material flow system. Each sheet must follow a specific structure to be correctly parsed by the notebook.

Sheet Structure (Required)

Each sheet (unit process) must contain the following mandatory columns:

Column Name Data Type Description Example Values
flow_name String Unique identifier for the flow f_0-1_eol-libs, f_12-1_int-recycled
flow_type String Type of flow product, waste, by-product
provider/consumer String Source or destination of the flow economic environment, fu, u12_tank, background
direction String Flow direction relative to the process input or output
mass-FU_kg-eq Float Mass flow rate in kg-equivalent per functional unit 1.000, 0.581

Chemical Element Columns (Required)

After the mandatory columns, chemical element columns must be present. These columns represent the mass concentration (in weight percent, w%) of each chemical element in the flow.

Recognized chemical elements (2-letter symbols from the periodic table):

  • Al, C, Ca, Co, Cu, F, Fe, H, Li, Mn, Na, Ni, O, P, S
  • The notebook also recognizes e- (electrons) and Rest as special cases

Example element columns:

Al C Ca Co Cu e- F Fe H Li Mn Na Ni O P S
1.874 31.163 0.0 7.584 1.295 0.0 3.078 0.0 0.161 4.469 7.070 0.000 22.660 20.635 0.011 0.000

Optional Columns

The following columns are optional and used for extended analysis:

Column Name Data Type Description
enthalpy_flowsheet_kW Float Enthalpy in kW
enthalpy-FU_MJ-eq Float Enthalpy per functional unit in MJ-equivalent
exergy_flowsheet_kW Float Exergy in kW
exergy-FU_MJ-eq Float Exergy per functional unit in MJ-equivalent
mass_flowsheet_t/h Float Mass flow rate in tonnes per hour
lca_upr_name_*, lca_upr_loc_*, lca_flow_name_*, amount_*, lca_database_* Mixed Life Cycle Assessment (LCA) data for background processes

Sheet Naming Convention

  • Each sheet name represents a Unit Process
  • Sheet names should be unique and descriptive
  • Example: u1_black-mass-pulping, u2_leaching, u3_hydrated-lime_pulping
  • The prefix u followed by a number is recommended for ordering

Data Requirements

  1. Direction Values: Must be either input or output (case-insensitive)
  2. Provider/Consumer Values:
    • For flows from the environment/background: Use terms like economic environment, fu, background, stock
    • For flows between processes: Use the exact sheet name of the connected process (e.g., u12_tank)
  3. Mass Flow Rate: Must be numeric (float or integer)
  4. Element Concentrations: Must be numeric (float or integer), representing weight percent (w%)

Example Sheet Structure

| flow_name | flow_type | provider/consumer | direction | mass-FU_kg-eq | Al | C | Ca | ... |
|-----------|-----------|-------------------|-----------|---------------|----|---|----|-----|
| f_0-1_eol-libs | product | economic environment, fu | input | 1.000 | 1.874 | 31.163 | 0.0 | ... |
| f_0-1_HF-heating | product | background | input | 0.000 | 0.0 | 0.0 | 0.0 | ... |
| f_12-1_int-recycled | product | u12_tank | input | 0.581 | 0.0 | 0.139 | 0.0 | ... |
| f_1-2_black-mass | product | u2_leaching | output | 1.581 | 1.874 | 31.163 | 0.0 | ... |

Building Your Own sea.xlsx File

To create a compatible Excel file:

  1. Create a new Excel workbook
  2. Add sheets for each unit process in your system
  3. Include all mandatory columns in each sheet
  4. Add chemical element columns for all elements present in your flows
  5. Ensure data consistency:
    • All flows must have valid flow_name values
    • direction must be either input or output
    • provider/consumer must reference either another process sheet or an environment/background source
    • Element concentrations must sum to approximately 100% (or less if Rest is used)
  6. Save as .xlsx format (Excel Workbook)

Validation Checklist

Before running the notebook, verify your Excel file:

  • Each sheet has a unique name
  • All mandatory columns are present
  • Chemical element columns use valid 1-2 letter symbols
  • direction column contains only input or output
  • mass-FU_kg-eq column contains numeric values
  • Element concentration values are numeric (0-100 range)
  • provider/consumer references are valid (either environment or existing process sheets)

πŸ““ Notebook: main_sea.ipynb

Overview

The main_sea.ipynb notebook implements a complete Statistical Entropy Analysis workflow following the methodology described in:

  • Rechberger & Graedel (2002) - The contemporary European copper cycle: statistical entropy analysis
  • Laner et al. (2017) - Material flow analysis and statistical entropy for the assessment of recycling systems

Notebook Structure

πŸ”Ή Section 1: Initialisation

Cells 1-4: Setup and configuration

  • Cell 1: Import required libraries

    • numpy, pandas - Data manipulation
    • matplotlib - Visualization
    • mendeleev - Chemical element validation (optional, with fallback)
    • collections - Data structures for graph traversal
  • Cell 2: Define local paths

    • Set file_path variable to point to your Excel file location
    • Default: excel_file_path = "sea.xlsx" (file in same directory)
  • Cell 3: Chemical element recognition

    • is_chemical_element() function validates column names as chemical elements
    • Supports standard periodic table symbols (1-2 letters)
    • Special case: "Rest" is treated as a valid component
    • Fallback mechanism if mendeleev library is not available

πŸ”Ή Section 2: Unit Processes Elemental-Mass Balance

Cells 5-7: Mass balance verification

  • Function: check_mass_balance_per_element(excel_file)
  • Purpose: Validates mass balance for each process and element
  • Output:
    • Detailed mass balance per element (input vs output)
    • Overall mass balance per process
    • Relative error percentages
    • Identification of largest imbalances
  • Key Metrics:
    • Total input/output mass (t/h)
    • Element-wise mass flows (kg/h)
    • Balance error and relative error (%)

Note: This step ensures data quality before proceeding with SEA calculations.

πŸ”Ή Section 3: Stage Diagram Construction

Cells 8-20: Process ranking and stage diagram creation

This section implements the stage diagram methodology from Rechberger & Graedel (2002):

"The number of stages in the system is defined as one more than the number of processes. If the system contains n_P processes, the number of stages n_S is given by: n_S = n_P + 1"

Subsections:

  1. Get Original Processes (Cell 13)

    • get_original_processes(excel_file) - Identifies root nodes
    • Criteria: Processes with "fu" in input provider OR no process inputs
  2. Process Ranking (Cells 15-16)

    • assign_process_ranks_all_options() - Assigns ranks using BFS from each original process
    • Handles recycling flows (flows where producer rank β‰₯ consumer rank)
    • Implements back-propagation for unranked providers
    • Generates multiple ranking options (one per original process)
  3. Flow Distinctions (Cell 17)

    • get_internal_recycling_flows() - Detects recycling flows
    • get_input_environment_flows() - Identifies environment inputs
    • get_output_environment_flows() - Identifies environment outputs
    • get_intermediate_foreground_product_flows() - Identifies intermediate flows
  4. Stages Creation (Cells 19-20)

    • build_system_2stage_dataframes() - Creates 2-stage system diagram
    • build_stage_flow_dataframes() - Builds dataframes for each stage
    • Stage Assignment Rules:
      • Environment inputs: Stages 1 to consumer_rank
      • Intermediate flows: provider_rank+1 to consumer_rank
      • Environment outputs: producer_rank+1 to max_stage
      • Recycling flows: Special handling for backward flows

πŸ”Ή Section 4: Stage Diagram Execution

Cells 21-30: Execute ranking and stage construction

  • Select ranking option (manual or automatic)
  • Generate stage dataframes
  • Create visual stage diagram

Output:

  • stage_dfs[i] - DataFrame for each stage i, containing all flows in that stage
  • Ranking CSV files for each option
  • Recycling flow identification

πŸ”Ή Section 5: Stages Elemental-Mass Balance

Cell 32: Validate mass balance at stage level

  • Ensures mass conservation across stages
  • Prepares data for entropy calculations

πŸ”Ή Section 6: Compute the SEA

Cells 34-41: Statistical Entropy Analysis computation

Key Functions:

  1. For One Stage (Cell 36)

    • compute_stage_entropy() - Calculates entropy for a single stage
    • Adds 3 columns to stage DataFrame:
      • Shannon entropy
      • Rechberger entropy
      • Relative Statistical Entropy (RSE)
  2. For Elements (Cell 39)

    • Element-wise entropy calculations
    • Contribution analysis per element
  3. General (Cell 41)

    • Aggregated entropy metrics
    • System-level indicators

Entropy Formulas:

  • Shannon Entropy: H = -Ξ£ (p_i Γ— logβ‚‚(p_i))
    • Where p_i is the mass fraction of flow i
  • Rechberger Entropy: Modified Shannon entropy for material flows
  • Relative Statistical Entropy (RSE): Normalized entropy measure

πŸ”Ή Section 7: Main Execution and Results

Cells 43-47: Run complete analysis and visualize results

  • Execute all SEA computations
  • Generate plots and charts
  • Example: O concentration vs. O RSE contribution

πŸ”Ή Section 8: Analyse the SEA

Cells 49-57: Advanced analysis and interpretation

  • Compare flows between stages - Track entropy changes through the system
  • Contribution analysis - Identify which flows/elements contribute most to entropy
  • Element listing - Detailed breakdown by chemical element

πŸ”§ Requirements

Python Packages

The notebook requires the following Python packages:

pip install numpy pandas matplotlib openpyxl mendeleev

Optional: If mendeleev is not available, the notebook falls back to a predefined list of chemical symbols.

Python Version

  • Recommended: Python 3.8+
  • Tested with: Python 3.10+

πŸš€ Quick Start

  1. Clone the repository:

    git clone https://github.com/LouisFreboeuf/statistical_entropy_analysis.git
    cd statistical_entropy_analysis
  2. Install dependencies:

    pip install numpy pandas matplotlib openpyxl mendeleev
  3. Prepare your data:

    • Create sea.xlsx following the structure described above
    • Or use the provided example file
  4. Run the notebook:

    jupyter notebook main_sea.ipynb
  5. Follow the workflow:

    • Execute cells in order
    • Review mass balance results
    • Select ranking option if multiple original processes exist
    • Analyze SEA results

πŸ“š Methodology References

The SEA methodology implemented in this repository is based on:

  1. Rechberger, H., & Graedel, T. E. (2002). The contemporary European copper cycle: statistical entropy analysis. Center for Industrial Ecology, School of Forestry and Environmental Studies, Yale University. DOI:10.1016/j.ecolind.2017.07.060

  2. Laner, D., Rechberger, H., & Astner, I. (2017). Material flow analysis and statistical entropy for the assessment of recycling systems. Ecological Indicators, 81, 148-158.

Key Concepts

  • Statistical Entropy: Measure of disorder or uncertainty in a system
  • Material Flow Analysis (MFA): Tracking materials through a system
  • Stage Diagram: Representation of material flows through sequential stages
  • Recycling Flows: Material flows that loop back to earlier stages

πŸ“œ Citation

If you use this repository or its methodology in your research, please cite it using the provided CITATION.cff file. This file follows the Citation File Format standard and is compatible with Zenodo and other citation tools.

How to Cite

  1. Using the CITATION.cff file:

    • Many reference managers (e.g., Zotero) and platforms (e.g., Zenodo) automatically recognize this file.
    • Example citation (APA style):
      Freboeuf, L. (2026). Statistical Entropy Analysis (SEA) Repository (Version 1.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.XXXXXXX
      
  2. Manual Citation:

    • Format: Author (Year). Title (Version). [Computer software]. Repository URL. DOI (if available).
  3. BibTeX Entry:

    @software{Freboeuf2026StatisticalEntropyAnalysis,
      author = {Freboeuf, Louis},
      title = {Statistical Entropy Analysis (SEA) Repository},
      year = {2026},
      version = {1.0.0},
      publisher = {Zenodo},
      doi = {10.5281/zenodo.XXXXXXX},
      url = {https://github.com/LouisFreboeuf/statistical_entropy_analysis}
    }

Zenodo Integration

This repository is configured for seamless integration with Zenodo. To create a citable archive:

  1. Connect your GitHub account to Zenodo.
  2. Enable the repository for automatic archiving.
  3. Create a GitHub release (e.g., v1.0.0).
  4. Zenodo will automatically archive the release and assign a DOI.

πŸ”’ Repository Protection

License

This repository is licensed under the MIT License (see LICENSE file).

Permissions:

  • βœ… Free to use, copy, modify, merge
  • βœ… Free to publish, distribute, sublicense
  • βœ… Free to sell copies
  • ❌ Must include copyright notice and license in all copies
  • ❌ No liability or warranty provided

Intellectual Property

  • Copyright: Β© 2026 LouisFreboeuf
  • Attribution: When using this code or methodology, please cite the original repository and relevant academic papers

Data Privacy

  • The example sea.xlsx file contains simulated process data
  • No real-world proprietary data is included
  • Users are responsible for ensuring their own data complies with privacy regulations

Contribution Guidelines

While this repository is currently a single-author project, contributions are welcome:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request with clear description of changes
  4. Ensure all tests pass (if applicable)
  5. Maintain code style and documentation standards

Security

  • This repository contains no sensitive credentials or API keys
  • All data is synthetic and for demonstration purposes
  • Users should not commit real-world sensitive data to public repositories

πŸ“ž Support

For questions or issues:

  1. Check this README for Excel file structure requirements
  2. Review the notebook comments for detailed explanations
  3. Consult the referenced papers for methodological questions
  4. Open an issue on GitHub for bugs or feature requests

🎯 Use Cases

This SEA implementation is suitable for:

  • Recycling system analysis - Evaluate material recovery efficiency
  • Process optimization - Identify entropy hotspots in material flows
  • Sustainability assessment - Quantify resource dissipation
  • Circular economy studies - Analyze material loop closure
  • Industrial ecology - Model complex material flow networks

Last updated: July 2026 Maintainer: LouisFreboeuf

About

This repository is operationnalising statisitcal entropy analysis on any kind of material flow data, even complex processes taken from process simulation softwares. The only inputs are: (1) Flows networks (links between flows, processes, and environment nodes and (2) flows mass flow rate and mass concentrations data.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages