selexprep 0.1.0__tar.gz

selexprep-0.1.0/.claudeignore

@@ -0,0 +1,33 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+htmlcov/
+coverage.xml
+
+# Caches (regenerated on demand)
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+
+# Lockfile — large; regenerated by `uv sync`. Excluding keeps a fresh
+# Claude session from indexing thousands of resolved-package entries.
+uv.lock
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Built docs (the source is in docs/, not docs/site/)
+docs/site/
+site/
+
+# Local scratch
+scratch/
+tmp/
+*.log

selexprep-0.1.0/.dockerignore

@@ -0,0 +1,23 @@
+# Keep the Docker build context small and reproducible: only pyproject,
+# README, LICENSE, and src/ are needed to build the wheel (see Dockerfile).
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+htmlcov
+.coverage
+coverage.xml
+dist
+build
+*.egg-info
+docs
+site
+examples
+tests
+benchmarks
+*.sif

selexprep-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    if: github.event_name == 'release'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

selexprep-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,47 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Type-check with mypy
+        run: mypy src/
+
+      - name: Run pytest with coverage
+        run: pytest --cov=selexprep --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

selexprep-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+build/
+dist/
+wheels/
+
+# Testing & coverage
+.pytest_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Type-checking & linting
+.mypy_cache/
+.ruff_cache/
+
+# Snakemake (created by --dry-run too — both repo-root and benchmarks/)
+.snakemake/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.python-version
+
+# Environment files
+.env
+.env.local
+
+# Documentation
+docs/site/
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local data / scratch
+scratch/
+tmp/
+*.log
+
+# Benchmark candidate-curation: local-only tools + scratch (not package content;
+# the curation decisions they produced are captured in the committed evidence
+# files: ground_truth.tsv / read_state_evidence.tsv / screening_log.tsv)
+benchmarks/screen_read_state.py
+benchmarks/*_screen.tsv
+
+# Project-metadata builder API caches (regenerable from OpenAlex / figshare / Zenodo)
+benchmarks/.oa_cache.json
+benchmarks/.discovery_doi_cache.json
+
+# Example run artifacts — notebooks self-generate demo/, run_public_accession.sh writes demo_public/
+examples/**/demo*/
+.ipynb_checkpoints/
+
+# Transient HPC run-result tarballs (scp'd back for analysis, not repo content)
+full_list_*.tar.gz

selexprep-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.0
+          - types-pyyaml
+          - types-requests
+        args: [--config-file=pyproject.toml]
+        files: ^src/

selexprep-0.1.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `selexprep` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+_No unreleased changes yet._
+
+## [0.1.0] - 2026-06-13
+
+First public release: accession-first preprocessing for high-throughput SELEX
+(HT-SELEX) sequencing deposits, with automatic primer / constant-region
+inference. Give it an INSDC accession (ENA / SRA / DDBJ) and it fetches the
+runs, infers the library's flanking constants from the reads, and extracts the
+random regions — no manual primer entry required.
+
+### Added
+
+- **Command-line interface** (`selexprep <verb>`):
+  - `inspect` — summarize an accession's runs and metadata.
+  - `fetch` — download FASTQs for an accession (ENA-direct by default).
+  - `detect` — infer the 5′/3′ constant regions (primers) from the reads.
+  - `extract` — strip the inferred constants and emit the random-region reads.
+  - `count` — collapse extracted reads to unique-sequence counts per round.
+  - `qc` — quality-control flags and plots.
+  - `run` — end-to-end fetch → detect → extract → count, with `--resume`.
+  - `catalog` — browse the bundled discovery catalog of SELEX deposits.
+- **Primer / constant-region inference** (`detect`): position-anchored
+  consensus over the read pool, with a typed `LibraryReport` describing the
+  inferred 5′/3′ constants, random-region length, match rates, read state
+  (raw vs. pre-trimmed), and a confidence-graded status. Cross-round inference
+  reconciles evidence across selection rounds.
+- **Adapter awareness**: known Illumina sequencing adapters (e.g. TruSeq) are
+  recorded where present and excluded from primer candidates, so adapter
+  read-through is reported as diagnostic information rather than mistaken for a
+  library constant.
+- **`extract`**: paired-end handling, strand-orientation detection, and
+  per-mode adapter handling. cutadapt is invoked as a subprocess (its CLI is
+  the stable contract). Supports `--override-primer-{5p,3p}` to bypass
+  inference, and a rebuild path for manually corrected primers.
+- **Discovery catalog** (`catalog`): a bundled, refreshable index of public
+  SELEX deposits built from INSDC `library_strategy="SELEX"` queries, with
+  per-run and per-BioProject strategy filtering and manual exclusions for
+  mislabelled deposits.
+- **Quality control** (`qc`): diversity / rarefaction helpers and depth-aware
+  flags (e.g. unexpected rarefied-diversity increase, modal-length spread,
+  orientation skew, low read depth, adapter contamination).
+- **Deterministic outputs**: all gzip writes are byte-identical across reruns
+  (gzip header `mtime=0`) and JSON is written with sorted keys, so a
+  `SelexprepManifestV1` run manifest carries reproducible `sha256` hashes.
+- **Benchmark suite** (under `benchmarks/`, not shipped on PyPI): a Tier 1
+  primer-recovery benchmark against paper-grounded ground truth and a Tier 2
+  corpus-audit pipeline over the discovery catalog.
+
+### Known limitations (v0.2 carry-forward)
+
+- **Multiplexed (inline-barcoded) deposits** need a user-supplied sample sheet;
+  automatic demultiplex detection is deferred.
+- **Read merging** of overlapping mates is not implemented.
+- **`qc.readiness`** (clustering / enrichment review) is a faithful library
+  API but expects clustering artifacts that v0.1 does not produce; it is not
+  wired into the `qc` verb.
+- **`count.counter`** can still trim raw FASTQs inline; the clean split
+  (`extract` strips, `count` only counts) is partial.
+- **`--from-pretrimmed-fastq`** validates record completeness but not per-line
+  FASTQ conformance — adequate for the power-user opt-in.
+- **Network coverage**: the non-ENA fetch backends still lack offline mocked
+  tests (carried into v0.2).
+
+### Packaging
+
+- MIT-licensed. A default `pip install selexprep` pulls only MIT-compatible
+  dependencies (pydantic v2, Typer, pandas, numpy); cutadapt is invoked as a
+  subprocess.
+- `kingfisher` (GPL-3.0) is an optional, runtime-detected subprocess backend —
+  not a declared dependency — so the default install stays MIT-only.
+
+[Unreleased]: https://github.com/marcorotanegroni/selexprep/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/marcorotanegroni/selexprep/releases/tag/v0.1.0

selexprep-0.1.0/CLAUDE.md

@@ -0,0 +1,94 @@
+# selexprep — Claude Code project context
+
+Accession-first preprocessing for public HT-SELEX datasets with empirical
+primer / constant-region inference. v0.1 ships a CLI + bundled discovery
+catalog. Target venues: Bioinformatics Advances Application Note (tool) +
+NAR Database Issue (catalog, v0.2).
+
+The locked Codex-peer-reviewed implementation plan lives at
+`~/.claude/plans/unified-seeking-treehouse.md` (four review passes; treat
+as a contract — don't rewrite for additive extensions, just commit +
+CHANGELOG entry).
+
+## Commands
+
+| Task                | Command                                  |
+| ------------------- | ---------------------------------------- |
+| Tests               | `uv run pytest`                          |
+| Lint                | `uv run ruff check src/ tests/`          |
+| Format              | `uv run ruff format src/ tests/`         |
+| Type-check          | `uv run mypy src/`                       |
+| Catalog browse      | `uv run selexprep catalog list --target X --insdc-only` |
+| Catalog refresh     | `uv run selexprep catalog refresh`       |
+
+CI runs lint + format + mypy + pytest on Python 3.10 / 3.11 / 3.12.
+Always run all four locally before committing.
+
+## Layout
+
+```
+src/selexprep/
+├── _common.py         shared utilities (iter_srr_files, load_csv, …)
+├── _io.py             deterministic gzip + sha256 helpers
+├── cli.py             Typer dispatcher (root)
+├── catalog/           bundled public-SELEX catalog + filters + CLI subapp
+├── count/             per-round sequence counting
+├── extract/           demux + trim (sample-sheet driven; deterministic gzip)
+├── fetch/             accession discovery + download (ENA-first)
+├── library/           primer detection + audit (Phase 2: LibraryReport)
+└── qc/                round coverage, consistency, readiness, plots
+```
+
+## Strict-mypy boundary
+
+Only `selexprep.library.report` is strict-mypy (Phase 2 LibraryReport
+schema — type precision matters for confidence calibration). Other
+modules use the permissive profile declared in `pyproject.toml`'s
+`[tool.mypy] disable_error_code`.
+
+## Critical gotchas (do not relearn)
+
+- **macOS TCC** blocks `~/Documents` on this Mac → repo lives at
+  `/Users/marcorotanegroni/selexprep`, NOT under `~/Documents/...`.
+- **`detect.detect_from_parquet`** defaults to `top_n=None` (no
+  subsampling). Don't reintroduce the 10_000 cap — the long tail of
+  rare uniques confirms primer consensus.
+- **`download_srr`** defaults to `backend="auto"` → ENA-direct first
+  (MIT-licensed path). kingfisher is GPL-3.0 and only invoked as
+  opt-in fallback (with a loud GPL notice). Never promote it to default.
+- **All `.gz` writes** must go through
+  `selexprep._io.open_gzip_text_deterministic` (mtime=0 + suppressed
+  FNAME). Plain `gzip.open` breaks SHA256 reproducibility.
+- **Curation flags** (`include`, `manual_curation_notes`,
+  `library_type_verification`, `library_type_evidence`,
+  `has_processed_counts`) are NEVER in the package catalog or in any
+  user-facing output. Curation is the user's downstream job; the
+  package reflects the public archives.
+- **Phase 2 centerpiece** is `LibraryReport` with explicit
+  `extraction_mode` × `read_source` × `required_action` matrix
+  (see the plan file for the full pydantic schema and the
+  cross-round-persistence inference algorithm).
+
+## Workflow
+
+- **Big design decisions** → user cross-checks with Codex
+  (independent peer-review). Don't self-approve scope changes. Trigger
+  phrase: *"let me run this through Codex"*. Wait for the response
+  before applying changes.
+- **Per-feature implementations** → use `EnterPlanMode` to get plan
+  approval before writing code on anything > a one-file change.
+- **Subagents** → `Explore` agent for read-only mapping when the
+  surface area is unclear; do edits in the main context.
+- **Background polling** (CI, long-running jobs) → use `Bash` with
+  `run_in_background: true` + a sha-aware Python poll script at
+  `/tmp/wait_for_sha_ci.py`. Don't write nested `python -c` with
+  escaped quotes — they break and run forever silently.
+
+## Where context lives
+
+- **Plan (locked contract):** `~/.claude/plans/unified-seeking-treehouse.md`
+- **Change log + v0.1 follow-ups:** `CHANGELOG.md` in this repo
+- **Project memory** (durable user preferences, project state):
+  `~/.claude/projects/-Users-marcorotanegroni-Documents-subtractive-proteomics-pipeline-aptameri-selex-corpus/memory/MEMORY.md`
+  (the path is keyed on the original thesis directory, not on this
+  repo — index file lists every memory note).

selexprep-0.1.0/Dockerfile

@@ -0,0 +1,45 @@
+# syntax=docker/dockerfile:1
+#
+# selexprep container image.
+#
+# Build:   docker build -t selexprep:0.1.0 .
+# Run:     docker run --rm selexprep:0.1.0 inspect SRR1234567
+#          docker run --rm -v "$PWD":/data selexprep:0.1.0 run /data/accessions.tsv --outdir /data/out
+#
+# The image installs selexprep from the local source tree (this checkout), so it
+# is buildable before the PyPI release. cutadapt arrives as a declared pip
+# dependency and is invoked as a subprocess at runtime — no apt package needed
+# (its manylinux wheel runs on the debian-slim base).
+
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.title="selexprep" \
+      org.opencontainers.image.description="Accession-first preprocessing for public HT-SELEX with primer auto-inference" \
+      org.opencontainers.image.source="https://github.com/marcorotanegroni/selexprep" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.version="0.1.0"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /build
+
+# Copy only the files the build backend (hatchling) needs to produce the wheel.
+# pyproject references README.md (readme) and LICENSE (license-files); the
+# package code and bundled catalog CSV live under src/.
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN python -m pip install --upgrade pip \
+    && python -m pip install . \
+    && rm -rf /build
+
+# Run as an unprivileged user; default working dir is a writable home.
+RUN useradd --create-home --uid 1000 selex
+USER selex
+WORKDIR /home/selex
+
+ENTRYPOINT ["selexprep"]
+CMD ["--help"]

selexprep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Rota Negroni
+
+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.