Welcome to Stingray’s documentation¶
Contents:
Stingray API¶
Library of Time Series Methods For Astronomical X-ray Data.
-
class
stingray.
AveragedPowerspectrum
(lc, segment_size, norm='rms')[source]¶ Make an averaged periodogram from a light curve by segmenting the light curve, Fourier-transforming each segment and then averaging the resulting periodograms.
Parameters: lc: lightcurve.Lightcurve object OR
iterable of lightcurve.Lightcurve objects The light curve data to be Fourier-transformed.
segment_size: float
The size of each segment to average. Note that if the total duration of each Lightcurve object in lc is not an integer multiple of the segment_size, then any fraction left-over at the end of the time series will be lost.
norm: {“leahy” | “rms”}, optional, default “rms”
The normaliation of the periodogram to be used. Options are “leahy” or “rms”, default is “rms”.
Attributes
norm: {“leahy” | “rms”} the normalization of the periodogram freq: numpy.ndarray The array of mid-bin frequencies that the Fourier transform samples ps: numpy.ndarray The array of normalized squared absolute values of Fourier amplitudes df: float The frequency resolution m: int The number of averaged periodograms n: int The number of data points in the light curve nphots: float The total number of photons in the light curve
-
class
stingray.
Lightcurve
(time, counts, input_counts=True)[source]¶ Make a light curve object from an array of time stamps and an array of counts.
Parameters: time: iterable
A list or array of time stamps for a light curve
counts: iterable, optional, default None
A list or array of the counts in each bin corresponding to the bins defined in
time
(note: not the count rate, i.e. counts/second, but the counts/bin).input_counts: bool, optional, default True
If True, the code assumes that the input data in ‘counts’ is in units of counts/bin. If False, it assumes the data in ‘counts’ is in counts/second.
Attributes
time: numpy.ndarray The array of midpoints of time bins counts: numpy.ndarray The counts per bin corresponding to the bins in time
.countrate: numpy.ndarray The counts per second in each of the bins defined in time
.ncounts: int The number of data points in the light curve. dt: float The time resolution of the light curve. tseg: float The total duration of the light curve. tstart: float The start time of the light curve. -
static
make_lightcurve
(toa, dt, tseg=None, tstart=None)[source]¶ Make a light curve out of photon arrival times.
Parameters: toa: iterable
list of photon arrival times
dt: float
time resolution of the light curve (the bin width)
tseg: float, optional, default None
The total duration of the light curve. If this is
None
, then the total duration of the light curve will be the interval between the arrival between the first and the last photon intoa
.Note: If tseg is not divisible by dt (i.e. if tseg/dt is not an integer number), then the last fractional bin will be dropped!
tstart: float, optional, default None
The start time of the light curve. If this is None, the arrival time of the first photon will be used as the start time of the light curve.
Returns: lc:
Lightcurve
objectA light curve object with the binned light curve
-
rebin_lightcurve
(dt_new, method='sum')[source]¶ Rebin the light curve to a new time resolution. While the new resolution need not be an integer multiple of the previous time resolution, be aware that if it is not, the last bin will be cut off by the fraction left over by the integer division.
Parameters: dt_new: float
The new time resolution of the light curve. Must be larger than the time resolution of the old light curve!
method: {“sum” | “mean” | “average”}, optional, default “sum”
This keyword argument sets whether the counts in the new bins should be summed or averaged.
Returns: lc_new:
Lightcurve
objectThe
Lightcurve
object with the new, binned light curve.
-
static
-
class
stingray.
Powerspectrum
(lc=None, norm='rms')[source]¶ Make a Periodogram (power spectrum) from a (binned) light curve. Periodograms can be Leahy normalized or fractional rms normalized. You can also make an empty Periodogram object to populate with your own fourier-transformed data (this can sometimes be useful when making binned periodograms).
Parameters: lc: lightcurve.Lightcurve object, optional, default None
The light curve data to be Fourier-transformed.
norm: {“leahy” | “rms”}, optional, default “rms”
The normaliation of the periodogram to be used. Options are “leahy” or “rms”, default is “rms”.
Attributes
norm: {“leahy” | “rms”} the normalization of the periodogram freq: numpy.ndarray The array of mid-bin frequencies that the Fourier transform samples ps: numpy.ndarray The array of normalized squared absolute values of Fourier amplitudes df: float The frequency resolution m: int The number of averaged powers in each bin n: int The number of data points in the light curve nphots: float The total number of photons in the light curve -
classical_significances
(threshold=1, trial_correction=False)[source]¶ Compute the classical significances for the powers in the power spectrum, assuming an underlying noise distribution that follows a chi-square distributions with 2M degrees of freedom, where M is the number of powers averaged in each bin.
Note that this function will only produce correct results when the following underlying assumptions are fulfilled: (1) The power spectrum is Leahy-normalized (2) There is no source of variability in the data other than the periodic signal to be determined with this method. This is important! If there are other sources of (aperiodic) variability in the data, this method will not produce correct results, but instead produce a large number of spurious false positive detections! (3) There are no significant instrumental effects changing the statistical distribution of the powers (e.g. pile-up or dead time)
By default, the method produces (index,p-values) for all powers in the power spectrum, where index is the numerical index of the power in question. If a
threshold
is set, then only powers with p-values below that threshold with their respective indices. Iftrial_correction
is set to True, then the threshold will be corrected for the number of trials (frequencies) in the power spectrum before being used.Parameters: threshold : float
The threshold to be used when reporting p-values of potentially significant powers. Must be between 0 and 1. Default is 1 (all p-values will be reported).
trial_correction : bool
A Boolean flag that sets whether the
threshold
will be correted by the number of frequencies before being applied. This decreases the threshold (p-values need to be lower to count as significant). Default is False (report all powers) though for any application wherethreshold
is set to something meaningful, this should also be applied!Returns: pvals : iterable
A list of (index, p-value) tuples for all powers that have p-values lower than the threshold specified in
threshold
.
-
compute_rms
(min_freq, max_freq)[source]¶ Compute the fractional rms amplitude in the periodgram between two frequencies.
Parameters: min_freq: float
The lower frequency bound for the calculation
max_freq: float
The upper frequency bound for the calculation
Returns: rms: float
The fractional rms amplitude contained between min_freq and max_freq
-
rebin
(df, method='mean')[source]¶ Rebin the periodogram to a new frequency resolution df.
Parameters: df: float
The new frequency resolution
Returns: bin_ps = Periodogram object
The newly binned periodogram
-
rebin_log
(f=0.01)[source]¶ Logarithmic rebin of the periodogram. The new frequency depends on the previous frequency modified by a factor f:
dnu_j = dnu_{j-1}*(1+f)
Parameters: f: float, optional, default 0.01
parameter that steers the frequency resolution
Returns: binfreq: numpy.ndarray
the binned frequencies
binps: numpy.ndarray
the binned powers
nsamples: numpy.ndarray
the samples of the original periodogramincluded in each frequency bin
-
-
stingray.
optimal_bin_time
(fftlen, tbin)[source]¶ Vary slightly the bin time to have a power of two number of bins.
Given an FFT length and a proposed bin time, return a bin time slightly shorter than the original, that will produce a power-of-two number of FFT bins.
-
stingray.
rebin_data
(x, y, dx_new, method=u'sum')[source]¶ Rebin some data to an arbitrary new data resolution. Either sum the data points in the new bins or average them.
Parameters: x: iterable
The dependent variable with some resolution dx_old = x[1]-x[0]
y: interable
The independent variable to be binned
dx_new: float
The new resolution of the dependent variable x
method: {“sum” | “average” | “mean”}, optional, default “sum”
The method to be used in binning. Either sum the samples y in each new bin of x, or take the arithmetic mean.
Returns: xbin: numpy.ndarray
The midpoints of the new bins in x
ybin: numpy.ndarray
The binned quantity y
-
stingray.
simon
(message, **kwargs)[source]¶ The Statistical Interpretation MONitor.
A warning system designed to always remind the user that Simon is watching him/her.
Parameters: message : string
The message that is thrown
kwargs : dict
The rest of the arguments that are passed to warnings.warn
-
stingray.
test
(package=None, test_path=None, args=None, plugins=None, verbose=False, pastebin=None, remote_data=False, pep8=False, pdb=False, coverage=False, open_files=False, **kwargs)[source]¶ Run the tests using py.test. A proper set of arguments is constructed and passed to pytest.main.
Parameters: package : str, optional
The name of a specific package to test, e.g. ‘io.fits’ or ‘utils’. If nothing is specified all default tests are run.
test_path : str, optional
Specify location to test by path. May be a single file or directory. Must be specified absolutely or relative to the calling directory.
args : str, optional
Additional arguments to be passed to pytest.main in the
args
keyword argument.plugins : list, optional
Plugins to be passed to pytest.main in the
plugins
keyword argument.verbose : bool, optional
Convenience option to turn on verbose output from py.test. Passing True is the same as specifying
'-v'
inargs
.pastebin : {‘failed’,’all’,None}, optional
Convenience option for turning on py.test pastebin output. Set to
'failed'
to upload info for failed tests, or'all'
to upload info for all tests.remote_data : bool, optional
Controls whether to run tests marked with @remote_data. These tests use online data and are not run by default. Set to True to run these tests.
pep8 : bool, optional
Turn on PEP8 checking via the pytest-pep8 plugin and disable normal tests. Same as specifying
'--pep8 -k pep8'
inargs
.pdb : bool, optional
Turn on PDB post-mortem analysis for failing tests. Same as specifying
'--pdb'
inargs
.coverage : bool, optional
Generate a test coverage report. The result will be placed in the directory htmlcov.
open_files : bool, optional
Fail when any tests leave files open. Off by default, because this adds extra run time to the test suite. Requires the psutil package.
parallel : int, optional
When provided, run the tests in parallel on the specified number of CPUs. If parallel is negative, it will use the all the cores on the machine. Requires the pytest-xdist plugin installed. Only available when using Astropy 0.3 or later.
kwargs
Any additional keywords passed into this function will be passed on to the astropy test runner. This allows use of test-related functionality implemented in later versions of astropy without explicitly updating the package template.