pyLoopSage 1.1.5__tar.gz → 2.0.0rc2__tar.gz

pyloopsage-2.0.0rc2/MANIFEST.in

@@ -0,0 +1,2 @@
+exclude Dockerfile
+recursive-include src *.html *.css *.xml *.pfm

pyloopsage-2.0.0rc2/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: pyLoopSage
+Version: 2.0.0rc2
+Summary: An energy-based stochastic model of loop extrusion in chromatin.
+Home-page: https://github.com/SFGLab/pyLoopSage
+Author: Sebastian Korsak
+Author-email: s.korsak@datascience.edu.pl
+License: GNU General Public License v3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>1.2
+Requires-Dist: numba
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: argparse
+Requires-Dist: matplotlib
+Requires-Dist: mdtraj
+Requires-Dist: seaborn
+Requires-Dist: scikit-learn
+Requires-Dist: configparser
+Requires-Dist: typing-extensions
+Requires-Dist: tqdm
+Requires-Dist: pyvista[all]
+Requires-Dist: OpenMM
+Requires-Dist: OpenMM-cuda
+Requires-Dist: statsmodels
+Requires-Dist: imageio
+Requires-Dist: imageio[ffmpeg]
+Requires-Dist: pillow
+Requires-Dist: pyBigWig
+Requires-Dist: hic-straw
+Requires-Dist: topoly
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<p align="center">
+  <img src="assets/logo.svg" alt="LoopSage" width="760">
+</p>
+
+<p align="center">
+  <a href="https://www.python.org"><img alt="Python" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
+  <a href="https://openmm.org"><img alt="OpenMM" src="https://img.shields.io/badge/OpenMM-8.5%2B-6a3de8"></a>
+  <a href="https://numba.pydata.org"><img alt="Numba" src="https://img.shields.io/badge/Numba-JIT%20sampler-00A3E0?logo=numba&logoColor=white"></a>
+  <a href="https://pyvista.org"><img alt="PyVista" src="https://img.shields.io/badge/PyVista-3D%20viewer-FF7F00"></a>
+  <a href="https://www.docker.com"><img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white"></a>
+  <a href="https://numpy.org"><img alt="NumPy" src="https://img.shields.io/badge/NumPy-013243?logo=numpy&logoColor=white"></a>
+  <a href="https://scipy.org"><img alt="SciPy" src="https://img.shields.io/badge/SciPy-8CAAE6?logo=scipy&logoColor=white"></a>
+  <a href="https://mdtraj.org"><img alt="MDTraj" src="https://img.shields.io/badge/MDTraj-trajectories-1a1a1f"></a>
+  <a href="tests"><img alt="pytest" src="https://img.shields.io/badge/tested%20with-pytest-0A9EDC?logo=pytest&logoColor=white"></a>
+  <a href="https://www.gnu.org/licenses/gpl-3.0.html"><img alt="GPL v3 license" src="https://img.shields.io/badge/License-GPL%20v3-blue"></a>
+</p>
+
+**LoopSage** is an energy-based stochastic model of chromatin loop extrusion. Cohesin complexes are modelled as loop-extruding factors (LEFs) that slide along a chromatin fibre, are blocked by CTCF sites and rebind elsewhere. A Metropolis / simulated-annealing Monte Carlo samples ensembles of loop configurations that agree with your loop data (e.g. ChIA-PET, HiChIP, Hi-C loops, or CTCF peaks). Each ensemble can be turned into 3D structures with a short OpenMM molecular-dynamics run.
+
+From one command you get an HTML report with the contact maps, loop statistics, 3D structures and diagnostics.
+
+## Installation
+
+Python 3.10 or newer is required. `openmm` and `pyBigWig` install most reliably from conda. `hic-straw` (reads `.hic` files for the optional `--hic` reference) is installed with the package. It needs a C++ compiler and libcurl when no wheel exists for your system.
+
+```bash
+git clone https://github.com/SFGLab/pyLoopSage.git
+cd pyLoopSage
+conda create -n loopsage python=3.11 -y && conda activate loopsage
+conda install -c conda-forge "openmm>=8.5.1" pybigwig -y
+pip install -r requirements.txt && pip install -e .
+```
+
+Then install the package (`pip install -e .`) to get the `loopsage` command (version 2.0.0rc2).
+
+## Usage
+
+```bash
+# Minimal run: loops file + region
+loopsage -f loops.bedpe -r chr1:77000000-95000000
+
+# Settings from a config file, with command-line overrides
+loopsage -c config.ini -t 4 --n-replicas 3
+
+# BEDPE without orientation columns: read CTCF orientation from the reference genome, keep loops with >= 3 PET
+loopsage -f loops.bedpe -r chr1:77000000-95000000 --motif-genome hg38.fa --min-pet 3
+
+# See every option
+loopsage -h
+```
+
+- **Input:** a `.bedpe` loop file, or `.bed` / `.narrowPeak` CTCF sites, plus the genomic region.
+- **CTCF motif search (optional):** with `--motif-genome FASTA` every loop anchor is scanned for the CTCF motif (bundled JASPAR MA0139.1, or your own `--motif-pfm`) and the orientation probabilities are added automatically; `--min-pet N` keeps only loops with at least N PET counts (works without a genome too). Needs no extra packages; the genome is read through a `.fai` index and never loaded into memory. Hits are accepted at `--motif-pvalue` (default 1e-5). The report shows a progress bar while searching and a diagnostics section (loops kept, motif scores, orientation calls). The annotated loops are saved in the run's `data` folder.
+- **Config:** `config_example.ini` lists every parameter with a short description; command-line flags override it.
+- **Output:** `results/<chrom>_<start>_<end>_<run>/`, with the report in `report/report.html`.
+- **MD platform:** `--platform auto` (default) tries CUDA, then OpenCL, then the multi-threaded CPU platform, and the chosen platform is always printed. Force one with `--platform CUDA|OpenCL|CPU`.
+- **Monte Carlo:** `--method Metropolis|Annealing`, `--t-init`, `--t-final`, `--mc-steps`, `--sample-every` and `--burnin` control the sampler (all also keys in the config file).
+- **Parallelism:** `-t/--threads` sets worker threads and `--n-replicas` runs independent Monte Carlo chains (default 1).
+- **Demo:** `python demo/run_demo.py quick` runs a small example in seconds.
+
+Detailed documentation of the model, parameters and outputs is in [`markdown/`](markdown/).
+
+## Tests
+
+Run the whole suite in parallel, with a per-module report:
+
+```bash
+python tools/run_tests.py             # all tests, one worker per two cores
+python tools/run_tests.py -j 8 --html # 8 workers, also writes test_report/report.html
+python tools/run_tests.py -k contrast # only tests whose name matches
+```
+
+Plain `PYTHONPATH=src python -m pytest -q` also works, but runs the files one after another (about 15 minutes). Tests of optional packages (`hicstraw`, `pyBigWig`) are skipped when those are not installed.
+
+## Citation
+
+If you use LoopSage, please cite:
+
+- Korsak, S. and Plewczynski, D. *LoopSage: An energy-based Monte Carlo approach for the loop extrusion modelling of chromatin.* Methods (2024).
+- Jodkowska, K., Parteka-Tojek, Z., Agarwal, A., Denkiewicz, M., Korsak, S., Chiliński, M., Banecki, K., & Plewczynski, D. *Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes.* bioRxiv (2024). https://doi.org/10.1101/2024.05.16.594268
+
+## License
+
+GNU General Public License v3.0.

pyloopsage-2.0.0rc2/README.md

@@ -0,0 +1,84 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="LoopSage" width="760">
+</p>
+
+<p align="center">
+  <a href="https://www.python.org"><img alt="Python" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
+  <a href="https://openmm.org"><img alt="OpenMM" src="https://img.shields.io/badge/OpenMM-8.5%2B-6a3de8"></a>
+  <a href="https://numba.pydata.org"><img alt="Numba" src="https://img.shields.io/badge/Numba-JIT%20sampler-00A3E0?logo=numba&logoColor=white"></a>
+  <a href="https://pyvista.org"><img alt="PyVista" src="https://img.shields.io/badge/PyVista-3D%20viewer-FF7F00"></a>
+  <a href="https://www.docker.com"><img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white"></a>
+  <a href="https://numpy.org"><img alt="NumPy" src="https://img.shields.io/badge/NumPy-013243?logo=numpy&logoColor=white"></a>
+  <a href="https://scipy.org"><img alt="SciPy" src="https://img.shields.io/badge/SciPy-8CAAE6?logo=scipy&logoColor=white"></a>
+  <a href="https://mdtraj.org"><img alt="MDTraj" src="https://img.shields.io/badge/MDTraj-trajectories-1a1a1f"></a>
+  <a href="tests"><img alt="pytest" src="https://img.shields.io/badge/tested%20with-pytest-0A9EDC?logo=pytest&logoColor=white"></a>
+  <a href="https://www.gnu.org/licenses/gpl-3.0.html"><img alt="GPL v3 license" src="https://img.shields.io/badge/License-GPL%20v3-blue"></a>
+</p>
+
+**LoopSage** is an energy-based stochastic model of chromatin loop extrusion. Cohesin complexes are modelled as loop-extruding factors (LEFs) that slide along a chromatin fibre, are blocked by CTCF sites and rebind elsewhere. A Metropolis / simulated-annealing Monte Carlo samples ensembles of loop configurations that agree with your loop data (e.g. ChIA-PET, HiChIP, Hi-C loops, or CTCF peaks). Each ensemble can be turned into 3D structures with a short OpenMM molecular-dynamics run.
+
+From one command you get an HTML report with the contact maps, loop statistics, 3D structures and diagnostics.
+
+## Installation
+
+Python 3.10 or newer is required. `openmm` and `pyBigWig` install most reliably from conda. `hic-straw` (reads `.hic` files for the optional `--hic` reference) is installed with the package. It needs a C++ compiler and libcurl when no wheel exists for your system.
+
+```bash
+git clone https://github.com/SFGLab/pyLoopSage.git
+cd pyLoopSage
+conda create -n loopsage python=3.11 -y && conda activate loopsage
+conda install -c conda-forge "openmm>=8.5.1" pybigwig -y
+pip install -r requirements.txt && pip install -e .
+```
+
+Then install the package (`pip install -e .`) to get the `loopsage` command (version 2.0.0rc2).
+
+## Usage
+
+```bash
+# Minimal run: loops file + region
+loopsage -f loops.bedpe -r chr1:77000000-95000000
+
+# Settings from a config file, with command-line overrides
+loopsage -c config.ini -t 4 --n-replicas 3
+
+# BEDPE without orientation columns: read CTCF orientation from the reference genome, keep loops with >= 3 PET
+loopsage -f loops.bedpe -r chr1:77000000-95000000 --motif-genome hg38.fa --min-pet 3
+
+# See every option
+loopsage -h
+```
+
+- **Input:** a `.bedpe` loop file, or `.bed` / `.narrowPeak` CTCF sites, plus the genomic region.
+- **CTCF motif search (optional):** with `--motif-genome FASTA` every loop anchor is scanned for the CTCF motif (bundled JASPAR MA0139.1, or your own `--motif-pfm`) and the orientation probabilities are added automatically; `--min-pet N` keeps only loops with at least N PET counts (works without a genome too). Needs no extra packages; the genome is read through a `.fai` index and never loaded into memory. Hits are accepted at `--motif-pvalue` (default 1e-5). The report shows a progress bar while searching and a diagnostics section (loops kept, motif scores, orientation calls). The annotated loops are saved in the run's `data` folder.
+- **Config:** `config_example.ini` lists every parameter with a short description; command-line flags override it.
+- **Output:** `results/<chrom>_<start>_<end>_<run>/`, with the report in `report/report.html`.
+- **MD platform:** `--platform auto` (default) tries CUDA, then OpenCL, then the multi-threaded CPU platform, and the chosen platform is always printed. Force one with `--platform CUDA|OpenCL|CPU`.
+- **Monte Carlo:** `--method Metropolis|Annealing`, `--t-init`, `--t-final`, `--mc-steps`, `--sample-every` and `--burnin` control the sampler (all also keys in the config file).
+- **Parallelism:** `-t/--threads` sets worker threads and `--n-replicas` runs independent Monte Carlo chains (default 1).
+- **Demo:** `python demo/run_demo.py quick` runs a small example in seconds.
+
+Detailed documentation of the model, parameters and outputs is in [`markdown/`](markdown/).
+
+## Tests
+
+Run the whole suite in parallel, with a per-module report:
+
+```bash
+python tools/run_tests.py             # all tests, one worker per two cores
+python tools/run_tests.py -j 8 --html # 8 workers, also writes test_report/report.html
+python tools/run_tests.py -k contrast # only tests whose name matches
+```
+
+Plain `PYTHONPATH=src python -m pytest -q` also works, but runs the files one after another (about 15 minutes). Tests of optional packages (`hicstraw`, `pyBigWig`) are skipped when those are not installed.
+
+## Citation
+
+If you use LoopSage, please cite:
+
+- Korsak, S. and Plewczynski, D. *LoopSage: An energy-based Monte Carlo approach for the loop extrusion modelling of chromatin.* Methods (2024).
+- Jodkowska, K., Parteka-Tojek, Z., Agarwal, A., Denkiewicz, M., Korsak, S., Chiliński, M., Banecki, K., & Plewczynski, D. *Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes.* bioRxiv (2024). https://doi.org/10.1101/2024.05.16.594268
+
+## License
+
+GNU General Public License v3.0.

{pyloopsage-1.1.5 → pyloopsage-2.0.0rc2}/setup.py

@@ -1,12 +1,15 @@
-from setuptools import setup, find_packages
+from setuptools import setup, find_namespace_packages
+import re
 from pathlib import Path
 
 with open('README.md', 'r', encoding='utf-8') as f:
     long_description = f.read()
 
+VERSION = re.search(r'"([^"]+)"', Path('src/version.py').read_text().split('__version__')[1]).group(1)
+
 setup(
     name='pyLoopSage',  # Package name
-    version='1.1.5',  # Version of the software
+    version=VERSION,  # read from src/version.py
     description='An energy-based stochastic model of loop extrusion in chromatin.',
     long_description=long_description,
     long_description_content_type='text/markdown',
@@ -14,10 +17,14 @@ setup(
     author_email='s.korsak@datascience.edu.pl',
     url='https://github.com/SFGLab/pyLoopSage',  # GitHub repository URL
     license='GNU General Public License v3.0',
-    packages=find_packages(include=['loopsage', 'loopsage.*']),
+    package_dir={'': 'src'},
+    packages=find_namespace_packages('src', exclude=['*__pycache__*']),
+    py_modules=['run', 'logger', 'version'],
     include_package_data=True,
     package_data={
-    'loopsage': ['forcefields/*'],
+        'html': ['*.html', '*.css'],
+        'molecular_dynamics.forcefields': ['*.xml'],
+        'motif_finder.data': ['*.pfm'],
     },
     install_requires=[  # List your package dependencies here
         'numpy>1.2,<2.0',
@@ -40,11 +47,12 @@ setup(
         'imageio[ffmpeg]',
         'pillow',
         'pyBigWig',
+        'hic-straw',  # reads .hic files (--hic)
         'topoly',
     ],
     entry_points={
         'console_scripts': [
-            'loopsage=loopsage.run:main',  # loopsage command points to run.py's main function
+            'loopsage=run:main',  # the `loopsage` command runs src/run.py
         ],
     },
     classifiers=[
@@ -53,4 +61,4 @@ setup(
         'Operating System :: POSIX :: Linux',  # General OS classifier
     ],
     python_requires='>=3.10',  # Specify Python version compatibility
-)
+)

pyloopsage-2.0.0rc2/src/analysis/__init__.py

@@ -0,0 +1 @@
+"""Post-processing of Monte Carlo / MD results (no plotting here)."""

pyloopsage-2.0.0rc2/src/analysis/ensemble.py

@@ -0,0 +1,202 @@
+"""Loop statistics of the equilibrium ensemble.
+
+- Convergence and equilibrium diagnostics of the Monte Carlo run.
+- Extra insight metrics for the loop ensemble: anchor recovery, LEF dynamics, length agreement.
+- Agreement between independent MC chains (replicas).
+- Epigenetic model: average state, same-state map, agreement of loop ends, energy over time.
+"""
+import numpy as np
+from scipy.ndimage import gaussian_filter1d
+from scipy.stats import ks_2samp, spearmanr
+
+
+# ---- Loop statistics of the equilibrium ensemble ---------------------------
+
+_MOVES = ("Rebinding", "Sliding", "Epigenetic-state change")
+
+
+def loop_lengths(res) -> np.ndarray:
+    """All loop lengths (beads) of every LEF in every post-burn-in snapshot."""
+    return (res.production(res.Ns) - res.production(res.Ms)).ravel()
+
+
+def occupancy(res, n_beads: int) -> np.ndarray:
+    """Average number of LEF legs sitting on each bead (anchor probability)."""
+    legs = np.concatenate([res.production(res.Ms).ravel(), res.production(res.Ns).ravel()])
+    return np.bincount(legs, minlength=n_beads) / res.production(res.Es).shape[0]
+
+
+def acceptance_table(res) -> list:
+    """[(move, proposed, accepted, rate)] for each move type that was used."""
+    return [(name, int(p), int(a), a / p) for name, (p, a) in zip(_MOVES, res.acc) if p > 0]
+
+
+def loop_pairs_of_frame(ms, ns) -> np.ndarray:
+    """Unique loops (left, right) of one MC snapshot as an (k, 2) int array; zero-length loops dropped."""
+    lo, hi = np.minimum(ms, ns), np.maximum(ms, ns)
+    pairs = np.unique(np.c_[lo, hi][hi > lo], axis=0)
+    return pairs.astype(int)
+
+
+# ---- Convergence and equilibrium diagnostics of the Monte Carlo run --------
+
+TERMS = {"Es": "Total energy", "Bs": "Binding energy", "Ks": "Crossing energy",
+         "Fs": "Folding energy", "ufs": "Unfolded fraction"}
+
+
+def acf(x, max_lag=None) -> np.ndarray:
+    """Normalised autocorrelation function (FFT based), lag 0 = 1."""
+    x = np.asarray(x, float) - np.mean(x)
+    n = len(x)
+    f = np.fft.rfft(x, 2 * n)
+    a = np.fft.irfft(f * np.conj(f))[:n]
+    a = a / a[0] if a[0] > 0 else np.zeros(n)
+    return a[: (max_lag or n // 2) + 1]
+
+
+def integrated_time(x) -> float:
+    """Integrated autocorrelation time in samples (Sokal self-consistent window)."""
+    rho = acf(x, len(x) - 1)
+    tau = 1.0
+    for m in range(1, len(rho)):
+        tau = 1 + 2 * rho[1:m + 1].sum()
+        if m >= 5 * tau:
+            break
+    return float(max(tau, 1.0))
+
+
+def detrend(x, deg: int = 3) -> np.ndarray:
+    """Remove a polynomial trend (annealing drifts the energy)."""
+    t = np.arange(len(x))
+    return np.asarray(x) - np.polyval(np.polyfit(t, x, deg), t)
+
+
+def equilibrium_summary(res) -> dict:
+    """Post-burn-in mean/std per term, drift between halves, and effective sample size."""
+    out, annealing = {}, res.meta["method"] == "Annealing"
+    for key in TERMS:
+        x = res.production(getattr(res, key))
+        half = len(x) // 2
+        drift = (x[half:].mean() - x[:half].mean()) / (x.std() + 1e-12) if half > 1 else 0.0
+        out[key] = dict(mean=float(x.mean()), std=float(x.std()), drift=float(drift))
+    x = res.production(res.Fs)
+    tau = integrated_time(detrend(x) if annealing else x) if len(x) > 10 else 1.0
+    out["tau"], out["ess"], out["n"] = tau, len(x) / tau, len(x)
+    return out
+
+
+# ---- Extra insight metrics for the loop ensemble: anchor recovery, LEF dynamics, length agreement ----
+
+def anchor_profile(inputs) -> np.ndarray:
+    """Input anchor strength per bead (L + R)."""
+    return inputs.loops.L + inputs.loops.R
+
+
+def anchor_recovery(res, inputs, sigma: float = 1.0) -> dict:
+    """How well LEF legs sit on the strongest input anchors.
+
+    Anchors = beads above the 75th percentile of the non-zero input signal.
+    recall = anchors that hold a LEF leg; precision = occupied beads that are anchors.
+    """
+    occ, sig = occupancy(res, len(inputs.loops.L)), anchor_profile(inputs)
+    nz = sig[sig > 0]
+    anchors = sig >= (np.percentile(nz, 75) if nz.size else np.inf)
+    used = occ > 0.5 * occ.max() if occ.max() > 0 else occ > 0
+    rho = spearmanr(gaussian_filter1d(occ, sigma), gaussian_filter1d(sig, sigma))[0] if sig.std() > 0 else np.nan
+    return dict(n_anchor_beads=int(anchors.sum()), n_used_beads=int(used.sum()),
+                recall=float((anchors & used).sum() / max(anchors.sum(), 1)),
+                precision=float((anchors & used).sum() / max(used.sum(), 1)), spearman=float(rho))
+
+
+def lef_dynamics(res, jump_beads: int = 20) -> dict:
+    """Stability of loops between consecutive post-burn-in snapshots."""
+    ms, ns = res.production(res.Ms), res.production(res.Ns)
+    same = (ms[:, 1:] == ms[:, :-1]) & (ns[:, 1:] == ns[:, :-1])
+    jumps = (np.abs(ms[:, 1:] - ms[:, :-1]) > jump_beads) | (np.abs(ns[:, 1:] - ns[:, :-1]) > jump_beads)
+    step, n_int = res.meta["mc_step"], max(same.shape[1], 1)
+    changes = (~same).sum(axis=1)
+    return dict(stable_fraction=float(same.mean()),
+                dwell_steps=float(n_int * step / np.maximum(changes, 1).mean()),
+                rebinding_per_1000=float(jumps.sum(axis=1).mean() / (n_int * step) * 1000),
+                frozen_lefs=float((changes == 0).mean()))
+
+
+def length_agreement(res, inputs, geom):
+    """Input vs simulated loop lengths in kb: (input_kb, sim_kb, KS statistic, p-value)."""
+    inp = geom.beads_to_bp(inputs.loops.loop_lengths) / 1e3
+    sim = geom.beads_to_bp(loop_lengths(res)) / 1e3
+    if inp.size < 2 or sim.size < 2:
+        return inp, sim, np.nan, np.nan
+    ks = ks_2samp(inp, sim)
+    return inp, sim, float(ks.statistic), float(ks.pvalue)
+
+
+# ---- Agreement between independent MC chains (replicas) --------------------
+
+def r_hat(chains) -> float:
+    """Gelman-Rubin potential scale reduction of a scalar series per chain (1 = chains agree)."""
+    n = min(len(c) for c in chains)
+    x = np.array([c[-n:] for c in chains], float)
+    m = len(x)
+    w, b = x.var(axis=1, ddof=1).mean(), n * x.mean(axis=1).var(ddof=1)
+    return float(np.sqrt(((n - 1) / n * w + b / n) / w)) if w > 0 else float("nan")
+
+
+def replica_summary(res) -> dict:
+    """Per-chain energy statistics, occupancy profiles and their pairwise correlation."""
+    chains = res.chains
+    prod = [c.production(c.Es) for c in chains]
+    occ = np.array([occupancy(c, c.meta["n_beads"]) for c in chains])
+    corr = np.corrcoef(occ) if len(chains) > 1 else np.ones((1, 1))
+    iu = np.triu_indices(len(chains), 1)
+    return dict(energy=prod, mean=np.array([e.mean() for e in prod]), std=np.array([e.std() for e in prod]), occ=occ, corr=corr,
+                rhat=r_hat(prod) if len(chains) > 1 else float("nan"), min_corr=float(corr[iu].min()) if len(iu[0]) else float("nan"))
+
+
+# ---- Epigenetic model: states of beads and their link to the loops ----------
+
+def state_fractions(S, n_states: int) -> np.ndarray:
+    """(n_states, n_beads): fraction of snapshots in which each bead is in each state."""
+    return np.stack([(S == s).mean(axis=1) for s in range(n_states)])
+
+
+def same_state_map(S, n_states: int) -> np.ndarray:
+    """P(S_i == S_j) over snapshots for every pair of beads (1 on the diagonal)."""
+    out = np.zeros((S.shape[0],) * 2)
+    for s in range(n_states):
+        x = (S == s).astype(float)
+        out += x @ x.T
+    return out / S.shape[1]
+
+
+def loop_state_agreement(res, n_states: int, n_bins: int = 10) -> dict:
+    """Do the two ends of a loop share an epigenetic state more often than expected at that distance?
+
+    Returns bin centres (beads), observed rate for loop ends and baseline rate for any two beads
+    the same distance apart (baseline = mean of the same-state map along the matching diagonal).
+    """
+    S = res.production(res.epi)
+    M = same_state_map(S, n_states)
+    m, n = res.production(res.Ms), res.production(res.Ns)              # (n_lef, n_snapshots)
+    d = (n - m).ravel()
+    same = (np.take_along_axis(S, m, 0) == np.take_along_axis(S, n, 0)).ravel()
+    base_d = np.array([np.diagonal(M, k).mean() if k < M.shape[0] else np.nan for k in range(M.shape[0])])
+    edges = np.unique(np.geomspace(max(d.min(), 1), d.max() + 1, n_bins + 1).astype(int))
+    idx = np.clip(np.digitize(d, edges) - 1, 0, len(edges) - 2)
+    keep = [b for b in range(len(edges) - 1) if (idx == b).any()]
+    return dict(
+        sep=np.array([d[idx == b].mean() for b in keep]),
+        loops=np.array([same[idx == b].mean() for b in keep]),
+        baseline=np.array([np.nanmean(base_d[d[idx == b]]) for b in keep]),
+        overall=float(same.mean()), overall_base=float(np.nanmean(base_d[d])))
+
+
+def epigenetic_energy_series(p, res) -> tuple:
+    """Epigenetic-model energy at every saved snapshot: (MC steps, energies)."""
+    from monte_carlo.energy import E_epi, E_epi_dyn
+    out = np.empty(res.n_samples)
+    for k in range(res.n_samples):
+        S = res.epi[:, k].astype(np.int64)
+        ms, ns = res.Ms[:, k].astype(np.int64), res.Ns[:, k].astype(np.int64)
+        out[k] = E_epi_dyn(S, ms, ns, p.h, p.epi_norm) if p.epi_dynamic else E_epi(S, p.J, p.h, p.epi_norm)
+    return np.arange(res.n_samples) * res.meta["mc_step"], out

pyloopsage-2.0.0rc2/src/analysis/inputs.py

@@ -0,0 +1,127 @@
+"""Anchor-level view of a BEDPE: position, strength, CTCF orientation and its confidence.
+
+- Compartment (A/B) domains and their relation to loop anchors.
+"""
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.stats import mannwhitneyu
+
+from preproc.readers import numeric_col, read_region_table, valid_prob
+
+
+# ---- Anchor-level view of a BEDPE: position, strength, CTCF orientation and its confidence ----
+
+CONF_MIN = 0.2          # below this an orientation call is treated as uncertain
+CONFIGS = ("convergent", "tandem", "divergent", "uncertain")
+
+
+@dataclass
+class Anchors:
+    bp: np.ndarray          # anchor centre (bp)
+    strength: np.ndarray    # loop weight carried by the anchor
+    p_rev: np.ndarray       # P(reverse), -1 = unknown
+    loop: np.ndarray        # index of the loop each anchor belongs to
+    left_bp: np.ndarray     # per loop: left / right anchor centre (bp)
+    right_bp: np.ndarray
+    loop_strength: np.ndarray
+    config: np.ndarray      # per loop: one of CONFIGS
+
+    @property
+    def confidence(self) -> np.ndarray:
+        return np.where(self.p_rev >= 0, np.abs(2 * self.p_rev - 1), 0.0)
+
+    @property
+    def orient(self) -> np.ndarray:
+        """'forward' / 'reverse' / 'ambiguous' / 'unknown' per anchor."""
+        o = np.where(self.p_rev < 0.5, "forward", "reverse").astype(object)
+        o[self.confidence < CONF_MIN] = "ambiguous"
+        o[self.p_rev < 0] = "unknown"
+        return o
+
+    @property
+    def loop_len_bp(self) -> np.ndarray:
+        return self.right_bp - self.left_bp
+
+
+def _config(p_left, p_right) -> np.ndarray:
+    """Loop configuration from the orientations of its left and right anchors."""
+    sure = lambda p: (p >= 0) & (np.abs(2 * p - 1) >= CONF_MIN)
+    ok = sure(p_left) & sure(p_right)
+    lf, rf = p_left < 0.5, p_right < 0.5
+    out = np.full(len(p_left), "uncertain", dtype=object)
+    out[ok & lf & ~rf] = "convergent"          # left forward, right reverse: -> ... <-
+    out[ok & ~lf & rf] = "divergent"
+    out[ok & (lf == rf)] = "tandem"
+    return out
+
+
+def anchor_table(path, geom):
+    """Anchors of every BEDPE loop in the region, or None if the file has no loops."""
+    df = read_region_table(path, geom, paired=True)
+    if df.empty:
+        return None
+    c1, c2 = (df[1] + df[2]).to_numpy() / 2, (df[4] + df[5]).to_numpy() / 2
+    w = numeric_col(df, 6, 1.0)
+    p1, p2 = numeric_col(df, 7, -1.0), numeric_col(df, 8, -1.0)
+    if not (valid_prob(p1) and valid_prob(p2)):
+        p1 = p2 = np.full(len(df), -1.0)
+    swap = c1 > c2                                        # make anchor 1 the left one
+    cl, cr = np.where(swap, c2, c1), np.where(swap, c1, c2)
+    pl, pr = np.where(swap, p2, p1), np.where(swap, p1, p2)
+    n = len(df)
+    return Anchors(bp=np.concatenate([cl, cr]), strength=np.concatenate([w, w]), p_rev=np.concatenate([pl, pr]),
+                   loop=np.concatenate([np.arange(n), np.arange(n)]), left_bp=cl, right_bp=cr,
+                   loop_strength=w, config=_config(pl, pr))
+
+
+def orientation_summary(a: Anchors) -> list:
+    """Rows [class, anchors, share, median strength, mean confidence]."""
+    rows, o = [], a.orient
+    for name in ("forward", "reverse", "ambiguous", "unknown"):
+        m = o == name
+        rows.append([name, int(m.sum()), m.mean(), float(np.median(a.strength[m])) if m.any() else 0.0,
+                     float(a.confidence[m].mean()) if m.any() else 0.0])
+    return rows
+
+
+def config_summary(a: Anchors) -> list:
+    """Rows [configuration, loops, share, mean length (kb), mean strength]."""
+    rows = []
+    for name in CONFIGS:
+        m = a.config == name
+        rows.append([name, int(m.sum()), m.mean(), float(a.loop_len_bp[m].mean() / 1e3) if m.any() else 0.0,
+                     float(a.loop_strength[m].mean()) if m.any() else 0.0])
+    return rows
+
+
+# ---- Compartment (A/B) domains and their relation to loop anchors ----------
+
+def domains(comp, min_beads: int = 2):
+    """Runs of equal sign: list of (first_bead, last_bead, 'A' or 'B'); runs shorter than min_beads are merged away."""
+    sign = np.where(np.asarray(comp) >= 0, 1, -1)
+    edges = np.flatnonzero(np.diff(sign)) + 1
+    out = []
+    for s, e in zip(np.r_[0, edges], np.r_[edges, len(sign)]):
+        if e - s >= min_beads or not out:
+            out.append([s, e - 1, "A" if sign[s] > 0 else "B"])
+        else:
+            out[-1][1] = e - 1                     # absorb a flicker into the previous domain
+    merged = []
+    for d in out:                                  # fuse neighbours of the same type
+        if merged and merged[-1][2] == d[2]:
+            merged[-1][1] = d[1]
+        else:
+            merged.append(d)
+    return [tuple(d) for d in merged]
+
+
+def compartment_summary(comp, anchor_strength, geom) -> dict:
+    """Shares of A/B, domain sizes (kb) and anchor strength per compartment."""
+    doms, bp = domains(comp), geom.bp_per_bead
+    size = lambda t: np.array([(e - s + 1) * bp / 1e3 for s, e, k in doms if k == t])
+    a_mask = np.asarray(comp) >= 0
+    in_a, in_b = anchor_strength[a_mask], anchor_strength[~a_mask]
+    p = mannwhitneyu(in_a, in_b).pvalue if len(in_a) > 2 and len(in_b) > 2 and anchor_strength.std() > 0 else np.nan
+    return dict(frac_a=float(a_mask.mean()), n_domains=len(doms), size_a=size("A"), size_b=size("B"),
+                anchors_a=in_a, anchors_b=in_b, p=float(p), domains=doms)