About this book

This book was written as an introduction and a guide to BalanceMate, a package facilitating analyses of postural data, created and maintained by Jean Monéger. Any question should be directed toward Jean Monéger (moneger.jean@outlook.fr). Development of the package was supported by the laboratory Vision Action Cognition (VAC, URP 7326 - Institut de Psychologie, Université Paris Cité). The author thanks the VAC laboratory for funding this project and providing access to Force plates and softwares to test the package.

The BalanceMate package was created to facilitate the handling of postural data. It was tailored to facilitate the importation of postural data exported using an AMTI platform and their software Netforce.

Users can access the package at the following address: https://github.com/JeanMoneger/BalanceMate/

To install BalanceMate from GitHub, use devtools:

# Install devtools if it's not already installed
# install.packages("devtools")

# Install the package
devtools::install_github("JeanMoneger/BalanceMate")

# Load tha package
library(BalanceMate)

AMTI platforms are force plates used in research in biophysics as well as psychology. Nevertheless, they appear to be designed to help practioners assessing patients individually without experimental protocol. Researchers, however, may find some difficulties in analyzing the output from the NetForce software. In particular:

The software does not allow merging all individual data files into one big data files
The software outputs minimal information: regarding the bsf file designed to be analysed using the BioAnalasysis prioritary software, the data contains moments and forces and time course; but for the data in text format allowing computation through different softwares, the data contains only moments and forces stored in unlabelled columns
The BioAnalysis software lacks flexibility and does not allow the computation of postural indicators in specified time intervals (i.e., if the protocol includes a training phase, the AMTI softwares will not allow the distinction between the two phases)
The BioAnalysis software does not offer transparency in the way postural indicators are calculated. In fact subtle differences in moments and forces between the .bsf outputs and .txt outputs suggest undisclosed transformations occuring in the .bsf data
The AMTI team offers limited information regarding their softwares (see mysterious point 4)

The BalanceMate package aims to provide a toolbox for researchers that recognise the use of AMTI forceplates and their softwares but that would like to use more flexible and transparent approaches to manage, pre-process, and process postural signals. However, note that this package can also be used with postural data collected using different platforms, as long as you have a data frame containing:

participants’ unique identifiers
time course for each session
Moments + Forces or CoP-X + CoP-Y

In this guide we will cover each functions of the package, and suggest a pipeline to follow. Although the suggested pipeline is directed at AMTI platforms users, once again, it should be adaptable to any users’ purpose.

This guide assumes that you are familiar with postural data - for instance, we will not develop what a Center of Pressure is.

The package will cover three main topics:

Managing Postural data: Import multiple data files, marking time-course for each sessions, labelling periods of time (epochs) and slicing the data in different periods of interes (e.g., training, trial, fixation cross, etc.)
Pre-processing postural data: Use filters to remove noise and artifacts
Processing postural data: Compute relevant postural indicators (e.g., Center of Pressures, Center of Pressures Standard deviations, 95% Confidence Ellipse interval, Sway Path Length) at the participant level or at the epoch-level, output some graphic representations of postural data (e.g., “spaghetti plot, 95% Confidence Ellipse Interval).

Managing

Merge_posData

This function is designed for AMTI NetForce users. Upon exporting your sessions’ recording in txt format, place all the recordings you want to analyse in the same folder on your computer. This helpful function will 1) merge all sessions in one large datafile, 2) label columns (original NetForce output does not label columns…), 3) Compute CoP data from moments and forces, and 4) assign a time course column to keep track of the time during the session.

To use it you will need to find the path leading to your postural data, to indicate the duration of your protocol, and to specify the sampling rate in your protocol. This function assumes that all protocols are of the same duration and using similar sampling rate.

Epoch_SliceR

This tool enables the synthesis of your postural data at a specified time-bin level (a.k.a., epoch).

Time_StampeR

This tool function can label periods of interest in your data. For instance, if you have a protocol of 60 seconds that includes:

a fixation cross (5 seconds)
and then 5 different stimuli presented for 10 seconds each,
and finally a blank screen for 5 seconds.

This function will help you to label each data point following the period.

You will need to have a good understanding of your protocol and indicate 1) the cut-points seperating each periods in your protocol, 2) the labels you want to give to each periods.

Pre-Process Data

Butterworth_it

A wrapper function of the filtfilt function from the signal package. It allows the user to filter using Butterworth filters and a specified: cut-off frequency, type of order (i.e., “first order”, “second order”, “third order”, etc.) and a type of pass (i.e., “High” or “Low” pass filter).

Note: visualising filtered data is always recommended as sometimes the application of a filter can mess with the data

Process Data

Compute_Postural_Indicators

A wrapper for computing any postural indicator (from a list - might be updated in the future to include more indicators, but for now: CoP-X, CoP-Y, SD CoP-X, SD CoP-Y, Sway Path Length, X% Confidence Ellipse Area). The function can be used to compute one or multiple postural indicators at the session level (ID) or at the epoch level. To run this function you will need: a data frame that contains: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

CoPX_ComputeR

A function to compute CoP-X. Requires a data frame containing 1) moments on the Y axis, and 2) Forces on the z-axis. note: although counterintuitive, CoP-X is derived from the rotation of the Y axis (moment)

CoPY_ComputeR

A function to compute CoP-Y. Requires a data frame containing 1) moments on the X axis, and 2) Forces on the z-axis. note: although counterintuitive, CoP-Y is derived from the inverse rotation of the X axis (moment) - inverse because of conventions.

SPL_ComputeR

A function that computes Sway Path Length. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

EllipseArea_ComputeR

A function that computes the X percent confidence interval area. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second). Optionally, you can specify which type of confidence you want for that ellipse – the default is 95%.

SD_CoPX_ComputeR

A function that computes the standard deviation of the CoP-X movements. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

SD_CoPY_ComputeR

A function that computes the standard deviation of the CoP-Y movements. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

Spaghetti plot

A function that outputs a spaghetti plot. A function that computes the standard deviation of the CoP-X movements. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

Spaghetti + Ellipse plot

A function that outputs a spaghetti plot and a confidence Ellipse area around those CoP movements. A function that computes the standard deviation of the CoP-X movements. You will need a data frame containing: 1) a unique session/participant identifier, 2) CoP-X, 3) CoP-Y, and optionnally to compute indicators per epoch, 4) a time column, 5) a specification of an epoch (e.g. 1 second).

Glossary

ID: a unique identifier for the session (or the participant, or in simple words: the data file outputed from NetForce).

Epoch: an epoch is a time-bin of interest. For example, if your session is a 60 seconds long passive viewing task, you might be interested in computing postural indicators for the first 30 seconds and the last 30 seconds (e.g., Fawver et al. 2014), or maybe each second.

X axis: Medio-lateral axis. For instance: CoP-X = CoP displacements on the medio-lateral axis.

Y axis: Antero-posterior axis. For instance: CoP-Y = CoP displacements on the antero-posterior axis.

Z axis: vertical axis.

Spaghetti plot: we call a spaghetti plot a plot that displays the displacements of the CoP of one or multiple sessions of postural recording. Formally, it is called a stabilogram, and also the name “spaghetti plot” is an already established type of plot (see https://en.wikipedia.org/wiki/Spaghetti_plot). But really, stabilograms look way more like spaghetti. Also stabilograms have been called spaghetti plot in the past (Dìaz et al., 2019). Calling stabilograms ‘spaghetti plots’ is a hill I am willing to die on.


Vision, Action, Cognition	Université Paris Cité

BalanceMate: a Package to manage, pre-process, and process postural data