feat: Bispectrum update and expansion

docs/api.rst

@@ -182,6 +182,50 @@ Bispectrum
 
 ----
 
+AveragedBispectrum
+------------------
+
+.. autoclass:: stingray.bispectrum.AveragedBispectrum
+   :members:
+   :inherited-members:
+
+----
+
+CrossBispectrum
+---------------
+
+.. autoclass:: stingray.bispectrum.CrossBispectrum
+   :members:
+
+----
+
+AveragedCrossBispectrum
+-----------------------
+
+.. autoclass:: stingray.bispectrum.AveragedCrossBispectrum
+   :members:
+   :inherited-members:
+
+----
+
+Dynamical Bispectrum
+--------------------
+
+.. autoclass:: stingray.bispectrum.DynamicalBispectrum
+   :members:
+   :inherited-members:
+
+----
+
+Dynamical CrossBispectrum
+-------------------------
+
+.. autoclass:: stingray.bispectrum.DynamicalCrossBispectrum
+   :members:
+   :inherited-members:
+
+----
+
 
 Covariancespectrum
 ------------------

docs/changes/982.bispectrum-cumulant.breaking.rst

@@ -0,0 +1,9 @@
+The default bispectrum estimator is now the direct Fourier-decomposition method
+(Maccarone 2013) rather than the indirect third-order-cumulant method. The
+cumulant estimator is retained and available via ``Bispectrum(..., method="cumulant")``
+and ``AveragedBispectrum(..., method="cumulant")`` (with the ``maxlag``,
+``window`` and ``scale`` options), but it is no longer the default and its
+results are no longer returned by default. Code relying on the old default
+behaviour or on the previous standalone ``Bispectrum`` attributes must be updated
+to select ``method="cumulant"`` and/or the new ``Bispectrum`` /
+``AveragedBispectrum`` interface.

docs/changes/982.bispectrum-fourier.feature.rst

@@ -0,0 +1,23 @@
+The ``bispectrum`` module has been rewritten around the Fourier-decomposition
+estimator (Maccarone 2013) and brought in line with the modern spectral-timing
+classes such as ``Powerspectrum``. New user-facing capabilities include:
+
+- ``CrossBispectrum`` and ``AveragedCrossBispectrum``, measuring quadratic phase
+  coupling *between* channels (sampled on the full signed frequency plane), with
+  ``Bispectrum`` recovered as the single-channel special case.
+- ``DynamicalBispectrum`` and ``DynamicalCrossBispectrum`` for time-resolved
+  (cross-)bispectra, with ``plot_diagonal``, ``plot_slice``, ``plot_frame``,
+  ``plot_montage`` and ``plot_trace`` plotting options and a ``shift_and_add``
+  method for tracking a drifting coupling.
+- Three bicoherence normalizations -- Kim & Powers (the default, squared form),
+  Sigl & Chamoun, and Hagihira -- switchable after the fact with
+  ``recompute_bicoherence`` without recomputing the FFTs.
+- Poisson-noise bias subtraction (Wirnitzer 1985) via ``poisson_subtract``,
+  overlap-aware for the cross case through ``channels_overlap``.
+- The biphase and its circular-statistics (Fisher 1993) uncertainty.
+- Jellyfish plots (``plot_jellyfish``), plus ``plot_mag``, ``plot_phase`` and
+  ``plot_bicoherence``, all returning their ``matplotlib`` axes.
+- Construction from light curves, event lists, arrays of event times,
+  ``StingrayTimeseries`` objects and iterables of light curves.
+- ``save_all`` and ``save_diagonal`` options to control the memory used by the
+  per-segment bispectrum cube.

pyproject.toml

@@ -184,8 +184,8 @@ filterwarnings = [
     "ignore:.*Pyarrow:",
     "ignore:.*Creating an ndarray from ragged nested sequences:",
     "ignore:.*the tpfmodel submodule is not available without oktopus.*:UserWarning",
-    "ignore:.*chararray"
-
+    "ignore:.*chararray",
+    "ignore:The stingray bispectrum interface has changed:UserWarning",
 ]
 
 [tool.towncrier]