U f{jI@sddlZddlZddlmZmZmZddlmZddl m Z ddl m Z m Z mZeGdd d eZdd d Zd dZddZddZddZdddZdddZeedZdS)N)get_coef BaseEstimator_check_estimator)TimeDelayingRidge) is_regressor)_validate_typeverbosefill_docc @sReZdZdZedddZdd Zdd d Zd d ZddZ ddZ dddZ dS)ReceptiveFieldaRFit a receptive field model. This allows you to fit an encoding model (stimulus to brain) or a decoding model (brain to stimulus) using time-lagged input features (for example, a spectro- or spatio-temporal receptive field, or STRF) :footcite:`TheunissenEtAl2001,WillmoreSmyth2003,CrosseEtAl2016,HoldgrafEtAl2016`. Parameters ---------- tmin : float The starting lag, in seconds (or samples if ``sfreq`` == 1). tmax : float The ending lag, in seconds (or samples if ``sfreq`` == 1). Must be >= tmin. sfreq : float The sampling frequency used to convert times into samples. feature_names : array, shape (n_features,) | None Names for input features to the model. If None, feature names will be auto-generated from the shape of input data after running `fit`. estimator : instance of sklearn.base.BaseEstimator | float | None The model used in fitting inputs and outputs. This can be any scikit-learn-style model that contains a fit and predict method. If a float is passed, it will be interpreted as the ``alpha`` parameter to be passed to a Ridge regression model. If `None`, then a Ridge regression model with an alpha of 0 will be used. fit_intercept : bool | None If True (default), the sample mean is removed before fitting. If ``estimator`` is a :class:`sklearn.base.BaseEstimator`, this must be None or match ``estimator.fit_intercept``. scoring : ['r2', 'corrcoef'] Defines how predictions will be scored. Currently must be one of 'r2' (coefficient of determination) or 'corrcoef' (the correlation coefficient). patterns : bool If True, inverse coefficients will be computed upon fitting using the covariance matrix of the inputs, and the cross-covariance of the inputs/outputs, according to :footcite:`HaufeEtAl2014`. Defaults to False. n_jobs : int | str Number of jobs to run in parallel. Can be 'cuda' if CuPy is installed properly and ``estimator is None``. .. versionadded:: 0.18 edge_correction : bool If True (default), correct the autocorrelation coefficients for non-zero delays for the fact that fewer samples are available. Disabling this speeds up performance at the cost of accuracy depending on the relationship between epoch length and model duration. Only used if ``estimator`` is float or None. .. versionadded:: 0.18 %(verbose)s Attributes ---------- coef_ : array, shape ([n_outputs, ]n_features, n_delays) The coefficients from the model fit, reshaped for easy visualization. During :meth:`mne.decoding.ReceptiveField.fit`, if ``y`` has one dimension (time), the ``n_outputs`` dimension here is omitted. patterns_ : array, shape ([n_outputs, ]n_features, n_delays) If fit, the inverted coefficients from the model. delays_ : array, shape (n_delays,), dtype int The delays used to fit the model, in indices. To return the delays in seconds, use ``self.delays_ / self.sfreq`` valid_samples_ : slice The rows to keep during model fitting after removing rows with missing values due to time delaying. This can be used to get an output equivalent to using :func:`numpy.convolve` or :func:`numpy.correlate` with ``mode='valid'``. See Also -------- mne.decoding.TimeDelayingRidge Notes ----- For a causal system, the encoding model will have significant non-zero values only at positive lags. In other words, lags point backward in time relative to the input, so positive lags correspond to previous input time samples, while negative lags correspond to future input time samples. References ---------- .. footbibliography:: Nr2FTc CsP||_t||_||_||_|dkr(dn||_||_||_||_| |_ | |_ dS)Ng) feature_namesfloatsfreqtmintmax estimator fit_interceptscoringpatternsn_jobsedge_correction) selfrrrrrrrrrrr r[/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/decoding/receptive_field.py__init__js zReceptiveField.__init__cCsd|j|jf}|j}t|ts*t|j}|d|f7}t|dr|jdk r|j}t|dkrp|d|d7}n|d|d|df7}|d 7}n|d 7}t|d r|d |j 7}d |S)Nztmin, tmax : (%.3f, %.3f), zestimator : %s, coef_rz feature: %s, rzfeatures : [%s, ..., %s], z fit: Truez fit: FalseZscores_z scored (%s)z) rrr isinstancestrtypehasattrrlenr)rsrZfeatsrrr__repr__ys        zReceptiveField.__repr__cCsTt|jtsLt||j|j|j|jd}t|}|dk rL|j d|j ddd}||fS)z Delay and reshape the variables.) fill_meanNrForder) r estimator_r_delay_time_seriesrrrr_reshape_for_estreshapeshape)rXyrrr_delay_and_reshapes z!ReceptiveField._delay_and_reshapec Csddlm}|jtkr4tdtt|jfddlm}| ||\}}}|_ |j |j krvtd|j |j ft |j |j |j|_t|j|_t|jtjr|jdkrd|_t|j |j |j|j|j|j|jd}n`t|jr(||j}|jdk r|j|jkrtd |j|jf|j|_ntd t|j||_~t|j|j\}}} |jd } t|j} |j dk rt|j | krtd | t|j f|!||\}}|j"||t#|jd } | | g} |j dkr| $dd | %| |_&|j'rt|jtr:|jj(t)||d}|j%d |jd dd}n||j*ddd}t+,|j-}~|j.dkr|jddkr||j*ddd}|/t+,|j-}ndt)||d}~t+%|j&| | | f} |0| 0|}|%| |_1|S)aFit a receptive field model. Parameters ---------- X : array, shape (n_times[, n_epochs], n_features) The input features for the model. y : array, shape (n_times[, n_epochs][, n_outputs]) The output features for the model. Returns ------- self : instance The instance so you can chain operations. r)linalgz!scoring must be one of %s, got%s )clonez#tmin (%s) must be at most tmax (%s)NT)alpharrrzEstimator fit_intercept (%s) != initialization fit_intercept (%s), initialize ReceptiveField with the same fit_intercept value or use fit_intercept=NonezK`estimator` must be a float or an instance of `BaseEstimator`, got type %s.rz7n_features in X does not match feature names (%s != %s)rrr'r()Zkeepdimsrg?)2Zscipyr2r_SCORERSkeys ValueErrorsortedZ sklearn.baser3_check_dimensions_y_dimrr_times_to_delaysrdelays__delays_to_slicevalid_samples_rrnumbersRealrrrrrr!r*rr.r#rr1fitrinsertr-rrcov_rmeannpZcovTndimZpinvdotZ patterns_)rr/r0r2r3_rn_timesn_epochsn_feats n_outputsn_delaysZcoefr.rCZinv_YrrrrrAs                         zReceptiveField.fitcCst|dstd|j|ddddd\}}}~|jdd}|jdkr\||jjd f}||\}}|j|}|j |d d }t |j}|d kr| dd }nd}|d|j|}||_|S) aGenerate predictions with a receptive field. Parameters ---------- X : array, shape (n_times[, n_epochs], n_channels) The input features for the model. Returns ------- y_pred : array, shape (n_times[, n_epochs][, n_outputs]) The output predictions. "Note that valid samples (those unaffected by edge artifacts during the time delaying step) can be obtained using ``y_pred[rf.valid_samples_]``. r<zEstimator has not been fit yet.NTpredictrrrr'r(r) r"r7r9r.r:rr1r*rPr-listpop)rr/rIX_dimZ pred_shapey_predr.extrarrrrPs$     zReceptiveField.predictc Cst|j}|j||dddd\}}|j\}}}||}||j}||j}|jd|gdd}|jd|gdd}|j|jkst|||dd }|S) aScore predictions generated with a receptive field. This calls ``self.predict``, then masks the output of this and ``y` with ``self.valid_samples_``. Finally, it passes this to a :mod:`sklearn.metrics` scorer. Parameters ---------- X : array, shape (n_times[, n_epochs], n_channels) The input features for the model. y : array, shape (n_times[, n_epochs][, n_outputs]) Used for scikit-learn compatibility. Returns ------- scores : list of float, shape (n_outputs,) The scores estimated by the model for each output (e.g. mean R2 of ``predict(X)``). TrONrrr'r( raw_values multioutput)r5rr9r.rPr>r-AssertionError) rr/r0Zscorer_rJrKrMrUZscoresrrrscore$s     zReceptiveField.scorecCs|j}|dk r|jnd}|dkr|ddtjddf}|dk r|dkr`|ddtjtjf}q|dkr|ddtjddf}qtd|jfnZ|jdkr|dk r|jdkr|ddddtjf}q|jdkrtdntd|jf|dk r|jd|jdkr*td|jd|jdf|jd|jdkr\td |jd|jdf|r|jd t|jjkrtd ||||fS) Nrrrz8y must be shape (n_times[, n_epochs][,n_outputs], got %srQz4If X has 3 dimensions, y must have 2 or 3 dimensionsz9X must be shape (n_times[, n_epochs], n_features), got %sz-X and y do not have the same n_times %s != %sz.X and y do not have the same n_epochs %s != %srzBNumber of outputs does not match estimator coefficients dimensions)rGrEnewaxisr7r.r#r*r)rr/r0rPrTZy_dimrrrr9IsB     z ReceptiveField._check_dimensions)NNNr FNTN)N)F) __name__ __module__ __qualname____doc__r rr%r1rArPr[r9rrrrr s W  g$%r Fc Cst|||t|||}t|jt|f}|rp|jdd}|jdkrVtj|dd}|ddtjf|dd<t |D]\}} | dkr|d| d|f} || d} n:| dkr|| dd|f} |d| } n|d|f} |} | | dd<|rx| dd|| jdd7<qx|S)aReturn a time-lagged input time series. Parameters ---------- X : array, shape (n_times[, n_epochs], n_features) The time series to delay. Must be 2D or 3D. tmin : int | float The starting lag. tmax : int | float The ending lag. Must be >= tmin. sfreq : int | float The sampling frequency of the series. Defaults to 1.0. fill_mean : bool If True, the fill value will be the mean along the time dimension of the feature, and each cropped and delayed segment of data will be shifted to have the same mean value (ensuring that mean subtraction works properly). If False, the fill value will be zero. Returns ------- delayed : array, shape(n_times[, n_epochs][, n_features], n_delays) The delayed data. It has the same shape as X, with an extra dimension appended to the end. Examples -------- >>> tmin, tmax = -0.1, 0.2 >>> sfreq = 10. >>> x = np.arange(1, 6) >>> x_del = _delay_time_series(x, tmin, tmax, sfreq) >>> print(x_del) # doctest:+SKIP [[2. 1. 0. 0.] [3. 2. 1. 0.] [4. 3. 2. 1.] [5. 4. 3. 2.] [0. 5. 4. 3.]] r)ZaxisrQN.) _check_delayer_paramsr;rEZzerosr.r#rDrGr\ enumerate) r/rrrr&delaysZdelayedZ mean_valueiiZix_delayoutZuse_Xrrrr+ns*'      "r+cCs0ttt||tt||d}|S)z)Convert a tmin/tmax in seconds to delays.r)rEZarangeintround)rrrrcrrrr;sr;cCs:|ddkrdn|d}|ddkr(dn|d}t||S)z=Find the slice to be taken in order to remove missing values.rrN)slice)rcZ min_delayZ max_delayrrrr=sr=cCs:t|dd||fD]}t|ddq||ks6tddS)z@Check delayer input parameters. For future custom delay support.numericz`sfreq`z tmin/tmaxztmin must be <= tmaxN)r r7)rrrZtlimrrrras   racCs4|j\}}}}|||d}|j||ddd}|S)z,Convert X_del to a sklearn-compatible shape.rr'r()r.r-)ZX_delrJrKrLrNrrrr,sr,csfddlm|dkstfD]}|jdkr td|jfq tfddtjdDS) Nr)pearsonrrWrz/inputs must be shape (samples, outputs), got %scs2g|]*}dd|fdd|fdqS)Nrr).0rdrjr0y_truerr sz_corr_score..r) Z scipy.statsrjrZrGr7r.rEarrayrange)rmr0rYZthis_yrrlr _corr_scores     rqcCsddlm}||||dS)Nr)r2_scorerX)Zsklearn.metricsrr)rmr0rYrrrrr _r2_scores rs)r Zcorrcoef)F)N)N)r?numpyrEbaserrrZtime_delaying_ridgerfixesrutilsr r r r r+r;r=rar,rqrsr5rrrrs"  ^ A