roxylib 0.2.0__tar.gz

roxylib-0.2.0/.github/workflows/examples.yml

@@ -0,0 +1,30 @@
+name: examples
+
+on:
+  push:
+    paths:
+      - "roxy/**"
+      - "examples/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/examples.yml"
+  pull_request:
+    paths:
+      - "roxy/**"
+      - "examples/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/examples.yml"
+
+jobs:
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run examples
+        run: bash examples/run_ci_examples.sh

roxylib-0.2.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,17 @@
+name: pre-commit
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  prek:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - uses: j178/prek-action@v2

roxylib-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,48 @@
+name: publish-pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/roxylib
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

roxylib-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    paths:
+      - "roxy/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/tests.yml"
+  pull_request:
+    paths:
+      - "roxy/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/tests.yml"
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run tests
+        run: uv run pytest -q

roxylib-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Tools
+.ruff_cache/
+.mypy_cache/
+
+# uv
+.uv-cache/
+.uv_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDEs
+.idea/
+.vscode/
+
+# OS
+.DS_Store

roxylib-0.2.0/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Project Overview
+
+**Roxy** is a Python library for computing classical protein sequence descriptors for machine learning workflows. It sits between:
+
+- **Sylphy** (sequence encoders and embeddings) — parallel; Roxy does NOT duplicate Sylphy's one-hot/ordinal/k-mers/FFT encoders
+
+**Roxy scope**: classical descriptors only. Input: amino-acid sequences (strings). Output: `polars.DataFrame` of numerical features.
+
+This project uses `uv` and `taskipy` — see `DEVELOPMENT.md` for setup and task commands.
+
+## Descriptor Architecture
+
+New descriptor families follow this pattern:
+
+```python
+from roxy.descriptors import BaseDescriptor, register
+
+@register("aac", family="composition")
+class AACDescriptor(BaseDescriptor):
+    def compute_one(self, sequence: str) -> dict[str, float]:
+        ...
+```
+
+- `compute_one` returns unprefixed feature names (`{"A": 0.05, "C": 0.02, ...}`).
+- `compute(sequences, ids=...)` calls `compute_one` per sequence and returns a DataFrame with columns prefixed by `{name}_`.
+- Register families by importing the module in `descriptors/__init__.py`.
+
+## Key Invariants
+
+- Descriptors must be stateless or only hold configuration (no mutable global state).
+- `compute_one` must handle empty or non-standard sequences gracefully (return NaN, not raise).
+- Never import EDA, projection, or visualisation libraries — those are out of scope.
+- AAIndex CSV is bundled in `roxy/data/aaindex.csv` and loaded via `importlib.resources`. No download or cache path needed.

roxylib-0.2.0/DEVELOPMENT.md

@@ -0,0 +1,52 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.11–3.14
+- [uv](https://docs.astral.sh/uv/) (package manager)
+
+## Setup
+
+```bash
+git clone https://github.com/ProteinEngineering-PESB2/roxy_library
+cd roxy_library
+uv sync --all-extras
+```
+
+## Common Tasks
+
+```bash
+uv run task format      # sort imports + ruff format
+uv run task lint        # ruff check (no fixes)
+uv run task lint-fix    # ruff check --fix
+uv run task test        # pytest -q
+uv run task test-v      # pytest -v
+uv run task test-cov    # pytest + HTML coverage report
+```
+
+## Running the CLI
+
+```bash
+uv run roxy --version
+uv run roxy --help
+uv run roxy list
+```
+
+## Adding a Descriptor Family
+
+1. Create `roxy/descriptors/<family_name>/<module>.py`.
+2. Implement a class inheriting `BaseDescriptor` and decorate with `@register`.
+3. Import the module in `roxy/descriptors/__init__.py` so the decorator fires.
+4. Add tests in `tests/descriptors/<family_name>/`.
+
+See `AGENTS.md` for the full list of families and their source notebooks in `dev_notebooks/`.
+
+## Project Structure
+
+See `AGENTS.md` for the full package layout.
+
+## Branches
+
+- `main` — stable releases
+- `refactor/cleanup-base` — current base refactor (S1)
+- `feat/descriptors-<family>` — individual descriptor families (S2/S3)

roxylib-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kren AI Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roxylib-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+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

roxylib-0.2.0/README.md

@@ -0,0 +1,123 @@
+# 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

roxylib-0.2.0/examples/basic_api.py

@@ -0,0 +1,30 @@
+"""Basic Python API example for Roxy."""
+
+from __future__ import annotations
+
+from roxy import DESCRIPTOR_REGISTRY
+
+
+def main() -> None:
+    """Compute a simple descriptor block from Python."""
+    sequences = [
+        "MKWVTFISLLFLFSSAYSRGVFRR",
+        "GAVLKVLTTGLPALISWIKRKRQQ",
+        "DDDEEEGGGSSSNNNQQQ",
+    ]
+    ids = ["albumin_like", "signal_peptide_like", "acidic_low_complexity"]
+
+    descriptor = DESCRIPTOR_REGISTRY["aac"]()
+    features = descriptor.compute(sequences, ids=ids)
+
+    assert features.height == 3
+    assert "id" in features.columns
+    assert "aac_length" in features.columns
+    assert "aac_freq_A" in features.columns
+
+    print("basic_api.py")
+    print(features.select(["id", "aac_length", "aac_freq_A", "aac_freq_K"]))
+
+
+if __name__ == "__main__":
+    main()

roxylib-0.2.0/examples/cli_roundtrip.py

@@ -0,0 +1,91 @@
+"""CLI example that writes a config and computes features from FASTA."""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+import polars as pl
+
+from roxy import read_fasta
+
+FASTA_TEXT = """>seq1
+MKWVTFISLLFLFSSAYSRGVFRR
+>seq2
+GAVLKVLTTGLPALISWIKRKRQQ
+>seq3
+DDDEEEGGGSSSNNNQQQ
+"""
+
+
+def _run(*args: str, cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        args,
+        cwd=cwd,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def main() -> None:
+    """Exercise `roxy init-config` and `roxy compute` end to end."""
+    repo_root = Path(__file__).resolve().parents[1]
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        fasta_path = tmp_path / "toy_sequences.fasta"
+        config_path = tmp_path / "toy_config.yaml"
+        output_path = tmp_path / "toy_features.csv"
+
+        fasta_path.write_text(FASTA_TEXT, encoding="utf-8")
+
+        _run(
+            "uv",
+            "run",
+            "roxy",
+            "init-config",
+            "-d",
+            "aac",
+            "-d",
+            "charge",
+            "-o",
+            str(config_path),
+            cwd=repo_root,
+        )
+
+        config_text = config_path.read_text(encoding="utf-8")
+        config_text = config_text.replace("include_counts: true", "include_counts: false")
+        config_path.write_text(config_text, encoding="utf-8")
+
+        _run(
+            "uv",
+            "run",
+            "roxy",
+            "compute",
+            str(fasta_path),
+            "--config",
+            str(config_path),
+            "-o",
+            str(output_path),
+            "--no-progress",
+            cwd=repo_root,
+        )
+
+        records = read_fasta(fasta_path)
+        df = pl.read_csv(output_path)
+
+        assert len(records) == 3
+        assert df.height == 3
+        assert "length" in df.columns
+        assert "aac_freq_A" in df.columns
+        assert "aac_count_A" not in df.columns
+        assert "charge_net_charge_ph5p0" in df.columns
+
+        print("cli_roundtrip.py")
+        print(df.select(["id", "length", "aac_freq_A", "charge_net_charge_ph5p0"]))
+
+
+if __name__ == "__main__":
+    main()