Experiment module¶

This module stores classes and functions for handling experiment data in .nd2 file.

Experiments in .nd2 files define how image sequences are organized and looped. The most common types of loops include:

Time Loop (timeloop): A sequence of images captured over time.
Z-Stack (zstack): Frames stacked along the z-axis, representing different focal planes.
Multi-Point (multipoint): Images captured at multiple specified locations (points) with known coordinates.

An image can have no experiment, a single experiment, or a combination of multiple experiments.

This experiment data is stored in the ExperimentLevel class, you can get instance of this class by getting experiment peoperty of Nd2Reader object.

ExperimentLoopType ¶

Enum specifying which experiment type was used in ExperimentLevel

ATTRIBUTE	DESCRIPTION
`eEtTimeLoop`	Timeloop experiment (see `ExperimentTimeLoop`) TYPE: `int`
`eEtNETimeLoop`	Non-equidistant timeloop experiment (see `ExperimentNETimeLoop`) TYPE: `int`
`eEtXYPosLoop`	Multipoint experiment (see `ExperimentXYPosLoop`) TYPE: `int`
`eEtZStackLoop`	Z-stack experiment (see `ExperimentZStackLoop`) TYPE: `int`
`eEtSpectLoop`	Spectral experiment (see `ExperimentSpectralLoop`) TYPE: `int`

toLongName `staticmethod` ¶

toLongName(eType: ExperimentLoopType | int)

Returns long name for experiment type.

toShortName `staticmethod` ¶

toShortName(eType: ExperimentLoopType | int)

Returns short name for experiment type.

ExperimentLevel `dataclass` ¶

ExperimentLevel()

This class stores information about experiments used in an image, this class stores information about one experiment level directly and it may contain nested experiments (similar to linked list data structure).

This nesting of experimtents is used to define the order of experiments in the image.

To iterate over all experiments in the image, iterate over this class instance in for loop like this:

for exp in experiment:
    print(exp.name)
    print(exp.count)
    # another experiment specific instructions

Each experiment level has a type, which is defined by ExperimentLoopType enum stored in eType attribute, this type defines which experiment parameters are used in given level, those parameters are stored in uLoopPars attribute.

In order to get experiment of specific type, use findLevel method with an instance of ExperimentLoopType enum as argument.

This will allow you to get attributes for specific experiment type, for example, to get z-stack loop experiment attributes, use this code:

zstack = experiment.findLevel(limnd2.ExperimentLoopType.eEtZStackLoop)

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
`eType`	Experiment type used in the image, also defines which parameters are used in this level. TYPE: `ExperimentLoopType`
`uLoopPars`	Parameters of the current level loop, the structure depends on the content of `eType` member variable. TYPE: `ExperimentLoop`
`ppNextLevelEx`	List of nested ExperimentLevel instances. TYPE: `list[ExperimentLevel]`
`uiNextLevelCount`	Number of nested experiments. TYPE: `int`

count `property` ¶

count: int

Returns number of frames in the experiment.

dims `property` ¶

dims: dict[str, int]

Returns a dictionary mapping each experiment to number of frames in that experiment.

isLambda `property` ¶

isLambda: bool

Checks if this experiment loop is a spectral loop.

isMultipoint `property` ¶

isMultipoint: bool

Checks if this experiment loop is a Multi point

isTimeLapse `property` ¶

isTimeLapse: bool

Checks if this experiment loop is a Time lapse

isZStack `property` ¶

isZStack: bool

Checks if this experiment loop is a Z-Stack

name `property` ¶

name: str

Returns name of the experiment.

shortName `property` ¶

shortName: str

Returns short name of the experiment.

typeName `property` ¶

typeName: str

Returns type name of the experiment.

valid `property` ¶

valid: bool

Checks if experiment and all sub-experiments are valid.

dimnames ¶

dimnames(*, skipSpectralLoop: bool = True) -> tuple[str, ...]

Returns names of nested dimensions.

findLevel ¶

findLevel(loopType: ExperimentLoopType) -> ExperimentLevel | None

Find and returns experiment of specified type or None.

generateLoopIndexes ¶

generateLoopIndexes(*, named: Literal[True]) -> list[dict[str, int]]

generateLoopIndexes(*, named: Literal[False] = ...) -> list[tuple[int, ...]]

generateLoopIndexes(*, named: bool) -> list[tuple[int, ...]] | list[dict[str, int]]

generateLoopIndexes(*, named: bool = False) -> list[tuple[int, ...]] | list[dict[str, int]]

Generate list of indexes for all experiments in the image.

indexOfLoop ¶

indexOfLoop(loopType: ExperimentLoopType, *, skipSpectralLoop: bool = True) -> int | None

Returns index of specified loop type or None.

loopTypes ¶

loopTypes(*, skipSpectralLoop: bool = True) -> tuple[ExperimentLoopType, ...]

Returns tuple with ExperimentLoopType instances of all experiments in the image.

ndim ¶

ndim(skipSpectralLoop: bool = True) -> int

Returns number of experiments in the experiment level.

shape ¶

shape(*, skipSpectralLoop: bool = True) -> tuple[int, ...]

Returns shape of the experiment. (number of frames in each experiment)

ExperimentTimeLoop `dataclass` ¶

ExperimentTimeLoop(*, dStart: float = LV_field(0, DOUBLE), dPeriod: float = LV_field(0, DOUBLE), dDuration: float = LV_field(0, DOUBLE), dMinPeriodDiff: float = LV_field(0, DOUBLE), dMaxPeriodDiff: float = LV_field(0, DOUBLE), dAvgPeriodDiff: float = LV_field(0, DOUBLE), wsPhaseName: str = LV_field('', STRING), sAutoFocusBeforePeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), sAutoFocusBeforeCapture: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), uiLoopType: ExperimentType = LV_field(eEtDefault, UINT32), uiGroup: int = LV_field(0, UINT32), uiStimulationCount: int = LV_field(0, UINT32), bDurationPref: bool = LV_field(None, BOOL), pIncubationData: bytes = LV_field(b'', UNKNOWN), uiIncubationDataSize: int = LV_field(0, UNKNOWN), wsInterfaceName: str = LV_field('', STRING), uiTreatment: int = LV_field(0, UINT32), dIncubationDuration: float = LV_field(-1.0, DOUBLE))

Dataclass storing parameters about timeloop experiment in the image.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
`uiCount`	Number of frames in the experiment TYPE: `int`
`dStart`	Start time of the experiment TYPE: `float`
`dPeriod`	Time interval between frames in miliseconds. TYPE: `float`
`dDuration`	Duration of the experiment in miliseconds. If value is non-zero, dPeriod must be zero and the experiment is captured as fast as possible for dDuration ms. TYPE: `float`
`dMinPeriodDiff`	Minimum difference between periods. TYPE: `float`
`dMaxPeriodDiff`	Maximum difference between periods. TYPE: `float`
`dAvgPeriodDiff`	Average difference between periods. TYPE: `float`

formattedDuration `property` ¶

formattedDuration: str

Returns formatted duration of the experiment.

formattedInterval `property` ¶

formattedInterval: str

Returns formatted time interval between frames.

info `property` ¶

info: list[dict[str, Any]]

Returns information about timeloop experiment.

ExperimentNETimeLoop `dataclass` ¶

ExperimentNETimeLoop(*, uiPeriodCount: int = LV_field(0, UINT32), pPeriod: list[ExperimentTimeLoop] = LV_field(list, LEVEL), pSubLoops: dict | None = LV_field(None, ENCODING_NOT_IMPLEMENTED), sAutoFocusBeforePeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), sAutoFocusBeforeCapture: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), wsCommandBeforePeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), wsCommandAfterPeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), szCommandBeforePeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), szCommandAfterPeriod: dict = LV_field(dict, ENCODING_NOT_IMPLEMENTED), pPeriodValid: bytes = LV_field(bytes, BYTEARRAY))

Dataclass for storing parameters about nonequidistant time loop experiment. This is done by storing a list of ExperimentTimeLoop instances (each one is called a period).

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
`uiCount`	Number of frames in the experiment (total from frames in all periods) TYPE: `int`
`uiPeriodCount`	Number of periods in the experiment TYPE: `int`
`pPeriod`	List of periods in the nonequidistant time loop experiment TYPE: `list[ExperimentTimeLoop]`

info `property` ¶

info: list[dict[str, Any]]

Returns information about nonequidistant time loop experiment.

ExperimentXYPosLoopPoint `dataclass` ¶

ExperimentXYPosLoopPoint(*, dPosX: float = LV_field(0.0, DOUBLE), dPosY: float = LV_field(0.0, DOUBLE), dPosZ: float = LV_field(0.0, DOUBLE), dPFSOffset: float = LV_field(0.0, DOUBLE), dPosName: str = LV_field('', STRING))

Dataclass for storing infomartion about a single point in multipoint experiment.

ATTRIBUTE	DESCRIPTION
`dPosX`	The X-coordinate of the position. TYPE: `float`
`dPosY`	The Y-coordinate of the position. TYPE: `float`
`dPosZ`	The Z-coordinate of the position. TYPE: `float`
`dPFSOffset`	The offset applied for Perfect Focus System (PFS). TYPE: `float`
`dPosName`	A descriptive name for the position. TYPE: `str`

ExperimentXYPosLoop `dataclass` ¶

ExperimentXYPosLoop()

Dataclass for storing parameters about multipoint experiment in the image.

ATTRIBUTE	DESCRIPTION
`bUseZ`	Whether Z-axis positions are used in the experiment. TYPE: `bool`
`bRelativeXY`	Whether XY coordinates are defined relative to a reference point. TYPE: `bool`
`dReferenceX`	The X-coordinate of the reference point. TYPE: `float`
`dReferenceY`	The Y-coordinate of the reference point. TYPE: `float`
`bRedefineAfterPFS`	Whether to redefine points after using the Perfect Focus System (PFS). TYPE: `bool`
`bRedefineAfterAutoFocus`	Whether to redefine points after performing autofocus. TYPE: `bool`
`bKeepPFSOn`	Whether to keep the Perfect Focus System (PFS) active during the experiment. TYPE: `bool`
`bSplitMultipoints`	Whether to split multipoints into separate groups or sequences. TYPE: `bool`
`bUseAFPlane`	Whether to use the autofocus plane for determining Z positions. TYPE: `bool`
`bZEnabled`	Whether the Z-axis is enabled in the experiment. TYPE: `bool`
`sZDevice`	The name of the Z-axis device used in the experiment. TYPE: `str`
`sAFBefore`	Settings for autofocus performed before the experiment. TYPE: `dict`
`Points`	A list of points defining the XY positions for the experiment. TYPE: `list of ExperimentXYPosLoopPoint`

info `property` ¶

info: list[dict[str, Any]]

Returns information about multipoint experiment.

ZStackType ¶

Enumeration of Z stack movement types.

ATTRIBUTE	DESCRIPTION
`zstBottomToTopFixedTop`	Bottom -> Top stack with a fixed Top position. TYPE: `int`
`zstBottomToTopFixedBottom`	Bottom -> Top stack with a fixed Bottom position. TYPE: `int`
`zstSymmetricRangeFixedHomeBottomToTop`	Symmetric range around a fixed Home position (Bottom -> Top). TYPE: `int`
`zstAsymmetricRangeFixedHomeBottomToTop`	Asymmetric range around a fixed Home position (Bottom -> Top). TYPE: `int`
`zstTopToBottomFixedTop`	Top -> Bottom stack with a fixed Top position. TYPE: `int`
`zstTopToBottomFixedBottom`	Top -> Bottom stack with a fixed Bottom position. TYPE: `int`
`zstSymmetricRangeFixedHomeTopToBottom`	Symmetric range around a fixed Home position (Top -> Bottom). TYPE: `int`
`zstAsymmetricRangeFixedHomeTopToBottom`	Asymmetric range around a fixed Home position (Top -> Bottom). TYPE: `int`

ExperimentZStackLoop `dataclass` ¶

ExperimentZStackLoop()

Dataclass for storing parameters about Z-stack experiment in the image.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
`uiCount`	Number of frames in the experiment (total from frames in all periods) TYPE: `int`
`dZLow`	The lowest Z position in the experiment. TYPE: `float`
`dZLowPFSOffset`	Offset applied to the lowest Z position for Perfect Focus System (PFS). TYPE: `float`
`dZHigh`	The highest Z position in the experiment. TYPE: `float`
`dZHighPFSOffset`	Offset applied to the highest Z position for Perfect Focus System (PFS). TYPE: `float`
`dZHome`	The home (central) Z position in the experiment. TYPE: `float`
`dZStep`	Step size between Z positions in the experiment. TYPE: `float`

bottom `property` ¶

bottom

Returns the lowest Z position in the experiment.

homeIndex `property` ¶

homeIndex

Returns index of the frame with home position.

info `property` ¶

info: list[dict[str, Any]]

Returns information about zstack experiment.

step `property` ¶

step: float | None

Returns step size between Z positions in the experiment in micrometers.

top `property` ¶

top

Returns the highest Z position in the experiment.

ExperimentSpectralLoop `dataclass` ¶

ExperimentSpectralLoop()

Dataclass for storing parameters about spectral loop experiment in the image.

info `property` ¶

info: list[dict[str, Any]]

Returns information about spectral loop experiment.

Experiment module¶

ExperimentLoopType ¶

toLongName staticmethod ¶

toShortName staticmethod ¶

ExperimentLevel dataclass ¶

count property ¶

dims property ¶

isLambda property ¶

isMultipoint property ¶

isTimeLapse property ¶

isZStack property ¶

name property ¶

shortName property ¶

typeName property ¶

valid property ¶

dimnames ¶

findLevel ¶

generateLoopIndexes ¶

indexOfLoop ¶

loopTypes ¶

ndim ¶

shape ¶

ExperimentTimeLoop dataclass ¶

formattedDuration property ¶

formattedInterval property ¶

info property ¶

ExperimentNETimeLoop dataclass ¶

info property ¶

ExperimentXYPosLoopPoint dataclass ¶

ExperimentXYPosLoop dataclass ¶

info property ¶

ZStackType ¶

ExperimentZStackLoop dataclass ¶

bottom property ¶

homeIndex property ¶

info property ¶

step property ¶

top property ¶

ExperimentSpectralLoop dataclass ¶

info property ¶

toLongName `staticmethod` ¶

toShortName `staticmethod` ¶

ExperimentLevel `dataclass` ¶

count `property` ¶

dims `property` ¶

isLambda `property` ¶

isMultipoint `property` ¶

isTimeLapse `property` ¶

isZStack `property` ¶

name `property` ¶

shortName `property` ¶

typeName `property` ¶

valid `property` ¶

ExperimentTimeLoop `dataclass` ¶

formattedDuration `property` ¶

formattedInterval `property` ¶

info `property` ¶

ExperimentNETimeLoop `dataclass` ¶

info `property` ¶

ExperimentXYPosLoopPoint `dataclass` ¶

ExperimentXYPosLoop `dataclass` ¶

info `property` ¶

ExperimentZStackLoop `dataclass` ¶

bottom `property` ¶

homeIndex `property` ¶

info `property` ¶

step `property` ¶

top `property` ¶

ExperimentSpectralLoop `dataclass` ¶

info `property` ¶