FlowCytometer

Classes related to the overall configuration of a flow cytometry system.

class FlowCytometer(**kwargs)

Bases: object

A simulation class for modeling flow cytometer signals, including Forward Scatter (FSC) and Side Scatter (SSC) channels.

The FlowCytometer class integrates optical and flow dynamics to simulate signal generation in a flow cytometer. It handles particle distributions, flow cell properties, laser source configurations, and detector behavior to replicate realistic cytometry conditions. This includes the generation of synthetic signal pulses for each particle event and noise modeling for accurate signal representation.

Parameters:

• opto_electronics (OptoElectronics) – An instance of the OptoElectronics class, which contains the configuration of detectors, digitizer, source, and amplifier.

• fluidics (Fluidics) – An instance of the Fluidics class, which manages the flow cell and scatterer collection.

• signal_processing (SignalProcessing) – An instance of the SignalProcessing class, which handles the processing of analog and digital signals.

• background_power (pint.Quantity, optional) – The background power level in the system, defaulting to 0 mW. This represents the constant background signal that is present in the system, which can affect the detection of actual signals.

Raises:

AssertionError – If the number of detectors provided is not exactly two, or if both detectors share the same name.

compute_analog(run_time, event_collection)

Simulates the complete analog optical response generated by all detected particle events.

This function builds the full analog waveform that emerges from the optical and opto electronic chain of the cytometer. It proceeds in three major stages:

1. Optical domain - Creates an optical power time series for each detector - For explicit sampling models, generates Gaussian shaped pulses directly - For gamma models, draws a gamma distributed power trace that matches the

expected total particle contribution and optionally smooths it with a Gaussian convolution

• Adds the constant background optical power

2. Conversion to photocurrent - Converts optical power to photocurrent using the detector responsivity

and the illumination wavelength

• Applies bandwidth dependent effects from the digitizer

3. Current domain to voltage domain - Adds optional dark current noise when enabled in simulation settings - Passes all photocurrents through the analog amplifier model - Applies final analog conditioning and filtering steps

The output is returned as an AcquisitionDataFrame, which contains voltage waveforms for all detectors on a shared time base, formatted with a clear multi level index.

Parameters:

• run_time (Time) – Total simulated duration of the acquisition

• event_collection (pandas.DataFrame) – Collection of detected particle events, where each entry contains the event time, width, amplitude, velocity, and sampling method

Returns:

Structured representation of the final analog voltage signals for all detectors, including the time axis and processed analog waveforms

Return type:

AcquisitionDataFrame

Raises:

ValueError – If required event fields are missing, including Sigmas or Time for explicit pulse generation

generate_event_collection(**kwargs)

run(run_time)

Runs a complete flow cytometry simulation for the specified acquisition duration.

The pipeline includes: 1. Initialization and setup of fluidic/optical components 2. Particle event simulation and optical signal generation 3. Analog and digital signal processing 4. Triggered signal extraction and peak feature detection

Parameters:

• run_time (Time) – Duration of the simulated acquisition (e.g., 1.0 * ureg.millisecond).

• compute_cross_section (bool, optional) – Whether to compute the scattering cross-section for each event. Default is False.

Returns:

Simulation output containing all analog, digital, and peak-level data.

Return type:

RunRecord

run_explicit_models(event_collection, signal_generator)

Run all ExplicitModel populations and add their optical power pulses to the signal generator.

For each population event frame using ExplicitModel, this method generates Gaussian shaped pulses directly in the optical power domain for every detector, using: - events[“Time”] as pulse centers - events[“Sigmas”] as pulse widths - events[detector.name] as pulse amplitudes

Notes

Assumes all required columns exist and carry Pint units. Skips populations whose event frame is empty.

Return type:

None

run_gamma_models(event_collection, signal_generator)

Run all GammaModel populations and add correlated optical power traces to the signal generator.

For each GammaModel population, this method produces a single shared stochastic latent trace and applies detector specific scaling so that all detector signals are perfectly correlated in time and differ only by amplitude.

Implementation

• Use the first detector as a reference to draw one gamma distributed power trace via the

C++ backend (this sets the temporal stochasticity). - Convert that reference trace into a dimensionless latent particle trace by dividing by the reference mean amplitude. - For each other detector, scale the latent trace by its mean amplitude and add it to the corresponding detector signal.

Notes

Skips populations whose event frame is empty. Assumes: - events.population.concentration exists - events.attrs[“VelocitySigmas”] exists (Pint Quantity) - signal_generator._cpp_add_gamma_trace writes into the named signal and returns the trace - signal_generator.add_array_to_signal exists (as in your SignalGenerator wrapper)

Return type:

None