brainiak.eventseg package¶
Event segmentation of continuous data + event transfer between datasets.
Submodules¶
brainiak.eventseg.event module¶
Event segmentation using a Hidden Markov Model
Given an ROI timeseries, this class uses an annealed fitting procedure to segment the timeseries into events with stable activity patterns. After learning the signature activity pattern of each event, the model can then be applied to other datasets to identify a corresponding sequence of events.
Full details are available in: Christopher Baldassano, Janice Chen, Asieh Zadbood, Jonathan W Pillow, Uri Hasson, Kenneth A Norman Discovering event structure in continuous narrative perception and memory Neuron, Volume 95, Issue 3, 709  721.e5 https://doi.org/10.1016/j.neuron.2017.06.041
This class also extends the model described in the Neuron paper: 1) It allows transition matrices that are composed of multiple separate chains of events rather than a single linear path. This allows a model to contain patterns for multiple event sequences (e.g. narratives), and fit probabilities along each of these chains on a new, unlabeled timeseries. To use this option, pass in an event_chain vector labeling which events belong to each chain, define event patterns using set_event_patterns(), then fit to a new dataset with find_events.
2) To obtain better fits when the underlying event structure contains events that vary substantially in length, the split_merge option allows the fit() function to redistribute events during fitting. The number of merge/split proposals is controlled by split_merge_proposals, which controls how thorough versus fast the fitting process is.

class
brainiak.eventseg.event.
EventSegment
(n_events=2, step_var=<function EventSegment._default_var_schedule>, n_iter=500, event_chains=None, split_merge=False, split_merge_proposals=1)¶ Bases:
sklearn.base.BaseEstimator
Class for event segmentation of continuous fMRI data
 Parameters
n_events (int) – Number of segments to learn
step_var (Callable[[int], float] : default 4 * (0.98 ** (step  1))) – The Gaussian variance to use during fitting, as a function of the number of steps. Should decrease slowly over time.
n_iter (int, default: 500) – Maximum number of steps to run during fitting
event_chains (ndarray with length = n_events) – Array with unique value for each separate chain of events, each linked in the order they appear in the array
split_merge (bool, default: False) – Determines whether merge/split proposals are used during fitting with fit(). This can improve fitting performance when events are highly uneven in size, but requires additional time
split_merge_proposals (int, default: 1) – Number of merges and splits to consider at each step. Computation time scales as O(proposals^2) so this should usually be a small value

p_start, p_end
initial and final prior distributions over events
 Type
length n_events+1 ndarray

P
¶ HMM transition matrix
 Type
n_events+1 by n_events+1 ndarray

ll_
¶ Loglikelihood for training datasets over the course of training
 Type
ndarray with length = number of training datasets

segments_
¶ Learned (soft) segmentation for training datasets
 Type
list of (time by event) ndarrays

event_var_
¶ Gaussian variance at the end of learning
 Type
float

event_pat_
¶ Learned mean patterns for each event
 Type
voxel by event ndarray

calc_weighted_event_var
(D, weights, event_pat)¶ Computes normalized weighted variance around event pattern
Utility function for computing variance in a training set of weighted event examples. For each event, the sum of squared differences for all timepoints from the event pattern is computed, and then the weights specify how much each of these differences contributes to the variance (normalized by the number of voxels).
 Parameters
D (timepoint by voxel ndarray) – fMRI data for which to compute event variances
weights (timepoint by event ndarray) – specifies relative weights of timepoints for each event
event_pat (voxel by event ndarray) – mean event patterns to compute variance around
 Returns
ev_var
 Return type
ndarray of variances for each event

find_events
(testing_data, var=None, scramble=False)¶ Applies learned event segmentation to new testing dataset
After fitting an event segmentation using fit() or setting event patterns directly using set_event_patterns(), this function finds the same sequence of event patterns in a new testing dataset.
 Parameters
testing_data (timepoint by voxel ndarray) – fMRI data to segment based on previouslylearned event patterns
var (float or 1D ndarray of length equal to the number of events) – default: uses variance that maximized training loglikelihood Variance of the event Gaussians. If scalar, all events are assumed to have the same variance. If fit() has not previously been run, this must be specifed (cannot be None).
scramble (bool : default False) – If true, the order of the learned events are shuffled before fitting, to give a null distribution
 Returns
segments (time by event ndarray) – The resulting soft segmentation. segments[t,e] = probability that timepoint t is in event e
test_ll (float) – Loglikelihood of model fit

fit
(X, y=None)¶ Learn a segmentation on training data
Fits event patterns and a segmentation to training data. After running this function, the learned event patterns can be used to segment other datasets using find_events
 Parameters
X (time by voxel ndarray, or a list of such ndarrays) – fMRI data to be segmented. If a list is given, then all datasets are segmented simultaneously with the same event patterns
y (not used (added to comply with BaseEstimator definition)) –
 Returns
self
 Return type
the EventSegment object

model_prior
(t)¶ Returns the prior probability of the HMM
Runs forwardbackward without any data, showing the prior distribution of the model (for comparison with a posterior).
 Parameters
t (int) – Number of timepoints
 Returns
segments (time by event ndarray) – segments[t,e] = prior probability that timepoint t is in event e
test_ll (float) – Loglikelihood of model (dataindependent term)

predict
(X)¶ Applies learned event segmentation to new testing dataset
Alternative function for segmenting a new dataset after using fit() to learn a sequence of events, to comply with the sklearn Classifier interface
 Parameters
X (timepoint by voxel ndarray) – fMRI data to segment based on previouslylearned event patterns
 Returns
 Return type
Event label for each timepoint

set_event_patterns
(event_pat)¶ Set HMM event patterns manually
Rather than fitting the event patterns automatically using fit(), this function allows them to be set explicitly. They can then be used to find corresponding events in a new dataset, using find_events().
 Parameters
event_pat (voxel by event ndarray) –