Doc- clarify return types as instance of original type

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`_.

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",

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
         --------

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":

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

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).

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

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)

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

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.

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

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

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

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"])

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

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