Utilities

Internal utility functions used across the biomechzoo toolbox, including file I/O, data structure helpers, and signal utilities.

File I/O

biomechzoo.utils.zload.zload(filepath)[source]
biomechzoo.utils.zsave.zsave(fl, data, inplace=True, out_folder=None, root_folder=None, verbose=False)[source]

Save zoo data to a .zoo file (MATLAB MAT format).

Parameters:

  • fl (str) – Full path to the original .zoo file.

  • data (dict) – Zoo data dictionary to save.

  • inplace (bool, optional) – If True, overwrite the original file. Default is True.

  • out_folder (str or None, optional) – Output folder name (relative to root_folder or the file’s location) when inplace=False.

  • root_folder (str or None, optional) – Optional base directory used when inplace=False.

  • verbose (bool, optional) – If True, print save progress. Default is False.

biomechzoo.utils.engine.engine(root_folder, extension='.zoo', subfolders=None, name_contains=None, name_excludes=None, match_all=False, verbose=False)[source]

Recursively search for files with a given extension, with optional filters.

Parameters:

  • root_folder (str) – Root directory path where the search begins.

  • extension (str, optional) – File extension to search for. Default is ‘.zoo’.

  • subfolders (str or list of str, optional) – Restrict search to folders whose names match these strings.

  • name_contains (str or list of str, optional) – Substring(s) that must appear in the filename.

  • name_excludes (str or list of str, optional) – Substring(s) that must not appear in the filename.

  • match_all (bool, optional) – If False, keep file if it contains ANY of the substrings in name_contains. If True, keep only if it contains ALL of them. Default is False.

  • verbose (bool, optional) – If True, print the list of matched files. Default is False.

Returns:

list of str – Sorted list of absolute file paths matching the search criteria.

biomechzoo.utils.fileparts.fileparts(file)[source]

Split a file path into its directory, filename, and extension.

Parameters:

file (str) – Full path to the file.

Returns:

  • directory (str) – Directory containing the file.

  • filename (str) – Base filename without extension.

  • extension (str) – File extension including the leading dot (e.g. '.zoo').

Data Structure

biomechzoo.utils.set_zoosystem.set_zoosystem(fl=None)[source]

Create the ‘zoosystem’ metadata branch for data imported into BiomechZoo.

Parameters:

fl (str, optional) – Path to the source file (e.g., a C3D or CSV file).

Returns:

dict – Dictionary containing default BiomechZoo system parameters including Video, Analog, Anthro, Units, Version, and CompInfo sections.

biomechzoo.utils.update_channel_list.update_channel_list(data, section='Video', ch_add=None, ch_remove=None)[source]

Update the channel list of a zoosystem section by adding or removing channels.

Parameters:

  • data (dict) – Zoo data dictionary containing a ‘zoosystem’ key.

  • section (str, optional) – Section name to update (e.g., ‘Video’ or ‘Analog’). Default is ‘Video’.

  • ch_add (str or list of str, optional) – Channel name(s) to add to the section’s channel list.

  • ch_remove (str or list of str, optional) – Channel name(s) to remove from the section’s channel list.

Returns:

dict – The updated zoo dictionary (modified in place).

biomechzoo.utils.findfield.findfield(data, target_event)[source]

Search zoo data for the value and channel associated with a target event.

Parameters:

  • data (dict) – Biomechanical data dictionary loaded from a zoo file.

  • target_event (str) – Name of the event to search for.

Returns:

  • events (list or None) – Event data as [frame_index, value, 0], or None if not found.

  • channel (str or None) – Name of the channel containing the event, or None if not found.

biomechzoo.utils.get_split_events.get_split_events(data, first_event_name)[source]

splits lengthy trials containing n cycles into n trials based on side

Signal Utilities

biomechzoo.utils.compute_sampling_rate_from_time.compute_sampling_rate_from_time(t, verbose=False)[source]

Compute the sampling rate from a time column.

Parameters:

  • t (ndarray) – 1-D array of recorded timestamps in seconds.

  • verbose (bool, optional) – If True, print the computed sampling rate. Default is False.

Returns:

fsamp (int) – Sampling rate in Hz, rounded to the nearest integer.

biomechzoo.utils.peak_sign.peak_sign(r)[source]

Determine whether the largest absolute peak in the signal is positive or negative.

Parameters:

r (array-like) – Signal vector.

Returns:

sign (int) – 1 if the maximum peak is positive, -1 if negative.

biomechzoo.utils.batchdisp.batchdisp(msg, level=1, verbose='none')[source]

utility to control verbosity level during batch processing

biomechzoo.utils.common_substring.common_substring_join(strings)[source]
biomechzoo.utils.zplot.zplot(data, ch, xlabel='frames', ylabel='angles (deg)')[source]

Plot a single channel of a zoo file, along with any existing events.

Parameters:

  • data (dict) – Loaded zoo file.

  • ch (str) – Name of the channel to plot, e.g., ‘RkneeAngles’.

  • xlabel (str) – Label for x-axis. Default is ‘frames’.

  • ylabel (str) – Label for y-axis. Default is ‘angles (deg)’.

Returns:

None

biomechzoo.utils.combine_xsens_csv.combine_quats_to_csv(csv_files, prefixes, out_folder=None, out_filename=None)[source]

Concatenates time, quaternions, gyroscope, and accelerometer data from multiple CSV files into a single CSV file with prefixes defining segment.

Parameters:
Return type:

str

biomechzoo.utils.group_by_terminal_folder.group_by_terminal_folder(files, root)[source]
biomechzoo.utils.version.get_biomechzoo_version()[source]
Return type:

str