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.

property area0: Quantity

The area of the light source(s), used to convert between power and irradiance.

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: Float[ndarray, '*sources 3'], target_coords: Quantity) → Float[ndarray, '*sources targets']

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

viz_params(coords: Quantity, direction: Float[ndarray, '*sources 3'], T_threshold: float, n_points_per_source: int = 4000, **kwargs) → Quantity

Returns info needed for visualization. Output is ((*sources, n_points_per_source, 3) viz_points array, markersize, intensity_scale).

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

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

Bases: LightModel

Even illumination over a circular area, with no scattering.

Method generated by attrs for class KoehlerBeam.

property area0: Quantity

The area of the light source(s), used to convert between power and irradiance.

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 (*sources, n_targets).

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

Returns info needed for visualization. Output is ((*sources, n_points_per_source, 3) viz_points array, markersize, intensity_scale).

For best-looking results, implementations should scale markersize 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, save_history: bool = True, light_model: LightModel, wavelength: Quantity = 0.473 * umetre, max_value: Quantity = None, max_value_viz: Quantity = None)

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.

direction: Float[ndarray, '*sources 3']

(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

property irradiance: Quantity

Returns history of light irradiance with units.

property irradiance_: Quantity

Returns history of light irradiance without units (/(mwatt/mm2)).

light_model: LightModel

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

max_value: Quantity

The maximum value (power or irradiance) the light source can emit.

Usually determined by hardware in a real experiment.

max_value_viz: Quantity

Maximum value (power or 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 power: Quantity

Returns history of light power with units.

property power_: Quantity

Returns history of light power without units (/mwatt).

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: Quantity) → None

Set the light power or irradiance. The units of the input value determine which.

Parameters:

value (Quantity) – The light irradiance (mW/mm^2) or power (mW). If a scalar, it will be broadcast to all sources. If an array, it must be the same shape as the number of sources.

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, spectrum_interpolator: ~typing.Callable = <function log_pchip_interpolator>, extrapolate: bool = False)

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: Quantity) → float

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

extrapolate: bool

Whether or not to attempt to extrapolate (using spectrum_interpolator) outside of the provided excitation/action spectrum.

property light_agg_ngs: dict[str, NeuronGroup]

Returns the “neurons” that aggregate light for this device. Dict of form {target_ng.name: light_agg_ng}.

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 property area0: Quantity

The area of the light source(s), used to convert between power and irradiance.

abstract transmittance(source_coords: Quantity, source_direction: Float[ndarray, '*sources 3'], target_coords: Quantity) → Float[ndarray, '*sources n_targets']

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

abstract viz_params(coords: Quantity, direction: Float[ndarray, '*sources 3'], T_threshold: float, n_points_per_source: int = None, **kwargs) → tuple[Quantity, Quantity, float]

Returns info needed for visualization. Output is ((*sources, n_points_per_source, 3) viz_points array, markersize, intensity_scale).

For best-looking results, implementations should scale markersize 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)

property area0: Quantity

The area of the light source(s), used to convert between power and irradiance.

ntis: float

tissue index of refraction (wavelength/tissue dependent)

transmittance(source_coords: Quantity, source_dir_uvec: Float[ndarray, '*sources 3'], target_coords: Quantity) → Float[ndarray, '*sources n_targets']

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

viz_params(coords: Quantity, direction: Float[ndarray, '*sources 3'], T_threshold: float, n_points_per_source: int = 4000, **kwargs) → Quantity

Returns info needed for visualization. Output is ((*sources, n_points_per_source, 3) viz_points array, markersize, intensity_scale).

For best-looking results, implementations should scale markersize 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.log_linear_interpolator(lambdas_nm, epsilons, lambda_new_nm)

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

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

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

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

cleo.light.plot_spectra(*ldds: LightDependent, extrapolate: bool = False, range: str = '1p') → tuple[Figure, Axes]

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

Parameters:

• *ldds (LightDependent) – Device(s) to plot spectra for

• extrapolate (bool, optional) – Whether to plot extrapolated spectra, by default False

• range (str, optional) – “1p”, “2p”, or “1p2p”, indicating What wavelengths to plot, by default “1p”

Returns:

The Figure and Axes objects containing the plot

Return type:

tuple[plt.Figure, plt.Axes]

Raises:

ValueError – For an incorrect range

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.