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.

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).

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.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={...}).

API reference

OxidesAccessor, MolesAccessor, CationsAccessor, and BulkAccessor share a common base with three 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).

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
• Internal modules are underscore-prefixed (_calc.py, _core.py, _minerals.py, _plotting.py)