Metadata-Version: 2.5
Name: ramappy
Version: 0.1.2rc1
Summary: Process and analyse hyperspectral data
Project-URL: Homepage, https://ramapp.io
Project-URL: Repository, https://github.com/ramappy/ramappy
Author: Andrea Masella, Elia Broggio
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: MCR,N-FINDR,PCA,baseline,chemometrics,hyperspectral,imaging,raman,spectroscopy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: h5py>=3.6
Requires-Dist: joblib>=1.1
Requires-Dist: matplotlib>=3.7
Requires-Dist: numba>=0.55
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=9.0
Requires-Dist: polars>=1.0
Requires-Dist: pybaselines[full]>=1.0
Requires-Dist: pydantic-extra-types
Requires-Dist: pydantic>=2.0
Requires-Dist: pymcr>=0.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: renishawwire>=0.1
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: tqdm>=4.60
Requires-Dist: zarr>=3.0
Requires-Dist: zarrs>=0.2.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: ty>=0.0.1; extra == 'dev'
Requires-Dist: types-pillow; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: autodoc-pydantic>=2; extra == 'docs'
Requires-Dist: myst-parser>=3.0; extra == 'docs'
Requires-Dist: numpydoc>=1.7; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx-argparse>=0.5; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3.0; extra == 'docs'
Requires-Dist: sphinx-design>=0.6; extra == 'docs'
Requires-Dist: sphinx>=8.0; extra == 'docs'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://ramapp.io"><img width="75%" src="./docs/assets/ramappy_logo.svg" alt="ramappy"></a>
</p>

# ramappy

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![PyPI version](https://img.shields.io/pypi/v/ramappy.svg)](https://pypi.org/project/ramappy/)
[![CI](https://github.com/ramappy/ramappy/actions/workflows/ci.yml/badge.svg)](https://github.com/ramappy/ramappy/actions)

`ramappy` is a Python toolkit for hyperspectral spectroscopy processing and analysis,
with a strong focus on Raman maps.


It provides:

- typed core data structures (`SpectralMap`, `Spectrum`)
- composable processing and analysis steps
- extensible IO format registries
- project/session primitives for backend applications

## Architecture overview

The codebase is organized around a few stable layers:

1. **Core domain (`ramappy.core`)**
   - `SpectralMap`: map-level container (`n_pixels × n_spectral` + spatial geometry)
   - `Spectrum`: spectrum container (single or multi-pixel)
   - entities (`Mask`, `Image2D`, grouped/ordered collections)

2. **Pipeline layer (`ramappy.core.pipeline`, `ramappy.pipeline`)**
   - step schemas (`StepParams`)
   - step registry/decorator (`@pipeline_step`)
   - middleware-based execution (`StepRunner`)

3. **IO layer (`ramappy.io`)**
   - format registries for readers/writers
   - decorator-based registration (`@input_format`, `@output_format`)
   - automatic format guessing by extension/sniffer

4. **Project/session layer (`ramappy.project`)**
   - backend-ready wrapper for data + pipeline + versioned assets

## Installation

Install the latest release from PyPI with [uv](https://docs.astral.sh/uv/) (recommended) or `pip`:

```bash
uv add ramappy
# or
pip install ramappy
```

For the unreleased development version, install directly from Git:

```bash
uv add git+https://github.com/ramappy/ramappy.git
# or
pip install git+https://github.com/ramappy/ramappy.git
```

To install optional pandas export support, use `ramappy[pandas]`.

## Core abstractions

### `SpectralMap`

Main map object containing:

- spectral axis (`x`)
- flattened spectral data matrix (`data`)
- spatial shape (`img_width`, `img_height`)
- unit metadata (`x_axis_unit`, `data_unit`)
- optional masks/images/spectra/history

### `Spectrum`

Spectrum object used for:

- extracted map spectra (cursor, mask averages, etc.)
- standalone imported spectra
- plotting/export and alignment operations

### IO registries

IO formats are registered centrally through decorators:

- `@input_format(...)` → reader registration
- `@output_format(...)` → writer registration

This keeps extension handling and parameter validation declarative.

## Usage examples

### Create a map from arrays

**From a 3-D cube** `(height, width, n_spectral)`: preferred when your data is already spatially arranged:

```python
import numpy as np
from ramappy import SpectralMap

x = np.linspace(100.0, 1800.0, 512)
cube = np.random.rand(10, 10, 512).astype(np.float32)  # (height, width, n_spectral)

hsi = SpectralMap.from_cube(cube, spectral_axis=x)
```

**From a 2-D flat array** `(n_pixels, n_spectral)`: when data arrives row-major (all pixels concatenated):

```python
import numpy as np
from ramappy import SpectralMap

x = np.linspace(100.0, 1800.0, 512)
data = np.random.rand(100, 512).astype(np.float32)  # (n_pixels, n_spectral)

hsi = SpectralMap(x=x, data=data, img_width=10, img_height=10)
# img_width * img_height must equal data.shape[0]
```

Both representations are interchangeable at runtime: `hsi.data` is the flat view and `hsi.cube` is the
zero-copy 3-D view `(height, width, n_spectral)`.

### Read data from file

```python
from ramappy.io import read_file

hsi = read_file("sample.zarr", format="auto", as_hsi=True)
```

### Export map data

```python
from ramappy.io import export_spectra

export_spectra(hsi, out_file="out.zarr", format_name="zarr", format_params={})
```

## Command-line interface

Installing `ramappy` exposes the `ramappy-batch` command for running a pipeline over a set of files and
collecting all results into a single aggregated output file.

```
ramappy-batch [src_files ...] dest_dir -c config.yaml [-p N] [-w]
```

| Argument | Description |
|---|---|
| `src_files` | One or more input files, or a single directory (all files with the format's extension are used) |
| `dest_dir` | Output directory. The aggregated result is written to `dest_dir/<config_stem>.<ext>` |
| `-c`, `--config_file` | YAML pipeline config file (required) |
| `-p`, `--parallel` | Number of parallel workers; `-1` = all CPUs (default), `0` = serial |
| `-w`, `--overwrite` | Overwrite the output file if it already exists |

### Config file format

```yaml
input:
  format: renishaw_wdf # any registered input format (renishaw_wdf, csv, zarr, …)
  format_params: {}    # format-specific reader options

pipeline:
  - name: correct_baseline
    params:
      method: rubberband

output:
  format: parquet      # csv (default), parquet, or feather
  transpose: false     # set true to stack results vertically instead of aligning columns

general:               # optional section
  mask_dir: path/to/masks   # directory containing pre-computed masks named <stem>_mask_<id>.png
```

### Example

```bash
# Process all .wdf files in raw_data/, write results to results/
ramappy-batch raw_data/ results/ -c pipeline.yaml

# Serial processing, overwrite existing output
ramappy-batch sample_*.wdf results/ -c pipeline.yaml -p 0 -w
```

## Development guidelines

### Environment setup

Prefer `uv`:

```bash
uv sync --all-extras
```

Or editable install:

```bash
pip install -e .
```

## Documentation (auto-generated)

API docs are generated from docstrings using **Sphinx**.

### Build the documentation

To build the documentation locally, run:

```bash
# Sync dependencies
uv sync --extra docs

# Build HTML documentation
cd docs
make html
```

The output HTML files will be generated in `docs/_build/html/`. You can open `docs/_build/html/index.html` in your web browser to view the built site.

Configuration lives in `docs/conf.py`; manually written documentation pages live under `docs/reference/`
(e.g., `core.md`, `processing.md`), while `docs/reference/api/` holds the auto-generated API reference.

## License

`ramappy` is released under the [GNU General Public License v3.0](LICENSE).
