roxylib 0.2.0__py3-none-any.whl

roxy/__init__.py

@@ -0,0 +1,26 @@
+"""Roxy — protein sequence descriptors for machine learning."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .core import (
+    RoxyError,
+    RoxyIOError,
+    read_fasta,
+    read_sequences,
+    write_table,
+)
+from .descriptors import DESCRIPTOR_REGISTRY, BaseDescriptor, register
+
+__all__ = [
+    "DESCRIPTOR_REGISTRY",
+    "BaseDescriptor",
+    "RoxyError",
+    "RoxyIOError",
+    "__version__",
+    "read_fasta",
+    "read_sequences",
+    "register",
+    "write_table",
+]

roxy/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Roxy CLI package."""
+
+from __future__ import annotations
+
+from .main import app
+
+__all__ = ["app"]

roxy/cli/_utils.py

@@ -0,0 +1,24 @@
+"""Shared CLI utilities."""
+
+from __future__ import annotations
+
+from roxy.descriptors import DESCRIPTOR_REGISTRY
+
+
+def _resolve_names(
+    all_: bool,
+    descriptors: list[str],
+    family: list[str],
+) -> list[str]:
+    if all_:
+        return sorted(DESCRIPTOR_REGISTRY)
+    names: list[str] = list(descriptors)
+    for fam in family:
+        names += [n for n, c in DESCRIPTOR_REGISTRY.items() if c.family == fam]
+    seen: set[str] = set()
+    result: list[str] = []
+    for n in names:
+        if n not in seen:
+            seen.add(n)
+            result.append(n)
+    return sorted(result)

roxy/cli/compute.py

@@ -0,0 +1,167 @@
+"""``roxy compute`` — run descriptors on a sequence file."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import polars as pl
+import typer
+import yaml
+
+from roxy.cli._utils import _resolve_names
+from roxy.core.exceptions import RoxyIOError
+from roxy.core.io import read_sequences, write_table
+from roxy.descriptors import DESCRIPTOR_REGISTRY
+
+if TYPE_CHECKING:
+    from roxy.descriptors.base import BaseDescriptor
+
+_BASE_COLS = {"length", "valid_residue_count"}
+
+
+def _load_config(path: Path) -> dict[str, dict[str, object]]:
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as exc:
+        msg = f"Invalid YAML in {path}: {exc}"
+        raise typer.BadParameter(msg) from exc
+
+    if not isinstance(raw, dict):
+        msg = "Config must be a YAML mapping of descriptor names to params."
+        raise typer.BadParameter(msg)
+
+    validated: dict[str, dict[str, object]] = {}
+    for name, raw_params in raw.items():
+        if name not in DESCRIPTOR_REGISTRY:
+            available = ", ".join(sorted(DESCRIPTOR_REGISTRY))
+            msg = f"Unknown descriptor {name!r}.\nAvailable: {available}"
+            raise typer.BadParameter(msg)
+        norm_params: dict[str, object] = raw_params or {}
+        if not isinstance(norm_params, dict):
+            msg = f"Params for {name!r} must be a mapping, got {type(norm_params).__name__}."
+            raise typer.BadParameter(msg)
+        sig = inspect.signature(DESCRIPTOR_REGISTRY[name].__init__)
+        valid = {k for k in sig.parameters if k != "self"}
+        unknown = set(norm_params) - valid
+        if unknown:
+            msg = (
+                f"Unknown param(s) for {name!r}: {', '.join(sorted(unknown))}.\n"
+                f"Valid: {', '.join(sorted(valid))}"
+            )
+            raise typer.BadParameter(msg)
+        validated[name] = dict(norm_params)
+    return validated
+
+
+def _build_instances(
+    config: dict[str, dict[str, object]] | None,
+    names: list[str],
+) -> list[tuple[str, BaseDescriptor]]:
+    if config is not None:
+        return [(n, DESCRIPTOR_REGISTRY[n](**p)) for n, p in config.items()]
+    return [(n, DESCRIPTOR_REGISTRY[n]()) for n in names]
+
+
+def _run_descriptors(
+    instances: list[tuple[str, BaseDescriptor]],
+    seqs: list[str],
+    ids: list[str],
+    *,
+    no_progress: bool,
+) -> tuple[list[pl.DataFrame], list[str]]:
+    frames: list[pl.DataFrame] = []
+    desc_names: list[str] = []
+
+    if no_progress:
+        for name, inst in instances:
+            frames.append(inst.compute(seqs, ids=ids))
+            desc_names.append(name)
+        return frames, desc_names
+
+    from rich.progress import Progress  # noqa: PLC0415
+
+    with Progress() as progress:
+        task = progress.add_task("Computing descriptors...", total=len(instances))
+        for name, inst in instances:
+            progress.update(task, description=f"[cyan]{name}[/cyan]")
+            frames.append(inst.compute(seqs, ids=ids))
+            desc_names.append(name)
+            progress.advance(task)
+    return frames, desc_names
+
+
+def _concat_frames(frames: list[pl.DataFrame], desc_names: list[str]) -> pl.DataFrame:
+    """Horizontally concat descriptor frames, keeping id and base cols only from first."""
+    _drop_from_rest = _BASE_COLS | {"id"}
+    parts: list[pl.DataFrame] = []
+    for i, (df, name) in enumerate(zip(frames, desc_names, strict=True)):
+        if i == 0:
+            rename = {f"{name}_{col}": col for col in _BASE_COLS if f"{name}_{col}" in df.columns}
+            parts.append(df.rename(rename))
+        else:
+            drop = [c for col in _drop_from_rest for c in (f"{name}_{col}", col) if c in df.columns]
+            parts.append(df.drop(drop))
+    return functools.reduce(pl.DataFrame.hstack, parts)
+
+
+def compute(  # noqa: PLR0917
+    input_path: Path = typer.Argument(..., metavar="INPUT", help="FASTA, CSV, or Parquet file."),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="YAML config file with descriptor params."
+    ),
+    all_: bool = typer.Option(False, "--all", help="Run all registered descriptors."),
+    descriptors: list[str] = typer.Option([], "--descriptor", "-d", help="Descriptor name (repeatable)."),
+    family: list[str] = typer.Option(
+        [], "--family", "-f", help="Family name — runs all descriptors in it (repeatable)."
+    ),
+    output: Path = typer.Option(..., "--output", "-o", help="Output file (.csv or .parquet)."),
+    seq_col: str = typer.Option("sequence", "--seq-col", help="Sequence column name (CSV/Parquet)."),
+    id_col: str | None = typer.Option(None, "--id-col", help="ID column to preserve (CSV/Parquet)."),
+    no_progress: bool = typer.Option(False, "--no-progress", help="Disable progress bar."),
+) -> None:
+    """Compute descriptors for sequences in INPUT and write to OUTPUT."""
+    if config is not None and (all_ or descriptors or family):
+        typer.echo("--config is mutually exclusive with --all / -d / -f.", err=True)
+        raise typer.Exit(1)
+
+    if config is not None:
+        cfg = _load_config(config)
+        instances = _build_instances(cfg, [])
+    else:
+        names = _resolve_names(all_, descriptors, family)
+        if not names:
+            typer.echo("Specify --config, --all, -d <name>, or -f <family>.", err=True)
+            raise typer.Exit(1)
+        unknown = [n for n in names if n not in DESCRIPTOR_REGISTRY]
+        if unknown:
+            typer.echo(f"Unknown descriptors: {', '.join(unknown)}", err=True)
+            raise typer.Exit(1)
+        instances = _build_instances(None, names)
+
+    try:
+        records = read_sequences(input_path, seq_col=seq_col, id_col=id_col)
+    except RoxyIOError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    ids = [r[0] for r in records]
+    seqs = [r[1] for r in records]
+
+    try:
+        frames, desc_names = _run_descriptors(instances, seqs, ids, no_progress=no_progress)
+    except Exception as exc:
+        typer.echo(f"Error computing descriptors: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+    result = _concat_frames(frames, desc_names)
+
+    try:
+        write_table(result, output)
+    except RoxyIOError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(f"Wrote {result.shape[0]} sequences x {result.shape[1]} features → {output}")

roxy/cli/describe_descriptor.py

@@ -0,0 +1,101 @@
+"""``roxy describe`` — show full details for a registered descriptor."""
+
+from __future__ import annotations
+
+import inspect
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from roxy.core.constants import AA20_ORDERED
+from roxy.descriptors import DESCRIPTOR_REGISTRY
+
+_SEQ = "".join(AA20_ORDERED)
+
+
+def _parse_google_args(doc: str) -> dict[str, str]:
+    """Extract param descriptions from a Google-style Args section."""
+    args: dict[str, str] = {}
+    in_args = False
+    current: str | None = None
+    parts: list[str] = []
+
+    for line in doc.splitlines():
+        stripped = line.strip()
+        if stripped == "Args:":
+            in_args = True
+            continue
+        if not in_args:
+            continue
+        # New top-level section ends Args
+        if stripped and not line.startswith(" "):
+            break
+        # Param line: exactly 4-space indent with ": "
+        if line.startswith("    ") and not line.startswith("        ") and ": " in stripped:
+            if current is not None:
+                args[current] = " ".join(parts)
+            param, _, desc = stripped.partition(": ")
+            current, parts = param.strip(), [desc.strip()]
+        elif line.startswith("        ") and current is not None:
+            parts.append(stripped)
+
+    if current is not None:
+        args[current] = " ".join(parts)
+    return args
+
+
+def _summary(doc: str) -> str:
+    return doc.splitlines()[0] if doc else ""
+
+
+def describe_descriptor(name: str = typer.Argument(..., help="Descriptor name.")) -> None:
+    """Show family, parameters, column count, and column names for a descriptor."""
+    cls = DESCRIPTOR_REGISTRY.get(name)
+    if cls is None:
+        available = ", ".join(sorted(DESCRIPTOR_REGISTRY))
+        typer.echo(f"Unknown descriptor: {name!r}\nAvailable: {available}", err=True)
+        raise typer.Exit(1)
+
+    console = Console()
+
+    doc = inspect.getdoc(cls) or ""
+    sig = inspect.signature(cls.__init__)
+    params = {k: v for k, v in sig.parameters.items() if k != "self"}
+    arg_descs = _parse_google_args(doc)
+
+    inst = cls()
+    columns = list(inst.compute_one(_SEQ))
+
+    header = Text()
+    header.append(name, style="bold cyan")
+    header.append(f"  [{cls.family}]", style="green")
+    console.print(header)
+    console.print()
+    if doc:
+        console.print(_summary(doc))
+        console.print()
+
+    if params:
+        ptable = Table(show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0))
+        ptable.add_column("Parameter")
+        ptable.add_column("Default")
+        ptable.add_column("Annotation")
+        ptable.add_column("Description")
+        for pname, p in params.items():
+            default = "" if p.default is inspect.Parameter.empty else repr(p.default)
+            ann = "" if p.annotation is inspect.Parameter.empty else str(p.annotation)
+            desc = arg_descs.get(pname, "")
+            ptable.add_row(pname, default, ann, f"[dim]{desc}[/dim]")
+        console.print(Panel(ptable, title="Parameters", title_align="left"))
+
+    col_text = "  ".join(f"[dim]{c}[/dim]" for c in columns)
+    console.print(
+        Panel(
+            f"[bold]{len(columns)} columns[/bold] (default parameters)\n\n{col_text}",
+            title="Output columns",
+            title_align="left",
+        )
+    )

roxy/cli/init_config.py

@@ -0,0 +1,61 @@
+"""``roxy init-config`` — generate a YAML config with descriptor defaults."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from pathlib import Path
+
+import typer
+import yaml
+
+from roxy.cli._utils import _resolve_names
+from roxy.descriptors import DESCRIPTOR_REGISTRY
+
+
+def _default_params(cls: type) -> dict[str, object]:
+    sig = inspect.signature(cls.__init__)
+    return {
+        name: param.default
+        for name, param in sig.parameters.items()
+        if name != "self" and param.default is not inspect.Parameter.empty
+    }
+
+
+def init_config(
+    all_: bool = typer.Option(False, "--all", help="Include all registered descriptors."),
+    descriptors: list[str] = typer.Option([], "--descriptor", "-d", help="Descriptor name (repeatable)."),
+    family: list[str] = typer.Option([], "--family", "-f", help="Family name (repeatable)."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Output file (default: stdout)."),
+) -> None:
+    """Generate a YAML config file populated with descriptor defaults."""
+    names = _resolve_names(all_, descriptors, family)
+
+    if not names:
+        typer.echo("Specify --all, -d <name>, or -f <family>.", err=True)
+        raise typer.Exit(1)
+
+    unknown = [n for n in names if n not in DESCRIPTOR_REGISTRY]
+    if unknown:
+        typer.echo(f"Unknown descriptors: {', '.join(unknown)}", err=True)
+        raise typer.Exit(1)
+
+    header = (
+        "# Roxy descriptor configuration\n"
+        "# Edit parameters, then run:\n"
+        "#   roxy compute sequences.fasta --config <this-file> -o results.parquet\n"
+        "# Use 'roxy describe <name>' for parameter documentation.\n"
+    )
+    config_map = {name: _default_params(DESCRIPTOR_REGISTRY[name]) for name in names}
+    body = yaml.safe_dump(
+        config_map,
+        sort_keys=False,
+        default_flow_style=False,
+    )
+    content = header + "\n" + body
+
+    if output is None:
+        sys.stdout.write(content)
+    else:
+        output.write_text(content)
+        typer.echo(f"Config written to {output}")

roxy/cli/list_descriptors.py

@@ -0,0 +1,78 @@
+"""``roxy list`` — display all registered descriptor families."""
+
+from __future__ import annotations
+
+import inspect
+import textwrap
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from roxy.descriptors import DESCRIPTOR_REGISTRY
+
+
+def _descriptor_lines(
+    name: str,
+    summary: str,
+    *,
+    name_width: int,
+    desc_width: int,
+) -> list[Text]:
+    desc_lines = textwrap.wrap(summary, width=desc_width) or [""]
+    lines: list[Text] = []
+    for idx, desc_line in enumerate(desc_lines):
+        line = Text()
+        if idx == 0:
+            line.append(f"{name:<{name_width}}", style="cyan")
+        else:
+            line.append(" " * name_width)
+        line.append("  ")
+        line.append(desc_line, style="dim")
+        lines.append(line)
+    return lines
+
+
+def list_descriptors(
+    family: str | None = typer.Option(None, "--family", "-f", help="Filter by family name."),
+) -> None:
+    """List all registered descriptors grouped by family."""
+    entries = sorted(DESCRIPTOR_REGISTRY.items())
+    if family:
+        entries = [(n, c) for n, c in entries if c.family == family]
+
+    if not entries:
+        Console().print("[yellow]No descriptors registered.[/yellow]")
+        raise typer.Exit
+
+    families: dict[str, list[tuple[str, type]]] = {}
+    for name, cls in entries:
+        families.setdefault(cls.family, []).append((name, cls))
+
+    total = sum(len(v) for v in families.values())
+    max_name = max(len(n) for n, _ in entries)
+    console = Console()
+    console.print(f"[bold]Roxy descriptors[/bold] ({total})")
+
+    for fam in sorted(families):
+        descriptors = families[fam]
+        title = Text()
+        title.append(fam, style="bold green")
+        title.append(f" ({len(descriptors)})", style="dim")
+        console.print()
+        console.print(title)
+
+        desc_width = max(24, console.width - max_name - 2)
+        for name, cls in descriptors:
+            doc = inspect.getdoc(cls) or ""
+            first_line = doc.splitlines()[0] if doc else ""
+            for line in _descriptor_lines(
+                name,
+                first_line,
+                name_width=max_name,
+                desc_width=desc_width,
+            ):
+                console.print(line)
+
+    console.print()
+    console.print("[dim]Use [bold]roxy describe <name>[/bold] for full details.[/dim]")

roxy/cli/main.py

@@ -0,0 +1,65 @@
+"""Roxy CLI entrypoint."""
+
+from __future__ import annotations
+
+import typer
+
+from roxy import __version__
+from roxy.cli.compute import compute
+from roxy.cli.describe_descriptor import describe_descriptor
+from roxy.cli.init_config import init_config
+from roxy.cli.list_descriptors import list_descriptors
+
+_HELP_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+app = typer.Typer(
+    name="roxy",
+    add_completion=False,
+    context_settings=_HELP_CONTEXT_SETTINGS,
+    help="Roxy — protein sequence descriptors for ML.",
+)
+
+
+def _version_callback(value: bool | None) -> None:
+    if value:
+        typer.echo(f"roxy {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    _version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Roxy CLI main callback."""
+
+
+app.command(
+    name="list",
+    help="List all registered descriptors grouped by family.",
+)(list_descriptors)
+
+app.command(
+    name="describe",
+    help="Show full details for a descriptor.",
+)(describe_descriptor)
+
+app.command(
+    name="compute",
+    help="Compute descriptors for sequences in a file.",
+)(compute)
+
+app.command(
+    name="init-config",
+    help="Generate a YAML config file populated with descriptor defaults.",
+)(init_config)
+
+
+if __name__ == "__main__":
+    app()

roxy/core/__init__.py

@@ -0,0 +1,17 @@
+"""Roxy core package."""
+
+from __future__ import annotations
+
+from .exceptions import (
+    RoxyError,
+    RoxyIOError,
+)
+from .io import read_fasta, read_sequences, write_table
+
+__all__ = [
+    "RoxyError",
+    "RoxyIOError",
+    "read_fasta",
+    "read_sequences",
+    "write_table",
+]