nsdget 0.0.3

Python API to easily download stimuli and fMRI betas from Natural Scenes Dataset.

🧠🏞️ nsdget

nsdget: easily download and use the single trial betas 1.8mm and coco images from the Natural Scenes Dataset

Note: I'm not affiliated with Natural Scenes Dataset. I just wanted an easier and quicker way to download the data I needed from them (hence this package).

Shoutout to https://github.com/clane9/NSD-Flat/ since I reused some of the functions from there. Thank you!

Usage

To use the data, please fill out the NSD Data Access Agreement first. Then download the nsdget python package:

Install

uv add nsdget

or

pip install nsdget

Then, to download the betas for all 8 subjects and 73k coco images do

from nsdget import nsd_betas_images_trials, nsd_coco_image, nsd_single_trial_betas

# download and use data
df: pd.DataFrame = nsd_betas_images_trials(save_to="./nsdata/")
betas: np.ndarray = sd_single_trial_betas(df.iloc[0]) # 1.8mm res fmri single trial from NSD for the given row (index 0 here) 
image0: PIL.Image = nsd_coco_image(df.iloc[0]) # crops how NSD did and gives you the PIL image (can easily be converted to numpy too)

Example above ran in example.ipynb.

Note that download happens only once. After the first slow run, subsequent runs will be very fast.

Development

Dev run

uv sync
make run

Deployment PyPi

uv sync
TOKEN=... make publish # insert your PyPi token where ...

References

• https://naturalscenesdataset.org/ (Allen, St-Yves, Wu, Breedlove, Prince, Dowdle, Nau, Caron, Pestilli, Charest, Hutchinson, Naselaris*, & Kay*. A massive 7T fMRI dataset to bridge cognitive neuroscience and artificial intelligence. Nature Neuroscience (2021).)
• https://cocodataset.org/#home
• https://github.com/clane9/NSD-Flat/blob/b6851300ea3778eae7e4dbb88a85d71ce18cb9a5/generate_dataset.py#L157