Repository of the article A change in behavioral state switches the pattern of motor output that underlies rhythmic head and orofacial movements by Liao & Kleinfeld. Current Biology (2023).

Link to the paper: https://www.sciencedirect.com/science/article/pii/S0960982223004566

Graphical abstract (source: https://ars.els-cdn.com/content/image/1-s2.0-S0960982223004566-fx1.jpg)

Data can be downloaded from the following two sources:

1. Download from Google Drive (original format)
2. Download from DANDI (NWB format)

Codes on this repository can be run directly on the data downloaded from Google Drive. Conversion of data from the DANDI (in NWB format) to the original format is needed before running the codes for analysis and figure generation. Conversion code is available in the folder /nwb2mat. Instructions are provided in the following sections.

Link to the Google Drive. Please contact the authors for access.

Notes:

• The /Data folder on the Google Drive contains 33 folders, each folder corresponding to an animal investigated in this study.

• Experimental procedures for each animal can be found in Table S4 in Supplemental Information.

• The animal ID is in the format of SLRXXX (for example, SLR087).

• The session ID is named in thr format of <animal_ID>_arena_<recording_id>. Some example session IDs are SLR087_arena_d1 and SLR126_arena_h2.

• The prefix h in the recording ID means only the head sensor is taking data during the session (ex. h2). The prefix d means that both the head and torso sensors are used (ex. d1).

• For the signal processing details, please refer to the paper.

• In each animal folder (ex. SLR087) these data files are available:

  • <session_ID>_D_36data.mat is the main time series data used for analysis. The shape of the matrix should be (number of timestep sampled at 2kHz, 36), abbreviated as the 36data. The variables stored in each column are described below (variables that were frequently studied are displayed in Bold). Information of the EMG envelope channels (columns 3-6) are listed in the Appendix section below.

    	Variable		Variable		Variable		Variable
    1	Time	11	Head roll angle	21	Torso acceleration Ax	31	Torso pitch velocity
    2	N/A	12	Head acceleration Ax	22	Torso acceleration Ay	32	Torso roll velocity
    3	EMG envelope #1	13	Head acceleration Ay	23	Torso acceleration Az	33	Head-torso yaw velocity
    4	EMG envelope #2	14	Head acceleration Az	24	Torso angular velocity Wx	34	Head-torso pitch velocity
    5	EMG envelope #3	15	Head angular velocity Wx	25	Torso angular velocity Wy	35	Head-torso roll velocity
    6	EMG envelope #4	16	Head angular velocity Wy	26	Torso angular velocity Wz	36	Breathing
    7	N/A	17	Head angular velocity Wz	27	Head yaw velocity
    8	N/A	18	Torso yaw angle	28	Head pitch velocity
    9	Head yaw angle	19	Torso pitch angle	29	Head roll velocity
    10	Head pitch angle	20	N/A	30	Torso yaw velocity

  • <session_ID>_D_LCmat.mat is the raw data exported from LabChart (the data acquisition system). The signals were processed and stored as part of the 36data.

  • <session_ID>_D_video.avi is the recorded video of the session.

  • <session_ID>_D_excel.xlsx is the raw data taken by the head sensor (or head and torsor sensors). The signals were processed and stored as part of the 36data.

  • <session_ID>_D_eventLog.mat is the annotated bahaviors of the animal during the session (ex. grooming, dog-shaking). The annotations were processed and stored as part of the bBoolsMap.mat data (see below).

  • <animal_ID>_D_bBoolsMap.mat contains the boolean values for each frame from each session.

  • <animal_ID>_D_percentiles_36data.mat stores the percentiles of the selected variables from the 36data.

  • <animal_ID>_D_recordingListMap.mat lists the recording_id for each animal.

  • <animal_ID>_D_videoFrameBoundaries.mat stores the start and end frames of the video file that map to the beginning and the end of the 36data.

• In some selected animal folders these data files are available:

  • A_<animal ID>_annotation_epochs.xlsx contains the start/end frames and the location of the food pellet of each foraging trial.

  • A_<animal ID>_annotation_epochs_transposed.xlsx is a transposed version of A_<animal ID>_annotation_epochs.xlsx solely for the purpose of NWB data conversion.

  • <session_ID>_D_videoDLC_torso.csv contains the coordinates of the torso using the DeepLabCut package.

  • <session_ID>_D_arena_ellipse_params.mat stores the parameters of the boundary of the arena floor observed by the camera.

Link to DANDI Dandiset.

Details of data conversion from Google Drive to DANDI.

Codes (MATLAB) are available in the /Scripts folder, which contains the following subfolders:

• /Scripts/codes_for_figures contains the codes that can generate the figures. Please see the comments in the files for more information.
• /Scripts/codes_for_supplemental_figures contains the codes that can generate the supplemental figures. Please see the comments in the files for more information.
• /Scripts/utils contains the helper codes that are called by the other scripts.

1. Install MATLAB and the MATLAB Signal Processing Toolbox.

2. Download Chronux and add the path to the package into the MATLAB settings for spectral analysis.

3. Create a working folder (ex. /CURBIO) and place the folder /Scripts under the working folder (/CURBIO/Scripts).

4. Add the path to the subfolder /CURBIO/Scripts/utils into the MATLAB.

Choose one of the two options below to donwload the dataset:

1. Contact the authors for access and download all data from the Google Drive.

2. Place the folder /Data under the same working folder that was created in "Step 1" (i.e., /CURBIO/Data).

1. Download the dataset (Dandiset) from DANDI Dandiset. Place the folder /000540 under the working folder (i.e., /CURBIO/000540)

2. Download the folder /nwb2mat from this repository and place into the same working folder (i.e., /CURBIO/nwb2mat).

3. Create a Python virtual environment (for example, using Anaconda).

4. Install these packages in the environment:

   • numpy (install using conda)
   • pandas (install using conda)
   • pynwb (install using conda)
   • xlsxwriter (install using pip)
   • scipy (install using conda)

5. In the terminal, move to the CURBIO folder and run /nwb2mat/run_nwb2mat.py by the command below. It will create a folder Data to store data

   cd <PATH_TO_CURBIO>
   
   python nwb2mat/run_nwb2mat.py --src_dir ./000540 --dest_dir ./Data
   

6. Open and run /nwb2mat/run_mat2map.m. It will further process the data in Data and complete the full conversion.

Please note that Step 6 must be run after the completion of Step 5.

You can start running the codes and see the figures in this study.

Information of the EMG envelope channels (columns 3-6 in 36data). Only animals with EMG recordings are listed. Please also see Table S1 in the paper.

Abbreviations. L: left side, R: right side, SM: sternomastoid, CM: cleidomastoid, CT: clavotrapezius, SP: splenius, BC: biventer cervicis, VI: vibrissa intrinsic, NL: nasolabialis, DN: deflector nasi, NS: nasalis (analysis for nasalis is not published).