PI BEAT

Copyright BEAT 2020

Purposes

This toolbox allows computing Performance Indicator (PI) within the BEAT project protocol. In particular, kinematic parameters both in stepping and perturbed conditions, muscle synergies in stepping condition, posturographic parameters both in stepping and perturbed conditions and parameters to understand the behaviour under step and sinusoidal parameters can be computed. The toolbox contains seven PI's algorithms.

Installation

To enable the code under octave, additional packages are needed. Follow this link to make the installation of the additional packages needed.

Once octave is configured:

pkg load statistics
pkg load io
pkg load linear-algebra
pkg load signal

Usage

Protocol benchmark

The code enables scoring 7 different protocols

• Protocol 1.
  • run_kinematic_walking
  • run_emg

./run_protocol1 tests/data/protocol1/input/jointAngles.csv tests/data/protocol1/input/platformData.csv tests/data/protocol1/input/emg.csv out_tests

• Protocol 2.
  • run_kinematic_walking
  • run_emg
  • run_posturography_unperturbed

./run_protocol2 tests/data/protocol2/input/jointAngles.csv tests/data/protocol2/input/platformData.csv tests/data/protocol2/input/emg.csv out_tests

• Protocol 3.
  • run_posturography_unperturbed

./run_protocol3 tests/data/protocol3/input/platformData.csv out_tests

• Protocol 4.
  • run_posturography_unperturbed

./run_protocol4 tests/data/protocol4/input/platformData.csv out_tests

• Protocol 5.
  • run_kinematic_perturbation
  • run_posturography_perturbation

./run_protocol5 tests/data/protocol5/input/jointAngles.csv tests/data/protocol5/input/platformData.csv out_tests

• Protocol 6.
  • run_kinematic_perturbation
  • run_posturography_perturbation
  • run_stepperturbation

./run_protocol6 tests/data/protocol6/input/jointAngles.csv tests/data/protocol6/input/platformData.csv out_tests

• Protocol 7.
  • run_posturography_perturbation
  • run_sinusoidalperturbation

./run_protocol7 tests/data/protocol7/input/jointAngles.csv tests/data/protocol7/input/platformData.csv out_tests

Performance Indicator launch

kinematic_routine_walking

This routine computes the mean range of motion and the Coefficient of Variation when stepping on place protocols have been performed. Assuming folder out_tests exists:

./run_kinematic_walking ./tests/data/protocol1/input/jointAngles.csv ./tests/data/protocol1/input/PlatformData.csv ./out_tests

The script can be launched for the protocol1 or protocol2.

kinematic_routine_perturbation

This routine computes the range of motion in different directions of the space when perturbation protocols have been performed. Assuming folder out_tests exists:

./run_kinematic_perturbation ./tests/data/protocol5/input/jointAngles.csv ./tests/data/protocol5/input/platformData.csv ./out_tests

PlatformData file must be related to the protocol5 or protocol6.

EMG_routine

This routine computes the muscle synergy number for the right and left side of the lower limbs when stepping protocols have been performed. Assuming folder out_tests exists:

./run_EMG ./tests/data/protocol1/input/emg.csv ./tests/data/protocol1/input/platformData.csv ./out_tests

PlatformData must be related to the protocol1 or protocol2.

posturographic_routine_unperturbed

This routine computes the posturographic parameters: path length of the Centre of Pressure (CoP), path length of the CoP in antero-posterior direction, path length of the CoP in medio-lateral direction and the area at 95% of the confidence ellipse when protocols without perturbations have been performed. Assuming folder out_tests exists:

./run_posturography_unperturbed ./tests/data/protocol2/input/platformData.csv ./out_tests

PlatformData must be related to the protocol2, protocol3 or protocol4.

posturographic_routine_perturbation

This routine computes the posturographic parameters: path length of the Centre of Pressure (CoP) and the area at 95% of the confidence ellipse in different space directions when protocols with perturbations have been performed. Assuming folder out_tests exists:

./run_posturography_perturbation ./tests/data/protocol5/input/platformData.csv ./out_tests

platformData must be related to the protocol5, protocol6 or protocol7.

step_perturbation

This routine computes the parameters to quantify the reaction of the subject to step perturbation: overshoot of the platform angle, the final angular position of the platform and the range of the excursion of the platform during the last 1.5 s of the task in each space direction when step perturbation protocol with uneven surface has been performed. Assuming folder out_tests exists:

./run_stepperturbation ./tests/data/protocol6/input/platformData.csv ./out_tests

platformData must be related to protocol6.

sinusoidal_perturbation

This routine computes the kinematic parameters to quantify the reaction of the subject to sinusoidal perturbation: gain ratio and shift phase with respect to the imposed sinusoidal wave when sinusoidal perturbation protocol has been performed. Assuming folder out_tests exists:

./run_sinusoidalperturbation ./tests/data/protocol7/input/jointAngles.csv ./tests/data/protocol7/input/platformData.csv ./out_tests

platformData must be related to protocol7.

Docker-based code access

The following is valid for Linux machines.

Get official image

An image ready to be used is available, without downloading that code:

docker pull eurobenchtest/pi_beat

Now you can jump on the command to launch the docker image.

Build docker image

Run the following command in order to create the docker image for this testbed, from the repository code:

docker build . -t beat_routine

Launch the docker image

Assuming the tests/protocol1/input contains the input data, and that the directory out_tests/ is already created, and will contain the PI output:

docker run --rm -v $PWD/tests/data/protocol1/input:/in -v $PWD/out_tests:/out beat_routine ./run_protocol1 /in/jointAngles.csv /in/platformData.csv /in/emg.csv /out

Testing

All scripts are provided with reference input and related output files. Under linux, an automatic regression testing can be launched, making sure all scripts generate the recorded output files, given the recorded input files.

This is based on the Eurobench docker testing tool. The test plan, related to the script calls previously listed, is in file tests/test_plan.xml.

Assuming the docker image has been created using name pi_csic_manip, the testing can be launched locally using (python3 is required):

# only done once
wget -O test_docker_call.py https://raw.githubusercontent.com/eurobench/docker_test/master/test_docker_call.py
export DOCKER_IMAGE='beat_routine'
export TEST_PLAN='tests/test_plan.xml'
python3 test_docker_call.py

If any of the scripts does not generate the expected output files, the python file will state it.

Acknowledgements

Supported by Eurobench - the European robotic platform for bipedal locomotion benchmarking. More information: Eurobench website

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement no. 779963.

The opinions and arguments expressed reflect only the author‘s view and reflect in no way the European Commission‘s opinions. The European Commission is not responsible for any use that may be made of the information it contains.