Running TRF model¶

You're ready to estimate (multivariate) TRF models that predict EEG responses from the predictors. Here, TRFs will be estimated using the boosting algorithm implemented in the Eelbrain package.

As in previous steps, you can either run everything in a notebook by passing arguments directly to a function, or define the settings in a configuration file first. Because TRF model fitting is usually the most computationally intensive and time-consuming, it's recommended to use the configuration file and then submit a Slurm job to a computing cluster to run the code with parallel processing, if you have access to a cluster. The next tutorial will provide a more detailed example of how to do this using Northwestern Quest.

But for now, we'll first illustrate how to define and run models in a notebook as in previous steps.

Defining and running TRF models¶

The thing to do is to specify the TRF models. Here, we will fit three models: one full model that includes both the 8-band gammatone envelope and 8-band onset predictors, and two reduced models that include only one of these predictor types. Reduced models are useful when you want to evaluate the unique contribution of one or more predictors. For example, suppose the full model includes predictors A, B, C, and D, and you're interested in the unique predictive power of A and B. You can estimate this by subtracting the predictive power of a model containing only C and D from that of the full model. More details will be provided in the results analysis section.

Models are specified using a dictionary. The dictionary keys are model names, and the values are lists of predictor names to include in each model. Again, predictor names correspond to the part of the predictor filename after the tilde (~) and before the file extension (e.g., 'track1~gammatone-8.pickle').

In [2]:

Copied!





models = {
    'full': ['gammatone-8', 'gammatone-on-8'],
    'onsets_only': ['gammatone-on-8'],
    'envelope_only': ['gammatone-8']
}
models = {
    'full': ['gammatone-8', 'gammatone-on-8'],
    'onsets_only': ['gammatone-on-8'],
    'envelope_only': ['gammatone-8']
}

Next, specify the configurations for the boosting algorithm. The following settings should work fine for most analyses. See the Eelbrain documentation for details.

The parameters you are most likely to adjust are tstart and tstop, which define the minimum and maximum time lags of the TRF, respectively. In other words, they specify the time window over which stimulus features are allowed to predict the EEG response, from $\tau_{\min}$ to $\tau_{\max}$. If you expect neural responses at longer latencies (e.g., to higher-order linguistic features), you may want to increase tstop.

In [3]:

Copied!





boosting_cfgs = {
    'tstart': -0.1,
    'tstop': 0.5,
    'error': 'l1',   # Use L1 error
    'delta': 0.005,
    'basis': 0.05,
    'partitions': 5, # Do 5-fold cross-validation
    'test': 1,
    'selective_stopping': 1
}
boosting_cfgs = {
    'tstart': -0.1,
    'tstop': 0.5,
    'error': 'l1',   # Use L1 error
    'delta': 0.005,
    'basis': 0.05,
    'partitions': 5, # Do 5-fold cross-validation
    'test': 1,
    'selective_stopping': 1
}

Finally, estimate TRF model using ns.trf.run_boosting():

In [4]:

Copied!

import neuraspeech as ns
import neuraspeech as ns

In [5]:

Copied!





# Run boosting with the specified configurations
ns.trf.run_boosting(
    eeg_path = 'eeg/prepared',
    predictor_set_path = 'predictors/acou_pred_set',
    results_path = 'results',
    metadata_path = 'misc/example_metadata.csv',
    metadata_filename_col = 'filename',

    models = models,
    boosting_cfgs = boosting_cfgs,
    random_seed = 2026,

    parallelproc = True,
    n_workers = 2,
    skip_estimated_models = True,
    include = {'sub': ['3000_04', '3042_04']},
    exclude = None
    )
# Run boosting with the specified configurations
ns.trf.run_boosting(
    eeg_path = 'eeg/prepared',
    predictor_set_path = 'predictors/acou_pred_set',
    results_path = 'results',
    metadata_path = 'misc/example_metadata.csv',
    metadata_filename_col = 'filename',

    models = models,
    boosting_cfgs = boosting_cfgs,
    random_seed = 2026,

    parallelproc = True,
    n_workers = 2,
    skip_estimated_models = True,
    include = {'sub': ['3000_04', '3042_04']},
    exclude = None
    )

Running without a configuration file; using resolved keyword arguments.
Subset the data files based on the following filter criteria and metadata at C:\Users\xyc6648\OneDrive - Northwestern University\Desktop\scripts\neuraspeech\neuraspeech\trf\misc\example_metadata.csv:
  Include: {'sub': ['3000_04', '3042_04']}
  Exclude: None
Using parallel processing with 2 workers (max available: 20).

The path arguments should be straightforward. Just provide the path to the prepared EEG data, the path to the predictor set you want to use (make sure that the set contains all predictors specified in your models), the output directory for the TRF results, and the path to the metadata spreadsheet (along with the name of the column that contains the EEG filenames).

Next, provide the model model, boosting configurations, and a random seed to ensure reproducibility.

The function also includes several control parameters:

parallelproc: Whether to use parallel processing. If True, multiple workers are used to run TRF models in parallel, with each worker assigned to handle one EEG data file at a time. If False, the data files will be processed sequentially, which may take a long time.
n_workers: Numner of workers to use. Set to None to use all available workers.
skip_estimated_models: Whether to skip models that have already been estimated. The function uses the model names in models to determine whether a model has already been fit. Therefore, if you later change the definition of an existing model such as the 'full' model, you should set skip_estimated_models = False to refit it.
include and exclude: Optional filters controlling which EEG data files are included in the analysis. Each filter should be specified as a dictionary, where the key is a metadata column name and the value is a list of levels to include or exclude. The column names used as keys must appear in the metadata spreadsheet. Here, we only include subjects '3000_04' and '3042_04'. As another example, if you have a column called 'condition' in the metadata and you only want to run TRFs for the quiet condition, you could do something like include = {'condition': ['Quiet']}. Set both arguments to None to disable filtering.

Each data file may take about 20-40 mins to run for the models defined here. The runtime can vary a lot depending on factors like EEG sampling rate, the number of predictors/models to fit, etc. In some cases, a single data file may take more than one hour.

The results directory will contain one subfolder for each EEG data file. Each subfolder is named after the EEG filename without the file extension (e.g., 'sub-3000_04_ses-1_task-alice'). Each subfolder should contain the fitted model objects, such as:

BoostingResults-full.pickle
BoostingResults-envelope_only.pickle
BoostingResults-onsets_only.pickle

Later in the data analysis section, we'll examine what these result objects contain and how to extract the relevant TRF results from them.

Using the configuration file¶

As in the previous steps, we can specify the settings in the configuration file and pass it to the function:

In [ ]:

Copied!

# Load the configuration. By default it loads from 'neuraspeech / trf/ conf / conf.yaml', but you can pass a path to a different configuration file.
config = ns.trf.load_config()
ns.trf.run_boosting(config)
# Load the configuration. By default it loads from 'neuraspeech / trf/ conf / conf.yaml', but you can pass a path to a different configuration file.
config = ns.trf.load_config()
ns.trf.run_boosting(config)

However, as mentioned, the recommended way is to submit the TRF analysis as a Slurm job to a computing cluster and run the models there with parallel processing, rather than running everything inside a notebook. See the Submitting Slurm jobs section for details.