ep-touche 0.1.0__tar.gz

ep_touche-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

ep_touche-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev --extra legacy --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build

ep_touche-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish ep-touche
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ep-touche/
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ep_touche-0.1.0/.gitignore

@@ -0,0 +1,187 @@
+**/.DS_Store
+**/.vscode
+_reference/
+benchmark/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+.uv-cache/
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor  
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

ep_touche-0.1.0/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`touche` (PyPI: `ep-touche`) is a Python package + CLI that refactors the
+Danko Lab `E-P_contacts` R/shell reference workflows for high-resolution
+chromatin contact (Micro-C) analysis into a dependency-light, faster
+implementation. It starts from processed pairs files (from `distiller-nf` or
+equivalent) — it does not do FASTQ alignment, dedup, or cooler generation.
+
+The original reference implementation lives at `_reference/E-P_contacts/`
+(R/awk/shell scripts). New Python implementations are expected to reproduce
+its numeric behavior; when in doubt about expected output shape or a
+threshold/default, check the corresponding reference script there before
+changing behavior.
+
+`touche` uses `polars` as its only dataframe library, both internally and at
+the public `touche.api` surface (`pl.DataFrame`/`pl.LazyFrame`) — `pandas` is
+not a dependency. CSV outputs have no implicit index column (polars has no
+index concept); anywhere a row label matters (e.g. APA's pixel-bin matrices)
+it's an explicit `bin_label` column instead.
+
+## Commands
+
+Development uses `uv`.
+
+```bash
+uv sync --dev                       # install package + dev deps
+uv run touche --help                # run the CLI
+uv run pytest                       # run the full test suite
+uv run pytest tests/test_apa.py     # run one test file
+uv run pytest tests/test_apa.py::test_name  # run one test
+uv run ruff check src tests         # lint (this is what CI runs)
+uv build                            # build sdist/wheel
+```
+
+`mypy` is listed as a dev dependency but is not run in CI (`ci.yml` only runs
+`ruff check` and `pytest`).
+
+Numba is a core dependency (installed by `uv sync --dev`), so `backend="numba"`
+code paths are always exercisable without an extra install step.
+
+CI (`.github/workflows/ci.yml`) runs on Python 3.10/3.11/3.12: `uv sync --dev`,
+`ruff check src tests`, `pytest`, `uv build`. See `docs/testing-and-publishing.md`
+for the release/publish process (trusted PyPI publishing via `publish.yml`).
+
+## Architecture
+
+### Layering
+
+- `touche.io` — `scan_pairs` builds a lazy `polars.LazyFrame` over pairs files
+  (canonical 9-column `touche` format vs. 10+ column `distiller`/pairtools
+  format, `source="auto"` sniffs the layout from the first data row's field
+  count). All downstream code reads pairs through this module.
+- `touche.models` — shared frozen dataclasses: `ContactIndex` (numpy arrays
+  for one chromosome: `pos_a`, `pos_b`, strand, mapq), `PairStats`,
+  `NamedPath`/`NamedDepth` (used for `NAME=PATH` / `NAME=INTEGER` CLI
+  arguments across treatment/control commands).
+- `touche.contacts` — builds `ContactIndex` per chromosome from a pairs file
+  and reads/writes chromosome-sharded NPZ caches (`build_contact_indexes`,
+  `build_npz_cache`, `load_npz_cache`, `write_npz_cache`). This is the
+  in-memory numeric representation almost every compute function operates on.
+  `build_npz_cache`'s default (non-`"all"`) path spools the scanned pairs to a
+  local Parquet file once, then materializes and writes one chromosome's rows
+  at a time — peak memory is bounded by the largest single chromosome, not the
+  whole file.
+- `touche.preprocess` — pairs filtering/conversion (mapq + cis/trans filters,
+  distiller→touche format conversion).
+- `touche.pair_stats` — QC accumulation (row counts, cis/trans, mapq
+  pass/fail, per-chromosome, distance histogram) shared by `preprocess qc`,
+  `preprocess summarize`, and cache building (so a large file is scanned once
+  for both the cache and its QC).
+- Domain modules — `touche.local_decay`, `touche.apa`, `touche.background`:
+  each exposes an in-memory `compute_*` function operating on `ContactIndex`
+  objects/anchors, plus a file-driven wrapper (e.g. `call_local_decay`,
+  `aggregate_apa`, `count_ep_and_background`) that reads inputs, calls the
+  compute function, and writes output files.
+- `touche.pipelines` — `run_*_pipeline` functions that chain the file-driven
+  wrappers for a full command-group workflow (e.g. call → assign → plot for
+  local-decay) and write a `manifest.json` (inputs, parameters, outputs,
+  metrics, `touche` version, elapsed time, optional per-step timings).
+- `touche.api` — the curated notebook-facing re-export surface (`import
+  touche.api as tt`); update `__all__` here when adding a new public
+  compute/plot function intended for interactive use.
+- `touche.cli/` — one argparse module per command group (`preprocess.py`,
+  `local_decay.py`, `background.py`, `apa.py`), wired together in `main.py`.
+  Each subcommand's `func` callback maps CLI args to the corresponding
+  domain/pipeline function and prints a JSON summary via `cli/utils.py`.
+- `touche.backends` / `touche.numba/` — Numba acceleration, a core
+  dependency. `touche.numba` is a subpackage split by the domain that uses
+  each kernel (`touche.numba.apa`, `.background`, `.local_decay`, `.stats`);
+  numba is never imported at package import time — only when a
+  numba-accelerated function is actually called, so every `from
+  touche.numba.<domain> import ...` happens inside a function body, never at
+  a domain module's own top level. Counting (APA matrix/1D signal,
+  EP/background pairs, local-decay's observed-count helper) always uses its
+  Numba kernel — each was verified exact-equivalent to the plain NumPy
+  implementation it replaced (see `notes/numba-implementation-plan.md`), so
+  there's no `backend` choice exposed for it. `lowess_backend`
+  (`"numba"`/`"statsmodels"`) and `fisher_backend` (`"numba"`/`"scipy"`) are
+  different: each numba path is a validated but inexact approximation of its
+  alternative, so both choices remain exposed, defaulting to `"numba"`.
+- `touche.instrumentation` — the shared `Instrumentation` dataclass
+  (`progress`, `profile`) threaded through compute/pipeline functions as the
+  `progress=` argument. `instrument.iter(...)` wraps iterables with `tqdm`
+  when enabled; `instrument.step("name")` is a context manager that records
+  step timings when `profile=True`. CLI flags: `--progress`/`--profile`.
+
+### Contact indexing strategies
+
+Local-decay (and similar chromosome-scoped work) supports three
+`index_strategy` values, most relevant when touching caching or performance
+code:
+
+- `cache` (default): build/reuse chromosome-sharded NPZ caches under
+  `--cache-dir` (or `contact_index_cache/` next to the output), loading one
+  chromosome shard at a time — lowest memory.
+- `all`: read the whole pairs file once, hold every chromosome in memory —
+  fastest given enough RAM.
+- `chromosome`: re-scan the pairs file once per bait chromosome, keeping only
+  one chromosome resident — no persistent cache files, but slow on gzipped
+  input.
+
+### Pairs source formats
+
+Most commands take `--source {auto,distiller,touche}`. `touche` format is the
+canonical 9-column layout this package writes (`preprocess filter-pairs`/
+`convert-pairs`); `distiller` is pairtools/distiller-nf's 10+ column layout
+(leading read_id column). `auto` infers from field count — don't rely on
+`auto` when column counts could plausibly overlap between formats.
+
+### Repository conventions
+
+- `docs/` — human-facing usage guides a `touche` user should read directly
+  (CLI reference, API guide, preprocessing, reproducing reference plots,
+  testing/publishing). Keep these current when changing CLI flags or public
+  API signatures.
+- `notes/` — agent-facing implementation plans, benchmark logs, and design
+  sketches. Do not put user-facing documentation here, and don't move scratch
+  planning into `docs/` unless it's rewritten for users.
+- `scripts/` — standalone, runnable tools promoted out of `notes/` once
+  they're more than a one-off benchmark log (e.g. `reference_replication.py`,
+  which downloads the upstream E-P_contacts example data and replicates its
+  reference workflows end to end). Not part of the `touche` package build.
+- `_reference/E-P_contacts/` — the original reference workflows being ported;
+  treat as read-only prior art, not something to modify.
+- Manifests, cache directories, and other generated outputs (`.cache/`,
+  `contact_index_cache/`, `results/`) are run artifacts, not source.

ep_touche-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Youlin He
+
+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.

ep_touche-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: ep-touche
+Version: 0.1.0
+Summary: Tools for preprocessing and analyzing high-resolution chromatin contact data.
+Project-URL: Homepage, https://github.com/adamyhe/touche
+Project-URL: Repository, https://github.com/adamyhe/touche
+Project-URL: Issues, https://github.com/adamyhe/touche/issues
+Author: Adam He
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numba>=0.59
+Requires-Dist: numpy>=1.24
+Requires-Dist: polars>=1.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: seaborn>=0.12
+Requires-Dist: tqdm>=4.65
+Provides-Extra: legacy
+Requires-Dist: statsmodels>=0.14; extra == 'legacy'
+Description-Content-Type: text/markdown
+
+# touche
+
+[![PyPI](https://img.shields.io/pypi/v/ep-touche)](https://pypi.org/project/ep-touche/)
+[![Tests](https://github.com/adamyhe/touche/actions/workflows/ci.yml/badge.svg)](https://github.com/adamyhe/touche/actions/workflows/ci.yml)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/ep-touche?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/ep-touche)
+
+Python API and CLI tools for analyzing enhancer-promoter contacts (touches) from high-resolution chromatin contact data, refactored from the [Danko Lab E-P_contacts reference workflows](https://github.com/Danko-Lab/E-P_contacts).
+
+`touche` starts from processed pairs files. Raw FASTQ processing, alignment,
+deduplication, and cooler generation should be handled by an external workflow
+such as [distiller-nf](https://github.com/open2c/distiller-nf).
+
+## Status
+
+The current implementation includes CLI tools+API for:
+
+- Micro-C pairs conversion, filtering, QC, and chromosome-sharded NPZ caches
+- local-decay contact calling, pair-type assignment, and plotting
+- Aggregated peak analysis (APA) aggregation and inter-sample APA comparison
+- enhancer/promoter local-background counting and treatment comparison
+- pipeline `run` wrappers that preserve intermediate outputs and write JSON
+  manifests
+
+## Installation
+
+Install with `pip` from PyPI (package name is `ep-touche`):
+
+```bash
+pip install ep-touche
+touche --help
+```
+
+`uv` can also install and run the package:
+
+```bash
+uv add ep-touche
+uv run touche --help
+```
+
+`local-decay` also supports a statsmodels-backed LOWESS path
+(`lowess_backend="statsmodels"`) for exact reference comparisons
+(at the cost of being much slower than our custom implementation).
+Install the optional `legacy` extra only if you need that backend:
+
+```bash
+pip install ep-touche[legacy]
+# or: uv sync --extra legacy
+```
+
+### Older CPUs and Rosetta
+
+Polars publishes an `lts-cpu` wheel for older CPUs and for x86-64 Python on
+Apple Silicon under Rosetta. Because `polars-lts-cpu` provides the same
+`import polars` module but is a different Python distribution, it does not
+automatically satisfy `ep-touche`'s normal `polars>=1.0` dependency. If the
+standard Polars wheel does not run on your machine, install `ep-touche`, then
+replace Polars in that environment:
+
+```bash
+pip install ep-touche
+pip uninstall polars
+pip install "polars-lts-cpu>=1.0"
+```
+
+## CLI Overview
+
+```bash
+touche preprocess --help
+touche local-decay --help
+touche apa --help
+touche background --help
+```
+
+Available command groups:
+
+- `touche preprocess`: convert/filter pairs, write QC summaries, and build NPZ
+  caches.
+- `touche local-decay`: call observed/expected contacts, assign pair types, plot
+  distributions, or run the full local-decay workflow.
+- `touche apa`: aggregate APA matrices, compare treatment/control APAs, or run a
+  paired APA workflow.
+- `touche background`: count EP/background contacts, compare treatment ratios,
+  or run the full EP/background workflow.
+
+See the [CLI reference](docs/cli.md) for examples, common options, and expected
+outputs.
+
+## Typical workflow
+
+Start from analysis-ready `.pairs` or `.pairs.gz` files produced by distiller-nf
+or an equivalent workflow.
+
+1. Filter or convert pairs with `touche preprocess`.
+2. For real or repeated local-decay runs, build a position-only cache with
+   `touche preprocess build-cache --no-metadata`.
+3. Use the `run` wrappers for end-to-end analyses:
+   `touche local-decay run`, `touche apa run`, and `touche background run`.
+4. Use individual subcommands such as `local-decay call` or `background count`
+   when debugging or replacing one stage.
+
+Many of the computation-heavy steps use `numba` acceleration and parallelism.
+Set `NUMBA_NUM_THREADS` before running to control CPU usage (default is to use
+all threads on machine):
+
+```bash
+NUMBA_NUM_THREADS=8 touche background run ...
+```
+
+## Python API
+
+For notebooks and custom scripts, import the provisional API surface:
+
+```python
+import touche.api as tt
+
+indexes = tt.build_contact_indexes("sample.nodups_30_intra.pairs.gz", source="touche")
+```
+
+The API is organized around reading pairs and anchors once, running in-memory
+compute functions such as `compute_apa`, `compute_local_decay`, and
+`compute_ep_and_background`, then displaying or saving returned Matplotlib
+figures as needed. Long-running CLI and API calls support optional progress
+bars and lightweight profiling. See the [API guide](docs/api.md) for examples.
+
+## Documentation
+
+Detailed usage notes live under `docs/`:
+
+- [Docs index](docs/README.md): human-facing guides and documentation
+  conventions.
+- [CLI reference](docs/cli.md): command groups, common options, examples,
+  outputs, and run-wrapper manifests.
+- [Micro-C preprocessing](docs/micro-c-preprocessing.md): distiller-nf boundary,
+  pairs format expectations, filtering, QC, and cache building.
+- [API](docs/api.md): provisional in-memory APIs for notebooks, interactive analyses,
+  and custom scripts.
+- [Reproducing reference plots](docs/reproducing-reference-plots.md): end-to-end
+  commands for the reference local-decay, APA, and EP/background plots.
+- [Testing and publishing](docs/testing-and-publishing.md): CI, local checks,
+  and PyPI release workflow for the `ep-touche` distribution.
+
+Implementation plans, experiment logs, and agent-facing notes belong in
+`notes/`.
+
+## Development
+
+Development is managed with `uv`.
+
+```bash
+git clone https://github.com/adamyhe/touche.git
+cd touche/
+uv sync --dev
+uv run touche --help
+uv run pytest
+```