read_analyze_wl {workloopR}

All-in-one import function for work loop files

Description

read_analyze_wl() is an all-in-one function to read in a work loop file, select cycles, and compute work and power output.

Usage

read_analyze_wl(file_name, ...)

Arguments

file_name

A .ddf file that contains data from a single workloop experiment

...

Additional arguments to be passed to read_ddf(), select_cycles(), or analyze_workloop().

Details

Please be careful with units! See Warnings below. This function combines read_ddf() with select_cycles() and then ultimately analyze_workloop() into one handy function.

As detailed in these three functions, possible arguments include:
cycle_def - used to specify which part of the cycle is understood as the beginning and end. There are currently three options: 'lo' for L0-to-L0; 'p2p' for peak-to-peak; and 't2t' for trough-to-trough
bworth_order - Filter order for low-pass filtering of Position via signal::butter prior to finding peak lengths. Default: 2.
bworth_freq - Critical frequency (scalar) for low-pass filtering of Position via signal::butter prior to finding peak lengths. Default: 0.05.
keep_cycles - Which cycles should be retained. Default: 4:6.
GR - Gear ratio. Default: 1.
M - Velocity multiplier used to positivize velocity; should be either -1 or 1. Default: -1.
vel_bf - Critical frequency (scalar) for low-pass filtering of velocity via signal::butter. Default: 0.05.

The gear ratio (GR) and velocity multiplier (M) parameters can help correct for issues related to the magnitude and sign of data collection. By default, they are set to apply no gear ratio adjustment and to positivize velocity. Instantaneous velocity is often noisy and the vel_bf parameter allows for low-pass filtering of velocity data. See signal::butter() and signal::filtfilt() for details of how filtering is achieved.

Value

The function returns a list of class analyzed_workloop that provides instantaneous velocity, a smoothed velocity, and computes work, instantaneous power, and net power from a work loop experiment. All data are organized by the cycle number and important metadata are stored as Attributes.

Within the list, each entry is labeled by cycle and includes:

Time

Time, in sec

Position

Length change of the muscle, corrected for gear ratio, in mm

Force

Force, corrected for gear ratio, in mN

Stim

When stimulation occurs, on a binary scale

Cycle

Cycle ID, as a letter

Inst_velocity

Instantaneous velocity, computed from Position change, reported in meters/sec

Filt_velocity

Instantaneous velocity, after low-pass filtering, again in meter/sec

Inst_Power

Instantaneous power, a product of Force and Filt_velocity, reported in J

Percent_of_Cycle

The percent of that particular cycle which has elapsed

In addition, the following information is stored in the analyzed_workloop object's attributes:

stimulus_frequency

Frequency at which stimulus pulses occurred

cycle_frequency

Frequency of oscillations (assuming sine wave trajectory)

total_cycles

Total number of oscillatory cycles (assuming sine wave trajectory) that the muscle experienced.

cycle_def

Specifies what part of the cycle is understood as the beginning and end. There are currently three options: 'lo' for L0-to-L0; 'p2p' for peak-to-peak; and 't2t' for trough-to-trough

amplitude

Amplitude of length change (assuming sine wave trajectory)

phase

Phase of the oscillatory cycle (in percent) at which stimulation occurred. Somewhat experimental, please use with caution

position_inverted

Logical; whether position inversion has been applied)

units

The units of measurement for each column in the object after running this function. See Warning

sample_frequency

Frequency at which samples were collected

header

Additional information from the header

units_table

Units from each Channel of the original ddf file

protocol_table

Protocol in tabular format; taken from the original ddf file

stim_table

Specific info on stimulus protocol; taken from the original ddf file

stimulus_pulses

Number of sequential pulses within a stimulation train

stimulus_offset

Timing offset at which stimulus began

gear_ratio

Gear ratio applied by this function

file_id

File name

mtime

Time at which file was last modified

retained_cycles

Which cycles were retained, as numerics

summary

Simple table showing work (in J) and net power (in W) for each cycle

Warning

Most systems we have encountered record Position data in millimeters and Force in millinewtons, and therefore this function assumes data are recorded in those units. Through a series of internal conversions, this function computes velocity in meters/sec, work in Joules, and power in Watts. If your raw data do not originate in millimeters and millinewtons, please transform your data accordingly and ignore what you see in the attribute units.

Author(s)

Vikram B. Baliga

References

Josephson RK. 1985. Mechanical Power output from Striated Muscle during Cyclic Contraction. Journal of Experimental Biology 114: 493-512.

See Also

read_ddf, select_cycles analyze_workloop

Other data analyses: analyze_workloop(), isometric_timing(), read_analyze_wl_dir()

Other data import functions: as_muscle_stim(), get_wl_metadata(), read_analyze_wl_dir(), read_ddf_dir(), read_ddf()

Other workloop functions: analyze_workloop(), fix_GR(), get_wl_metadata(), invert_position(), read_analyze_wl_dir(), select_cycles(), summarize_wl_trials(), time_correct()

Examples

library(workloopR)

# import the workloop.ddf file included in workloopR and analyze with
# a gear ratio correction of 2 and cycle definition of peak-to-peak
wl_dat <- read_analyze_wl(system.file("extdata", "workloop.ddf",
                                      package = 'workloopR'),
                          phase_from_peak = TRUE,
                          GR = 2, cycle_def = "p2p")