Metadata-Version: 2.5
Name: sylphy
Version: 1.1.0
Summary: Protein sequence representation: encoders, embeddings, and reductions.
Project-URL: Documentation, https://github.com/kren-ai-lab/sylphy#readme
Project-URL: Homepage, https://github.com/kren-ai-lab/sylphy
Project-URL: Issues, https://github.com/kren-ai-lab/sylphy/issues
Project-URL: Source, https://github.com/kren-ai-lab/sylphy
Author-email: Kren AI Lab <krenai@umag.cl>
License-Expression: MIT
License-File: LICENSE
Keywords: AAindex,ESM,ProtBERT,ProtT5,bioinformatics,dimension-reduction,embeddings,k-mers,protein,transformers
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.15,>=3.11
Requires-Dist: huggingface-hub<1.0,>=0.36.0
Requires-Dist: niquests<4.0,>=3.0
Requires-Dist: numpy<3.0,>=2.3.5
Requires-Dist: platformdirs<5.0,>=4.0
Requires-Dist: polars<2.0,>=1.20
Requires-Dist: rich<16.0,>=15.0
Requires-Dist: scikit-learn<2.0,>=1.8.0
Requires-Dist: scipy<2.0,>=1.17.1
Requires-Dist: typer<1.0,>=0.24.1
Provides-Extra: all
Requires-Dist: clustpy<1.0,>=0.0.3; extra == 'all'
Requires-Dist: esm<3.3,>=3.2.1; (python_version < '3.12') and extra == 'all'
Requires-Dist: esm<4.0,>=3.4.1; (python_version >= '3.12') and extra == 'all'
Requires-Dist: httpx; (python_version < '3.12') and extra == 'all'
Requires-Dist: llvmlite>=0.46.0; extra == 'all'
Requires-Dist: numba>=0.64.0; extra == 'all'
Requires-Dist: sentencepiece<1.0,>=0.2.1; extra == 'all'
Requires-Dist: torch<3.0,>=2.10.0; extra == 'all'
Requires-Dist: transformers<5.0,>=4.48; extra == 'all'
Requires-Dist: umap-learn<1.0,>=0.5.9; extra == 'all'
Provides-Extra: embeddings
Requires-Dist: esm<3.3,>=3.2.1; (python_version < '3.12') and extra == 'embeddings'
Requires-Dist: esm<4.0,>=3.4.1; (python_version >= '3.12') and extra == 'embeddings'
Requires-Dist: httpx; (python_version < '3.12') and extra == 'embeddings'
Requires-Dist: sentencepiece<1.0,>=0.2.1; extra == 'embeddings'
Requires-Dist: torch<3.0,>=2.10.0; extra == 'embeddings'
Requires-Dist: transformers<5.0,>=4.48; extra == 'embeddings'
Provides-Extra: reductions
Requires-Dist: clustpy<1.0,>=0.0.3; extra == 'reductions'
Requires-Dist: llvmlite>=0.46.0; extra == 'reductions'
Requires-Dist: numba>=0.64.0; extra == 'reductions'
Requires-Dist: umap-learn<1.0,>=0.5.9; extra == 'reductions'
Description-Content-Type: text/markdown

# Sylphy 🧬
[![PyPI](https://img.shields.io/pypi/v/sylphy?style=flat-square)](https://pypi.org/project/sylphy/)
[![PyVersions](https://img.shields.io/pypi/pyversions/sylphy?style=flat-square)](https://github.com/kren-ai-lab/sylphy)
[![Tests](https://img.shields.io/github/actions/workflow/status/kren-ai-lab/sylphy/tests.yml?style=flat-square)](https://github.com/kren-ai-lab/sylphy/actions/workflows/tests.yml)
![License](https://img.shields.io/github/license/kren-ai-lab/sylphy?style=flat-square)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21819735-blue?style=flat-square)](https://doi.org/10.5281/zenodo.21819735)

Sylphy is a Python toolkit for turning protein sequences into machine-learning-ready representations.

It covers three main workflows:

- Classical sequence encoders: one-hot, ordinal, frequency, k-mers, physicochemical, FFT
- Embedding extraction from pretrained protein models: ESM2, ProtT5, ProtBERT, Ankh2, Mistral-Prot, ESM-C
- Dimensionality reduction for downstream analysis and visualization

## Installation

```bash
pip install sylphy
```

Install optional extras as needed:

- `embeddings` for PyTorch and Transformers-based embedding extraction
- `reductions` for UMAP and related optional reducers
- `all` for all optional runtime dependencies

The `reductions` extra may require a C++ compiler and Python development headers because of optional native dependencies such as ClustPy.

```bash
pip install 'sylphy[embeddings]'
pip install 'sylphy[all]'
```

On Debian or Ubuntu systems, install the build prerequisites with:

```bash
sudo apt-get install build-essential python3-dev
```

On Fedora or RHEL systems:

```bash
sudo dnf install gcc gcc-c++ python3-devel
```

## Quick Start

Classical sequence encoding:

```python
import polars as pl
from sylphy.sequence_encoder import create_encoder

df = pl.DataFrame({"sequence": ["MKTAYIAKQR", "GAVLIMPFWK", "PEPTIDE"]})

encoder = create_encoder(
    "one_hot",  # or: ordinal, kmers, frequency, physicochemical, fft
    dataset=df,
    sequence_column="sequence",
)
encoder.run_process()
encoded = encoder.coded_dataset
```

Embedding extraction:

```python
import polars as pl
from sylphy.embedding_extractor import create_embedding

df = pl.DataFrame({"sequence": ["MKTAYIAKQR", "GAVLIMPFWK", "PEPTIDE"]})

embedder = create_embedding(
    model_name="facebook/esm2_t6_8M_UR50D",
    dataset=df,
    column_seq="sequence",
    name_device="cuda",
    precision="fp16",  # fp32, fp16, or bf16
)

embedder.run_process(batch_size=8, pool="mean")  # mean, cls, or eos
embeddings = embedder.coded_dataset
embedder.export_encoder("embeddings.parquet")
```

Dimensionality reduction:

```python
from sylphy.reductions import reduce_dimensionality

model, reduced = reduce_dimensionality(
    method="pca",  # pca, truncated_svd, umap, tsne, isomap, etc.
    dataset=embeddings,
    n_components=2,
    random_state=42,
)
```

## CLI

```bash
sylphy --help

# Extract embeddings (ESM2, GPU, fp16)
sylphy embed \
  -i sequences.csv -o embeddings.parquet \
  -m facebook/esm2_t6_8M_UR50D -d cuda -p fp16 -b 16

# Extract embeddings (ProtT5, last 4 layers averaged)
sylphy embed \
  -i sequences.csv -o embeddings.npy \
  -m Rostlab/prot_t5_xl_uniref50 -d cuda -p bf16 --layers last4 --layer-agg mean

# Classical encoding — one-hot
sylphy encode --method one_hot -i sequences.csv -o encoded.parquet

# Classical encoding — physicochemical (AAIndex)
sylphy encode --method physicochemical \
  -i sequences.csv -o phys.parquet --name-property ARGP820101

# Classical encoding — k-mers TF-IDF
sylphy encode --method kmers -i sequences.csv -o kmers.csv -k 4

# Cache management
sylphy cache stats
sylphy cache ls --recursive
sylphy cache prune --max-size 10GB --apply
```

## Configuration

By default Sylphy stores cache data in the platform cache directory:

- Linux: `~/.cache/sylphy`
- macOS: `~/Library/Caches/sylphy`
- Windows: `%LOCALAPPDATA%\\sylphy\\Cache`

Useful environment variables:

- `SYLPHY_CACHE_ROOT` to override the cache location
- `SYLPHY_DEVICE` to force `cpu` or `cuda`
- `SYLPHY_MODEL_<NAME>` to override a registered model path

## Learn More

- [DEVELOPMENT.md](DEVELOPMENT.md) for local setup, tests, architecture, and contribution notes
- [examples/README.md](examples/README.md) for the examples index and runnable scripts/notebooks

## Citation

If you use Sylphy in your research, please cite:

> Medina-Ortiz, D.; Álvarez Saravia, D.; García-Vinuesa, J.
> *Sylphy: Protein Sequence Representation: Encoders, Embeddings, and Reductions*.
> Version 1.0.0, 2026. Zenodo.
> https://doi.org/10.5281/zenodo.21819735

```bibtex
@software{sylphy2026,
  author    = {Medina-Ortiz, David and Álvarez Saravia, Diego and García-Vinuesa, Julián},
  title     = {{Sylphy}: Protein Sequence Representation: Encoders, Embeddings, and Reductions},
  year      = {2026},
  version   = {1.0.0},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21819735},
  url       = {https://doi.org/10.5281/zenodo.21819735}
}
```

To cite this exact release, use the version DOI [10.5281/zenodo.21819736](https://doi.org/10.5281/zenodo.21819736).
Machine-readable metadata lives in [CITATION.cff](CITATION.cff).

## License

**MIT**. See [LICENSE](LICENSE).

## Acknowledgements

Built with the Hugging Face Transformers ecosystem, the Meta ESM-C SDK, and the broader scientific Python stack including scikit-learn, PyTorch, UMAP, and ClustPy.

Developed by **KREN AI Lab** at Universidad de Magallanes, Chile.
