Metadata-Version: 2.5
Name: roxylib
Version: 0.2.0
Summary: Protein sequence descriptors for machine learning.
Project-URL: Homepage, https://github.com/kren-ai-lab/roxy
Project-URL: Repository, https://github.com/kren-ai-lab/roxy
Project-URL: Issues, https://github.com/kren-ai-lab/roxy/issues
Author-email: Kren AI Lab <krenai@umag.cl>
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,descriptors,feature-engineering,machine-learning,proteins
Classifier: Development Status :: 3 - Alpha
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 :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy<3.0,>=2.4
Requires-Dist: polars>=1.40.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich<16.0,>=15.0
Requires-Dist: scikit-learn<2.0,>=1.8
Requires-Dist: scipy<2.0,>=1.17
Requires-Dist: typer<1.0,>=0.27
Description-Content-Type: text/markdown

# Roxy

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

Classical protein sequence descriptors for machine learning.

Roxy computes classical numerical descriptors from amino-acid sequences and
returns tabular features as `polars.DataFrame` objects.

## Install

```bash
pip install roxylib
# or with uv:
uv add roxylib
```

## Quickstart

```python
from roxy import read_fasta, DESCRIPTOR_REGISTRY

# Load sequences from FASTA
records = read_fasta("sequences.fasta")  # [(id, seq), ...]
sequences = [seq for _, seq in records]
ids = [seq_id for seq_id, _ in records]

descriptor = DESCRIPTOR_REGISTRY["aac"]()
features = descriptor.compute(sequences, ids=ids)  # polars.DataFrame
```

For direct Python use, descriptors are importable by family:

```python
from roxy.descriptors.aaindex import AAIndexDescriptor
from roxy.descriptors.composition import KmerFullAlphabetDescriptor
from roxy.descriptors.physicochemical import ChargeDescriptor

kmer = KmerFullAlphabetDescriptor(k=2)
aaindex = AAIndexDescriptor()
charge = ChargeDescriptor()

kmer_features = kmer.compute(["ACDEFGHIK"])
aaindex_features = aaindex.compute(["ACDEFGHIK"])
charge_features = charge.compute(["ACDEFGHIK"])
```

## CLI

```bash
roxy --help
roxy --version

# List and inspect descriptors
roxy list
roxy list --family composition
roxy describe aac

# Compute descriptors from FASTA, CSV, or Parquet input
roxy compute sequences.fasta -d aac -d charge -o features.csv
roxy compute sequences.fasta -f composition -o composition.parquet
roxy compute sequences.csv -d aac --seq-col sequence --id-col id -o features.csv
roxy compute sequences.fasta --all -o all_features.parquet

# Generate and use a YAML config with descriptor parameters
roxy init-config -d aac -d charge -o roxy.yaml
roxy init-config -f composition -o composition.yaml
roxy init-config --all -o all_descriptors.yaml
roxy compute sequences.fasta --config roxy.yaml -o configured_features.csv
```

`roxy compute` requires exactly one descriptor selector: `--config`, `--all`,
`--descriptor/-d`, or `--family/-f`. CSV and Parquet inputs use `sequence` as
the default sequence column; pass `--seq-col` and `--id-col` when needed.

## Examples

The repository ships a few plain Python scripts under [`examples/`](examples):

- `examples/basic_api.py` for direct descriptor use from Python
- `examples/configured_descriptors.py` for parameterized descriptor instances
- `examples/cli_roundtrip.py` for an end-to-end CLI config and compute flow

Run them with:

```bash
bash examples/run_ci_examples.sh
```

## Descriptor Families

Registry keys are the names used by `roxy compute -d`, config files, and output
column prefixes.

| Family          | Descriptor keys                                                                       |
|-----------------|---------------------------------------------------------------------------------------|
| aaindex         | `aaindex`                                                                             |
| autocorrelation | `autocorrelation`                                                                     |
| complexity      | `entropy_complexity`, `local_repetition`, `run_blockiness`                            |
| composition     | `aac`, `compositional_bias`, `dpc`, `grouped`, `kmer_full_alphabet`                   |
| ctd             | `ctd_classic`, `distribution`                                                         |
| hybrid          | `family_summary`                                                                      |
| motif           | `functional_residue_content`, `pattern`, `spacing`, `user_regex`                      |
| physicochemical | `charge`, `global_basic`, `hydrophobicity`, `order_disorder`, `structural_propensity` |
| positional      | `normalized`, `sliding_window`, `terminal`                                            |
| pseudo          | `pseaac`, `qso`, `sequence_order`                                                     |

## Development

```bash
uv sync
uv run pytest -q
uv run task lint
uv run roxy --help
```

## Related Projects

- [Sylphy](https://github.com/kren-ai-lab/sylphy) — sequence encoders and pretrained model embeddings
