selexprep 0.1.0__py3-none-any.whl

selexprep/__init__.py

@@ -0,0 +1,3 @@
+"""selexprep — accession-first preprocessing for public HT-SELEX datasets."""
+
+__version__ = "0.1.0"

selexprep/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for selexprep modules."""
+
+from __future__ import annotations
+
+import csv
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Canonical per-SRR FASTQ filename conventions produced by kingfisher /
+# sra-toolkit. Single-end runs produce `{srr}.fastq.gz`; paired-end runs
+# produce `{srr}_1.fastq.gz` and `{srr}_2.fastq.gz`. Match EXACTLY to avoid
+# prefix collisions (SRR1234 must not match SRR12345).
+
+
+def iter_srr_files(root: Path, srr: str, suffix: str = ".fastq.gz") -> list[Path]:
+    """Return FASTQ files for `srr` under `root`, matching exact filenames only.
+
+    Supports both single-end (`{srr}{suffix}`) and paired-end
+    (`{srr}_1{suffix}`, `{srr}_2{suffix}`) layouts.
+    """
+    if not root.exists():
+        return []
+    valid_names = {f"{srr}{suffix}", f"{srr}_1{suffix}", f"{srr}_2{suffix}"}
+    return [p for p in root.rglob(f"*{suffix}") if p.name in valid_names]
+
+
+def load_csv(path: Path) -> list[dict[str, str]]:
+    """Load a CSV file into a list of dicts. Returns `[]` if the file is missing."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return list(csv.DictReader(f))
+    except FileNotFoundError:
+        logging.getLogger(__name__).warning("File not found: %s", path)
+        return []
+
+
+def parse_round_number(parquet_path: Path) -> int | str:
+    """Extract the round number from a per-round parquet filename.
+
+    Handles `.counts.parquet` and `.clusters.parquet` suffixes. Returns the
+    integer round when the trailing token parses as int, otherwise returns
+    the bare stem (so callers can detect and route non-round files).
+    """
+    stem = parquet_path.stem.replace(".counts", "").replace(".clusters", "")
+    tail = stem.split("_")[-1]
+    try:
+        return int(tail)
+    except ValueError:
+        return stem
+
+
+def setup_logging(
+    logger_name: str,
+    log_dir: Path | None = None,
+    log_prefix: str | None = None,
+) -> logging.Logger:
+    """Configure root logging with optional rotating per-run file handler.
+
+    Idempotent: only attaches a stream handler once. When `log_dir` is given,
+    a timestamped log file is added on top of the stream handler.
+    """
+    root = logging.getLogger()
+    if not root.handlers:
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            handlers=[logging.StreamHandler(sys.stdout)],
+        )
+    if log_dir is not None:
+        log_dir.mkdir(exist_ok=True)
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        prefix = log_prefix or logger_name
+        fh = logging.FileHandler(log_dir / f"{prefix}_{ts}.log", encoding="utf-8")
+        fh.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s"))
+        root.addHandler(fh)
+    return logging.getLogger(logger_name)

selexprep/_io.py

@@ -0,0 +1,80 @@
+"""Deterministic I/O helpers for reproducible-output guarantees.
+
+The selexprep manifest promises bit-identical SHA256 across reruns for
+FASTA/FASTQ/TSV/JSON outputs. The default ``gzip.open`` writer embeds the
+current ``mtime`` in the gzip header, which breaks this guarantee silently.
+``open_gzip_text_deterministic`` forces ``mtime=0`` so the output bytes are
+reproducible across machines and across reruns on the same machine.
+
+See the plan's "Reproducible-output discipline" section: every ``.gz`` write
+must go through this module.
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import IO
+
+
+def open_gzip_text_deterministic(
+    path: Path,
+    encoding: str = "utf-8",
+) -> io.TextIOWrapper:
+    """Open a deterministic-gzip writer in text mode.
+
+    The gzip format normally embeds two non-deterministic bits in the header:
+
+    1. ``mtime`` — the wall-clock time of writing.
+    2. ``FNAME`` — the destination filename (so two runs writing to ``a.gz``
+       and ``b.gz`` produce different headers even for identical content).
+
+    We suppress both: ``mtime=0`` and an empty ``filename=""`` (with an
+    explicit ``fileobj``) prevent either field from making it into the
+    header. The resulting bytes depend only on the payload, so any two
+    invocations with the same content yield byte-for-byte identical output
+    — which is the property the manifest's SHA256 checks rely on.
+
+    The returned ``TextIOWrapper`` is the caller's to close. Closing it
+    cascades through the inner ``GzipFile`` to the underlying raw file
+    because we set ``gz.myfileobj = raw``, which is how stdlib ``gzip``
+    flags file ownership for its own close path.
+
+    Example::
+
+        with open_gzip_text_deterministic(Path("out.fastq.gz")) as fh:
+            fh.write("@read_0\\nACGT\\n+\\nIIII\\n")
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    raw = open(path, "wb")  # noqa: SIM115 — closed via GzipFile.myfileobj cascade
+    gz = gzip.GzipFile(filename="", mode="wb", mtime=0, fileobj=raw)
+    # Force GzipFile.close() to close `raw` for us so the caller-visible close
+    # on the TextIOWrapper produces a clean cascade with no file-handle leak.
+    gz.myfileobj = raw  # type: ignore[attr-defined]
+    return io.TextIOWrapper(gz, encoding=encoding, write_through=True)
+
+
+@contextmanager
+def write_gzip_text_deterministic(
+    path: Path,
+    encoding: str = "utf-8",
+) -> Iterator[IO[str]]:
+    """Context-managed version of :func:`open_gzip_text_deterministic`."""
+    fh = open_gzip_text_deterministic(path, encoding=encoding)
+    try:
+        yield fh
+    finally:
+        fh.close()
+
+
+def sha256_file(path: Path, chunk: int = 1 << 20) -> str:
+    """Stream-SHA256 a file in 1 MiB chunks (memory-bounded for multi-GB inputs)."""
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for block in iter(lambda: fh.read(chunk), b""):
+            h.update(block)
+    return h.hexdigest()

selexprep/benchmark/__init__.py

@@ -0,0 +1,20 @@
+"""Benchmark scaffolding for primer-recovery metrics + result tables.
+
+Public surface kept minimal — most callers should reach for the named
+functions in the submodules directly.
+"""
+
+from selexprep.benchmark.corpus_audit import (
+    CorpusAuditReport,
+    aggregate_audit_from_run_outputs,
+    sample_corpus,
+)
+from selexprep.benchmark.equivalence import EquivalenceResult, primer_equivalent
+
+__all__ = [
+    "CorpusAuditReport",
+    "EquivalenceResult",
+    "aggregate_audit_from_run_outputs",
+    "primer_equivalent",
+    "sample_corpus",
+]