supereeg.Model¶

class supereeg.Model(data=None, locs=None, template=None, numerator=None, denominator=None, n_subs=None, meta=None, date_created=None, rbf_width=20, save=None)[source]¶

Model data object for the supereeg package

This class holds your supereeg model. To create an instance, pass a list of brain objects and the model will be generated from those brain objects. You can also add your own model by passing a numpy array as your matrix and the corresponding locations. Alternatively, you can bypass creating a new model by passing numerator, denominator, locations, and n_subs (see parameters for details). Additionally, you can include a meta dictionary with any other information that you want to save with the model.

Parameters:	data : supereeg.Brain or list supereeg.Brain, supereeg.Nifti or list supereeg.Nifti, or Numpy.ndarray A supereeg.Brain object or supereeg.Nifti object, list of objects, or a Numpy.ndarray of your model. locs : pandas.DataFrame or np.ndarray MNI coordinate (x,y,z) by number of electrode df containing electrode locations template : filepath Path to a template nifti file used to set model locations numerator : Numpy.ndarray (Optional) A locations x locations matrix comprising the sum of the log z-transformed correlation matrices over subjects. If used, must also pass denominator, locs and n_subs. Otherwise, numerator will be computed from the brain object data. denominator : Numpy.ndarray (Optional) A locations x locations matrix comprising the sum of the log (weighted) number of subjects contributing to each matrix cell. If used, must also pass numerator, locs and n_subs. Otherwise, denominator will be computed from the brain object data. n_subs : int The number of subjects used to create the model. Required if you pass numerator/denominator. Otherwise computed automatically from the data. rbf_width : positive scalar The width of the radial basis function (RBF) used as a spatial prior for smoothing estimates at nearby locations. (Default: 20) meta : dict Dict containing whatever you want: Initialized with a stability field {‘stable’:True}. This is changed to {‘stable’:False} after subtraction performed. date created : str Time created save : None Optional filename to save created model
Returns:	model : supereeg.Model instance A model that can be used to infer timeseries from unknown locations
Attributes:	numerator : Numpy.ndarray A locations x locations matrix comprising the sum of the log z-transformed correlation matrices over subjects denominator : Numpy.ndarray A locations x locations matrix comprising the log sum of the (weighted) number of subjects contributing to each matrix cell n_subs : int Number of subject used to create the model

Methods

`get_locs`()	Returns the locations in the model
`get_model`([z_transform])	Returns a copy of the model in the form of a correlation matrix
`get_slice`(loc_inds[, inplace])	Indexes brain object data
`info`()	Print info about the model object Prints the number of electrodes, number of subjects, date created, and any optional meta data.
`plot_data`([savefile, show])	Plot the supereeg model as a correlation matrix This function wraps seaborn’s heatmap and accepts any inputs that seaborn supports for models less than 2000x2000.
`plot_locs`([pdfpath])	Plots electrode locations from brain object
`predict`(bo[, nearest_neighbor, ...])	Takes a brain object and a ‘full’ covariance model, fills in all
`save`(fname[, compression])	Save method for the model object The data will be saved as a ‘mo’ file, which is a dictionary containing the elements of a model object saved in the hd5 format using deepdish.
`set_locs`(new_locs[, force_include_bo_locs])	update self.locs to a new set of locations (and blur the correlation matrix accordingly). if
`update`(data[, inplace])	Update a model with new data.

get_locs()[source]¶: Returns the locations in the model

get_model(z_transform=False)[source]¶: Returns a copy of the model in the form of a correlation matrix

get_slice(loc_inds, inplace=False)[source]¶

Indexes brain object data

Parameters:	sample_inds : int or list Times you wish to index loc_inds : int or list Locations you with to index inplace : bool If True, indexes in place.

info()[source]¶: Print info about the model object Prints the number of electrodes, number of subjects, date created, and any optional meta data.

plot_data(savefile=None, show=True, **kwargs)[source]¶

Plot the supereeg model as a correlation matrix This function wraps seaborn’s heatmap and accepts any inputs that seaborn supports for models less than 2000x2000. If the model is larger, the plot cannot be generated without specifying a savefile.

Parameters:	show : bool If False, image not rendered (default : True)
Returns:	ax : matplotlib.Axes An axes object

plot_locs(pdfpath=None)[source]¶

Plots electrode locations from brain object

Parameters:	pdfpath : str A name for the file. If the file extension (.pdf) is not specified, it will be appended.

predict(bo, nearest_neighbor=False, match_threshold='auto', force_update=False, force_include_bo_locs=True, preprocess='zscore', recon_loc_inds=None)[source]¶

Takes a brain object and a ‘full’ covariance model, fills in all electrode timeseries for all missing locations and returns the new brain object

Parameters:

Parameters:	bo : a Brain, Nifti, or Model object that will be converted to a Brain object. nearest_neighbor : True Default finds the nearest voxel for each subject’s electrode location and uses that as revised electrodes location matrix in the prediction. match_threshold : ‘auto’ or int auto: if match_threshold auto, ignore all electrodes whose distance from the nearest matching voxel is greater than the maximum voxel dimension If value is greater than 0, inlcudes only electrodes that are within that distance of matched voxel force_update : False If True, will update model with patient’s correlation matrix. force_include_bo_locs : True If True, and if force_update = False, update the locations in the model to include the locations in the given brain object prior to generating the predictions. If force_update = True, this parameter is forced to be True (force_update requires updating the locations) and the specified value is ignored. preprocess : ‘zscore’ or None The predict algorithm requires the data to be zscored. However, if your data are already zscored you can bypass this by setting to None. recon_at_loc : electrode ind or None Index for estimated location in model (location in unknown_inds)
Returns:	bo_p : supereeg.Brain New brain data object with missing electrode locations filled in

bo : a Brain, Nifti, or Model object that will be converted to a Brain object.
nearest_neighbor : True: Default finds the nearest voxel for each subject’s electrode location and uses that as revised electrodes location matrix in the prediction.
match_threshold : ‘auto’ or int: auto: if match_threshold auto, ignore all electrodes whose distance from the nearest matching voxel is greater than the maximum voxel dimension If value is greater than 0, inlcudes only electrodes that are within that distance of matched voxel
force_update : False: If True, will update model with patient’s correlation matrix.
force_include_bo_locs : True: If True, and if force_update = False, update the locations in the model to include the locations in the given brain object prior to generating the predictions. If force_update = True, this parameter is forced to be True (force_update requires updating the locations) and the specified value is ignored.
preprocess : ‘zscore’ or None: The predict algorithm requires the data to be zscored. However, if your data are already zscored you can bypass this by setting to None.
recon_at_loc : electrode ind or None: Index for estimated location in model (location in unknown_inds)

Returns:

bo_p : supereeg.Brain: New brain data object with missing electrode locations filled in

save(fname, compression='blosc')[source]¶

Save method for the model object The data will be saved as a ‘mo’ file, which is a dictionary containing the elements of a model object saved in the hd5 format using deepdish.

Parameters:	fname : str A name for the file. If the file extension (.mo) is not specified, it will be appended. compression : str The kind of compression to use. See the deepdish documentation for options: http://deepdish.readthedocs.io/en/latest/api_io.html#deepdish.io.save

set_locs(new_locs, force_include_bo_locs=False)[source]¶: update self.locs to a new set of locations (and blur the correlation matrix accordingly). if force_include_bo_locs is True (default: False), the final set of locations will also include the old locations.

update(data, inplace=True)[source]¶

Update a model with new data.

Parameters:	data : supereeg.Brain, supereeg.Nifti, supereeg.Model (or a mixed list of these) New data inplace : bool Whether to run update in place or return a new model (default True).
Returns:	model : supereeg.Model A new updated model object