diff --git a/doc/changes/dev/13674.other.rst b/doc/changes/dev/13674.other.rst new file mode 100644 index 00000000000..576f70dcf57 --- /dev/null +++ b/doc/changes/dev/13674.other.rst @@ -0,0 +1 @@ +Improve documentation of return values to clarify that methods typically return the original instance type for chaining purposes, by `Aniket Singh Yadav`_. diff --git a/doc/conf.py b/doc/conf.py index 126d8f365a1..2fc68dca974 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -318,13 +318,18 @@ numpydoc_xref_ignore = { # words "and", + "as", "between", + "data", "instance", "instances", + "input", "of", "default", + "same", "shape", "or", + "the", "with", "length", "pair", diff --git a/mne/_fiff/meas_info.py b/mne/_fiff/meas_info.py index 92a4cf58531..fbb602caf2f 100644 --- a/mne/_fiff/meas_info.py +++ b/mne/_fiff/meas_info.py @@ -397,7 +397,7 @@ def set_montage( Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The instance, modified in-place. See Also @@ -539,7 +539,7 @@ def set_channel_types(self, mapping, *, on_unit_change="warn", verbose=None): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The instance (modified in place). .. versionchanged:: 0.20 @@ -642,7 +642,7 @@ def rename_channels( Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The instance (modified in place). .. versionchanged:: 0.20 @@ -787,7 +787,7 @@ def anonymize(self, daysback=None, keep_his=False, verbose=None): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The modified instance. Notes @@ -816,8 +816,8 @@ def set_meas_date(self, meas_date): Returns ------- - inst : instance of Raw | Epochs | Evoked - The modified raw instance. Operates in place. + inst : same type as the input data + The modified instance. Operates in place. See Also -------- diff --git a/mne/_fiff/proj.py b/mne/_fiff/proj.py index aa010085904..65125c45d3d 100644 --- a/mne/_fiff/proj.py +++ b/mne/_fiff/proj.py @@ -243,7 +243,7 @@ def add_proj(self, projs, remove_existing=False, verbose=None): Returns ------- - self : instance of Raw | Epochs | Evoked + self : same type as the input data The data container. """ if isinstance(projs, Projection): @@ -283,7 +283,7 @@ def apply_proj(self, verbose=None): Returns ------- - self : instance of Raw | Epochs | Evoked + self : same type as the input data The instance. Notes @@ -362,7 +362,7 @@ def del_proj(self, idx="all"): Returns ------- - self : instance of Raw | Epochs | Evoked + self : same type as the input data The instance. """ if isinstance(idx, str) and idx == "all": diff --git a/mne/_fiff/reference.py b/mne/_fiff/reference.py index 13fed0eebd2..3b654ee7784 100644 --- a/mne/_fiff/reference.py +++ b/mne/_fiff/reference.py @@ -228,7 +228,7 @@ def add_reference_channels(inst, ref_channels, copy=True): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data Data with added EEG reference channels. Notes @@ -396,7 +396,7 @@ def set_eeg_reference( Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data Data with EEG channels re-referenced. If ``ref_channels="average"`` and ``projection=True`` a projection will be added instead of directly re-referencing the data. @@ -575,7 +575,7 @@ def set_bipolar_reference( Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data Data with the specified channels re-referenced. See Also diff --git a/mne/channels/channels.py b/mne/channels/channels.py index d337353c49c..ab54bf200dd 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -325,7 +325,7 @@ def set_eeg_reference( Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data Data with EEG channels re-referenced. If ``ref_channels='average'`` and ``projection=True`` a projection will be added instead of directly re-referencing the data. @@ -388,7 +388,7 @@ def pick_types( Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. See Also @@ -463,7 +463,7 @@ def pick_channels(self, ch_names, ordered=True, *, verbose=None): Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. See Also @@ -501,7 +501,7 @@ def pick(self, picks, exclude=(), *, verbose=None): Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. """ picks = _picks_to_idx(self.info, picks, "all", exclude, allow_empty=False) @@ -532,7 +532,7 @@ def reorder_channels(self, ch_names): Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. See Also @@ -569,7 +569,7 @@ def drop_channels(self, ch_names, on_missing="raise"): Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. See Also @@ -691,7 +691,7 @@ def add_channels(self, add_list, force_update_info=False): Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. See Also @@ -812,7 +812,7 @@ def add_reference_channels(self, ref_channels): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The modified instance. """ return add_reference_channels(self, ref_channels, copy=False) @@ -878,7 +878,7 @@ def interpolate_bads( Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data The modified instance. Notes @@ -1006,7 +1006,7 @@ def interpolate_to( Returns ------- - inst : instance of Raw, Epochs, or Evoked + inst : same type as the input data A new instance with interpolated data and updated channel information. @@ -2015,7 +2015,7 @@ def combine_channels( Returns ------- - combined_inst : instance of Raw, Epochs, or Evoked + combined_inst : same type as the input data An MNE-Python object of the same type as the input ``inst``, containing one virtual channel for each group in ``groups`` (and, if ``keep_stim`` is ``True``, also containing stimulus channels). diff --git a/mne/filter.py b/mne/filter.py index 304afdf4de7..f8f4abf6499 100644 --- a/mne/filter.py +++ b/mne/filter.py @@ -2387,7 +2387,7 @@ def savgol_filter(self, h_freq, verbose=None): Returns ------- - inst : instance of Epochs, Evoked or SourceEstimate + inst : same type as the input data The object with the filtering applied. See Also @@ -2480,7 +2480,7 @@ def filter( Returns ------- - inst : instance of Epochs, Evoked, SourceEstimate, or Raw + inst : same type as the input data The filtered data. See Also @@ -2616,7 +2616,7 @@ def resample( Returns ------- - inst : instance of Epochs or Evoked + inst : same type as the input data The resampled object. See Also diff --git a/mne/io/base.py b/mne/io/base.py index e2cc3e3c757..ec5ce7594e4 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -2185,11 +2185,11 @@ def close(self): pass # noqa def copy(self): - """Return copy of Raw instance. + """Return copy of the instance. Returns ------- - inst : instance of Raw + inst : same type as the input data A copy of the instance. """ return deepcopy(self) diff --git a/mne/preprocessing/_csd.py b/mne/preprocessing/_csd.py index 35a32e90245..b2c9bf1fa8b 100644 --- a/mne/preprocessing/_csd.py +++ b/mne/preprocessing/_csd.py @@ -90,7 +90,7 @@ def compute_current_source_density( Returns ------- - inst_csd : instance of Raw, Epochs or Evoked + inst_csd : same type as the input data The transformed data. Output type will match input type. Notes diff --git a/mne/preprocessing/_regress.py b/mne/preprocessing/_regress.py index d7d54c637d6..6c866b6e421 100644 --- a/mne/preprocessing/_regress.py +++ b/mne/preprocessing/_regress.py @@ -63,7 +63,7 @@ def regress_artifact( Returns ------- - inst : instance of Epochs | Raw + inst : same type as the input data The processed data. betas : ndarray, shape (n_picks, n_picks_ref) The betas used during regression. diff --git a/mne/preprocessing/eyetracking/eyetracking.py b/mne/preprocessing/eyetracking/eyetracking.py index 5c95b5c4d78..afdf0d6c033 100644 --- a/mne/preprocessing/eyetracking/eyetracking.py +++ b/mne/preprocessing/eyetracking/eyetracking.py @@ -40,7 +40,7 @@ def set_channel_types_eyetrack(inst, mapping): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The instance, modified in place. Notes @@ -179,7 +179,7 @@ def convert_units(inst, calibration, to="radians"): Returns ------- - inst : instance of Raw | Epochs | Evoked + inst : same type as the input data The Raw, Epochs, or Evoked instance, modified in place. Notes diff --git a/mne/preprocessing/ica.py b/mne/preprocessing/ica.py index 9b98ef9b2d4..38ce20a4318 100644 --- a/mne/preprocessing/ica.py +++ b/mne/preprocessing/ica.py @@ -1247,7 +1247,7 @@ def get_sources(self, inst, add_channels=None, start=None, stop=None): Returns ------- - sources : instance of Raw, Epochs or Evoked + sources : same type as the input data The ICA sources time series. """ if isinstance(inst, BaseRaw): @@ -2221,7 +2221,7 @@ def apply( Returns ------- - out : instance of Raw, Epochs or Evoked + out : same type as the input data The processed data. Notes diff --git a/mne/preprocessing/interpolate.py b/mne/preprocessing/interpolate.py index e0152bbf2dc..e934e158fab 100644 --- a/mne/preprocessing/interpolate.py +++ b/mne/preprocessing/interpolate.py @@ -101,7 +101,7 @@ def interpolate_bridged_electrodes(inst, bridged_idx, bad_limit=4): Returns ------- - inst : instance of Epochs, Evoked, or Raw + inst : same type as the input data The modified data object. See Also diff --git a/mne/preprocessing/stim.py b/mne/preprocessing/stim.py index a823820988b..ca8e15cf64e 100644 --- a/mne/preprocessing/stim.py +++ b/mne/preprocessing/stim.py @@ -94,7 +94,7 @@ def fix_stim_artifact( Returns ------- - inst : instance of Raw or Evoked or Epochs + inst : same type as the input data Instance with modified data. """ _check_option("mode", mode, ["linear", "window", "constant"]) diff --git a/mne/simulation/evoked.py b/mne/simulation/evoked.py index 2b225727dfe..9805e520496 100644 --- a/mne/simulation/evoked.py +++ b/mne/simulation/evoked.py @@ -117,7 +117,7 @@ def add_noise(inst, cov, iir_filter=None, random_state=None, verbose=None): Returns ------- - inst : instance of Evoked, Epochs, or Raw + inst : same type as the input data The instance, modified to have additional noise. Notes diff --git a/mne/utils/mixin.py b/mne/utils/mixin.py index 741636115e2..f0d4b9f7524 100644 --- a/mne/utils/mixin.py +++ b/mne/utils/mixin.py @@ -603,7 +603,7 @@ def crop(self, tmin=None, tmax=None, include_tmax=True, verbose=None): Returns ------- - inst : instance of Raw, Epochs, Evoked, AverageTFR, or SourceEstimate + inst : same type as the input data The cropped time-series object, modified in-place. Notes