ChromGEM

Overview

ChromGEM (Chromatin Geometry Empowered Model) is a three-layer computational framework that models how the ground-truth organization of chromatin is transformed by fluorescence labeling and single-molecule localization microscopy (SMLM) measurement physics. The framework begins with a heterogeneous distribution of nucleosomes, simulates the accessibility and binding of fluorescent probes, and then simulates the stochastic localization events detected by an SMLM experiment. The resulting data can be compared directly with the underlying nucleosome distribution to quantify how probe geometry and fluorophore photokinetics influence the apparent structure of chromatin.

The three layers are connected sequentially:

1. Layer 1 — SR-EV Chromatin Generation: generates ground-truth 3D nucleosome coordinates representative of electron microscopy-observed chromatin in a cell line of choice.
2. Layer 2 — Molecular Dynamics Simulation of Label Probes: places mobile EdU- or BrdU-associated probes around the fixed nucleosome configuration, simulates probe diffusion and binding, and removes unbound probes in a simulated wash.
3. Layer 3 — Monte Carlo Simulation of Fluorophore Emissions: converts the post-wash probe coordinates into stochastic SMLM localization events using experimentally informed blinking and localization-uncertainty distributions.

The downstream workflows operate on voxel-based 3D TIFF volumes rather than coordinate lists. The nucleosome, probe, or simulated-localization coordinates are therefore binned into a 3D grid and smoothed with a 3D Gaussian filter before domain identification and analysis. The workflows then identify packing-domain centers, extract individual three-dimensional domains, calculate their radial density and mass-scaling properties, and generate the plots used in Figure 3d–e.

Layer 1: SR-EV nucleosome coordinates
              |
              v
Layer 2: accessible, bound-probe coordinates
              |
              v
Layer 3: simulated SMLM localization coordinates
              |
              v
Coordinate binning + 3D Gaussian blur (radius = 5 pixels)
              |
              v
Voxel-based 3D TIFF volumes
              |
              v
3D domain identification and domain analysis
              |
              v
Radial-density plots

In this folder, we explain the ChromGEM codes and demonstrate for an illustrative example ChromGEM profiling of label performance of BrdU and EdU labels in HCT116 model chromatin using BrdU. Scripts are given for reproducibility but the data generated by each layer are provided for added convenience.

System Requirements

Software Requirements

1. LAMMPS (the study used the March 3, 2020 version), built with the ASPHERE, MPI, MPIIO, OpenCL, and OpenMP packages.
2. Open MPI version 4.1.4.
3. A Fortran 90 compiler, such as gfortran.
4. Not required but highly recommended: A SLURM-compatible computing cluster for the supplied batch-execution script.
5. Not required but highly recommended: Anaconda to install Python, Jupyter Notebook, and required Python dependencies easily.

Hardware Requirements

• It is recommended to allocate at least 30GB and 16 processors to each simulation. Each simulation will take up to 48 hours to run. ChromGEM can be run in serial (simulated SMLM in one chromatin configuration at a time) or in parallel (simulated SMLM in multiple chromatin configurations at once).
• The Domain Identification in 3D/3D Domain Identification_github.ipynb script in particular will take 5+ hours to run for workstation with 32GB of RAM.

Python Dependencies

The notebooks require the following key Python packages:

numpy 1.26.4
pandas 2.1.4
matplotlib 3.8.0
scipy 1.11.4
tifffile 2023.4.12

Not every imported package is used by every script. A dedicated environment file is recommended for long-term reproducibility.

Versions Tested

• Layers 1 and 2 have successfully run on Linux-RHEl7-x86_64.
• Layer 3 has successfully run on Windows 11.

Installation Guide

Download the zipped file and unzip in your working directory. This will take <5 min. on a typical desktop.

Layer 1: SR-EV Model Chromatin Generation

In the SR-EV algorithm, a Self-Returning Random Walk (SRRW) is performed to generate a list of nucleosome locations in space followed by a short molecular dynamics simulation to account for excluded volume occupied by each nucleosome. The computational procedure for the Self-Returning, Excluded Volume (SR-EV) polymer model generation was obtained from published work (Carignano, Kroeger, et al., eLife, 2024). Two user-selected parameters are input into SR-EV: alpha ($\alpha$), which tunes clustering patterns in the SRRW, and phi ($\phi$), which controls the chromatin volume fraction in the simulation box (and subsequently the number of outputted nucleosomes). The SR-EV generation code is not included in this repository and are available upon request from the co-first authors of the cited publication.

What this layer does

Layer 1 generates a three-dimensional distribution of chromatin in which each particle represents a nucleosome. The Self-Returning Excluded Volume model begins by generating a Self-Returning Random Walk (SRRW), a modified random walk that is guided by two “return rules” for dictating the probability of return steps and forward steps in the walk:

$$P_R(U_0) = \frac{(U_0)^{-\alpha}}{\alpha}$$ $$P_J(U_1>1) = \frac{\alpha+1}{(U_1)^{\alpha+2}}$$

Equation 1 computes the return probability ($P_R$) as a function of $𝑈_0$, the length of the previous step over which the walk may return, and input folding parameter $\alpha$. If the walk does not return based on Equation 1, the model proceeds with Equation 2 to compute the forward ("jump”) probability ($P_J$). $P_J$ is computed as a function of $𝑈_1$ (the length of the next step in the walk) and $\alpha$. The randomization algorithm for step lengths and orientations is enumerated in Carignano, Kroeger, et al., eLife, 2024.

Critically, these return rules can be modulated via $\alpha$, an input parameter regulating folding in the walk. The number of points (nucleosomes) in the walk is tuned via $\phi$, the second input parameter of SR-EV. The crowding parameter $\phi$ denotes the average volume fraction of chromatin in the space in which the configuration is generated. $\phi$ can be tuned to generate chromatin configurations that correspond to a wide range of cell types and stages of differentiation. Following the generation of the SRRW, a brief molecular dynamics simulation is performed to enforce repulsion between any points in the walk that overlap in a manner unrealistic of nucleosomes and thus enable the SR-EV model to produce model chromatin distributions that take into account the excluded volume effects of each nucleosome. This configuration provides the ground-truth chromatin geometry used by both the labeling simulation and the downstream domain analyses.

Input

• SR-EV model parameters $\alpha$ and $\phi$.
• If needed, other minor SR-EV generation settings defined in the source implementation, namely the simulation box dimensions. This would likely need to be tweaked for SREV configurations with $\phi$ > 0.12 to avoid overcrowding in the box before the SR-EV algorithm approaches the desired $\phi$.

Output

• A three-dimensional SR-EV nucleosome configuration, normally stored as a LAMMPS-style dump file containing particle coordinates, unique particle identifiers, and particle types (all set to 1 to indicate they are nucleosomes).
• These nucleosome coordinates are used as:
  • the model chromatin substrate for labeling in Layer 2;
  • the ground-truth nucleosome coordinates in Layer 3; and
  • the source data for 3D packing domain identification and analysis.

BrdU and EdU in HCT116 Case Study

In this study, input parameters of $\alpha$ = 1.15 and $\phi$ = 0.12 were used to generate model HCT116 chromatin distributions because they were previously demonstrated to generate chromatin configurations that align with ChromSTEM observations of domain distributions in HCT116. The SREV configurations outputted from these parameters were also what was used in the manuscript. These are given in Layer 2/Inputs for use in the BrdU and EdU example study.

Layer 2: Molecular-Dynamics Simulation of the Label Probe

Layer 2 is contained in Layer_2/ and includes the execution scripts for EdU and BrdU labeling used in the study. The simulations use LAMMPS to model 10,000 fluorescent label probes diffusing about a fixed SR-EV nucleosome configuration.

What this layer does

For each SR-EV configuration, Layer 2 performs the following operations:

1. Go to the directory containing the SREV configuration (ideally should have 1 SREV configuration per folder).
2. Copy over the fluorophore diffusivity simulation scripts to that directory.
3. Load the LAMMPS Molecular Dynamics and MPI packages.
4. Enter SREV configuration filenames into the fluorophore diffusivity scripts.
5. InitWalkers.f90 randomly initializes 10,000 probe positions inside the simulation box while rejecting positions that overlap nucleosomes or previously placed probes.
6. getconfig_nooverlaps.in prepares the nucleosome configuration and remove rare unrealistic nucleosome overlaps before probe diffusion is simulated.
7. overlapfilter.in outputs the number of SREV nucleosomes from Step #6, which is used to compute the LAMMPS parameter needed to maintain a constant temperature* throughout binding iterations for input into first_sim.in.
8. first_sim.in performs the first LAMMPS diffusion interval and writes the probe trajectory to walkers.xyz.
9. For n number of user-specified iterations, loop through Steps #10-12 below:

10. ImmobilConversion.f90 reads the final saved frame, calculates the probe-to-nucleosome distance, and based on this distance assigns each probe a state:

• type 2: mobile/unbound;
• type 3: nucleosome-colocalized/immobilized.

11. overlapfilter_continue.in outputs the number of immobilized dye labels and stuck SREV nucleosomes in the simulation, which is used to compute the LAMMPS parameter needed to maintain a constant temperature* throughout binding iterations for input into continue_sim.in.
12. continue_sim.in uses the updated probe states to continue the simulation. Bound probes remain fixed, while unbound probes continue to diffuse.

13. FinalWash.f90 performs the final distance check and removes all probes that remain unbound, producing the simulated post-wash labeled chromatin sample.

These scripts are stored in General_Label_Execution_Scripts/ , the program version for generating simulated labeling data in a probe size of choice. Before running, consult "Layer 2 Preparation Steps" first and complete the checks therein.

Input

• One SR-EV nucleosome configuration per simulation directory, in LAMMPS dump format.
• User-edited parameters in the Fortran, LAMMPS, and SLURM scripts, including:
  • input SR-EV configuration filename;
  • simulation box lengths and lower bounds (must be consistent with the SREV-outputted file);
  • probe size;
  • number of probes;
  • number of diffusion/immobilization iterations;
  • Optional but highly recommended: SLURM array range, account, working directory, and source-script directory.

Output

• walkerinput.in: initial nonoverlapping probe coordinates formatted as LAMMPS create_atoms commands.
• walkers.xyz: probe trajectory from the current LAMMPS diffusion interval.
• post-immobil-input.in: updated probe coordinates and particle types for the next interval.
• Edited/overlap-filtered nucleosome configuration used for subsequent calculations.
• Post-wash .xyz files containing only probes classified as chromatin-bound, for example:
  • EdU-2nm-washed.xyz;
  • BrdU-10nm-washed.xyz.

Layer 2 Preparation Steps

Set up your directory of SREV configurations in the following manner:

• Have a production directory that is for containing all of your SMLM simulations in your set of input SREV configurations. This directory should ONLY contain SREV configurations (configs) that were made with the same input parameters (ex: all the SREV configs in this directory being made with input alpha = 1.15 & phi = 0.12 is good, some SREV configs in this directory being made with input alpha = 1.15 & phi = 0.12 and other SREV configs in this directory being made with input alpha = 1.15 & phi = 0.16 is bad).

• For the n number of SREV configs in this production directory, have n directories (one for each SREV config). Each SREV config should be assigned its own index that is between 1 to n. The SREV config file name should be named as "config-$i.dump", where $i is the index of that SREV config. Each of the directories within the production directory should also be assigned its own index that is between 1 to n. Each of these directories within the production directory should be named as "Config_$i", where $i is the assigned index of that directory. Each of these directories should only contain the SREV config that is of the same index as the directory.

Specify the simulation box dimensions.

• This should match the SREV config file dimensions. All these scripts are in units of reduced units or "ru", where 1 ru = 10 nm. Go to InitWalkers.f90, ImmobilConversion.f90, and FinalWash.f90, and ensure all xlength, ylength, and zlength variables are consistent with the box dimensions indicated in the SREV config file and that in the InitWalkers.f90 file all xlowerbound, ylowerbound, and zlowerbound variables are consistent with the lowerbound dimensions stipulated in lines 6-8 of the SREV config file. To identify the xlowerbound, ylowerbound, and zlowerbound information in the SREV config file, understand that line 6 specifies the lower and upper limits of the box in the x direction, line 7 specifies the lower and upper limits of the box in the y direction, and line 8 specifies the lower and upper limits of the box in the z direction. In lines 6-8, the order of the values is lower limit in that dimension and then upper limit in that dimension. Understand that these box dimensions are given in ru and in scientific notation. So, if line 7 says " -1.0000000000000000e+02 1.0000000000000000e+02", that means the box dimension in the y dimension is -100 ru to 100 ru. This means you should go to the lines that define the ylowerbound and ylength variables and set ylowerbound as -100 and ylength as 200 (as y_upper_limit - y_lower_limit = ylength).

Update the bash file.

Open the execute_sim_in_array.sh file in EdU_Execution_Scripts and in BrdU_Execution_Scripts. Make the following updates:

• If executing a batch job in parallel: In line #3: change the range specified in the definition of array to match the range of SREV configs you wish to simulate SMLM labeling in. So, if you would like to simulate SMLM labeling in 100 SREV configs, change the "#SBATCH --array=1-10" line to be "#SBATCH --array=1-100".

• Update the locations of LAMMPS and OpenMPI to the locations of those packages on your machine.

• Update the size variable to be your chosen size for the probe to simulate in the model chromatin. This update should be in nm; the script will handle the internal conversion to reduced units.

• In line #13: change the production directory for the location of the directory containing your SREV configs and utilize the SLURM_ARRAY_TASK_ID variable to tell the supercomputer how to locate each SREV config. So, if you have 100 SREV configs in a directory with the name "/home/my_SMLM_simulations/SREV_configs_made_with_phi_0.12_alpha_1.15/" and in this directory, each SREV configuration of index i is in a directory with a name of "SREV_Configi" (ex: "SREV_Config1", "SREV_Config2", "SREV_Config3", etc.), change the "dirname="/projects/p31375/ChromGEM-main/BrdU_Phi08/Config${SLURM_ARRAY_TASK_ID}"" line to be "dirname="/home/my_SMLM_simulations/SREV_configs_made_with_phi_0.12_alpha_1.15/SREV_Config${SLURM_ARRAY_TASK_ID}"".

• In line 19: change the source directory line for the location of the directory containing the BrdU and EdU SMLM simulation execution scripts. These are the locations of the BrdU_Execution_Scripts folder and EdU_Execution_Scripts folder on your machine/workspace. So, if the BrdU_Execution_Scripts folder and EdU_Execution_Scripts folder are in a directory with the name "/home/SMLM_Execution_Scripts/BrdU_Execution_Scripts/" and "/home/SMLM_Execution_Scripts/EdU_Execution_Scripts/" respectively, in the execute_sim_in_array.sh file located in BrdU_Execution_Scripts, change the "cp /projects/p31375/ChromGEM/BrdU_Execution_Scripts/* ." line to "cp /home/SMLM_Execution_Scripts/BrdU_Execution_Scripts/* ." and in the execute_sim_in_array.sh file located in EdU_Execution_Scripts, change the "cp /projects/p31375/ChromGEM-main/EdU_Execution_Scripts/* ." line to "cp /home/SMLM_Execution_Scripts/EdU_Execution_Scripts/* ." . Make sure to preserve the "* ." at the end!

• If executing through a cluster: In line 2 and 9: change the line "#SBATCH --account=p31375" to specify instead the project you would be running this through on Quest and change the "#SBATCH --output=log.%j" to your preferred name for output logs.

Layer 2 Conceptual Notes

Why is redefining the temperature parameters important?

Over the course of all the simulation iterations, it is important that you are collecting molecule localizations that occur at the same temperature. When specifying the input target temperature parameters, LAMMPS takes that to specify the temperature of the whole simulation. Since the vast majority of the simulation particles are SREV nucleosome ellipsoids that are kept stuck in place, this complicates the actual energy that gets distributed among the mobile particles to have them move at the specified temperature. Therefore, the input temperature parameters that are given to the LAMMPS simulator program should take this into account so that the mobile particles are actually diffusing at your desired target temperature (in this case the script is set to simulate the objects at a target temperature T = 2.50*). Since the number of particles the simulation should mark as immobilized gets updated with each iteration, the temperature to input is re-computed each iteration to account for that updated number.

The equation that computes the temperature to input to produce the desired temperature is the following: number_of_mobile_particles / (number_of_mobile_particles + number_of_immobile_particles) * desired_temp = temp_to_input

BrdU and EdU Case Study

As an example, the BrdU and EdU Execution Scripts used for the manuscript are provided (Layer_2/BrdU_Execution_Scripts and Layer_2/EdU_Execution_Scripts, respectively). The supplied BrdU scripts use an effective probe diameter of 1 reduced unit (10 nm), whereas the supplied EdU scripts use an effective diameter of 0.2 reduced units (2 nm). Throughout Layer 2, 1 reduced unit = 10 nm. For convenience, the final outputs for Layer 2 with SREV config #3 are stored in the Layer_3_Monte_Carlo/Layer 3 input folder for easy input into Layer 3.

Layer 3: Monte Carlo Simulation of Fluorophore Emissions

Notebook: Layer_3_Monte_Carlo/Layer 3 Monte Carlo simulation_github.ipynb

What this notebook does

The Layer 3 notebook converts the physical probe locations produced by Layer 2 into the localization events expected from an SMLM measurement. It performs four main tasks:

1. Reads the pre-wash and post-wash EdU and BrdU coordinates and the edited ground-truth nucleosome coordinates from .xyz files.
2. Converts the Layer 2 coordinates from reduced units to nanometers by multiplying each coordinate by 10.
3. Selects probes and nucleosomes within a user-defined 3D region and optionally randomly subsamples them for visualization or computation.
4. Applies an experimentally informed Monte Carlo model to every selected post-wash probe:
   • the number of localization events per fluorophore is sampled from a negative-binomial distribution;
   • the radial localization error is sampled from a log-normal distribution;
   • a uniformly sampled angle distributes that error in the imaging plane;
   • the sampled displacement is added to the probe coordinate to generate a simulated detected localization.

The implemented generateLocalization() function records both the true fluorophore position and every simulated localization generated from it. The model parameters are set directly inside this function and should be changed when modeling a different fluorophore, buffer, acquisition condition, or experimentally measured photokinetic distribution.

Input

The example files are stored in Layer_3_Monte_Carlo/Layer 3 input/:

• EdU-2nm.xyz: EdU probe coordinates before the simulated wash.
• EdU-2nm-washed.xyz: chromatin-bound EdU probe coordinates after the simulated wash.
• BrdU-10nm.xyz: BrdU probe coordinates before the simulated wash.
• BrdU-10nm-washed.xyz: chromatin-bound BrdU probe coordinates after the simulated wash.
• edited-config-3.xyz: "edited" ground-truth SR-EV nucleosome coordinates.
  • This "edited" file is generated in Layer 2; before performing the label diffusivity simulations, the original SREV-generated model chromatin configurations pass through an initial filter In Layer 2 that screens out any nucleosome positions overlapping in a manner unrealistic of the excluded volume occupied by nucleosomes. This step is vital to prevent simulation crashes. These screened nucleosome positions were 0-25 out of the outputted 530000+. Label diffusivity simulations are then performed on those "edited" files.

User-defined notebook parameters include the input and output directories, the x, y, and z bounds of the analyzed region, the sampling factor, and the negative-binomial and log-normal distribution parameters used by the Monte Carlo model.

Each coordinate file is expected to contain whitespace-separated rows of the form:

particle_type  x  y  z

Output

• df_locali_EdU.csv: simulated EdU localization events. Columns contain the parent fluorophore position, localization-event number, and simulated x [nm] and y [nm] coordinates.
• df_locali_BrdU.csv: corresponding simulated BrdU localization events.
• df_fluor_EdU.csv: selected ground-truth post-wash EdU probe positions in the imaging plane.
• df_fluor_BrdU.csv: selected ground-truth post-wash BrdU probe positions in the imaging plane.
• df_fluor_nucleosome.csv: selected ground-truth nucleosome positions in the imaging plane.
• Diagnostic scatter plots comparing label distributions before and after the simulated wash.

These CSV files provide paired ground-truth and simulated measurement datasets for downstream quantitative comparison.

The post-wash EdU and BrdU coordinate files, together with the edited SR-EV nucleosome configuration, are the principal inputs to Layer 3. The same ground-truth nucleosome and post-wash probe distributions can also be voxelized and analyzed through the parallel 3D domain-analysis branch. Layer 3 localizations are therefore the simulated SMLM endpoint; they are not required by the supplied 3D radial-density notebook in Domain Radial Density Plot (Figure 3 d e)/.

Coordinate-to-Volume Conversion for Downstream Analysis

The outputs of Layers 1–3 are coordinate-based datasets, whereas the downstream 3D domain-identification and domain-analysis workflows operate on voxel-based multipage TIFF volumes. An additional preprocessing step is therefore required to convert a selected coordinate distribution into a volumetric density image:

1. Assign the x, y, and z coordinates to voxels in a 3D grid.
2. Count the coordinates falling within each voxel to generate a 3D occupancy or density volume.
3. Apply a 3D Gaussian blur with a radius of 5 pixels to the voxelized volume.
4. Save the smoothed volume as a multipage TIFF file.

For the nucleosome coordinates, this procedure generates:

Nucleosome_Gaussian_rad5.tif

This TIFF represents the spatially smoothed 3D nucleosome-density distribution and is the primary input for both 3D domain identification and the subsequent 3D domain-property analysis. Gaussian smoothing reduces voxel-scale fluctuations introduced by coordinate discretization and creates a continuous local-density field from which packing-domain centers and radial-density profiles can be calculated.

Equivalent TIFF volumes can be generated from the EdU, BrdU, or simulated localization coordinates when those distributions are analyzed using the same volume-based workflow. For matched comparisons, all coordinate datasets must use the same grid dimensions, voxel size, coordinate origin, and Gaussian-filter parameters.

Downstream Analysis 1: Domain Identification in 3D

Directory: Domain Identification in 3D/

What the domain identification script does

This domain identification workflow takes after the domain identification workflow in 2D chromatin scanning transmission electron microscopy (ChromSTEM) data (Li et al., Scientific Reports 2022 W.S.Li, Carter, Almassalha et al., Science Advances 2025). The domain identification workflow locates the centers of local chromatin packing domains in the ground-truth SR-EV configuration:

1. Converts the 3D nucleosome coordinates into a voxelized chromatin-density volume.
2. Applies a 3 x 3 x 3 maximum filter to identify candidate local maxima. A voxel is retained as a candidate when its intensity equals the maximum intensity in its local neighborhood.
3. For each candidate center with intensity I_c, forms a tolerance mask containing voxels that satisfy I_c - I(r) <= T, where T is the selected intensity tolerance (the standard deviation of voxel intensities was used in the study).
4. Applies 26-neighbor connected-component analysis to the tolerance mask and retains only the component containing the candidate center. This connected component is the candidate's dominant region.
5. Ranks candidates from highest to lowest intensity. A lower-intensity candidate is discarded if its coordinate lies within the dominant region of a previously accepted higher-intensity candidate. This merges neighboring maxima that belong to the same tolerance-defined packing domain and avoids duplicate centers.
6. Returns the surviving coordinates as the 3D packing-domain centers.

Input

• Nucleosome_Gaussian_rad5.tif, generated by voxelizing the nucleosome coordinates and applying a 3D Gaussian blur with a radius of 5 pixels.
• Voxel size and volume dimensions.
• Maximum-filter neighborhood size (3 x 3 x 3 in the study).
• Intensity tolerance T.

Output

• An N x 3 array of domain-center voxel coordinates, typically stored as a NumPy .npy file.
• The example downstream filename is Nucleosome_maxima (domain center)_github.npy.
• Optional intermediate products may include the voxelized nucleosome volume, candidate-maxima mask, and accepted-center visualization.

The detected center coordinates are used by the 3D domain analysis notebook to center and extract one cubic region of interest for each domain.

Downstream Analysis 2: Domain Analysis in 3D

Notebook: Domain analysis in 3D/Fig3_3D_domain_analysis_github.ipynb

What this notebook does

This notebook characterizes each detected packing domain in a 3D density volume. For every supplied domain center, it:

1. Measures the center's distance from all six volume boundaries and sets the available half-width, ahw, to the smaller of this distance and the maximum requested half-width hw.
2. Skips centers for which ahw is smaller than ahw_thresh, preventing analysis of domains with insufficient surrounding volume.
3. Extracts an odd-sized cubic region of interest centered on the domain.
4. Generates a summed 2D projection of the extracted domain.
5. Normalizes the extracted central subvolume and bins voxel intensities into concentric 3D spherical shells.
6. Divides the intensity in each shell by the number of sampled voxels in that shell to calculate radial density (meanRD).
7. Calculates shell mass and cumulative enclosed mass by scaling the radial-density terms by spherical surface-area and volume factors.
8. Computes the local slope of log cumulative mass versus log radius with a moving fitting window. This scale-dependent slope represents the local mass-scaling exponent.
9. Saves the plots and numerical variables for every domain.

Important notebook parameters include:

• dr = 2: radial step/voxel spacing used to construct the radius array;
• hw = 150: maximum domain half-width in voxels;
• cw = 5: central-window half-width excluded from the usable radial extent;
• ahw_thresh = 25: minimum accepted half-width;
• windowsize = 5: default moving-window size for slope estimation.

Input

• A 3D nucleosome-density TIFF, such as Nucleosome_Gaussian_rad5.tif.
• Domain-center coordinates as an N x 3 array, ideally loaded from Nucleosome_maxima (domain center)_github.npy.
• Output directory and the analysis parameters described above.

The coordinate ordering must match the TIFF axis ordering used by the notebook. The current code maps each center into the array as (slice, row, column) during ROI extraction; this convention should be verified whenever a new volume or center file is used.

Output

For every accepted domain NN, the notebook writes:

• DomainProjNN.tif: summed 2D projection of the 3D domain.
• DomainMSRingNN.tif: log-log plot of shell mass versus radius.
• DomainMSNN.tif: log-log plot of cumulative enclosed mass versus radius.
• DomainMSFirstDevNN.tif: scale-dependent slope of the cumulative mass-scaling curve.
• RadialDensityNN.tif: radial-density curve.
• DomainNN.mat: numerical results containing meanMSRing, sdMSRing, meanMS, sdMS, rslope, slope, meanRD, sdRD, r_domain, cw, rn, and the domain centroid.

The DomainNN.mat files are the inputs to the Figure 3d–e radial-density plotting notebook.

Downstream Analysis 3: Domain Radial Density Plot (Figure 3d–e)

Notebook: Domain Radial Density Plot (Figure 3 d e)/Fig3de.RadialDensityPlot_github.ipynb

What this notebook does

This notebook compares the radial organization of the ground-truth nucleosomes with the accessible EdU and BrdU label distributions for a representative domain. It:

1. Loads the MATLAB result files generated by the 3D domain-analysis workflow for EdU, BrdU, and nucleosomes.
2. Extracts meanRD from each file.
3. Normalizes each radial-density curve by its own maximum so the spatial profiles can be compared independent of absolute signal magnitude.
4. Plots the normalized EdU, BrdU, and nucleosome radial-density profiles.
5. Calculates and plots the first discrete derivative of the normalized EdU and BrdU profiles to highlight changes in radial accessibility.

Input

• Domain04_EdU_github.mat.
• Domain04_BrdU_github.mat.
• Domain04_Nucleosome_github.mat.

Each .mat file must contain a one-dimensional meanRD array generated using the same center, voxel size, radial sampling, and ROI definition. Example files are supplied in the notebook's input/ directory.

Filename note: The repository currently stores Domain04_Nucleosome_github.mat, whereas the notebook loads Domain04_nucleosome_github.mat. This capitalization should be made consistent for case-sensitive operating systems.

Output

• A normalized radial-density plot comparing EdU, BrdU, and nucleosome profiles (Figure 3d).
• A first-derivative plot comparing the EdU and BrdU normalized radial-density profiles (Figure 3e).
• Figures can be saved in any Matplotlib-supported format by setting the output path in plt.savefig().

Layer 3 Reproducibility Notes

• Replace the blank or Windows-style input/output paths in the notebooks before execution.
• Set explicit random seeds for the Layer 3 subsampling and Monte Carlo simulation if exactly reproducible localization sets are required.
• Confirm that all coordinate units are correct. Layer 2 uses reduced units (1 ru = 10 nm), while Layer 3 converts coordinates to nanometers.
• Use the same coordinate origin, grid dimensions, voxel size, and Gaussian-blur parameters when generating matched nucleosome, EdU, BrdU, or localization TIFF volumes.
• Confirm axis ordering between domain-center coordinates and TIFF volumes.
• Use identical centers and radial-analysis parameters when comparing EdU, BrdU, and nucleosome profiles.

End-to-End Data Handoff

Stage	Primary input	Primary output	Used by
Layer 1	$\alpha$, $\phi$, SR-EV settings	3D nucleosome configuration	Layer 2; 3D domain identification
Layer 2	SR-EV nucleosomes; EdU/BrdU probe settings	Pre-wash and post-wash probe .xyz files; edited nucleosome configuration	Layer 3
Layer 3	Post-wash probes; ground-truth nucleosomes	Simulated SMLM localization CSVs and ground-truth coordinate CSVs	SMLM-vs-ground-truth comparisons
Coordinate-to-volume conversion	Nucleosome, probe, or localization coordinates	Gaussian-smoothed 3D TIFF volume	Volume-based downstream analysis
3D domain identification	Nucleosome_Gaussian_rad5.tif	Domain-center coordinates (.npy)	3D domain analysis
3D domain analysis	Density volume; domain centers	Per-domain TIFF plots and DomainNN.mat files	Figure 3d–e plotting
Radial-density plotting	Matched EdU, BrdU, and nucleosome DomainNN.mat files	Normalized radial-density and derivative figures	Figure 3d–e

References and Acknowledgements

1. Carignano, M. A., Kroeger, B., et al. Local Volume Concentration, Packing Domains and Scaling Properties of Chromatin. eLife (2024). https://elifesciences.org/articles/97604
2. Yeo, W.-H., et al. Investigating uncertainties in single-molecule localization microscopy using experimentally informed Monte Carlo simulation. Nano Letters 23, 7253–7259 (2023).
3. Thompson, A. P., et al. LAMMPS—a flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales. Computer Physics Communications 271, 108171 (2022).
4. Brown, W. M., Petersen, M. K., Plimpton, S. J. & Grest, G. S. Liquid crystal nanodroplets in solution. Journal of Chemical Physics 130, 044901 (2009).

The simulations scripted here were performed using the LAMMPS Molecular Dynamics Simulator³. For more on LAMMPS, consult https://www.lammps.org . Interactions between the particles were modeled using LAMMPS' pair gayberne framework for modeling Gay-Berne interaction potentials between ellipsoidal particles⁴.

We acknowledge the contributions of Dr. Marcelo Carignano in determining the formula for obtaining the desired simulation temperature based on the number of mobile particles and immobilized particles.

Declaration of Generative AI and AI-Assisted Technologies in this Documentation During the preparation of this document, the author(s) used ChatGPT 5.6 in order to ensure readability. After using this tool/service, the author(s) reviewed and edited the content as needed and took full responsibility for the content of the publication.