Fix docstrings [docs only]

Author: matteobachetti

stingray/crossspectrum.py

@@ -2381,7 +2381,7 @@ def trace_maximum(self, min_freq=None, max_freq=None):
         return np.array(max_positions)
 
     def shift_and_add(self, f0_list, nbins=100, output_obj_type=AveragedCrossspectrum, rebin=None):
-        """Shift and add the dynamical power spectrum.
+        """Shift and add the dynamical cross spectrum.
 
         This is the basic operation for the shift-and-add operation used to track
         kHz QPOs in X-ray binaries (e.g. Méndez et al. 1998, ApJ, 494, 65).
@@ -2404,6 +2404,10 @@ def shift_and_add(self, f0_list, nbins=100, output_obj_type=AveragedCrossspectru
         rebin : int, default None
             Rebin the final spectrum by this factor. At the moment, the rebinning
             is linear.
+        output_obj_type : class, default :class:`AveragedCrossspectrum`
+            The type of the output object. Can be, e.g. :class:`AveragedCrossspectrum` or
+            :class:`AveragedPowerspectrum`.
+
         Returns
         -------
         output: :class:`AveragedPowerspectrum` or :class:`AveragedCrossspectrum`

stingray/powerspectrum.py

@@ -1049,6 +1049,52 @@ def __init__(self, lc=None, segment_size=None, norm="frac", gti=None, sample_tim
         self._make_matrix(lc)
 
     def shift_and_add(self, f0_list, nbins=100, rebin=None):
+        """Shift-and-add the dynamical power spectrum.
+
+        This is the basic operation for the shift-and-add operation used to track
+        kHz QPOs in X-ray binaries (e.g. Méndez et al. 1998, ApJ, 494, 65).
+
+        Parameters
+        ----------
+        freqs : np.array
+            Array of frequencies, the same for all powers. Must be sorted and on a uniform
+            grid.
+        power_list : list of np.array
+            List of power spectra. Each power spectrum must have the same length
+            as the frequency array.
+        f0_list : list of float
+            List of central frequencies
+
+        Other parameters
+        ----------------
+        nbins : int, default 100
+            Number of bins to extract
+        rebin : int, default None
+            Rebin the final spectrum by this factor. At the moment, the rebinning
+            is linear.
+
+        Returns
+        -------
+        output: :class:`AveragedPowerspectrum`
+            The final averaged power spectrum.
+
+        Examples
+        --------
+        >>> power_list = [[2, 5, 2, 2, 2], [1, 1, 5, 1, 1], [3, 3, 3, 5, 3]]
+        >>> power_list = np.array(power_list).T
+        >>> freqs = np.arange(5) * 0.1
+        >>> f0_list = [0.1, 0.2, 0.3, 0.4]
+        >>> dps = DynamicalPowerspectrum()
+        >>> dps.dyn_ps = power_list
+        >>> dps.freq = freqs
+        >>> dps.df = 0.1
+        >>> dps.m = 1
+        >>> output = dps.shift_and_add(f0_list, nbins=5)
+        >>> assert isinstance(output, AveragedPowerspectrum)
+        >>> assert np.array_equal(output.m, [2, 3, 3, 3, 2])
+        >>> assert np.array_equal(output.power, [2. , 2. , 5. , 2. , 1.5])
+        >>> assert np.allclose(output.freq, [0.05, 0.15, 0.25, 0.35, 0.45])
+        """
         return super().shift_and_add(
             f0_list, nbins=nbins, output_obj_type=AveragedPowerspectrum, rebin=rebin
         )