Analysis

class ledsa.analysis.ExtinctionCoefficientsLinear.ExtinctionCoefficientsLinear(experiment, reference_property='sum_col_val', num_ref_imgs=10, average_images=False, lambda_reg=0.001)

Bases: ExtinctionCoefficients

ExtinctionCoefficientsLinear computes the extinction coefficients by linearizing the Beer–Lambert law. Specifically, using the transformation:

-ln(I_e / I_0) = sum_i (sigma_i * Delta s_{i})

the problem is recast as a linear least squares system that can be solved efficiently. A Tikhonov regularization is added via a finite-difference operator to enforce smoothness in the solution.

Variables:

solver (str) – Type of solver (linear or nonlinear).

calc_coefficients_of_img(rel_intensities: ndarray) → ndarray

Calculate the extinction coefficients for a single image using a linearized approach. This method solves the linear system derived from the Beer-Lambert law using non-negative least squares with Tikhonov regularization.

Parameters:

rel_intensities (np.ndarray) – Array of relative (normalized) LED intensities (I_e/I_0).

Returns:

Array of the computed extinction coefficients (sigmas).

Return type:

np.ndarray

class ledsa.analysis.ExtinctionCoefficientsNonLinear.ExtinctionCoefficientsNonLinear(experiment, reference_property='sum_col_val', num_ref_imgs=10, average_images=False, weighting_curvature=1e-06, weighting_preference=-0.006, num_iterations=200)

Bases: ExtinctionCoefficients

ExtinctionCoefficientsNonLinear computes the extinction coefficients by directly minimizing the difference between observed and predicted intensities using the Beer-Lambert law:

I_e = I_0 * exp(-sum_i (sigma_i * Delta s_{i}))

A numerical optimization approach is used with regularization terms to enforce smoothness in the solution.

Variables:

• bounds (list[tuple]) – Bounds for each layer.

• weighting_preference (float) – Weighting factor for the preference to push the numerical solver to high or low values for the extinction coefficients.

• weighting_curvature (float) – Weighting factor for the smoothness of the solution.

• num_iterations (int) – Maximum number of iterations of the numerical solver.

• solver – Type of solver (linear or nonlinear).

calc_coefficients_of_img(rel_intensities: ndarray) → ndarray

Calculate the extinction coefficients for a single image based on a minimization procedure.

Parameters:

rel_intensities – Array of relative (normalized) LED intensities (I_e/I_0).

Returns:

Array of the computed extinction coefficients (sigmas)

Return type:

np.ndarray

calc_intensities(sigmas: ndarray) → ndarray

Calculate the intensities from a given set of extinction coefficients. This implements the Beer-Lambert law and is called during the minimization of the cost function.

Parameters:

sigmas (np.ndarray) – An array of extinction coefficients (sigma values).

Returns:

An array of the calculated relative intensities (I_e/I_0).

Return type:

np.ndarray

cost_function(sigmas: ndarray, target: ndarray) → float

Calculate the cost based on the difference between the computed intensities and target intensities. The cost function aims to minimize the root mean square error (rmse) between the computed and target intensities, while also considering the smoothness of the solution (curvature) and boundaries of the coefficients (preference).

Parameters:

• sigmas (np.ndarray) – Extinction coefficients (sigma values).

• target (np.ndarray) – Target relative intensities (I_e/I_0).

Returns:

Computed cost.

Return type:

float

class ledsa.analysis.Experiment.Camera(pos_x: float, pos_y: float, pos_z: float)

Bases: object

Contains a camera’s position in 3D space.

Variables:

• pos_x (float) – The x-coordinate of the camera

• pos_y (float) – The y-coordinate of the camera

• pos_z (float) – The z-coordinate of the camera

pos_x: float

pos_y: float

pos_z: float

class ledsa.analysis.Experiment.Experiment(layers: Layers, led_array: int, camera: Camera, path=PosixPath('.'), channel=0, merge_led_arrays=False)

Bases: object

Represents an experimental setup involving layers, an LED array, and a camera.

Variables:

• layers (Layers) – The spatial layers involved in the experiment.

• led_array (int) – The identifier for the LED array.

• camera (Camera) – The camera involved in the experiment.

• leds (List[LED]) – List of LED light sources.

• led_number (int) – Number of LEDs on LED array.

• path (Path) – File path for experiment data.

• channel (int) – The camera channel to be analysed.

• merge_led_arrays (bool) – Whether to merge LED arrays.

calc_traversed_dist_in_plane(led: LED) → ndarray

Calculate the distance traversed by light from an LED in a plane to the camera.

Parameters:

led (LED) – The LED light source

Returns:

Array of distances traversed in each layer within the plane

Return type:

np.ndarray

calc_traversed_dist_per_layer(led: LED) → ndarray

Calculate the distance traversed by light from an LED through each layer to the camera.

Parameters:

led (LED) – The LED light source

Returns:

Array of distances traversed in each layer

Return type:

np.ndarray

calc_traversed_dist_per_layer_with_nonzero_alpha(alpha: float, led: LED) → ndarray

Calculate the distance traversed by light from an LED through each layer to the camera, taking into account a non-zero angle of incidence.

Parameters:

• alpha (float) – The angle of incidence

• led (LED) – The LED light source

Returns:

Array of distances traversed in each layer considering the angle

Return type:

np.ndarray

calc_traversed_height_in_layer(led_height: float, layer_bot: float, layer_top: float) → float

Calculate the vertical distance (height) traversed by light from an LED within a layer.

Parameters:

• led_height (float) – The z-coordinate of the LED

• layer_bot (float) – The z-coordinate of the bottom of the layer

• layer_top (float) – The z-coordinate of the top of the layer

Returns:

The vertical distance traversed within the layer

Return type:

float

distance_calculation_is_consistent(distance_per_layer: ndarray, led: LED, silent=True) → bool

Check if the computed distance values for each layer are consistent with the Euclidean distance.

Parameters:

• distance_per_layer (np.ndarray) – Array of distances traversed in each layer

• led (LED) – The LED light source

• silent (bool, optional) – If set to False, prints out debugging information, defaults to True

Returns:

True if computations are consistent, False otherwise

Return type:

bool

get_led_ids() → ndarray

Retrieve the IDs for the LEDs involved in the experiment.

Returns:

Array of LED IDs

Return type:

np.ndarray

get_led_positions(ids: ndarray) → List[ndarray]

Retrieve the 3D positions for a set of LEDs.

Parameters:

ids (np.ndarray) – Array of LED identifiers

Returns:

List of arrays containing x, y, and z coordinates for each LED

Return type:

List[np.ndarray]

set_leds() → None

Initialize the LED instances involved in the experiment based on loaded data.

class ledsa.analysis.Experiment.LED(id: int, pos_x: float, pos_y: float, pos_z: float)

Bases: object

Represents a LED light source in 3D space.

Variables:

• id (int) – The identifier for the LED

• pos_x (float) – The x-coordinate of the LED

• pos_y (float) – The y-coordinate of the LED

• pos_z (float) – The z-coordinate of the LED

id: int

pos_x: float

pos_y: float

pos_z: float

class ledsa.analysis.Experiment.Layer(bottom_border: float, top_border: float)

Bases: object

Represents a spatial layer with a bottom and top border.

Variables:

• bottom_border (float) – The z-coordinate of the bottom border of the layer

• top_border (float) – The z-coordinate of the top border of the layer

bottom_border: float

top_border: float

class ledsa.analysis.Experiment.Layers(amount: int, bottom_border: float, top_border: float)

Bases: object

Represents a collection of spatial layers.

Variables:

• amount (int) – The number of layers

• bottom_border (float) – The z-coordinate of the bottom-most border of the layers

• top_border (float) – The z-coordinate of the top-most border of the layers

amount: int

borders: ndarray

bottom_border: float

layers: [<class 'ledsa.analysis.Experiment.Layer'>]

top_border: float