Scatterers#

Classes representing particles and populations within the cytometer.

class ScattererCollection(medium_refractive_index=<Quantity(1.0, 'refractive_index_unit')>, populations=None, coupling_model=CouplingModel.MIE)[source]#

Bases: object

Defines and manages the diameter and refractive index distributions of scatterers (particles) passing through a flow cytometer. This class generates random scatterer diameters and refractive indices based on a list of provided distributions (e.g., Normal, LogNormal, Uniform, etc.).

Parameters:

medium_refractive_index (Quantity)
populations (List[BasePopulation])
coupling_model (CouplingModel | None)

add_population(*population)[source]#

Adds a population to the ScattererCollection instance with the specified attributes.

Parameters:

name (str) – The name of the population.
diameter (BaseDistribution) – The diameter distribution of the population.
refractive_index (BaseDistribution) – The refractive index distribution of the population.
population (BasePopulation)

Returns:

The ScattererCollection instance (to support chaining).

Return type:

ScattererCollection

Raises:

ValueError – If the concentration does not have the expected dimensionality.

property concentrations: List[Quantity]#

Gets the concentration of each population in the ScattererCollection instance.

Returns:: A list of concentrations for each population.
Return type:: List[Quantity]

dilute(factor)[source]#

Dilutes the populations in the flow cytometry system by a given factor.

Parameters:: factor (float) – The dilution factor to apply to each population. For example, a factor of 0.5 reduces the population density by half.
Returns:: The method modifies the populations in place.
Return type:: None

Notes

This method iterates over all populations in the system and applies the dilute method of each population.
The specific implementation of how a population is diluted depends on the dilute method defined in the population object.

Examples

Dilute all populations by 50%: >>> system.dilute(0.5)

fill_dataframe_with_sampling(scatterer_dataframe)[source]#

Fills a DataFrame with diameter and refractive index sampling data for each population.

Parameters:

scatterer_dataframe (pd.DataFrame) – A DataFrame indexed by population names (first level) and containing the following columns: ‘Diameter’: To be filled with particle diameter data. ‘RefractiveIndex’: To be filled with refractive index data. The DataFrame must already have the required structure.

Returns:

None – The method modifies the scatterer_dataframe in place, adding diameter and refractive index sampling data.
After filling, the DataFrame will be populated with diameter and refractive index data.

Return type:

None

get_population_dataframe(total_sampling=200, use_ratio=True)[source]#

Generate a DataFrame by sampling particles from populations.

Parameters:

total_sampling (Quantity, optional) – Total number of samples to draw, distributed across populations based on their ratios.
use_ratio (bool)

Returns:

A MultiIndex DataFrame containing the sampled data from all populations. The first index level indicates the population name, and the second level indexes the sampled data.

Return type:

pd.DataFrame

get_population_ratios()[source]#

Return type:: list[float]

set_concentrations(values)[source]#

Sets the concentration of each population in the ScattererCollection instance.

Parameters:: values (Union[List[Quantity], Quantity]) – A list of concentrations to set for each population, or a single concentration value to set for all populations.
Raises:: ValueError – If the length of the values list does not match the number of populations or if any concentration has an incorrect dimensionality.
Return type:: None

class Sphere(name, refractive_index, diameter, particle_count)[source]#

Bases: BasePopulation

Represents a population of scatterers (particles) in a flow cytometry setup.

This class encapsulates the properties of a particle population including its name, refractive index, particle diameter, and particle count (density). The refractive index and diameter can be provided as either fixed values (Quantity) or as statistical distributions (instances of distribution.Base). The class automatically converts Quantity attributes to their base SI units during initialization.

Parameters:

name (str) – The identifier or label for the population.
refractive_index (Union[distribution.Base, Quantity]) – The refractive index (or its distribution) of the particles. If provided as a Quantity, it must have units of refractive index (RIU). If provided as a distribution, it should be an instance of distribution.Base.
diameter (Union[distribution.Base, Quantity]) – The particle diameter (or its distribution). If provided as a Quantity, it must have units of length (e.g., meters). If provided as a distribution, it should be an instance of distribution.Base.
particle_count (ParticleCount | Quantity) – The number density of particles (scatterers) per cubic meter. If a Quantity is provided, it should be convertible to a ParticleCount.

diameter: Base | Quantity#

generate_property_sampling(sampling)[source]#

Generate a sampling of particle properties.

This method uses the underlying distributions (or fixed quantities) for diameter and refractive index to generate a sample set for simulation or analysis.

This method creates a dictionnary with the following entries:

‘Diameter’: The generated diameters.
‘RefractiveIndex’: The generated refractive index values.

Parameters:: sampling (int) – The sampling parameter (e.g., number of samples or a resolution quantity) used by the distributions.
Returns:: A tuple containing the generated diameter sample and refractive index sample.
Return type:: tuple

particle_count: ParticleCount | Quantity#

class CoreShell(name, core_diameter, shell_thickness, core_refractive_index, shell_refractive_index, particle_count)[source]#

Bases: BasePopulation

Represents a population of core-shell scatterers in a flow cytometry setup.

In a core-shell particle, the inner core is defined by its diameter and the outer shell is defined by its thickness. The overall particle diameter is given by:

overall_diameter = core_diameter + 2 * shell_thickness

The refractive indices for the core and shell can be provided either as fixed values (Quantity) or as statistical distributions (instances of distribution.Base). The particle_count defines the scatterer density in particles per cubic meter.

Parameters:

name (str) – The identifier or label for the population.
core_diameter (Union[distribution.Base, Quantity]) – The diameter of the particle core. If provided as a Quantity, it must have length units (e.g., meter). If provided as a distribution, it must be an instance of distribution.Base.
shell_thickness (Union[distribution.Base, Quantity]) – The thickness of the particle shell. If provided as a Quantity, it must have length units. If provided as a distribution, it must be an instance of distribution.Base.
refractive_index_core (Union[distribution.Base, Quantity]) – The refractive index (or its distribution) of the core. If provided as a Quantity, it must have refractive index units (RIU).
refractive_index_shell (Union[distribution.Base, Quantity]) – The refractive index (or its distribution) of the shell. If provided as a Quantity, it must have refractive index units (RIU).
particle_count (ParticleCount | Quantity) – The particle density in particles per cubic meter.
core_refractive_index (Base | Quantity)
shell_refractive_index (Base | Quantity)

core_diameter: Base | Quantity#

core_refractive_index: Base | Quantity#

generate_property_sampling(sampling)[source]#

Generate a sampling of core-shell particle properties.

This method generates a sample set for the core diameter, shell thickness, core refractive index, and shell refractive index from their underlying distributions (or fixed values).

This method creates a dictionnary with the following entries:

‘CoreDiameter’: The generated core diameters.
‘ShellThickness’: The generated shell thickness values.
‘CoreRefractiveIndex’: The generated core refractive indices.
‘ShellRefractiveIndex’: The generated shell refractive indices.

Parameters:: sampling (Quantity) – The sampling parameter used by the distributions.
Returns:: A tuple containing the generated samples in the order: (core_diameter, shell_thickness, refractive_index_core, refractive_index_shell).
Return type:: tuple

overall_diameter(sampling)[source]#

Generate the overall particle diameter.

This method calculates the overall particle diameter for a given sampling by generating the core diameter and shell thickness samples from their respective distributions. The overall diameter is computed as:

overall_diameter = core_diameter + 2 * shell_thickness

Parameters:: sampling (Quantity) – The sampling parameter used by the distributions to generate values.
Returns:: The overall diameter of the particles.
Return type:: Quantity

particle_count: ParticleCount | Quantity#

shell_refractive_index: Base | Quantity#

shell_thickness: Base | Quantity#