Code for the journal article "Behavioral evidence for the hierarchical execution of sequential movements"

This repository contains the code and data used for the manuscript titled"Behavioral evidence for the hierarchical execution of sequential movements". ## Getting StartedAll analyses and simulations were performed on a Linux machine. While we cannotguarantee it, there should be no trouble running this code on Windows or Mac. The experiment code was done using psychopy and tested on both linux and windowssystems. Its behavior on mac systems is entirely untested. ### Environment Setup This project uses `poetry` to manage dependencies. If you do not wish to use poetry, you can read the dependencies directly in thepyproject.toml file. While we cannot guarantee it, results are unlikely tochange with package versions different from the ones we used, but our code mightrely on functions exclusive to recent versions. To use poetry, follow these steps: 1. **Install Poetry:** If you don't have Poetry installed, follow theinstructions at[https://python-poetry.org/docs/#installation](https://python-poetry.org/docs/#installation). 2. **Install Dependencies:** Navigate to the project's root directory (where`pyproject.toml` is located) and run: ```bashpoetry install``` This command will create a virtual environment and install all the necessarypackages specified in `pyproject.toml`. If you wish to also install the dependencies to run the experiment, run:```bashpoetry install --with experiment```Note that a necessary dependency is psychopy, which is notoriously difficultto install on some systems (due to wxpython) and might requiresystem-specific troubleshooting. 3. **Activate the Environment:** Before running any scripts, activate thevirtual environment: ```bashpoetry shell``` You should now see the environment's name in your shell prompt, indicatingthat it's active. Newer versions of poetry instead require:```basheval $(poetry env activate)``` Alternatively, all files can be executed by replacing "python" with "poetryrun" in their commands. ### The experimentRunning the experiment requires optional dependencies, as outlined above, aswell as specialized hardware and its software interface (Qualisys system).However, a test version of the experiment, where the mouse pointer is used asinput to simulate the 2D position of the fingertip on the table can be executedwith the following command:```bashpython src/experiment/main.py --no-track```Note, however, that the audio interface needs to be configured in advance, asthis is system specific. To do this, run the following command:```bashpython src/experiment/config_sound.py```and follow the instructions. The audio interface must be configured only onceper system. Other flags like --no-track are defined that modify the experiment. They aredocumented in src/experiment/main.py (at the end of the file or by running```python src/experiment/main.py --help```). Of particular importance, the--short flag runs a version of the experiment with only a few trials permovement, and a small number of movements. While in the experiment, pressing shift+ESC will interrupt the experiment andclose the window. If one or more experimental conditions were finished, thepartial data will be saved in the data folder. Note for windows systems: moreoften than not, windows will not correctly handle the shut-down of theexperiment (with shift-ESC or even when finalizing it normally). In these cases,forcibly closing the window or the python process is the only way to end it. ### ModelsThe two models begin studied are implemented in the ./src/models/hierarchical.pyfile, with class names vpSOC and HiSeq. Each of them can be instantiated withoutany parameters for a default configuration with all the sequences in theexperiment pre-configured, and sequences can be simulated with the "move"method. For HiSeq, the first input of the move method, the initial condition x_t,controls both the starting point in the 2D space of the table (first 2dimensions) and the current target in the currently-active sequence. The methodchoose_seq (defined in the parent class Simple) changes the currently activesequence. For VPSoC, the interface for the move method is simplified, with an extraparameter ix_seq to identify the sequence to be performed. In addition, theinitial condition x_t only needs to be specified in the 2D space of the table. Examples to run both vpSOC and HiSeq simulations can be seen in./src/simulations.py, functions vpsoc_reference and hiseq_reference,respectively. Additionally, the function hiseq_allsoc demonstrates a HiSeq agentthat consists only of SOC segments, as shown in the supplementary materials. ### Data, simulations and pre-processingIf the zip file was downloaded, the raw participant data can be found in./data/data_XXX.csv files, where XXX is the participant number. Additionally to the raw data, pre-processed data for all participants is in the./data_all.csv file. This file can be reproduced from the raw data by runningimport_data.import_data() and saving the output (e.g.data.to_csv('./data_all.csv')). To see all pre-processing done, see thedocstring from the importing function. Three more files are included in the zip file: (1) data_chalf.csv, (2)hiseq_chalf.csv and (3) vpsoc_chalf.csv. These include pre-calculated curvatureand coarticulation values for the participant data and for simulations with thetwo models. They can be generated by using theanalyses.XXX_curvature_vs_halfway() function, where XXX is either HiSeq orVPSoC. For the participant data, the function name isanalyses.curvature_vs_halfway(). Note that data/simulations need to be providedto these functions. To run the simulations we used for Figures 4 and 5, as well as for Table 1, runsimulations.hiseq_reference() or simulations.vpsoc3_reference() without anyinputs. The parameter values for each model can be found in paper_config.py.IMPORTANT NOTE: running these simulations takes a long time (a couple of hoursin a consumer desktop computer) and the results take up a lot of space in memoryand disk. ### Generating Figures The figures used in the publication can be generated using the `src/figures.py`script. To run it: 1. Ensure the Poetry environment is activated (see above). 2. Execute the script from the project's root directory: ```bashpython src/figures.py``` This will generate all figures exactly as in the paper. Note that if thepre-processed csv files are not present, the code will attempt to run thesimulations, which takes a long time (a few hours on a normal consumer-gradePC).