Tutorial¶
This tutorial will take you through how to setup and run a full pipeline.
Setting up Pipeline Directory¶
Make a new directory for your pipeline, then run python $PATH_TO_PYCORR/setup_example.py full. This will install the following in the current directory:
- config.yaml
- run.py
- pycorr_full_data
Example Data Structure¶
The example data is contained in pycorr_full_data. Looking at how this directory is set up will give a sense for how the config file works. The directory should look like this:
├── rois
│ ├── BHipp_3mm_thr30.nii.gz
│ ├── ...
│ └── precun_3mm_thr50.nii.gz
└── subjects
├── OG_062312
│ ├── intact
│ │ └── trans_filtered_func_data.nii.gz
│ ├── mini_wordscram
│ │ └── trans_filtered_func_data.nii.gz
│ ├── short_wordscram
│ │ └── trans_filtered_func_data.nii.gz
│ └── wordscram
│ └── trans_filtered_func_data.nii.gz
├── ...
│ ├── ...
│ │ └── ...
├── aud_env_wordscram.npy
├── pieman_intact_audenv.mat
└── pieman_wordscram_audenv.mat
With a little bit of squinting, it’s clear the structure is:
├── rois
│ └── {roi_id}
└── subjects
├── {sub_id}
│ ├── runA
│ │ └── trans_filtered_func_data.nii.gz
│ └── runB
│ └── trans_filtered_func_data.nii.gz
│
└── OTHER THINGS
This is very config-able!
Config file¶
The configuration file uses Yaml, and consists of experiment-wide and condition specific settings. Here, necessary parameters are in bold.
- Experiment-wide parameters are:
- roi_files: path to rois to-be-loaded into experiment
- sub_folder: where to store data from each Run. A single hdf5 file will be created per participant.
- Condition-wide parameters are:
- base_dir: used as prefix for all paths in condition
- nii_files: path to niftis (or npy files) to-be-loaded
- audio_env: path to audio envelope for stimulus
- offset: default 0. Shift each timecourse forward by offset.
- max_len: default None (all). Maximum length of timecourse.
- threshold: default ???. Drop voxels with mean activation below threshold.
- prop_pass_thresh: default ???. How many participants need to be above threshold to keep voxel at group level.
Using ``{var}`` magic: Setting roi_files and nii_files can be done by inserting {roi_file} or {nii_file} into their respective paths. For example, in the data we have in our folder, the path to rois is rois/{roi_id}.nii*. In searching for the path, pycorr will use both {roi_id} and * as wildcards. However, it will enter each matched nifti with the name of whatever matches {roi_id}.
This takes advantage of pycorr.subject.get_subject_files().
Repeating default condition parameters. Yaml lets you set parameters from one condition as defaults for another. An example of this is in the config.yaml. The following snippet shows a default condition in action:
default: &default
max_offset: 10
conditions:
condA:
<<: *default
Running Pipeline¶
To start the pipeline, enter python run.py in the console. The starter script, run.py, iterates over conditions and performs alignment, thresholding, makes a composite, and performs inter-subject correlation.