#NEWLINE# @ verbose #NEWLINE# def compute_covariance( epochs , keep_sample_mean = True , tmin = None , tmax = None , projs = None , method = 'empirical' , method_params = None , cv = 3 , scalings = None , n_jobs = 1 , return_estimators = False , verbose = None ) : #NEWLINE# #INDENT# "Estimate noise covariance matrix from epochs.\n\n    The noise covariance is typically estimated on pre-stim periods\n    when the stim onset is defined from events.\n\n    If the covariance is computed for multiple event types (events\n    with different IDs), the following two options can be used and combined:\n\n        1. either an Epochs object for each event type is created and\n           a list of Epochs is passed to this function.\n        2. an Epochs object is created for multiple events and passed\n           to this function.\n\n    .. note:: Baseline correction should be used when creating the Epochs.\n              Otherwise the computed covariance matrix will be inaccurate.\n\n    .. note:: For multiple event types, it is also possible to create a\n              single Epochs object with events obtained using\n              merge_events(). However, the resulting covariance matrix\n              will only be correct if keep_sample_mean is True.\n\n    .. note:: The covariance can be unstable if the number of samples is\n              not sufficient. In that case it is common to regularize a\n              covariance estimate. The ``method`` parameter of this\n              function allows to regularize the covariance in an\n              automated way. It also allows to select between different\n              alternative estimation algorithms which themselves achieve\n              regularization. Details are described in [1]_.\n\n    Parameters\n    ----------\n    epochs : instance of Epochs, or a list of Epochs objects\n        The epochs.\n    keep_sample_mean : bool (default True)\n        If False, the average response over epochs is computed for\n        each event type and subtracted during the covariance\n        computation. This is useful if the evoked response from a\n        previous stimulus extends into the baseline period of the next.\n        Note. This option is only implemented for method='empirical'.\n    tmin : float | None (default None)\n        Start time for baseline. If None start at first sample.\n    tmax : float | None (default None)\n        End time for baseline. If None end at last sample.\n    projs : list of Projection | None (default None)\n        List of projectors to use in covariance calculation, or None\n        to indicate that the projectors from the epochs should be\n        inherited. If None, then projectors from all epochs must match.\n    method : str | list | None (default 'empirical')\n        The method used for covariance estimation. If 'empirical' (default),\n        the sample covariance will be computed. A list can be passed to run a\n        set of the different methods.\n        If 'auto' or a list of methods, the best estimator will be determined\n        based on log-likelihood and cross-validation on unseen data as\n        described in [1]_. Valid methods are:\n\n            * ``'empirical'``: the empirical or sample covariance\n            * ``'diagonal_fixed'``: a diagonal regularization as in\n              mne.cov.regularize (see MNE manual)\n            * ``'ledoit_wolf'``: the Ledoit-Wolf estimator [2]_\n            * ``'shrunk'``: like 'ledoit_wolf' with cross-validation for\n              optimal alpha (see scikit-learn documentation on covariance\n              estimation)\n            * ``'pca'``: probabilistic PCA with low rank [3]_\n            * ``'factor_analysis'``: Factor Analysis with low rank [4]_\n\n        If ``'auto'``, this expands to::\n\n             ['shrunk', 'diagonal_fixed', 'empirical', 'factor_analysis']\n\n        .. note:: ``'ledoit_wolf'`` and ``'pca'`` are similar to\n           ``'shrunk'`` and ``'factor_analysis'``, respectively. They are not\n           included to avoid redundancy. In most cases ``'shrunk'`` and\n           ``'factor_analysis'`` represent more appropriate default\n           choices.\n\n        The ``'auto'`` mode is not recommended if there are many\n        segments of data, since computation can take a long time.\n\n        .. versionadded:: 0.9.0\n\n    method_params : dict | None (default None)\n        Additional parameters to the estimation procedure. Only considered if\n        method is not None. Keys must correspond to the value(s) of `method`.\n        If None (default), expands to::\n\n            'empirical': {'store_precision': False, 'assume_centered': True},\n            'diagonal_fixed': {'grad': 0.01, 'mag': 0.01, 'eeg': 0.0,\n                               'store_precision': False,\n                               'assume_centered': True},\n            'ledoit_wolf': {'store_precision': False, 'assume_centered': True},\n            'shrunk': {'shrinkage': np.logspace(-4, 0, 30),\n                       'store_precision': False, 'assume_centered': True},\n            'pca': {'iter_n_components': None},\n            'factor_analysis': {'iter_n_components': None}\n\n    cv : int | sklearn cross_validation object (default 3)\n        The cross validation method. Defaults to 3, which will\n        internally trigger a default 3-fold shuffle split.\n    scalings : dict | None (default None)\n        Defaults to ``dict(mag=1e15, grad=1e13, eeg=1e6)``.\n        These defaults will scale magnetometers and gradiometers\n        at the same unit.\n    n_jobs : int (default 1)\n        Number of jobs to run in parallel.\n    return_estimators : bool (default False)\n        Whether to return all estimators or the best. Only considered if\n        method equals 'auto' or is a list of str. Defaults to False\n    verbose : bool | str | int | or None (default None)\n        If not None, override default verbose level (see mne.verbose).\n\n    Returns\n    -------\n    cov : instance of Covariance | list\n        The computed covariance. If method equals 'auto' or is a list of str\n        and return_estimators equals True, a list of covariance estimators is\n        returned (sorted by log-likelihood, from high to low, i.e. from best\n        to worst).\n\n    See Also\n    --------\n    compute_raw_covariance : Estimate noise covariance from raw data\n\n    References\n    ----------\n    .. [1] Engemann D. and Gramfort A. (2015) Automated model selection in\n           covariance estimation and spatial whitening of MEG and EEG\n           signals, vol. 108, 328-342, NeuroImage.\n    .. [2] Ledoit, O., Wolf, M., (2004). A well-conditioned estimator for\n           large-dimensional covariance matrices. Journal of Multivariate\n           Analysis 88 (2), 365 - 411.\n    .. [3] Tipping, M. E., Bishop, C. M., (1999). Probabilistic principal\n           component analysis. Journal of the Royal Statistical Society:\n           Series B (Statistical Methodology) 61 (3), 611 - 622.\n    .. [4] Barber, D., (2012). Bayesian reasoning and machine learning.\n           Cambridge University Press., Algorithm 21.1\n    " #NEWLINE# accepted_methods = ( 'auto' , 'empirical' , 'diagonal_fixed' , 'ledoit_wolf' , 'shrunk' , 'pca' , 'factor_analysis' ) #NEWLINE# msg = ( 'Invalid method ({method}). Accepted values (individually or in a list) are "%s"' % '" or "' . join ( ( accepted_methods + ( 'None' , ) ) ) ) #NEWLINE# if isinstance ( scalings , dict ) : #NEWLINE# #INDENT# for ( k , v ) in scalings . items ( ) : #NEWLINE# #INDENT# if ( k not in ( 'mag' , 'grad' , 'eeg' ) ) : #NEWLINE# #INDENT# raise ValueError ( ( 'The keys in `scalings` must be "mag" or"grad" or "eeg". You gave me: %s' % k ) ) #NEWLINE# #UNINDENT# #UNINDENT# #UNINDENT# scalings = _handle_default ( 'scalings' , scalings ) #NEWLINE# _method_params = { #NEWLINE# #INDENT# 'empirical' : { #NEWLINE# #INDENT# 'store_precision' : False , #NEWLINE# 'assume_centered' : True , #NEWLINE# #UNINDENT# } , #NEWLINE# 'diagonal_fixed' : { #NEWLINE# #INDENT# 'grad' : 0.01 , #NEWLINE# 'mag' : 0.01 , #NEWLINE# 'eeg' : 0.0 , #NEWLINE# 'store_precision' : False , #NEWLINE# 'assume_centered' : True , #NEWLINE# #UNINDENT# } , #NEWLINE# 'ledoit_wolf' : { #NEWLINE# #INDENT# 'store_precision' : False , #NEWLINE# 'assume_centered' : True , #NEWLINE# #UNINDENT# } , #NEWLINE# 'shrunk' : { #NEWLINE# #INDENT# 'shrinkage' : np . logspace ( ( - 4 ) , 0 , 30 ) , #NEWLINE# 'store_precision' : False , #NEWLINE# 'assume_centered' : True , #NEWLINE# #UNINDENT# } , #NEWLINE# 'pca' : { #NEWLINE# #INDENT# 'iter_n_components' : None , #NEWLINE# #UNINDENT# } , #NEWLINE# 'factor_analysis' : { #NEWLINE# #INDENT# 'iter_n_components' : None , #NEWLINE# #UNINDENT# } , #NEWLINE# #UNINDENT# } #NEWLINE# if isinstance ( method_params , dict ) : #NEWLINE# #INDENT# for ( key , values ) in method_params . items ( ) : #NEWLINE# #INDENT# if ( key not in _method_params ) : #NEWLINE# #INDENT# raise ValueError ( ( 'key (%s) must be "%s"' % ( key , '" or "' . join ( _method_params ) ) ) ) #NEWLINE# #UNINDENT# _method_params [ key ] . update ( method_params [ key ] ) #NEWLINE# #UNINDENT# #UNINDENT# def _unpack_epochs( epochs ) : #NEWLINE# #INDENT# if ( len ( epochs . event_id ) > 1 ) : #NEWLINE# #INDENT# epochs = [ epochs [ k ] for k in epochs . event_id ] #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# epochs = [ epochs ] #NEWLINE# #UNINDENT# return epochs #NEWLINE# #UNINDENT# if ( not isinstance ( epochs , list ) ) : #NEWLINE# #INDENT# epochs = _unpack_epochs ( epochs ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# epochs = sum ( [ _unpack_epochs ( epoch ) for epoch in epochs ] , [ ] ) #NEWLINE# #UNINDENT# for epochs_t in epochs : #NEWLINE# #INDENT# if ( ( epochs_t . baseline is None ) and ( epochs_t . info [ 'highpass' ] < 0.5 ) and keep_sample_mean ) : #NEWLINE# #INDENT# warn ( 'Epochs are not baseline corrected, covariance matrix may be inaccurate' ) #NEWLINE# #UNINDENT# #UNINDENT# for epoch in epochs : #NEWLINE# #INDENT# epoch . info . _check_consistency ( ) #NEWLINE# #UNINDENT# bads = epochs [ 0 ] . info [ 'bads' ] #NEWLINE# if ( projs is None ) : #NEWLINE# #INDENT# projs = cp . deepcopy ( epochs [ 0 ] . info [ 'projs' ] ) #NEWLINE# for epochs_t in epochs [ 1 : ] : #NEWLINE# #INDENT# if ( epochs_t . proj != epochs [ 0 ] . proj ) : #NEWLINE# #INDENT# raise ValueError ( 'Epochs must agree on the use of projections' ) #NEWLINE# #UNINDENT# for ( proj_a , proj_b ) in zip ( epochs_t . info [ 'projs' ] , projs ) : #NEWLINE# #INDENT# if ( not _proj_equal ( proj_a , proj_b ) ) : #NEWLINE# #INDENT# raise ValueError ( 'Epochs must have same projectors' ) #NEWLINE# #UNINDENT# #UNINDENT# #UNINDENT# #UNINDENT# else : #NEWLINE# #INDENT# projs = cp . deepcopy ( projs ) #NEWLINE# #UNINDENT# ch_names = epochs [ 0 ] . ch_names #NEWLINE# for epochs_t in epochs [ 1 : ] : #NEWLINE# #INDENT# if ( epochs_t . info [ 'bads' ] != bads ) : #NEWLINE# #INDENT# raise ValueError ( 'Epochs must have same bad channels' ) #NEWLINE# #UNINDENT# if ( epochs_t . ch_names != ch_names ) : #NEWLINE# #INDENT# raise ValueError ( 'Epochs must have same channel names' ) #NEWLINE# #UNINDENT# #UNINDENT# picks_list = _picks_by_type ( epochs [ 0 ] . info ) #NEWLINE# picks_meeg = np . concatenate ( [ b for ( _ , b ) in picks_list ] ) #NEWLINE# picks_meeg = np . sort ( picks_meeg ) #NEWLINE# ch_names = [ epochs [ 0 ] . ch_names [ k ] for k in picks_meeg ] #NEWLINE# info = epochs [ 0 ] . info #NEWLINE# if ( method == 'auto' ) : #NEWLINE# #INDENT# method = [ 'shrunk' , 'diagonal_fixed' , 'empirical' , 'factor_analysis' ] #NEWLINE# #UNINDENT# if ( not isinstance ( method , ( list , tuple ) ) ) : #NEWLINE# #INDENT# method = [ method ] #NEWLINE# #UNINDENT# ok_sklearn = ( check_version ( 'sklearn' , '0.15' ) is True ) #NEWLINE# if ( ( not ok_sklearn ) and ( ( len ( method ) != 1 ) or ( method [ 0 ] != 'empirical' ) ) ) : #NEWLINE# #INDENT# raise ValueError ( 'scikit-learn is not installed, `method` must be `empirical`' ) #NEWLINE# #UNINDENT# if ( keep_sample_mean is False ) : #NEWLINE# #INDENT# if ( ( len ( method ) != 1 ) or ( 'empirical' not in method ) ) : #NEWLINE# #INDENT# raise ValueError ( '`keep_sample_mean=False` is only supportedwith `method="empirical"`' ) #NEWLINE# #UNINDENT# for ( p , v ) in _method_params . items ( ) : #NEWLINE# #INDENT# if ( v . get ( 'assume_centered' , None ) is False ) : #NEWLINE# #INDENT# raise ValueError ( '`assume_centered` must be True if `keep_sample_mean` is False' ) #NEWLINE# #UNINDENT# #UNINDENT# n_epoch_types = len ( epochs ) #NEWLINE# data_mean = ( [ 0 ] * n_epoch_types ) #NEWLINE# n_samples = np . zeros ( n_epoch_types , dtype = np . int ) #NEWLINE# n_epochs = np . zeros ( n_epoch_types , dtype = np . int ) #NEWLINE# for ( ii , epochs_t ) in enumerate ( epochs ) : #NEWLINE# #INDENT# tslice = _get_tslice ( epochs_t , tmin , tmax ) #NEWLINE# for e in epochs_t : #NEWLINE# #INDENT# e = e [ ( picks_meeg , tslice ) ] #NEWLINE# if ( not keep_sample_mean ) : #NEWLINE# #INDENT# data_mean [ ii ] += e #NEWLINE# #UNINDENT# n_samples [ ii ] += e . shape [ 1 ] #NEWLINE# n_epochs [ ii ] += 1 #NEWLINE# #UNINDENT# #UNINDENT# n_samples_epoch = ( n_samples // n_epochs ) #NEWLINE# norm_const = np . sum ( ( n_samples_epoch * ( n_epochs - 1 ) ) ) #NEWLINE# data_mean = [ ( ( 1.0 / n_epoch ) * np . dot ( mean , mean . T ) ) for ( n_epoch , mean ) in zip ( n_epochs , data_mean ) ] #NEWLINE# #UNINDENT# if ( not all ( ( ( k in accepted_methods ) for k in method ) ) ) : #NEWLINE# #INDENT# raise ValueError ( msg . format ( method = method ) ) #NEWLINE# #UNINDENT# info = pick_info ( info , picks_meeg ) #NEWLINE# tslice = _get_tslice ( epochs [ 0 ] , tmin , tmax ) #NEWLINE# epochs = [ ee . get_data ( ) [ : , picks_meeg , tslice ] for ee in epochs ] #NEWLINE# picks_meeg = np . arange ( len ( picks_meeg ) ) #NEWLINE# picks_list = _picks_by_type ( info ) #NEWLINE# if ( len ( epochs ) > 1 ) : #NEWLINE# #INDENT# epochs = np . concatenate ( epochs , 0 ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# epochs = epochs [ 0 ] #NEWLINE# #UNINDENT# epochs = np . hstack ( epochs ) #NEWLINE# n_samples_tot = epochs . shape [ ( - 1 ) ] #NEWLINE# _check_n_samples ( n_samples_tot , len ( picks_meeg ) ) #NEWLINE# epochs = epochs . T #NEWLINE# if ok_sklearn : #NEWLINE# #INDENT# cov_data = _compute_covariance_auto ( epochs , method = method , method_params = _method_params , info = info , verbose = verbose , cv = cv , n_jobs = n_jobs , stop_early = True , picks_list = picks_list , scalings = scalings ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# if ( _method_params [ 'empirical' ] [ 'assume_centered' ] is True ) : #NEWLINE# #INDENT# cov = ( epochs . T . dot ( epochs ) / n_samples_tot ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# cov = np . cov ( epochs . T , bias = 1 ) #NEWLINE# #UNINDENT# cov_data = { #NEWLINE# #INDENT# 'empirical' : { #NEWLINE# #INDENT# 'data' : cov , #NEWLINE# #UNINDENT# } , #NEWLINE# #UNINDENT# } #NEWLINE# #UNINDENT# if ( keep_sample_mean is False ) : #NEWLINE# #INDENT# cov = cov_data [ 'empirical' ] [ 'data' ] #NEWLINE# cov *= n_samples_tot #NEWLINE# for mean_cov in data_mean : #NEWLINE# #INDENT# cov -= mean_cov #NEWLINE# #UNINDENT# cov /= norm_const #NEWLINE# #UNINDENT# covs = list ( ) #NEWLINE# for ( this_method , data ) in cov_data . items ( ) : #NEWLINE# #INDENT# cov = Covariance ( data . pop ( 'data' ) , ch_names , info [ 'bads' ] , projs , nfree = n_samples_tot ) #NEWLINE# logger . info ( ( 'Number of samples used : %d' % n_samples_tot ) ) #NEWLINE# logger . info ( '[done]' ) #NEWLINE# cov . update ( method = this_method , ** data ) #NEWLINE# covs . append ( cov ) #NEWLINE# #UNINDENT# if ok_sklearn : #NEWLINE# #INDENT# msg = [ 'log-likelihood on unseen data (descending order):' ] #NEWLINE# logliks = [ ( c [ 'method' ] , c [ 'loglik' ] ) for c in covs ] #NEWLINE# logliks . sort ( reverse = True , key = ( lambda c : c [ 1 ] ) ) #NEWLINE# for ( k , v ) in logliks : #NEWLINE# #INDENT# msg . append ( ( '%s: %0.3f' % ( k , v ) ) ) #NEWLINE# #UNINDENT# logger . info ( '\n   ' . join ( msg ) ) #NEWLINE# #UNINDENT# if ( ok_sklearn and ( not return_estimators ) ) : #NEWLINE# #INDENT# ( keys , scores ) = zip ( * [ ( c [ 'method' ] , c [ 'loglik' ] ) for c in covs ] ) #NEWLINE# out = covs [ np . argmax ( scores ) ] #NEWLINE# logger . info ( 'selecting best estimator: {0}' . format ( out [ 'method' ] ) ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# if ok_sklearn : #NEWLINE# #INDENT# out = covs #NEWLINE# out . sort ( key = ( lambda c : c [ 'loglik' ] ) , reverse = True ) #NEWLINE# #UNINDENT# else : #NEWLINE# #INDENT# out = covs [ 0 ] #NEWLINE# #UNINDENT# #UNINDENT# return out