MANIC: Mass Analysis & Natural Isotope Correction

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.

---

Documentation

For Users

• Getting Started / User Guide - The primary manual. Step-by-step instructions for import, integration, and export.
• Understanding the Output - How to interpret the results exported in the excel workbook.
• Isotope Correct External Data - How to re-process results files without raw CDF data.

Technical Reference

• 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.
• 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 Incorperation & Carbon Enrichment - Derivation of the fractional carbon contribution formula.

---

Installation

Option 1: Standalone Installer (Recommended)

For most users, simply download the latest compiled executable. This requires no Python knowledge or external dependencies.

1. Navigate to the latest release page of this repository.
2. Click on the Assets drop-down.
3. Download the installer named MANIC_Setup.zip (either the Windows or Mac version).
4. Unzip the downloaded file.
5. 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.

Option 2: Running from Source

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:

1. Clone the repository:

   git clone [https://github.com/your-org/clone_pmanic.git](https://github.com/your-org/clone_pmanic.git)
   cd clone_pmanic

2. Run the application using the helper script:

   ./scripts/run.sh

   (Note: This script automatically handles dependency synchronization and environment setup.)

---

Support & Issues

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

Report a Bug or Request a Feature

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:

1. 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.”

2. Sign in to GitHub (or create a free account) if prompted. This helps us track and respond to your request.

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

4. Click Submit. We’ll review and follow up if we need more details.

---

Developer Instructions

This project uses modern Python tooling including uv for dependency management and PySide6 for the GUI.

Development Environment Setup

To set up your local environment for development:

# Install uv (if not installed)
pip install uv

# Sync dependencies from lockfile
uv sync

Running Tests

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

Building Executables

To compile the application into a standalone Windows executable (.exe) and installer:

1. Ensure you are on a Windows machine.
2. Run the build script:

scripts\build_windows.bat

3. Artifacts will be generated in the dist/ and Output/ directories.