Introduce power colors

docs/api.rst

@@ -5,12 +5,57 @@ Stingray API
 
 Library of Time Series Methods For Astronomical X-ray Data.
 
+Base Class
+==========
+Most `stingray`` classes are subclasses of a single class, :class:`stingray.StingrayObject`, which
+implements most of the I/O functionality and common behavior (e.g. strategies to combine data and
+make operations such as the sum, difference, or negation). This class is not intended to be
+instantiated directly, but rather to be used as a base class for other classes. Any class wanting
+to inherit from :class:`stingray.StingrayObject` should define a ``main_array_attr`` attribute, which
+defines the name of the attribute that will be used to store the "independent variable" main data array.
+For example, for all time series-like objects, the main array is the time array, while for the
+periodograms the main array is the frequency array.
+All arrays sharing the length (not the shape: they might be multi-dimensional!) of the main array are called
+"array attributes" and are accessible through the ``array_attrs`` method.
+When applying a mask or any other selection to a :class:`stingray.StingrayObject`,
+all array attributes are filtered in the same way. Some array-like attributes might have the same length
+by chance, in this case the user or the developer should add these to the ``not_array_attr`` attribute.
+For example, :class:`stingray.StingrayTimeseries` has ``gti`` among the not_array_attrs, since it is an
+array but not related 1-to-1 to the main array, even if in some cases it might happen to have the same numbers
+of elements of the main array, which is ``time``.
+
+StingrayObject
+--------------
+
+.. autoclass:: stingray.StingrayObject
+   :members:
+
+----
+
 Data Classes
 ============
 
 These classes define basic functionality related to common data types and typical methods
 that apply to these data types, including basic read/write functionality. Currently
-implemented are :class:`stingray.Lightcurve` and :class:`stingray.events.EventList`.
+implemented are :class:`stingray.StingrayTimeseries`, :class:`stingray.Lightcurve` and
+:class:`stingray.events.EventList`.
+
+All time series-like data classes inherit from :class:`stingray.StingrayTimeseries`, which
+implements most of the common functionality. The main data array is stored in the ``time``
+attribute.
+Good Time Intervals (GTIs) are stored in the ``gti`` attribute, which is a list of 2-tuples or 2-lists
+containing the start and stop times of each GTI. The ``gti`` attribute is not an array attribute, since
+it is not related 1-to-1 to the main array, even if in some cases it might happen to have the same number
+of elements of the main array. It is by default added to the ``not_array_attr`` attribute.
+
+
+StingrayTimeseries
+------------------
+
+.. autoclass:: stingray.StingrayTimeseries
+   :members:
+
+----
 
 Lightcurve
 ----------
@@ -88,7 +133,7 @@ Dynamical Powerspectrum
 .. autoclass:: stingray.DynamicalPowerspectrum
    :members:
    :inherited-members:
-   
+
 ----
 
 CrossCorrelation

docs/changes/780.feature.rst

@@ -0,0 +1 @@
+Introduce power colors à la Heil et al. 2015

docs/changes/782.feature.rst

@@ -0,0 +1 @@
+Add function to randomize data in small bad time intervals

docs/changes/787.trivial.rst

@@ -0,0 +1 @@
+More informative GTI messages

docs/index.rst

@@ -24,14 +24,16 @@ Current Capabilities
 1. Data handling and simulation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* loading event lists from fits files of a few missions (RXTE/PCA, NuSTAR/FPM, XMM-Newton/EPIC, NICER/XTI)
-* constructing light curves from event data, various operations on light curves (e.g. addition, subtraction, joining, and truncation)
+* loading event lists from fits files (and generally good handling of OGIP-compliant missions, like RXTE/PCA, NuSTAR/FPM, XMM-Newton/EPIC, NICER/XTI)
+* constructing light curves and time series from event data
+* various operations on time series (e.g. addition, subtraction, joining, and truncation)
 * simulating a light curve with a given power spectrum
 * simulating a light curve from another light curve and a 1-d (time) or 2-d (time-energy) impulse response
 * simulating an event list from a given light curve _and_ with a given energy spectrum
 * Good Time Interval operations
+* Filling gaps in light curves with statistically sound fake data
 
-2. Fourier methods
+1. Fourier methods
 ~~~~~~~~~~~~~~~~~~
 * power spectra and cross spectra in Leahy, rms normalization, absolute rms and no normalization
 * averaged power spectra and cross spectra
@@ -44,6 +46,7 @@ Current Capabilities
 * bispectra; *needs testing*
 * (Bayesian) quasi-periodic oscillation searches
 * Lomb-Scargle periodograms and cross spectra
+* Power Colors
 
 3. Other time series methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,7 +64,6 @@ Other future additions we are currently implementing are:
 * bicoherence
 * phase-resolved spectroscopy of quasi-periodic oscillations
 * Fourier-frequency-resolved spectroscopy
-* power colours
 * full HEASARC-compatible mission support
 * pulsar searches with :math:`H`-test
 * binary pulsar searches

setup.cfg

@@ -59,6 +59,7 @@ docs =
     docutils
     sphinx-astropy
     nbsphinx>=0.8.3,!=0.8.8
+    nbconvert<7.14
     pandoc
     ipython
     towncrier<22.12.0