Processing

Functions for modifying the zoo data structure: adding, removing, renaming, and partitioning channels and events, as well as computing representative trials.

Channels

biomechzoo.processing.addchannel_data.addchannel_data(data, ch_new_name, ch_new_data, section='Video')[source]

Add a new channel to zoo data.

Parameters:

  • data (dict) – Zoo file data dictionary.

  • ch_new_name (str) – Name of the new channel.

  • ch_new_data (array_like) – New data to be added to the channel (should be n x 1 or n x 3).

  • section ({‘Video’, ‘Analog’}, optional) – Section of zoo data. Default is ‘Video’.

Returns:

dict – Updated zoo data with new channel added.

Parameters:
Return type:

Dict

Notes

If the channel already exists, it will be overwritten.

Adds channel name to the list in data[‘zoosystem’][section][‘Channels’].

biomechzoo.processing.removechannel_data.removechannel_data(data, channels, mode='remove')[source]

Remove or keep specified channels in a biomechanical data structure.

This function provides two modes of operation: ‘remove’ mode deletes the specified channels from the data, while ‘keep’ mode retains only the specified channels and removes all others. The function updates both the main data dictionary and the channel lists in the zoosystem metadata.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a zoo file.

  • channels (list of str) – List of channel names to remove or keep, depending on mode.

  • mode ({‘remove’, ‘keep’}, optional) – Operation mode. If ‘remove’, specified channels are deleted. If ‘keep’, only specified channels are retained. Default is ‘remove’.

Returns:

dict of str to Any – Modified data dictionary with channels removed or kept according to mode.

Raises:

ValueError – If mode is not ‘remove’ or ‘keep’, or if channel section cannot be determined.

Parameters:
Return type:

Dict[str, Any]

Notes

Channels not found in the data will generate a warning but will not cause an error.

The function modifies the input data dictionary in place and also returns it.

biomechzoo.processing.renamechannel_data.renamechannel_data(data, ch_old_names, ch_new_names, section='Video')[source]

Rename channels in a biomechanical data structure.

This function renames one or more channels by creating new channel entries with the new names, copying the line data and events from the old channels, and then removing the old channel entries. The channel list in zoosystem metadata is updated accordingly.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a zoo file.

  • ch_old_names (str or list of str) – Current name(s) of channel(s) to rename.

  • ch_new_names (str or list of str) – New name(s) for the channel(s). Must be same length as ch_old_names.

  • section ({‘Video’, ‘Analog’}, optional) – Section of zoo data where channels belong. Default is ‘Video’.

Returns:

dict of str to Any – Modified data dictionary with renamed channels.

Parameters:
Return type:

Dict[str, Any]

Notes

If a new channel name already exists in the data, it will be overwritten with a warning message.

The function modifies the input data dictionary in place and also returns it.

biomechzoo.processing.explodechannel_data.explodechannel_data(data, channels=None)[source]

Explode 3D channels (n x 3 arrays) into separate X, Y, Z component channels.

This function takes channels containing 3D data (e.g., position, angle, or force vectors) and splits them into three separate channels with ‘_x’, ‘_y’, and ‘_z’ suffixes. Events from the original channel are preserved in the ‘_x’ component only.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a zoo file.

  • channels (list of str, optional) – List of channel names to explode. If None, automatically explodes all channels with ‘line’ data shaped (n x 3).

Returns:

dict of str to Any – Deep copy of input data with specified channels exploded into X, Y, Z components.

Raises:

ValueError – If channel section (Video/Analog) cannot be determined.

Parameters:
Return type:

Dict[str, Any]

Notes

Original channel events are transferred only to the ‘_x’ component channel. The ‘_y’ and ‘_z’ components will have empty event dictionaries.

Channels that are not n x 3 shaped will be skipped with a warning message.

Events

biomechzoo.processing.addevent_data.addevent_data(data, channels, ename, etype, fsamp=None, constant=None)[source]

Add events to specified channels in a biomechanical data structure.

This function creates events based on various event types (e.g., max, min, peaks, movement onset/offset, force plate thresholds) and adds them to the specified channels in the data dictionary.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary containing channels and zoosystem metadata.

  • channels (str or list of str) – Channel name(s) to add events to. Pass 'all' to apply to all channels.

  • ename (str) – Name of the event to add. Use empty string to clear all events.

  • etype (str) – Event type, one of: ‘max’, ‘min’, ‘absmax’, ‘first’, ‘last’, ‘rom’, ‘first peak’, ‘movement_onset’, ‘movement_offset’, ‘mcgrath_fs’, ‘mcgrath_fo’, ‘fs_fp’, ‘fo_fp’.

  • fsamp (float, optional) – Sampling frequency in Hz. If None, extracted from zoosystem metadata.

  • constant (float, optional) – Threshold or parameter value for certain event types (e.g., peak height threshold, force plate threshold).

Returns:

dict of str to Any – Deep copy of input data with events added to specified channels.

Raises:

  • KeyError – If specified channel does not exist in data.

  • ValueError – If event type is unknown or if required peaks are not found.

  • Warning – If video and analog sampling rates differ for force plate events.

Parameters:
Return type:

Dict[str, Any]

Notes

Event format in data structure: [index, value, 0] where index is the frame number, value is the signal value at that frame, and 0 is a placeholder.

For event types that find multiple events (mcgrath_fs, mcgrath_fo), events are numbered sequentially (e.g., ‘ename_1’, ‘ename_2’, etc.).

biomechzoo.processing.addevent_data.find_first_peak(yd, constant)[source]

Extract the index of the first peak from a multi-peak signal.

Parameters:

  • yd (ndarray) – 1-D signal data array to search for peaks.

  • constant (float or None) – Minimum height threshold for peak detection.

Returns:

int – Index of the first peak in the signal.

Raises:

ValueError – If fewer than 2 peaks are found.

Parameters:
Return type:

int

biomechzoo.processing.removeevent_data.removeevent_data(data, events, mode='remove')[source]

Remove or retain specified events across all channels in a biomechanical data structure.

This function operates on every channel in the input data dictionary, either removing the specified events or keeping only the specified events (removing all others). Events not found in the data generate a warning and are skipped.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a .zoo file.

  • events (str or list of str) – Event name or list of event names to remove or retain.

  • mode ({‘remove’, ‘keep’}, optional) – Operation mode. If ‘remove’, specified events are deleted. If ‘keep’, only the specified events are retained and all others are removed. Default is ‘remove’.

Returns:

dict of str to Any – Deep copy of the input data with events modified according to the selected mode.

Raises:

ValueError – If mode is not ‘remove’ or ‘keep’.

Parameters:
Return type:

Dict[str, Any]

Notes

Events not found in the data generate a warning but do not raise an error.

The operation is applied to all channels in the data structure.

biomechzoo.processing.renameevent_data.renameevent_data(data, evt, nevt)[source]

Rename events in all channels of a biomechanical data structure.

This function searches all channels for specified event names and renames them to the new names. If an old event name is not found in a channel, it is skipped for that channel without error.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a zoo file.

  • evt (str or list of str) – Existing event name(s) to rename.

  • nevt (str or list of str) – New event name(s) to apply. Must be same length as evt.

Returns:

dict of str to Any – Modified data dictionary with renamed events.

Raises:

ValueError – If evt and nevt do not have the same length.

Parameters:
Return type:

Dict[str, Any]

Notes

Only events that exist in a channel will be renamed. Missing events are silently skipped for each channel.

The function modifies the input data dictionary in place and also returns it.

Trials

biomechzoo.processing.partition_data.partition_data(data, evt_start, evt_end)[source]

Partition data for all channels between two specified events.

This function extracts a subset of data between a start event and an end event, trimming all channel data to this time range. Event indices within channels are adjusted relative to the new partitioned start position.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary containing channels and events.

  • evt_start (str) – Name of the starting event for partitioning.

  • evt_end (str) – Name of the ending event for partitioning.

Returns:

dict of str to Any – Deep copy of input data with channels partitioned between the two events.

Raises:

ValueError – If either start or end event is not found in the data.

Parameters:
Return type:

Dict[str, Any]

Notes

Event indices are automatically adjusted relative to the new partition start. Events marked with index 999 (outlier markers) are preserved unchanged.

Channels that cause IndexError or ValueError during partitioning will be skipped with a warning message.

biomechzoo.processing.split_trial_data.split_trial_data(data, start_event, end_event)[source]

Split trial data between two specified events, extracting a sub-trial.

This function extracts a portion of trial data between a start event and an end event (inclusive), creating a new data structure with adjusted time indices. All channel data is sliced to this range, and event indices are recalculated relative to the new start position.

Parameters:

  • data (dict of str to Any) – Biomechanical data dictionary loaded from a zoo file.

  • start_event (str) – Name of the event marking the beginning of the sub-trial.

  • end_event (str) – Name of the event marking the end of the sub-trial.

Returns:

dict of str to Any or None – Deep copy of input data containing only the data between the two events, or None if the end event is outside the data range.

Raises:

ValueError – If either start_event or end_event is not found in the data.

Parameters:
Return type:

Dict[str, Any] | None

Notes

The end event index is inclusive in the slice (start:end+1).

If the end event index exceeds the trial length, the function returns None and prints a warning message.

Event indices are adjusted relative to the new start position in the split trial.

biomechzoo.processing.rep_trial_data.reptrial_data(gdata, channels, method='mean')[source]

Compute a representative trial from a set of trials for a subject/condition.

This function can operate in two modes:

  1. ‘mean’: Computes the pointwise mean of each specified channel across all trials, producing a synthetic representative trial.

  2. ‘rmse’: Computes the trial whose waveform is closest to the mean in the root-mean-squared error (RMSE) sense, per channel, and returns that trial as the representative.

Parameters:

  • gdata (dict) – Dictionary of zoo data. Each key corresponds to a trial (e.g., ‘data1’, ‘data2’, …).

  • channels (list of str or ‘all’) – List of channel names to include in the representative trial computation. If ‘all’, all channels in the first trial are used.

  • method ({‘mean’, ‘rmse’}, optional) – Method to compute the representative trial. Default is ‘mean’.

    • ‘mean’ : Synthetic trial from pointwise mean.

    • ‘rmse’ : Select existing trial closest to mean waveform.

Returns:

  • rep (dict) – Representative trial, in the same format as a single trial in gdata.

  • file_index (int or str) – Index of the selected trial in gdata for ‘rmse’ method, or ‘mean’ string if method=’mean’.

Raises:

ValueError – If NaN values are found in channels or if unknown method is specified.

Parameters:
Return type:

Tuple[Dict, int | str]

Notes

Events are not handled here. Rather, the user could run event detection for the representative trial.

File Combining

biomechzoo.processing.combine_files_data.combine_files_within(fld, suffix_map, name_contains, subfolders, inplace, out_folder)[source]

Combines zoo-files within a subfolder into a single file

This function operates on a root folder and automatically finds all the subdirectories. All channels withing the files within the folders will be combined into a single zoo-file.

Parameters:

  • fld (str) – Path to the root folder containing all zoo-files

  • suffix_map (list[str]) – List of names containing suffixes for channels –> must be matched to the file names

  • name_contains (str or list of str) – Name of list of names that should be within the filepath

  • subfolders (str of list of str) – Folder of list of folders that should be within the filepath

  • inplace (bool)

  • out_folder (str)

Returns:

None

Parameters:

Notes

Automatically saves the combined file to the out-folder.

biomechzoo.processing.combine_files_data.combine_files_between(in_folder, fld1, fld2, suffix, name_contains, subfolders, method='down', inplace=False, fl1exclude=None, fl2exclude=None, out_folder=None, strmatch=None)[source]

Combines 2 zoo-files in different subfolders into a single file.

This function operates on 2 folders that have the same root and automatically finds all the subdirectories. The function find the files to combine by matching the filename. Possible use case is combining data collected with different motion capture devices, e.g. IMUs and Vicon, Vicon and Force plates.

Parameters:

  • in_folder (str) – Path to the root folder containing all zoo-files

  • fld1 (str) – Path to the subfolder th be merged

  • fld2 (str) – Path to the subfolder to be merged

  • suffix (str) – Name containing suffix for the channels

  • name_contains (str or list of str) – Name of list of names that should be within the filepath

  • subfolders (str of list of str) – Folder of list of folders that should be within the filepath

  • method (str) – determines if you want to upsample the signal with the lower frequency (“up”), if you want to downsample the signal with the highest frequency (‘down’), or leave them the same ‘none’. Default is down if frequencies are different.

  • inplace (bool)

  • fl1exclude (str or list of str) – files names to ignore from fld1. Default is None.

  • fl2exclude (str or list of str) – filenames to ignore from fld2. Default is None.

  • strmatch (str) – The regular expression to find the common subject folder.

  • out_folder (str)

Returns:

None

Parameters:

Notes

Automatically saves the combined file to the out-folder using the subdirectories of the first folder path. Filenames MUST have the exact same name.

Currently files need to have the same file name in order to combine successfully e.g.

#TODO: Allow to work without strmatch #TODO: find the files to exclude for fl1 and fl2 #TODO: Find the files that are shared between the two folders. #TODO: REWORK COMBINE TO INCLUDE RESAMPLING METHODS AND TO USE THE SELF INPUT

biomechzoo.processing.xsens_dot_csv_combine.combine_quats_to_csv()[source]
biomechzoo.processing.xsens_dot_csv_combine.combine_imu_to_csv_data(csv_files, prefixes, skip_rows=None, out_folder=None, out_filename=None, verbose=1)[source]

Merge multiple Xsens DOT CSV files into a single combined CSV file.

Each sensor file is identified by a prefix. Quaternion, gyroscope, and accelerometer columns from every file are renamed with the corresponding prefix and concatenated side-by-side.

Parameters:

  • csv_files (list of str) – Ordered list of paths to the individual sensor CSV files.

  • prefixes (list of str) – Ordered list of sensor prefixes (e.g. ['LF', 'RF', 'Trunk']). Must be the same length as csv_files.

  • skip_rows (int or None, optional) – Number of header rows to skip when reading each CSV. Default is None.

  • out_folder (str or None, optional) – Directory to write the combined CSV. Defaults to 'combined_csvs' inside the current working directory.

  • out_filename (str or None, optional) – Name of the output CSV file. Defaults to 'combined_sensors.csv'.

  • verbose (int, optional) – If non-zero, prints the path of the saved file. Default is 1.

Returns:

str – Absolute path to the saved combined CSV file.

Parameters:
Return type:

str

biomechzoo.processing.xsens_dot_csv_combine.combine_imu_to_csv(prefixes, in_folder, out_folder=None, inplace=False, name_contains=None, subfolders=None, verbose=1)[source]

Batch-combine Xsens DOT CSV files for multiple subjects.

Searches in_folder recursively for CSV files, groups them by subject (parent folder name), matches files to prefixes by filename suffix, then calls combine_imu_to_csv_data() for each subject.

Parameters:

  • prefixes (list of str) – Sensor prefixes to match and order (e.g. ['LF', 'RF', 'Trunk']). Files whose basename ends with a prefix will be selected.

  • in_folder (str) – Root folder to search for CSV files.

  • out_folder (str or None, optional) – Root output folder. Each subject gets its own subfolder. Defaults to the subject’s source folder.

  • inplace (bool, optional) – Not currently used. Reserved for future in-place saving. Default is False.

  • name_contains (str or list of str or None, optional) – Only include files whose path contains this substring or all these substrings. Default is None (no filter).

  • subfolders (str or list of str or None, optional) – Only include files located inside these subfolder names. Default is None (no filter).

  • verbose (int, optional) – Verbosity level. 0 = silent, 1 = summary, 2 = per-subject. Default is 1.

Returns:

None – Results are saved to disk; nothing is returned.

Parameters:

prefixes (list[str])