pyLoopSage 0.0.2__tar.gz → 0.0.6__tar.gz

{pyloopsage-0.0.2 → pyloopsage-0.0.6}/LICENSE

@@ -632,7 +632,7 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) December 2023  Sebastian Korsak - Sevastianos Korsak 
+    Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
   If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    LoopSage  Copyright (C) December 2023  Sebastian Korsak - Sevastianos Korsak 
+    pyLoopSage  Copyright (C) 2024  Sebastian Korsak (Sevastianos Korsak)
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

{pyloopsage-0.0.2 → pyloopsage-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyLoopSage
-Version: 0.0.2
+Version: 0.0.6
 Summary: An energy-based stochastic model of loop extrusion in chromatin.
 Home-page: https://github.com/SFGLab/pyLoopSage
 Author: Sebastian Korsak
@@ -31,11 +31,17 @@ Requires-Dist: statsmodels
 Requires-Dist: imageio
 Requires-Dist: pillow
 
-# LoopSage
-An energy-based model for loop extrusion.
+# pyLoopSage
+Updated version of the stochastic loop extrusion model: LoopSage with capability to run incredibly fast, parallelized across CPU cores. This package is even more user-friendly and it can be installed via PyPI.
 
-**Important!!!** *Now the molecular dynamics can run for larger regions, since the code or `LoopSage_md.py` is fixed and does not allocate so much memory.*
+## New features
 
+- More user-friendly environment.
+- Installable with `pip install pyLoopSage`.
+- Parralelization of the stochastic simulation across multiple CPUs.
+- Capability of modelling the whole chromosome.
+- Visualization functions.
+- Capability to run form terminal with a simple command `loopsage -c config.ini`.
 
 ## Publication
 Please cite the method paper in case that you would like to use this model for your work,
@@ -44,33 +50,31 @@ Please cite the method paper in case that you would like to use this model for y
 
 ## The model
 
+We have a polymer chain with $$N_{\text{beads}}$$ number of monomers. In general we can scale by deault the granularity of the simulation so as to give reasonable results. Therefore if we have a `region` counted in genomic coordinates, we can assume that `N_beads=(region[1]-region[0])//2000`.
+
 Let's assume that each cohesin $i$ can be represented of two coordinates $(m_{i},n_{i})$ we allow three moves in our simulation:
 
-* Slide right ( $n_{i} -> n_{i+1}$ to the right).
-* Slide left ( $m_{i} -> m_{i-1}$ to the left).
+* Slide both locations randomly (as 1D random walk) or
 * Rebind somewhere else.
 
+In general a good working assumption is that the number of cohesins (or loop extrusion factors LEFs) is $$N_{\text{lef}}=2N_{\text{CTCF}}$$.
 
 The main idea of the algorithm is to ensemble loop extrusion from a Boltzmann probability distribution, with Hamiltonian,
 
-$$E = \dfrac{f}{N_{fold}}\sum_{i=1}^{N_{coh}}\log(n_i-m_i)+\dfrac{\kappa}{N_{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+\dfrac{b}{N_{bind}}\sum_{i=1}^{N_{coh}}\left(L(m_i)+R(n_i)\right)$$
+$$E = c_{\text{fold}}\sum_{i=1}^{N_{\text{coh}}}\log(n_i-m_i)+c_{\text{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+c_{\text{bind}}\sum_{i=1}^{N_{\text{coh}}}\left(L(m_i)+R(n_i)\right)$$
 
 The first term corresponds to the folding of chromatin, and the second term is a penalty for the appearance of crosss. Therefore, we have the function,
 $K(m_{i},n_{i};m_{j},n_{j})$ which takes the value 1 when $m_{i} < m_{j} < n_{i} < n_{j}$ or $m_{i}=m_{j}$ or $m_{i}=n_{j}$.
 
 These $L(\cdot), R(\cdot)$ functions are two functions that define the binding potential and they are orientation specific - so they are different for left and right position of cohesin (because CTCF motifs are orientation specific), therefore when we have a gap in these functions, it means presence of CTCF. These two functions are derived from data with CTCF binning and by running the script for probabilistic orientation. Moreover, by $N_{(\cdot)}$ we symbolize the normalization constants for each factor,
 
-$$N_{fold}=N_{coh}\cdot \langle n_i-m_i\rangle,\quad N_{cross}=N_{coh},\quad N_{bind}=\sum_{k}\left(L(k)+R(k)\right).$$
-
-An additional term which allows other protein factors that may act as barriers for the motion of LEFs can me optionally added,
-
-$$E_{bw}=\sum_{i=1}^{N_{\text{bw}}}\frac{r_{i}}{N_{bw,i}}\sum_{j=1}^{N_{lef}}\left(W_i(m_j)+W_i(n_j)\right),\qquad N_{bw,i} = \sum_{k}W_i(k)$$
+$$c_{\text{fold}}=-\dfrac{N_{\text{beads}}f}{N_{\text{lef}}\log(N_{\text{beads}}/N_{\text{lef}})},\quad c_{\text{bind}}=-\dfrac{N_{\text{beads}}b}{\sum_i \left(L(m_i)+R(n_i)\right)},\quad c_{\text{cross}}=\kappa \times 10^4.$$
 
-where $N_{bw}$ is the number of \texttt{.BigWig} ChIP-Seq experiments that are imported for each one of the proteins of interest. The energy term $W_{i}(\cdot)$ it corresponds to the average values of the ChIP-Seq experiment $i$ for each loci of interest. Finally, $r_{i}$ it is a weight that corresponds each one of these experiments and by default it is set as $r_{i}=b/2$.
+The parameters are defined in such a way that when $$f=b=\kappa=1$$, the three terms of the stochastic energy are balanced. 
 
-Thus,
+And the energy difference can be expressed as the energy difference of each term,
 
-$$\Delta E = \Delta E_{fold}+\Delta E_{cross}+\Delta E_{bind} + \Delta E_{bw}.$$
+$$\Delta E = \Delta E_{\text{fold}}+\Delta E_{\text{cross}}+\Delta E_{\text{bind}}.$$
 
 In this manner we accept a move in two cases:
 
@@ -79,35 +83,39 @@ In this manner we accept a move in two cases:
 
 And of course, the result - the distribution of loops in equilibrium -  depends on temperature of Boltzmann distribution $T$.
 
-## Packages to install
-Install a python 3.10 environment and OpenMM 8.0 and run 
-
-```
-pip install -r requirements.txt
-```
+## Installation
 
-For faster computations use CUDA toolkit: https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=20.04&target_type=deb_local.
+Can be easily installed with `pip install pyLoopSage`. To have CUDA acceleration, it is needed to have cuda-toolkit installed in case that you use nvidia drivers (otherwise you can use OpenCL or parallelization across CPU cores).
 
 ## How to use?
 
+### Python Implementation
+
 The main script is `LoopSage.py`. The implementation of the code is very easy and it can be described in the following lines,
 
 ```python
-N_steps, MC_step, burnin, T, T_min = int(1e4), int(2e2), 1000, 5,1
-region, chrom = [88271457,88851999], 'chr10'
-label=f'Petros_wt1h'
-bedpe_file = '/mnt/raid/data/Petros_project/loops/wt1h_pooled_2.bedpe'
-coh_track_file = '/mnt/raid/data/Petros_project/bw/RAD21_ChIPseq/mm_BMDM_WT_Rad21_heme_60min.bw'
-bw_file1 = '/mnt/raid/data/Petros_project/bw/BACH1_ChIPseq/mm_Bach1_1h_rep1_heme_merged.bw'
-bw_file2 = '/mnt/raid/data/Petros_project/bw/RNAPol_ChIPseq/WT-RNAPOLIIS2-1h-heme100-rep1_S5.bw'
-bw_files = [bw_file1,bw_file2]
-
-sim = LoopSage(region,chrom,bedpe_file,label=label,N_lef=50,N_beads=1000,bw_files=bw_files,track_file=coh_track_file)
-Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,poisson_choice=True,mode='Annealing',viz=True,save=True)
-sim.run_MD()
+# Definition of Monte Carlo parameters
+import Loopsage.stochastic_simulation as lps
+
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = lps.StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
 ```
 
-Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported. In `coh_track_file` you can optionally define the track file with some cohesin coverage of ChIP-Seq to determine the distribution of LEFs and allow preferencial binding in regions with higher signal. Then the user can optionally define a list of BigWig files which are needed in case that user would like to model other protein factors and their coefficients $r_i$.
+Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported.
 
 Note that the `.bedpe_file` must be in the following format,
 
@@ -128,6 +136,35 @@ where the last two columns represent the probabilites for left and right anchor
 
 Then, we define the main parameters of the simulation `N_beads,N_coh,kappa,f,b` or we can choose the default ones (take care because it might be the case that they are not the appropriate ones and they need to be changed), the parameters of Monte Carlo `N_steps, MC_step, burnin, T`, and we initialize the class `LoopSage()`. The command `sim.run_energy_minimization()` corresponds to the stochastic Monte Carlo simulation, and it produces a set of cohesin constraints as a result (`Ms, Ns`). Note that the stochastic simulation has two modes: `Annealing` and `Metropolis`. We feed cohesin constraints to the molecular simulation part of and we run `MD_LE()` or `MD_EM()` simulation which produces a trajectory of 3d-structures, and the average heatmap. `MD_LE()` function can produce an actual trajectory and a `.dcd` video of how simulation changes over time. However, the implementation needs a high amount of memory since we need to define a bond for each time step, and it may not work for large systems. `EM_LE()` is suggested for large simulations, because it does not require so big amount of memory.
 
+### Command-line command
+To run LoopSage from command-line, you only need to type a command
+
+```bash
+loopsage -c config.ini
+```
+
+With this command the model will run with parameters specified in `config.ini` file. An example of a `config.ini` file would be the following,
+
+```txt
+# Definition of Monte Carlo parameters
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
+``` 
+
 ### Output Files
 In the output files, simulation produces one folder with 4 subfolders. In subfolder `plots`, you can find plots that are the diagnostics of the algorithm. One of the most basic results you should see is the trajectories of cohesins (LEFs). this diagram should look like that,
 

{pyloopsage-0.0.2 → pyloopsage-0.0.6}/README.md

@@ -1,8 +1,14 @@
-# LoopSage
-An energy-based model for loop extrusion.
+# pyLoopSage
+Updated version of the stochastic loop extrusion model: LoopSage with capability to run incredibly fast, parallelized across CPU cores. This package is even more user-friendly and it can be installed via PyPI.
 
-**Important!!!** *Now the molecular dynamics can run for larger regions, since the code or `LoopSage_md.py` is fixed and does not allocate so much memory.*
+## New features
 
+- More user-friendly environment.
+- Installable with `pip install pyLoopSage`.
+- Parralelization of the stochastic simulation across multiple CPUs.
+- Capability of modelling the whole chromosome.
+- Visualization functions.
+- Capability to run form terminal with a simple command `loopsage -c config.ini`.
 
 ## Publication
 Please cite the method paper in case that you would like to use this model for your work,
@@ -11,33 +17,31 @@ Please cite the method paper in case that you would like to use this model for y
 
 ## The model
 
+We have a polymer chain with $$N_{\text{beads}}$$ number of monomers. In general we can scale by deault the granularity of the simulation so as to give reasonable results. Therefore if we have a `region` counted in genomic coordinates, we can assume that `N_beads=(region[1]-region[0])//2000`.
+
 Let's assume that each cohesin $i$ can be represented of two coordinates $(m_{i},n_{i})$ we allow three moves in our simulation:
 
-* Slide right ( $n_{i} -> n_{i+1}$ to the right).
-* Slide left ( $m_{i} -> m_{i-1}$ to the left).
+* Slide both locations randomly (as 1D random walk) or
 * Rebind somewhere else.
 
+In general a good working assumption is that the number of cohesins (or loop extrusion factors LEFs) is $$N_{\text{lef}}=2N_{\text{CTCF}}$$.
 
 The main idea of the algorithm is to ensemble loop extrusion from a Boltzmann probability distribution, with Hamiltonian,
 
-$$E = \dfrac{f}{N_{fold}}\sum_{i=1}^{N_{coh}}\log(n_i-m_i)+\dfrac{\kappa}{N_{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+\dfrac{b}{N_{bind}}\sum_{i=1}^{N_{coh}}\left(L(m_i)+R(n_i)\right)$$
+$$E = c_{\text{fold}}\sum_{i=1}^{N_{\text{coh}}}\log(n_i-m_i)+c_{\text{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+c_{\text{bind}}\sum_{i=1}^{N_{\text{coh}}}\left(L(m_i)+R(n_i)\right)$$
 
 The first term corresponds to the folding of chromatin, and the second term is a penalty for the appearance of crosss. Therefore, we have the function,
 $K(m_{i},n_{i};m_{j},n_{j})$ which takes the value 1 when $m_{i} < m_{j} < n_{i} < n_{j}$ or $m_{i}=m_{j}$ or $m_{i}=n_{j}$.
 
 These $L(\cdot), R(\cdot)$ functions are two functions that define the binding potential and they are orientation specific - so they are different for left and right position of cohesin (because CTCF motifs are orientation specific), therefore when we have a gap in these functions, it means presence of CTCF. These two functions are derived from data with CTCF binning and by running the script for probabilistic orientation. Moreover, by $N_{(\cdot)}$ we symbolize the normalization constants for each factor,
 
-$$N_{fold}=N_{coh}\cdot \langle n_i-m_i\rangle,\quad N_{cross}=N_{coh},\quad N_{bind}=\sum_{k}\left(L(k)+R(k)\right).$$
-
-An additional term which allows other protein factors that may act as barriers for the motion of LEFs can me optionally added,
-
-$$E_{bw}=\sum_{i=1}^{N_{\text{bw}}}\frac{r_{i}}{N_{bw,i}}\sum_{j=1}^{N_{lef}}\left(W_i(m_j)+W_i(n_j)\right),\qquad N_{bw,i} = \sum_{k}W_i(k)$$
+$$c_{\text{fold}}=-\dfrac{N_{\text{beads}}f}{N_{\text{lef}}\log(N_{\text{beads}}/N_{\text{lef}})},\quad c_{\text{bind}}=-\dfrac{N_{\text{beads}}b}{\sum_i \left(L(m_i)+R(n_i)\right)},\quad c_{\text{cross}}=\kappa \times 10^4.$$
 
-where $N_{bw}$ is the number of \texttt{.BigWig} ChIP-Seq experiments that are imported for each one of the proteins of interest. The energy term $W_{i}(\cdot)$ it corresponds to the average values of the ChIP-Seq experiment $i$ for each loci of interest. Finally, $r_{i}$ it is a weight that corresponds each one of these experiments and by default it is set as $r_{i}=b/2$.
+The parameters are defined in such a way that when $$f=b=\kappa=1$$, the three terms of the stochastic energy are balanced. 
 
-Thus,
+And the energy difference can be expressed as the energy difference of each term,
 
-$$\Delta E = \Delta E_{fold}+\Delta E_{cross}+\Delta E_{bind} + \Delta E_{bw}.$$
+$$\Delta E = \Delta E_{\text{fold}}+\Delta E_{\text{cross}}+\Delta E_{\text{bind}}.$$
 
 In this manner we accept a move in two cases:
 
@@ -46,35 +50,39 @@ In this manner we accept a move in two cases:
 
 And of course, the result - the distribution of loops in equilibrium -  depends on temperature of Boltzmann distribution $T$.
 
-## Packages to install
-Install a python 3.10 environment and OpenMM 8.0 and run 
-
-```
-pip install -r requirements.txt
-```
+## Installation
 
-For faster computations use CUDA toolkit: https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=20.04&target_type=deb_local.
+Can be easily installed with `pip install pyLoopSage`. To have CUDA acceleration, it is needed to have cuda-toolkit installed in case that you use nvidia drivers (otherwise you can use OpenCL or parallelization across CPU cores).
 
 ## How to use?
 
+### Python Implementation
+
 The main script is `LoopSage.py`. The implementation of the code is very easy and it can be described in the following lines,
 
 ```python
-N_steps, MC_step, burnin, T, T_min = int(1e4), int(2e2), 1000, 5,1
-region, chrom = [88271457,88851999], 'chr10'
-label=f'Petros_wt1h'
-bedpe_file = '/mnt/raid/data/Petros_project/loops/wt1h_pooled_2.bedpe'
-coh_track_file = '/mnt/raid/data/Petros_project/bw/RAD21_ChIPseq/mm_BMDM_WT_Rad21_heme_60min.bw'
-bw_file1 = '/mnt/raid/data/Petros_project/bw/BACH1_ChIPseq/mm_Bach1_1h_rep1_heme_merged.bw'
-bw_file2 = '/mnt/raid/data/Petros_project/bw/RNAPol_ChIPseq/WT-RNAPOLIIS2-1h-heme100-rep1_S5.bw'
-bw_files = [bw_file1,bw_file2]
-
-sim = LoopSage(region,chrom,bedpe_file,label=label,N_lef=50,N_beads=1000,bw_files=bw_files,track_file=coh_track_file)
-Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,poisson_choice=True,mode='Annealing',viz=True,save=True)
-sim.run_MD()
+# Definition of Monte Carlo parameters
+import Loopsage.stochastic_simulation as lps
+
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = lps.StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
 ```
 
-Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported. In `coh_track_file` you can optionally define the track file with some cohesin coverage of ChIP-Seq to determine the distribution of LEFs and allow preferencial binding in regions with higher signal. Then the user can optionally define a list of BigWig files which are needed in case that user would like to model other protein factors and their coefficients $r_i$.
+Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported.
 
 Note that the `.bedpe_file` must be in the following format,
 
@@ -95,6 +103,35 @@ where the last two columns represent the probabilites for left and right anchor
 
 Then, we define the main parameters of the simulation `N_beads,N_coh,kappa,f,b` or we can choose the default ones (take care because it might be the case that they are not the appropriate ones and they need to be changed), the parameters of Monte Carlo `N_steps, MC_step, burnin, T`, and we initialize the class `LoopSage()`. The command `sim.run_energy_minimization()` corresponds to the stochastic Monte Carlo simulation, and it produces a set of cohesin constraints as a result (`Ms, Ns`). Note that the stochastic simulation has two modes: `Annealing` and `Metropolis`. We feed cohesin constraints to the molecular simulation part of and we run `MD_LE()` or `MD_EM()` simulation which produces a trajectory of 3d-structures, and the average heatmap. `MD_LE()` function can produce an actual trajectory and a `.dcd` video of how simulation changes over time. However, the implementation needs a high amount of memory since we need to define a bond for each time step, and it may not work for large systems. `EM_LE()` is suggested for large simulations, because it does not require so big amount of memory.
 
+### Command-line command
+To run LoopSage from command-line, you only need to type a command
+
+```bash
+loopsage -c config.ini
+```
+
+With this command the model will run with parameters specified in `config.ini` file. An example of a `config.ini` file would be the following,
+
+```txt
+# Definition of Monte Carlo parameters
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
+``` 
+
 ### Output Files
 In the output files, simulation produces one folder with 4 subfolders. In subfolder `plots`, you can find plots that are the diagnostics of the algorithm. One of the most basic results you should see is the trajectories of cohesins (LEFs). this diagram should look like that,
 

{pyloopsage-0.0.2 → pyloopsage-0.0.6}/pyLoopSage.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyLoopSage
-Version: 0.0.2
+Version: 0.0.6
 Summary: An energy-based stochastic model of loop extrusion in chromatin.
 Home-page: https://github.com/SFGLab/pyLoopSage
 Author: Sebastian Korsak
@@ -31,11 +31,17 @@ Requires-Dist: statsmodels
 Requires-Dist: imageio
 Requires-Dist: pillow
 
-# LoopSage
-An energy-based model for loop extrusion.
+# pyLoopSage
+Updated version of the stochastic loop extrusion model: LoopSage with capability to run incredibly fast, parallelized across CPU cores. This package is even more user-friendly and it can be installed via PyPI.
 
-**Important!!!** *Now the molecular dynamics can run for larger regions, since the code or `LoopSage_md.py` is fixed and does not allocate so much memory.*
+## New features
 
+- More user-friendly environment.
+- Installable with `pip install pyLoopSage`.
+- Parralelization of the stochastic simulation across multiple CPUs.
+- Capability of modelling the whole chromosome.
+- Visualization functions.
+- Capability to run form terminal with a simple command `loopsage -c config.ini`.
 
 ## Publication
 Please cite the method paper in case that you would like to use this model for your work,
@@ -44,33 +50,31 @@ Please cite the method paper in case that you would like to use this model for y
 
 ## The model
 
+We have a polymer chain with $$N_{\text{beads}}$$ number of monomers. In general we can scale by deault the granularity of the simulation so as to give reasonable results. Therefore if we have a `region` counted in genomic coordinates, we can assume that `N_beads=(region[1]-region[0])//2000`.
+
 Let's assume that each cohesin $i$ can be represented of two coordinates $(m_{i},n_{i})$ we allow three moves in our simulation:
 
-* Slide right ( $n_{i} -> n_{i+1}$ to the right).
-* Slide left ( $m_{i} -> m_{i-1}$ to the left).
+* Slide both locations randomly (as 1D random walk) or
 * Rebind somewhere else.
 
+In general a good working assumption is that the number of cohesins (or loop extrusion factors LEFs) is $$N_{\text{lef}}=2N_{\text{CTCF}}$$.
 
 The main idea of the algorithm is to ensemble loop extrusion from a Boltzmann probability distribution, with Hamiltonian,
 
-$$E = \dfrac{f}{N_{fold}}\sum_{i=1}^{N_{coh}}\log(n_i-m_i)+\dfrac{\kappa}{N_{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+\dfrac{b}{N_{bind}}\sum_{i=1}^{N_{coh}}\left(L(m_i)+R(n_i)\right)$$
+$$E = c_{\text{fold}}\sum_{i=1}^{N_{\text{coh}}}\log(n_i-m_i)+c_{\text{cross}}\sum_{i,j}K(m_i,n_i;m_j,n_j)+c_{\text{bind}}\sum_{i=1}^{N_{\text{coh}}}\left(L(m_i)+R(n_i)\right)$$
 
 The first term corresponds to the folding of chromatin, and the second term is a penalty for the appearance of crosss. Therefore, we have the function,
 $K(m_{i},n_{i};m_{j},n_{j})$ which takes the value 1 when $m_{i} < m_{j} < n_{i} < n_{j}$ or $m_{i}=m_{j}$ or $m_{i}=n_{j}$.
 
 These $L(\cdot), R(\cdot)$ functions are two functions that define the binding potential and they are orientation specific - so they are different for left and right position of cohesin (because CTCF motifs are orientation specific), therefore when we have a gap in these functions, it means presence of CTCF. These two functions are derived from data with CTCF binning and by running the script for probabilistic orientation. Moreover, by $N_{(\cdot)}$ we symbolize the normalization constants for each factor,
 
-$$N_{fold}=N_{coh}\cdot \langle n_i-m_i\rangle,\quad N_{cross}=N_{coh},\quad N_{bind}=\sum_{k}\left(L(k)+R(k)\right).$$
-
-An additional term which allows other protein factors that may act as barriers for the motion of LEFs can me optionally added,
-
-$$E_{bw}=\sum_{i=1}^{N_{\text{bw}}}\frac{r_{i}}{N_{bw,i}}\sum_{j=1}^{N_{lef}}\left(W_i(m_j)+W_i(n_j)\right),\qquad N_{bw,i} = \sum_{k}W_i(k)$$
+$$c_{\text{fold}}=-\dfrac{N_{\text{beads}}f}{N_{\text{lef}}\log(N_{\text{beads}}/N_{\text{lef}})},\quad c_{\text{bind}}=-\dfrac{N_{\text{beads}}b}{\sum_i \left(L(m_i)+R(n_i)\right)},\quad c_{\text{cross}}=\kappa \times 10^4.$$
 
-where $N_{bw}$ is the number of \texttt{.BigWig} ChIP-Seq experiments that are imported for each one of the proteins of interest. The energy term $W_{i}(\cdot)$ it corresponds to the average values of the ChIP-Seq experiment $i$ for each loci of interest. Finally, $r_{i}$ it is a weight that corresponds each one of these experiments and by default it is set as $r_{i}=b/2$.
+The parameters are defined in such a way that when $$f=b=\kappa=1$$, the three terms of the stochastic energy are balanced. 
 
-Thus,
+And the energy difference can be expressed as the energy difference of each term,
 
-$$\Delta E = \Delta E_{fold}+\Delta E_{cross}+\Delta E_{bind} + \Delta E_{bw}.$$
+$$\Delta E = \Delta E_{\text{fold}}+\Delta E_{\text{cross}}+\Delta E_{\text{bind}}.$$
 
 In this manner we accept a move in two cases:
 
@@ -79,35 +83,39 @@ In this manner we accept a move in two cases:
 
 And of course, the result - the distribution of loops in equilibrium -  depends on temperature of Boltzmann distribution $T$.
 
-## Packages to install
-Install a python 3.10 environment and OpenMM 8.0 and run 
-
-```
-pip install -r requirements.txt
-```
+## Installation
 
-For faster computations use CUDA toolkit: https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=20.04&target_type=deb_local.
+Can be easily installed with `pip install pyLoopSage`. To have CUDA acceleration, it is needed to have cuda-toolkit installed in case that you use nvidia drivers (otherwise you can use OpenCL or parallelization across CPU cores).
 
 ## How to use?
 
+### Python Implementation
+
 The main script is `LoopSage.py`. The implementation of the code is very easy and it can be described in the following lines,
 
 ```python
-N_steps, MC_step, burnin, T, T_min = int(1e4), int(2e2), 1000, 5,1
-region, chrom = [88271457,88851999], 'chr10'
-label=f'Petros_wt1h'
-bedpe_file = '/mnt/raid/data/Petros_project/loops/wt1h_pooled_2.bedpe'
-coh_track_file = '/mnt/raid/data/Petros_project/bw/RAD21_ChIPseq/mm_BMDM_WT_Rad21_heme_60min.bw'
-bw_file1 = '/mnt/raid/data/Petros_project/bw/BACH1_ChIPseq/mm_Bach1_1h_rep1_heme_merged.bw'
-bw_file2 = '/mnt/raid/data/Petros_project/bw/RNAPol_ChIPseq/WT-RNAPOLIIS2-1h-heme100-rep1_S5.bw'
-bw_files = [bw_file1,bw_file2]
-
-sim = LoopSage(region,chrom,bedpe_file,label=label,N_lef=50,N_beads=1000,bw_files=bw_files,track_file=coh_track_file)
-Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,poisson_choice=True,mode='Annealing',viz=True,save=True)
-sim.run_MD()
+# Definition of Monte Carlo parameters
+import Loopsage.stochastic_simulation as lps
+
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = lps.StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
 ```
 
-Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported. In `coh_track_file` you can optionally define the track file with some cohesin coverage of ChIP-Seq to determine the distribution of LEFs and allow preferencial binding in regions with higher signal. Then the user can optionally define a list of BigWig files which are needed in case that user would like to model other protein factors and their coefficients $r_i$.
+Firstly, we need to define the input files from which LoopSage would take the information to construct the potential. We define also the specific region that we would like to model. Therefore, in the code script above we define a `bedpe_file` from which information about the CTCF loops it is imported.
 
 Note that the `.bedpe_file` must be in the following format,
 
@@ -128,6 +136,35 @@ where the last two columns represent the probabilites for left and right anchor
 
 Then, we define the main parameters of the simulation `N_beads,N_coh,kappa,f,b` or we can choose the default ones (take care because it might be the case that they are not the appropriate ones and they need to be changed), the parameters of Monte Carlo `N_steps, MC_step, burnin, T`, and we initialize the class `LoopSage()`. The command `sim.run_energy_minimization()` corresponds to the stochastic Monte Carlo simulation, and it produces a set of cohesin constraints as a result (`Ms, Ns`). Note that the stochastic simulation has two modes: `Annealing` and `Metropolis`. We feed cohesin constraints to the molecular simulation part of and we run `MD_LE()` or `MD_EM()` simulation which produces a trajectory of 3d-structures, and the average heatmap. `MD_LE()` function can produce an actual trajectory and a `.dcd` video of how simulation changes over time. However, the implementation needs a high amount of memory since we need to define a bond for each time step, and it may not work for large systems. `EM_LE()` is suggested for large simulations, because it does not require so big amount of memory.
 
+### Command-line command
+To run LoopSage from command-line, you only need to type a command
+
+```bash
+loopsage -c config.ini
+```
+
+With this command the model will run with parameters specified in `config.ini` file. An example of a `config.ini` file would be the following,
+
+```txt
+# Definition of Monte Carlo parameters
+N_steps, MC_step, burnin, T, T_min = int(4e4), int(5e2), 1000, 2.5, 1.0
+mode = 'Metropolis'
+
+# Simulation Strengths
+f, b, kappa = 1.0, 1.0, 1.0
+
+# Definition of region
+region, chrom = [15550000,16850000], 'chr6'
+
+# Definition of data
+output_name='../HiChIP_Annealing_T1_MD_region'
+bedpe_file = '/home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe'
+
+sim = StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=1000)
+Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=True,save=True)
+sim.run_MD('CUDA')
+``` 
+
 ### Output Files
 In the output files, simulation produces one folder with 4 subfolders. In subfolder `plots`, you can find plots that are the diagnostics of the algorithm. One of the most basic results you should see is the trajectories of cohesins (LEFs). this diagram should look like that,
 

{pyloopsage-0.0.2 → pyloopsage-0.0.6}/setup.py

@@ -6,7 +6,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
 
 setup(
     name='pyLoopSage',  # Package name
-    version='0.0.2',  # Version of the software
+    version='0.0.6',  # Version of the software
     description='An energy-based stochastic model of loop extrusion in chromatin.',
     long_description=long_description,
     long_description_content_type='text/markdown',
@@ -46,4 +46,4 @@ setup(
         'Operating System :: POSIX :: Linux',  # General OS classifier
     ],
     python_requires='>=3.10',  # Specify Python version compatibility
-)
+)