MassFlow

English | 简体中文

MassFlow is a modular preprocessing and data management framework for Mass Spectrometry Imaging (MSI) data.

Get the code

# Clone the repository
git clone https://github.com/NeoNexusX/MassFlow.git
cd MassFlow

Online Documentation

Online Documentation: https://neonexusx.github.io/MassFlow/

Project Structure

MassFlow/
├── .github/                 # GitHub configuration (Issue templates, Workflows)
├── .vscode/                 # VSCode configuration
├── data/                    # Example data
├── docs/                    # Documentation (VitePress)
│   ├── en/
│   └── zh/
├── logs/                    # Runtime logs
├── src/
│   └── massflow/            # Core source code
│       ├── data_manager/         # Data managers (MSDataManager, MSDataManagerImzML)
│       ├── module/               # Core data models
│       │   ├── spectrum.py       # Spectrum base type
│       │   ├── spectrum_imzml.py # ImzML spectrum with lazy loading
│       │   ├── mass_spectrum_set.py  # Collection of spectra
│       │   ├── ms_meta_data.py       # Metadata structures (ImzMlMetaData, etc.)
│       │   └── ...
│       ├── preprocess/              # Preprocessing pipeline
│       │   ├── api.py               # Chainable task registration API (PreprocessorAPI)
│       │   ├── preprocessor.py      # Pipeline executor (Preprocessor)
│       │   ├── flat_pre_fun.py      # Flat-array preprocessing (FlatPreprocess)
│       │   └── ...
│       ├── r_preprocess/       # R/Cardinal adapter
│       └── tools/              # Utility functions
├── tests/                   # Test cases
├── LICENSE
├── main.py
├── package.json
├── pyproject.toml           # Project configuration and dependencies
└── README.md

Development & Contribution

Quick Dev Start

It is recommended to run the following code (main.py) directly to verify data loading:

# Close conda first:
conda deactivate

# Install uv:
please follow :https://docs.astral.sh/uv/getting-started/installation/

# For Example:
# Linux && macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh 
# Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install dependencies:
uv sync 
uv pip install -e .

# Install optional R backend dependencies (requires local R):
uv sync --extra r

#run the code
uv run python main.py

• Default installation (uv sync) does not include R/Cardinal backend dependencies.

• If you need Cardinal backend (backend="cardinal"), install extra dependency group r and make sure R is installed and available in PATH (or set R_HOME).

• please read Contribution Guide: docs/en/contribution.md and docs/zh/contribution.md first

• Naming Conventions: docs/en/naming-conventions.md and docs/zh/naming-conventions.md

• Commit Convention: Conventional Commits (e.g., feat:, fix:, docs:, refactor:, test:)

• Recommended Extensions: Python, Pylance, Pylint, H5Web

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

References

• MATLAB Mass Spectrometry Preprocessing: https://www.mathworks.com/help/bioinfo/ug/preprocessing-raw-mass-spectrometry-data.html
• Cardinal MSI: https://cardinalmsi.org/
  • Cardinal Guide Book;https://bioconductor.org/packages/devel/bioc/vignettes/Cardinal/inst/doc/Cardinal3-guide.html
  • Cardinal Github：https://github.com/kuwisdelu/Cardinal
  • Matter Github：https://github.com/kuwisdelu/matter
• PyOpenMS: https://pyopenms.readthedocs.io/
  • github：https://github.com/OpenMS/OpenMS
  • docs：https://github.com/OpenMS/OpenMS-docs
  • contributing libraries ：https://github.com/OpenMS/contrib
  • Flash APP ：https://github.com/OpenMS/FLASHApp

Feedback

For support or to report issues, please open an issue on the GitHub repository.