Metadata-Version: 2.4
Name: xpectrass
Version: 0.0.1
Summary: FTIR/ToF-SIMS Spectral Analysis Suite - Preprocessing toolkit for spectral classification
Home-page: https://github.com/kazilab/xpectrass
Author: FTIR-PLASTIC Team
Author-email: FTIR-PLASTIC Team <xpectrass@kazilab.se>
Maintainer-email: FTIR-PLASTIC Team <xpectrass@kazilab.se>
License: MIT
Project-URL: Homepage, https://github.com/kazilab/xpectrass
Project-URL: Documentation, https://xpectrass.readthedocs.io/
Project-URL: Repository, https://github.com/kazilab/xpectrass
Project-URL: Issues, https://github.com/kazilab/xpectrass/issues
Project-URL: Changelog, https://github.com/kazilab/xpectrass/blob/main/CHANGELOG.md
Keywords: FTIR,spectroscopy,preprocessing,baseline correction,plastic classification,ToF-SIMS,chemometrics,machine learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: polars>=0.15.0
Requires-Dist: pybaselines>=1.0.0
Requires-Dist: PyWavelets>=1.1.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: joblib>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: pre-commit>=2.17.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# xpectrass

A comprehensive preprocessing toolkit for spectral classification.

[![Python Version](https://img.shields.io/pypi/pyversions/xpectrass.svg)](https://pypi.org/project/xpectrass/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Documentation Status](https://readthedocs.org/projects/xpectrass/badge/?version=latest)](https://xpectrass.readthedocs.io/)

## Features

- **9 Preprocessing Steps** with multiple configurable methods
- **50+ Baseline Correction** algorithms via pybaselines
- **sklearn-compatible API** with fit/transform pattern
- **Preset Configurations** for common use cases
- **Polars DataFrame Support** for high-performance data handling

### Preprocessing Pipeline

| Step | Methods Available |
|------|-------------------|
| Data Validation | Completeness, range checks, outlier detection |
| Baseline Correction | 50+ methods (airpls, asls, poly, mor, ...) |
| Denoising | Savitzky-Golay, wavelet, median, Gaussian, ... |
| Normalization | SNV, vector, min-max, area, peak normalization |
| Atmospheric Correction | CO₂/H₂O interpolation, reference subtraction |
| Spectral Derivatives | 1st/2nd derivative, gap derivative |
| Scatter Correction | MSC, EMSC, SNV+detrend |
| Region Selection | Predefined FTIR regions for plastics |
| Mean Centering | For PCA/PLS preparation |

## Installation

### From PyPI (when published)

```bash
pip install xpectrass
```

### From Source

```bash
git clone https://github.com/kazilab/xpectrass.git
cd xpectrass
pip install -e .
```

### With Development Dependencies

```bash
pip install -e ".[dev]"
```

## Quick Start

```python
from xpectrass import FTIRPreprocessor, create_preprocessor
from xpectrass.utils import process_batch_files
import glob

# Load FTIR data
files = glob.glob('data/*.csv')
df = process_batch_files(files)

# Standard preprocessing pipeline
pipe = create_preprocessor('standard')
processed = pipe.fit_transform(df)
```

### Custom Configuration

```python
from xpectrass import FTIRPreprocessor, PreprocessingConfig

config = PreprocessingConfig(
    baseline_params={'method': 'airpls', 'lam': 1e6},
    denoise_params={'method': 'savgol', 'window_length': 15},
    normalize_params={'method': 'snv'},
    region_selection=True,
    regions=[(400, 1800), (2700, 3100)],
)

pipe = FTIRPreprocessor(config)
processed = pipe.fit_transform(df)
```

### Available Presets

| Preset | Description |
|--------|-------------|
| `minimal` | Baseline + SNV normalization |
| `standard` | Baseline → Denoise → Normalize → Mean center |
| `classification` | Optimized for plastic classification |
| `pca` | Standard + first derivative |
| `raw` | Validation only |

## Individual Utilities

```python
from xpectrass.utils import (
    # Baseline
    baseline_correction, baseline_method_names,
    
    # Denoising
    denoise, denoise_method_names,
    
    # Normalization
    normalize, mean_center, auto_scale,
    
    # Derivatives
    spectral_derivative, first_derivative,
    
    # Region selection
    select_region, FTIR_REGIONS,
)

# Apply individual preprocessing
corrected = baseline_correction(spectrum, method='airpls')
denoised = denoise(corrected, method='savgol')
normalized = normalize(denoised, method='snv')
```

## Documentation

Full documentation is available at [xpectrass.readthedocs.io](https://xpectrass.readthedocs.io/).

### Building Documentation Locally

```bash
cd docs
pip install -r requirements.txt
sphinx-build -b html . _build/html
```

## Requirements

- Python ≥ 3.8
- NumPy, SciPy, Pandas, Polars
- PyBaselines, PyWavelets
- Matplotlib, scikit-learn

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this software in your research, please cite:

```bibtex
@software{xpectrass,
  author = {FTIR-PLASTIC Team},
  title = {xpectrass: FTIR/ToF-SIMS Spectral Analysis Suite},
  year = {2024},
  url = {https://github.com/kazilab/xpectrass}
}
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
