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)

Load a .zoo file into a zoo data dictionary.

Parameters:

filepath (str) – Path to the .zoo file to load.

Returns:

data (dict) – Zoo data dictionary, with MATLAB structs converted to nested Python dicts and Video/Analog channel lists converted to Python lists of stripped strings.

Raises:

• ValueError – If filepath does not end in '.zoo'.

• FileNotFoundError – If filepath does not exist.

Parameters:

filepath (str)

Return type:

Dict

biomechzoo.utils.zsave.zsave(fl, data, inplace=True, out_folder=None, root_folder=None, verbose=False)

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.

Parameters:

• fl (str)

• data (Dict)

• inplace (bool)

• out_folder (str | None)

• root_folder (str | None)

• verbose (bool)

Return type:

None

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

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:

matched_files (list[str]) – Sorted list of string of absolute file paths matching the search criteria.

Parameters:

• root_folder (str)

• extension (str)

• subfolders (str | List[str] | None)

• name_contains (str | List[str] | None)

• name_excludes (str | List[str] | None)

• match_all (bool)

• verbose (bool)

Return type:

list[str]

biomechzoo.utils.fileparts.fileparts(file)

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').

Parameters:

file (str)

Return type:

Tuple[str, str, str]

Data Structure

biomechzoo.utils.set_zoosystem.set_zoosystem(fl=None)

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:

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

Parameters:

fl (str | None)

Return type:

Dict

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

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:

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

Parameters:

• data (Dict)

• section (str)

• ch_add (str | List[str] | None)

• ch_remove (str | List[str] | None)

Return type:

Dict

biomechzoo.utils.findfield.findfield(data, target_event)

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 (ndarray 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.

Parameters:

• data (Dict)

• target_event (str)

Return type:

Tuple[ndarray | None, str | None]

biomechzoo.utils.get_split_events.get_split_events(data, first_event_name)

Split a lengthy trial containing multiple cycles into per-cycle event names.

Searches data for events following the naming pattern name1, name2, etc., starting from first_event_name.

Parameters:

• data (dict) – Zoo file data dictionary.

• first_event_name (str) – Name of the first event in the numbered sequence (e.g. 'RFS1').

Returns:

split_events (list of str or None) – Names of the numbered events found in sequence, or None if the event channel could not be found or fewer than 2 events exist.

Parameters:

• data (Dict)

• first_event_name (str)

Return type:

List[str] | None

Signal Utilities

biomechzoo.utils.compute_sampling_rate_from_time.compute_sampling_rate_from_time(t, verbose=False)

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.

Parameters:

• t (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

• verbose (bool)

Return type:

int

biomechzoo.utils.peak_sign.peak_sign(r)

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.

Parameters:

r (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Return type:

int

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

Print a message if the verbosity level permits.

Parameters:

• msg (str) – Message to print.

• level ({0, 1, 2, ‘none’, ‘minimal’, ‘all’}, optional) – Verbosity level required for msg to be printed. Default is 1.

• verbose ({0, 1, 2, ‘none’, ‘minimal’, ‘all’}, optional) – Current verbosity setting. msg is printed when verbose is greater than or equal to level. Default is 'none'.

Parameters:

• msg (str)

• level (int | str)

• verbose (int | str)

Return type:

None

biomechzoo.utils.common_substring.common_substring_join(strings)

Join the substrings common to every string in a list of underscore-separated names.

Parameters:

strings (list of str) – Underscore-separated strings to compare, e.g. 'a_pelvis_antpost_tilt_corr'.

Returns:

joined (str) – Underscore-joined string of the parts shared by every entry in strings, in their original order.

Parameters:

strings (List[str])

Return type:

str

biomechzoo.utils.zplot.zplot(data, ch, xlabel='frames', ylabel='angles (deg)')

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

Parameters:

• data (Dict)

• ch (str)

• xlabel (str)

• ylabel (str)

Return type:

None

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

Concatenate time, quaternion, gyroscope, and accelerometer data from multiple CSV files into a single CSV file, with column prefixes identifying each segment.

Parameters:

• csv_files (list of str) – Paths to the input CSV files, one per sensor/segment.

• prefixes (list of str) – Column-name prefix to apply for each file in csv_files, identifying the segment (e.g. 'pelvis').

• out_folder (str, optional) – Folder (relative to the current working directory) to save the combined CSV to. Default is 'combined_csvs'.

• out_filename (str, optional) – Name of the combined output CSV file. Default is 'combined_sensors.csv'.

Returns:

out_file (str) – Full path to the saved combined CSV file.

Parameters:

• csv_files (List[str])

• prefixes (List[str])

• out_folder (str | None)

• out_filename (str | None)

Return type:

str

biomechzoo.utils.group_by_terminal_folder.group_by_terminal_folder(files, root)

Group file paths by their containing (terminal) folder.

Parameters:

• files (list of str) – File paths to group.

• root (str) – Unused. Reserved for future path-relativization support.

Returns:

groups (dict of {str : list of str}) – Mapping of each unique parent folder to the list of files it contains.

Parameters:

• files (List[str])

• root (str)

Return type:

Dict[str, List[str]]

biomechzoo.utils.version.get_biomechzoo_version()

Get the installed biomechzoo package version.

Returns:

version (str) – Installed biomechzoo version string.

Return type:

str