Metadata-Version: 2.4
Name: jukebox-hic
Version: 0.3.0b0
Summary: Hi-C noise analysis toolkit for .hic/.cool matrices
Author: NoiseSampler Developers
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/timrez/NoiseSampler
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"

# jukebox-hic

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 jukebox-hic
```

**Single-backend profiles:**

```bash
# cooler only (.cool / .mcool / .scool)
pip install "jukebox-hic[cooler]"

# hicstraw only (.hic)
pip install "jukebox-hic[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 jukebox-hic` errors during the hicstraw
> build step, bypass the default install and use the cooler-only profile:
>
> ```bash
> pip install jukebox-hic --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
> jukebox-hic sample-noise --hic sample.mcool --cooler_path /resolutions/10000 --res 10000 --out_dir outputs/
> ```
## Command Line Usage
### Sampled noise with subsampling summaries
```bash
jukebox-hic 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
jukebox-hic noise-bedgraph \
  --hic sample.hic \
  --res 5000,10000 \
  --out_dir outputs/
# Add --cpu <N> to parallelize per (chrom, res) tasks
jukebox-hic 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
jukebox-hic plot \
  --noise_bed outputs/chr1_10000_sampled.bedgraph \
  --out_png noise_density.png
```

### Build a blacklist from bedgraphs
```bash
jukebox-hic 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 jukebox_hic 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 jukebox-hic` (default) | cooler + hicstraw | `.cool`, `.mcool`, `.scool`, `.hic` |
| `pip install "jukebox-hic[cooler]"` | cooler only | `.cool`, `.mcool`, `.scool` |
| `pip install "jukebox-hic[straw]"` | hicstraw only | `.hic` |

Runtime guidance:
- If you pass a `.hic` file without hicstraw installed, the tool will suggest `pip install "jukebox-hic[straw]"`.
- If you pass a cooler-format file without `cooler` installed, the tool will suggest `pip install "jukebox-hic[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 jukebox-hic` now includes both `cooler` and `hic-straw`. Single-backend profiles `[cooler]` and `[straw]` are available for constrained environments.

### v0.2.4
- Initial public release.

