Fetching predictors & images
To facilitate creating custom analysis workflows, pyNS provides a number of high-level utilities for fetching predictors from the Neuroscout API, and the corresponding images from the preprocessed BIDS dataset.
Note
Analysis pipelines created using these utilities will not be centrally registered on Neuroscout, and will not be available to other users by the Neuroscout API or web interface.
If your analysis type is supported by Neuroscout-CLI (e.g. summary statistics GLM), it is recommended to use the web interface to create your analysis or the follow the guide for Creating analyses using pyNS.
If you use these data in a publication, please cite the following paper:
Alejandro de la Vega, Roberta Rocca, Ross W Blair, Christopher J Markiewicz, Jeff Mentch, James D Kent, Peer Herholz, Satrajit S Ghosh, Russell A Poldrack, Tal Yarkoni (2022). Neuroscout, a unified platform for generalizable and reproducible fMRI research. eLife 11:e79277 https://doi.org/10.7554/eLife.79277
In addition, please cite the original dataset(s), and the predictor extractors you use.
Fetching & re-sampling predictor data
The method pyns.fetch_utils.fetch_predictors() can be used to fetch predictor data,
resample it to the TR of the images, and return it as a pandas DataFrame.
You only need two things: a list of predictors, and the name of the BIDS dataset. Optionally, you can also restrict the data to a subset of subjects, runs or tasks (reccomended for testing).
fetch_predictors(predictor_names=['speech', 'rms'], dataset_name='Budapest',
subject='sid000005', run=[1, 2], resample=True, rescale=False)
onset |
duration |
speech |
rms |
run |
subject |
run_id |
|
|---|---|---|---|---|---|---|---|
0 |
0 |
1 |
9.5801e-06 |
6.18876e-07 |
1 |
sid000005 |
1433 |
2 |
1 |
1 |
-2.57011e-05 |
-1.49298e-06 |
1 |
sid000005 |
1433 |
4 |
2 |
1 |
6.755e-05 |
3.50004e-06 |
1 |
sid000005 |
1433 |
6 |
3 |
1 |
-0.000173993 |
-7.91888e-06 |
1 |
sid000005 |
1433 |
8 |
4 |
1 |
0.000439006 |
1.70871e-05 |
1 |
sid000005 |
1433 |
This will return a pandas DataFrame with the predictors resampled to the TR (in this case 0.33s) with onset and duration columns. In addition, columns describing the entities identifying each columns (e.g. subject, run…) are included as columns.
Note that you can choose to rescale the predictors to have a mean of 0 and standard deviation of 1, by setting rescale=True. This operation will occur prior to densification and resampling of variables.
It’s possible to retrieve BIDSRunVariableCollection collection (return_type=’collection’), which can be used to apply further transformations to the data.
Note
To learn about low-level utilities for fetching predictors, see the Querying the Neuroscout API documentation.
Fetching preprocessed images
Note
Datalad is required to download images. See DataLad documentation for installation instructions.
The method pyns.fetch_utils.fetch_images() facilitates downloading preprocessed images from the
Neuroscout datasets. It can be used to download images for a single subject, or for all subjects in a
dataset.
Simply provide a directory where Neuroscout datasets should be installed, and the dataset name. Optionally, you can also restrict the data to a subset of subjects, runs or tasks (reccomended for testing).
preproc_dir, img_paths = fetch_images('Budapest', '/tmp/', subject=subject)
img_paths[0]
<BIDSImageFile filename='/tmp/Budapest/fmriprep/sub-sid000005/func/sub-sid000005_task-movie_run-1_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz'>
pyns.fetch_utils.fetch_images() installs the dataset using datalad, and returns the path to the
preprocessed dataset, as well as a list of BIDSImageFile objects for each image.
The BIDSImageFile objects can be used to load the images into memory using nibabel, and can be used to extract metadata about the image, such as the associated entities:
target = img_paths[0]
img = target.get_image()
target.get_entities()
{'datatype': 'func',
'desc': 'preproc',
'extension': '.nii.gz',
'run': 1,
'space': 'MNI152NLin2009cAsym',
'subject': 'sid000005',
'suffix': 'bold',
'task': 'movie'}
Using these methods you can easily create custom analysis workflows.