coordination_metrics_toolbox

Module contents

class coordination_metrics_toolbox.CoordinationMetrics(list_files_angles, list_name_angles=None, name=None, end_effector=False, deg=True, freq=None)

Bases: object

This class provides a toolbox for computing various coordination metrics from joint angle data.

It includes methods for loading data, setting angle names, computing velocities, and various coordination metrics such as continuous relative phase, principal component analysis, cross-correlation, and more.

list_files_angles

List of file paths to the CSV files containing joint angle data.

Type:

list

list_name_angles

List of names corresponding to the angles.

Type:

list

name

Name of the dataset instance.

Type:

str

end_effector

Flag indicating if the data contains end-effector data.

Type:

bool

deg

Flag indicating if the angles are in degrees.

Type:

bool

freq

Frequency of the data.

Type:

float

data_joints_angles

List of pandas DataFrames containing joint angle data.

Type:

list

list_name_velocities

List of names of the velocities of the angles.

Type:

list

angles_combinations

List of all possible combinations of angles.

Type:

list

n_dof

Number of degrees of freedom.

Type:

int

load_csv_files()

Loads joint angle data from a list of CSV files.

set_angle_names()

Sets the names of the angles based on the data provided.

set_velocities_names()

Sets the names of the velocities of the angles.

set_angles_combinations()

Sets the combinations of angles for computing inter-joint coordination metrics.

rename_time_column()

Renames the first column of each DataFrame in the data_joints_angles attribute to “time”.

rename_end_effector_columns()

Renames the columns of the end-effector data.

compute_end_effector_velocity()

Computes the velocity of the end-effector data.

set_n_dof()

Sets the number of degrees of freedom (n_dof) for the object.

convert_angles_to_radians()

Converts the joint angles from degrees to radians.

compute_joints_angular_velocity()

Computes the angular velocity for each joint angle in the dataset.

plot_joints_angles(trial=None)

Plots the joint angles for the specified trial, all trials, or mean trial.

plot_joints_angular_velocity(trial=None)

Plots the joint angular velocities for the specified trial.

compute_continuous_relative_phase(trial=None, plot=False)

Compute the Continuous Relative Phase (CRP) for joint angles.

compute_angle_angle_plot(trial=None)

Generates an angle-angle plot for joint angles data.

compute_principal_component_analysis(trial=None, plot=False, n_components=2)

Compute Principal Component Analysis (PCA) on joint angle data.

compute_cross_correlation(trial=None, plot=False, normalize=False)

Compute the cross-correlation between joint angles for a given trial or all trials.

compute_interjoint_coupling_interval(trial=None, plot=False)

Computes the Interjoint Coupling Interval (ICI) for the given trial or all trials.

get_pca_subspace(n_components=None)

Computes the PCA (Principal Component Analysis) subspace for the given data.

Examples

>>> list_files_angles = ["data/angles1.csv", "data/angles2.csv"]
>>> list_name_angles = ["angle1", "angle2", "angle3"]
>>> m = CoordinationMetrics(list_files_angles, list_name_angles, "Test Data", end_effector = False, deg=False)
>>> m.compute_continuous_relative_phase(trial=4, plot=True)

compute_angle_angle_plot(trial=None)

Generates an angle-angle plot for joint angles data.

Parameters:

trial (int, optional) – The index of the trial to plot. If None, all trials are concatenated and plotted. If -1, the mean of all trials is plotted. Defaults to None.

Returns:

The data used for plotting.

Return type:

DataFrame

Raises:

ValueError – If the trial index is out of range.

compute_angle_ratio(trial=None, plot=False)

Compute the ratio of joint angles at the time of maximum end-effector velocity.

Parameters:

• trial – int, optional The index of the trial to compute the angle ratio for. If None, computes for all trials. If -1, computes for the mean of all trials. Default is None.

• plot – bool, optional If True, plots the angle ratios. Default is False.

Returns:

pd.DataFrame

A DataFrame containing the trial index, joint pairs, and their corresponding angle ratios.

Raises:

ValueError – If end-effector data is not available or if the trial index is out of range.

Notes

The angle ratio is computed as the ratio of the angles of two joints at the time point where the end-effector velocity is maximum. If the angle of the second joint is zero, the ratio is set to NaN.

compute_continuous_relative_phase(trial=None, plot=False)

Compute the Continuous Relative Phase (CRP) for joint angles.

Parameters:

• trial (plots the CRP for the specified) – int, optional Index of the trial to compute the CRP for. If None, computes CRP for all trials. If -1, computes CRP for the mean of all trials. Default is None.

• plot – bool, optional

• True (If)

• trial

Returns:

list of pandas.DataFrame

List of DataFrames containing the joint angles and their computed phases, as well as the CRP for the specified trial(s).

Return type:

data

Raises:

ValueError – If the specified trial index is out of range.

Notes

The function computes the phase for each joint using the arctangent of the joint angle velocity and the joint angle. It then computes the CRP between specified pairs of joints (angles_combinations) by unwrapping the difference between their phases. If plotting is enabled, it generates plots of the CRP over time for the specified trial(s).

compute_correlation(trial=None, plot=False, type='pearson')

Compute the correlation between joint angles for a given trial or all trials.

Parameters:

• trial – int, optional The index of the trial to compute the correlation for. If None, computes the correlation for all trials. If -1, computes the correlation for the mean of all trials. Default is None.

• plot – bool, optional If True, plots the correlation results. Default is False.

• type – str, optional The type of correlation to compute. Options are ‘pearson’, ‘kendall’, or ‘spearman’. Default is ‘pearson’.

Returns:

pd.DataFrame

A DataFrame containing the correlation results with columns [‘trial’, ‘joints’, ‘correlation’].

Raises:

ValueError – If the trial index is out of range.

Notes

The method computes the correlation between all combinations of joint angles specified in self.angles_combinations.

compute_cross_correlation(trial=None, plot=False, normalize=False)

Compute the cross-correlation between joint angles for a given trial or all trials.

Parameters:

• trial – int, optional Index of the trial to compute cross-correlation for. If None, computes for all trials. If -1, computes for the mean of all trials. Defaults to None.

• plot – bool, optional If True, plots the cross-correlation results. Defaults to False.

• normalize – bool, optional If True, normalizes the data before computing cross-correlation. Defaults to False.

Returns:

list

A list of DataFrames containing the cross-correlation results for each trial.

Return type:

data

Raises:

ValueError – If the trial index is out of range.

compute_distance_between_PCs(cm2, n_components=None, plot=False)

Computes the distance between the principal components (PCs) of the joint angles.

From Bockemühl Till, Troje NF, Dürr V. Inter‑joint coupling and joint angle synergies of human catching movements. Hum Mov Sci. 2010;29(1):73–93. https:// doi. org/ 10. 1016/j. humov. 2009. 03. 003. Distance between PCs is defined as dist(U, V ) = np.sqrt(1 − s^2), with s being the minimum singular value of the matrix W = min(U^T V ).

Parameters:

• cm2 – CoordinationMetrics The CoordinationMetrics object to compare the distance between PCs with.

• trial – int The index of the trial to compute the distance between PCs for. Default is None and uses all the data. If -1, uses the mean joints data

• plot – bool Flag to indicate whether to plot the distance between PCs. Default is False.

Raises:

ValueError – If the trial index is out of range.

Returns:

A dataframe containing the distance between PCs for each pair of joints, one row per trial.

Return type:

res_dist_pca

compute_dynamic_time_warping(trial=None, plot=False)

Compute the Dynamic Time Warping (DTW) distance between joint angles for a given trial or all trials.

Parameters:

• trial – int, optional The index of the trial to compute DTW for. If None, computes DTW for all trials. If -1, computes DTW for the mean of all trials. Defaults to None.

• plot – bool, optional If True, plots the DTW results. Defaults to False.

Returns:

A DataFrame containing the DTW results with columns ‘trial’, ‘joints’, and ‘dtw’.

Return type:

pd.DataFrame

Raises:

ValueError – If the trial index is out of range.

Notes

• The DTW distance is computed for each combination of joint angles.

• If plot is True, a bar plot of the DTW results is displayed.

compute_end_effector_velocity()

Computes the velocity of the end-effector data.

This method computes the velocity of the end-effector data by taking the derivative of the “ee_x”, “ee_y”, and “ee_z” columns. The velocity is stored in the “ee_x_velocity”, “ee_y_velocity”, and “ee_z_velocity” columns. The global end-effector velocity is also computed and stored in the “ee_velocity” column.

Returns:

None

compute_interjoint_coupling_interval(trial=None, plot=False)

Computes the Interjoint Coupling Interval (ICI) for the given trial or all trials.

Parameters:

• trial – int, optional The index of the trial to compute the ICI for. If None, computes the ICI for all trials. If -1, computes the ICI for the mean of all trials. Default is None.

• plot – bool, optional If True, plots the ICI results using a bar plot. Default is False.

Returns:

pd.DataFrame

A DataFrame containing the ICI results with columns ‘trial’, ‘joints’, and ‘ICI’.

Raises:

ValueError – If the trial index is out of range.

Notes

The ICI is computed as the difference in deactivation times between two joints. The deactivation time is defined as the first element of the last block of consecutive indices where the joint’s velocity is less than 5% of its maximum velocity.

compute_jcvpca(coord_metric, plot=True, n_pca=None)

Compute Joint Contribution Variation using PCA (JCVPCA).

Parameters:

• coord_metric – object An object that provides the method get_concatenate_data() to retrieve the data for PCA.

• plot – bool, optional If True, the function will generate and display plots of the PCA results. Default is True.

• n_pca – int, optional Number of principal components to compute. If None, it defaults to the number of degrees of freedom (self.n_dof).

Returns:

numpy.ndarray

The PCA subspace of the reference dataset.

resnumpy.ndarray

The absolute values of the projection of the second dataset in the PCA subspace.

subnumpy.ndarray

The difference between the absolute values of the PCA subspaces of the two datasets.

Return type:

subspaceA

compute_joints_angular_velocity()

Computes the angular velocity for each joint angle in the dataset.

This method calculates the angular velocity for each joint angle by taking the difference between consecutive angle values and dividing by the time difference. The resulting angular velocities are stored in new columns with the suffix ‘_velocity’.

Parameters:

None

Returns:

None

compute_jsvcrp(coord_metric, plot=False)

Compute the Joint Synchronization Variation based on Continuous Relative Phase (JSvCRP) between two datasets.

Parameters:

• coord_metric – object An object containing the second dataset with a method to compute continuous relative phase.

• plot – bool If True, a heatmap of the JSvCRP will be plotted. Default is False.

Returns:

A DataFrame containing the JSvCRP values for each pair of angles.

Return type:

pd.DataFrame

Notes

• The method computes the Continuous Relative Phase (CRP) for both datasets.

• The JSvCRP is calculated as the integral of the absolute difference between the CRP values of the two datasets.

• The resulting JSvCRP values are stored in a DataFrame with angles as both rows and columns.

• If plot is True, a heatmap of the JSvCRP values is displayed.

compute_principal_component_analysis(trial=None, plot=False, n_components=2)

Compute Principal Component Analysis (PCA) on joint angle data.

Parameters:

• trial – int, optional Index of the trial to analyze. If None, all trials are concatenated. If -1, the mean of all trials is used. Default is None.

• plot – bool, optional If True, plots the PCA components. Default is False.

• n_components – int, optional Number of principal components to compute. Default is 2.

Returns:

PCA object

Fitted PCA object containing the principal components.

Return type:

pca

Raises:

ValueError – If the trial index is out of range.

compute_temporal_coordination_index(trial=None, plot=False)

Compute the Temporal Coordination Index (TCI) for the given trial(s). This metric calculates the time difference between the start of the end-effector movement and the start of each joint’s movement. The start of the movement is defined as the point where the velocity exceeds 5% of its maximum value.

Parameters:

• trial – int, optional The index of the trial to compute the TCI for. If None, computes TCI for all trials. If -1, computes TCI for the mean of all trials. Default is None.

• plot – bool, optional If True, plots the TCI results using a bar plot. Default is False.

Returns:

pandas.DataFrame

A DataFrame containing the TCI results with columns ‘trial’, ‘joints’, and ‘tci’.

Return type:

tci_results

Raises:

ValueError – If end-effector data is not available. If the trial index is out of range.

compute_zero_crossing(trial=None, plot=False)

Compute the zero crossing time delay for joint angles.

This method calculates the time delay between the start of movement and the deactivation time for each joint angle. The start of movement is defined as the time when the end-effector velocity exceeds 5% of its maximum value. The deactivation time for each joint is defined as the time when the joint’s velocity drops below 5% of its maximum value.

Parameters:

• trial – int, optional The index of the trial to compute the zero crossing for. If None, computes for all trials. If -1, computes for the mean of all trials. Defaults to None.

• plot – bool, optional If True, plots the zero crossing time delay for each joint. Defaults to False.

Returns:

A DataFrame containing the zero crossing time delay for each joint

in each trial. The DataFrame has columns ‘trial’, ‘joints’, and ‘zero_crossing’.

Return type:

pd.DataFrame

Raises:

ValueError – If end-effector data is not available or if the trial index is out of range.

convert_angles_to_radians()

Converts the joint angles from degrees to radians.

This method converts the joint angles from degrees to radians by multiplying the values in the data_joints_angles attribute by the conversion factor pi/180.

Parameters:

data_joints_angles (list of DataFrames) – A list containing DataFrames with joint angle data.

Returns:

None

get_angles_combinations()

Getter function for the angles_combinations attribute.

This function returns the angles_combinations attribute.

Returns:

A list containing all possible combinations of angles.

Return type:

list

get_concatenate_data()

Concatenate all joints data in a single DataFrame.

Returns:

A DataFrame containing all joints data.

Return type:

DataFrame

get_data_joints_angles()

Getter function for the data_joints_angles attribute.

This function returns the data_joints_angles attribute.

Returns:

A list of DataFrames containing joint angle data.

Return type:

list

get_list_name_angles()

Getter function for the list_name_angles attribute.

This function returns the list_name_angles attribute.

Returns:

A list containing the names of the angles.

Return type:

list

get_list_name_velocities()

Getter function for the list_name_velocities attribute.

This function returns the list_name_velocities attribute.

Returns:

A list containing the names of the velocities of the angles.

Return type:

list

get_mean_data()

Returns the mean of the data for all trials.

Returns:

A DataFrame containing the mean of the data for all trials.

Return type:

DataFrame

get_n_dof()

Getter function for the n_dof attribute.

This function returns the n_dof attribute.

Returns:

The number of degrees of freedom.

Return type:

int

get_name()

Getter function for the name attribute.

This function returns the name attribute.

Returns:

The name of the dataset instance.

Return type:

str

get_pca_subspace(n_components=None)

Computes the PCA (Principal Component Analysis) subspace for the given data.

Parameters:

n_components (int, optional) – Number of principal components to keep. If None, the number of components will be set to the number of degrees of freedom (self.n_dof).

Returns:

A DataFrame containing the PCA-transformed data with the specified number of components.

Return type:

DataFrame

load_csv_files()

Loads joint angle data from a list of CSV files.

This method reads CSV files specified in self.list_files_angles and stores the data in self.data_joints_angles. Each file is expected to have a header row.

Raises:

• FileNotFoundError – If any file in self.list_files_angles does not exist.

• ValueError – If any file in self.list_files_angles is not a CSV file.

plot_joints_angles(trial=None)

Plots the joint angles for the specified trial, all trials, or mean trial.

Parameters:

trial (int, optional) – The index of the trial to plot. If None, plots all trials. If -1, plots the mean of all trials. Defaults to None.

Raises:

• ValueError – If the trial index is out of range.

• The plot will display the joint angles over time for the specified trial(s). –

• The x-axis represents time, and the y-axis represents the joint angles. –

• The y-axis label will indicate whether the angles are in degrees or radians. –

• The plot title will include the name of the trial(s) and, if available, the name of the dataset. –

plot_joints_angular_velocity(trial=None)

Plots the joint angular velocities for the specified trial.

Parameters:

trial (int) – The index of the trial to plot. If None, plots all trials. If -1 plots the mean of all trials.

Raises:

ValueError – If the trial index is out of range.

Returns:

None

rename_end_effector_columns()

Renames the columns of the end-effector data.

This method renames the columns of the end-effector data to “ee_x”, “ee_y”, and “ee_z”. The function iterates over all dataframes containing joints angles.

Returns:

None

rename_time_column()

Renames the first column of each DataFrame in the data_joints_angles attribute to “time”.

This method iterates over the list of DataFrames stored in the data_joints_angles attribute and renames the first column of each DataFrame to “time”.

Returns:

None

set_angle_names()

Sets the names of the angles based on the data provided.

This method assigns the list of angle names to the list_name_angles attribute. If list_name_angles is None and end_effector is False, it sets list_name_angles to all columns of data_joints_angles[0] except the first one. If list_name_angles is None and end_effector is True, it sets list_name_angles to all columns of data_joints_angles[0] except the first one and the last three.

Parameters:

• list_name_angles (list) – The list of angle names.

• data_joints_angles (list) – A list containing data frames with joint angles.

• end_effector (bool) – A flag indicating whether the end effector is considered.

set_angles_combinations()

Sets the combinations of angles for computing inter-joint coordination metrics. This method generates all possible combinations of angles from the list of angle names and stores them in the angles_combinations attribute.

Parameters:

• list_name_angles (list) – A list containing the names of the angles.

• angles_combinations (list) – A list containing all possible combinations of angles.

set_n_dof()

Sets the number of degrees of freedom (n_dof) for the object. This method calculates the number of degrees of freedom by determining the length of the list_name_angles attribute and assigns this value to the n_dof attribute.

Parameters:

• n_dof (int) – The number of degrees of freedom.

• list_name_angles (list) – A list containing the names of the angles.

Returns:

None

set_velocities_names()

Sets the names of the velocities of the angles. This method sets the names of the velocities of the angles by appending “_velocity” to the names of the angles.

Parameters:

• list_name_angles (list) – A list containing the names of the angles.

• list_name_velocities (list) – A list containing the names of the velocities of the angles.

coordination_metrics_toolbox.generate_palette(n)

Generate a color palette with n colors using the ‘viridis’ colormap.

Parameters

nint

The number of colors to generate.

Returns

colorslist

A list of RGBA color tuples.

coordination_metrics_toolbox.get_pca_frame(data, n_components=2)

Perform Principal Component Analysis (PCA) on the given data and return the PCA frame.

Parameters

dataarray-like, shape (n_samples, n_features)

The input data to perform PCA on.

n_componentsint, optional, default=2

The number of principal components to compute.

Returns

componentsarray, shape (n_components, n_features)

The principal components of the data.

explained_variance_ratioarray, shape (n_components,)

The amount of variance explained by each of the selected components.

Notes

The function normalizes the data by subtracting the mean before performing PCA.