FRAME

FRactionation And Mixing Evaluation

Welcome to FRAME — a Bayesian stable isotope mixing model with a friendly graphical interface.

Easiest entry point: if you know a little Python but do not want to install software locally, open FRAME in Google Colab — it runs in the browser at no cost (direct link).

About

FRAME estimates the fractional contributions of multiple isotope sources to a mixture, with optional simultaneous estimation of isotopic fractionation progress (e.g. denitrification, evaporation, N₂O reduction). The core algorithm is a Markov-Chain Monte Carlo model (Metropolis-Hastings) implemented in Python.

Key capabilities:

1D, 2D and 3D stable isotope systems; arbitrary number of sources
Source isotope signatures defined either as Gaussian point estimates (stdev) or flat uniform ranges (spread) — likelihoods for uniform sources are computed via exact FFT convolution (v2.0+)
Custom model equations for any fractionation process (open-system, Rayleigh-type, equilibrium, etc.)
Selectable prior for auxiliary variables (uniform or log-uniform), configurable from the GUI or the Python API
Graphical interface and headless batch mode (Python script or Windows executable)
Google Colab — full MCMC demos in the browser (no installation); ideal if you know even a little Python

The scientific background and detailed case studies are published in:

Lewicki MP, Lewicka-Szczebak D, Skrzypek G (2022) FRAME — Monte Carlo model for evaluation of the stable isotope mixing and fractionation. PLOS ONE 17(11): e0277204.
https://doi.org/10.1371/journal.pone.0277204

Install

Try FRAME in Google Colab — no installation

If you have a Google account and basic Python familiarity, you can run FRAME entirely in your browser. There is nothing to download, configure, or compile — open the notebook, run the cells top to bottom, and you get the same numerical results and diagnostic plots as a local batch run.

The notebook docs/colab_demo.ipynb clones the repository for you inside Colab and handles dependencies automatically. It includes a plain 2-D mixing example, a fractionation run with selectable priors for the auxiliary variable r, tables of results, and inline figures.

Open the FRAME demo in Google Colab →

Latest release: v2.0

Platform	Download
Browser (recommended first try)	Open demo in Google Colab — Python notebook, zero install
Windows (GUI + batch)	Download EXE — v2.0
All platforms (source)	GitHub repository

For local source installation instructions see the README.

Quick start — graphical interface

The program works in five steps:

Step	Screenshot
1. Load data on your measured samples
2. Load isotopic signatures of considered sources
3. (Optional) Load auxiliary fractionation parameters	$screenshot loading fractionation$
4. Verify your loaded data
5. Run the model

Voilà — the simulation is running!

A full user guide with input file formats, model equation syntax and output interpretation is here.

The example input files are included with the release. Real-world datasets are available in input/real world examples.

Batch / scripting mode

FRAME can be run without the GUI — useful for processing many samples or automating analyses.

Windows (PowerShell) — using the pre-built executable:

.\FRAME_batch.exe data.csv sources.csv --aux_file frac.csv `
    --output_dir results --niter 500000 --burnout 200 --chain_length 500 `
    --plot_online False

With a log-uniform prior on the fractionation variable r:

.\FRAME_batch.exe data.csv sources.csv --aux_file frac.csv `
    --aux_prior_type loguniform --aux_r_min 0.001 --aux_r_max 1.0 `
    --output_dir results --plot_online False

All platforms — from source:

python run/run_batch.py data.csv sources.csv --aux_file frac.csv \
    --output_dir results --niter 500000 --chain_length 500 --plot_online False

Argument	Default	Description
`--aux_file`	(none)	Path to auxiliary parameters CSV
`--output_dir`	`output`	Directory for results
`--output_filenames`	(auto)	Custom tag for output file names
`--output_formats`	`pdf,png`	Comma-separated plot formats
`--niter`	`1000000`	Maximum MCMC iterations
`--burnout`	`100`	Burn-in steps
`--chain_length`	`500`	Accepted steps to record
`--plot_online`	`True`	Live plotting (`True`/`False`)
`--aux_prior_type`	`uniform`	Prior for `r`: `uniform` or `loguniform`
`--aux_r_min`	`0.0`	Lower bound of the `r` prior
`--aux_r_max`	`1.0`	Upper bound of the `r` prior

The same workflow (clone repo, configure paths, interpret outputs) is explained step by step in the Google Colab demo above — no local setup required.

Discussion and bugs

Questions / discussion: mailing list at groups.google.com/g/frame-isotopes
Bug reports: issue tracker at github.com/malewick/frame/issues

Attribution

Please cite FRAME in publications using:

Lewicki MP, Lewicka-Szczebak D, Skrzypek G (2022) FRAME — Monte Carlo model for evaluation of the stable isotope mixing and fractionation. PLoS ONE 17(11): e0277204. https://doi.org/10.1371/journal.pone.0277204

License

FRAME is GPL v3 licensed. Please cite our work when using it and consider contributing your changes back.

FRAME is provided free of charge and is distributed in the hope that it will be useful. This software is provided “as is” and without warranty. Use at your own risk.

Authors

Maciej Lewicki — malewick[at]cern.ch — malewick.web.cern.ch
Dominika Lewicka-Szczebak — dominika.lewicka-szczebak[at]uwr.edu.pl
Grzegorz Skrzypek — grzegorz.skrzypek[at]uwa.edu.au — gskrzypek.com