PyPI - pyLoopSage - Versions diffs - 1.0.16__tar.gz → 1.0.18__tar.gz - Mend

pyLoopSage 1.0.16tar.gz → 1.0.18tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

{pyloopsage-1.0.16/pyLoopSage.egg-info → pyloopsage-1.0.18}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyLoopSage
-Version: 1.0.16
+Version: 1.0.18
 Summary: An energy-based stochastic model of loop extrusion in chromatin.
 Home-page: https://github.com/SFGLab/pyLoopSage
 Author: Sebastian Korsak
@@ -31,6 +31,16 @@ Requires-Dist: statsmodels
 Requires-Dist: imageio
 Requires-Dist: imageio[ffmpeg]
 Requires-Dist: pillow
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 # 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.
@@ -44,11 +54,6 @@ Updated version of the stochastic loop extrusion model: LoopSage with capability
 - 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,
-* Korsak, Sevastianos, and Dariusz Plewczynski. "LoopSage: An energy-based Monte Carlo approach for the loop extrusion modelling of chromatin." Methods (2024).
 ## The model
 ### Stochastic Simulation
@@ -74,7 +79,7 @@ These $L(\cdot), R(\cdot)$ functions are two functions that define the binding p
 $$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.$$
-The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced.
+The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced. To clarrify, this parametrization is slightly different than this of the original paper. We multiply with $N_{\text{beads}}$, so as to keep the input parameters $f,b,\kappa$ simpler close to 1. Therefore, a value $f=0.1$ leads to unfolded structures, and a value $f=2$ it leads to very fast propagating long loops.
 And the energy difference can be expressed as the energy difference of each term,
@@ -113,7 +118,7 @@ For the implementation of this model in python, we used OpenMM and CUDA accelera
 In general the user can run simulation in two different ways:
 1. **Energy minimization (EM)**: It means that for each sample of cohesin positions $C_{t_i}=(m_j(t_i),n_j(t_i))$ start from a different initial structure (usually 3D random walk) and we apply the forcefield. For each structure we start from a different initial condition. In general, it is suggested to run the model in this way because it is faster, less prone to errors and the structures are not correlated to each other.
-2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. Novertheness, it is not suggested because it is more prone to errors and can lead to autocorrelated structures. We suggest our users to set the power of excluded volume $\alpha=1$ for the purposes of MD simulation. However, this depends on the research interests of the user.
+2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. It is also biophysically more correct, in the sense that loop extrusion should be time-dependent, and the structure at time $t_i$ has to me correlated with structures at time $t_{i\pm1}$. It is a little bit more prone to error, and you may need to change the simulation frequence and step in case of instability (smaller frequency and more steps to stabilize it).
 ## Installation
@@ -262,3 +267,55 @@ In the output folder there are another three subfolders:
 An example, illustrated with Chimera software, simulated trajectory of structures after running Simulated Annealing and molecular dynamics.
 ![siman_traj_GitHub](https://github.com/SFGLab/LoopSage/assets/49608786/c6626641-f709-46e0-b01b-42566b1829ef)
+### Long-table of LoopSage arguments
+| Argument Name          | Description                                                                                                     | Type        | Default Value       |
+|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
+| PLATFORM              | Name of the platform. Available choices: CPU, CUDA, OpenCL                                                      | str        | CPU               |
+| DEVICE                | Device index for CUDA or OpenCL (count from 0)                                                                  | str        | None                  |
+| N_BEADS               | Number of Simulation Beads.                                                                                     | int        | None                  |
+| BEDPE_PATH            | A .bedpe file path with loops. It is required.                                                                  | str        | None                  |
+| OUT_PATH              | Output folder name.                                                                                             | str        | ../results       |
+| REGION_START          | Starting region coordinate.                                                                                     | int        | None                  |
+| REGION_END            | Ending region coordinate.                                                                                       | int        | None                  |
+| CHROM                 | Chromosome that corresponds to the modeling region of interest.                                                 | str        | None                  |
+| LEF_RW                | True if cohesins slide as a random walk instead of one direction.                                               | bool       | True                |
+| LEF_DRIFT             | True if LEFs are pushed back when they encounter other LEFs.                                                   | bool       | False               |
+| N_STEPS               | Number of Monte Carlo steps.                                                                                    | int        | 40000               |
+| N_LEF                 | Number of loop extrusion factors.                                                                               | int        | None                  |
+| N_LEF2                | Number of second family loop extrusion factors.                                                                | int        | 0                   |
+| MC_STEP               | Monte Carlo frequency to avoid autocorrelated ensembles.                                                       | int        | 200                 |
+| BURNIN               | Burn-in period (steps before equilibrium).                                                                      | int        | 1000                |
+| T_INIT                | Initial Temperature of the Stochastic Model.                                                                   | float      | 2.0                 |
+| T_FINAL               | Final Temperature of the Stochastic Model.                                                                     | float      | 1.0                 |
+| METHOD                | Stochastic modeling method (Metropolis or Simulated Annealing).                                                | str        | 'Annealing'         |
+| FOLDING_COEFF         | Folding coefficient.                                                                                           | float      | 1.0                 |
+| FOLDING_COEFF2        | Folding coefficient for the second family of LEFs.                                                            | float      | 0.0                 |
+| CROSS_COEFF          | LEF crossing coefficient.                                                                                      | float      | 1.0                 |
+| CROSS_LOOP           | True if the penalty is applied when mi<mj<ni<nj. False if it applies only when mj=ni. When false it is better to enable LEF_DRIFT as well. | bool |True                |
+| BIND_COEFF           | CTCF binding coefficient.                                                                                      | float      | 1.0                 |
+| SAVE_PLOTS           | True to save diagnostic plots.                                                                                 | bool       | True                |
+| SAVE_MDT             | True to save metadata of the stochastic simulation.                                                            | bool       | True                |
+| INITIAL_STRUCTURE_TYPE | Choose from: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.                                | str        | rw                |
+| SIMULATION_TYPE       | Either EM (energy minimizations) or MD (molecular dynamics).                                                  | str        | None                  |
+| INTEGRATOR_STEP       | Step of the integrator.                                                                                        | Quantity   | 100 femtosecond   |
+| FORCEFIELD_PATH       | Path to XML file with forcefield.                                                                             | str        | default_xml_path    |
+| ANGLE_FF_STRENGTH     | Angle force strength.                                                                                          | float      | 200.0               |
+| LE_FF_LENGTH         | Equilibrium distance of loop forces.                                                                          | float      | 0.1                 |
+| LE_FF_STRENGTH       | Interaction Strength of loop forces.                                                                          | float      | 50000.0             |
+| EV_P                 | Probability that excluded volume is disabled. Enable it only in case of topoisomerase activity simulation.    | float      | 0.0                 |
+| EV_FF_STRENGTH       | Excluded-volume strength.                                                                                     | float      | 100.0               |
+| EV_FF_POWER          | Excluded-volume power.                                                                                        | float      | 3.0                 |
+| FRICTION             | Friction coefficient of the Langevin integrator.                                                              | float      | 0.1                 |
+| TOLERANCE            | Stopping condition for energy minimization.                                                                   | float      | 0.001               |
+| VIZ_HEATS            | True to visualize the output average heatmap.                                                                | bool       | True                |
+| SIM_TEMP             | Temperature of the 3D simulation (EM or MD).                                                                  | Quantity   | 310 kelvin        |
+| SIM_STEP             | Amount of simulation steps for loop force adjustments.                                                        | int        | 1000                |
+## Citation
+Please cite the method and biological paper in case that you would like to use this model for your work,
+* Korsak, Sevastianos, and Dariusz Plewczynski. "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. (2024). Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes. In bioRxiv (p. 2024.05.16.594268). https://doi.org/10.1101/2024.05.16.594268

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/README.md RENAMED Viewed

@@ -10,11 +10,6 @@ Updated version of the stochastic loop extrusion model: LoopSage with capability
 - 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,
-* Korsak, Sevastianos, and Dariusz Plewczynski. "LoopSage: An energy-based Monte Carlo approach for the loop extrusion modelling of chromatin." Methods (2024).
 ## The model
 ### Stochastic Simulation
@@ -40,7 +35,7 @@ These $L(\cdot), R(\cdot)$ functions are two functions that define the binding p
 $$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.$$
-The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced.
+The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced. To clarrify, this parametrization is slightly different than this of the original paper. We multiply with $N_{\text{beads}}$, so as to keep the input parameters $f,b,\kappa$ simpler close to 1. Therefore, a value $f=0.1$ leads to unfolded structures, and a value $f=2$ it leads to very fast propagating long loops.
 And the energy difference can be expressed as the energy difference of each term,
@@ -79,7 +74,7 @@ For the implementation of this model in python, we used OpenMM and CUDA accelera
 In general the user can run simulation in two different ways:
 1. **Energy minimization (EM)**: It means that for each sample of cohesin positions $C_{t_i}=(m_j(t_i),n_j(t_i))$ start from a different initial structure (usually 3D random walk) and we apply the forcefield. For each structure we start from a different initial condition. In general, it is suggested to run the model in this way because it is faster, less prone to errors and the structures are not correlated to each other.
-2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. Novertheness, it is not suggested because it is more prone to errors and can lead to autocorrelated structures. We suggest our users to set the power of excluded volume $\alpha=1$ for the purposes of MD simulation. However, this depends on the research interests of the user.
+2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. It is also biophysically more correct, in the sense that loop extrusion should be time-dependent, and the structure at time $t_i$ has to me correlated with structures at time $t_{i\pm1}$. It is a little bit more prone to error, and you may need to change the simulation frequence and step in case of instability (smaller frequency and more steps to stabilize it).
 ## Installation
@@ -228,3 +223,55 @@ In the output folder there are another three subfolders:
 An example, illustrated with Chimera software, simulated trajectory of structures after running Simulated Annealing and molecular dynamics.
 ![siman_traj_GitHub](https://github.com/SFGLab/LoopSage/assets/49608786/c6626641-f709-46e0-b01b-42566b1829ef)
+### Long-table of LoopSage arguments
+| Argument Name          | Description                                                                                                     | Type        | Default Value       |
+|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
+| PLATFORM              | Name of the platform. Available choices: CPU, CUDA, OpenCL                                                      | str        | CPU               |
+| DEVICE                | Device index for CUDA or OpenCL (count from 0)                                                                  | str        | None                  |
+| N_BEADS               | Number of Simulation Beads.                                                                                     | int        | None                  |
+| BEDPE_PATH            | A .bedpe file path with loops. It is required.                                                                  | str        | None                  |
+| OUT_PATH              | Output folder name.                                                                                             | str        | ../results       |
+| REGION_START          | Starting region coordinate.                                                                                     | int        | None                  |
+| REGION_END            | Ending region coordinate.                                                                                       | int        | None                  |
+| CHROM                 | Chromosome that corresponds to the modeling region of interest.                                                 | str        | None                  |
+| LEF_RW                | True if cohesins slide as a random walk instead of one direction.                                               | bool       | True                |
+| LEF_DRIFT             | True if LEFs are pushed back when they encounter other LEFs.                                                   | bool       | False               |
+| N_STEPS               | Number of Monte Carlo steps.                                                                                    | int        | 40000               |
+| N_LEF                 | Number of loop extrusion factors.                                                                               | int        | None                  |
+| N_LEF2                | Number of second family loop extrusion factors.                                                                | int        | 0                   |
+| MC_STEP               | Monte Carlo frequency to avoid autocorrelated ensembles.                                                       | int        | 200                 |
+| BURNIN               | Burn-in period (steps before equilibrium).                                                                      | int        | 1000                |
+| T_INIT                | Initial Temperature of the Stochastic Model.                                                                   | float      | 2.0                 |
+| T_FINAL               | Final Temperature of the Stochastic Model.                                                                     | float      | 1.0                 |
+| METHOD                | Stochastic modeling method (Metropolis or Simulated Annealing).                                                | str        | 'Annealing'         |
+| FOLDING_COEFF         | Folding coefficient.                                                                                           | float      | 1.0                 |
+| FOLDING_COEFF2        | Folding coefficient for the second family of LEFs.                                                            | float      | 0.0                 |
+| CROSS_COEFF          | LEF crossing coefficient.                                                                                      | float      | 1.0                 |
+| CROSS_LOOP           | True if the penalty is applied when mi<mj<ni<nj. False if it applies only when mj=ni. When false it is better to enable LEF_DRIFT as well. | bool |True                |
+| BIND_COEFF           | CTCF binding coefficient.                                                                                      | float      | 1.0                 |
+| SAVE_PLOTS           | True to save diagnostic plots.                                                                                 | bool       | True                |
+| SAVE_MDT             | True to save metadata of the stochastic simulation.                                                            | bool       | True                |
+| INITIAL_STRUCTURE_TYPE | Choose from: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.                                | str        | rw                |
+| SIMULATION_TYPE       | Either EM (energy minimizations) or MD (molecular dynamics).                                                  | str        | None                  |
+| INTEGRATOR_STEP       | Step of the integrator.                                                                                        | Quantity   | 100 femtosecond   |
+| FORCEFIELD_PATH       | Path to XML file with forcefield.                                                                             | str        | default_xml_path    |
+| ANGLE_FF_STRENGTH     | Angle force strength.                                                                                          | float      | 200.0               |
+| LE_FF_LENGTH         | Equilibrium distance of loop forces.                                                                          | float      | 0.1                 |
+| LE_FF_STRENGTH       | Interaction Strength of loop forces.                                                                          | float      | 50000.0             |
+| EV_P                 | Probability that excluded volume is disabled. Enable it only in case of topoisomerase activity simulation.    | float      | 0.0                 |
+| EV_FF_STRENGTH       | Excluded-volume strength.                                                                                     | float      | 100.0               |
+| EV_FF_POWER          | Excluded-volume power.                                                                                        | float      | 3.0                 |
+| FRICTION             | Friction coefficient of the Langevin integrator.                                                              | float      | 0.1                 |
+| TOLERANCE            | Stopping condition for energy minimization.                                                                   | float      | 0.001               |
+| VIZ_HEATS            | True to visualize the output average heatmap.                                                                | bool       | True                |
+| SIM_TEMP             | Temperature of the 3D simulation (EM or MD).                                                                  | Quantity   | 310 kelvin        |
+| SIM_STEP             | Amount of simulation steps for loop force adjustments.                                                        | int        | 1000                |
+## Citation
+Please cite the method and biological paper in case that you would like to use this model for your work,
+* Korsak, Sevastianos, and Dariusz Plewczynski. "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. (2024). Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes. In bioRxiv (p. 2024.05.16.594268). https://doi.org/10.1101/2024.05.16.594268

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/loopsage/__init__.py RENAMED Viewed

@@ -1,4 +1,4 @@
 # Importing specific functions or classes from submodules
 from .run import main
-__version__ = "1.0.16"
+__version__ = "1.0.18"

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/loopsage/args_definition.py RENAMED Viewed

@@ -145,6 +145,7 @@ args = ListOfArgs([
     # Stochastic Simulation parameters
     Arg('LEF_RW', help="True in case that you would like to make cohesins slide as random walk, instead of sliding only in one direction.", type=bool, default='True', val='True'),
+    Arg('LEF_DRIFT', help="True in case that LEFs are pushed back when they encounter other LEFs.", type=bool, default='False', val='False'),
     Arg('N_STEPS', help="Number of Monte Carlo steps.", type=int, default='40000', val='40000'),
     Arg('N_LEF', help="Number of loop extrusion factors (condensins and cohesins). If you leave it empty it would add for LEFs twice the number of CTCFs.", type=int, default='', val=''),
     Arg('N_LEF2', help="Number of second family loop extrusion factors, in case that you would like to simulate a second group with different speed.", type=int, default='0', val='0'),
@@ -156,6 +157,7 @@ args = ListOfArgs([
     Arg('FOLDING_COEFF', help="Folding coefficient.", type=float, default='1.0', val='1.0'),
     Arg('FOLDING_COEFF2', help="Folding coefficient for the second family of LEFs.", type=float, default='0.0', val='0.0'),
     Arg('CROSS_COEFF', help="LEF crossing coefficient.", type=float, default='1.0', val='1.0'),
+    Arg('CROSS_LOOP', help="It true if the penalty is applied for situations mi<mj<ni<nj and mi=nj, and false if it is applied only for mi=nj.", type=bool, default='True', val='True'),
     Arg('BIND_COEFF', help="CTCF binding coefficient.", type=float, default='1.0', val='1.0'),
     Arg('SAVE_PLOTS', help="It should be true in case that you would like to save diagnostic plots. In case that you use small MC_STEP or large N_STEPS is better to mark it as False.", type=bool, default='True', val='True'),
     Arg('SAVE_MDT', help="In case that you would liketo save metadata of the stochastic simulation.", type=bool, default='True', val='True'),
@@ -168,7 +170,8 @@ args = ListOfArgs([
     Arg('ANGLE_FF_STRENGTH', help="Angle force strength.", type=float, default='200.0', val='200.0'),
     Arg('LE_FF_LENGTH', help="Equillibrium distance of loop forces.", type=float, default='0.1', val='0.1'),
     Arg('LE_FF_STRENGTH', help="Interaction Strength of loop forces.", type=float, default='50000.0', val='50000.0'),
-    Arg('EV_FF_STRENGTH', help="Excluded-volume strength.", type=float, default='10.0', val='10.0'),
+    Arg('EV_P', help="Probability that randomly excluded volume may be disabled.", type=float, default='0.0', val='0.0'),
+    Arg('EV_FF_STRENGTH', help="Excluded-volume strength.", type=float, default='100.0', val='100.0'),
     Arg('EV_FF_POWER', help="Excluded-volume power.", type=float, default='3.0', val='3.0'),
     Arg('FRICTION',help='Friction coefficient of the Langevin integrator.',type=float, default='0.1', val='0.1'),
     Arg('TOLERANCE', help="Tolerance that works as stopping condition for energy minimization.", type=float, default='0.001', val='0.001'),

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/loopsage/md.py RENAMED Viewed

@@ -12,20 +12,11 @@ from sys import stdout
 from mdtraj.reporters import HDF5Reporter
 from scipy import ndimage
 from openmm.app import PDBFile, PDBxFile, ForceField, Simulation, PDBReporter, PDBxReporter, DCDReporter, StateDataReporter, CharmmPsfFile
-import importlib.resources
 from .utils import *
 from .initial_structures import *
-# Dynamically set the default path to the XML file in the package
-try:
-    with importlib.resources.path('loopsage.forcefields', 'classic_sm_ff.xml') as default_xml_path:
-        default_xml_path = str(default_xml_path)
-except FileNotFoundError:
-    # If running in a development setup without the resource installed, fallback to a relative path
-    default_xml_path = 'loopsage/forcefields/classic_sm_ff.xml'
 class MD_LE:
-    def __init__(self,M,N,N_beads,burnin,MC_step,path=None,platform='CPU',angle_ff_strength=200,le_distance=0.1,le_ff_strength=50000.0,ev_ff_strength=10.0,ev_ff_power=3.0,tolerance=0.001):
+    def __init__(self,M,N,N_beads,path=None,platform='CPU',angle_ff_strength=200,le_distance=0.1,le_ff_strength=50000.0,ev_ff_strength=100.0,ev_ff_power=3.0,tolerance=0.001):
         '''
         M, N (np arrays): Position matrix of two legs of cohesin m,n.
                           Rows represent  loops/cohesins and columns represent time
@@ -35,8 +26,8 @@ class MD_LE:
         '''
         self.M, self.N = M, N
         self.N_coh, self.N_steps = M.shape
-        self.N_beads, self.step, self.burnin = N_beads, MC_step, burnin//MC_step
-        self.path = path
+        self.N_beads = N_beads
+        self.path = path if path!=None else make_folder('../output')
         self.platform = platform
         self.angle_ff_strength = angle_ff_strength
         self.le_distance = le_distance
@@ -45,15 +36,12 @@ class MD_LE:
         self.ev_ff_power = ev_ff_power
         self.tolerance = tolerance
-    def run_pipeline(self,run_MD=True, friction=0.1, integrator_step=100 * mm.unit.femtosecond, sim_step=1000, ff_path=default_xml_path, temperature=310, plots=False):
+    def run_pipeline(self,run_MD=True, friction=0.1, integrator_step=10 * mm.unit.femtosecond, sim_step=100, ff_path = 'forcefields/classic_sm_ff.xml',temperature=310, p_ev=0, plots=False):
         '''
         This is the basic function that runs the molecular simulation pipeline.
         '''
         # Parameters
-        self.angle_ff_strength=200
-        self.le_distance=0.1
-        self.le_ff_strength=300000.0
-        self.tolerance=0.001
+        self.p_ev = p_ev
         # Define initial structure
         print('Building initial structure...')
@@ -91,15 +79,17 @@ class MD_LE:
             start = time.time()
             heats = list()
             for i in range(1,self.N_steps):
+                # Define probabilities that EV would be disabled
+                if p_ev>0: self.ps_ev = np.random.rand(self.N_beads)
+                # Change forcefield
                 self.change_loop(i)
+                self.change_ev()
                 self.simulation.step(sim_step)
-                if i>=self.burnin:
-                    self.state = self.simulation.context.getState(getPositions=True)
-                    PDBxFile.writeFile(pdb.topology, self.state.getPositions(), open(self.path+f'/ensemble/MDLE_{i-self.burnin+1}.cif', 'w'))
-                    heats.append(get_heatmap(self.state.getPositions(),save=False))
+                self.state = self.simulation.context.getState(getPositions=True)
+                PDBxFile.writeFile(pdb.topology, self.state.getPositions(), open(self.path+f'/ensemble/MDLE_{i}.cif', 'w'))
+                heats.append(get_heatmap(self.state.getPositions(),save=False))
             end = time.time()
             elapsed = end - start
             print(f'Everything is done! Simulation finished succesfully!\nMD finished in {elapsed/60:.2f} minutes.\n')
             self.avg_heat = np.average(heats,axis=0)
@@ -111,6 +101,12 @@ class MD_LE:
                 self.plot_heat(self.avg_heat,f'/plots/avg_heatmap.svg')
                 self.plot_heat(self.std_heat,f'/plots/std_heatmap.svg')
         return self.avg_heat
+    def change_ev(self):
+        ev_strength = (self.ps_ev>self.p_ev).astype(int)*np.sqrt(self.ev_ff_strength) if self.p_ev>0 else np.sqrt(self.ev_ff_strength)*np.ones(self.N_beads)
+        for n in range(self.N_beads):
+            self.ev_force.setParticleParameters(n,[ev_strength[n],0.05])
+        self.ev_force.updateParametersInContext(self.simulation.context)
     def change_loop(self,i):
         force_idx = self.system.getNumForces()-1
@@ -121,12 +117,12 @@ class MD_LE:
     def add_evforce(self):
         'Leonard-Jones potential for excluded volume'
-        self.ev_force = mm.CustomNonbondedForce(f'epsilon*((sigma1+sigma2)/(r+r_small))^{self.ev_ff_power}')
-        self.ev_force.addGlobalParameter('epsilon', defaultValue=self.ev_ff_strength)
-        self.ev_force.addGlobalParameter('r_small', defaultValue=0.01)
+        self.ev_force = mm.CustomNonbondedForce(f'(epsilon1*epsilon2*(sigma1*sigma2)/(r+r_small))^{self.ev_ff_power}')
+        self.ev_force.addGlobalParameter('r_small', defaultValue=0.1)
         self.ev_force.addPerParticleParameter('sigma')
+        self.ev_force.addPerParticleParameter('epsilon')
         for i in range(self.N_beads):
-            self.ev_force.addParticle([0.05])
+            self.ev_force.addParticle([np.sqrt(self.ev_ff_strength),0.05])
         self.system.addForce(self.ev_force)
     def add_bonds(self):
@@ -173,7 +169,7 @@ class MD_LE:
 def main():
     # A potential example
-    M = np.load('/home/skorsak/Dropbox/LoopSage/files/region_[48100000,48700000]_chr3/Annealing_Nbeads500_ncoh50/Ms.npy')
-    N = np.load('/home/skorsak/Dropbox/LoopSage/files/region_[48100000,48700000]_chr3/Annealing_Nbeads500_ncoh50/Ns.npy')
-    md = MD_LE(4*M,4*N,2000,5,1)
-    md.run_pipeline()
+    M = np.load('/home/skorsak/Projects/mine/RepliSage/output/other/Ms.npy')
+    N = np.load('/home/skorsak/Projects/mine/RepliSage/output/other/Ns.npy')
+    md = MD_LE(M,N,np.max(N)+1,platform='CUDA')
+    md.run_pipeline()

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/loopsage/run.py RENAMED Viewed

@@ -70,11 +70,11 @@ def main():
     # Run Simulation
     sim = StochasticSimulation(region,chrom,bedpe_file,out_dir=output_name,N_beads=N_beads,N_lef=N_lef,N_lef2=N_lef2)
-    Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=args.SAVE_PLOTS,save=args.SAVE_MDT,lef_rw=args.LEF_RW,f=f,f2=f2,b=b,kappa=kappa)
+    Es, Ms, Ns, Bs, Ks, Fs, ufs = sim.run_energy_minimization(N_steps,MC_step,burnin,T,T_min,mode=mode,viz=args.SAVE_PLOTS,save=args.SAVE_MDT,lef_rw=args.LEF_RW,f=f,f2=f2,b=b,kappa=kappa,lef_drift=args.LEF_DRIFT,cross_loop=args.CROSS_LOOP)
     if args.SIMULATION_TYPE=='EM':
         sim.run_EM(args.PLATFORM,args.ANGLE_FF_STRENGTH,args.LE_FF_LENGTH,args.LE_FF_STRENGTH,args.EV_FF_STRENGTH,args.EV_FF_POWER,args.TOLERANCE,args.FRICTION,args.INTEGRATOR_STEP,args.SIM_TEMP,args.VIZ_HEATS,args.FORCEFIELD_PATH)
     elif args.SIMULATION_TYPE=='MD':
-        sim.run_MD(args.PLATFORM,args.ANGLE_FF_STRENGTH,args.LE_FF_LENGTH,args.LE_FF_STRENGTH,args.EV_FF_STRENGTH,args.EV_FF_POWER,args.TOLERANCE,args.FRICTION,args.INTEGRATOR_STEP,args.SIM_TEMP,args.SIM_STEP,args.VIZ_HEATS,args.FORCEFIELD_PATH)
+        sim.run_MD(args.PLATFORM,args.ANGLE_FF_STRENGTH,args.LE_FF_LENGTH,args.LE_FF_STRENGTH,args.EV_FF_STRENGTH,args.EV_FF_POWER,args.TOLERANCE,args.FRICTION,args.INTEGRATOR_STEP,args.SIM_TEMP,args.SIM_STEP,args.VIZ_HEATS,args.FORCEFIELD_PATH,args.EV_P)
     elif args.SIMULATION_TYPE==None:
         print('\n3D simulation did not run because it was not specified. Please specify argument SIMULATION_TYPE as EM or MD.')
     else:

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/loopsage/stochastic_simulation.py RENAMED Viewed

@@ -5,6 +5,7 @@ import random as rd
 import scipy.stats as stats
 from numba import njit, prange
 from tqdm import tqdm
+import importlib.resources
 # scipy
 from scipy.stats import norm
@@ -16,14 +17,23 @@ from .plots import *
 from .md import *
 from .em import *
+# Dynamically set the default path to the XML file in the package
+try:
+    with importlib.resources.path('loopsage.forcefields', 'classic_sm_ff.xml') as default_xml_path:
+        default_xml_path = str(default_xml_path)
+except FileNotFoundError:
+    # If running in a development setup without the resource installed, fallback to a relative path
+    default_xml_path = 'loopsage/forcefields/classic_sm_ff.xml'
 @njit
-def Kappa(mi,ni,mj,nj):
+def Kappa(mi,ni,mj,nj,cross_loop=True):
     '''
     Computes the crossing function of LoopSage.
     '''
     k=0.0
-    if mi<mj and mj<ni and ni<nj: k+=1 # np.abs(ni-mj)+1
-    if mj<mi and mi<nj and nj<ni: k+=1 # np.abs(nj-mi)+1
+    if cross_loop:
+        if mi<mj and mj<ni and ni<nj: k+=1 # np.abs(ni-mj)+1
+        if mj<mi and mi<nj and nj<ni: k+=1 # np.abs(nj-mi)+1
     if mj==ni or mi==nj or ni==nj or mi==mj: k+=1
     return k
@@ -37,14 +47,14 @@ def E_bind(L, R, ms, ns, bind_norm):
     return E_b
 @njit
-def E_cross(ms, ns, k_norm):
+def E_cross(ms, ns, k_norm, cross_loop):
     '''
     The crossing energy.
     '''
     crossing = 0.0
     for i in prange(len(ms)):
         for j in range(i + 1, len(ms)):
-            crossing += Kappa(ms[i], ns[i], ms[j], ns[j])
+            crossing += Kappa(ms[i], ns[i], ms[j], ns[j], cross_loop)
     return k_norm * crossing
 @njit
@@ -56,12 +66,12 @@ def E_fold(ms, ns, fold_norm):
     return fold_norm * folding
 @njit
-def get_E(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, N_lef, N_lef2):
+def get_E(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, N_lef, N_lef2, cross_loop):
     ''''
     The total energy.
     '''
-    energy = E_bind(L, R, ms, ns, bind_norm) + E_cross(ms, ns, k_norm) + E_fold(ms, ns, fold_norm)
-    if fold_norm2!=0: energy += E_fold(ms[N_lef:N_lef+N_lef2],ns[N_lef:N_lef+N_lef2],fold_norm2)
+    energy = E_bind(L, R, ms, ns, bind_norm) + E_cross(ms, ns, k_norm, cross_loop) + E_fold(ms, ns, fold_norm)
+    if fold_norm2!=0: energy += E_fold(ms[N_lef:N_lef+N_lef2],ns[N_lef:N_lef+N_lef2], fold_norm2)
     return energy
 @njit
@@ -79,19 +89,19 @@ def get_dE_fold(fold_norm,ms,ns,m_new,n_new,idx):
     return fold_norm*(np.log(n_new-m_new)-np.log(ns[idx]-ms[idx]))
 @njit
-def get_dE_cross(ms, ns, m_new, n_new, idx, k_norm):
+def get_dE_cross(ms, ns, m_new, n_new, idx, k_norm, cross_loop):
     '''
     Energy difference for crossing energy.
     '''
     K1, K2 = 0, 0
     for i in prange(len(ms)):
         if i != idx:
-            K1 += Kappa(ms[idx], ns[idx], ms[i], ns[i])
-            K2 += Kappa(m_new, n_new, ms[i], ns[i])
+            K1 += Kappa(ms[idx], ns[idx], ms[i], ns[i], cross_loop)
+            K2 += Kappa(m_new, n_new, ms[i], ns[i], cross_loop)
     return k_norm * (K2 - K1)
 @njit
-def get_dE(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, m_new, n_new, idx, N_lef, N_lef2):
+def get_dE(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, m_new, n_new, idx, N_lef, N_lef2, cross_loop):
     '''
     Total energy difference.
     '''
@@ -99,9 +109,9 @@ def get_dE(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, m_new, n_new,
     if idx<N_lef:
         dE += get_dE_fold(fold_norm,ms[:N_lef],ns[:N_lef],m_new,n_new,idx)
     else:
-        dE += get_dE_fold(fold_norm2,ms[N_lef:N_lef+N_lef2],ns[N_lef:N_lef2],m_new,n_new,idx-N_lef)
+        dE += get_dE_fold(fold_norm2,ms[N_lef:N_lef+N_lef2],ns[N_lef:N_lef+N_lef2],m_new,n_new,idx-N_lef)
     dE += get_dE_bind(L, R, bind_norm, ms, ns, m_new, n_new, idx)
-    dE += get_dE_cross(ms, ns, m_new, n_new, idx, k_norm)
+    dE += get_dE_cross(ms, ns, m_new, n_new, idx, k_norm, cross_loop)
     return dE
 @njit
@@ -114,7 +124,7 @@ def unbind_bind(N_beads):
     return int(m_new), int(n_new)
 @njit
-def slide(m_old, n_old, N_beads, rw=True):
+def slide(m_old, n_old, ms, ns, N_beads, rw=True, drift=True):
     '''
     Sliding Monte-Carlo step.
     '''
@@ -122,7 +132,11 @@ def slide(m_old, n_old, N_beads, rw=True):
     r1 = np.random.choice(choices) if rw else -1
     r2 = np.random.choice(choices) if rw else 1
     m_new = m_old + r1 if m_old + r1>=0 else 0
+    if np.any(ns==m_new) and drift and m_old-r1<n_old-1:
+        m_new =  m_old - r1 if m_old + r1>=0 else 0
     n_new = n_old + r2 if n_old + r2<N_beads else N_beads-1
+    if np.any(ms==n_new) and drift and n_old-r2>m_old+1:
+        n_new =  n_old - r2 if n_old + r2>=0 else 0
     return int(m_new), int(n_new)
 @njit
@@ -148,14 +162,14 @@ def initialize(N_beads,N_lef):
     return ms, ns
 @njit
-def run_simulation(N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,bind_norm,k_norm,N_lef,N_lef2,L,R,mode,lef_rw=True):
+def run_simulation(N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,bind_norm,k_norm,N_lef,N_lef2,L,R,mode,lef_rw=True,lef_drift=True,cross_loop=True):
     '''
     Runs the Monte Carlo simulation.
     '''
     Ti = T
     bi = burnin//MC_step
     ms, ns = initialize(N_beads,N_lef+N_lef2)
-    E = get_E(L, R, bind_norm, fold_norm, fold_norm2, k_norm,  ms, ns, N_lef, N_lef2)
+    E = get_E(L, R, bind_norm, fold_norm, fold_norm2, k_norm,  ms, ns, N_lef, N_lef2, cross_loop)
     Es,Ks,Fs,Bs,ufs = np.zeros(N_steps//MC_step, dtype=np.float64),np.zeros(N_steps//MC_step, dtype=np.float64),np.zeros(N_steps//MC_step, dtype=np.float64),np.zeros(N_steps//MC_step, dtype=np.float64),np.zeros(N_steps//MC_step, dtype=np.float64)
     Ms, Ns = np.zeros((N_lef+N_lef2,N_steps//MC_step), dtype=np.int64), np.zeros((N_lef+N_lef2,N_steps//MC_step), dtype=np.int64)
@@ -167,10 +181,10 @@ def run_simulation(N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,b
             if r==0:
                 m_new, n_new = unbind_bind(N_beads)
             else:
-                m_new, n_new = slide(ms[j],ns[j],N_beads,lef_rw)
+                m_new, n_new = slide(ms[j],ns[j],ms,ns,N_beads,lef_rw,lef_drift)
             # Compute energy difference
-            dE = get_dE(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, m_new, n_new, j, N_lef, N_lef2)
+            dE = get_dE(L, R, bind_norm, fold_norm, fold_norm2, k_norm, ms, ns, m_new, n_new, j, N_lef, N_lef2, cross_loop)
             if dE <= 0 or np.exp(-dE/Ti) > np.random.rand():
                 ms[j], ns[j] = m_new, n_new
@@ -183,7 +197,7 @@ def run_simulation(N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,b
         if i%MC_step==0:
             ufs[i//MC_step] = unfolding_metric(ms,ns,N_beads)
             Es[i//MC_step] = E
-            Ks[i//MC_step] = E_cross(ms,ns,k_norm)
+            Ks[i//MC_step] = E_cross(ms,ns,k_norm,cross_loop)
             Fs[i//MC_step] = E_fold(ms,ns,fold_norm)
             Bs[i//MC_step] = E_bind(L,R,ms,ns,bind_norm)
     return Ms, Ns, Es, Ks, Fs, Bs, ufs
@@ -213,7 +227,7 @@ class StochasticSimulation:
         print('Number of LEFs:',self.N_lef+self.N_lef2)
         self.path = make_folder(out_dir)
-    def run_energy_minimization(self,N_steps,MC_step,burnin,T=1,T_min=0,mode='Metropolis',viz=False,save=False, f=1.0, f2=0.0, b=1.0, kappa=1.0, lef_rw=True):
+    def run_energy_minimization(self,N_steps,MC_step,burnin,T=1,T_min=0,mode='Metropolis',viz=False,save=False, f=1.0, f2=0.0, b=1.0, kappa=1.0, lef_rw=True, lef_drift=True, cross_loop=True):
         '''
         Implementation of the stochastic Monte Carlo simulation.
@@ -233,7 +247,7 @@ class StochasticSimulation:
         print('\nRunning simulation (with parallelization across CPU cores)...')
         start = time.time()
         self.burnin = burnin
-        self.Ms, self.Ns, self.Es, self.Ks, self.Fs, self.Bs, self.ufs = run_simulation(self.N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,bind_norm,k_norm,self.N_lef,self.N_lef2,self.L,self.R,mode,lef_rw)
+        self.Ms, self.Ns, self.Es, self.Ks, self.Fs, self.Bs, self.ufs = run_simulation(self.N_beads,N_steps,MC_step,burnin,T,T_min,fold_norm,fold_norm2,bind_norm,k_norm,self.N_lef,self.N_lef2,self.L,self.R,mode,lef_rw,lef_drift,cross_loop)
         end = time.time()
         elapsed = end - start
         print(f'Computation finished succesfully in {elapsed//3600:.0f} hours, {elapsed%3600//60:.0f} minutes and  {elapsed%60:.0f} seconds.')
@@ -242,13 +256,13 @@ class StochasticSimulation:
         if save:
             f = open(self.path+'/other/info.txt', "w")
             f.write(f'Number of beads {self.N_beads}.\n')
-            f.write(f'Number of cohesins {self.N_lef}. Number of CTCFs {self.N_CTCF}.\n')
+            f.write(f'Number of cohesins {self.N_lef}. Number of cohesins in second family {self.N_lef2}. Number of CTCFs {self.N_CTCF}. \n')
             f.write(f'Bedpe file for CTCF binding is {self.bedpe_file}.\n')
             f.write(f'Initial temperature {T}. Minimum temperature {T_min}.\n')
             f.write(f'Monte Carlo optimization method: {mode}.\n')
             f.write(f'Monte Carlo steps {N_steps}. Sampling frequency {MC_step}. Burnin period {burnin}.\n')
             f.write(f'Crossing energy in equilibrium is {np.average(self.Ks[burnin//MC_step:]):.2f}. Crossing coefficient kappa={kappa}.\n')
-            f.write(f'Folding energy in equilibrium is {np.average(self.Fs[burnin//MC_step:]):.2f}. Folding coefficient f={f}.\n')
+            f.write(f'Folding energy in equilibrium is {np.average(self.Fs[burnin//MC_step:]):.2f}. Folding coefficient f={f}. Folding coefficient for the second family f2={f2}\n')
             f.write(f'Binding energy in equilibrium is {np.average(self.Bs[burnin//MC_step:]):.2f}. Binding coefficient b={b}.\n')
             f.write(f'Energy at equillibrium: {np.average(self.Es[burnin//MC_step:]):.2f}.\n')
             f.close()
@@ -274,14 +288,14 @@ class StochasticSimulation:
         self.N_CTCF = np.max([np.count_nonzero(self.L),np.count_nonzero(self.R)])
         print('Number of CTCF:',self.N_CTCF)
-    def run_EM(self,platform='CPU',angle_ff_strength=200,le_distance=0.0,le_ff_strength=300000.0,ev_ff_strength=10.0,ev_ff_power=3.0,tolerance=0.001,friction=0.1,integrator_step=100*mm.unit.femtosecond,temperature=310,save_plots=True,ff_path='forcefields/classic_sm_ff.xml'):
+    def run_EM(self,platform='CPU',angle_ff_strength=200,le_distance=0.0,le_ff_strength=300000.0,ev_ff_strength=10.0,ev_ff_power=3.0,tolerance=0.001,friction=0.1,integrator_step=100*mm.unit.femtosecond,temperature=310,save_plots=True,ff_path=default_xml_path):
         em = EM_LE(self.Ms,self.Ns,self.N_beads,self.burnin,self.MC_step,self.path,platform,angle_ff_strength,le_distance,le_ff_strength,ev_ff_strength,ev_ff_power,tolerance)
         sim_heat = em.run_pipeline(plots=save_plots,friction=friction,integrator_step=integrator_step,temperature=temperature,ff_path=ff_path)
         corr_exp_heat(sim_heat,self.bedpe_file,self.region,self.chrom,self.N_beads,self.path)
-    def run_MD(self,platform='CPU',angle_ff_strength=200,le_distance=0.0,le_ff_strength=300000.0,ev_ff_strength=10.0,ev_ff_power=3.0,tolerance=0.001,friction=0.1,integrator_step=100*mm.unit.femtosecond,temperature=310,sim_step=1000,save_plots=True,ff_path='forcefields/classic_sm_ff.xml'):
-        md = MD_LE(self.Ms,self.Ns,self.N_beads,self.burnin,self.MC_step,self.path,platform,angle_ff_strength,le_distance,le_ff_strength,ev_ff_strength,ev_ff_power,tolerance)
-        sim_heat = md.run_pipeline(plots=save_plots,sim_step=sim_step,friction=friction,integrator_step=integrator_step,temperature=temperature,ff_path=ff_path)
+    def run_MD(self,platform='CPU',angle_ff_strength=200,le_distance=0.0,le_ff_strength=300000.0,ev_ff_strength=10.0,ev_ff_power=3.0,tolerance=0.001,friction=0.1,integrator_step=100*mm.unit.femtosecond,temperature=310,sim_step=1000,save_plots=True,ff_path=default_xml_path,p_ev=0):
+        md = MD_LE(self.Ms,self.Ns,self.N_beads,self.path,platform,angle_ff_strength,le_distance,le_ff_strength,ev_ff_strength,ev_ff_power,tolerance)
+        sim_heat = md.run_pipeline(plots=save_plots,sim_step=sim_step,friction=friction,integrator_step=integrator_step,temperature=temperature,ff_path=ff_path,p_ev=p_ev)
         corr_exp_heat(sim_heat,self.bedpe_file,self.region,self.chrom,self.N_beads,self.path)
 def main():

{pyloopsage-1.0.16 → pyloopsage-1.0.18/pyLoopSage.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyLoopSage
-Version: 1.0.16
+Version: 1.0.18
 Summary: An energy-based stochastic model of loop extrusion in chromatin.
 Home-page: https://github.com/SFGLab/pyLoopSage
 Author: Sebastian Korsak
@@ -31,6 +31,16 @@ Requires-Dist: statsmodels
 Requires-Dist: imageio
 Requires-Dist: imageio[ffmpeg]
 Requires-Dist: pillow
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 # 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.
@@ -44,11 +54,6 @@ Updated version of the stochastic loop extrusion model: LoopSage with capability
 - 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,
-* Korsak, Sevastianos, and Dariusz Plewczynski. "LoopSage: An energy-based Monte Carlo approach for the loop extrusion modelling of chromatin." Methods (2024).
 ## The model
 ### Stochastic Simulation
@@ -74,7 +79,7 @@ These $L(\cdot), R(\cdot)$ functions are two functions that define the binding p
 $$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.$$
-The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced.
+The parameters are defined in such a way that when $f=b=\kappa=1$, the three terms of the stochastic energy are balanced. To clarrify, this parametrization is slightly different than this of the original paper. We multiply with $N_{\text{beads}}$, so as to keep the input parameters $f,b,\kappa$ simpler close to 1. Therefore, a value $f=0.1$ leads to unfolded structures, and a value $f=2$ it leads to very fast propagating long loops.
 And the energy difference can be expressed as the energy difference of each term,
@@ -113,7 +118,7 @@ For the implementation of this model in python, we used OpenMM and CUDA accelera
 In general the user can run simulation in two different ways:
 1. **Energy minimization (EM)**: It means that for each sample of cohesin positions $C_{t_i}=(m_j(t_i),n_j(t_i))$ start from a different initial structure (usually 3D random walk) and we apply the forcefield. For each structure we start from a different initial condition. In general, it is suggested to run the model in this way because it is faster, less prone to errors and the structures are not correlated to each other.
-2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. Novertheness, it is not suggested because it is more prone to errors and can lead to autocorrelated structures. We suggest our users to set the power of excluded volume $\alpha=1$ for the purposes of MD simulation. However, this depends on the research interests of the user.
+2. **Molecular Dynamics (MD)**: In this case we have only one initial structure, we minimize the energy according to the forcefield only once and then we run a molecular dynamics simulation over time. This creates a continuous trajectory of structures, and it is cool for visualization pruposes. It is also biophysically more correct, in the sense that loop extrusion should be time-dependent, and the structure at time $t_i$ has to me correlated with structures at time $t_{i\pm1}$. It is a little bit more prone to error, and you may need to change the simulation frequence and step in case of instability (smaller frequency and more steps to stabilize it).
 ## Installation
@@ -262,3 +267,55 @@ In the output folder there are another three subfolders:
 An example, illustrated with Chimera software, simulated trajectory of structures after running Simulated Annealing and molecular dynamics.
 ![siman_traj_GitHub](https://github.com/SFGLab/LoopSage/assets/49608786/c6626641-f709-46e0-b01b-42566b1829ef)
+### Long-table of LoopSage arguments
+| Argument Name          | Description                                                                                                     | Type        | Default Value       |
+|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
+| PLATFORM              | Name of the platform. Available choices: CPU, CUDA, OpenCL                                                      | str        | CPU               |
+| DEVICE                | Device index for CUDA or OpenCL (count from 0)                                                                  | str        | None                  |
+| N_BEADS               | Number of Simulation Beads.                                                                                     | int        | None                  |
+| BEDPE_PATH            | A .bedpe file path with loops. It is required.                                                                  | str        | None                  |
+| OUT_PATH              | Output folder name.                                                                                             | str        | ../results       |
+| REGION_START          | Starting region coordinate.                                                                                     | int        | None                  |
+| REGION_END            | Ending region coordinate.                                                                                       | int        | None                  |
+| CHROM                 | Chromosome that corresponds to the modeling region of interest.                                                 | str        | None                  |
+| LEF_RW                | True if cohesins slide as a random walk instead of one direction.                                               | bool       | True                |
+| LEF_DRIFT             | True if LEFs are pushed back when they encounter other LEFs.                                                   | bool       | False               |
+| N_STEPS               | Number of Monte Carlo steps.                                                                                    | int        | 40000               |
+| N_LEF                 | Number of loop extrusion factors.                                                                               | int        | None                  |
+| N_LEF2                | Number of second family loop extrusion factors.                                                                | int        | 0                   |
+| MC_STEP               | Monte Carlo frequency to avoid autocorrelated ensembles.                                                       | int        | 200                 |
+| BURNIN               | Burn-in period (steps before equilibrium).                                                                      | int        | 1000                |
+| T_INIT                | Initial Temperature of the Stochastic Model.                                                                   | float      | 2.0                 |
+| T_FINAL               | Final Temperature of the Stochastic Model.                                                                     | float      | 1.0                 |
+| METHOD                | Stochastic modeling method (Metropolis or Simulated Annealing).                                                | str        | 'Annealing'         |
+| FOLDING_COEFF         | Folding coefficient.                                                                                           | float      | 1.0                 |
+| FOLDING_COEFF2        | Folding coefficient for the second family of LEFs.                                                            | float      | 0.0                 |
+| CROSS_COEFF          | LEF crossing coefficient.                                                                                      | float      | 1.0                 |
+| CROSS_LOOP           | True if the penalty is applied when mi<mj<ni<nj. False if it applies only when mj=ni. When false it is better to enable LEF_DRIFT as well. | bool |True                |
+| BIND_COEFF           | CTCF binding coefficient.                                                                                      | float      | 1.0                 |
+| SAVE_PLOTS           | True to save diagnostic plots.                                                                                 | bool       | True                |
+| SAVE_MDT             | True to save metadata of the stochastic simulation.                                                            | bool       | True                |
+| INITIAL_STRUCTURE_TYPE | Choose from: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.                                | str        | rw                |
+| SIMULATION_TYPE       | Either EM (energy minimizations) or MD (molecular dynamics).                                                  | str        | None                  |
+| INTEGRATOR_STEP       | Step of the integrator.                                                                                        | Quantity   | 100 femtosecond   |
+| FORCEFIELD_PATH       | Path to XML file with forcefield.                                                                             | str        | default_xml_path    |
+| ANGLE_FF_STRENGTH     | Angle force strength.                                                                                          | float      | 200.0               |
+| LE_FF_LENGTH         | Equilibrium distance of loop forces.                                                                          | float      | 0.1                 |
+| LE_FF_STRENGTH       | Interaction Strength of loop forces.                                                                          | float      | 50000.0             |
+| EV_P                 | Probability that excluded volume is disabled. Enable it only in case of topoisomerase activity simulation.    | float      | 0.0                 |
+| EV_FF_STRENGTH       | Excluded-volume strength.                                                                                     | float      | 100.0               |
+| EV_FF_POWER          | Excluded-volume power.                                                                                        | float      | 3.0                 |
+| FRICTION             | Friction coefficient of the Langevin integrator.                                                              | float      | 0.1                 |
+| TOLERANCE            | Stopping condition for energy minimization.                                                                   | float      | 0.001               |
+| VIZ_HEATS            | True to visualize the output average heatmap.                                                                | bool       | True                |
+| SIM_TEMP             | Temperature of the 3D simulation (EM or MD).                                                                  | Quantity   | 310 kelvin        |
+| SIM_STEP             | Amount of simulation steps for loop force adjustments.                                                        | int        | 1000                |
+## Citation
+Please cite the method and biological paper in case that you would like to use this model for your work,
+* Korsak, Sevastianos, and Dariusz Plewczynski. "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. (2024). Improved cohesin HiChIP protocol and bioinformatic analysis for robust detection of chromatin loops and stripes. In bioRxiv (p. 2024.05.16.594268). https://doi.org/10.1101/2024.05.16.594268

{pyloopsage-1.0.16 → pyloopsage-1.0.18}/setup.py RENAMED Viewed

@@ -6,7 +6,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
 setup(
     name='pyLoopSage',  # Package name
-    version='1.0.16',  # Version of the software
+    version='1.0.18',  # 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',