optimap.trace

Functions for extracting time-series from videos.

optimap.trace.select_traces(video, size=5, ref_frame=0, x=None, fps=None)

Interactive selection/plotting of traces from a video. Click on the image to select a position. Right click to remove a position. Close the window to finish.

Parameters:

• video (3D np.ndarray) – Video to select traces from

• size (int) – Size parameter for trace

• ref_frame (int) – Reference frame of the first video to show

• x (1D array, optional) – X-axis values, by default None. See show_traces() for details.

• fps (float, optional) – Frames per second, by default None. See show_traces() for details.

Returns:

• traces (2D np.ndarray) – Traces of the selected positions

• positions (list of tuples) – List of selected positions

optimap.trace.extract_traces(video, coords, size=5, show=False, window=None, **kwargs)

Extract trace or traces from a video at specified coordinates.

Multiple coordinates can be provided, and the averaging method for trace extraction can be selected.

Warning

Coordinates are given as (y, x) tuples, not (x, y) tuples to be consistent with matplotlib convention (origin of image in the top left corner). E.g. the coordinate (5, 10) is equivalent to img[10, 5] in numpy.

Different averaging window types of traces:

• ‘rect’ - rectangle around the coordinates of size (size, size). This is the default option, see set_default_trace_window() to change the default. Note that if size is even the rectangle is shifted by one pixel to the top left, as there is no center pixel.

• ‘disc’ - disc around the coordinates with diameter size

• ‘pixel’ - only the pixel at the coordinates (equivalent to size=1)

Parameters:

• video (3D array) – Video to extract traces from

• coords (tuple or list of tuples) – Coordinates of the traces

• size (int, optional) – Size parameter for selection mask, by default 5px. If 0, only the pixel trace is returned.

• show (bool, optional) – Whether to show the traces using show_traces(), by default False

• window (str, optional) – Type of trace, by default ‘rect’ ‘rect’ - rectangle around the coordinates ‘disc’ - disc around the coordinates ‘pixel’ - only the pixel at the coordinates (equivalent to size=0)

• **kwargs (dict) – Extra arguments for show_traces()

Returns:

2D array containing the extracted traces.

Return type:

ndarray

optimap.trace.select_positions(image, as_integers=True)

Interactive selection of positions on an image. Click on the image to select a position. Right click to remove a position. Close the window to finish.

Parameters:

• image (2D array) – Image to select positions from

• as_integers (bool, optional) – Return pixel coordinates if True, by default True

Returns:

List of selected positions

Return type:

list of tuples

optimap.trace.compare_traces(videos, coords=None, labels=None, colors=None, size=5, ref_frame=0, fps=None, x=None)

Compare traces of multiple videos.

If coords is given, traces are plotted at the given coordinates. Otherwise, an interactive window is opened to select coordinates by clicking on the image. Close the interactive window to finish.

Parameters:

• videos (list of 3D arrays) – List of videos to compare

• coords (tuple or list of tuples) – Coordinates of the traces

• labels (list of strings, optional) – List of labels for the videos, by default None

• colors (list of colors, optional) – Colors for the traces, has to be the same length as videos, by default None

• size (int, optional) – Size parameter of the trace, by default 5

• ref_frame (int, optional) – Reference frame of the first video to show, by default 0 Only used if coords is None

• fps (float, optional) – Sampling rate of the traces (frames per second), by default None. If passed x-axis is shown in seconds. x and fps cannot be passed at the same time.

• x (1D array, optional) – X-axis values, by default None

optimap.trace.show_positions(positions, image=None, size=None, color=None, cmap='gray', vmin=None, vmax=None, ax=None, **kwargs)

Overlay positions on an image.

Parameters:

• positions (list of tuples) – List of positions to overlay

• image (2D array) – Image to overlay positions on, optional

• size (float or array-like, shape (n, ), optional) – Size of the points, see s parameter in matplotlib.pyplot.scatter() for more information

• color (str or list of str, optional) – Color of the points, by default None

• cmap (str, optional) – Colormap to use for image, by default ‘gray’

• vmin (float, optional) – Minimum value for the colormap, by default None

• vmax (float, optional) – Maximum value for the colormap, by default None

• ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure is created.

• kwargs (dict, optional) – Additional arguments to pass to matplotlib.pyplot.scatter()

Return type:

matplotlib.axes.Axes

optimap.trace.show_trace(*args, **kwargs)

Alias for show_traces().

optimap.trace.show_traces(traces, x=None, fps=None, colors=None, labels=None, ax=None, **kwargs)

Plot one or more traces.

Parameters:

• traces (1D or 2D array) – Traces to plot

• x (1D array, optional) – X-axis values, by default None

• fps (float, optional) – Sampling rate of the traces (frames per second), by default None. If passed x-axis is shown in seconds. x and fps cannot be passed at the same time.

• colors (list of colors, optional) – Colors for the traces, by default None

• labels (list of str, optional) – Labels for the traces, by default None

• ax (matplotlib.axes.Axes, optional) – Axes to plot on

• kwargs (dict, optional) – Additional arguments to pass to matplotlib.pyplot.plot()

Return type:

matplotlib.axes.Axes

optimap.trace.normalize(array: ~numpy.ndarray, ymin=0, ymax=None, vmin=None, vmax=None, dtype=<class 'numpy.float32'>, clip=True)

Normalize an array (time-series or multiple-timeseries, 1D or 2D array) to a specified range and data type.

By default, the input will be normalized to the interval [0, 1] with type np.float32 based on the minumum and maximum value of the input array.

If parameters vmin or vmax are specified, the normalization is performed using these values and the resulting array will be clipped.

The parameters ymin and ymax specify the minimum and maximum values of the resulting array, by default 0 and 1 if dtype is a floating point type, or the maximum value of the data type if dtype is an integer type.

Parameters:

• array (ndarray) – The input array to be normalized.

• ymin (float, optional) – Minimum value of the resulting video, by default 0

• ymax (float, optional) – Maximum value of the resulting video, by default 1 for floating point arrays, or the maximum value of the data type for integer arrays.

• vmin (float, optional) – Minimum value of the input video, by default None If None, the minimum value of the input video is calculated.

• vmax (float, optional) – Maximum value of the input video, by default None If None, the maximum value of the input video is calculated.

• dtype (type, optional) – Data type of the resulting array, by default np.float32

• clip (bool, optional) – If True, the resulting video will be clipped to [ymin, ymax], by default True Only applies if vmin or vmax are specified.

Returns:

Normalized array/time-series (multiple).

Return type:

ndarray

optimap.trace.detrend_timeseries(data, kind='spline', period=None, ptimes=2, retain_baseline=True, return_trend_data=False)

Detrends a time series using the seasonal package.

Parameters:

• data (1d array) – The time series to be detrended.

• kind (str) – One of (“mean”, “median”, “line”, “spline”, None) if mean, apply a period-based mean filter if median, apply a period-based median filter if line, fit a slope to median-filtered data. if spline, fit a piecewise cubic spline to the data if None, return zeros

• period (number) – seasonal periodicity, for filtering the trend. if None, will be estimated.

• ptimes (number) – multiple of period to use as smoothing window size

• retain_baseline (bool) – Retain baseline level of the time series by adding the mean of the trend back to the detrended time series.

• return_trend_data (bool) – Do not detrend, but return the trend data instead.

Returns:

detrended or trend – The detrended time series (if return_trend_data is False), the calculated trend otherwise.

Return type:

ndarray

optimap.trace.random_positions(shape_or_mask, N=1)

Returns N randomly distributed positions within image shape or mask.

Parameters:

• shape_or_mask (tuple or ndarray) – either image shape (e.g. (128, 128)) or a image mask

• N (int) – number of positions, by default 1

Returns:

list of N positions (y, x)

Return type:

list of tuples

optimap.trace.positions_from_A_to_B(N, A, B)

Creates N positions along straight line from A to B (2D coordinates).

Parameters:

• N (int) – number of positions to create

• A (tuple) – starting point (x, y)

• B (tuple) – end point (x, y)

Returns:

TODO: (x, y) or (y, x) ???

Return type:

list of tuples

optimap.trace.collage_positions(positions, image_shape, ncols=6)

Correspondant to image.collage() but for positions. Collages the positions in the same way as the images would be collaged.

positions is a list of list of tuples, i.e. one list of positions for each image. The function collages the positions in the same way as the images would be collaged and returns a list of tuples where the positions have been offset to the correct position in the collage. All images are assumed to have the same shape image_shape.

Parameters:

• positions (list of arrays) – List of list of positions to collage

• image_shape (tuple) – Shape of the images where the positions are from

• ncols (int, optional) – Number of columns, by default 6

Returns:

Collaged positions

Return type:

list of tuples

optimap.trace.set_default_trace_window(window)

Set the default trace window type.

Parameters:

window (str) – Type of trace, one of ‘rect’, ‘disc’, ‘pixel’ See extract_trace() for more information.

optimap.trace.get_default_trace_window()

Get the default trace window.

Returns:

Type of trace, one of ‘rect’, ‘disc’, ‘pixel’

Return type:

str