Predictors from tables¶

You can also build impulse-like predictors from tables or spreadsheets in which rows correspond to stimulus events and columns contain the impulse values. This is useful when you have stimulus features or annotations that were computed outside the neuraspeech workflow but want to include them as predictors. As long as these features can be saved as .csv tables or spreadsheets with one column listing the event timestamps and one or more additional columns containing predictor values, they can be converted into TRF predictors quickly and easily. Similar to predictors generated from TextGrid files, the resulting predictors are sparse arrays: they are filled with zeros except at the specified event times, where the predictor values are inserted.

Making predictors using tables¶

THis functionality is implemented in ns.trf.make_predictors_from_tables(), which takes .csv tables/spreadsheets like the one below. In this example, we create lexical/linguistic predictors containing surprisal values for the speech stimuli, with each surprisal value aligned to word onset and computed using a 5-gram language model:

Key arguments you may want to change or check:

• table_path: Path to the folder containing the table/spreadsheet files (.csv) for the stimuli. The files should have the same filenames as their corresponding audio files except for the file extension. For example, track1.csv should correspond to track1.wav.

• predictor_name: Name of the predictor to generate. In this example, we use lexical.

• target_tier: Name of the tier in the TextGrid files that contains the events you want to use.

• time_col: Name of the column in the tables listing the timestamps (in seconds) of stimulus events.

• val_cols: Name(s) of the column(s) containing the impulse values. It can be a list containing more than one column.

The surprisal predictors will be named like track1~lexical-surprisal.pickle.

Do a plot to visualize these predictors:

Again, if you set duration_mode = 'concat' during EEG data preparation, you'll need to run the EEG data preparation function to concatenate the newly genearated predictors.

Pro tips¶

1. Including or excluding specific events¶

You can pass dictionaries specifying inclusion/exclusion criteria to the include or exclude arguments to filter the tables before building the predictors. If you want to include only surprisals for content words and exclude those with with n-gram length of 1, you can do it like this:

2. Combining predictors¶

If your val_cols is a list containing more than one predictor and you want to include them in a single predictor file rather than as separate files (which is the default behavior), you can set merge_predictors = True as in the following example. Then the output predictor file for each stimulus track will be named like track1~lexical-2.pickle, where the suffix -2 indicates the number of predictors included.