petropandas

A pandas-accessor library for processing electron microprobe (EMPA) mineral analyses — convert oxide wt% to APFU, compute structural formulas, estimate Fe³⁺/Fe²⁺, calculate end-members, validate stoichiometry, and produce publication-ready plots.

Install

uv sync

Optional dependencies

uv sync --extra lab    # Jupyter notebook workflows
uv sync --extra tests  # running the test suite
uv sync --extra docs   # building the documentation

Contributors should instead run uv sync --dev, which installs all of the above plus ruff and pre-commit.

On Linux, pandas' clipboard I/O (pandas.read_clipboard() / DataFrame.to_clipboard()) needs a system-level clipboard utility — install xclip or xsel via your system package manager (e.g. sudo apt install xclip).

Quick start

from petropandas import pd, Grt
from petropandas.data import minerals as df
# minerals is a DataFrame of example analyses

Filter to oxide columns:

df.oxides()

Re-order columns in standard petrological order (SiO₂ first, volatiles last):

df.oxides.sorted()

Select rows by searching for "Garnet" in column "Mineral":

g = df.oxides.select("Garnet", on="Mineral")

Compute element APFU with Fe³⁺/Fe²⁺ splitting for garnet (12 oxygens):

g.mineral.apfu(Grt)

Site-allocated structural formula:

g.mineral.site_allocations(Grt)

End-member proportions:

g.mineral.end_members(Grt)

Validate analysis quality against ideal stoichiometry:

g.mineral.check_stoichiometry(Grt)

Returns a DataFrame of 0–1 scores per criterion (1 = perfect fit).

Supported minerals

* Chlorite uses 28-charge normalization (n_oxygens=14 effective). † Staurolite's 29.5 reflects typical partial vacancy at its divalent Y-site (crystallographic maximum is 30, across T=8/M=18/Y=4).

All 16 instances above are also registered in mdb (from petropandas import mdb), a small lookup registry:

from petropandas import mdb

list(mdb.all())  # every built-in Mineral instance
mdb.names  # ["Garnet", "GarnetFe3", "Feldspar", ...]
mdb.abbreviations  # ["Grt", "GrtFe3", "Fsp", ...]
mdb.by_name("garnet")  # Grt (case-insensitive)
mdb.by_abbreviation("GRT")  # Grt (case-insensitive)
repr(mdb)  # "Mineral database (16 minerals available)"

mdb only covers these 16 built-ins, not the hpxeos a-x phases below.

THERMOCALC activity-composition (a-x) solution models are available through the petropandas.hpxeos subpackage, covering three real THERMOCALC axfiles — hpxeos.metapelite, hpxeos.metabasite, hpxeos.igneous — each exposing ready-to-use TC_<abbreviation> instances (e.g. TC_g, TC_pl4tr) alongside their Phase classes:

from petropandas.hpxeos.metapelite import TC_g

df.mineral.apfu(TC_g)
df.mineral.site_allocations(TC_g)
df.mineral.variables(TC_g)
df.mineral.end_members(TC_g)
df.mineral.check_stoichiometry(TC_g)

Phase subclasses with order-disorder variables (e.g. Biotite Q, Augite Qfm/Qal) accept an optional order_parameters dict, passed through df.mineral.end_members(mineral, order_parameters={...}). df.mineral.variables(phase) returns the a-x pipeline's two intermediate stages — site fractions (e.g. Biotite's Fe, Mg, AlOct) followed by the derived compositional variables (x, y, z, m, Q, ...), in that column order — between site allocation and end-member proportions, for a Phase instance only (not plain Mineral instances, which have no site_fractions/variables methods); any order-disorder variable defaults to 0.0 (fully disordered) — call phase.variables(...) directly to supply order_parameters.

API reference

OxidesAccessor, MolesAccessor, CationsAccessor, and BulkAccessor share a common base with methods, all operating on the accessor's data in whatever petro_units it's currently in (no forced conversion) and tagging the result with that same unit — df.mineral does not have these:

OxidesAccessor (df.oxides)

MolesAccessor (df.moles)

CationsAccessor (df.cations)

All callable accessors auto-convert from the current petro_units attr. Chains work seamlessly: df.oxides().moles().oxides() roundtrips back to wt%. df.cations(n_oxygens=N).oxides() converts APFU back to oxide wt% (ratios preserved).

MineralAccessor (df.mineral)

BulkAccessor (df.bulk)

Series accessor (series.mineral)

Plotting

Three plot classes are available for visualising microprobe and end-member data:

from petropandas import ScatterPlot, TernaryPlot, ProfilePlot

ScatterPlot

X/y scatter plot where axes are pandas.eval() expressions over DataFrame columns.

s = ScatterPlot("Prp", "Sps+Grs")
s.add(garnet_df, label="Garnet 1")
s.add(other_df, label="Garnet 2")
fig, ax = s.render()

TernaryPlot

Ternary diagram built on plain matplotlib (no mpltern dependency). Axes are pandas.eval() expressions.

s = TernaryPlot("Prp", "Sps", "Grs")
s.add(garnet_df, label="Garnet 1")
fig, ax = s.render()

ProfilePlot

Line plot of DataFrame columns against their index, with optional dual y-axes for columns spanning different value scales.

s = ProfilePlot(secondary_columns=["Alm"])
s.add(profile_df, label="Profile 1")
fig, ax = s.render()

All three inherit from BasePlot and share add(), render(), show(), and savefig() methods.

Configuration

Global defaults are stored in the ppconfig singleton (petropandas.PPConfig):

from petropandas import ppconfig

ppconfig.default_db = "ig"
ppconfig.default_system = "KFMASH"
ppconfig.reset()  # restore all defaults

Mutations are global and persist for the session.

Stoichiometry checking

df.mineral.check_stoichiometry(mineral) returns a DataFrame scored 0–1 for each criterion:

Inapplicable criteria are dropped (all-NaN columns removed).

df.mineral.stoichiometry_quality(mineral) condenses three of those criteria — cation_deviation, site_vacancies, leftover_cations — into a single 0–1 score (their mean) per analysis, as a pandas.Series. NaN if the mineral doesn't define ideal_cations (so cation_deviation is NaN).

Fe³⁺/Fe²⁺ estimation methods

• Droop (1987): method="droop" — charge-balance approach on total cations
• Schumacher (1991): method="schumacher" — oxygen-excess approach
• FeO→Fe₂O₃ conversion: Epidote and Titanite internally convert all FeO to Fe₂O₃ before normalisation
• Spinel: Merges Fe₂O₃ into FeO before Droop split (inverse spinel model)
• df.oxides.split_valence(): General-purpose valence splitting on any element
• df.oxides.oxidize(o_excess): THERMOCALC excess-oxygen convention (Fe₂O₃ = 2 × o_excess)

Conventions

• Ion column names use periodictable notation: Fe{2+}, Fe{3+}, Si{4+}, Na{+}
• Structural formula columns: (site, cation) tuples (e.g. ("Z", "Si{4+}"), ("X", "Fe{2+}"))
• Unit tracking via df.attrs["petro_units"]: "wt%" (default) → "moles" → "apfu"
• Callable accessors (df.oxides(), df.moles(), df.cations()) auto-convert from current units
• Mineral instances are configuration objects — stateless, reusable
• str(mineral) returns mineral.abbreviation (e.g. "Grt", matching the instance variable it's exported under); repr(mineral) returns f"{name}[{abbreviation}] cations={ideal_cations} n_oxygens={n_oxygens}" (e.g. "Garnet[Grt] cations=8 n_oxygens=12")
• Internal modules are underscore-prefixed (_calc.py, _core.py, _minerals.py, _plotting.py)