R/analyse_muscle_power.R

In Kneerav/biomechanics: Biomechanics Data Analysis

#' Analyse muscle power
#'
#' This function computes muscle power as the product of muscle force and muscle lengthening velocity.
#' It includes an option to reverse the velocity signal to treat shortening as positive (useful for power generation interpretation).
#'
#' @param muscle_force_df A dataframe containing the muscle force data (e.g., from a "muscle_forces.sto" file).
#' @param muscle_velocity_df A dataframe containing the muscle lengthening velocities (e.g., from a "muscle_velocities.sto" file).
#' @param file_output A string specifying the output file path for the muscle power results (e.g., "muscle_power.sto").
#' @param reverse_velocity A logical indicating whether to reverse the sign of velocity (default is FALSE).
#' @param write_file A logical indicating whether to write the results to a file (default is TRUE).
#' @param return_object A logical indicating whether to return the resulting data frame (default is FALSE).
#'
#' @return If return_object = TRUE, returns a data frame with the computed muscle power. If write_file = TRUE, writes the data to a file.
#' @export
#'
#' @import dplyr
#' @importFrom stringr str_replace_all

analyse_muscle_power <- function(muscle_force_df,
                                      muscle_velocity_df,
                                      file_output = "muscle_power.sto",
                                      reverse_velocity = FALSE,
                                      write_file = TRUE,
                                      return_object = FALSE) {

  # Ensure required packages are loaded
  if (!requireNamespace("dplyr", quietly = TRUE)) {
    stop("Package 'dplyr' is required but not installed.")
  }

  # Read data
  forces <- muscle_force_df
  vels <- muscle_velocity_df

  # Check dimensions match
  if (ncol(forces) != ncol(vels) || nrow(forces) != nrow(vels)) {
    stop("The number of rows or columns in the muscle force and velocity files do not match.")
  }

  # Optionally reverse velocity
  if (reverse_velocity) {
    vels[ , -1] <- -vels[ , -1]  # Assuming first column is time
  }

  # Compute power for each muscle
  power_list <- list()
  for (force_i in 2:ncol(forces)) {

    #get forces column
    force_col_i = forces[force_i]

    #get matching velocity column
    vel_col_i = vels[colnames(force_col_i)]

    #compute and store power
    power_list[[force_i - 1]] <- force_col_i * vel_col_i
  }

  # Combine to data frame
  power_df <- data.frame(time = forces[[1]], do.call(cbind, power_list))
  colnames(power_df) <- colnames(forces)

  # Write to file if needed
  if (write_file) {
    write_mot_sto(power_df, "Muscle power", "no", file_output)
  }

  # Return result if requested
  if (return_object) {
    return(power_df)
  }
}