Metadata-Version: 2.4
Name: massflow
Version: 0.1.0
Summary: MassFlow is a modular, high-performance framework for Mass Spectrometry Imaging (MSI) data.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Requires-Dist: h5py>=3.16.0
Requires-Dist: hdf5plugin>=6.0.0
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: numba>=0.64.0
Requires-Dist: numpy>=2.4.3
Requires-Dist: pyimzml>=1.5.5
Requires-Dist: pywavelets>=1.9.0
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.16.3
Requires-Dist: umap-learn>=0.5.12
Requires-Dist: wheezy-template>=3.2.5
Requires-Dist: zarr>=3.2.1
Provides-Extra: r
Requires-Dist: rpy2>=3.6.4; extra == "r"
Provides-Extra: torch
Requires-Dist: torch>=2.11.0; extra == "torch"
Dynamic: license-file

# MassFlow

English | [简体中文](README_CN.md)

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

## Get the code

```bash
# 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:

```bash
# 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](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.
