FIX: Fix many docstrings

doc/source/python_reference.rst

@@ -578,6 +578,8 @@ Functions:
    apply_inverse
    apply_inverse_epochs
    apply_inverse_raw
+   compute_source_psd
+   compute_source_psd_epochs
    compute_rank_inverse
    estimate_snr
    make_inverse_operator
@@ -679,26 +681,40 @@ Time-Frequency
 
 .. currentmodule:: mne.time_frequency
 
+Classes:
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   AverageTFR
+
+Functions that operate on mne-python objects:
+
 .. autosummary::
    :toctree: generated/
    :template: function.rst
 
-   ar_raw
-   compute_raw_psd
+   compute_epochs_csd
    compute_epochs_psd
-   cwt_morlet
-   iir_filter_raw
-   morlet
+   compute_raw_psd
+   fit_iir_model_raw
    tfr_morlet
    tfr_multitaper
+   tfr_stockwell
+   read_tfrs
+   write_tfrs
+
+Functions that operate on ``np.ndarray`` objects:
+
+   cwt_morlet
+   dpss_windows
+   morlet
+   multitaper_psd
    single_trial_power
-   yule_walker
    stft
    istft
    stftfreq
-   tfr_stockwell
-   write_tfrs
-   read_tfrs
 
 
 Connectivity Estimation

doc/source/whats_new.rst

@@ -191,6 +191,8 @@ API
 
    - ``add_figs_to_section`` and ``add_images_to_section`` now have a ``textbox`` parameter to add comments to the image by `Teon Brooks`_
 
+   - Deprecated ``iir_filter_raw`` for ``fit_iir_model_raw``.
+
 .. _changes_0_8:
 
 Version 0.8

examples/time_frequency/plot_temporal_whitening.py

@@ -16,7 +16,7 @@
 import matplotlib.pyplot as plt
 
 import mne
-from mne.time_frequency import ar_raw
+from mne.time_frequency import fit_iir_model_raw
 from mne.datasets import sample
 
 print(__doc__)
@@ -38,14 +38,11 @@
 picks = picks[:5]
 
 # Estimate AR models on raw data
-coefs = ar_raw(raw, order=order, picks=picks, tmin=60, tmax=180)
-mean_coefs = np.mean(coefs, axis=0)  # mean model across channels
-
-filt = np.r_[1, -mean_coefs]  # filter coefficient
+b, a = fit_iir_model_raw(raw, order=order, picks=picks, tmin=60, tmax=180)
 d, times = raw[0, 1e4:2e4]  # look at one channel from now on
 d = d.ravel()  # make flat vector
-innovation = signal.convolve(d, filt, 'valid')
-d_ = signal.lfilter([1], filt, innovation)  # regenerate the signal
+innovation = signal.convolve(d, a, 'valid')
+d_ = signal.lfilter(b, a, innovation)  # regenerate the signal
 d_ = np.r_[d_[0] * np.ones(order), d_]  # dummy samples to keep signal length
 
 ###############################################################################

mne/beamformer/_dics.py

@@ -452,6 +452,8 @@ def tf_dics(epochs, forward, noise_csds, tmin, tmax, tstep, win_lengths,
         tf source grid.
     mode : str
         Spectrum estimation mode can be either: 'multitaper' or 'fourier'.
+    n_ffts : list | None
+        FFT lengths to use for each frequency bin.
     mt_bandwidths : list of float
         The bandwidths of the multitaper windowing function in Hz. Only used in
         'multitaper' mode. One value should be provided for each frequency bin.

mne/beamformer/_lcmv.py

@@ -451,13 +451,13 @@ def lcmv_raw(raw, forward, noise_cov, data_cov, reg=0.01, label=None,
         Index of first time sample (index not time is seconds).
     stop : int
         Index of first time sample not to include (index not time is seconds).
+    picks : array-like of int
+        Channel indices to use for beamforming (if None all channels
+        are used except bad channels).
     pick_ori : None | 'normal' | 'max-power'
         If 'normal', rather than pooling the orientations by taking the norm,
         only the radial component is kept. If 'max-power', the source
         orientation that maximizes output source power is chosen.
-    picks : array-like of int
-        Channel indices to use for beamforming (if None all channels
-        are used except bad channels).
     rank : None | int | dict
         Specified rank of the noise covariance matrix. If None, the rank is
         detected automatically. If int, the rank is specified for the MEG

mne/channels/channels.py

@@ -289,14 +289,14 @@ def pick_types(self, meg=True, eeg=False, stim=False, eog=False,
             gradiometer.
         eeg : bool
             If True include EEG channels.
+        stim : bool
+            If True include stimulus channels.
         eog : bool
             If True include EOG channels.
         ecg : bool
             If True include ECG channels.
         emg : bool
             If True include EMG channels.
-        stim : bool
-            If True include stimulus channels.
         ref_meg: bool | str
             If True include CTF / 4D reference channels. If 'auto', the
             reference channels are only included if compensations are present.

mne/cov.py

@@ -14,7 +14,7 @@
 from scipy import linalg
 
 from .io.write import start_file, end_file
-from .io.proj import (make_projector, proj_equal, activate_proj,
+from .io.proj import (make_projector, _proj_equal, activate_proj,
                       _has_eeg_average_ref_proj)
 from .io import fiff_open
 from .io.pick import (pick_types, channel_indices_by_type, pick_channels_cov,
@@ -97,7 +97,13 @@ def nfree(self):
         return self['nfree']
 
     def save(self, fname):
-        """Save covariance matrix in a FIF file"""
+        """Save covariance matrix in a FIF file
+
+        Parameters
+        ----------
+        fname : str
+            Output filename.
+        """
         check_fname(fname, 'covariance', ('-cov.fif', '-cov.fif.gz'))
 
         fid = start_file(fname)
@@ -188,11 +194,11 @@ def plot(self, info, exclude=[], colorbar=True, proj=False, show_svd=True,
             Show colorbar or not.
         proj : bool
             Apply projections or not.
-        show : bool
-            Call pyplot.show() as the end or not.
         show_svd : bool
             Plot also singular values of the noise covariance for each sensor
             type. We show square roots ie. standard deviations.
+        show : bool
+            Call pyplot.show() as the end or not.
         verbose : bool, str, int, or None
             If not None, override default verbose level (see mne.verbose).
 
@@ -587,7 +593,7 @@ def _unpack_epochs(epochs):
             if epochs_t.proj != epochs[0].proj:
                 raise ValueError('Epochs must agree on the use of projections')
             for proj_a, proj_b in zip(epochs_t.info['projs'], projs):
-                if not proj_equal(proj_a, proj_b):
+                if not _proj_equal(proj_a, proj_b):
                     raise ValueError('Epochs must have same projectors')
     else:
         projs = cp.deepcopy(projs)

mne/decoding/classifier.py

@@ -88,6 +88,8 @@ def transform(self, epochs_data, y=None):
         ----------
         epochs_data : array, shape=(n_epochs, n_channels, n_times)
             The data.
+        y : None
+            Not used.
 
         Returns
         -------
@@ -150,6 +152,8 @@ def transform(self, epochs_data, y=None):
         ----------
         epochs_data : array, shape=(n_epochs, n_channels, n_times)
             The data.
+        y : None
+            Not used.
 
         Returns
         -------
@@ -238,6 +242,8 @@ def transform(self, epochs_data, y=None):
         ----------
         epochs_data : array, shape=(n_epochs, n_channels, n_times)
             The data
+        y : None
+            Not used.
 
         Returns
         -------
@@ -389,6 +395,8 @@ def transform(self, epochs_data, y=None):
         ----------
         epochs_data : array, shape=(n_epochs, n_channels, n_times)
             The data.
+        y : None
+            Not used.
 
         Returns
         -------

mne/decoding/csp.py

@@ -189,6 +189,8 @@ def transform(self, epochs_data, y=None):
         ----------
         epochs_data : array, shape=(n_epochs, n_channels, n_times)
             The data.
+        y : None
+            Not used.
 
         Returns
         -------

mne/decoding/ems.py

@@ -12,7 +12,7 @@
 
 
 @verbose
-def compute_ems(epochs, conditions=None, picks=None, verbose=None, n_jobs=1):
+def compute_ems(epochs, conditions=None, picks=None, n_jobs=1, verbose=None):
     """Compute event-matched spatial filter on epochs
 
     This version operates on the entire time course. No time window needs to

mne/decoding/time_gen.py

@@ -68,15 +68,15 @@ class GeneralizationAcrossTime(object):
 
     Parameters
     ----------
-    clf : object | None
-        An estimator compliant with the scikit-learn API (fit & predict).
-        If None the classifier will be a standard pipeline including
-        StandardScaler and a linear SVM with default parameters.
     cv : int | object
         If an integer is passed, it is the number of folds.
         Specific cross-validation objects can be passed, see
         sklearn.cross_validation module for the list of possible objects.
         Defaults to 5.
+    clf : object | None
+        An estimator compliant with the scikit-learn API (fit & predict).
+        If None the classifier will be a standard pipeline including
+        StandardScaler and a linear SVM with default parameters.
     train_times : dict | None
         A dictionary to configure the training times.
         'slices' : np.ndarray, shape (n_clfs,)
@@ -284,6 +284,8 @@ def predict(self, epochs, test_times=None, picks=None):
                 one time sample.
 
             If None, empty dict. Defaults to None.
+        picks : np.ndarray (n_selected_chans,) | None
+            Channels to be included.
 
         Returns
         -------

mne/dipole.py

@@ -51,6 +51,8 @@ class Dipole(object):
         The dipole orientations (normalized to unit length).
     gof : array, shape (n_dipoles,)
         The goodness of fit.
+    name : str | None
+        Name of the dipole.
     """
     def __init__(self, times, pos, amplitude, ori, gof, name=None):
         self.times = times

mne/epochs.py

@@ -26,7 +26,7 @@
 from .io.constants import FIFF
 from .io.pick import (pick_types, channel_indices_by_type, channel_type,
                       pick_channels)
-from .io.proj import setup_proj, ProjMixin, proj_equal
+from .io.proj import setup_proj, ProjMixin, _proj_equal
 from .io.base import _BaseRaw, _time_as_index, _index_as_time, ToDataFrameMixin
 from .evoked import EvokedArray, aspect_rev
 from .baseline import rescale
@@ -590,14 +590,14 @@ def plot_psd_topomap(self, bands=None, vmin=None, vmax=None, proj=False,
             Apply projection.
         n_fft : int
             Number of points to use in Welch FFT calculations.
-        n_overlap : int
-            The number of points of overlap between blocks.
         ch_type : {None, 'mag', 'grad', 'planar1', 'planar2', 'eeg'}
             The channel type to plot. For 'grad', the gradiometers are
             collected in
             pairs and the RMS for each pair is plotted. If None, defaults to
             'mag' if MEG data are present and to 'eeg' if only EEG data are
             present.
+        n_overlap : int
+            The number of points of overlap between blocks.
         layout : None | Layout
             Layout instance specifying sensor positions (does not need to
             be specified for Neuromag data). If possible, the correct layout
@@ -668,8 +668,6 @@ class Epochs(_BaseEpochs, ToDataFrameMixin):
         Start time before event.
     tmax : float
         End time after event.
-    name : string
-        Comment that describes the Evoked data created.
     baseline : None or tuple of length 2 (default (None, 0))
         The time interval to apply baseline correction.
         If None do not apply it. If baseline is (a, b)
@@ -681,8 +679,9 @@ class Epochs(_BaseEpochs, ToDataFrameMixin):
         The baseline (a, b) includes both endpoints, i.e. all
         timepoints t such that a <= t <= b.
     picks : array-like of int | None (default)
-        Indices of channels to include (if None, all channels
-        are used).
+        Indices of channels to include (if None, all channels are used).
+    name : string
+        Comment that describes the Evoked data created.
     preload : boolean
         Load all epochs from disk when creating the object
         or wait before accessing each epoch (more memory
@@ -1191,6 +1190,18 @@ def __iter__(self):
 
     def next(self, return_event_id=False):
         """To make iteration over epochs easy.
+
+        Parameters
+        ----------
+        return_event_id : bool
+            If True, return both an epoch and and event_id.
+
+        Returns
+        -------
+        epoch : instance of Epochs
+            The epoch.
+        event_id : int
+            The event id. Only returned if ``return_event_id`` is ``True``.
         """
         if self.preload:
             if self._current >= len(self._data):
@@ -2284,7 +2295,7 @@ def _compare_epochs_infos(info1, info2, ind):
         raise ValueError('epochs[%d][\'info\'][\'ch_names\'] must match' % ind)
     if len(info2['projs']) != len(info1['projs']):
         raise ValueError('SSP projectors in epochs files must be the same')
-    if not all(proj_equal(p1, p2) for p1, p2 in
+    if not all(_proj_equal(p1, p2) for p1, p2 in
                zip(info2['projs'], info1['projs'])):
         raise ValueError('SSP projectors in epochs files must be the same')
 

mne/evoked.py

@@ -345,7 +345,7 @@ def shift_time(self, tshift, relative=True):
                                dtype=np.float) / sfreq
 
     def plot(self, picks=None, exclude='bads', unit=True, show=True, ylim=None,
-             proj=False, xlim='tight', hline=None, units=None, scalings=None,
+             xlim='tight', proj=False, hline=None, units=None, scalings=None,
              titles=None, axes=None):
         """Plot evoked data as butterfly plots
 
@@ -393,7 +393,7 @@ def plot(self, picks=None, exclude='bads', unit=True, show=True, ylim=None,
                            titles=titles, axes=axes)
 
     def plot_image(self, picks=None, exclude='bads', unit=True, show=True,
-                   clim=None, proj=False, xlim='tight', units=None,
+                   clim=None, xlim='tight', proj=False, units=None,
                    scalings=None, titles=None, axes=None, cmap='RdBu_r'):
         """Plot evoked data as images
 
@@ -484,6 +484,8 @@ def plot_topomap(self, times=None, ch_type='mag', layout=None, vmin=None,
             for grad and 1e15 for mag.
         scale_time : float | None
             Scale the time labels. Defaults to 1e3 (ms).
+        unit : str | None
+            The unit of the channel type used for colorbar labels.
         res : int
             The resolution of the topomap image (n pixels along each side).
         size : scalar
@@ -575,7 +577,7 @@ def plot_field(self, surf_maps, time=None, time_label='t = %0.0f ms',
         return plot_evoked_field(self, surf_maps, time=time,
                                  time_label=time_label, n_jobs=n_jobs)
 
-    def plot_white(self, noise_cov, scalings=None, show=True):
+    def plot_white(self, noise_cov, show=True):
         """Plot whitened evoked response
 
         Plots the whitened evoked response and the whitened GFP as described in

mne/filter.py

@@ -426,6 +426,8 @@ def construct_iir_filter(iir_params=dict(b=[1, 0], a=[1, 0], padlen=0),
     f_stop : float or list of float
         Stop-band frequency (same size as f_pass). Not used if 'order' is
         specified in iir_params.
+    sfreq : float | None
+        The sample rate.
     btype : str
         Type of filter. Should be 'lowpass', 'highpass', or 'bandpass'
         (or analogous string representations known to scipy.signal).