brainiak.utils package¶
Utilities used by multiple subpackages.
Submodules¶
brainiak.utils.fmrisim module¶
fMRI Simulator
Simulate fMRI data for a single subject.
This code provides a set of functions necessary to produce realistic simulations of neural data.
Steps:
generate_signal Specify the volume (or volumes) which represent the signal in the neural data.
generate_stimfunction Create a function to describe the stimulus onsets/durations
export_stimfunction: Generate a three column timing file that can be used with software like FSL
double_gamma_hrf Convolve the stimulus function with the HRF to model when events are expected.
apply_signal Combine the volume and the HRF
calc_noise Estimate the noise properties of a given volume
generate_noise Create the noise for this run. This creates temporal, task and white noise. Various parameters can be tuned depending on need
mask_brain Mask the volume to look like a volume. Based on MNI standard space
plot_brain Show the brain as it unfolds over time with a given opacity.
Authors: Cameron Ellis (Princeton) 20162017 Chris Baldassano (Princeton) 20162017

brainiak.utils.fmrisim.
generate_signal
(dimensions, feature_coordinates, feature_size, feature_type, signal_magnitude=[1], signal_constant=1)¶ Generate volume containing signal
Generate signal in specific regions of the brain with for a single volume. This will then be convolved with the HRF across time
Parameters:  dimensions (1d array, ndarray) – What are the dimensions of the volume you wish to create
 feature_coordinates (multidimensional array) – What are the feature_coordinates of the signal being created. Be aware of clipping: features far from the centre of the brain will be clipped. If you wish to have multiple features then list these as an features x 3 array. To create a signal of a specific shape then supply all the individual feature_coordinates and set the feature_size to 1.
 feature_size (list, int) – How big is the signal. If m=1 then only one value is accepted, if m>1 then either one value must be supplied or m values
 feature_type (list, string) – What feature_type of signal is being inserted? Options are cube, loop, cavity, sphere. If features = 1 then only one value is accepted, if features > 1 then either one value must be supplied or m values
 signal_magnitude (list, float) – What is the (average) magnitude of the signal being generated? A value of 1 means that the signal is one standard deviation from the noise
 signal_constant (list, bool) – Is the signal constant or is it a random pattern (with the same average magnitude)
Returns: volume_static – Creates a single volume containing the signal
Return type: 3 dimensional array, float

brainiak.utils.fmrisim.
generate_stimfunction
(onsets, event_durations, total_time, weights=[1], timing_file=None, temporal_resolution=1000.0)¶ Return the function for the onset of events
When do stimuli onset, how long for and to what extent should you resolve the fMRI time course. There are two ways to create this, either by supplying onset, duration and weight information or by supplying a timing file (in the three column format)
Parameters:  onsets (list, int) – What are the timestamps for when an event you want to generate onsets?
 event_durations (list, int) – What are the durations of the events you want to generate? If there is only one value then this will be assigned to all onsets
 total_time (int) – How long is the experiment in total.
 weights (list, float) – How large is the box car for each of the onsets. If there is only one value then this will be assigned to all onsets
 timing_file (string) – The filename (with path) to a three column timing file (FSL) to make the events. Still requires tr_duration and total_time
 temporal_resolution (float) – How many elements per second are you modeling for the stim function
Returns: The time course of stimulus related activation
Return type: Iterable[float]

brainiak.utils.fmrisim.
export_stimfunction
(stimfunction, filename, temporal_resolution=1000.0)¶ Output a tab separated timing file
This produces a three column tab separated text file, with the three columns representing onset time, event duration and weight, respectively
Useful if you want to run the simulated data through FEAT analyses
Parameters:  stimfunction (list) – The stimulus function describing the time course of events
 filename (str) – The name of the three column text file to be output
 temporal_resolution (float) – How many elements per second are you modeling for the stim function

brainiak.utils.fmrisim.
double_gamma_hrf
(stimfunction, tr_duration, response_delay=6, undershoot_delay=12, response_dispersion=0.9, undershoot_dispersion=0.9, response_scale=1, undershoot_scale=0.035, scale_function=1, temporal_resolution=1000.0)¶ Return a double gamma HRF
Parameters:  stimfunction (list, bool) – What is the time course of events to be modelled in this experiment
 tr_duration (float) –
 response_delay (float) – How many seconds until the peak of the HRF
 undershoot_delay (float) – How many seconds until the trough of the HRF
 response_dispersion (float) – How wide is the rising peak dispersion
 undershoot_dispersion (float) – How wide is the undershoot dispersion
 response_scale (float) – How big is the response relative to the peak
 undershoot_scale (float) – How big is the undershoot relative to the trough
 scale_function (bool) – Do you want to scale the function to a range of 1
 temporal_resolution (float) – How many elements per second are you modeling for the stim function
Returns: The time course of the HRF convolved with the stimulus function
Return type: one dimensional array

brainiak.utils.fmrisim.
apply_signal
(signal_function, volume_static)¶ Apply the convolution and stimfunction
Apply the convolution of the HRF and stimulus time course to the volume.
Parameters:  signal_function (list, float) – The one dimensional timecourse of the signal over time. Found by convolving the HRF with the stimulus time course.
 volume_static (multi dimensional array, float) –
Returns: Generates the spatial noise volume for these parameters
Return type: multidimensional array, float

brainiak.utils.fmrisim.
calc_noise
(volume, mask=None, noise_dict=None)¶ Calculates the noise properties of the volume supplied. This estimates what noise properties the volume has. For instance it determines the spatial smoothness, the autoregressive noise, system noise etc. Read the doc string for generate_noise to understand how these different types of noise interact.
Parameters:  volume (4d numpy array, float) – Take in a functional volume (either the file name or the numpy array) to be used to estimate the noise properties of this
 mask (4d numpy array, float) – The mask to be used, the same size as the volume
Returns:  dict
 Return a dictionary of the calculated noise parameters of the provided
 dataset

brainiak.utils.fmrisim.
generate_noise
(dimensions, stimfunction_tr, tr_duration, mask=None, noise_dict=None)¶ Generate the noise to be added to the signal. Default noise parameters will create a noise volume with a standard deviation of 0.1 (where the signal defaults to a value of 1). This has built into estimates of how different types of noise mix. All noise values can be set by the user
Parameters:  dimensions (nd array) – What is the shape of the volume to be generated
 stimfunction_tr (Iterable, list) – When do the stimuli events occur. Each element is a TR
 tr_duration (float) – What is the duration, in seconds, of each TR?
 mask (4d array, float) – The mask of the brain volume, using
 noise_dict (dictionary, float) – This is a dictionary which describes the noise parameters of the data. If there are no other variables provided then it will default values
Returns: Generates the noise volume for these parameters
Return type: multidimensional array, float

brainiak.utils.fmrisim.
mask_brain
(volume, mask_name=None, mask_threshold=0.1, mask_self=0)¶ Mask the simulated volume This takes in a volume and will output the masked volume. if a one dimensional array is supplied then the output will be a volume of the dimensions specified in the array. The mask can be created from the volume by averaging it. All masks will be bounded to the range of 0 to 1.
Parameters:  volume (multidimensional array) – Either numpy array of the volume that has been simulated or a tuple describing the dimensions of the mask to be created
 mask_name (str) – What is the path to the mask to be loaded? If empty then it defaults to an MNI152 grey matter mask.
 mask_threshold (float) – What is the threshold (0 > 1) for including a voxel in the mask?
 mask_self (bool) – If set to true then it makes a mask from the volume supplied (by averaging across time points and changing the range).
Returns: mask – The masked brain
Return type: multidimensional array, float

brainiak.utils.fmrisim.
plot_brain
(fig, brain, mask=None, percentile=99)¶ Display the brain that has been generated with a given threshold
Parameters:  fig (matplotlib object) – The figure to be displayed, generated from matplotlib. import matplotlib.pyplot as plt; fig = plt.figure()
 brain (3d array) – This is a 3d array with the neural data
 mask (3d array) – A binary mask describing the location that you want to specify as
 percentile (float) – What percentage of voxels will be included? Based on the values supplied
Returns: ax – Object with the information to be plotted
Return type: matplotlib object
brainiak.utils.utils module¶

class
brainiak.utils.utils.
ReadDesign
(fname=None, include_orth=True, include_pols=True)¶ Bases:
object
 A class which has the ability of reading in design matrix in .1D file,
 generated by AFNI’s 3dDeconvolve.
Parameters:  fname (string, the address of the file to read.) –
 include_orth (Boollean, whether to include “orthogonal” regressors in) – the nuisance regressors which are usually head motion parameters. All the columns of design matrix are still going to be read in, but the attribute cols_used will reflect whether these orthogonal regressors are to be included for furhter analysis. Note that these are not entered into design_task attribute which include only regressors related to task conditions.
 include_pols (Boollean, whether to include polynomial regressors in) – the nuisance regressors which are used to capture slow drift of signals.

design
¶ 2d array. The design matrix read in from the csv file.

design_task
¶ 2d array. The part of design matrix corresponding to – task conditions.

n_col
¶ number of total columns in the design matrix.

column_types
¶ 1d array. the types of each column in the design matrix. – 0 for orthogonal regressors (usually head motion parameters), 1 for polynomial basis (capturing slow drift of signals), values > 0 for stimulus conditions

n_basis
¶ scalar. The number of polynomial bases in the designn matrix.

n_stim
¶ scalar. The number of stimulus conditions.

n_orth
¶ scalar. The number of orthogoanal regressors (usually head – motions)

StimLabels
¶ list. The names of each column in the design matrix.

read_afni
(fname)¶

brainiak.utils.utils.
concatenate_not_none
(l, axis=0)¶ Construct a numpy array by stacking notNone arrays in a list
Parameters:  data (list of arrays) – The list of arrays to be concatenated. Arrays have same shape in all but one dimension or are None, in which case they are ignored.
 axis (int, default = 0) – Axis for the concatenation
Returns: data_stacked – The resulting concatenated array.
Return type: array

brainiak.utils.utils.
cov2corr
(cov)¶  Calculate the correlation matrix based on a
 covariance matrix
Parameters: cov (2D array) – Returns: corr – correlation converted from the covarince matrix Return type: 2D array

brainiak.utils.utils.
from_sym_2_tri
(symm)¶  convert a 2D symmetric matrix to an upper
 triangular matrix in 1D format
Parameters: symm (2D array) – Symmetric matrix Returns: tri – Contains elements of upper triangular matrix Return type: 1D array

brainiak.utils.utils.
from_tri_2_sym
(tri, dim)¶  convert a upper triangular matrix in 1D format
 to 2D symmetric matrix
Parameters:  tri (1D array) – Contains elements of upper triangular matrix
 dim (int) – The dimension of target matrix.
Returns: symm – Symmetric matrix in shape=[dim, dim]
Return type: 2D array

brainiak.utils.utils.
gen_design
(stimtime_files, scan_duration, TR, style=’FSL’, hrf_para={‘response_delay’: 6, ’undershoot_delay’: 12, ’undershoot_scale’: 0.035, ’undershoot_dispersion’: 0.9, ’response_dispersion’: 0.9})¶  Generate design matrix based on a list of names of stimulus
 timing files. The function will read each file, and generate a numpy array of size [time_points * condition], where time_points equals duration / TR, and condition is the size of stimtime_filenames. Each column is the hypothetical fMRI response based on the stimulus timing in the corresponding file of stimtime_files. This function uses generate_stimfunction and double_gamma_hrf of brainiak.utils.fmrisim.
Parameters:  stimtime_files (a string or a list of string.) – Each string is the name of the file storing the stimulus timing information of one task condition. The contents in the files will be interpretated based on the style parameter. Details are explained under the style parameter.
 scan_duration (float or a list (or a 1D numpy array) of numbers.) – Total duration of each fMRI scan, in unit of seconds. If there are multiple runs, the duration should be a list (or 1d numpy array) of numbers. If it is a list, then each number in the list represents the duration of the corresponding scan in the stimtime_files. If only a number is provided, it is assumed that there is only one fMRI scan lasting for scan_duration.
 TR (float.) – The sampling period of fMRI, in unit of seconds.
 style (string, default: ‘FSL’) –
Acceptable inputs: ‘FSL’, ‘AFNI’ The formating style of the stimtime_files. ‘FSL’ style has one line for each event of the same condition. Each line contains three numbers. The first number is the onset of the event relative to the onset of the first scan, in units of seconds. (Multiple scans should be treated as a concatenated long scan for the purpose of calculating onsets. However, the design matrix from one scan won’t leak into the next). The second number is the duration of the event, in unit of seconds. The third number is the amplitude modulation (or weight) of the response. It is acceptable to not provide the weight, or not provide both duration and weight. In such cases, these parameters will default to 1.0.
’AFNI’ style has one line for each scan (run). Each line has a few triplets in the format of stim_onsets*weight:duration (or simpler, see below), separated by spaces. For example, 3.2*2.0:1.5 means that one event starts at 3.2s, modulated by weight of 2.0 and lasts for 1.5s. If some run does not include a single event of a condition (stimulus type), then you can put *, or a negative number, or a very large number in that line. Either duration or weight can be neglected. In such cases, they will default to 1.0. For example, 3.0, 3.0*1.0, 3.0:1.0 and 3.0*1.0:1.0 all means an event starting at 3.0s, lasting for 1.0s, with amplitude modulation of 1.0.
Returns: design – design matrix. Each time row represents one TR (fMRI sampling time point) and each column represents one experiment condition, in the order in stimtime_files
Return type: 2D numpy array

brainiak.utils.utils.
sumexp_stable
(data)¶ Compute the sum of exponents for a list of samples
Parameters: data (array, shape=[features, samples]) – A data array containing samples. Returns:  result_sum (array, shape=[samples,]) – The sum of exponents for each sample divided by the exponent of the maximum feature value in the sample.
 max_value (array, shape=[samples,]) – The maximum feature value for each sample.
 result_exp (array, shape=[features, samples]) – The exponent of each element in each sample divided by the exponent of the maximum feature value in the sample.
Note
This function is more stable than computing the sum(exp(v)). It useful for computing the softmax_i(v)=exp(v_i)/sum(exp(v)) function.