megabouts.tracking_data#

megabouts.tracking_data.convert_tracking.interpolate_tail_keypoint(tail_x, tail_y, n_segments=10)[source]#

Interpolate tail keypoints to create a smooth curve.

Parameters:

tail_x (np.ndarray) – X-coordinates of tail keypoints, shape (T, n_segments_input)
tail_y (np.ndarray) – Y-coordinates of tail keypoints, shape (T, n_segments_input)
n_segments (int, optional) – Number of segments in output curve, by default 10

Returns:

(tail_x_interp, tail_y_interp) : Interpolated coordinates Each array has shape (T, n_segments+1)

Return type:

tuple

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('fulltracking_posture')
>>> tail_x = df.filter(like='tail_x').values
>>> tail_y = df.filter(like='tail_y').values
>>> x_interp, y_interp = interpolate_tail_keypoint(tail_x, tail_y, n_segments=8)
>>> x_interp.shape[1] == 9  # n_segments + 1 points
True

megabouts.tracking_data.convert_tracking.compute_angles_from_keypoints(head_x, head_y, tail_x, tail_y)[source]#

Compute tail angles and body orientation from keypoints.

Parameters:

head_x (np.ndarray) – X-coordinates of head, shape (T,)
head_y (np.ndarray) – Y-coordinates of head, shape (T,)
tail_x (np.ndarray) – X-coordinates of tail points, shape (T, N_keypoints)
tail_y (np.ndarray) – Y-coordinates of tail points, shape (T, N_keypoints)

Returns:

tail_angle (np.ndarray or None) – Cumulative angles between tail segments, shape (T, N_keypoints-1) None if only one tail point
head_yaw (np.ndarray) – Body orientation angle, shape (T,)

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('SLEAP_fulltracking')
>>> head_x = ((df["left_eye.x"] + df["right_eye.x"]) / 2) * mm_per_unit
>>> head_y = ((df["left_eye.y"] + df["right_eye.y"]) / 2) * mm_per_unit
>>> tail_x = df[[f"tail{i}.x" for i in range(5)]].values * mm_per_unit
>>> tail_y = df[[f"tail{i}.y" for i in range(5)]].values * mm_per_unit
>>> angles, yaw = compute_angles_from_keypoints(head_x, head_y, tail_x, tail_y)
>>> angles.shape[1] == tail_x.shape[1] - 1  # one angle between each segment
True

megabouts.tracking_data.convert_tracking.convert_tail_angle_to_keypoints(head_x, head_y, head_yaw, tail_angle, body_to_tail_mm=0.5, tail_to_tail_mm=0.32)[source]#

Convert tail angles back to keypoint coordinates.

Parameters:

head_x (np.ndarray) – X-coordinates of head, shape (T,)
head_y (np.ndarray) – Y-coordinates of head, shape (T,)
head_yaw (np.ndarray) – Body orientation angles, shape (T,)
tail_angle (np.ndarray) – Tail segment angles, shape (T, N_segments)
body_to_tail_mm (float, optional) – Distance from body to first tail point, by default 0.5
tail_to_tail_mm (float, optional) – Distance between consecutive tail points, by default 0.32

Returns:

(tail_x, tail_y) : Tail keypoint coordinates Each array has shape (T, N_segments+1)

Return type:

tuple

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('fulltracking_posture')
>>> head_x = df['head_x'].values * mm_per_unit
>>> head_y = df['head_y'].values * mm_per_unit
>>> head_yaw = df['head_angle'].values
>>> tail_angle = df.filter(like='tail_angle').values
>>> tail_x, tail_y = convert_tail_angle_to_keypoints(head_x, head_y, head_yaw, tail_angle)
>>> tail_x.shape == (len(head_x), tail_angle.shape[1] + 1)
True

megabouts.tracking_data.convert_tracking.interpolate_tail_angle(tail_angle, n_segments=10)[source]#

Interpolate tail angles to a different number of segments.

Parameters:

tail_angle (np.ndarray) – Tail angles, shape (T, N_segments)
n_segments (int, optional) – Number of segments in output, by default 10

Returns:

Interpolated tail angles, shape (T, n_segments)

Return type:

np.ndarray

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('fulltracking_posture')
>>> tail_angle = df.filter(like='tail_angle').values
>>> interp_angles = interpolate_tail_angle(tail_angle, n_segments=8)
>>> interp_angles.shape == (len(tail_angle), 8)
True

megabouts.tracking_data.load_example.load_example_data(source)[source]#

Load example tracking data from various sources.

Parameters:

source (str) – The source of the tracking data. Options are: - ‘fulltracking_posture’: High-res posture data (700 fps) - ‘SLEAP_fulltracking’: SLEAP tracking data (350 fps) - ‘HR_DLC’: Head-restrained DLC data (250 fps) - ‘zebrabox_SLEAP’: Zebrabox SLEAP data (25 fps)

Returns:

df (pd.DataFrame) – The loaded tracking data
fps (int) – Frames per second of the recording
mm_per_unit (float) – Scale factor to convert units to millimeters

Examples

>>> df, fps, mm_per_unit = load_example_data('fulltracking_posture')
>>> fps
700
>>> mm_per_unit
1

class megabouts.tracking_data.tracking_data.TrackingConfig(*, fps, tracking)[source]#

Bases: object

Configuration for zebrafish tracking datasets.

Parameters:

fps (int) – Frames per second of the recording (between 20 and 700)
tracking (str) – Type of tracking (‘full_tracking’, ‘head_tracking’, ‘tail_tracking’)

Examples

>>> config = TrackingConfig(fps=700, tracking='full_tracking')
>>> config.fps
700
>>> config = TrackingConfig(fps=25, tracking='head_tracking')
>>> config.tracking
'head_tracking'

__init__(*, fps, tracking)[source]#

class megabouts.tracking_data.tracking_data.TrackingData[source]#

Bases: ABC

abstract classmethod from_keypoints(*args)[source]#

abstract classmethod from_posture(*args)[source]#

class megabouts.tracking_data.tracking_data.FullTrackingData(head_x, head_y, head_yaw, tail_x, tail_y, tail_angle)[source]#

Bases: TrackingData

Container for full tracking data including both head and tail information.

The class provides two constructors: - from_keypoints: construct from raw x,y coordinates - from_posture: construct from head position and tail angles

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('fulltracking_posture')
>>> head_x = df["head_x"].values * mm_per_unit
>>> head_y = df["head_y"].values * mm_per_unit
>>> head_yaw = df["head_angle"].values
>>> tail_angle = df.filter(like="tail_angle").values
>>> tracking_data = FullTrackingData.from_posture(
...     head_x=head_x, head_y=head_y, head_yaw=head_yaw, tail_angle=tail_angle
... )
>>> isinstance(tracking_data.tail_df, pd.DataFrame)
True
>>> isinstance(tracking_data.traj_df, pd.DataFrame)
True

__init__(head_x, head_y, head_yaw, tail_x, tail_y, tail_angle)[source]#

classmethod from_keypoints(*, head_x, head_y, tail_x, tail_y)[source]#

Construct from raw keypoint coordinates.

Parameters:

head_x (array-like) – Head coordinates, shape (T,)
head_y (array-like) – Head coordinates, shape (T,)
tail_x (array-like) – Tail coordinates, shape (T, N_segments)
tail_y (array-like) – Tail coordinates, shape (T, N_segments)

classmethod from_posture(*, head_x, head_y, head_yaw, tail_angle)[source]#

Construct from head position and tail angles.

Parameters:

head_x (array-like) – Head coordinates, shape (T,)
head_y (array-like) – Head coordinates, shape (T,)
head_yaw (array-like) – Head orientation, shape (T,)
tail_angle (array-like) – Tail angles, shape (T, N_segments)

property tail_df#

property traj_df#

property tail_keypoints_df#

class megabouts.tracking_data.tracking_data.HeadTrackingData(head_x, head_y, head_yaw, swimbladder_x, swimbladder_y)[source]#

Bases: TrackingData

Container for head tracking data.

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('zebrabox_SLEAP')
>>> head_x = df['mid_eye.x'].values * mm_per_unit
>>> head_y = df['mid_eye.y'].values * mm_per_unit
>>> swimbladder_x = df['swim_bladder.x'].values * mm_per_unit
>>> swimbladder_y = df['swim_bladder.y'].values * mm_per_unit
>>> tracking_data = HeadTrackingData.from_keypoints(
...     head_x=head_x, head_y=head_y,
...     swimbladder_x=swimbladder_x, swimbladder_y=swimbladder_y)
>>> isinstance(tracking_data.traj_df, pd.DataFrame)
True

__init__(head_x, head_y, head_yaw, swimbladder_x, swimbladder_y)[source]#

classmethod from_keypoints(*, head_x, head_y, swimbladder_x, swimbladder_y)[source]#

classmethod from_posture(*, head_x, head_y, head_yaw)[source]#

property traj_df#

class megabouts.tracking_data.tracking_data.TailTrackingData(tail_x, tail_y, tail_angle)[source]#

Bases: TrackingData

Container for tail tracking data.

Examples

>>> from megabouts.tracking_data import load_example_data
>>> df, fps, mm_per_unit = load_example_data('HR_DLC')
>>> tail_x = df["DLC_resnet50_Zebrafish"].loc[:, [(f"tail{i}", "x") for i in range(11)]].values * mm_per_unit
>>> tail_y = df["DLC_resnet50_Zebrafish"].loc[:, [(f"tail{i}", "y") for i in range(11)]].values * mm_per_unit
>>> tracking_data = TailTrackingData.from_keypoints(tail_x=tail_x, tail_y=tail_y)
>>> isinstance(tracking_data.tail_df, pd.DataFrame)
True

__init__(tail_x, tail_y, tail_angle)[source]#

classmethod from_keypoints(*, tail_x, tail_y)[source]#

classmethod from_posture(*, tail_angle)[source]#

property tail_df#