megabouts.segmentation#

class megabouts.segmentation.segmentation.SegmentationResult(config: SegmentationConfig, onset: ndarray, offset: ndarray, T: int)[source]#

Bases: object

Container for segmentation results.

Parameters:

  • config (SegmentationConfig) – Configuration used for segmentation

  • onset (np.ndarray) – Start frames of detected segments

  • offset (np.ndarray) – End frames of detected segments

  • T (int) – Total number of frames in recording

__init__(config: SegmentationConfig, onset: ndarray, offset: ndarray, T: int)[source]#
set_HB1(first_half_beat: ndarray)[source]#

Set the first half-beat frames for each segment.

Parameters:

first_half_beat (np.ndarray) – Frame indices of first half-beats, must match length of onset

extract_tail_array(*, tail_angle: ndarray, align_to_onset: bool = True) → ndarray[source]#

Extract tail angles for each detected segment.

Parameters:

  • tail_angle (np.ndarray) – Full tail angle array, shape (T, n_segments)

  • align_to_onset (bool, optional) – If True, align to bout onset, else to HB1, by default True

Returns:

Array of tail angles for each bout, shape (n_bouts, n_segments, bout_duration)

Return type:

np.ndarray

extract_traj_array(*, head_x: ndarray, head_y: ndarray, head_angle: ndarray, align_to_onset: bool = True, align: bool = True, idx_ref: int = 0) → ndarray[source]#

Extract trajectory data for each detected segment.

Parameters:

  • head_x (np.ndarray) – Head position coordinates

  • head_y (np.ndarray) – Head position coordinates

  • head_angle (np.ndarray) – Head orientation angles

  • align_to_onset (bool, optional) – If True, align to bout onset, else to HB1, by default True

  • align (bool, optional) – Whether to align trajectories, by default True

  • idx_ref (int, optional) – Reference frame for alignment, by default 0

Returns:

Array of trajectory data for each bout, shape (n_bouts, 3, bout_duration) Channels are [x, y, angle]

Return type:

np.ndarray

align_traj_array(traj_array: ndarray, idx_ref) → ndarray[source]#

Wrapper around the standalone align_traj_array function.

class megabouts.segmentation.segmentation.Segmentation(config: SegmentationConfig)[source]#

Bases: ABC

Abstract base class for segmentation algorithms.

__init__(config: SegmentationConfig)[source]#
abstract segment(data: ndarray) → SegmentationResult[source]#

Perform segmentation on the provided data.

Parameters:

data (np.ndarray) – Data to segment

Returns:

Detected segments

Return type:

SegmentationResult

classmethod from_config(config: SegmentationConfig) → Segmentation[source]#

Factory method to create appropriate segmentation instances.

Parameters:

config (SegmentationConfig) – Configuration for segmentation

Returns:

Instance of appropriate segmentation subclass

Return type:

Segmentation

class megabouts.segmentation.segmentation.TailSegmentation(config: TailSegmentationConfig)[source]#

Bases: Segmentation

Class for segmenting data based on tail movement.

__init__(config: TailSegmentationConfig)[source]#
segment(tail_vigor: ndarray) → SegmentationResult[source]#

Segment data based on tail vigor.

Parameters:

tail_vigor (np.ndarray) – 1D Array of tail vigor

Returns:

Detected segments

Return type:

SegmentationResult

class megabouts.segmentation.segmentation.TrajSegmentation(config: TrajSegmentationConfig)[source]#

Bases: Segmentation

Class for segmenting data based on trajectory movement.

__init__(config: TrajSegmentationConfig)[source]#
segment(kinematic_activity: ndarray) → SegmentationResult[source]#

Segment data based on kinematic activity.

Parameters:

kinematic_activity (np.ndarray) – Array of kinematic activity values

Returns:

Detected segments

Return type:

SegmentationResult

static find_inter_peak_min(x: ndarray, peaks: ndarray) → ndarray[source]#

Find minima between peaks.

Parameters:

  • x (np.ndarray) – Input signal

  • peaks (np.ndarray) – Indices of peaks

Returns:

Indices of minima between peaks

Return type:

np.ndarray

static find_onset_offset_around_peak(x: ndarray, peaks: ndarray, inter_peak_min: ndarray, peak_percentage: float) → Tuple[ndarray, ndarray][source]#

Find onset and offset around each peak.

Parameters:

  • x (np.ndarray) – Input signal

  • peaks (np.ndarray) – Indices of peaks

  • inter_peak_min (np.ndarray) – Indices of minima between peaks

  • peak_percentage (float) – Percentage of peak value to determine onset/offset

Returns:

  • onset (np.ndarray) – Onset indices

  • offset (np.ndarray) – Offset indices

megabouts.segmentation.segmentation.align_traj_array(traj_array: ndarray, idx_ref: int, bout_duration: int) → ndarray[source]#

Align trajectory arrays to a reference point.

Parameters:

  • traj_array (np.ndarray) – Array of shape (N, 3, bout_duration) containing x, y, and heading

  • idx_ref (int) – Reference index for alignment

  • bout_duration (int) – Duration of bout

Returns:

Aligned trajectory array

Return type:

np.ndarray

Raises:

ValueError – If idx_ref is negative or greater than bout_duration If traj_array does not have the expected shape

Examples

>>> N, duration = 10, 100  # 10 bouts, 100 frames each
>>> traj = np.zeros((N, 3, duration))  # x, y, heading
>>> traj[:, 0, :] = np.linspace(0, 1, duration)  # x increases linearly
>>> aligned = align_traj_array(traj, idx_ref=0, bout_duration=duration)
>>> np.allclose(aligned[:, 0, 0], 0)  # all trajectories start at x=0
True