Stingray: Next-Generation Spectral Timing¶
Stingray is a Python library designed to perform times series analysis and related tasks on astronomical light curves. It supports a range of commonly-used Fourier analysis techniques, as well as extensions for analyzing pulsar data, simulating data sets, and statistical modelling. Stingray is designed to be easy to extend, and easy to incorporate into data analysis workflows and pipelines.
If you use Stingray for work presented in a publication or talk, please help the project by providing a proper citation.
Currently implemented functionality in this library comprises:
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)
Good Time Interval operations
power spectra in Leahy, rms normalization, absolute rms and no normalization
averaged power spectra
dynamical power spectra
maximum likelihood fitting of periodograms/parametric models
(averaged) cross spectra
coherence, time lags
cross correlation functions
RMS spectra and lags (time vs energy, time vs frequency); needs testing
covariance spectra; needs testing
bispectra; needs testing
(Bayesian) quasi-periodic oscillation searches
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
pulsar searches with Epoch Folding, \(Z^2_n\) test
We welcome feature requests: if you need a particular tool that’s currently not available or have a new method you think might be usefully implemented in Stingray, please get in touch!
Other future additions we are currently implementing are:
phase-resolved spectroscopy of quasi-periodic oscillations
full HEASARC-compatible mission support
pulsar searches with \(H\)-test
binary pulsar searches
Windows uses an internal 32-bit representation for
int. This might create numerical errors when using large integer numbers (e.g. when calculating the sum of a light curve, if the
lc.counts array is an integer).
On Windows, we automatically convert the
counts array to float. The small numerical errors should be a relatively small issue compare to the above.
There are currently three ways to install Stingray:
Below, you can find instructions for each of these methods.
A minimal installation of Stingray requires the following dependencies:
In typical uses, requiring input/output, caching of results, and faster processing, we recommend the following dependencies:
numba (highly recommended)
tbb (needed by numba)
tqdm (for progress bars, always useful)
pyfftw (for the fastest FFT in the West)
h5py (for input/output)
pyyaml (for input/output)
emcee (for MCMC analysis, e.g. for PSD fitting)
corner (for the plotting of MCMC results)
statsmodels (for some statistical analysis)
For pulsar searches and timing, we recommend installing
Some of the dependencies are available in
conda, the others via
To install all required and recommended dependencies in a recent installation, you should be good running the following command:
$ pip install astropy scipy matplotlib numpy h5py tqdm numba pint-pulsar emcee corner statsmodels pyfftw tbb
For development work, you will need the following extra libraries:
Which can be installed with the following command:
$ pip install pytest pytest-astropy jinja2<=3.0.0 docutils sphinx-astropy nbsphinx pandoc ipython jupyter notebook towncrier<22.12.0 tox black
If you manage your Python installation and packages
via Anaconda or miniconda, you can install
$ conda install -c conda-forge stingray
That should be all you need to do! Just remember to run the tests before you use it!
pip-installing Stingray is easy! Just do:
$ pip install stingray
And you should be done! Just remember to run the tests before you use it!
Installing from source (bleeding edge version)¶
For those of you wanting to install the bleeding-edge development version from source (it will have bugs; you’ve been warned!), first clone our repository on GitHub:
$ git clone --recursive https://github.com/StingraySoftware/stingray.git
cd into the newly created
$ pip install -e "."
Installing development environment (for new contributors)¶
For those of you wanting to contribute to the project, install the bleeding-edge development version from source. First fork our repository on GitHub and clone the forked repository using:
$ git clone --recursive https://github.com/<your github username>/stingray.git
Now, navigate to this folder and run the following command to add an upstream remote that’s linked to Stingray’s main repository. (This will be necessary when submitting PRs later.):
$ cd stingray $ git remote add upstream https://github.com/StingraySoftware/stingray.git
Now, install the necessary dependencies:
$ pip install astropy scipy matplotlib numpy pytest pytest-astropy h5py tqdm
$ pip install -e "."
Please be sure to run the test suite before you use the package, and please report anything you think might be bugs on our GitHub Issues page.
$ tox -e test
You may need to install tox first:
$ pip install tox
To run a specific test file (e.g., test_io.py), try:
$ cd stingray $ py.test tests/test_io.py
If you have installed Stingray via pip or conda, the source directory might not be easily accessible. Once installed, you can also run the tests using:
$ python -c 'import stingray; stingray.test()'
or from within a python interpreter:
>>> import stingray >>> stingray.test()
Building the Documentation¶
One quick way to build the documentation is using our tox environment:
$ tox -e build_docs
You can build the API reference yourself by going into the
docs folder within the
directory and running the
$ cd stingray/docs $ make html
If that doesn’t work on your system, you can invoke
sphinx-build itself from the stingray source directory:
$ cd stingray $ sphinx-build docs docs/_build
The documentation should be located in
stingray/docs/_build. Try opening
the stingray source directory.
- Core Stingray Functionality
- Data Exploration
- Analysing Pulsar Data
- The Stingray Modelling Interface
- Stingray Simulator (
- Dealing with dead time
- Stingray API