phic 2.0.7

Polymer dynamics deciphered from Hi-C data

PHi-C2

PHi-C2 allows for a physical interpretation of a Hi-C contact matrix. The phic package includes a suite of command line tools.

Installation

Install phic from PyPI using pip:

pip install phic

Without preparing a Python environment, PHi-C2 rus on Google Colab.

Requirements

• PHi-C2 is based on python3.
• Python packages numpy, matplotlib, scipy, numba, click.

To visualize the simulated polymer dynamics and conformations, VMD is needed.

Citation

If you use PHi-C2, please cite:

Soya Shinkai, Hiroya Itoga, Koji Kyoda, and Shuichi Onami. (2022). PHi-C2: interpreting Hi-C data as the dynamic 3D genome state. bioRxiv.

Quick Start

After the installation of phic and downloading of the directory demo, move to the directory demo:

demo/
  Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp.txt
  Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp_list.txt
  make_demo_input_by_Straw.py
  run.sh

Then, run the following scripts:

./run.sh

It will take a few minutes.

Here, Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp.txt is an input file generated by Straw for Python with KR normalization for Hi-C data of mouse embryo stem cells (chr8: 42,100-44,525 kb, 25-kb resolution) by Bonev et al..

---

Usage

phic needs a subcommand on the command line interface:

phic SUBCOMMAND [OPTIONS]

Subcommands:
preprocessing
  |
optimization
  |-->  plot-optimization
  |-->  dynamics
  |-->  sampling
  |-->  rheology
          |--> plot-compliance
          |--> plot-modulus
          |--> plot-tangent

Here, NAME.txt as an ipunt is in the contact matrix format produced by Straw for Python. All output files of phic will be stored in the newly made directory NAME.

1. preprocessing

phic preprocessing [OPTIONS]

Options:
  --input     TEXT      Input contact matrix file dumped by Straw for a hic file  [required]
  --res       INTEGER   Resolution of the bin size  [required]
  --plt-max-c FLOAT     Maximum value of contact map  [required]
  --help                Show this message and exit.

The outputs are the followings:

NAME/
  C_normalized.svg
  C_normalized.txt
  P_normalized.svg
  P_normalized.txt

Example:

phic preprocessing --input NAME.txt --res 25000 --plt-max-c 0.1

2. optimization

phic optimization [OPTIONS]

Options:
  --name                      TEXT   Target directory name  [required]
  --init-k-backbone           FLOAT  Initial parameter of K_i,i+1  [default=0.5]
  --learning-rate             FLOAT  Learning rate  [default=1e-4]
  --stop-condition-parameter  FLOAT  Parameter for the stop condition  [default=1e-4]
  --threads                   TEXT   The number of threads  [default=1]
  --help                             Show this message and exit.

The outputs are the followings:

NAME/data_optimization/
  K_optimized.txt
  optimization.log

Example:

phic optimization --name NAME

3-1. plot-optimization

phic plot-optimization [OPTIONS]

Options:
  --name                TEXT      Target directory name  [required]
  --res                 INTEGER   Resolution of the bin size  [required]
  --plt-max-c           FLOAT     Maximum value of contact map  [required]
  --plt-max-k-backbone  FLOAT     Maximum value of K_i,i+1 profile  [required]
  --plt-max-k           FLOAT     Maximum and minimum values of optimized K map  [required]
  --plt-k-dis-bins      INTEGER   The number of bins of distribution of optimized K values  [required]
  --plt-max-k-dis       FLOAT     Maximum value of the K distributioin  [required]
  --help                          Show this message and exit.

The outputs are the followings:

NAME/data_optimization/
  C.svg
  C_optimized.txt
  Correlation.png
  Correlation_distance_corrected.png
  Cost.svg
  K.svg
  K_backbone.svg
  K_backbone.txt
  K_distribution.svg
  P.svg

Example:

phic plot-optimization --name NAME --res 25000 --plt-max-c 0.1 --plt-max-k-backbone 1.0 --plt-max-k 0.1 --plt-k-dis-bins 200 --plt-max-k-dis 100

3-2. dynamics

phic dynamics [OPTIONS]

Options:
  --name      TEXT      Target directory name  [required]
  --eps       FLOAT     Stepsize in the Langevin dynamics  [default=1e-3]
  --interval  INTEGER   The number of steps between output frames  [required]
  --frame     INTEGER   The number of output frames  [required]
  --sample    INTEGER   The number of output dynamics  [default=1]
  --seed      INTEGER   Seed of the random numbers  [default=12345678]
  --help                Show this message and exit.

The outputs are the followings:

NAME/data_dynamics/
  polymer_N{NUMBER-OF-BEADS}.psf
  sample{SAMPLE-NUMBER}.xyz

Example:

phic dynamics --name NAME --interval 100 --frame 1000

3-3. sampling

phic sampling [OPTIONS]

Options:
  --name    TEXT      Target directory name  [required]
  --sample  INTEGER   The number of output conformations  [required]
  --seed    INTEGER   Seed of the random numbers  [default=12345678]
  --help              Show this message and exit.

The outputs are the followings:

NAME/data_sampling/
  polymer_N{NUMBER-OF-BEADS}.psf
  conformations.xyz

Example:

phic sampling --name NAME --sample 1000

3-4-1. rheology

phic rheology [OPTIONS]

Options:
  --name    TEXT      Target directory name  [required]
  --upper   INTEGER   Upper value of the exponent of the angular frequency  [default=1]
  --lower   INTEGER   Lower value of the exponent of the angular frequency  [default=-5]
  --help              Show this message and exit.

The outputs are the followings:

NAME/data_rheology/
  n{BEAD-NUMBER}.txt

Example:

phic rheology --name NAME

3-4-2. plot-compliance

phic plot-compliance [OPTIONS]

Options:
  --name          TEXT      Target directory name  [required]
  --upper         INTEGER   Upper value of the exponent of the angular frequency  [default=1]
  --lower         INTEGER   Lower value of the exponent of the angular frequency  [default=-5]
  --plt-upper     INTEGER   Upper value of the exponent of the angular frequency in the spectrum  [required]
  --plt-lower     INTEGER   Lower value of the exponent of the angular frequency in the spectrum  [required]
  --plt-max-log   FLOAT     Maximum value of log10 |J*|  [required]
  --plt-min-log   FLOAT     Minimum value of log10 |J*|  [required]
  --aspect        FLOAT     Aspect ratio of the spectrum  [default=0.8]
  --help                    Show this message and exit.

The outputs are the followings:

NAME/data_rheology/
  data_J_storage_spectrum.txt
  data_J_loss_spectrum.txt
  data_J_abs_spectrum.txt
NAME/data_rheology/figs/
  J_storage_spectrum.svg
  J_loss_spectrum.svg
  J_abs_spectrum.svg
  J_curves.png

Example:

phic plot-compliance --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 1.3 --plt-min-log -0.3

3-4-2. plot-modulus

phic plot-modulus [OPTIONS]

Options:
  --name          TEXT      Target directory name  [required]
  --upper         INTEGER   Upper value of the exponent of the angular frequency  [default=1]
  --lower         INTEGER   Lower value of the exponent of the angular frequency  [default=-5]
  --plt-upper     INTEGER   Upper value of the exponent of the angular frequency in the spectrum  [required]
  --plt-lower     INTEGER   Lower value of the exponent of the angular frequency in the spectrum  [required]
  --plt-max-log   FLOAT     Maximum value of log10 |G*|  [required]
  --plt-min-log   FLOAT     Minimum value of log10 |G*|  [required]
  --aspect        FLOAT     Aspect ratio of the spectrum  [default=0.8]
  --help                    Show this message and exit.

The outputs are the followings:

NAME/data_rheology/
  data_G_storage_spectrum.txt
  data_G_loss_spectrum.txt
  data_G_abs_spectrum.txt
NAME/data_rheology/figs/
  G_storage_spectrum.svg
  G_loss_spectrum.svg
  G_abs_spectrum.svg
  G_curves.png

Example:

phic plot-modulus --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 0.4 --plt-min-log -1.2

3-4-3. plot-tangent

phic plot-tangent [OPTIONS]

Options:
  --name          TEXT      Target directory name  [required]
  --upper         INTEGER   Upper value of the exponent of the angular frequency  [default=1]
  --lower         INTEGER   Lower value of the exponent of the angular frequency  [default=-5]
  --plt-upper     INTEGER   Upper value of the exponent of the angular frequency in the spectrum  [required]
  --plt-lower     INTEGER   Lower value of the exponent of the angular frequency in the spectrum  [required]
  --plt-max-log   FLOAT     Maximum value of log10 tanδ  [required]
  --aspect        FLOAT     Aspect ratio of the spectrum  [default=0.8]
  --help                    Show this message and exit.

The output is the following:

NAME/data_rheology/
  data_tan_spectrum.txt
NAME/data_rheology/figs/
  tan_spectrum.svg

Example:

phic plot-tangent --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 0.2