optimap.trace¶
Functions for extracting time-series from videos.
- optimap.trace.select_traces(video, size=5, ref_frame=0, x=None, fps=None)[source]¶
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 or np.ndarray) – Reference frame of the first video to show. If an integer, the frame is taken from the video. If an array, the array is used.
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)[source]¶
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, seeset_default_trace_window()
to change the default. Note that ifsize
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 Falsewindow (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, title='Click to select positions', num_points=None, as_integers=True, **kwargs)[source]¶
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.
If
num_points
is specified, the window will close automatically once that many points have been selected.- Parameters:
image (2D array) – Image to select positions from
title (str, optional) – Title for the figure, by default “Click to select positions”
num_points (int, optional) – Number of points to select before automatically closing, by default None
as_integers (bool, optional) – Return pixel coordinates if True, by default True
kwargs (dict, optional) – Additional keyword arguments for
optimap.show_image()
- 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, title=None, legend_loc='outside upper center', x=None, axs=None)[source]¶
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
andfps
cannot be passed at the same time.title (str, optional) – Title of the plot, by default None
legend_loc (str, optional) – Location of the legend, by default “outside upper center”
x (1D array, optional) – X-axis values, by default None
axs (list of matplotlib.axes.Axes, optional) – Axes to plot on, by default None If not passed, a new figure is created. Only used if coords is not None.
- optimap.trace.show_positions(positions, image=None, size=None, color=None, cmap='gray', vmin=None, vmax=None, ax=None, **kwargs)[source]¶
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 informationcolor (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:
- optimap.trace.show_trace(*args, **kwargs)[source]¶
Alias for
show_traces()
.
- optimap.trace.show_traces(traces, x=None, fps=None, colors=None, labels=None, ax=None, **kwargs)[source]¶
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
andfps
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:
- optimap.trace.show_positions_and_traces(video_or_traces, positions, image=0, size=5, colors=None, figsize=(10, 2.5), fps=None, vmin=None, vmax=None, cmap='gray', **kwargs)[source]¶
Show positions and traces of a video.
- Parameters:
video_or_traces (3D video array or 2D/1D trace array) – Video to extract traces from or traces to plot
positions (list of tuples) – List of positions to overlay
image (2D array or int, optional) – Image to overlay positions on, by default 0 If an integer is passed, the image is taken from the video.
size (float or array-like, shape (n, ), optional) – Size parameter for
extract_traces()
, by default 5colors (list of str, optional) – Colors for the positions/traces, by default None
figsize (tuple, optional) – Size of the figure, by default (10, 2.5)
fps (float, optional) – Show traces in seconds, see
show_traces()
vmin (float, optional) – Minimum value for the colormap, by default None
vmax (float, optional) – Maximum value for the colormap, by default None
cmap (str, optional) – Colormap to use for image, by default ‘gray’
kwargs (dict, optional) – Additional arguments to pass to
show_traces()
- optimap.trace.normalize(array: ~numpy.ndarray, ymin=0, ymax=None, vmin=None, vmax=None, dtype=<class 'numpy.float32'>, clip=True)[source]¶
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 minimum and maximum value of the input array.
If parameters
vmin
orvmax
are specified, the normalization is performed using these values and the resulting array will be clipped.The parameters
ymin
andymax
specify the minimum and maximum values of the resulting array, by default 0 and 1 ifdtype
is a floating point type, or the maximum value of the data type ifdtype
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 ifvmin
orvmax
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)[source]¶
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)[source]¶
Returns N randomly distributed positions within image shape or mask.
- optimap.trace.positions_from_A_to_B(N, A, B)[source]¶
Creates N positions along straight line from A to B (2D coordinates).
- optimap.trace.collage_positions(positions, image_shape, ncols=6)[source]¶
Arranges a list of position arrays into a grid layout, corresponding to an image collage.
This function takes a list of position arrays (e.g., coordinates of detected features) and rearranges them as if the corresponding images were arranged in a grid (see
optimap.image.collage()
andoptimap.video.collage()
). It handles the offsets required to position the points correctly within the combined grid. All images are assumed to have the same shape image_shape.