mokume is a comprehensive proteomics quantification toolkit: it turns peptide-level mass-spectrometry intensities into protein expression matrices, with built-in normalization, imputation, batch correction, and differential expression. It supports iBAQ, TopN, MaxLFQ, and DirectLFQ quantification, is designed for the quantms ecosystem, and works equally well as a Python library and a standalone command-line tool.
mokume is an evolution of ibaqpy, extended well beyond iBAQ to a broader range of quantification, normalization, and differential-expression methods.
Mokume-gane (木目金, "wood-grain metal") is a Japanese metalworking technique that fuses layers of different metals into a single piece with a distinctive flowing pattern. mokume does the same with proteomics data: it melds many noisy, overlapping peptide intensities into one coherent protein expression profile.
This repository ships two implementations of mokume in one place, following the multi-language monorepo convention used by projects such as Apache Arrow (one top-level folder per language):
mokume/
├── docs/ # one shared documentation site (mkdocs)
├── python/ # the pure-Python implementation — the `mokume` package
└── rust/ # a Rust compute kernel: a standalone CLI binary + a maturin wheel
python/— the pure-Pythonmokumepackage (pip install mokume). The reference implementation: easiest to read, extend, and script against.rust/— a Rust compute kernel that runs the same methods much faster, shipped as a standalone CLI binary and an in-processmokume._mokumewheel.
Both implement the same toolkit; the Rust kernel is checked against captured outputs of the Python reference by a golden-test suite.
The Python package is the recommended way to get started:
pip install mokumeThe base install is lightweight and covers the core LFQ workflow — MaxLFQ, Top3/TopN, feature/peptide normalization, and parquet/SDRF I/O. Features that pull heavier dependencies are opt-in via extras (each raises a clear install hint if used without it):
pip install "mokume[ibaq]" # FASTA digestion + iBAQ / piBAQ / TPA absolute quant
pip install "mokume[analysis]" # differential expression, FDR, DEqMS, LOESS/RLR
pip install "mokume[imputation]" # KNN / missForest imputation
pip install "mokume[directlfq]" # DirectLFQ backend for MaxLFQ
pip install "mokume[plotting]" # QC reports and visualizations
pip install "mokume[tissuemap]" # tissue-specificity pipeline + AnnData export
pip install "mokume[agentic]" # AI-assisted DE optimization (DeepSeek / OpenAI)
pip install "mokume[all]" # everything (all optional dependencies)For the Rust accelerated build — a standalone CLI binary that needs no
Python runtime, running the same compute kernel — build from the rust/
workspace:
cargo install --path rust/crates/mokume-cli # standalone `mokume` CLI binaryA conda environment and build-from-source instructions are in docs/installation.md.
Run the full pipeline from a quantms feature table to a protein matrix:
mokume features2proteins \
--parquet features.parquet \
--sdrf samples.sdrf.tsv \
--quant-method maxlfq \
--output proteins.csvAdd differential expression by passing --de with one or more contrasts:
mokume features2proteins \
--parquet features.parquet \
--sdrf samples.sdrf.tsv \
--quant-method maxlfq \
--de --de-contrasts "Treatment-Control" \
--output proteins.csvThe pipeline above is driven through this CLI, shared by both builds. For scripting, the pure-Python package exposes component APIs — for example, quantifying a peptide table:
import pandas as pd
from mokume.quantification import TopNQuantification
# columns: ProteinName, PeptideCanonical, NormIntensity, SampleID
peptides = pd.read_csv("peptides.csv")
# TopN protein quantification; MaxLFQ / iBAQ / DirectLFQ share the .quantify interface
proteins = TopNQuantification(n=3).quantify(peptides)Normalization, imputation, and differential expression have the same
component-style API (see below and the
Python API reference). The Rust wheel
additionally exposes an in-process mokume.features2proteins(...) binding that
runs the whole pipeline with no subprocess.
| Command | What it does |
|---|---|
features2proteins |
Full pipeline: feature table → protein quantification matrix |
features2peptides |
Aggregate features to peptide-level intensities |
peptides2protein |
Roll peptide intensities up to protein quantities |
correct-batches |
Standalone ComBat batch correction (with AnnData export) |
features2proteins runs these stages in order:
- Quantification:
maxlfq,directlfq,ibaq,top3/topn,sum(alsomedian,ratio,abd,intensity,spectral_count). iBAQ requires a FASTA; TopN, MaxLFQ, and Sum do not. - Normalization: run-level and sample-level options including
median,quantile,rlr, andloess. - Imputation: a wide set of imputers, from simple (
mindet,knn) to model-based (qrilc,impseq). - Batch correction: native ComBat (parametric, non-parametric, and covariate-aware) that removes technical batch effects while preserving biological signal.
- Differential expression:
limma,deqms,rots,limrots,proda, and an ensemble (see below).
The full catalog lives in the user guide and the method concepts pages.
mokume ships several differential-expression methods behind one interface, with Benjamini-Hochberg (default) or IHW FDR control:
- LimROTS — limma moderation with a ROTS bootstrap-optimized statistic; the best sensitivity on MaxLFQ data.
- DEqMS — peptide-count-weighted eBayes; controls false positives better on noisier DirectLFQ data.
- proDA — probabilistic dropout-aware DE that models missing values as informative, not random.
- limma, ROTS, and a consensus ensemble are also wired.
from mokume.analysis import DifferentialExpression
de = DifferentialExpression(method="limrots")
results = de.run_comparisons(
protein_df,
sample_to_condition,
contrasts=[("Treatment", "Control")],
)
# results -> {"Treatment-Control": DataFrame with log2FC, pvalue, adj_pvalue, ...}LimROTS and ROTS report their own permutation-based FDR, so requesting IHW does not overwrite it. See docs/concepts/differential-expression.md.
mokume can tune its own differential-expression configuration with an
OpenAI-compatible LLM (DeepSeek by default) layered on top of deterministic
rule-based heuristics — profile the data, propose a method/filter/normalization
configuration, and iterate. It degrades gracefully to rule-based only when no
API key is set. Install with pip install "mokume[agentic]"; see
docs/ for setup.
mokume's methods exist in two builds that produce the same results:
- the pure-Python
mokumepackage — the reference implementation, ideal for reading, extending, and interactive analysis; and - a Rust compute kernel that runs the heavy lifting much faster, shipped as a
standalone CLI binary (
mokume, no Python runtime needed) and an in-processmokume._mokumewheel.
The CLI binary and the wheel share one compiled kernel, so a result computed either way is identical. For the full design, see docs/architecture.md.
A full run on real data: PXD030304, a 949-cell-line proteomic panel
(178 M feature rows). mokume's tissue-proteome pipeline (mokume.tissuemap)
quantifies the cell lines, scores AdaTiSS tissue specificity, embeds the
samples, and finds tissue markers — every figure below is rendered by mokume's
own visualization:
Tissue atlas — the 949 cell-line proteomes embedded and grouped by their tissue
of origin (mokume.tissuemap).
t-SNE of the same proteomes, each panel coloured by a top tissue-marker's expression.
AdaTiSS tissue-specificity score distribution (with the GMM-fitted specific / enriched / housekeeping thresholds) and the tissue-specific protein count per tissue. See docs/periphery/tissuemap.md.
- Documentation home
- Quick start
- Installation
- User guide · Method concepts
- CLI vs. wheel · Architecture
- Benchmarks
mokume is part of the quantms ecosystem and evolves ibaqpy. Until a dedicated mokume paper is available, please cite ibaqpy and quantms — see CITATION.cff and those repositories for current citation details and DOIs.
mokume is developed by the bigbio community as part of the quantms ecosystem. Contributions are welcome; see the community guide for development setup and guidelines.
Licensed under the MIT License.