****************************************************************************************************
*												   *
*           Movement conveys communicative functions in caregiver-infant musical interactions      *
*              Bigand, F.; Nguyen, T.; Cantoni, F.; Bianco, R.; Trainor, L.; Novembre, G.          *
*												   *
****************************************************************************************************


Data and code URLs
============================
Data analysed in the study: https://dataverse.iit.it/previewurl.xhtml?token=7ad2b3c0-7467-4410-b632-e28648c98314
Code to perform the analyses: https://github.com/felixbgd/dancing_queen


Dataset
============================
(I) KINEMATIC EXPERIMENTS:
Experiment 1 dataset contains .csv files for each mother (mum_01–20) and trial (tr01–08).
Experiment 2 dataset contains .csv files for each non-mother (nonmum_01–20) and trial (tr01–08). 

Each file contains 3D position data, organized as a (69 x 15,000) matrix:

	- 69 rows, across the 23 body markers and across the three spatial axes.	
		rows are ordered as follows: marker1_x, marker1_y, marker1_z, ... , marker23_x, marker23_y, marker23_z.
		markers are ordered as follows: (1) LB Head, (2) LF Head, (3) RF Head, (4) RB Head, (5) Sternum, (6) L Shoulder, (7) R Shoulder, (8) L Elbow, (9) L Wrist, (10) L Hand, (11) R Elbow, (12) R Wrist, (13) R Hand, (14) RF Hip, (15) RB Hip, (16) LB Hip, (17) LF Hip, (18) L Knee, (19) L Ankle, (20) L Foot, (21) R Knee, (22) R Ankle, (23) R Foot.
	- 15,000 columns, across time (all trials were 60 seconds, recorded at 250 fps).


(II) RATING EXPERIMENTS:
Experiment 3 dataset contains .csv files for the analysis of recognition scores (df_score.csv) and for modelling the relationship between recognition scores and principal movement activation (df_score_signed_PMmodel.csv).
Experiment 4-6 datasets contain .csv files for the analysis of recognition scores (df_score.csv) and for the analysis of different in recognition scores, between videos with full kinematic information and videos with movement cues removed (df_delta.csv).

All csv files are formatted in long format, including the dependent variable (either score or delta) and the covariates included in the models (e.g., participant number, biological sex, song function, principal movement (pm) manipulation, map site...).


Analysis codes 
====================================
(I) KINEMATIC EXPERIMENTS:
Software: Python v3.9.12.
Dependencies: 
matplotlib v3.5.1 and seaborn v0.11.2 are needed for potential plots.
scipy v1.13.1 is needed for signal processing
os is needed for data management
pycwt v0.3.0a22 is needed for periodicity calculations via wavelets.

All these libraries can be installed using conda or pip.

Note that two additional custom libraries are needed to run the codes:
- PLmocap: made by author FB, available here: https://github.com/felixbgd/PLmocap
- mne_fefe: MNE Python (Gramfort et al.) with minor bug fixes on cluster-based permutations, available on the github repository as .zip.

Each experiment runs within one code ("study1_mother_kinematics.py" and "study2_nonmother_kinematics.py", respectively). All quantitative results reported in the manuscript can be reproduced by running each analysis step sequentially, within code blocks. Visualizations of the Principal Movements (as 2D figures or 3D videos) is optional, and set to None by default.

For more details related to each analysis/method step, please refer to the comments throughout the code.


(II) RATING EXPERIMENTS:
Software: R v4.4.3
Dependencies: 
ordinal_2023.12-4.1 
dplyr_1.1.4         
ggplot2_4.0.1       
car_3.1-3           
carData_3.0-5       
emmeans_2.0.0      
lme4_1.1-37         
Matrix_1.7-4        
readr_2.1.6   

Each experiment runs within one code ("studyX_yyy.R"). All quantitative results reported in the manuscript can be reproduced by running the code sequentially.


Small dataset to demo the code
============================
(I) KINEMATIC EXPERIMENTS:
The entire dataset should be easy to demo, including all participants (mothers, Experiment 1; non-mothers, Experiment 2). With all participants, the code should run within 20 minutes maximum, on a normal computer. However, a smaller/faster demo can be achieved using only the first N mothers/non-mothers. This can be achieved by simply changing the parameter "NB_MUM" (line 49 in "study1_mother_kinematics.py") and "NB_NON_MUM" (line 58 in "study2_nonmother_kinematics.py) to the desired N.


(II) RATING EXPERIMENTS:
Rating experiments rely on very light data files (< 800 Kb) and therefore can be run without using partial datasets. This should run within 5 minutes maximum.

Contact
============================
Please email Félix Bigand (felix.bigand@iit.it) or Giacomo Novembre (giacomo.novembre@iit.it) for details.


License/Data Use Agreement	
============================
Creative Commons Attribution 4.0 International License. CC BY 4.0