Slice¶

lumicks.pylake.channel.Slice

class Slice(data_source, labels=None, calibration=None)¶

A lazily evaluated slice of a timeline/HDF5 channel

Users will only ever get this as a result of slicing a timeline/HDF5 channel or slicing another slice (via this class’s __getitem__()), i.e. the __init__() method should never be directly invoked by users.

Parameters:

data_source (Any) – A slice data source. Can be Continuous, TimeSeries, TimeTags, or any other source which conforms to the same interface.
labels (Dict[str, str]) – Plot labels: “x”, “y”, “title”.
calibration (ForceCalibration) –

__getitem__(item)¶: All indexing is in timestamp units (ns)

downsampled_by(factor, reduce=<function mean>)¶

Return a copy of this slice which is downsampled by factor

Parameters:

factor (int) – The size and sample rate of the data will be divided by this factor.
reduce (callable) – The numpy function which is going to reduce multiple samples into one. The default is np.mean, but np.sum could also be appropriate for some cases, e.g. photon counts.

downsampled_like(other_slice, reduce=<function mean>)¶

Downsample high frequency data analogously to a low frequency channel in the same way that Bluelake does it.

Note: some data required to reconstruct the first low frequency time point can actually occur before the starting timestamp of the marker and is therefore missing from the exported .h5 file. Therefore, it is not always possible to downsample to all of the data points in the low frequency other_slice. This function returns both the requested downsampled channel data and a copy of the input channel cropped such that both returned Slice objects have the same time points.

Parameters:

other_slice (Slice) – Timeline channel to downsample like. This should be a low frequency channel that provides the timestamps to downsample to.
reduce (callable) – The numpy function which is going to reduce multiple samples into one. The default is np.mean, but np.sum could also be appropriate for some cases, e.g. photon counts.

Returns:

downsampled_slice (Slice) – This channel downsampled to the same timestamp ranges as other_slice.
cropped_other_slice (Slice) – A copy of other_slice cropped such that the timestamps match those of downsampled_slice.

Raises:

TypeError – If the other slice is not a low frequency channel slice.
NotImplementedError – If this slice is a low frequency channel slice.
RuntimeError – If there is no overlap between the two slices.

downsampled_over(range_list, reduce=<function mean>, where='center')¶

Downsample channel data based on timestamp ranges.

The downsampling function (e.g. np.mean) is evaluated for the time between a start and end time of each block. A Slice is returned where each data point corresponds to the channel data downsampled over a block.

Parameters:

range_list (list of tuples) – A list of (start, stop) tuples indicating over which ranges to apply the function. Start and stop have to be specified in nanoseconds.
reduce (callable) – The numpy function which is going to reduce multiple samples into one. The default is np.mean, but np.sum could also be appropriate for some cases, e.g. photon counts.
where (str) –
Where to put the final time point.
- ”center” : The new time points are set to (timestamps_subset[0] + timestamps_subset[-1]) / 2, where timestamps_subset are the timestamps corresponding to the samples being downsampled over.
- ”left” : Time points are set to the starting timestamp of the downsampled data.

Returns:

slice – A slice containing data that was downsampled over the desired time ranges.

Return type:

Slice

Raises:

TypeError – If something other than a list is passed to range_list.
ValueError – If range_list does not contain a non-empty list of tuples of two elements (start and stop). If where is not set to either "center" or "left".
RuntimeError – If there is no overlap between the time ranges specified in range_list and the Slice which is to be downsampled.

Examples

from lumicks import pylake

file = pylake.File("example.h5")
stack = pylake.ImageStack("example.tiff")
file.force1x.downsampled_over(stack.frame_timestamp_ranges())

downsampled_to(frequency, reduce=<function mean>, where='center', method='safe')¶

Return a copy of this slice downsampled to a specified frequency

Parameters:

frequency (int) – The desired downsampled frequency downsampled (Hz)
reduce (callable) – The numpy function which is going to reduce multiple samples into one. The default is np.mean, but np.sum could also be appropriate for some cases, e.g. photon counts.
where (str) –
Where to put the final time point.
- ”center” : The new time points are set to (timestamps_subset[0] + timestamps_subset[-1]) / 2, where timestamps_subset are the timestamps corresponding to the samples being downsampled over.
- ”left” : Time points are set to the starting timestamp of the downsampled data.
method (str) –
How to handle target sample times that are not exact multiples of the current sample time.
- ”safe” : New sample time must be an exact multiple of the current sample time, else an exception is raised.
- ’ceil’ : Rounds the sample rate up to the nearest frequency which fulfills this condition.
- ’force’ : Downsample data with the target input frequency; this will result in variable sample times and a variable number of sampling contributing to each target sample but must be used for variable-frequency data.

plot(start=None, **kwargs)¶

A simple line plot to visualize the data over time

Parameters:

start (int64) – Origin timestamp. This can be used to plot two slices starting at different times on the same axis.
**kwargs – Forwarded to matplotlib.pyplot.plot().

range_selector(show=True, **kwargs) → SliceRangeSelectorWidget¶

Show a range selector widget

Opens a widget used to select time ranges. The timestamps of these time ranges can then be extracted from selector.ranges, while the slices can be extracted from selector.slices.

Actions:

left-click – Define time ranges by clicking the left and then the right boundary of the region you wish to select.
right-click – Remove previously selected time range.

Parameters:

show (bool, optional) – Show the plot. Default is True.
**kwargs – Forwarded to matplotlib.pyplot.plot().

Return type:

SliceRangeSelectorWidget

property calibration: list¶

List of force calibration items

The first element represents the calibration item that was active when this slice was made.

property data: numpy.typing.ArrayLike¶: The primary values of this channel slice

property sample_rate: Optional[float]¶: The data frequency for Continuous and TimeSeries data sources or None if it is not available or variable

property seconds¶: Relative time (in seconds) that corresponds to the channel data

property start¶: Starting timestamp of this time series in nanoseconds

property stop¶: End timestamp of this time series in nanoseconds

property timestamps: numpy.typing.ArrayLike¶: Absolute timestamps (since epoch) which correspond to the channel data