MANIC is a desktop application for the processing and analysis of isotopically labelled mass spectrometry data (GC-MS).
Built with Python and PySide6, it serves as a successor to the legacy MATLAB MANIC application. It provides a workflow for extracting ion chromatograms, correcting for natural isotope abundance, validating peak quality, and calculating absolute metabolite concentrations.
If MANIC is useful in your lab, star the FrancisCrickInstitute/pMANIC repository on GitHub. Stars are a public metric of usefulness and help justify the resources needed for further development.
MANIC asks you to choose a mode when an analysis starts. The choice is fixed for that session so the same ion signals cannot accidentally be interpreted using two different scientific models. Switch modes with File → New Analysis Session… (this clears the current session).
- Labelled is for stable-isotope tracing. It extracts consecutive M+0 to M+n channels and uses natural-abundance correction and label-derived outputs.
- Unlabelled is for targeted profiling. It integrates one quantifier ion (Q ion) for the reported response and uses qualifier ions, retention time, and reference ion ratios as identity-supporting checks. It does not apply isotopologue correction or calculate label incorporation.
Full unlabelled documentation (compound-list format, identity QC, UI guides, export sheets, and scientific rationale) is in Unlabelled Targeted Analysis.
⚠️ The Corrected Values sheet changes in 5.0. Ratio sheets move by less than half a percentage point; the largest change we found was 45.3% → 45.8%. Calibrated nmol amounts move by under 2.5%.
Two processing changes in 5.0 alter exported numbers. Both are measured below on two real lab datasets.
- Raw Values. Unchanged by the correction fix. Changed slightly by the baseline clamp (next section). On dataset_1, 11.8% of channel areas moved, by a median of 0.12%, and 90% of those that moved did so by under 1.9%.
- Isotope Ratio, % Label Incorporation, % Carbons Labelled. Move by less than half a percentage point. The largest change found anywhere was an Isotope Ratio of 45.30% becoming 45.78%. Your 4.x results stand.
- Abundances (nmol) for compounds calibrated against MM files. Change by under 2.5%, and typically by about 0.1%. Your 4.x results stand.
- Abundances for compounds with no MM-file calibration. Drop by 15 to 35%. 5.0 labels these columns Relative instead of nmol, because they never were absolute amounts.
- Corrected Values. Drop by roughly 15 to 40%. Do not compare a 4.x Corrected Values sheet with a 5.0 one. Reprocess the older data in 5.0 first.
Natural isotope correction. This works out how much of each isotopologue peak is real label and how much is the natural ¹³C background. MANIC 4.x, following the original MATLAB code, did that calculation correctly and then applied one extra step: it divided every channel by a number slightly below one. That extra step had no scientific basis. It inflated every corrected value, by more for bigger and more heavily derivatised molecules. MANIC 5.0 removes it.
Because the inflation was almost the same for every channel of a compound (the channels of one compound differed by at most 3.3%), it cancelled out wherever channels are compared with each other, which is what every ratio sheet does. It also cancelled out in calibrated abundances, because the response factor (MRRF) is computed from the same inflated values and inflates by the same amount. The only place it did not cancel is a compound whose response factor could not be computed and was assumed to be 1.0. Those abundances carried the full inflation.
Baseline clamp. When a compound has baseline correction on, MANIC fits a straight line under the peak and subtracts the area beneath it. In 4.x, if that line dipped below zero, the negative area was subtracted too, which added area to the peak. 5.0 subtracts only the part of the line above zero. A baseline can therefore only ever reduce a peak. This affects Raw Values and everything computed from them.
Before releasing 5.0 we took two real lab datasets and processed them from the raw CDF files twice, once with 5.0 and once with the 4.x correction swapped in, then compared every number on every sheet.
| Dataset | Compounds | Samples | EICs |
|---|---|---|---|
| dataset_1 | 17 | 39 | 663 |
| dataset_2 | 97 | 35 | 3395 |
First we confirmed the two correction versions really differ only by that one extra division. Across 585 sample and compound pairs, the 4.x number equalled the 5.0 number divided by the extra factor to ten decimal places (relative deviation 3.6e-10), all the way through deconvolution, baseline correction and integration. Then we measured how much each exported sheet moved.
Sheets that report amounts. Change relative to the 4.x value.
| Sheet | dataset_1 (522 pairs) | dataset_2 (2662 pairs) |
|---|---|---|
| Corrected Values | median 18.1%, max 26.2% | median 26.4%, max 39.1% |
| Abundances, MRRF from MM files | median 0.07%, max 2.5% | median 0.13%, max 2.1% |
| Abundances, MRRF assumed 1.0 | none in this dataset | 15% to 34% (4 compounds) |
Medians are typical values; maxima are the worst case found. The assumed-MRRF row rests on four compounds in one dataset, so treat its range as indicative.
Sheets that report percentages. The largest single change we found, shown as the 4.x value becoming the 5.0 value.
| Sheet | dataset_1 | dataset_2 |
|---|---|---|
| Isotope Ratio | 84.20% → 83.90% | 45.30% → 45.78% |
| % Label Incorporation | 15.80% → 16.10% | 44.15% → 44.62% |
| % Carbons Labelled | 43.84% → 44.06% | 42.34% → 42.82% |
Every other value on these three sheets moved less than the worst case shown.
The baseline clamp was measured on dataset_1 alone. 1325 of 11271 channel areas changed (11.8%), by a median of 0.12%; 90% of the changed areas moved by under 1.87%. A few areas changed by 100%, where the old negative baseline had been the whole of the reported area.
The size of the old correction inflation depends on how big and how derivatised the molecule is, not on how many positions can carry label. Across 111 labelled compounds it correlated +0.65 with total atom count and −0.23 with labelled atoms. Glycine (2 labelled carbons) was inflated 1.44×; Picolinate (6 labelled carbons) only 1.19×.
Every exported changelog records the MANIC version that produced it, so you can always tell which processing a workbook used. The mathematics is in Natural Isotope Correction and Baseline Correction.
- Quick Start - Mode, compound list, CDF folder, review, and export.
- Getting Started / User Guide - The primary manual. Step-by-step instructions for import, integration, and export.
- Unlabelled Targeted Analysis - Q and qualifier ions, compound lists, identity QC, review UI, and unlabelled exports.
- Understanding the Output - How to interpret the results exported in the excel workbook.
- Process External Data - How to re-process results files without raw CDF data.
- Natural Isotope Correction - Explanation of the matrix-based correction algorithm.
- Integration Methods - Time-based vs. Legacy Unit-spacing integration.
- Baseline Correction - Linear baseline subtraction algorithm.
- Chromatographic Peak Deconvolution - Separating overlapping peaks before integration (per-compound settings, fit models, noise gate).
- Abundance Calculation - Metabolite Response Ratio Factor calculations.
- Peak Validation - Criteria for automatic red/green quality indicators.
- Mass Tolerance - Details on the asymmetric mass binning logic.
- Label Incorporation and Carbon Enrichment - Derivation of the fractional carbon contribution formula.
For most users, simply download the latest compiled executable. This requires no Python knowledge or external dependencies.
- Navigate to the latest release page of this repository.
- Click on the
Assetsdrop-down. - Download the installer named
MANIC_Setup.zip(either the Windows or Mac version). - Unzip the downloaded file.
- Run the installer and follow the on-screen prompts. When you run this for the first time on a Mac, you might have to go into privacy settings and allow the application to run.
If you prefer to run the raw Python code, use the provided execution script.
Prerequisites:
- Python 3.10 or higher
- Git
- uv (Recommended for dependency management)
Steps:
-
Clone the repository:
git clone https://github.com/FrancisCrickInstitute/pMANIC.git cd pMANIC -
Run the application using the helper script:
./scripts/run.sh
(Note: This script automatically handles dependency synchronization and environment setup.)
If something doesn't work as expected or you have an idea to make MANIC better, you can let us know. The easiest way is to use our simple forms on GitHub. No technical knowledge is required.
Please first check if you bug or issue has already been reported by visiting the Issues tab on the GitHub repository. If it has not been reported, follow these steps:
-
Click one of the links below:
- Report a bug: Open the Bug Report form
- Request a feature: Open the Feature Request form
- If those links don’t work, go to the Issues tab and click New issue. Then choose either “Bug Report” or “Feature Request.”
-
Sign in to GitHub (or create a free account) if prompted. This helps us track and respond to your request.
-
Fill out the form:
- For bugs:
- What happened (and what you expected)
- Steps to reproduce (what you clicked or did)
- Any error messages shown
- Screenshots (optional but helpful)
- Your operating system (Windows/Mac) and MANIC version
- For feature requests:
- What you’d like MANIC to do
- Why it’s useful (your workflow or problem it solves)
- Any examples or similar tools you’ve seen
- For bugs:
-
Click Submit. We’ll review and follow up if we need more details.
This project uses modern Python tooling including uv for dependency management and PySide6 for the GUI.
To set up your local environment for development:
# Install uv (if not installed)
pip install uv
# Sync dependencies from lockfile
uv syncbench/history.tsv records how long each benchmarked action took, by commit and machine. uv run python scripts/record_bench.py prints it as a table. bench/README.md explains how to record a run.
The project maintains a test suite covering:
- Mathematical Correctness: Verifies mass binning, integration algorithms, and natural abundance correction logic against standard scientific principles and legacy MATLAB behavior.
- Data Integrity: Ensures accurate data extraction from CDF files, efficient batch processing, and correct database storage.
- System Robustness: Tests edge cases such as missing metadata, zero-width integration windows, and zero-intensity signals.
- UI Logic: Validates number formatting, auto-regeneration triggers, and peak quality validation logic.
# Run all tests using the provided script
./scripts/tests.shDevelopers: the performance suite lives in bench/ and is documented in bench/README.md.
Every number MANIC exports for two synthetic datasets is recorded in bench/reference/, and CI fails when the code no longer reproduces them. If your change is meant to alter results, run uv run python bench/reference.py update --pr <number> --why "<one sentence>" and commit what it writes. bench/reference/HISTORY.md is the list of every pull request that changed a result. See bench/README.md.
To attach installers to a GitHub Release from any machine, follow
releases/README.md. That path uses GitHub Actions
(Build Windows installer and Build macOS installer) and does not need
Windows or a Mac locally.
To compile on your own machine instead:
Windows. Run scripts\build_windows.bat on a Windows computer with Inno
Setup. The installer lands in dist\MANIC-Setup.exe.
macOS. Run scripts/build_macos.sh on a Mac. Install create-dmg with
Homebrew if you want the styled disk image. The app lands in dist/MANIC.app.