mars-ms 0.1.3__tar.gz

mars_ms-0.1.3/.agent/workflows/agents.md

@@ -0,0 +1,51 @@
+---
+description: How to run tests and linting for the mars project
+---
+
+# Mars Development Workflow
+
+## Running Tests
+// turbo
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+pytest tests/ -v
+```
+
+## Running Linter (Ruff)
+// turbo
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+ruff check mars/
+```
+
+## Auto-fix Linter Issues
+// turbo
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+ruff check mars/ --fix
+```
+
+## Running Full CI Check
+// turbo
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+ruff check mars/ && pytest tests/ -v
+```
+
+## Running Calibration on Example Data
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+mars calibrate \
+  --mzml "example-data/Ste-2024-12-02_HeLa_20msIIT_GPFDIA_*.mzML" \
+  --prism-csv example-data/Stellar-HeLa-GPF-PRISM.csv \
+  --tolerance 0.3 \
+  --min-intensity 500 \
+  --output-dir example-data/output/
+```
+
+## Installing in Development Mode
+// turbo
+```bash
+cd /home/maccoss/GitHub-Repo/maccoss/mars
+pip install -e .
+```

mars_ms-0.1.3/.github/dependabot.yml

@@ -0,0 +1,30 @@
+# Dependabot configuration for automated dependency updates
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+
+version: 2
+updates:
+  # Python dependencies (pip)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+    labels:
+      - "dependencies"
+      - "python"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "github-actions"

mars_ms-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mars-ms
+    permissions:
+      id-token: write  # Required for trusted publishing
+    
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mars_ms-0.1.3/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+      
+      - name: Lint with ruff
+        run: ruff check mars/

mars_ms-0.1.3/.gitignore

@@ -0,0 +1,90 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE settings
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Mac
+.DS_Store
+
+# Project-specific
+example-data/
+example-astral-data/

mars_ms-0.1.3/CLAUDE.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+This file provides context and instructions for AI agents working on the Mars repository.
+
+## Repository Overview
+
+Mars (Mass Accuracy Recalibration System) is a tool for calibrating DIA mass spectrometry data from the Thermo Stellar instrument. It uses XGBoost to learn m/z corrections from spectral library matches.
+
+## Continuous Integration (CI/CD)
+
+The repository uses GitHub Actions for CI/CD, defined in `.github/workflows/`.
+
+### Workflows
+
+1.  **Tests (`tests.yml`)**
+    *   **Triggers:** Push to `main`, Pull Requests to `main`.
+    *   **Actions:**
+        *   Sets up Python 3.10, 3.11, 3.12.
+        *   Installs dependencies with `pip install -e ".[dev]"`.
+        *   Runs tests using `pytest tests/ -v --tb=short`.
+        *   Runs linting with `ruff check mars/`.
+
+2.  **Publish to PyPI (`publish.yml`)**
+    *   **Triggers:** Release published.
+    *   **Actions:**
+        *   Builds the package (`python -m build`).
+        *   Publishes to PyPI using Trusted Publishing (OIDC).
+        *   Requires the tag (e.g., `v0.1.0`) to match the release.
+
+## Common Development Tasks
+
+*   **Install for dev:** `pip install -e ".[dev]"`
+*   **Run tests:** `pytest tests/`
+*   **Lint:** `ruff check .`
+*   **Build package:** `python -m build`
+
+## Release Notes
+
+When making bug fixes or improvements during development:
+
+*   **Update the current release notes:** Add any fixes or changes to the current version's release notes file in `release-notes/` (e.g., `RELEASE_NOTES_v0.1.3.md`).
+*   **Be specific:** Document what was fixed and why.
+*   **Group related changes:** Use appropriate sections (Bug Fixes, Changes, New Features, etc.).
+
+## Style Guidelines
+
+*   **No Emojis:** Do not use emojis in any output, documentation, source code comments, or Jupyter notebooks. Keep all text professional and plain.

mars_ms-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike MacCoss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mars_ms-0.1.3/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: mars-ms
+Version: 0.1.3
+Summary: Mass Accuracy Recalibration System
+Author-email: MacCoss Lab <maccoss@uw.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/maccoss/mars
+Project-URL: Repository, https://github.com/maccoss/mars
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyteomics>=4.6
+Requires-Dist: psims>=1.3
+Requires-Dist: xgboost>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.12
+Requires-Dist: click>=8.0
+Requires-Dist: tqdm>=4.65
+Requires-Dist: lxml>=4.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# MARS: Mass Accuracy Recalibration System
+
+[![PyPI version](https://img.shields.io/pypi/v/mars-ms.svg)](https://pypi.org/project/mars-ms/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mars-ms.svg)](https://pypi.org/project/mars-ms/)
+[![License](https://img.shields.io/pypi/l/mars-ms.svg)](https://github.com/maccoss/mars/blob/main/LICENSE)
+
+Mass recalibration tool for DIA mass spectrometry data from the ThermoFisher Stellar.
+
+## Overview
+
+Mars learns m/z calibration corrections from spectral library fragment matches. The XGBoost model accounts for:
+
+- **Fragment m/z**: Mass-dependent calibration bias
+- **Peak intensity**: Higher intensity peaks provide more reliable calibration
+- **Absolute time**: Calibration drift over the acquisition run
+- **Spectrum TIC**: Space charge effects from high ion current
+- **Ion injection time**: Signal accumulation duration effects
+- **Precursor m/z**: DIA isolation window-specific effects
+- **RF temperatures**: Thermal effects from RF amplifier (RFA2) and electronics (RFC2)
+
+## How It Works
+
+1. **Fragment matching**: For each DIA MS2 spectrum, Mars finds library peptides where:
+   - The precursor m/z falls within the DIA isolation window
+   - The spectrum RT is within the peptide's elution window
+
+2. **Peak selection**: For each expected fragment, Mars selects the **most intense** peak within the m/z tolerance (not the closest), filtering for minimum intensity
+
+3. **Model training**: Each matched fragment becomes a training point with up to 16 features (see [Model Features](#model-features)) and target: `delta_mz`
+
+4. **Calibration**: The trained model predicts m/z corrections for all peaks in the mzML
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install mars-ms
+```
+
+### From source
+
+```bash
+git clone https://github.com/maccoss/mars.git
+cd mars
+pip install -e .
+```
+
+**Requirements**: Python 3.10+, pyteomics, xgboost, numpy, pandas, matplotlib, seaborn, click
+
+## Usage
+
+### With PRISM CSV (Recommended)
+
+Use a CSV file created using this [Skyline report](Skyline-PRISM-Report/Skyline-PRISM.skyr) for accurate RT windows:
+
+```bash
+mars calibrate \
+  --mzml data.mzML \
+  --prism-csv prism_report.csv \
+  --tolerance 0.2 \
+  --min-intensity 500 \
+  --max-isolation-window 5.0 \
+  --output-dir output/
+```
+
+### Basic Usage
+
+```bash
+mars calibrate --mzml data.mzML --library library.blib --output-dir output/
+```
+
+### Batch Processing
+
+```bash
+# Multiple files with wildcard
+mars calibrate --mzml "*.mzML" --library library.blib --output-dir output/
+
+# All files in directory
+mars calibrate --mzml-dir /path/to/data/ --library library.blib --output-dir output/
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mzml` | - | Path to mzML file or glob pattern |
+| `--mzml-dir` | - | Directory containing mzML files |
+| `--library` | - | Path to blib spectral library (ignored if using PRISM Skyline Report) |
+| `--prism-csv` | - | PRISM Skyline CSV with Start/End Time columns |
+| `--tolerance` | 0.7 | m/z tolerance for matching (Th), ignored if `--tolerance-ppm` is set |
+| `--tolerance-ppm` | - | m/z tolerance for matching in ppm (e.g., 10 for Astral), overrides `--tolerance` |
+| `--min-intensity` | 500 | Minimum peak intensity for matching |
+| `--max-isolation-window` | - | Maximum isolation window width (m/z) to include |
+| `--temperature-dir` | - | Directory with RF temperature CSV files |
+| `--output-dir` | `.` | Output directory |
+| `--model-path` | - | Path to save/load calibration model |
+| `--no-recalibrate` | - | Only train model, don't write mzML |
+
+## RT Window Behavior
+
+- **With `--prism-csv`**: Uses exact `Start Time` and `End Time` from Skyline
+- **Without `--prism-csv`**: Uses ±5 seconds around the blib library RT
+
+## Isolation Window Filtering
+
+Some DIA methods use wide isolation windows (e.g., 20-30 m/z) that may reduce calibration accuracy. Use `--max-isolation-window` to exclude these:
+
+```bash
+# Exclude windows wider than 5 m/z
+mars calibrate --mzml data.mzML --prism-csv report.csv --max-isolation-window 5.0
+```
+
+This filters spectra during both model training and mzML recalibration. Typical narrow DIA windows (~1 m/z) are retained.
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `{input}-mars.mzML` | Recalibrated mzML file |
+| `mars_model.pkl` | Trained XGBoost calibration model |
+| `mars_qc_histogram.png` | Delta m/z distribution (before/after) |
+| `mars_qc_heatmap.png` | 2D heatmap (RT × m/z, color = delta) |
+| `mars_qc_intensity_vs_error.png` | Intensity vs mass error hexbin |
+| `mars_qc_rt_vs_error.png` | RT vs mass error hexbin |
+| `mars_qc_mz_vs_error.png` | Fragment m/z vs mass error hexbin |
+| `mars_qc_tic_vs_error.png` | TIC vs mass error hexbin |
+| `mars_qc_injection_time_vs_error.png` | Injection time vs mass error hexbin |
+| `mars_qc_tic_injection_time_vs_error.png` | TIC×injection time vs mass error hexbin |
+| `mars_qc_fragment_ions_vs_error.png` | Fragment ions vs mass error hexbin |
+| `mars_qc_rfa2_temperature_vs_error.png` | RFA2 temperature vs error (if available) |
+| `mars_qc_rfc2_temperature_vs_error.png` | RFC2 temperature vs error (if available) |
+| `mars_qc_feature_importance.png` | Model feature importance |
+| `mars_qc_summary.txt` | Calibration statistics |
+
+
+## Model Features
+
+The XGBoost model uses up to 16 features to predict m/z corrections:
+
+1. `precursor_mz` - DIA isolation window center
+2. `fragment_mz` - Fragment m/z being calibrated  
+3. `absolute_time` - Time relative to first acquisition (seconds)
+4. `log_tic` - Log10 of spectrum total ion current
+5. `log_intensity` - Log10 of peak intensity
+6. `injection_time` - Ion injection time (seconds)
+7. `tic_injection_time` - TIC × injection time product
+8. `fragment_ions` - Fragment intensity × injection time (total ions, not rate)
+9. `ions_above_0_1` - Total ions in (X+0.5, X+1.5] Th range above fragment m/z
+10. `ions_above_1_2` - Total ions in (X+1.5, X+2.5] Th range above fragment m/z
+11. `ions_above_2_3` - Total ions in (X+2.5, X+3.5] Th range above fragment m/z
+12. `ions_below_0_1` - Total ions in (X-1.5, X-0.5] Th range below fragment m/z
+13. `ions_below_1_2` - Total ions in (X-2.5, X-1.5] Th range below fragment m/z
+14. `ions_below_2_3` - Total ions in (X-3.5, X-2.5] Th range below fragment m/z
+15. `adjacent_ratio_0_1` - ions_above_0_1 / fragment_ions (relative adjacent density)
+16. `adjacent_ratio_1_2` - ions_above_1_2 / fragment_ions
+17. `adjacent_ratio_2_3` - ions_above_2_3 / fragment_ions
+18. `adjacent_ratio_below_0_1` - ions_below_0_1 / fragment_ions
+19. `adjacent_ratio_below_1_2` - ions_below_1_2 / fragment_ions
+20. `adjacent_ratio_below_2_3` - ions_below_2_3 / fragment_ions
+21. `rfa2_temp` - RF amplifier temperature (°C)
+22. `rfc2_temp` - RF electronics temperature (°C)
+
+**Note**: Features 6-20 are only included if injection time data is available in the mzML files. Features 21-22 are only included if temperature CSV files are provided. Features with universally missing data are automatically excluded.
+
+## RF Temperature Data
+
+Mars can incorporate RF temperature data to model thermal effects on mass accuracy. Temperature data is loaded from CSV files exported from Thermo chromatogram exports.
+
+### Temperature File Format
+
+Temperature CSV files should be in Thermo's chromatogram export format:
+- 3 header lines (skipped)
+- Columns: `Time(min)`, temperature value
+
+Example naming convention:
+```
+RFA2-Sample_Name.csv  # RF amplifier temperature
+RFC2-Sample_Name.csv  # RF electronics temperature  
+```
+
+### Usage with Temperature Data
+
+```bash
+mars calibrate \
+  --mzml data.mzML \
+  --prism-csv report.csv \
+  --temperature-dir /path/to/temperature_csvs/ \
+  --output-dir output/
+```
+
+Mars automatically finds temperature files matching each mzML filename and interpolates temperature values at each spectrum's retention time.
+
+## Python API
+
+```python
+from mars import load_blib, read_dia_spectra, match_library_to_spectra, MzCalibrator
+
+# Load library and match
+library = load_blib("library.blib")
+spectra = read_dia_spectra("data.mzML")
+matches = match_library_to_spectra(library, spectra, mz_tolerance=0.2, min_intensity=1500)
+
+# Train and save model
+calibrator = MzCalibrator()
+calibrator.fit(matches)
+calibrator.save("model.pkl")
+```
+
+## Requirements
+
+- **Spectral library**: blib format from Skyline with fragment annotations
+- **mzML files**: DIA data from Thermo Stellar (or similar unit resolution instrument)  
+- **PRISM CSV** (optional): Skyline report with `Start Time`, `End Time`, `Replicate Name` columns
+
+## License
+
+MIT