Quickstart

This tutorial will walk you through the fundamental functionality of BERG. You can also execute this tutorial on Google Colab. For additional tutorials, check out the Tutorial section in the BERG Repository.

Initialization

First, import the BERG package:

from berg import BERG

# Initialize BERG with the path to the root directory
berg = BERG(berg_dir="brain-encoding-response-generator")

Explore Available Models

You can list all available models:

# List all available models
available_models = berg.list_models()
print(f"Available models: {available_models}")

# Get a hierarchical view of available models by modality and dataset
catalog = berg.get_model_catalog(print_format=True)
print(f"Model Catalog as Dict: {catalog}")

Get Model Information

The describe function provides comprehensive information about the model, and about the required input parameters for the get_encoding_model() and encode() functions (i.e., the functions used to generate the in silico neural responses).

There are two ways to get detailed information about a model:

Using the describe method on a model ID:

# Get comprehensive model information
model_info = berg.describe("fmri-nsd-fwrf")

This will output detailed information about the model, including the required input parameters:

================================================================================
🧠 Model: fmri-nsd-fwrf
================================================================================

Modality: fmri
Dataset: NSD
Features: feature-weighted receptive fields (fwrf)
Repeats: single
Subject level: True

📋 Description:
This model generates in silico fMRI responses to visual stimuli using feature-
weighted receptive fields (fwrf)...

... (shortened for view)

📌 Parameters for encode():

• stimulus (numpy.ndarray, required)
  ↳ A batch of RGB images to be encoded. Images should be in integer format with
    values in the range [0, 255], and square dimensions (e.g. 224x224).
  ↳ Example: An array of shape [100, 3, 224, 224] representing 100 RGB images.

• device (str, optional, default='auto')
  ↳ Device to run the model on. 'auto' will use CUDA if available, otherwise
    CPU.
  ↳ Valid values: ['cpu', 'cuda', 'auto']
  ↳ Example: auto

📌 Parameters for get_encoding_model():

• subject (int, required)
  ↳ Subject ID from the NSD dataset (1-8)
  ↳ Valid values: [1, 2, 3, 4, 5, 6, 7, 8]
  ↳ Example: 1

• roi (str, required)
  ↳ Region of Interest (ROI) for voxel prediction. Early visual areas (V1-V3),
    category-selective regions (EBA, FFA, etc.), or composite regions (lateral,
    ventral).
  ↳ Valid values: 'V1', 'V2', 'V3', 'hV4', 'EBA', 'FBA-2', 'OFA', 'FFA-1', 'FFA-2', 'PPA', 'RSC', 'OPA', 'OWFA', 'VWFA-1', 'VWFA-2', 'mfs-words', 'early', 'midventral', 'midlateral', 'midparietal', 'parietal', 'lateral', 'ventral'
  ↳ Example: V1

• berg_dir (str, optional)
  ↳ Root directory of the BERG repository (optional if default paths are set)
  ↳ Example: ./

... (shortened for view)

Using the describe method on an instantiated model:

# Load Encoding Model
fwrf_model = berg.get_encoding_model("fmri-nsd-fwrf",
                                     subject=1,
                                     selection={"roi": "V1"})

# Get model description
fwrf_model.describe()

Both methods return the same comprehensive information. Always refer to the Parameters sections to understand what inputs each function requires.

Example: Working with the feature-weighted receptive field (fwRF) Model

This is an example on how to use the fwRF model with BERG. For more information on this model, please see the Model Overview.

# Load the fMRI encoding model
fwrf_model = berg.get_encoding_model("fmri-nsd-fwrf",
                                     subject=1,
                                     selection={"roi": "V1"}
                                     device="cpu")

# Assume images is a numpy array with shape (batch_size, 3, height, width)
# For example: (100, 3, 227, 227) for 100 RGB images

# Generate the in silico fMRI responses
fwrf_silico = berg.encode(fwrf_model, images)

# Get both in silico fMRI responses and metadata
fwrf_silico, fwrf_metadata = berg.encode(fwrf_model, images, return_metadata=True)

# Only get the encoding model's metadata
metadata = fwrf_model.get_metadata()

The generated in silico neural responses will be os shape (batch_size, n_voxels), where n_voxels depends on the selected ROI.

Always refer to the describe method to understand the specific parameters and requirements of each encoding model before using it.