cleo.light module

class cleo.light.GaussianEllipsoid(sigma_axial: Quantity = 18. * umetre, sigma_lateral: Quantity = 8. * umetre)

Bases: LightModel

Method generated by attrs for class GaussianEllipsoid.

sigma_axial: Quantity

Standard deviation distance along the focal axis.

Standard deviations estimated by taking point where response is ~60% of peak:

Publication	axial	lateral	measure
Prakash et al., 2012	13 μm	7 μm	photocurrent
Rickgauer et al., 2014	8 μm	4 μm	Ca2+ dF/F response
Packer et al., 2015	18 μm	8 μm	AP probability
Chen et al., 2019	18/11 μm	8/? μm	AP probability/photocurrent

sigma_lateral: Quantity

Standard deviation distance along the focal plane.

transmittance(source_coords: Quantity, source_dir_uvec: NDArray[Any, 3, Any], target_coords: Quantity) → NDArray[Any, Any, Float]

Output must be between 0 and 1 with shape (n_sources, n_targets).

viz_params(coords: Quantity, direction: NDArray[Any, 3, Any], T_threshold: float, n_points_per_source: int = 4000, **kwargs) → Quantity

Returns info needed for visualization. Output is ((m, n_points_per_source, 3) viz_points array, markersize_um, intensity_scale).

For best-looking results, implementations should scale markersize_um and intensity_scale.

class cleo.light.Koehler(radius: Quantity, zmax: Quantity = 0.5 * mmetre)

Bases: LightModel

Even illumination over a circular area, with no scattering.

Method generated by attrs for class Koehler.

radius: Quantity

The radius of the Köhler beam

transmittance(source_coords, source_dir_uvec, target_coords)

Output must be between 0 and 1 with shape (n_sources, n_targets).

viz_params(coords, direction, T_threshold, n_points_per_source=4000, **kwargs)

Returns info needed for visualization. Output is ((m, n_points_per_source, 3) viz_points array, markersize_um, intensity_scale).

For best-looking results, implementations should scale markersize_um and intensity_scale.

zmax: Quantity

The maximum extent of the Köhler beam, 500 μm by default (i.e., no thicker than necessary to go through a slice or culture).

class cleo.light.Light(coords=array([0., 0., 0.]) * metre, direction: Quantity = (0, 0, 1), *, name: str = _Nothing.NOTHING, save_history: bool = True, light_model: LightModel, wavelength: Quantity = 0.473 * umetre, max_Irr0_mW_per_mm2: float = None, max_Irr0_mW_per_mm2_viz: float = None, default_value: NDArray[Any, Float] = _Nothing.NOTHING)

Bases: Stimulator

Delivers light to the network for photostimulation and (when implemented) imaging.

Requires neurons to have 3D spatial coordinates already assigned.

Visualization kwargs:

• n_points_per_source (int, optional) – The number of points per light source used to represent light intensity in space. Default varies by light_model. Alias n_points.

• T_threshold (float, optional) – The transmittance below which no points are plotted. By default 1e-3.

• intensity (float, optional) – How bright the light appears, should be between 0 and 1. By default 0.5.

• rasterized (bool, optional) – Whether to render as rasterized in vector output, True by default. Useful since so many points makes later rendering and editing slow.

Method generated by attrs for class Light.

add_self_to_plot(ax, axis_scale_unit, **kwargs) → list[PathCollection]

Add device to an existing plot

Should only be called by plot().

Parameters:

• ax (Axes3D) – The existing matplotlib Axes object

• axis_scale_unit (Unit) – The unit used to label axes and define chart limits

• **kwargs (optional) –

Returns:

A list of artists used to render the device. Needed for use in conjunction with VideoVisualizer.

Return type:

list[Artist]

property color

Color of light

connect_to_neuron_group(neuron_group: NeuronGroup, **kwparams: Any) → None

Connect device to given neuron_group.

If your device introduces any objects which Brian must keep track of, such as a NeuronGroup, Synapses, or Monitor, make sure to add these to brian_objects.

Parameters:

• neuron_group (NeuronGroup) –

• **kwparams (optional) – Passed from inject

coords: Quantity

(x, y, z) coords with Brian unit specifying where to place the base of the light source, by default (0, 0, 0)*mm. Can also be an nx3 array for multiple sources.

default_value: NDArray[Any, Float]

The default value of the device—used on initialization and on reset()

direction: NDArray[Any, 3, Any]

(x, y, z) vector specifying direction in which light source is pointing, by default (0, 0, 1).

Will be converted to unit magnitude.

init_for_simulator(sim: CLSimulator) → None

Initialize device for simulator on initial injection.

This function is called only the first time a device is injected into a simulator and performs any operations that are independent of the individual neuron groups it is connected to.

Parameters:

simulator (CLSimulator) – simulator being injected into

light_model: LightModel

Defines how light is emitted. See OpticFiber for an example.

max_Irr0_mW_per_mm2: float

The maximum irradiance the light source can emit.

Usually determined by hardware in a real experiment.

max_Irr0_mW_per_mm2_viz: float

Maximum irradiance for visualization purposes.

i.e., the level at or above which the light appears maximally bright. Only relevant in video visualization.

property n

Number of light sources

property source: Subgroup

Returns the “neuron(s)” representing the light source(s).

to_neo()

Return a Neo signal object with the device’s data

Returns:

Neo object representing exported data

Return type:

neo.core.BaseNeo

transmittance(target_coords) → ndarray

Returns light_model transmittance given light’s coords and direction.

update(value: float | ndarray) → None

Set the light intensity, in mW/mm2 (without unit) for 1P excitation or laser power (mW) for 2P excitation (GaussianEllipsoid light model).

Parameters:

Irr0_mW_per_mm2 (float) – Desired light intensity for light source

update_artists(artists: list[Artist], value, *args, **kwargs) → list[Artist]

Update the artists used to render the device

Used to set the artists’ state at every frame of a video visualization. The current state would be passed in *args or **kwargs

Parameters:

artists (list[Artist]) – the artists used to render the device originally, i.e., which were returned from the first add_self_to_plot() call.

Returns:

The artists that were actually updated. Needed for efficient blit rendering, where only updated artists are re-rendered.

Return type:

list[Artist]

wavelength: Quantity

light wavelength with unit (usually nmeter)

class cleo.light.LightDependent(spectrum: list[tuple[float, float]] = _Nothing.NOTHING, spectrum_interpolator: ~typing.Callable = <function cubic_interpolator>)

Bases: object

Mix-in class for opsin and light-dependent indicator. Light-dependent devices are connected to light sources (and vice-versa) on injection via the registry.

We approximate dynamics under multiple wavelengths using a weighted sum of photon fluxes, where the ε factor indicates the activation relative to the peak-sensitivity wavelength for a equivalent power, which most papers report. When they report the action spectrum for equivalent photon flux instead (see Mager et al, 2018), use equal_photon_flux_spectrum(). This weighted sum is an approximation of a nonlinear peak-non-peak wavelength relation; see notebooks/multi_wavelength_model.ipynb for details.

Method generated by attrs for class LightDependent.

epsilon(lambda_new) → float

Returns the \(\varepsilon\) value for a given lambda (in nm) representing the relative sensitivity of the opsin to that wavelength.

property light_agg_ngs

spectrum: list[tuple[float, float]]

List of (wavelength, epsilon) tuples representing the action (opsin) or excitation (indicator) spectrum.

spectrum_interpolator: Callable

Function of signature (lambdas_nm, epsilons, lambda_new_nm) that interpolates the action spectrum data and returns \(\varepsilon \in [0,1]\) for the new wavelength.

class cleo.light.LightModel

Bases: ABC

Defines how light propagates given a source location and direction.

Method generated by attrs for class LightModel.

abstract transmittance(source_coords: Quantity, source_direction: NDArray[Any, 3, Any], target_coords: Quantity) → NDArray[Any, Any, Float]

Output must be between 0 and 1 with shape (n_sources, n_targets).

abstract viz_params(coords: Quantity, direction: NDArray[Any, 3, Any], T_threshold: float, n_points_per_source: int = None, **kwargs) → tuple[NDArray[Any, Any, 3, Any], float, float]

Returns info needed for visualization. Output is ((m, n_points_per_source, 3) viz_points array, markersize_um, intensity_scale).

For best-looking results, implementations should scale markersize_um and intensity_scale.

class cleo.light.OpticFiber(R0: Quantity = 100. * umetre, NAfib: float = 0.37, K: Quantity = 125. * metre**-1, S: Quantity = 7370. * metre**-1, ntis: float = 1.36)

Bases: LightModel

Optic fiber light model from Foutz et al., 2012.

Defaults are from paper for 473 nm wavelength.

Method generated by attrs for class OpticFiber.

K: Quantity

absorbance coefficient (wavelength/tissue dependent)

NAfib: float

optical fiber numerical aperture

R0: Quantity

optical fiber radius

S: Quantity

scattering coefficient (wavelength/tissue dependent)

ntis: float

tissue index of refraction (wavelength/tissue dependent)

transmittance(source_coords: Quantity, source_dir_uvec: NDArray[Any, 3, Any], target_coords: Quantity) → NDArray[Any, Any, Float]

Output must be between 0 and 1 with shape (n_sources, n_targets).

viz_params(coords: Quantity, direction: NDArray[Any, 3, Any], T_threshold: float, n_points_per_source: int = 4000, **kwargs) → Quantity

Returns info needed for visualization. Output is ((m, n_points_per_source, 3) viz_points array, markersize_um, intensity_scale).

For best-looking results, implementations should scale markersize_um and intensity_scale.

cleo.light.cubic_interpolator(lambdas_nm, epsilons, lambda_new_nm)

cleo.light.equal_photon_flux_spectrum(spectrum: list[tuple[float, float]]) → list[tuple[float, float]]

Converts an equival photon flux spectrum to an equal power density spectrum.

cleo.light.fiber473nm(R0=100. * umetre, NAfib=0.37, K=125. * metre**-1, S=7370. * metre**-1, ntis=1.36) → OpticFiber

Returns an OpticFiber model with parameters for 473 nm light.

Parameters from Foutz et al., 2012.

cleo.light.linear_interpolator(lambdas_nm, epsilons, lambda_new_nm)

cleo.light.plot_spectra(*ldds: LightDependent) → tuple[plt.Figure, plt.Axes]

Plots the action/excitation spectra for multiple light-dependent devices.

cleo.light.tp_light_from_scope(scope, wavelength=1.06 * umetre, **kwargs) → Light

Creates a light object from a scope object with 2P focused laser points at each target.

Parameters:

• scope (Scope) – The scope object containing the laser spots.

• wavelength (Quantity, optional) – The wavelength of the laser, by default 1060 * nmeter.