Metadata-Version: 2.5
Name: roxylib
Version: 0.3.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: David Medina-Ortiz, Diego Alvarez Saravia, Julián García-Vinuesa
Maintainer: David Medina-Ortiz, Diego Alvarez Saravia, Julián García-Vinuesa
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/roxy)
[![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

# Check a config file without reading any data
roxy validate-config roxy.yaml
roxy validate-config roxy.yaml --json
```

`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` when needed.

Record ids: in FASTA the id is the first whitespace-delimited token of the header. CSV and Parquet inputs need an id column, `id` by default or the one named by `--id-col`; there are no positional fallback ids. A missing id column, or empty or duplicated ids, is an error.

The `--config` file nests descriptor parameters under `descriptors:` (`schema_version` is optional). The old flat shape, with descriptor names at the root, is rejected.

```yaml
schema_version: 1
descriptors:
  aac:
    include_counts: false
  charge: {}
```

`roxy validate-config CONFIG` collects every problem (unknown keys, descriptors or parameters, wrongly typed or rejected values) and prints one `path: message` line per problem to stderr, or a JSON array of `{path, message}` on stdout with `--json`. It exits 0 if the config is valid and 2 otherwise. `roxy compute --config` applies the same checks.

Validate a config from Python:

```python
from roxy import ConfigIssue, validate_config

issues = validate_config("roxy.yaml")  # or a mapping with the same structure
for issue in issues:
    print(issue.path, issue.message)
```

`validate_config` returns a list of `ConfigIssue(path, message)`, empty when valid. A missing or unparsable file is one issue with path `""`.

Exit codes: 0 success, 2 usage or config error, 3 data or runtime error (for example unreadable input), 4 internal error (traceback on stderr).

Every successful `roxy compute` also writes a provenance sidecar,
`<output>.provenance.json`, next to the output file. It records the effective
descriptor parameters (defaults included), a config fingerprint, input and
output hashes, and package versions.

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

## Citation

If you use Roxy in your research, please cite:

> Medina-Ortiz, D.; Álvarez Saravia, D.; García-Vinuesa, J.
> *Roxy: Classical Protein Sequence Descriptors for Machine Learning*.
> Version 0.3.0, 2026. Zenodo.
> https://doi.org/10.5281/zenodo.21917534

```bibtex
@software{roxy2026,
  author    = {Medina-Ortiz, David and Álvarez Saravia, Diego and García-Vinuesa, Julián},
  title     = {{Roxy}: Classical Protein Sequence Descriptors for Machine Learning},
  year      = {2026},
  version   = {0.3.0},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21917534},
  url       = {https://doi.org/10.5281/zenodo.21917534}
}
```

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