pyLoopSage 1.1.5__tar.gz → 1.1.7__tar.gz

{pyloopsage-1.1.5/pyLoopSage.egg-info → pyloopsage-1.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyLoopSage
-Version: 1.1.5
+Version: 1.1.7
 Summary: An energy-based stochastic model of loop extrusion in chromatin.
 Home-page: https://github.com/SFGLab/pyLoopSage
 Author: Sebastian Korsak
@@ -48,6 +48,8 @@ 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.
 
+![screenshot](https://github.com/user-attachments/assets/7c338772-9fd5-4b57-8965-65d346b7f11c)
+
 ## New features
 
 - More user-friendly environment.
@@ -80,7 +82,7 @@ $K(m_{i},n_{i};m_{j},n_{j})$ which takes the value 1 when $m_{i} < m_{j} < n_{i}
 
 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,
 
-$$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.$$
+$$c_{\text{fold}}=-\dfrac{N_{\text{beads}}f}{N_{\text{lef}}\log(N_{\text{beads}}/N_{\text{lef}})},\quad c_{\text{bind}}=-\dfrac{2N_{\text{beads}}b}{N_{CTCF}},\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. 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. 
 
@@ -168,6 +170,7 @@ You do **not** need to manually stop or clean up anything—the container is tem
 
 ```bash
 docker rmi pyloopsage-cuda
+docker system prune -a
 ```
 
 **Note:** Install `nvidia-container-toolkit` in your system if you want to use the container with CUDA: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
@@ -193,16 +196,21 @@ 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'
+interaction_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)
+sim = lps.StochasticSimulation(region,chrom,interaction_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_EM('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.
+Behind the scenes, the class still walks through the same steps as before: it sets the main simulation parameters (`N_beads, N_coh, kappa, f, b`, or sensible defaults if you'd rather not specify them, though it's worth double-checking they suit your system), along with the Monte Carlo parameters (`N_steps, MC_step, burnin, T`), before initializing `LoopSage()`. Calling `sim.run_energy_minimization()` then launches the stochastic Monte Carlo simulation, which yields a set of cohesin constraints (`Ms, Ns`) — generated in one of two modes, `Annealing` or `Metropolis`. These constraints are passed on to the molecular simulation stage, where either `EM_LE()` or `MD_LE()` turns them into a trajectory of 3D structures and an average contact heatmap. `MD_LE()` goes a step further and produces an actual trajectory together with a `.dcd` video of the simulation evolving over time, though it's memory-hungry — a bond has to be defined at every timestep, which can make it impractical for larger systems. For those cases, `EM_LE()` is the better choice, since it achieves the same goal without the heavy memory footprint.
+
+#### Input data
+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 an `interaction_file` from which information about the CTCF loops or CTCF binding sites is imported. The format is auto-detected from the file extension, and three alternatives are supported: `.bedpe`, `.bed`, and `.narrowPeak`.
+
+1. `.bedpe` (paired loop anchors)
 
-Note that the `.bedpe_file` must be in the following format,
+This is the richest format, since each line already describes a candidate loop between two anchors. The `.bedpe` file must be in the following format:
 
 ```
 chr1	903917	906857	chr1	937535	939471	16	3.2197903072213415e-05	0.9431392038374097
@@ -217,31 +225,45 @@ chr1	990949	994698	chr1	1001076	1003483	34	0.5386388489931403	0.9942742844900859
 chr1	991375	993240	chr1	1062647	1064919	15	1.0	0.9997541297643132
 ```
 
-where the last two columns represent the probabilites for left and right anchor respectively to be tandem right. If the probability is negative it means that no CTCF motif was detected in this anchor. You can extract these probabilities from the repo: https://github.com/SFGLab/3d-analysis-toolkit, with `find_motifs.py` file. Please set `probabilistic=True` `statistics=False`.
+where the last two columns represent the probabilities for the left and right anchor respectively to be tandem right. If the probability is negative it means that no CTCF motif was detected in this anchor.
 
+*Alternativelly, it is possible to import a `.bedpe` file without the last two columns (CTCF orientation). In this case, CTCF would act as an orientation independent barrier. This might affect slightly the results, but it is an easier option, if you do not want to run a CTCF motif finding script.*
 
-To use this script you need to have a python 3.8 environment, and install the following dependencies from this file: [mateusz_script_env.txt](https://github.com/user-attachments/files/17568248/mateusz_script_env.txt).
+2. `.bed` (single CTCF sites, e.g. ChIP-seq intervals)
 
-You also need to download the reference genome from: ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/GRCh38_reference_genome/GRCh38_full_analysis_set_plus_decoy_hla.fa
+If you only have unpaired CTCF binding intervals rather than loop calls, you can pass a `.bed` file instead. LoopSage will still build orientation-aware `L`/`R` binding vectors from it, but since there is no anchor-pairing information in a `.bed` file, no loop-adjacency matrix (`J`) can be constructed - CTCF sites contribute individually rather than as loop anchors. Expected columns: `chrom, start, end, name, score, strand`, optionally followed by a probability column (probability the site's best motif hit is reverse-oriented) and an orientation call (`>`, `<`, or `.`).
+
+3. `.narrowPeak` (single CTCF peaks, e.g. MACS2/HiChIP peaks)
+
+Similarly, a `.narrowPeak` file of individual peaks can be used in place of a `.bedpe`/`.bed` file, with the same caveat: no `J` loop matrix is built, only `L`/`R`. Expected columns: `chrom, start, end, name, score`, optionally followed by a forward-orientation probability column and an orientation call.
+
+#### Extracting CTCF motif orientation
+
+To generate the orientation/probability columns for any of the three formats above (`.bedpe`, `.bed`, or `.narrowPeak`), use the motif-finding scripts from [BlackPianoCat/motif_finder](https://github.com/BlackPianoCat/motif_finder):
+
+- `motif_finder_bedpe.py` for `.bedpe` loop files
+- `bed_motif_finder.py` for `.bed` interval files
+- `motif_finder_peaks.py` for `.narrowPeak` peak files
 
-*Alternativelly, it is possible to import a .bedpe file without the last two columns (CTCF orientation). In this case, CTCF would act as an orientation independent barrier. This might affect slightly the results, but it is an easier option, if you do not want to run a CTCF motif finding script.*
+Run the appropriate script with `--prob` to get the probability columns shown above (e.g. `python motif_finder_bedpe.py -i loops.bedpe -g genome.fa -m CTCF.pfm -o loops_with_motif.bedpe --prob`). See that repo's README for full usage details on each script.
 
-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 `EM_LE()` or `EM_LE()` 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.
+You also need to download the reference genome from: ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/GRCh38_reference_genome/GRCh38_full_analysis_set_plus_decoy_hla.fa
 
 ### Running LoopSage from command-line
-To run LoopSage from command-line, you only need to type a command
+
+Running LoopSage from the command line comes down to a single 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,
+This command runs the model using the parameters specified in a `config.ini` file. Here's an example of what that file might look like:
 
 ```txt
 [Main]
 
 ; Input Data and Information
-BEDPE_PATH = /home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe
+INTERACTION_FILE = /home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe
 REGION_START = 15550000
 REGION_END = 16850000
 CHROM = chr6
@@ -261,7 +283,7 @@ PLATFORM = CUDA
 INITIAL_STRUCTURE_TYPE = rw
 SIMULATION_TYPE = EM 
 TOLERANCE = 1.0
-``` 
+```
 
 ### Visualization with PyVista
 
@@ -319,39 +341,47 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 ### Long-table of LoopSage arguments
 
 #### General Settings
-| 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                  |
-| OUT_PATH              | Output folder name.                                                                                             | str        | ../results       |
-| SAVE_MDT             | True to save metadata of the stochastic simulation.                                                            | bool       | True                |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| PLATFORM | Simulation platform: CPU, CUDA, or OpenCL | str | CPU |
+| DEVICE | CUDA/OpenCL device index (from 0) | str | None |
+| OUT_PATH | Output folder path | str | ../results |
+| SAVE_MDT | Save simulation metadata | bool | True |
 
 #### Input Data
-| Argument Name          | Description                                                                                                     | Type        | Default Value       |
-|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| BEDPE_PATH            | A .bedpe file path with loops. It is required.                                                                  | str        | None                  |
-| LEF_TRACK_FILE        | Path to a bw file of cohesin or condensin density. If it is provided, then simulation LEFs preferentially bind in enriched regions. | str | None |
-| BW_FILES              | List of paths to .bw files containing additional data for simulation. Enriched regions would act as barriers for cohesin.                | list       | None                  |
-| 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                  |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| INTERACTION_FILE | Loop/peak file (.bedpe, .bed, or .narrowPeak). Required. | str | None |
+| LEF_TRACK_FILE | bigWig track biasing LEF loading toward enriched regions | str | None |
+| BW_FILES | bigWig file(s) acting as extrusion barriers | list | None |
+| SMOOTHING_INPUT | Smooth noisy/sparse loop-peak signal before use | bool | False |
+| COMP_BW_FILE | bigWig track for A/B compartment bias | str | None |
+| COMP_BED_FILE | BED file for A/B compartment bias (alt. to COMP_BW_FILE) | str | None |
+| DATA_LOSS_MODE | 0 = 1D binding potentials (L/R); 1 = 2D loss interpolated from input loops | int | 0 |
+| CONTRASTIVE_BINDING | If True, penalizes loop-free regions so extrusion is confined within TADs; if False, extrusion is uniform everywhere | bool | False |
+| REGION_START | Region start coordinate | int | None |
+| REGION_END | Region end coordinate | int | None |
+| CHROM | Chromosome of the modeled region | str | None |
+| GENOME | Reference genome for chromosome sizes (e.g. hg38) | str | hg38 |
+| FLOAT_LIST | Extra custom numeric settings | list | None |
+| STRING_LIST | Extra custom text settings | list | None |
 
 #### Stochastic Simulation Parameters
-| Argument Name          | Description                                                                                                     | Type        | Default Value       |
-|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| N_BEADS               | Number of Simulation Beads.                                                                                     | int        | None                  |
-| N_STEPS               | Number of Monte Carlo steps.                                                                                    | int        | 40000               |
-| 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'         |
-| 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_LEF                 | Number of loop extrusion factors.                                                                               | int        | None                  |
-| N_LEF2                | Number of second family loop extrusion factors.                                                                | int        | 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                |
-| BETWEEN_FAMILIES_PENALTY | Penalty applied when loops from different LEF families cross.                                                | bool     | True                 |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| N_BEADS | Number of simulation beads | int | None |
+| N_STEPS | Monte Carlo steps | int | 40000 |
+| MC_STEP | Sampling frequency (reduces autocorrelation) | int | 200 |
+| BURNIN | Steps discarded before equilibrium | int | 1000 |
+| T_INIT | Initial temperature | float | 2.0 |
+| T_FINAL | Final temperature | float | 1.0 |
+| METHOD | 'Metropolis' or 'Annealing' | str | 'Annealing' |
+| LEF_RW | Cohesins slide as random walk (vs. one direction) | bool | True |
+| LEF_DRIFT | LEFs bounce back off each other | bool | False |
+| N_LEF | Number of loop extrusion factors | int | None |
+| N_LEF2 | Number of second-family LEFs | int | 0 |
+| CROSS_LOOP | Penalize mi<mj<ni<nj crossings (vs. only mj=ni); pair with LEF_DRIFT if False | bool | True |
+| BETWEEN_FAMILIES_PENALTY | Penalize crossings between LEF families | bool | True |
 
 #### Energy Coefficients
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |
@@ -365,7 +395,6 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 #### Molecular Dynamics Simulation
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |
 |------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| SIMULATION_TYPE       | Either EM (energy minimizations) or MD (molecular dynamics).                                                  | str        | None                  |
 | INITIAL_STRUCTURE_TYPE | Choose from: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.                                | str        | rw                |
 | INTEGRATOR_STEP       | Step of the integrator.                                                                                        | Quantity   | 100 femtosecond   |
 | FORCEFIELD_PATH       | Path to XML file with forcefield.                                                                             | str        | default_xml_path    |
@@ -379,7 +408,7 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 | FRICTION             | Friction coefficient of the Langevin integrator.                                                              | float      | 0.1              |
 | TOLERANCE            | Stopping condition for energy minimization.     | float      | 0.001              |
 | 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                |
+| SIM_STEP             | Amount of simulation steps for loop force adjustments.                                                        | int        | 2000                |
 
 #### Visualization
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |

{pyloopsage-1.1.5 → pyloopsage-1.1.7}/README.md

@@ -1,6 +1,8 @@
 # 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.
 
+![screenshot](https://github.com/user-attachments/assets/7c338772-9fd5-4b57-8965-65d346b7f11c)
+
 ## New features
 
 - More user-friendly environment.
@@ -33,7 +35,7 @@ $K(m_{i},n_{i};m_{j},n_{j})$ which takes the value 1 when $m_{i} < m_{j} < n_{i}
 
 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,
 
-$$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.$$
+$$c_{\text{fold}}=-\dfrac{N_{\text{beads}}f}{N_{\text{lef}}\log(N_{\text{beads}}/N_{\text{lef}})},\quad c_{\text{bind}}=-\dfrac{2N_{\text{beads}}b}{N_{CTCF}},\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. 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. 
 
@@ -121,6 +123,7 @@ You do **not** need to manually stop or clean up anything—the container is tem
 
 ```bash
 docker rmi pyloopsage-cuda
+docker system prune -a
 ```
 
 **Note:** Install `nvidia-container-toolkit` in your system if you want to use the container with CUDA: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
@@ -146,16 +149,21 @@ 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'
+interaction_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)
+sim = lps.StochasticSimulation(region,chrom,interaction_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_EM('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.
+Behind the scenes, the class still walks through the same steps as before: it sets the main simulation parameters (`N_beads, N_coh, kappa, f, b`, or sensible defaults if you'd rather not specify them, though it's worth double-checking they suit your system), along with the Monte Carlo parameters (`N_steps, MC_step, burnin, T`), before initializing `LoopSage()`. Calling `sim.run_energy_minimization()` then launches the stochastic Monte Carlo simulation, which yields a set of cohesin constraints (`Ms, Ns`) — generated in one of two modes, `Annealing` or `Metropolis`. These constraints are passed on to the molecular simulation stage, where either `EM_LE()` or `MD_LE()` turns them into a trajectory of 3D structures and an average contact heatmap. `MD_LE()` goes a step further and produces an actual trajectory together with a `.dcd` video of the simulation evolving over time, though it's memory-hungry — a bond has to be defined at every timestep, which can make it impractical for larger systems. For those cases, `EM_LE()` is the better choice, since it achieves the same goal without the heavy memory footprint.
+
+#### Input data
+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 an `interaction_file` from which information about the CTCF loops or CTCF binding sites is imported. The format is auto-detected from the file extension, and three alternatives are supported: `.bedpe`, `.bed`, and `.narrowPeak`.
+
+1. `.bedpe` (paired loop anchors)
 
-Note that the `.bedpe_file` must be in the following format,
+This is the richest format, since each line already describes a candidate loop between two anchors. The `.bedpe` file must be in the following format:
 
 ```
 chr1	903917	906857	chr1	937535	939471	16	3.2197903072213415e-05	0.9431392038374097
@@ -170,31 +178,45 @@ chr1	990949	994698	chr1	1001076	1003483	34	0.5386388489931403	0.9942742844900859
 chr1	991375	993240	chr1	1062647	1064919	15	1.0	0.9997541297643132
 ```
 
-where the last two columns represent the probabilites for left and right anchor respectively to be tandem right. If the probability is negative it means that no CTCF motif was detected in this anchor. You can extract these probabilities from the repo: https://github.com/SFGLab/3d-analysis-toolkit, with `find_motifs.py` file. Please set `probabilistic=True` `statistics=False`.
+where the last two columns represent the probabilities for the left and right anchor respectively to be tandem right. If the probability is negative it means that no CTCF motif was detected in this anchor.
 
+*Alternativelly, it is possible to import a `.bedpe` file without the last two columns (CTCF orientation). In this case, CTCF would act as an orientation independent barrier. This might affect slightly the results, but it is an easier option, if you do not want to run a CTCF motif finding script.*
 
-To use this script you need to have a python 3.8 environment, and install the following dependencies from this file: [mateusz_script_env.txt](https://github.com/user-attachments/files/17568248/mateusz_script_env.txt).
+2. `.bed` (single CTCF sites, e.g. ChIP-seq intervals)
 
-You also need to download the reference genome from: ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/GRCh38_reference_genome/GRCh38_full_analysis_set_plus_decoy_hla.fa
+If you only have unpaired CTCF binding intervals rather than loop calls, you can pass a `.bed` file instead. LoopSage will still build orientation-aware `L`/`R` binding vectors from it, but since there is no anchor-pairing information in a `.bed` file, no loop-adjacency matrix (`J`) can be constructed - CTCF sites contribute individually rather than as loop anchors. Expected columns: `chrom, start, end, name, score, strand`, optionally followed by a probability column (probability the site's best motif hit is reverse-oriented) and an orientation call (`>`, `<`, or `.`).
+
+3. `.narrowPeak` (single CTCF peaks, e.g. MACS2/HiChIP peaks)
+
+Similarly, a `.narrowPeak` file of individual peaks can be used in place of a `.bedpe`/`.bed` file, with the same caveat: no `J` loop matrix is built, only `L`/`R`. Expected columns: `chrom, start, end, name, score`, optionally followed by a forward-orientation probability column and an orientation call.
+
+#### Extracting CTCF motif orientation
+
+To generate the orientation/probability columns for any of the three formats above (`.bedpe`, `.bed`, or `.narrowPeak`), use the motif-finding scripts from [BlackPianoCat/motif_finder](https://github.com/BlackPianoCat/motif_finder):
+
+- `motif_finder_bedpe.py` for `.bedpe` loop files
+- `bed_motif_finder.py` for `.bed` interval files
+- `motif_finder_peaks.py` for `.narrowPeak` peak files
 
-*Alternativelly, it is possible to import a .bedpe file without the last two columns (CTCF orientation). In this case, CTCF would act as an orientation independent barrier. This might affect slightly the results, but it is an easier option, if you do not want to run a CTCF motif finding script.*
+Run the appropriate script with `--prob` to get the probability columns shown above (e.g. `python motif_finder_bedpe.py -i loops.bedpe -g genome.fa -m CTCF.pfm -o loops_with_motif.bedpe --prob`). See that repo's README for full usage details on each script.
 
-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 `EM_LE()` or `EM_LE()` 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.
+You also need to download the reference genome from: ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/GRCh38_reference_genome/GRCh38_full_analysis_set_plus_decoy_hla.fa
 
 ### Running LoopSage from command-line
-To run LoopSage from command-line, you only need to type a command
+
+Running LoopSage from the command line comes down to a single 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,
+This command runs the model using the parameters specified in a `config.ini` file. Here's an example of what that file might look like:
 
 ```txt
 [Main]
 
 ; Input Data and Information
-BEDPE_PATH = /home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe
+INTERACTION_FILE = /home/skorsak/Data/HiChIP/Maps/hg00731_smc1_maps_2.bedpe
 REGION_START = 15550000
 REGION_END = 16850000
 CHROM = chr6
@@ -214,7 +236,7 @@ PLATFORM = CUDA
 INITIAL_STRUCTURE_TYPE = rw
 SIMULATION_TYPE = EM 
 TOLERANCE = 1.0
-``` 
+```
 
 ### Visualization with PyVista
 
@@ -272,39 +294,47 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 ### Long-table of LoopSage arguments
 
 #### General Settings
-| 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                  |
-| OUT_PATH              | Output folder name.                                                                                             | str        | ../results       |
-| SAVE_MDT             | True to save metadata of the stochastic simulation.                                                            | bool       | True                |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| PLATFORM | Simulation platform: CPU, CUDA, or OpenCL | str | CPU |
+| DEVICE | CUDA/OpenCL device index (from 0) | str | None |
+| OUT_PATH | Output folder path | str | ../results |
+| SAVE_MDT | Save simulation metadata | bool | True |
 
 #### Input Data
-| Argument Name          | Description                                                                                                     | Type        | Default Value       |
-|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| BEDPE_PATH            | A .bedpe file path with loops. It is required.                                                                  | str        | None                  |
-| LEF_TRACK_FILE        | Path to a bw file of cohesin or condensin density. If it is provided, then simulation LEFs preferentially bind in enriched regions. | str | None |
-| BW_FILES              | List of paths to .bw files containing additional data for simulation. Enriched regions would act as barriers for cohesin.                | list       | None                  |
-| 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                  |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| INTERACTION_FILE | Loop/peak file (.bedpe, .bed, or .narrowPeak). Required. | str | None |
+| LEF_TRACK_FILE | bigWig track biasing LEF loading toward enriched regions | str | None |
+| BW_FILES | bigWig file(s) acting as extrusion barriers | list | None |
+| SMOOTHING_INPUT | Smooth noisy/sparse loop-peak signal before use | bool | False |
+| COMP_BW_FILE | bigWig track for A/B compartment bias | str | None |
+| COMP_BED_FILE | BED file for A/B compartment bias (alt. to COMP_BW_FILE) | str | None |
+| DATA_LOSS_MODE | 0 = 1D binding potentials (L/R); 1 = 2D loss interpolated from input loops | int | 0 |
+| CONTRASTIVE_BINDING | If True, penalizes loop-free regions so extrusion is confined within TADs; if False, extrusion is uniform everywhere | bool | False |
+| REGION_START | Region start coordinate | int | None |
+| REGION_END | Region end coordinate | int | None |
+| CHROM | Chromosome of the modeled region | str | None |
+| GENOME | Reference genome for chromosome sizes (e.g. hg38) | str | hg38 |
+| FLOAT_LIST | Extra custom numeric settings | list | None |
+| STRING_LIST | Extra custom text settings | list | None |
 
 #### Stochastic Simulation Parameters
-| Argument Name          | Description                                                                                                     | Type        | Default Value       |
-|------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| N_BEADS               | Number of Simulation Beads.                                                                                     | int        | None                  |
-| N_STEPS               | Number of Monte Carlo steps.                                                                                    | int        | 40000               |
-| 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'         |
-| 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_LEF                 | Number of loop extrusion factors.                                                                               | int        | None                  |
-| N_LEF2                | Number of second family loop extrusion factors.                                                                | int        | 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                |
-| BETWEEN_FAMILIES_PENALTY | Penalty applied when loops from different LEF families cross.                                                | bool     | True                 |
+| Argument | Description | Type | Default |
+|---|---|---|---|
+| N_BEADS | Number of simulation beads | int | None |
+| N_STEPS | Monte Carlo steps | int | 40000 |
+| MC_STEP | Sampling frequency (reduces autocorrelation) | int | 200 |
+| BURNIN | Steps discarded before equilibrium | int | 1000 |
+| T_INIT | Initial temperature | float | 2.0 |
+| T_FINAL | Final temperature | float | 1.0 |
+| METHOD | 'Metropolis' or 'Annealing' | str | 'Annealing' |
+| LEF_RW | Cohesins slide as random walk (vs. one direction) | bool | True |
+| LEF_DRIFT | LEFs bounce back off each other | bool | False |
+| N_LEF | Number of loop extrusion factors | int | None |
+| N_LEF2 | Number of second-family LEFs | int | 0 |
+| CROSS_LOOP | Penalize mi<mj<ni<nj crossings (vs. only mj=ni); pair with LEF_DRIFT if False | bool | True |
+| BETWEEN_FAMILIES_PENALTY | Penalize crossings between LEF families | bool | True |
 
 #### Energy Coefficients
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |
@@ -318,7 +348,6 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 #### Molecular Dynamics Simulation
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |
 |------------------------|-----------------------------------------------------------------------------------------------------------------|------------|---------------------|
-| SIMULATION_TYPE       | Either EM (energy minimizations) or MD (molecular dynamics).                                                  | str        | None                  |
 | INITIAL_STRUCTURE_TYPE | Choose from: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.                                | str        | rw                |
 | INTEGRATOR_STEP       | Step of the integrator.                                                                                        | Quantity   | 100 femtosecond   |
 | FORCEFIELD_PATH       | Path to XML file with forcefield.                                                                             | str        | default_xml_path    |
@@ -332,7 +361,7 @@ An example, illustrated with Chimera software, simulated trajectory of structure
 | FRICTION             | Friction coefficient of the Langevin integrator.                                                              | float      | 0.1              |
 | TOLERANCE            | Stopping condition for energy minimization.     | float      | 0.001              |
 | 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                |
+| SIM_STEP             | Amount of simulation steps for loop force adjustments.                                                        | int        | 2000                |
 
 #### Visualization
 | Argument Name          | Description                                                                                                     | Type        | Default Value       |

{pyloopsage-1.1.5 → pyloopsage-1.1.7}/loopsage/__init__.py

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

{pyloopsage-1.1.5 → pyloopsage-1.1.7}/loopsage/args_definition.py

@@ -7,6 +7,9 @@ import argparse
 import openmm as mm
 import importlib.resources
 from openmm.unit import Quantity
+from .logger import get_logger
+
+log = get_logger(__name__)
 
 # Dynamically set the default path to the XML file in the package
 try:
@@ -166,12 +169,16 @@ args = ListOfArgs([
     
     # Input data
     Arg('N_BEADS', help="Number of Simulation Beads.", type=int, default='', val=''),
-    Arg('BEDPE_PATH', help="A .bedpe file path with loops. It is required.", type=str, default='', val=''),
+    Arg('INTERACTION_FILE', help="A .bedpe, .bed, or .narrowPeak file path with loops. It is required.", type=str, default='', val=''),
     Arg('LEF_TRACK_FILE', help="An optional track file for cohesin or condensin in bw format. If this file is specified LEF preferentially binds were the signal is enriched.", type=str, default='', val=''),
     Arg('BW_FILES', help="List of bigWig file paths for feature extraction.", type=list, nargs='+', default=[], val=[]),
+    Arg('SMOOTHING_INPUT',help="Determines if the input signal from peaks or anchros, will be smoothed.", type=bool, default='False', val='False'),
+    Arg('COMP_BW_FILE', help="A bw file for compartmentalization. ", type=str,  default='', val=''),
+    Arg('COMP_BED_FILE', help="A bed file for compartmentalization. ", type=str,  default='', val=''),
     Arg('OUT_PATH', help="Output folder name.", type=str, default='../results', val='../results'),
     Arg('REGION_START', help="Starting region coordinate.", type=int, default='', val=''),
     Arg('REGION_END', help="Ending region coordinate.", type=int, default='', val=''),
+    Arg('GENOME',help='Reference genome assembly (e.g. "hg38" or "hg19"). Used to determine chromosome lengths and genomic coordinates.',type=str,default='hg38',val='hg38'),
     Arg('CHROM', help="Chromosome that corresponds the the modelling region of interest (in case that you do not want to model the whole genome).", type=str, default='', val=''),
     Arg('FLOAT_LIST', help="List of floating-point numbers.", type=list, nargs='+', default=[], val=[]),
     Arg('STRING_LIST', help="List of strings.", type=list, nargs='+', default=[], val=[]),
@@ -179,6 +186,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('VARIABLE_SLIDING_STEP', help="If True, the sliding step is uniformly sampled from [1, L_min] based on experimental loop lengths; if False, a fixed unit step is used.", 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'),
@@ -190,9 +198,14 @@ 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('EPI_COEFF', help="Coefficient of Epigenetic Mark Spreading Model (experimental).", type=float, default='0.0', val='0.0'),
+    Arg('N_EPI_STATES', help="Number of epigenetic states in the Potts model (by default 3: -1,0,1)", type=int, default='3', val='3'),
+    Arg('P_SPIN', help="Probability that it would be proposed a node state move, instead of a LEF move.", type=float, default='0.5', val='0.5'),
     Arg('BW_STRENGTHS', help="List of strengths of the energy (floats) corresponding to each BW file. This equivalent to the `r` parameter in the LoopSage paper.", type=list, nargs='+', default=[], val=[]),
     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('BETWEEN_FAMILIES_PENALTY', help="Penalty for LEF2s that are crossing LEFs.", type=bool, default='True', val='True'),
+    Arg('DATA_LOSS_MODE', help="If it is 0 means 1D, and thus we use L and R potentuals. If it is equal to 1, then it uses a 2D loss function interpolated from the input loops.", type=int, default='0', val='0'),
+    Arg('CONTRASTIVE_BINDING', help="If it will be True, loop free regions in the heatmap would be penalized, and loop extrusion can occur only within TADs. Otherwise, if False loop extrusion is homogeneous.", type=bool, default='False', val='False'),
     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'),
@@ -200,12 +213,12 @@ args = ListOfArgs([
     
     # Molecular Dynamic Properties
     Arg('INITIAL_STRUCTURE_TYPE', help="you can choose between: rw, confined_rw, self_avoiding_rw, helix, circle, spiral, sphere.", type=str, default='rw', val='rw'),
-    Arg('SIMULATION_TYPE', help="It can be either EM (multiple energy minimizations) or MD (one energy minimization and then run molecular dynamics).", type=str, default='', val=''),
-    Arg('INTEGRATOR_STEP', help="The step of the integrator.", type=Quantity, default='100 femtosecond', val='100 femtosecond'),
+    Arg('INTEGRATOR_STEP', help="The step of the integrator.", type=Quantity, default='`100 femtosecond', val='100 femtosecond'),
     Arg('FORCEFIELD_PATH', help="Path to XML file with forcefield.", type=str, default=default_xml_path, val=default_xml_path),
-    Arg('ANGLE_FF_STRENGTH', help="Angle force strength.", type=float, default='200.0', val='200.0'),
+    Arg('ANGLE_FF_STRENGTH', help="Angle force strength.", type=float, default='100.0', val='100.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('LE_FF_STRENGTH', help="Interaction Strength of loop forces.", type=float, default='60000.0', val='60000.0'),
+    Arg('DO_COMPARTMENTS', help="True to enable block-copolymer force in 3D.", type=bool, default='False', val='False'),
     Arg('CONTINUOUS_TOP', help="True if topoisomerase disables EV in a continuous region rather than a discrete set of points.", type=bool, default='False', val='False'),
     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'),
@@ -214,5 +227,5 @@ args = ListOfArgs([
     Arg('TOLERANCE', help="Tolerance that works as stopping condition for energy minimization.", type=float, default='0.001', val='0.001'),
     Arg('VIZ_HEATS', help="Visualize the output average heatmap.", type=bool, default='True', val='True'),
     Arg('SIM_TEMP', help="The temperature of the 3D simulation (EM or MD).", type=Quantity, default='310 kelvin', val='310 kelvin'),
-    Arg('SIM_STEP', help="This is the amount of simulation steps that are perform each time that we change the loop forces. If this number is too high, the simulation is slow, if is too low it may not have enough time to adapt the structure to the new constraints.", type=int, default='1000', val='1000'),
+    Arg('SIM_STEP', help="This is the amount of simulation steps that are perform each time that we change the loop forces. If this number is too high, the simulation is slow, if is too low it may not have enough time to adapt the structure to the new constraints.", type=int, default='2000', val='2000'),
 ])

{pyloopsage-1.1.5 → pyloopsage-1.1.7}/loopsage/initial_structures.py

@@ -1,5 +1,8 @@
 import numpy as np
 from tqdm import tqdm
+from .logger import get_logger
+
+log = get_logger(__name__)
 
 def dist(p1: np.ndarray, p2: np.ndarray) -> float:
     """Mierzy dystans w przestrzeni R^3"""
@@ -117,21 +120,38 @@ def random_walk_structure(N_beads, step_size=1):
     
     return V
 
-def compute_init_struct(N_beads,mode='rw'):
+def compute_init_struct(N_beads, mode='rw'):
+    log.info(f"Initializing polymer structure: mode='{mode}', N_beads={N_beads}")
+
     match mode:
         case 'rw':
+            log.debug("Using random walk initialization")
             return random_walk_structure(N_beads)
+
         case 'confined_rw':
+            log.debug("Using confined random walk initialization")
             return confined_random_walk(N_beads)
+
         case 'self_avoiding_rw':
+            log.debug("Using self-avoiding random walk initialization")
             return self_avoiding_random_walk(N_beads)
+
         case 'circle':
+            log.debug("Using circular polymer initialization")
             return polymer_circle(N_beads)
+
         case 'helix':
+            log.debug("Using helical polymer initialization")
             return helix_structure(N_beads)
+
         case 'spiral':
+            log.debug("Using spiral polymer initialization")
             return spiral_structure(N_beads)
+
         case 'sphere':
+            log.debug("Using spherical surface initialization")
             return sphere_surface_structure(N_beads)
+
         case _:
-            return IndentationError('Invalid option for initial structure.')
+            log.error(f"Invalid initialization mode: '{mode}'")
+            raise ValueError(f"Invalid option for initial structure: {mode}")