Metadata-Version: 2.4
Name: specclust
Version: 0.1.0
Summary: Conditional spectrum autoencoder and clustering for MS/MS dark-proteome discovery
Project-URL: Homepage, https://github.com/VilenneFrederique/specclust
Project-URL: Repository, https://github.com/VilenneFrederique/specclust
Project-URL: Issues, https://github.com/VilenneFrederique/specclust/issues
Author-email: Frederique Vilenne <frederique.vilenne@uhasselt.be>
License: MIT License
        
        Copyright (c) 2026 Frederique Vilenne, Piotr Prostko, Dirk Valkenborg
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: autoencoder,clustering,deep learning,mass spectrometry,proteomics
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: platformdirs>=3.0
Requires-Dist: scikit-learn>=1.2
Requires-Dist: tensorflow>=2.13
Requires-Dist: tqdm>=4.64
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: hdbscan
Requires-Dist: hdbscan>=0.8.33; extra == 'hdbscan'
Provides-Extra: mzml
Requires-Dist: pyteomics>=4.6; extra == 'mzml'
Provides-Extra: train
Requires-Dist: joblib>=1.2; extra == 'train'
Requires-Dist: pyteomics>=4.6; extra == 'train'
Requires-Dist: regex>=2023.0; extra == 'train'
Requires-Dist: tqdm>=4.64; extra == 'train'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == 'viz'
Requires-Dist: umap-learn>=0.5; extra == 'viz'
Description-Content-Type: text/markdown

# SpecClust

**SpecClust** embeds MS/MS spectra with a conditional transformer autoencoder
and clusters the latent space to discover candidate novel ("dark proteome")
peptides. Spectra are conditioned on precursor *m/z*, charge, and ion mobility,
so same-peptide spectra land close together in latent space.

The trained model is large (~650 MB), so it is **not** shipped on PyPI. The pip
package contains the code; the weights are hosted externally and downloaded +
cached on first use. Because embedding only needs the **encoder**, the default
download is encoder-only — roughly half the full model.

## Installation

```bash
pip install specclust                 # core: load model, embed, cluster
pip install "specclust[hdbscan]"      # add HDBSCAN clustering
pip install "specclust[viz]"          # add plotting (matplotlib, umap)
pip install "specclust[mzml]"         # add pyteomics for mzML
pip install "specclust[train]"        # everything needed to retrain
```

TensorFlow is a core dependency (the encoder needs it) but is imported lazily —
`import specclust` does not load TensorFlow until you actually build or load a
model.

## Getting the weights

The package looks for model files in this order:

1. `SPECCLUST_MODEL_DIR` — set this to a folder holding the weights (handy on
   an HPC node where you already have them):
   ```bash
   export SPECCLUST_MODEL_DIR=/path/to/weights
   ```
2. the local cache (downloaded once, then reused);
3. download from the URLs in `specclust.modelhub.REGISTRY`.

To enable automatic download, host the weights and fill in the `url` (and,
recommended, `sha256`) fields of `REGISTRY`. Good hosting options: a **GitHub
Release** asset (simple, up to 2 GB/file), the **Hugging Face Hub**
(purpose-built for model weights), or **Zenodo** (gives a citable DOI for the
paper). Any direct-download URL works.

You can always bypass the registry with explicit local paths:

```python
from specclust import load_encoder
encoder = load_encoder(weights="encoder.weights.h5", config="encoder_config.json")
```

## Quick start

```python
import numpy as np
from specclust import load_encoder, embed_raw_spectra, cluster_latents, score_clusters

encoder = load_encoder()  # downloads/caches the encoder on first call

# raw peak lists + precursor info (lists aligned by index)
latents = embed_raw_spectra(
    encoder,
    mz_list, intensity_list,
    precursor_mz, charge, ion_mobility,
)

labels, info = cluster_latents(latents, method="hdbscan", min_cluster_size=5)
scores = score_clusters(latents, labels)
print(info["n_clusters"], "clusters")
```

Command line:

```bash
specclust embed   -i parquet_dir/ -o latents.npy
specclust cluster -i latents.npy  -o clusters/ --method hdbscan
```

## Publishing the model (one-time)

Run the export step to produce the slim encoder assets from a trained
autoencoder, then upload them to your release/Hub:

```bash
python training/export_encoder.py --ae-dir AE_DIR --out release_assets/
# -> release_assets/specclust_encoder.weights.h5
#    release_assets/encoder_config.json
```

Compute SHA-256 for the registry:

```bash
python -c "import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" \
  release_assets/specclust_encoder.weights.h5
```

## Repository layout

```
src/specclust/      installable package (model, embed, cluster, consensus, CLI)
training/           NOT installed: HPC data-prep, training, and export scripts
  export_encoder.py   run once to create the slim encoder assets to publish
  reference/          the original monolithic scripts, kept verbatim
tests/              run without TensorFlow or weights (model tests auto-skip)
```

## Citation
Publication Pending!

Vilenne, Frédérique & Valkenborg Dirk. Clustering the Dark Proteome: A Deep Learning Approach to Novel Peptide Discovery in Immunopeptidomics (2026)

## License

MIT © 2026 Frédérique Vilenne, Dirk Valkenborg
