Metadata-Version: 2.4
Name: spectramap
Version: 0.6.4
Summary: Hyperspectral package for spectroscopists
Home-page: https://github.com/MicroscopeMaestro/spectramap
Author: Juan David Muñoz-Bolaños
Author-email: jmunozbolanos@gmail.com
Project-URL: Bug Tracker, https://github.com/MicroscopeMaestro/spectramap
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Software Development :: Bug Tracking
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: colorcet
Requires-Dist: spc-spectra
Requires-Dist: hdbscan
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SpectraMap (SpMap)

**A Robust Hyperspectral Analysis Package for Spectroscopists in Python**

<p align="justify">
Hyperspectral imaging has critical applications across medicine, agriculture, pharmaceuticals, materials science, and food quality control. <b>SpectraMap</b> provides an advanced, fast, and highly structured framework specifically designed for analyzing Raman and other spectroscopic hyperspectral data.
</p>
<p align="justify">
Recently optimized with a robust architecture, SpectraMap validates data types to ensure reliable and error-free execution of advanced processing techniques like clustering, unmixing, and deep dimensionality reduction.
</p>

---

## 🛠️ Key Features

SpectraMap is built around the highly versatile `hyper_object` class. It includes comprehensive tools covering the entire hyperspectral workflow:

### 1. Robust Data Type Architecture
SpectraMap strictly validates processing operations based on your data type to prevent computational errors:
* `hyper_image`: Full 2D/3D spatial spectral maps (supports spatial mapping, unmixing, and image segmentation).
* `multi_spectra`: Collections of independent spectra without spatial relations (supports PCA, PLS-LDA, scatter plotting).
* `single_spectrum`: Individual spectral signatures (supports baseline correction, smoothing, peak analysis).

### 2. Preprocessing & Correction
Advanced baseline corrections, smoothing algorithms, spike removal, and normalizations.

<p align="center"><img src="https://raw.githubusercontent.com/MicroscopeMaestro/spectramap/main/docs/images/tissue_signature.png" alt="Tissue Signature" /></p>
<p align="center"><i>Figure 1: Mean and standard deviation visualization of a tissue Raman signature.</i></p>

### 3. Machine Learning & Processing
Includes powerful unsupervised and supervised tools:
* **Clustering:** K-Means, Hierarchical (HCA), and Density-Based (DBSCAN/HDBSCAN).
* **Dimensionality Reduction:** Principal Component Analysis (PCA) and Partial Least Squares Discriminant Analysis (PLS-LDA).
* **Unmixing:** Vertex Component Analysis (VCA) for extracting pure endmembers.

<p align="center">
  <img src="https://raw.githubusercontent.com/MicroscopeMaestro/spectramap/main/docs/images/clustering_map.png" alt="Clustering Map" width="45%" />
  <img src="https://raw.githubusercontent.com/MicroscopeMaestro/spectramap/main/docs/images/clustering_stack.png" alt="Clustering Stack" width="45%" />
</p>
<p align="center"><i>Figure 2: Segmentation of microplastics on complex matrices via clustering algorithms.</i></p>

### 4. Advanced Visualization
High-quality rendering of false-color maps, spectral stacks, and scatter profiling.

<p align="center"><img src="https://raw.githubusercontent.com/MicroscopeMaestro/spectramap/main/docs/images/pca_scores.png" alt="PCA Scores" /></p>
<p align="center"><i>Figure 3: 2D PCA scores distinguishing different biomolecular components.</i></p>

---

## 🚀 Installation

SpectraMap is available on PyPI and requires Python 3. 

```bash
pip install spectramap
```

*For comprehensive documentation and all 7 extended hyperspectral examples, please see the [Official Manual](https://github.com/MicroscopeMaestro/spectramap/blob/main/docs/examples.md).*

---

## 📖 Quick Start Guide

### Example 1: Hyperspectral Image (HDBSCAN Clustering)
```python
from spectramap import spmap as sp

# Initialize as a hyperspectral image (default)
micro = sp.hyper_object('Microplastics', data_type='hyper_image')
micro.read_csv_xz('examples/microplastics_tissue/microplastics_tissue')

# Preprocessing to remove background and highlight sharp peaks
micro.keep(400, 1850)
micro.snip(30) # fast SNIP baseline correction
micro.gaussian(2)
micro.vector()

# Apply Hierarchical Density-Based Clustering (HDBSCAN)
micro.hdbscan(5, 5)

# Render the segmentation map and corresponding spectral stacks
colors = micro.show_map(['gray', 'k', 'r'], None, 1)
micro.show_stack(0.1, 0.5, colors)
```

### Example 2: Multi-Spectra (PCA & PLS-LDA)
```python
from spectramap import spmap as sp

# Initialize as independent multiple spectra
plastics = sp.hyper_object("Plastics", data_type="multi_spectra")
plastics.read_csv_xz('examples/plastics_PLS_PCA/plastics')

# Standard preprocessing
plastics.rubber(10)
plastics.vector()

# Principal Component Analysis
scores_pca, loadings_pca = plastics.pca(3)
scores_pca.show_scatter(main_label=15, size=15, colors="auto")
```

---

## 🗺️ Roadmap & Upcoming Developments
- [ ] Interactive Graphical User Interface (GUI)
- [ ] Integration of Supervised Deep Learning models
- [ ] Specialized spectral Large Language Model (LLM) agents
- [x] Robust `data_type` attribute validation framework
- [x] MKDocs comprehensive manual and example gallery

## 📄 License & References
SpectraMap is distributed under the **MIT License**.

**Key Algorithm References:**
1. Pedregosa et al., "Scikit-learn: Machine Learning in Python," *JMLR*, 2011.
2. Nascimento & Dias, "Vertex component analysis," *IEEE TGRS*, 2005.
3. Zhang et al., "Baseline correction using adaptive iteratively reweighted penalized least squares," *Analyst*, 2010.
4. McInnes et al., "hdbscan: Hierarchical density based clustering," *JOSS*, 2017.
