Classical protein sequence descriptors for machine learning.
Roxy computes classical numerical descriptors from amino-acid sequences and
returns tabular features as polars.DataFrame objects.
pip install roxylib
# or with uv:
uv add roxylibfrom 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.DataFrameFor direct Python use, descriptors are importable by family:
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"])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 --jsonroxy 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.
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:
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.
The repository ships a few plain Python scripts under examples/:
examples/basic_api.pyfor direct descriptor use from Pythonexamples/configured_descriptors.pyfor parameterized descriptor instancesexamples/cli_roundtrip.pyfor an end-to-end CLI config and compute flow
Run them with:
bash examples/run_ci_examples.shRegistry 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 |
uv sync
uv run pytest -q
uv run task lint
uv run roxy --help- Sylphy — sequence encoders and pretrained model embeddings
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
@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. Machine-readable metadata lives in CITATION.cff.