ZooMZ Browser App for doing ZooMS collagen analysis (React + Plotly)

Zooarchaeology by mass spectrometry, commonly referred to by the abbreviation ZooMS, is a scientific method that identifies animal species by means of characteristic peptide sequences in the protein collagen.

This app supports:

• Upload .mzML / .mzXML files (batch)
• Interactive Plotly spectrum (zoom/pan)
• Peak picking
• Matching against Speciescan-style reference DB CSVs (one row per species/taxon; marker m/z in columns)
• Automatic contaminant search from public/reference_dbs/contaminants_list.csv
• Per-sample confidence using decoy permutation scoring with configurable decoy settings
• Batch Excel export with QC summary, marker matches, and contaminants
• Confidence labels (High/Medium/Low) in results tables
• Note: expected input files are single-scan MALDI MS (multi-scan mzML is not supported)
• See Settings and QC explanations: Settings_QC.md

How to run analyses

• Single sample Upload one mzML/mzXML and run once to inspect the spectrum and results interactively.
• Small batch (uploaded files) Multi-select uploads and run; results append as multiple rows in the output Excel.
• Folder processing Select a local folder containing many mzML/mzXML files (for example, Zenodo datasets). By default the app processes every spectrum found and appends one row per file to the output Excel. In SpecieScan benchmark mode, folder runs can instead group technical replicates by sample ID prefix before analysis. Errors are logged per-file and do not stop the run.

Folder processing is intended for high-throughput validation runs (hundreds/thousands of spectra).

Decoy confidence thresholds used in the app:

• Permutation gate: qSample > 0.05 => Rejected (not acceptable)
• qSample is a per-spectrum decoy permutation p-value, not a batch-level FDR.
• Decoy gap is the difference between the top real score and the best decoy score; larger gaps indicate stronger separation, while zero/negative gaps suggest weak confidence.

Confidence estimation

Confidence levels reflect separation from random matches and from competing taxa, not a single statistical probability.

Procedure summary:

• Permutation control: reject if qSample > 0.05
• Separation from decoys: use best_score / best_decoy_score (or best_score - best_decoy_score when decoy scores are very small)
• Taxonomic discrimination: down-weight when top and second-best taxa are very close
• Evidence sufficiency (optional): down-weight if very few markers support the call

Ratio thresholds (when best_decoy_score >= 0.01):

• High: ratio >= 2.5 and best_score >= 0.03
• Medium: ratio >= 1.8 and best_score >= 0.02
• Low: ratio >= 1.3
• Rejected: otherwise

Gap thresholds (when best_decoy_score < 0.01):

• High: decoy_gap >= 0.15
• Medium: 0.10 <= decoy_gap < 0.15
• Low: 0.05 <= decoy_gap < 0.10
• Rejected: decoy_gap < 0.05

Override:

• If qSample <= 0.01 and decoy_gap >= 0.15, confidence is forced to High. Strong separation from decoys (low q and large decoy gap) is decisive; close scores among top taxa may be flagged as ambiguity but will not demote a strongly supported identification.

Confidence Interpretation High Strongly above decoys and clearly separated from alternative taxa Medium Above decoys but limited separation or moderate ambiguity Low Statistically admissible but weak separation or sparse evidence Rejected Not convincingly above random matches

Confidence labels are intended as interpretive guidance, not exact probabilities. The decoy qSample value is a per-spectrum permutation p-value, not a dataset-wide FDR estimate.

Run

This app is hosted on Github Pages https://arthuc01.github.io/ZooMZ/

npm install
npm run dev

Node validation

The browser engine can now be validated directly under Node without going through the older Python proxy scripts.

npm run validate:node -- --run A

Useful variants:

• npm run validate:node -- --run A --limit 20
• npm run validate:node -- --run A --sample DC12745

This command compiles the shared engine to validation/.node-build/ and runs validation/scripts/validate_ts_engine.mjs, writing results to validation/outputs/real_spectra/trackB_ts_runA_results.csv.

To run the Track B comparator with the TypeScript SpeciesCan-style preprocessing path and exact SpecieScan asymmetric scoring windows, pass --mode exact. That now uses the dedicated speciescan_exact replicate workflow in the shared engine, then writes validation/outputs/real_spectra/trackB_ts_exact_runA_results.csv.

For the SpecieScan-aligned scoring-only path on the exported R peaks, run npm run validate:rpeaks:ts. That scores the R-preprocessed peak CSVs from validation/outputs/r_preprocessed_peaks/ with the exact SpecieScan windowing rules and writes validation/outputs/real_spectra/trackR_ts_speciescan_results.csv.

To compare the TypeScript SpeciesCan-style preprocessing directly against those exported R peak CSVs, run npm run validate:preprocess:ts. That writes validation/outputs/real_spectra/trackR_ts_preprocessing_parity.csv with per-sample peak-list precision/recall/F1 against the R reference peaks.

For a diagnostic comparison that uses the validated R-preprocessed comparator whenever it is available, and falls back to the raw exact comparator only for samples missing an R result, run npm run validate:exact:consensus. It writes validation/outputs/real_spectra/trackB_ts_exact_consensus_results.csv.

SpeciesScan validation notes and the score comparison plot are documented in validation/README.md.

Deploy (GitHub Pages)

This repo is configured to deploy on pushes to main via GitHub Actions. If your repository name is not ZooMZ, update the base path in vite.config.ts to /<your-repo>/.

Reference DBs

Folder: public/reference_dbs/

• manifest.json lists selectable databases + contaminants file
• Populate the folder with Speciescan CSVs and update the manifest if you add/remove files.

SpecieScan

Emese I Végh, Katerina Douka, SpecieScan: semi-automated taxonomic identification of bone collagen peptides from MALDI-ToF-MS, Bioinformatics, Volume 40, Issue 3, March 2024, btae054, https://doi.org/10.1093/bioinformatics/btae054

Xenarthrans reference DB: https://pubs.acs.org/doi/10.1021/acs.jproteome.5c00636 Note: only MALDI-observable markers are included in the Xenarthrans list.

In-silico marker database (experimental)

In addition to empirically validated ZooMS marker databases, ZooMZ optionally supports an experimental in-silico–derived collagen marker database. This should be used for exploratory analysis ONLY.

This database is generated by downloading COL1A1 and COL1A2 protein sequences from UniProt, performing an in-silico tryptic digest, calculating monoisotopic peptide masses, and filtering peptides to the typical ZooMS mass range. Candidate markers are then selected based on their taxonomic presence patterns (informativeness) across species or higher taxonomic groupings.

The in-silico database is intended for exploratory analysis, method development, and assessing potential taxonomic resolution, and should not be interpreted as a replacement for empirically validated ZooMS markers. Marker presence reflects sequence-derived predictions rather than confirmed MALDI detectability, and results should therefore be interpreted with appropriate caution.

Users can select the in-silico database explicitly via the database selector in the application interface. By default, ZooMZ continues to prioritise experimentally established ZooMS reference databases.