Metadata-Version: 2.4
Name: sylphy
Version: 0.2.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: GPL-3.0-only
License-File: LICENSE
Keywords: AAindex,ESM,ProtBERT,ProtT5,bioinformatics,dimension-reduction,embeddings,k-mers,protein,transformers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.13,>=3.11
Requires-Dist: appdirs<2.0,>=1.4.4
Requires-Dist: huggingface-hub<2.0,>=0.36.0
Requires-Dist: numpy<3.0,>=2.3.5
Requires-Dist: pandas<4.0,>=3.0.1
Requires-Dist: requests<3.0,>=2.32.5
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.2; extra == 'all'
Requires-Dist: esm<4.0,>=3.2.1; extra == 'all'
Requires-Dist: fastparquet>=2024.11.0; extra == 'all'
Requires-Dist: llvmlite>=0.46.0; extra == 'all'
Requires-Dist: numba>=0.64.0; extra == 'all'
Requires-Dist: pyarrow>=23.0.1; 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: dev
Requires-Dist: pyrefly>=0.60.0; extra == 'dev'
Requires-Dist: pytest~=9.0.2; extra == 'dev'
Requires-Dist: ruff~=0.15.5; extra == 'dev'
Requires-Dist: taskipy~=1.14.0; extra == 'dev'
Requires-Dist: ty>=0.0.30; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: esm<4.0,>=3.2.1; 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: parquet
Requires-Dist: fastparquet>=2024.11.0; extra == 'parquet'
Requires-Dist: pyarrow>=23.0.1; extra == 'parquet'
Provides-Extra: reductions
Requires-Dist: clustpy<1.0,>=0.0.2; 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'
Provides-Extra: tests
Requires-Dist: pytest-cov~=7.1.0; extra == 'tests'
Requires-Dist: pytest~=9.0.2; extra == 'tests'
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)

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

Sylphy supports Python 3.11 and 3.12.

```bash
pip install sylphy
```

Install optional extras as needed:

- `embeddings` for PyTorch and Transformers-based embedding extraction
- `parquet` for Parquet export support
- `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,parquet]'
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 pandas as pd
from sylphy.sequence_encoder import create_encoder

df = pd.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 pandas as pd
from sylphy.embedding_extractor import create_embedding

df = pd.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

sylphy get-embedding \
  --model facebook/esm2_t6_8M_UR50D \
  --input-data sequences.csv \
  --sequence-identifier sequence \
  --output embeddings.parquet \
  --device cuda --precision fp16 --batch-size 16

sylphy encode-sequences \
  --encoder one_hot \
  --input-data sequences.csv \
  --sequence-identifier sequence \
  --output encoded.csv

sylphy cache stats
```

## 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

## License

**GPL-3.0-only**. 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.
