Skip to content

RepliSage

Python OpenMM NumPy Numba SciPy Matplotlib PyVista tested with pytest License GPL v3

RepliSage documentation

Welcome. These pages explain what RepliSage models, how to run it, and how to read what comes out. Start with the quick path below, then dive into whichever model you want to understand or tune.

How the documentation is organised

Section What it covers
Getting started Installation, command line and examples
Theory The ideas behind the model, without implementation details: scope and goals, the idea in a nutshell, the Hamiltonian idea, Monte Carlo, MCMC and Metropolis, microstates and macrostates, metrics
Implementation How the ideas are coded: pipeline, pre-processing, replication model, Monte Carlo model, molecular dynamics model
Reference Configuration, analysis and outputs and visualisation
Known limitations What the model leaves out: limitations

Quick path

  1. Read Scope and goals and the idea in a nutshell to see what the model is for.
  2. Install RepliSage and try the command line.
  3. Look at the pipeline to see what runs, and at the outputs to read the report.
  4. Come back to the Theory pages when you want to understand or tune a parameter.

Two ways to set things

  • Flags (--bedpe-file, --rt-file, --run-md, --with-stress, ...) cover the everyday choices.
  • config.ini (-c config.ini) holds everything else: energies, temperatures, force-field and plotting details. Flags always win over the file, and the file wins over the built-in defaults.

A note on notation

The pages use the symbols of the RepliSage paper (\(\mathcal{H}\), \(N_{\text{beads}}\), \((m_i, n_i)\), \(s_k\), \(T_{\text{mc}}\), ...). The notation table maps each one to its config name. Known simplifications are listed at the end in Known limitations.

A note on units

  • Genomic positions are in base pairs. One bead covers a stretch of DNA of (region length) / N_BEADS base pairs.
  • Time in the Monte Carlo and in the replication model is counted in MC steps.
  • 3D coordinates are written in angstrom in the CIF files and simulated in nanometre units inside OpenMM.

Citation

  • Korsak, S. et al. "RepliSage: a stochastic graph-based framework for 3D chromatin modeling across the cell cycle." Nucleic Acids Research 54.12 (2026): gkag618.
  • Buka, K. et al. "Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes." Communications Biology 8.1 (2025): 437.
  • Massey, D. J. and Koren, A. "High-throughput analysis of single human cells reveals the complex nature of DNA replication timing control." Nature Communications 13 (2022): 2402.