Metadata-Version: 2.4
Name: nsdget
Version: 0.0.3
Summary: Python API to easily download stimuli and fMRI betas from Natural Scenes Dataset.
Author-email: xnought <drbertucci@hotmail.com>
Requires-Python: >=3.10
Requires-Dist: colored>=2.3.0
Requires-Dist: nibabel>=5.3.2
Requires-Dist: numpy>=2.2.3
Requires-Dist: pandas>=2.2.3
Requires-Dist: pillow>=11.1.0
Requires-Dist: pyarrow>=19.0.1
Requires-Dist: tqdm>=4.67.1
Description-Content-Type: text/markdown

# 🧠🏞️ nsdget

[![PyPI - Version](https://img.shields.io/pypi/v/nsdget.svg)](https://pypi.org/project/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](https://naturalscenesdataset.org/). 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](https://docs.google.com/forms/d/e/1FAIpQLSduTPeZo54uEMKD-ihXmRhx0hBDdLHNsVyeo_kCb8qbyAkXuQ/viewform?usp=send_form) first. Then download the `nsdget` python package:

**Install**

```bash
uv add nsdget
```

or

```bash
pip install nsdget
```

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


```python
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`](./notebooks/example.ipynb).

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

## Development

**Dev run**

```bash
uv sync
make run
```

**Deployment PyPi**

```bash
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
