# Oscillations_Corrector_Algorithm_SICRIT
Suppressing Signal Artifacts in CE-SICRIT-MS via Oscillation Processing
This repository contains a Python tool to **detect and correct oscillations** that appear in mass spectrometry (MS) spectra acquired with the SICRIT ionization source.
The program reads .mzXML or .mzML files, identifies oscillatory m/z signals via FFT analysis, corrects their intensities, and outputs cleaned .mzML files.
The tool includes a **command-line interface (CLI)** to process single files or whole folders.
---
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Processing a Single File](#processing-a-single-file)
- [Processing a Folder of Files](#processing-a-folder-of-files)
- [Command-Line Options](#command-line-options)
- [Detection and Correction Workflow](#detection-and-correction-workflow)
- [Examples](#examples)
- [License](#license)
---
## Introduction
This Python module provides a pipeline for correcting oscillatory artifacts in CE-SICRIT-MS spectra.
It includes:
- Automatic loading of `.mzML` and `.mzXML` files.
- Conversion of `.mzXML` to `.mzML` using [ProteoWizard MSConvert](https://proteowizard.sourceforge.io/downloads.shtml).
- Detection of oscillatory m/z values using FFT-based power analysis.
- Correction of intensity oscillations via residual signal reconstruction.
- Saving corrected spectra in `.mzML` format.
---
## Installation
If you want to use the last released version, it is published in pypy already.
```bash
pip install sicritfix
```
If you want to install the source code or develop over it, clone the repository and install [the dependencies](conda_env.yml) inside a conda environment. If you want to run the CLI you shall install it as a module.
```bash
git clone https://github.com/ceu-biolab/Oscillations_Corrector_Algorithm_SICRIT.git
cd Oscillations_Corrector_Algorithm_SICRIT
conda create -n sicritfix python=3.12
conda activate sicritfix
pip install -e .
```
---
## Usage
You can run the program from the command line after installation.
Both single files and folders are supported.
### Processing a Single File
Run the tool with an input file:
```bash
python sicritfix.py input_file.mzXML --output corrected.mzML --overwrite
```
If no --output is provided, the tool will automatically generate a filename by appending _corrected.mzML.
### Processing a Folder of Files
To process an entire folder of `.mzXML` files, simply pass the folder path as input.
Each file will be automatically converted to `.mzML`, processed, and saved.
```bash
python CLI.py /path/to/folder --overwrite --verbose
```
During execution you’ll see messages like:
```bash
file: sample1.mzXML loaded correctly
file: sample2.mzXML loaded correctly
```
### Command-Line Options
- `--output` : Output path (optional).
- `--overwrite` : Overwrite existing files.
- `--plot` : Show diagnostic plots.
- `--verbose` : Print detailed execution logs.
- `--mz_window` : m/z bin size for oscillation detection (default: `0.01`). Increasing this value groups nearby m/z peaks into larger bins, making the algorithm less sensitive to small differences in m/z but more tolerant to noise. Decreasing it makes detection more precise at the cost of possibly missing weak or noisy signals.
- `--rt_window` : Retention time window for XIC smoothing (default: `0.01`). This controls how intensities are aggregated across retention time. A larger value smooths the signal more strongly, which can improve frequency detection but may blur fine details in short peaks. A smaller value preserves fine temporal resolution but may leave more noise in the XIC.
Note: Both parameters should be adjusted depending on the type of signa being processed.
---
## Detection and Correction Workflow
1. Load the input file(s).
- If `.mzXML` is detected, it is converted to `.mzML`.
2. Extract relevant MS data.
- Retention times (RT), m/z values, and intensities.
3. Detect oscillating m/z values.
- Uses FFT-based power spectrum analysis.
4. Correct oscillations.
- Subtracts a modeled sinusoidal component to recover residual signal.
5. Update spectra.
- Replace oscillating intensities with corrected values.
6. Save results.
- Corrected file is written to disk in `.mzML` format.
---
## Examples
Process a single file:
```bash
sicritfix data/sample.mzXML --plot
```
or
```bash
python CLI.py data/sample.mzXML --plot
```
Process all files in a folder:
```bash
sicritfix data/sample.mzXML --overwrite
```
or
```bash
python CLI.py data/sample.mzXML --overwrite
```
Verbose mode:
```bash
sicritfix data/sample.mzXML --verbose
```
or
```bash
python CLI.py data/sample.mzML --verbose
```
---
## License
This project is licensed under the GNU General Public License v3.0.
You are free to use, modify, and distribute the software, but any derivative work must also be open-source under the GPL-3.0 license.
For more details, see the full GPL-3.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "sicritfix",
"maintainer": "Maite G\u00f3mez del Rio Vinuesa",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "maite.gomezriovinuesa@gmail.com",
"keywords": "mass spectrometry, mzML, signal correction, fft, phase, oscillations",
"author": "Maite G\u00f3mez del Rio Vinuesa",
"author_email": "maite.gomezriovinuesa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d2/6d/01441f0b159a15a6d95d50a432c68b01c59d7d4d25a56c6c0d3fd4f050fc/sicritfix-0.0.3.tar.gz",
"platform": null,
"description": "# Oscillations_Corrector_Algorithm_SICRIT\nSuppressing Signal Artifacts in CE-SICRIT-MS via Oscillation Processing\n\nThis repository contains a Python tool to **detect and correct oscillations** that appear in mass spectrometry (MS) spectra acquired with the SICRIT ionization source.\nThe program reads .mzXML or .mzML files, identifies oscillatory m/z signals via FFT analysis, corrects their intensities, and outputs cleaned .mzML files.\n\nThe tool includes a **command-line interface (CLI)** to process single files or whole folders.\n\n---\n\n## Table of Contents\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Processing a Single File](#processing-a-single-file)\n - [Processing a Folder of Files](#processing-a-folder-of-files)\n - [Command-Line Options](#command-line-options)\n- [Detection and Correction Workflow](#detection-and-correction-workflow)\n- [Examples](#examples)\n- [License](#license)\n\n---\n\n## Introduction\nThis Python module provides a pipeline for correcting oscillatory artifacts in CE-SICRIT-MS spectra. \nIt includes:\n- Automatic loading of `.mzML` and `.mzXML` files. \n- Conversion of `.mzXML` to `.mzML` using [ProteoWizard MSConvert](https://proteowizard.sourceforge.io/downloads.shtml). \n- Detection of oscillatory m/z values using FFT-based power analysis. \n- Correction of intensity oscillations via residual signal reconstruction. \n- Saving corrected spectra in `.mzML` format.\n\n---\n\n## Installation\nIf you want to use the last released version, it is published in pypy already. \n```bash\npip install sicritfix\n```\n\nIf you want to install the source code or develop over it, clone the repository and install [the dependencies](conda_env.yml) inside a conda environment. If you want to run the CLI you shall install it as a module. \n\n```bash\ngit clone https://github.com/ceu-biolab/Oscillations_Corrector_Algorithm_SICRIT.git\ncd Oscillations_Corrector_Algorithm_SICRIT\n\nconda create -n sicritfix python=3.12\nconda activate sicritfix\npip install -e .\n```\n---\n\n## Usage\nYou can run the program from the command line after installation. \nBoth single files and folders are supported.\n\n### Processing a Single File\nRun the tool with an input file:\n\n```bash\npython sicritfix.py input_file.mzXML --output corrected.mzML --overwrite\n```\nIf no --output is provided, the tool will automatically generate a filename by appending _corrected.mzML.\n\n### Processing a Folder of Files\nTo process an entire folder of `.mzXML` files, simply pass the folder path as input. \nEach file will be automatically converted to `.mzML`, processed, and saved.\n\n```bash\npython CLI.py /path/to/folder --overwrite --verbose\n```\nDuring execution you\u2019ll see messages like:\n\n```bash\nfile: sample1.mzXML loaded correctly\nfile: sample2.mzXML loaded correctly\n```\n### Command-Line Options\n- `--output` : Output path (optional). \n- `--overwrite` : Overwrite existing files. \n- `--plot` : Show diagnostic plots. \n- `--verbose` : Print detailed execution logs. \n- `--mz_window` : m/z bin size for oscillation detection (default: `0.01`). Increasing this value groups nearby m/z peaks into larger bins, making the algorithm less sensitive to small differences in m/z but more tolerant to noise. Decreasing it makes detection more precise at the cost of possibly missing weak or noisy signals.\n- `--rt_window` : Retention time window for XIC smoothing (default: `0.01`). This controls how intensities are aggregated across retention time. A larger value smooths the signal more strongly, which can improve frequency detection but may blur fine details in short peaks. A smaller value preserves fine temporal resolution but may leave more noise in the XIC.\nNote: Both parameters should be adjusted depending on the type of signa being processed.\n\n---\n\n## Detection and Correction Workflow\n1. Load the input file(s). \n - If `.mzXML` is detected, it is converted to `.mzML`. \n\n2. Extract relevant MS data. \n - Retention times (RT), m/z values, and intensities. \n\n3. Detect oscillating m/z values. \n - Uses FFT-based power spectrum analysis. \n\n4. Correct oscillations. \n - Subtracts a modeled sinusoidal component to recover residual signal. \n\n5. Update spectra. \n - Replace oscillating intensities with corrected values. \n\n6. Save results. \n - Corrected file is written to disk in `.mzML` format.\n\n---\n\n## Examples\nProcess a single file:\n```bash\nsicritfix data/sample.mzXML --plot\n```\nor\n```bash\npython CLI.py data/sample.mzXML --plot\n```\nProcess all files in a folder:\n```bash\nsicritfix data/sample.mzXML --overwrite\n```\nor\n```bash\npython CLI.py data/sample.mzXML --overwrite\n```\nVerbose mode:\n```bash\nsicritfix data/sample.mzXML --verbose\n```\nor\n```bash\npython CLI.py data/sample.mzML --verbose\n```\n---\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0.\n\nYou are free to use, modify, and distribute the software, but any derivative work must also be open-source under the GPL-3.0 license.\n\nFor more details, see the full GPL-3.0 license.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Python package to detect and correct oscillatory artifacts in mass spectrometry mzML data.",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://github.com/MaiteGomezRio/Oscillations_Corrector_Algorithm_SICRIT#readme",
"Homepage": "https://github.com/MaiteGomezRio/Oscillations_Corrector_Algorithm_SICRIT",
"Repository": "https://github.com/MaiteGomezRio/Oscillations_Corrector_Algorithm_SICRIT"
},
"split_keywords": [
"mass spectrometry",
" mzml",
" signal correction",
" fft",
" phase",
" oscillations"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b01d77e50e79d6caa90164dedf76adb4ff87f809b8ce2bd14e55e3dde23503e0",
"md5": "fc64034dee09bc8aae20e6dad3100dac",
"sha256": "edb5b7b05c4ce29744301bb185c6d6334fe5354566cf3292fb31c9fc06e0662c"
},
"downloads": -1,
"filename": "sicritfix-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc64034dee09bc8aae20e6dad3100dac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 38213,
"upload_time": "2025-09-10T07:36:24",
"upload_time_iso_8601": "2025-09-10T07:36:24.733791Z",
"url": "https://files.pythonhosted.org/packages/b0/1d/77e50e79d6caa90164dedf76adb4ff87f809b8ce2bd14e55e3dde23503e0/sicritfix-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d26d01441f0b159a15a6d95d50a432c68b01c59d7d4d25a56c6c0d3fd4f050fc",
"md5": "79a538a057d9993d12f6c14a7dedfcab",
"sha256": "2b9bc00fc04a3ccb6c698e855ef59a21d7c2959a054b44b6732ae21660901f70"
},
"downloads": -1,
"filename": "sicritfix-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "79a538a057d9993d12f6c14a7dedfcab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 32936,
"upload_time": "2025-09-10T07:36:26",
"upload_time_iso_8601": "2025-09-10T07:36:26.183590Z",
"url": "https://files.pythonhosted.org/packages/d2/6d/01441f0b159a15a6d95d50a432c68b01c59d7d4d25a56c6c0d3fd4f050fc/sicritfix-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 07:36:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaiteGomezRio",
"github_project": "Oscillations_Corrector_Algorithm_SICRIT#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sicritfix"
}
JSON
