Algorithm functions

This section contains all the functions that are used to perform CIMAP with the description of the expected inputs and outputs. Here are presented all the functions that are given to apply the algorithm to a dataset. There are two possile way to apply the algorithm:

  1. The function run_algorithm that automatically runs all the functions requesting the user to select the input file where the data is stored.

  2. Use the other functions sequentially as explained in the CIMAP Application Example section, where is shown the sequential application of the functions for obtaining the results of CIMAP application.

run_algorithm(input_file=None, color=True)[source]

Function for the application of CIMAP to a dataset. This function when used applies all the methods of the algorithm to the data in the input_file.

Input:

  • input_file (string): None (default), a string containing the path of the .csv file that contains the input data for the application of CIMAP. In case no input_file is given the system opens a window that allows the user to search and select manually the file to use as input.

Output:

  • output_file: the method automatically generates a .csv file in the same position of the input file containing the results of the application of the CIMAP. Refer to the Data Requirements section of the documentation for the detail on the output format of the data.

  • graphics: all the graphs related to the CIMAP Algorithm application are given as output to the user.

intervals(cycles)[source]

Function for the extraction of the percentage value related to the activation intervals starting and ending point. This function is used in the pre-processing of the data for the extraction of the information necessary for the subsequent clustering steps. Also, the function returns the number of activation intervals in the cycle and the row where the cycle is put inside the “cycles” matrix. The row is used to mantain the sequence information of the cycles.

Input:

  • cycles (numpyarray): a numpy binary array whose rows represents the gait cycles and the columns represent the samples of the normalised cycle. It is important that the cycles are normalised all at the same value, in our case 1000 time samples.

Output:

  • out (list): a list containing numpy arrays which contain the percentage value of the starting and ending point of the activation intervals (e.g., out[n] = [ON1,OFF1,…,ONn, OFFm])

  • num (numpyarray): a numpy array that contains the number of activation intervals of the activation interval stored in out

  • idx (numpyarray): a numpy array that contains the sequentail number that matches the cycles stored in out

data_reading(input_file)[source]

Function that takes the input of CIMAP and prepares the data structures for the application of CIMAP Algorithm.

Input:

  • input_file (string): a string containing the path of the .csv file that contains the input data for the application of CIMAP. Be sure that the input data respects the requirements set in the Data Requirements section of the documentation.

Output:

  • s (dict): data structure of CIMAP that is used for the application of the methods of the algorithm.

  • muscles (dict): dictionary containing the information about the data that is given as input to CIMAP. Specifically the muscles, if the acquisition is bilateral and the position where to retrieve the cycles.

remove_add_ints(s)[source]

Function for the identification and removal of full active, full non-active cycles as this cycles are identified as outliers. The function also removes the activation intervals and small gaps that are smaller than 3% of the cycles as it was demonstrated in [1] that such length in the activation is ininfluent on the biomechanics of the task and so they represent noise.

Input:

  • s (dict): the dictionary containing the cycles activation data created by the Input function from the .csv file.

Output:

  • s (dict): same as the dictionary in input modified with the removal of the small gaps and of the always on/off cycles.

modality_division(s, muscles)[source]

Function for the division of the gait cycles in the different modalities before clustering. The function uses the function intervals to retrieve the activation intervals and then it divides them inside a list in muscles where the index identifies the number of activation intervals of the modality (0 always empty).

Input:

  • s (dict): the dictionary containing the cycles activation data created by the Input function from the .csv file.

  • muscles (dict): dictionary obtained as output of CIMAP_input.

Output:

  • muscles (dict): dictionary that contains the cycles divided by modality represented by the value of edges of the activation intervals translated as percentage of the cycle values.

dendrograms(muscles)[source]

Function for building of the dendrograms with the L1 and L infinite metrics for the clustering process [2].

Input:

  • muscles (dict): the dictionary containing the cycles divided by modality got as output from the modality division function.

Output:

  • muscles (dict): dictionary containing the dendrograms built from the cycles divided in modalities

cuts(muscles)[source]

Function for the identification of the optimal cut among the three different automatic cuts performed on the dendrograms based on distance [2].

Input:

  • muscles (dict): the dictionary containing the cycles divided by modality, and the dendrgrams got as output from the CIMAP_dendrograms function.

Output:

  • muscles (dict): dictionary containing the best clustering obtained for each muscle and modality.

find_cuts(distance)[source]

Function for the automatic identification of the cutting point on the dendrograms [1].

Input:

  • distance (numpyarray): the distance array that is the third column of the linkage function output.

Output:

  • cuts (list): list containing the optimal cutting point for each type of cut used.

algorithm_output(s, muscles)[source]

Function for the creation of the output of the algorithm. The output structure of this function is used for the clusterplot graphical function for the representation of the results of clustering.

Input:

  • s (dict): the dictionary containing the cycles activation data created by the Input function from the .csv file.

  • muscles (dict): output dictionary from the “CIMAP_cuts” function containing the results of the clustering on the ciclical activation intervals

Output:

  • cimap_output (dict): dictionary that contains the results of clustering divided for each individual muscle given as input with the removal of the non significant cluster

result_saver(cimap_output, input_file=None, saving=True)[source]

Function for saving the results of CIMAP in a .csv file.

Input:

  • cimap_output (dict): the dictionary containing the results of the application of CIMAP obtained from the function algorithm_output.

  • input_file (string): the path of the input file containing the data given to CIMAP. When set to None the function gives the opportunity to choose the folder where to save the data and input manually the name to give to the file.

  • saving (bool): a boolean variable that can be used to decide whether to save the results or not.

Output:

  • rows (array): array containing the results of the application of CIMAP.

act_plot(s, target='All')[source]

Function for plotting all the cycles and the activation before the application of CIMAP

Input:

  • s (dict): the dictionary containing the cycles activation data created by the Input function from the .csv file.

  • target: “All” (default), labels or portion of the label of the muscle that you want to plot. For example if LGS_R and LGS_L are available inserting the target “LGS” would plot both. Inserting the exact label give as output the graphs related to that label.

modality_distribution(s, target='All')[source]

Method for the graphical representation of the distribution of the cycles into the modalities.

Input:

  • s (dict): the dictionary containing the cycles activation data created by the Input function from the .csv file.

  • target: “All” (default), labels or portion of the label of the muscle that you want to plot. For example if LGS_R and LGS_L are available inserting the target “LGS” would plot both. Inserting the exact label give as output the graphs related to that label.

dendro_plot(muscles, target='All')[source]

Method for plotting the dendrograms built with CIMAP and chosen after performing the clustering process.

Input:

  • muscles (dict): the dictionary obtained as output from the CIMAP_cuts function.

  • target: “All” (default), labels or portion of the label of the muscle that you want to plot. For example if LGS_R and LGS_L are available inserting the target “LGS” would plot both. Inserting the exact label give as output the graphs related to that label.

clusters_plot(cimap_output, target='All', color=False)[source]

Method for the visualization of the clustering results of CIMAP.

Input:

  • cimap_output (dict): the dictionary obtained as output from the cimap_outputput function.

  • target: “All” (default), labels or portion of the label of the muscle that you want to plot. For example if LGS_R and LGS_L are available inserting the target “LGS” would plot both. Inserting the exact label give as output the graphs related to that label.

  • color (boolean): False (default), parameter to set the color of the clusters matching.

References

[1]. P. Bonato, T. D’Alessio and M. Knaflitz, A statistical method for the measurement of muscle activation intervals from surface myoelectric signal during gait. IEEE Transactions on Biomedical Engineering.

[2]. S. Rosati, C. Castagneri, V. Agostini, M. Knaflitz, and G. Balestra, Muscle contractions in cyclic movements: Optimization of CIMAP algorithm, 2017, doi: 10.1109/EMBC.2017.8036762.