sonar-c 0.4.0__tar.gz

sonar_c-0.4.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: sonar-c
+Version: 0.4.0
+Summary: Hi-C noise analysis toolkit for .hic/.cool matrices
+Author: Tim Reznicek
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/jrowley-lab-org/sonar-c
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: statsmodels>=0.13
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: scipy>=1.8
+Requires-Dist: cooler>=0.9.3
+Requires-Dist: hic-straw>=1.3.1
+Provides-Extra: cooler
+Requires-Dist: cooler>=0.9.3; extra == "cooler"
+Provides-Extra: straw
+Requires-Dist: hic-straw>=1.3.1; extra == "straw"
+Provides-Extra: profile
+Requires-Dist: psutil>=5.9; extra == "profile"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# sonar-c
+
+Lightweight Hi-C noise analysis toolkit for `.hic` ([hicstraw](https://github.com/aidenlab/straw)) and cooler formats (`.cool`, `.mcool`, `.scool`).
+
+## Features
+- Per-row noise estimates with optional subsampling simulations to gauge robustness.
+- Configurable row filtering based on distance-normalized signal and window occupancy.
+- Works with `.hic`, `.cool`, `.mcool`, and `.scool` input matrices (SciPy-backed pipeline for cooler formats).
+- Whole-genome noise tracks at requested resolutions.
+- Simple plotting helpers for comparing noise distributions (log-scaled histograms).
+
+## Installation
+
+**Default install — both backends (cooler + hicstraw):**
+
+```bash
+pip install sonar-c
+```
+
+**Single-backend profiles:**
+
+```bash
+# cooler only (.cool / .mcool / .scool)
+pip install "sonar-c[cooler]"
+
+# hicstraw only (.hic)
+pip install "sonar-c[straw]"
+```
+
+> **Windows users — known PyPI install error**
+>
+> `hic-straw` does not ship pre-built wheels for Windows on PyPI and may fail to
+> compile from source. If `pip install sonar-c` errors during the hicstraw
+> build step, bypass the default install and use the cooler-only profile:
+>
+> ```bash
+> pip install sonar-c --no-deps
+> pip install numpy pandas statsmodels matplotlib scipy cooler
+> ```
+>
+> To process `.hic` files on Windows, convert them first with
+> [`hic2cool`](https://github.com/4dn-dcic/hic2cool) and use the cooler backend:
+>
+> ```bash
+> pip install hic2cool
+> hic2cool convert sample.hic sample.mcool --resolutions 10000
+> sonar-c sample-noise --hic sample.mcool --cooler_path /resolutions/10000 --res 10000 --out_dir outputs/
+> ```
+## Command Line Usage
+### Sampled noise with subsampling summaries
+```bash
+sonar-c sample-noise \
+  --hic sample.cool \
+  --res 10000 \
+  --min_mean_score 0.9 \
+  --min_nonzero_frac 0.05 \
+  --subsample_ratios 1.0,0.75,0.5,0.25 \
+  --norm balance \
+  --out_dir outputs/10kb \
+  --seed 42 \
+  --profile outputs/10kb/profile.csv
+```
+Produces one `<chrom>_<res>.bedgraph` for the original map and a `subsample_summary.tsv`
+table with mean/median/log noise, ACF, variability, and empty-bin ratios at each subsample.
+
+### Noise bedgraph (genome-wide)
+```bash
+sonar-c noise-bedgraph \
+  --hic sample.hic \
+  --res 5000,10000 \
+  --out_dir outputs/
+# Add --cpu <N> to parallelize per (chrom, res) tasks
+sonar-c noise-bedgraph \
+  --hic sample.hic \
+  --res 5000,10000 \
+  --out_dir outputs/ \
+  --cpu 4
+# For .mcool/.scool inputs you can add: --cooler_path /resolutions/10000
+```
+
+### Plotting
+```bash
+sonar-c plot \
+  --noise_bed outputs/chr1_10000_sampled.bedgraph \
+  --out_png noise_density.png
+```
+
+### Build a blacklist from bedgraphs
+```bash
+sonar-c blacklist \
+  --input outputs/10kb/*.bedgraph \
+  --out blacklist.bed \
+  --top_quantile 0.95
+```
+This command removes any rows with `NaN` noise values and blacklists the top 5% most
+noisy intervals by default. Provide `--zscore_cutoff` to supply an explicit z-score
+threshold instead of using the percentile.
+
+## Python API
+```python
+from sonar_c import noise_sampling
+
+noise_sampling.compute_sampled_noise(
+    hic_path="sample.cool",
+    res=10_000,
+    sample_fraction=1.0,
+    min_mean_score=0.9,
+    min_nonzero_frac=0.05,
+    subsample_ratios=[1.0, 0.5, 0.25],
+    norm="balance",
+    out_dir="outputs",
+    seed=42,
+)
+```
+
+### Notes
+- For `.mcool`, the CLI selects the group matching `--res` (e.g. `/resolutions/10000`). Provide `--cooler_path` for `.scool` cell groups or custom URIs.
+- `--norm` accepts `none`, `balance` (cooler weights / KR for `.hic`), or a path to a bedgraph/vector defining custom bin weights.
+- All commands print a summary line with wall-clock time and memory usage; install the optional `profile` extra for psutil-backed RSS reporting.
+- `--profile` writes per-chromosome runtime and memory metrics to a CSV for downstream plotting.
+- `--cpu <N>` parallelizes `noise-bedgraph` by `(chromosome, resolution)` tasks (default 1, capped at available cores).
+- Every CLI invocation now emits a `contacts_overview.tsv` summarizing per-chromosome totals at the coarsest resolution.
+
+## Backends
+
+This project supports two I/O backends, both included in the default install:
+
+| Install | Backend | Formats |
+|---|---|---|
+| `pip install sonar-c` (default) | cooler + hicstraw | `.cool`, `.mcool`, `.scool`, `.hic` |
+| `pip install "sonar-c[cooler]"` | cooler only | `.cool`, `.mcool`, `.scool` |
+| `pip install "sonar-c[straw]"` | hicstraw only | `.hic` |
+
+Runtime guidance:
+- If you pass a `.hic` file without hicstraw installed, the tool will suggest `pip install "sonar-c[straw]"`.
+- If you pass a cooler-format file without `cooler` installed, the tool will suggest `pip install "sonar-c[cooler]"`.
+- The same `--cooler_path` argument selects resolution groups in `.mcool` files and cell groups in `.scool` files.
+
+## Changelog
+
+### v0.3.0
+- **`noise-bedgraph` subcommand** — renamed from `full-noise` for clarity. All existing flags are unchanged.
+- **Region-filtered `--chrom_sizes`** — the chromosome sizes file now accepts optional region columns (cols 3+) in `start:end` or `start-end` format (0-based, half-open). When regions are present, only bins overlapping those regions are emitted. The noise window still extends up to `--bindist_bp` on each side of the region, with chromosome-end clamping applied as usual. A region smaller than one bin outputs the single overlapping bin. Regions that exceed the chromosome size produce a warning and are skipped; chromosomes with no valid regions are skipped entirely.
+  ```
+  # Example extended chrom_sizes file (TSV):
+  # chrom    size         region1              region2
+  chr1       248956422    0:50000000           100000000:150000000
+  chr2       242193529
+  chrX       156040895    5000000-10000000
+  ```
+- **Multi-mode blacklist output** — `blacklist` and `default-run` now produce four output directories per run (`density_only/`, `noise_only/`, `union/`, `intersection/`) instead of a single file, enabling comparison of conservative and permissive thresholds.
+- **Default transforms changed to `log1p`** — both `--density_transform` and `--noise_transform` now default to `log1p` (previously `none` and `sqrt` respectively). `log1p` is more robust to outlier bins (repeats, centromeres) that can skew elbow detection.
+- **Both backends in default install** — `pip install sonar-c` now includes both `cooler` and `hic-straw`. Single-backend profiles `[cooler]` and `[straw]` are available for constrained environments.
+
+### v0.2.4
+- Initial public release.
+

sonar_c-0.4.0/README.md

@@ -0,0 +1,157 @@
+# sonar-c
+
+Lightweight Hi-C noise analysis toolkit for `.hic` ([hicstraw](https://github.com/aidenlab/straw)) and cooler formats (`.cool`, `.mcool`, `.scool`).
+
+## Features
+- Per-row noise estimates with optional subsampling simulations to gauge robustness.
+- Configurable row filtering based on distance-normalized signal and window occupancy.
+- Works with `.hic`, `.cool`, `.mcool`, and `.scool` input matrices (SciPy-backed pipeline for cooler formats).
+- Whole-genome noise tracks at requested resolutions.
+- Simple plotting helpers for comparing noise distributions (log-scaled histograms).
+
+## Installation
+
+**Default install — both backends (cooler + hicstraw):**
+
+```bash
+pip install sonar-c
+```
+
+**Single-backend profiles:**
+
+```bash
+# cooler only (.cool / .mcool / .scool)
+pip install "sonar-c[cooler]"
+
+# hicstraw only (.hic)
+pip install "sonar-c[straw]"
+```
+
+> **Windows users — known PyPI install error**
+>
+> `hic-straw` does not ship pre-built wheels for Windows on PyPI and may fail to
+> compile from source. If `pip install sonar-c` errors during the hicstraw
+> build step, bypass the default install and use the cooler-only profile:
+>
+> ```bash
+> pip install sonar-c --no-deps
+> pip install numpy pandas statsmodels matplotlib scipy cooler
+> ```
+>
+> To process `.hic` files on Windows, convert them first with
+> [`hic2cool`](https://github.com/4dn-dcic/hic2cool) and use the cooler backend:
+>
+> ```bash
+> pip install hic2cool
+> hic2cool convert sample.hic sample.mcool --resolutions 10000
+> sonar-c sample-noise --hic sample.mcool --cooler_path /resolutions/10000 --res 10000 --out_dir outputs/
+> ```
+## Command Line Usage
+### Sampled noise with subsampling summaries
+```bash
+sonar-c sample-noise \
+  --hic sample.cool \
+  --res 10000 \
+  --min_mean_score 0.9 \
+  --min_nonzero_frac 0.05 \
+  --subsample_ratios 1.0,0.75,0.5,0.25 \
+  --norm balance \
+  --out_dir outputs/10kb \
+  --seed 42 \
+  --profile outputs/10kb/profile.csv
+```
+Produces one `<chrom>_<res>.bedgraph` for the original map and a `subsample_summary.tsv`
+table with mean/median/log noise, ACF, variability, and empty-bin ratios at each subsample.
+
+### Noise bedgraph (genome-wide)
+```bash
+sonar-c noise-bedgraph \
+  --hic sample.hic \
+  --res 5000,10000 \
+  --out_dir outputs/
+# Add --cpu <N> to parallelize per (chrom, res) tasks
+sonar-c noise-bedgraph \
+  --hic sample.hic \
+  --res 5000,10000 \
+  --out_dir outputs/ \
+  --cpu 4
+# For .mcool/.scool inputs you can add: --cooler_path /resolutions/10000
+```
+
+### Plotting
+```bash
+sonar-c plot \
+  --noise_bed outputs/chr1_10000_sampled.bedgraph \
+  --out_png noise_density.png
+```
+
+### Build a blacklist from bedgraphs
+```bash
+sonar-c blacklist \
+  --input outputs/10kb/*.bedgraph \
+  --out blacklist.bed \
+  --top_quantile 0.95
+```
+This command removes any rows with `NaN` noise values and blacklists the top 5% most
+noisy intervals by default. Provide `--zscore_cutoff` to supply an explicit z-score
+threshold instead of using the percentile.
+
+## Python API
+```python
+from sonar_c import noise_sampling
+
+noise_sampling.compute_sampled_noise(
+    hic_path="sample.cool",
+    res=10_000,
+    sample_fraction=1.0,
+    min_mean_score=0.9,
+    min_nonzero_frac=0.05,
+    subsample_ratios=[1.0, 0.5, 0.25],
+    norm="balance",
+    out_dir="outputs",
+    seed=42,
+)
+```
+
+### Notes
+- For `.mcool`, the CLI selects the group matching `--res` (e.g. `/resolutions/10000`). Provide `--cooler_path` for `.scool` cell groups or custom URIs.
+- `--norm` accepts `none`, `balance` (cooler weights / KR for `.hic`), or a path to a bedgraph/vector defining custom bin weights.
+- All commands print a summary line with wall-clock time and memory usage; install the optional `profile` extra for psutil-backed RSS reporting.
+- `--profile` writes per-chromosome runtime and memory metrics to a CSV for downstream plotting.
+- `--cpu <N>` parallelizes `noise-bedgraph` by `(chromosome, resolution)` tasks (default 1, capped at available cores).
+- Every CLI invocation now emits a `contacts_overview.tsv` summarizing per-chromosome totals at the coarsest resolution.
+
+## Backends
+
+This project supports two I/O backends, both included in the default install:
+
+| Install | Backend | Formats |
+|---|---|---|
+| `pip install sonar-c` (default) | cooler + hicstraw | `.cool`, `.mcool`, `.scool`, `.hic` |
+| `pip install "sonar-c[cooler]"` | cooler only | `.cool`, `.mcool`, `.scool` |
+| `pip install "sonar-c[straw]"` | hicstraw only | `.hic` |
+
+Runtime guidance:
+- If you pass a `.hic` file without hicstraw installed, the tool will suggest `pip install "sonar-c[straw]"`.
+- If you pass a cooler-format file without `cooler` installed, the tool will suggest `pip install "sonar-c[cooler]"`.
+- The same `--cooler_path` argument selects resolution groups in `.mcool` files and cell groups in `.scool` files.
+
+## Changelog
+
+### v0.3.0
+- **`noise-bedgraph` subcommand** — renamed from `full-noise` for clarity. All existing flags are unchanged.
+- **Region-filtered `--chrom_sizes`** — the chromosome sizes file now accepts optional region columns (cols 3+) in `start:end` or `start-end` format (0-based, half-open). When regions are present, only bins overlapping those regions are emitted. The noise window still extends up to `--bindist_bp` on each side of the region, with chromosome-end clamping applied as usual. A region smaller than one bin outputs the single overlapping bin. Regions that exceed the chromosome size produce a warning and are skipped; chromosomes with no valid regions are skipped entirely.
+  ```
+  # Example extended chrom_sizes file (TSV):
+  # chrom    size         region1              region2
+  chr1       248956422    0:50000000           100000000:150000000
+  chr2       242193529
+  chrX       156040895    5000000-10000000
+  ```
+- **Multi-mode blacklist output** — `blacklist` and `default-run` now produce four output directories per run (`density_only/`, `noise_only/`, `union/`, `intersection/`) instead of a single file, enabling comparison of conservative and permissive thresholds.
+- **Default transforms changed to `log1p`** — both `--density_transform` and `--noise_transform` now default to `log1p` (previously `none` and `sqrt` respectively). `log1p` is more robust to outlier bins (repeats, centromeres) that can skew elbow detection.
+- **Both backends in default install** — `pip install sonar-c` now includes both `cooler` and `hic-straw`. Single-backend profiles `[cooler]` and `[straw]` are available for constrained environments.
+
+### v0.2.4
+- Initial public release.
+

sonar_c-0.4.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonar-c"
+version = "0.4.0"
+description = "Hi-C noise analysis toolkit for .hic/.cool matrices"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "BSD-3-Clause"}
+authors = [
+  {name = "Tim Reznicek"}
+]
+dependencies = [
+  "numpy>=1.21",
+  "pandas>=1.3",
+  "statsmodels>=0.13",
+  "matplotlib>=3.5",
+  "scipy>=1.8",
+  "cooler>=0.9.3",
+  "hic-straw>=1.3.1"
+]
+
+[project.optional-dependencies]
+cooler  = ["cooler>=0.9.3"]
+straw   = ["hic-straw>=1.3.1"]
+profile = ["psutil>=5.9"]
+dev     = ["pytest>=7.0", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/jrowley-lab-org/sonar-c"
+
+[project.scripts]
+sonar-c = "sonar_c.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sonar_c-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sonar_c-0.4.0/src/sonar_c/__init__.py

@@ -0,0 +1,18 @@
+"""
+sonar_c
+-----------
+
+Hi-C noise analysis library for .hic and .cool contact maps.
+"""
+
+from . import backends, cli, figures, noise_fullmap, noise_sampling, filters, reference
+
+__all__ = [
+    "backends",
+    "cli",
+    "figures",
+    "noise_fullmap",
+    "noise_sampling",
+    "filters",
+    "reference",
+]