# 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.
<img src="/img/fig0.svg">
### Installation
Install `phic` from PyPI using pip:
pip install phic
Without preparing a Python environment, PHi-C2 rus on [Google Colab](https://bit.ly/3rlptGI).
### Requirements
- PHi-C2 is based on `python3`.
- Python packages `numpy`, `matplotlib`, `scipy`, `numba`, `click`.
To visualize the simulated polymer dynamics and conformations, [VMD](https://www.ks.uiuc.edu/Research/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.**
[_Bioinformatics_ **38**(21) 4984–4986](https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btac613/6695219).
<!--
We will submit a manuscript on PHi-C2, in which we dramatically updated the algorithm of the optimization procedure.
But, the basic framework remains the same in the following papers:
- Soya Shinkai, Masaki Nakagawa, Takeshi Sugawara, Yuichi Togashi, Hiroshi Ochiai, Ryuichiro Nakato, Yuichi Taniguchi, and Shuichi Onami. (2020). **PHi-C: deciphering Hi-C data into polymer dynamics.** [_NAR Genomics and Bioinformatics_ **2** (2) lqaa020](https://doi.org/10.1093/nargab/lqaa020).
- Soya Shinkai, Takeshi Sugawara, Hisashi Miura, Ichiro Hiratani, and Shuichi Onami. (2020). **Microrheology for Hi-C Data Reveals the Spectrum of the Dynamic 3D Genome Organization.** [_Biophysical Journal_ **118** 2220–2228](https://doi.org/10.1016/j.bpj.2020.02.020). -->
### Quick Start
After the installation of `phic` and downloading of the directory [_demo_](/demo), move to the directory [_demo_](/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](https://github.com/aidenlab/straw/tree/master/pybind11_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.](https://doi.org/10.1016/j.cell.2017.09.043).
* * *
### 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](https://github.com/aidenlab/straw/tree/master/pybind11_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]
--for-high-resolution INTEGER Normalization of contact map for high-resolution case (ex. 1-kb, 500-bp, 200-bp) [default=0]
--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
<img src="/img/fig1.svg" height="250">
#### 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]
--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
<img src="/img/fig2.svg" height="500">
#### 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/
data_normalized_omega1.txt
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
<img src="/img/fig3.svg" height="250">
#### 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
<img src="/img/fig4.svg" height="250">
#### 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
<img src="/img/fig5.svg" height="250">
Raw data
{
"_id": null,
"home_page": "https://github.com/soyashinkai/PHi-C2",
"name": "phic",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "biophysics,bioinformatics,genomics,Hi-C,polymer modeling,polymer dynamics,rheology",
"author": "Soya SHINKAI",
"author_email": "soya.shinkai@riken.jp",
"download_url": "",
"platform": null,
"description": "# PHi-C2\nPHi-C2 allows for a physical interpretation of a Hi-C contact matrix.\nThe `phic` package includes a suite of command line tools.\n\n<img src=\"/img/fig0.svg\">\n\n### Installation\n\nInstall `phic` from PyPI using pip:\n\n pip install phic\n\nWithout preparing a Python environment, PHi-C2 rus on [Google Colab](https://bit.ly/3rlptGI).\n\n\n### Requirements\n- PHi-C2 is based on `python3`.\n- Python packages `numpy`, `matplotlib`, `scipy`, `numba`, `click`.\n\nTo visualize the simulated polymer dynamics and conformations, [VMD](https://www.ks.uiuc.edu/Research/vmd/) is needed.\n\n\n### Citation\n\nIf you use PHi-C2, please cite:\n\nSoya Shinkai, Hiroya Itoga, Koji Kyoda, and Shuichi Onami. (2022).\n**PHi-C2: interpreting Hi-C data as the dynamic 3D genome state.**\n[_Bioinformatics_ **38**(21) 4984\u20134986](https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btac613/6695219).\n\n<!--\nWe will submit a manuscript on PHi-C2, in which we dramatically updated the algorithm of the optimization procedure.\nBut, the basic framework remains the same in the following papers:\n\n- Soya Shinkai, Masaki Nakagawa, Takeshi Sugawara, Yuichi Togashi, Hiroshi Ochiai, Ryuichiro Nakato, Yuichi Taniguchi, and Shuichi Onami. (2020). **PHi-C: deciphering Hi-C data into polymer dynamics.** [_NAR Genomics and Bioinformatics_ **2** (2) lqaa020](https://doi.org/10.1093/nargab/lqaa020).\n\n- Soya Shinkai, Takeshi Sugawara, Hisashi Miura, Ichiro Hiratani, and Shuichi Onami. (2020). **Microrheology for Hi-C Data Reveals the Spectrum of the Dynamic 3D Genome Organization.** [_Biophysical Journal_ **118** 2220\u20132228](https://doi.org/10.1016/j.bpj.2020.02.020). -->\n\n### Quick Start\n\nAfter the installation of `phic` and downloading of the directory [_demo_](/demo), move to the directory [_demo_](/demo):\n\n demo/\n Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp.txt\n Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp_list.txt\n make_demo_input_by_Straw.py\n run.sh\n\nThen, run the following scripts:\n\n ./run.sh\n\nIt will take a few minutes.\n\nHere, `Bonev_ES_observed_KR_chr8_42100000-44525000_res25000bp.txt` is an input file generated by [Straw for Python](https://github.com/aidenlab/straw/tree/master/pybind11_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.](https://doi.org/10.1016/j.cell.2017.09.043).\n\n* * *\n\n### Usage\n\n`phic` needs a subcommand on the command line interface:\n\n phic SUBCOMMAND [OPTIONS]\n\n Subcommands:\n preprocessing\n |\n optimization\n |--> plot-optimization\n |--> dynamics\n |--> sampling\n |--> rheology\n |--> plot-compliance\n |--> plot-modulus\n |--> plot-tangent\n\nHere, _NAME.txt_ as an ipunt is in the contact matrix format produced by [Straw for Python](https://github.com/aidenlab/straw/tree/master/pybind11_python).\nAll output files of `phic` will be stored in the newly made directory _NAME_.\n\n#### 1. preprocessing\n\n phic preprocessing [OPTIONS]\n\n Options:\n --input TEXT Input contact matrix file dumped by Straw for a hic file [required]\n --res INTEGER Resolution of the bin size [required]\n --plt-max-c FLOAT Maximum value of contact map [required]\n --for-high-resolution INTEGER Normalization of contact map for high-resolution case (ex. 1-kb, 500-bp, 200-bp) [default=0]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/\n C_normalized.svg\n C_normalized.txt\n P_normalized.svg\n P_normalized.txt\n\n\nExample:\n\n phic preprocessing --input NAME.txt --res 25000 --plt-max-c 0.1\n\n<img src=\"/img/fig1.svg\" height=\"250\">\n\n#### 2. optimization\n\n phic optimization [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --init-k-backbone FLOAT Initial parameter of K_i,i+1 [default=0.5]\n --learning-rate FLOAT Learning rate [default=1e-4]\n --stop-condition-parameter FLOAT Parameter for the stop condition [default=1e-4]\n --help Show this message and exit.\n\n\nThe outputs are the followings:\n\n NAME/data_optimization/\n K_optimized.txt\n optimization.log\n\nExample:\n\n phic optimization --name NAME\n\n\n#### 3-1. plot-optimization\n\n phic plot-optimization [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --res INTEGER Resolution of the bin size [required]\n --plt-max-c FLOAT Maximum value of contact map [required]\n --plt-max-k-backbone FLOAT Maximum value of K_i,i+1 profile [required]\n --plt-max-k FLOAT Maximum and minimum values of optimized K map [required]\n --plt-k-dis-bins INTEGER The number of bins of distribution of optimized K values [required]\n --plt-max-k-dis FLOAT Maximum value of the K distributioin [required]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_optimization/\n C.svg\n C_optimized.txt\n Correlation.png\n Correlation_distance_corrected.png\n Cost.svg\n K.svg\n K_backbone.svg\n K_backbone.txt\n K_distribution.svg\n P.svg\n\nExample:\n\n 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\n\n<img src=\"/img/fig2.svg\" height=\"500\">\n\n\n#### 3-2. dynamics\n\n phic dynamics [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --eps FLOAT Stepsize in the Langevin dynamics [default=1e-3]\n --interval INTEGER The number of steps between output frames [required]\n --frame INTEGER The number of output frames [required]\n --sample INTEGER The number of output dynamics [default=1]\n --seed INTEGER Seed of the random numbers [default=12345678]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_dynamics/\n polymer_N{NUMBER-OF-BEADS}.psf\n sample{SAMPLE-NUMBER}.xyz\n\nExample:\n\n phic dynamics --name NAME --interval 100 --frame 1000\n\n#### 3-3. sampling\n\n phic sampling [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --sample INTEGER The number of output conformations [required]\n --seed INTEGER Seed of the random numbers [default=12345678]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_sampling/\n polymer_N{NUMBER-OF-BEADS}.psf\n conformations.xyz\n\nExample:\n\n phic sampling --name NAME --sample 1000\n\n#### 3-4-1. rheology\n\n phic rheology [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --upper INTEGER Upper value of the exponent of the angular frequency [default=1]\n --lower INTEGER Lower value of the exponent of the angular frequency [default=-5]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_rheology/\n data_normalized_omega1.txt\n n{BEAD-NUMBER}.txt\n\nExample:\n\n phic rheology --name NAME\n\n\n#### 3-4-2. plot-compliance\n\n phic plot-compliance [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --upper INTEGER Upper value of the exponent of the angular frequency [default=1]\n --lower INTEGER Lower value of the exponent of the angular frequency [default=-5]\n --plt-upper INTEGER Upper value of the exponent of the angular frequency in the spectrum [required]\n --plt-lower INTEGER Lower value of the exponent of the angular frequency in the spectrum [required]\n --plt-max-log FLOAT Maximum value of log10 |J*| [required]\n --plt-min-log FLOAT Minimum value of log10 |J*| [required]\n --aspect FLOAT Aspect ratio of the spectrum [default=0.8]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_rheology/\n data_J_storage_spectrum.txt\n data_J_loss_spectrum.txt\n data_J_abs_spectrum.txt\n NAME/data_rheology/figs/\n J_storage_spectrum.svg\n J_loss_spectrum.svg\n J_abs_spectrum.svg\n J_curves.png\n\nExample:\n\n phic plot-compliance --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 1.3 --plt-min-log -0.3\n\n<img src=\"/img/fig3.svg\" height=\"250\">\n\n\n#### 3-4-2. plot-modulus\n\n phic plot-modulus [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --upper INTEGER Upper value of the exponent of the angular frequency [default=1]\n --lower INTEGER Lower value of the exponent of the angular frequency [default=-5]\n --plt-upper INTEGER Upper value of the exponent of the angular frequency in the spectrum [required]\n --plt-lower INTEGER Lower value of the exponent of the angular frequency in the spectrum [required]\n --plt-max-log FLOAT Maximum value of log10 |G*| [required]\n --plt-min-log FLOAT Minimum value of log10 |G*| [required]\n --aspect FLOAT Aspect ratio of the spectrum [default=0.8]\n --help Show this message and exit.\n\nThe outputs are the followings:\n\n NAME/data_rheology/\n data_G_storage_spectrum.txt\n data_G_loss_spectrum.txt\n data_G_abs_spectrum.txt\n NAME/data_rheology/figs/\n G_storage_spectrum.svg\n G_loss_spectrum.svg\n G_abs_spectrum.svg\n G_curves.png\n\nExample:\n\n phic plot-modulus --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 0.4 --plt-min-log -1.2\n\n<img src=\"/img/fig4.svg\" height=\"250\">\n\n#### 3-4-3. plot-tangent\n\n phic plot-tangent [OPTIONS]\n\n Options:\n --name TEXT Target directory name [required]\n --upper INTEGER Upper value of the exponent of the angular frequency [default=1]\n --lower INTEGER Lower value of the exponent of the angular frequency [default=-5]\n --plt-upper INTEGER Upper value of the exponent of the angular frequency in the spectrum [required]\n --plt-lower INTEGER Lower value of the exponent of the angular frequency in the spectrum [required]\n --plt-max-log FLOAT Maximum value of log10 tan\u03b4 [required]\n --aspect FLOAT Aspect ratio of the spectrum [default=0.8]\n --help Show this message and exit.\n\nThe output is the following:\n\n NAME/data_rheology/\n data_tan_spectrum.txt\n NAME/data_rheology/figs/\n tan_spectrum.svg\n\nExample:\n\n phic plot-tangent --name NAME --plt-upper 0 --plt-lower -3 --plt-max-log 0.2\n\n<img src=\"/img/fig5.svg\" height=\"250\">\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Polymer dynamics deciphered from Hi-C data",
"version": "2.0.13",
"project_urls": {
"Homepage": "https://github.com/soyashinkai/PHi-C2"
},
"split_keywords": [
"biophysics",
"bioinformatics",
"genomics",
"hi-c",
"polymer modeling",
"polymer dynamics",
"rheology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2215ffe100172f871329542f15d1dcd607845cef86318c2d76eb17a6aea70cc",
"md5": "973dbfc051f831fe898df00b568ed1a9",
"sha256": "d07e1f5ff5a513dd301e23491cf51d5ab0d7bd26c46deaa62c2017af4ed6fa58"
},
"downloads": -1,
"filename": "phic-2.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "973dbfc051f831fe898df00b568ed1a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23510,
"upload_time": "2024-02-09T09:18:30",
"upload_time_iso_8601": "2024-02-09T09:18:30.160545Z",
"url": "https://files.pythonhosted.org/packages/c2/21/5ffe100172f871329542f15d1dcd607845cef86318c2d76eb17a6aea70cc/phic-2.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-09 09:18:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "soyashinkai",
"github_project": "PHi-C2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "phic"
}
JSON
