The Global Flows of Iron from Lithosphere to Technosphere

This repository contains the data, source code, Jupyter notebooks, and outputs used in our study on global iron flows from extraction to in-use stocks. It provides all materials needed to reproduce the analyses and visualizations presented in the manuscript.

An executable and reproducible version of the analysis is provided via a Code Ocean capsule linked to the manuscript. Access is available to editors and reviewers through the journal’s submission system.

Contents

• src/ – Source code for data processing, modeling, and analysis
• data/raw/ – Raw datasets used in the analysis
• data/output/ – Cleaned and formatted datasets ready for analysis
• data/netcdf/ – Final outputs in NetCDF format
• data/plot/ – Generated plots and figures
• data/atlas/ – Selected SESAME Human-Earth Atlas (Faisal et al., 2025) datasets used in this study
• demo/ – Lightweight demo workflow, including a reduced dataset, demo script, and example outputs for rapid verification of installation and execution

Usage

1. Explore the Jupyter notebooks to follow the full analysis workflow.
2. Run the scripts in src/ to reproduce data processing, modeling, and figures.
3. Check data/netcdf/ for the final outputs in NetCDF format.

System requirements

Operating systems

The software has been tested on:

• macOS 15.7
• Red Hat Enterprise Linux 7.9

Execution on Windows is expected but has not been explicitly tested.

Software dependencies

All dependencies are managed using Conda and are specified in environment.yml.

Key dependencies include:

• Python 3.11 or later
• numpy
• pandas
• scipy
• geopandas
• shapely
• pyproj
• rasterio
• cartopy
• xarray
• sesame-iesd
• networkx

Exact versions are resolved automatically during environment creation.

Hardware requirements

No non standard hardware is required. A standard desktop or laptop computer with at least 8 GB RAM is sufficient.

Installation guide

Step 0. Install Git LFS

This repository uses Git Large File Storage (LFS) to manage large data files.

Install Git LFS before cloning the repository.

macOS:

brew install git-lfs

Ubuntu or Debian:

sudo apt install git-lfs

Windows: Download and install from: https://git-lfs.github.com/

Initialize Git LFS:

git lfs install

Step 1. Clone the repository

git clone https://github.com/A2Faisal/FeFlow.git
cd FeFlow

Step 2. Pull Git LFS managed files

If the code does not work, then

git lfs pull

This step is required to download all large data files needed to run the workflows. If this step is skipped, the software will run with missing inputs and produce errors.

Note: If Git LFS is correctly installed prior to cloning, large files may be downloaded automatically during git clone. Running git lfs pull ensures that all required LFS-tracked files are present. Typical download time: approximately 2–10 minutes, depending on internet speed. Total repository size (including Git LFS files): approximately 3.9 GiB.

Step 3. Create the Conda environment

conda env create -f environment.yml -n feflow
conda activate feflow

Step 4. Verify installation

python -c "import xarray, geopandas, networkx, sesame;  print('Installation successful')"

Demo

A lightweight demo is provided to allow rapid verification of correct installation and execution without running the full computational workflow.

The demo script is located in the demo/ directory and uses a reduced dataset packaged specifically for this purpose.

Running the demo

From the repository root, run:

conda activate feflow
python demo/iron_demo.py

Expected output

NetCDF file, plots and maps are written to:

demo/output/

Notes

• All files required to reproduce the figures and results in the manuscript are included.
• Python and Jupyter are required to run the notebooks.
• The demo uses only files contained in demo/data/.
• The demo completes in approximately 1 to 10 minutes on a normal desktop computer.

Contact

For questions or inquiries about this project, please contact abdullah-al.faisal@mail.mcgill.ca or maxwell.kaye@mail.mcgill.ca.