Config Schema

Config Schema Reference#

Simulation Configuration Module#

This module defines the structure and parameters required for simulating cell behavior, diffusion tracks, and condensate dynamics within a spatial environment. The simulation configuration is described both in terms of a JSON schema and Python dataclasses, which are used to manage and validate the input parameters for simulations. The parameters are grouped into different categories like Cell_Parameters, Track_Parameters, Global_Parameters, Condensate_Parameters, and Output_Parameters.

The simulation configuration allows for customizing aspects like track diffusion, Hurst exponents, condensate properties, and camera settings. The module ensures that the correct units (e.g., space, time, intensity, diffusion) are used consistently throughout the simulation, helping to provide accurate modeling of physical phenomena.

The module follows the structure outlined in the corresponding JSON schema (sim_config.json), providing an intuitive and structured way to organize simulation parameters.

Configuration Parameters#

The configuration is composed of multiple groups of parameters, each represented by a Python dataclass and organized into the following sections:

version: str
- The version of the simulation configuration file.
length_unit: str
- Unit for length in the simulation (e.g., nm, um, mm).
space_unit: str
- Unit for space in the simulation (e.g., pixel).
time_unit: str
- Unit for time in the simulation (e.g., s, ms, us).
intensity_unit: str
- Unit for intensity in the simulation (AUD only supported).
diffusion_unit: str
- Unit for diffusion in the simulation (e.g., um²/s, mm²/s).

Cell Parameters#

`cell_type`#

Type: Union[str, CellType]
Description: Defines the type of the cell to simulate.
Supported: RectangularCell, SphericalCell, OvoidCell, RodCell, BuddingCell

`params`#

Type: dictionary of parameter names (String) and values (Any)
Description: Values for the cell_type specified above. The following the general structure:

# SphericalCell
params = {
    "center": [0, 0, 0],   # 3D center coordinates
    "radius": 10.0         # Radius of sphere
}

# RodCell
params = {
    "center": [0, 0, 0],       # 3D center coordinates
    "direction": [0, 0, 1],    # Direction vector (will be normalized)
    "height": 20.0,            # Length of the rod
    "radius": 5.0              # Radius of the rod
}

# RectangularCell
params = {
    "bounds": [-10, 10, -10, 10, -10, 10]  # [xmin, xmax, ymin, ymax, zmin, zmax]
}

# OvoidCell
params = {
    "center": [0, 0, 0],       # 3D center coordinates
    "xradius": 10.0,           # Radius in x-direction
    "yradius": 15.0,           # Radius in y-direction
    "zradius": 20.0            # Radius in z-direction
}

number_of_cells: int
- Number of cells to simulate.

Track Parameters#

num_tracks: int
- Number of tracks to simulate.
track_type: str
- Type of track to simulate (e.g., "fbm" for fractional Brownian motion).
track_length_mean: int
- Mean length of the track (in frames).
track_distribution: str
- Distribution type for track lengths (e.g., "exponential", "constant").
diffusion_coefficient: List[float]
- List of diffusion coefficients (in units of diffusion_unit).
diffusion_track_amount: List[float]
- Probabilities for each diffusion coefficient (must sum to 1.0).
hurst_exponent: List[float]
- List of Hurst exponents, defining the track behavior.
hurst_track_amount: List[float]
- Probabilities for each Hurst exponent (must sum to 1.0).
allow_transition_probability: bool
- Whether to allow transitions between different diffusion coefficients and Hurst exponents.
transition_matrix_time_step: int
- Time step for the transition matrices (in time_unit).
diffusion_transition_matrix: List[List[float]]
- Transition matrix for different diffusion coefficients (rows must sum to 1.0).
hurst_transition_matrix: List[List[float]]
- Transition matrix for different Hurst exponents (rows must sum to 1.0).
state_probability_diffusion: List[float]
- Initial probabilities for each diffusion coefficient state.
state_probability_hurst: List[float]
- Initial probabilities for each Hurst exponent state.

Global Parameters#

field_of_view_dim: List[float]
- Field of view dimensions in pixels.
frame_count: int
- Total number of frames in the simulation.
exposure_time: float
- Exposure time of the camera (in time_unit).
interval_time: float
- Time between frames when the camera is on (in time_unit).
oversample_motion_time: float
- Time for oversampling motion to simulate motion blur.
- If equal to frame_time and exposure_time, there is no motion blur.
pixel_size: float
- Size of each pixel (in length_unit).
axial_detection_range: float
- Range for detecting molecule excitation in the z-direction (in length_unit).
base_noise: float
- Base noise of the camera (in intensity_unit).
point_intensity: float
- Intensity of a single molecule excitation (in intensity_unit).
psf_sigma: float
- Point Spread Function (PSF) sigma (in length_unit).
axial_function: str
- Function for intensity change with z (e.g., "exponential", "ones" for no effect).

Condensate Parameters#

initial_centers: List[List[float]]
- Initial centers of the condensates, with [x, y, z] coordinates per row.
initial_scale: List[float]
- Initial radius of each condensate (in space_unit).
diffusion_coefficient: List[float]
- Diffusion coefficients for each condensate (in diffusion_unit).
hurst_exponent: List[float]
- Hurst exponents for each condensate.
density_dif: float
- Density difference between the condensates and the rest of the cell.

Output Parameters#

output_path: str
- Path to the directory where the output will be saved.
output_name: str
- Name of the output file.
subsegment_type: str
- Function for projecting data across subsegments (e.g., "mean", "max", "sum").
subsegment_number: int
- Number of subsegments to divide the simulation frames into. The total number of frames must be divisible by the subsegment number.

Dataclasses#

This module defines Python dataclasses to represent each section of the simulation configuration. The dataclasses allow for structured data management, type-checking, and easy manipulation of simulation parameters.

CellParameters:
- Stores the cell space, axial radius, and number of cells.
TrackParameters:
- Stores track-related parameters such as number of tracks, track length, diffusion coefficients, and Hurst exponents.
GlobalParameters:
- Stores global simulation settings such as field of view, frame count, and camera parameters.
CondensateParameters:
- Stores parameters related to condensates, including their initial centers, scales, and diffusion coefficients.
OutputParameters:
- Stores output-related settings such as file path, file name, and subsegment configurations.
SimulationConfig:
- The main class that contains all the parameters for the simulation. Inherits from a base class to facilitate conversion of lists to NumPy arrays for efficient mathematical operations.

`ABCConfig` `dataclass` #

Source code in SMS_BP/config_schema.py

@dataclass
class ABCConfig:
    def make_array(self):
        """
        Recursively converts all list attributes to numpy arrays, including nested dataclasses.
        """

        def _convert(obj: Any):
            if isinstance(obj, list):
                return np.array(obj)
            elif is_dataclass(obj):
                # Traverse nested dataclass
                for field in fields(obj):
                    value = getattr(obj, field.name)
                    setattr(obj, field.name, _convert(value))
            return obj

        # Apply conversion to the main dataclass
        for field in fields(self):
            value = getattr(self, field.name)
            setattr(self, field.name, _convert(value))

`make_array()` #

Recursively converts all list attributes to numpy arrays, including nested dataclasses.