Source-linked AI summary
Stingray: A Modern Python Library For Spectral Timing
D. Huppenkothen, M. Bachetti, A. L. Stevens, S. Migliari, P. Balm, O. Hammad, U. M. Khan, H. Mishra, H. Rashid, S. Sharma, R. V. Blanco, E. M. Ribeiro
TL;DR
Spectral-timing research lacked a common, open framework for reusable analysis methods. This paper presents Stingray, a modular and tested Python library with Fourier analysis, modeling, simulation, and pulsar extensions; its development roadmap identifies higher-order and energy-resolved spectral products as future work.
Problem
Spectral timing is fragmented across siloed software, lacks a commonly accepted current framework, and remains difficult for researchers without private code bases.
Method
Stingray provides modular, unit-tested Python building blocks for Fourier products, statistical modeling, stochastic simulation, and pulsar analysis, with interfaces to higher-level tools.
Results
The library implements core spectral-timing functionality and extensions that have been used in radio, optical, and X-ray studies across several source classes.
Takeaways & Limitations
Stingray provides an extensible platform for incorporating spectral-timing methods into analysis workflows and for adding future techniques.
Takeaways & Limitations
Higher-order Fourier products and instrument-response or XSPEC interfaces were not yet supported, while additional energy-resolved products remained future work.
Abstract
from arXiv · showhide
This paper describes the design and implementation of Stingray, a library in Python built to perform time series analysis and related tasks on astronomical light curves. Its core functionality comprises a range of Fourier analysis techniques commonly used in spectral-timing analysis, as well as extensions for analyzing pulsar data, simulating data sets, and statistical modeling. Its modular build allows for easy extensions and incorporation of its methods into data analysis workflows and pipelines. We aim for the library to be a platform for the implementation of future spectral-timing techniques. Here, we describe the overall vision and framework, core functionality, extensions, and connections to high-level command-line and graphical interfaces. The code is well-tested, with a test coverage of currently 95%, and is accompanied by extensive API documentation and a set of step-by-step tutorials.
1. INTRODUCTION
Astronomical variability across timescales and wavelengths provides key diagnostics of physical processes, while expanding datasets make spectral-timing analysis increasingly important. Stingray addresses this need with an open-source Python implementation of core timing methods.
- Variability across milliseconds to centuries helps probe the dynamics, emission processes, and physical mechanisms of astronomical sources.
- Time-dependent emission across wavelengths supports studies of accretion, strong gravity, and dense matter in compact objects.
- Public and forthcoming X-ray missions are producing datasets of unprecedented size and complexity for spectral-timing studies.
- Stingray provides a well-tested, open-source Python implementation of core time-series and spectral-timing algorithms across the electromagnetic spectrum.
- The package has been used for radio, optical, and X-ray studies, including accreting compact objects and cospectral statistics.
2. DATA
The paper demonstrates Stingray using real observations of compact objects, including black-hole systems, an AGN, and a pulsar. The datasets span different instruments, time resolutions, observing gaps, and data-quality considerations.
- Real compact-object observations are used to demonstrate Stingray functionality after data reduction into event files and light curves.
- 2.1. GX 339–4: GX 339–4 data come from a 64-channel RXTE event mode with 122 µs time resolution and approximately 1 ks of filtered good data.
- 2.2. KIC12158940: KIC12158940 is represented by twelve Kepler epochs, but published processing cautions that instrumental artifacts limit scientific conclusions from the pre-produced light curves.
- 2.2. KIC12158940: The Kepler light curves were checked with larger-aperture extraction and split along data gaps before analysis, while astrophysical use requires de-biased light curves.
- 2.3. Hercules X-1: Hercules X-1 observations provide a pulsar example, with a 1.23 s pulse period and NuSTAR data.
3. VISION AND GENERAL PACKAGE FRAMEWORK
Stingray was created to address fragmented spectral-timing software through accessible, tested, modular Python building blocks. Its core classes support Fourier analysis and extensions for modeling, simulation, pulsar analysis, and higher-level interfaces.
- Spectral timing lacked a commonly accepted, up-to-date framework, with siloed code and limited open-source access motivating Stingray’s development.
- Stingray makes core Fourier-analysis tools available in Python as a platform for new methods and tools.
- Its extensions support light-curve and power-spectrum modeling, synthetic-data simulation, and pulsar timing.
- The object-oriented, unit-tested modules provide flexible building blocks that users can incorporate into larger workflows and pipelines.
- HENDRICS and DAVE build command-line workflows and graphical exploratory analysis on top of Stingray functionality.
- At v0.1, the core package depends on NumPy, SciPy, and Astropy, with additional optional dependencies for modeling, plotting, and computational efficiency.
4. DEVELOPMENT AND INTEGRATION ENVIRONMENT
Stingray is developed in Python with version-controlled, community-hosted repositories that organize the core library, extensions, tutorials, website, and manuscript.
- Stingray is developed in Python 3, with Python 2.7 compatibility where possible through six.
- GitHub hosts interconnected repositories for the core library, HENDRICS, DAVE, tutorials, website, and manuscript.
5. CORE FUNCTIONALITY
Stingray provides modular core data structures and operations for event data, binned light curves, and Fourier-based spectral-timing analysis. Its methods support common transformations, rebinning, spectra, normalization, and statistical period searches.
- Data structures: Stingray represents event data and binned light curves through core classes, with light curves treated as the current default format.EventList stores timestamps and optional photon energies, while Lightcurve stores time bins and flux or count measurements.
- Lightcurve operations: Lightcurve operations include arithmetic, time shifting, joining, truncation, sorting, file input/output, and rebinning to coarser time resolution.Supported file formats include HDF5, FITS, and ASCII; interpolation to finer resolution is not supported.
- Data structures: Event lists can be converted to light curves, and light curves can be constructed from event arrival times using a chosen time resolution.The package also supports joining event lists and basic input/output operations.
- Spectral-timing analysis: Cross spectra are computed from two simultaneous, evenly sampled time series, while the power spectrum is implemented as the single-series special case.Stingray provides Crossspectrum and Powerspectrum classes, with the latter inheriting shared calculations from the former.
- Spectral-timing analysis: The package implements multiple spectral normalizations, including Leahy normalization, and supports logarithmic frequency rebinning with a fractional resolution factor f.For Leahy normalization, white-noise power follows a χ2 distribution with 2 degrees of freedom around mean 2, while the cospectrum follows a centered Laplace distribution with scale 1.
- Statistical analysis: Classical period searches evaluate whether an observed spectral outlier is consistent with statistical fluctuations under an expected noise distribution.The cited white-noise formulation supports p-value calculations for one or multiple powers.
6. THE MODELING SUBPACKAGE
Stingray’s modeling subpackage provides specialized, modular statistical modeling and parameter-estimation tools for spectral-timing products, especially power spectra. It supports likelihood-based inference, posterior sampling, periodic-signal searches, and extensibility, while leaving higher-order Fourier-product modeling for future development.
- Modeling interface: The modeling interface focuses on commonly used spectral-timing products, particularly averaged power spectra, because their statistical properties differ from other astronomical data.It builds on astropy.modeling.FittableModel while providing custom fitting algorithms for spectral-timing data.
- Statistical models: Likelihood and posterior classes separate statistical models from fitting functionality, allowing problem-specific likelihoods and priors to be exchanged within a modular framework.Posterior classes require user-defined logprior methods because priors depend strongly on the problem.
- Statistical models: Stingray includes Gaussian, Poisson, and power-spectrum likelihoods, with PSD models using χ2 distributions for individual and averaged Fourier spectra.For averaged power spectra, the distribution is χ2^2MK, where M is the number of averaged segments and K is the number of averaged neighboring frequency bins.
- Parameter estimation: Parameter-estimation utilities fit maximum-likelihood or maximum-a-posteriori solutions and use affine-invariant MCMC to sample posterior distributions.Optimization and sampling result classes provide parameter summaries and diagnostics such as covariance estimates, information criteria, acceptance fractions, autocorrelation lengths, and convergence statistics.
- Special functionality for Fourier products: PSDParEst searches for periodic signals by identifying power-spectrum outliers and calibrating posterior-predictive p-values against simulations of the underlying spectral model.The method accounts for uncertainty in the fitted power-spectrum parameters when assessing whether outliers can be explained by noise.
- Limitations: The modeling subpackage cannot yet model higher-order Fourier products or interface with instrument responses and XSPEC spectral models.This functionality was planned for a future Stingray release.
7. THE SIMULATOR SUBPACKAGE
Stingray’s simulator subpackage generates synthetic light curves and event lists from power-spectral shapes and input responses. It also supports transformed or multi-band simulations and uses acceptance-rejection sampling to convert light curves into event lists.
- Simulation capabilities: The simulator generates light curves from known power-spectral shapes and event lists from light curves.These capabilities support simulations of stochastic time-series data and synthetic observations.
- Light-curve simulation: The Simulator uses the Timmer–Koenig algorithm to generate Lightcurve objects from power-law indices, model objects, or user-provided arrays of powers.The resulting Lightcurve objects retain functionality for GTIs, spectral-timing products, and modeling.
- Response-based simulation: Multiple light curves can be generated from an initial light curve and multiple input responses to mimic observations in different energy bands.The responses encode transformations such as filtering and time lags between emission and observation.
- Event-list simulation: Event-list simulation uses acceptance-rejection sampling: candidate events receive uniform random times and random probabilities, then are accepted when the probability falls below the normalized light curve.The procedure first generates and normalizes a light curve, then accepts or rejects events according to its value at each event time.
- Implementation: Stingray uses arrays of events to improve the performance of event-list simulation.This implementation relies on functionality from NumPy.
8. THE PULSE SUBPACKAGE
Stingray’s pulse subpackage supports pulsation searches, pulse-profile analysis, phase tracking, and timing-parameter refinement. It combines epoch-folding and harmonic statistics with tools for efficient computation, precise frequency fitting, phaseogram inspection, and TOA calculation.
- The pulse subpackage provides operations for searching and characterizing pulsed signals, including X-ray pulsar searches.
- 8.1. Epoch Folding: Epoch Folding cuts signals at trial pulse periods and sums intervals in phase, producing pulse profiles or phase histograms.
- 8.1. Epoch Folding: Stingray implements Epoch Folding Search and Z2_n searches for event lists or light curves, addressing weak or poorly resolved Fourier pulsation signatures.
- 8.1. Epoch Folding: The epoch-folding statistic compares profile bins with a flat model and follows a χ2 distribution, enabling detection thresholds under the null hypothesis.
- 8.1. Epoch Folding: Binning folded profiles before evaluating harmonic terms accelerates Z2_n searches, with documentation recommending at least 10 bins per harmonic.
- 8.3. Characterization of pulsar behavior: Stingray fits sinc2 or Gaussian models to pulsation periodograms, uses phaseograms to diagnose timing and orbital errors, and calculates TOAs for external timing software.
9. HENDRICS: A COMMAND-LINE INTERFACE FOR stingray
HENDRICS builds on stingray to provide easy-to-execute command-line scripts for accurate quick-look spectral-timing analysis. It emphasizes gap and detector dead-time treatment while trading some flexibility for end-to-end common tasks.
- HENDRICS builds on stingray to provide easy-to-execute command-line scripts for accurate quick-look spectral-timing analysis.Its use cases include exploratory data analysis and quality assessment of larger pipelines.
- Accurate treatment of data gaps and detector dead time distinguishes HENDRICS from established command-line interfaces such as FTOOLS.Examples of gaps include Earth occultation and the South Atlantic Anomaly; NuSTAR is one detector context.
- HENDRICS provides end-to-end solutions for power spectra, cross spectra, time lags, pulsar searches, and color-based diagrams, at the cost of flexibility.
- HENDRICS supports netCDF4 and ASCII outputs that can be read by systems including XSPEC and ISIS.
10. DAVE: EXPLORATORY DATA ANALYSIS IN A GRAPHICAL USER INTERFACE
DAVE is a graphical interface built on stingray for interactive exploratory analysis of variable time series. It exposes spectral-timing products, filtering, comparisons, and auxiliary diagrams through interactive controls.
- DAVE provides interactive exploratory data analysis for variable time series on top of stingray.
- Its available functionality includes power spectra, cross spectra, dynamical power spectra, time lags, and coherence measurements.
- Users can filter light curves by energy, time range, and count rate, then compare products from different energy ranges.
- DAVE also supports color-color and color-intensity diagrams as auxiliary products for data exploration.
11. FUTURE DEVELOPMENT PLANS
Future Stingray development targets broader spectral-timing functionality, improved computational efficiency, and methods for irregularly sampled light curves. Planned capabilities include energy-dependent spectra, while current workflows remain limited by the lack of native energy-spectral modeling.
- Planned spectral-timing extensions include lag-energy, rms-energy, and excess-variance spectra, building on covariance-spectrum functionality.
- Stingray currently lacks native energy-spectral modeling, so spectral-timing products must be exported and loaded into other software.This significantly disrupts workflows and pipeline development.
- Increasing X-ray data rates motivate replacing implementations with GPU-enabled and multi-core high-performance computations.The optimization effort also targets computational overhead and memory usage.
- DAVE demonstrates interactive products including averaged and dynamic power spectra from segmented pulsar data.The example uses 109 segments of 256 seconds with 1.5-second binned time resolution.
- Irregularly sampled light curves remain a major future challenge and a high-priority long-term goal for Stingray.