From 54f057d23337e65cf3854515b7651df41027dada Mon Sep 17 00:00:00 2001 From: Matteo Bachetti Date: Thu, 24 Aug 2023 13:53:31 +0200 Subject: [PATCH 1/2] Add changelog [skip-tests] --- docs/changes/748.docs.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/changes/748.docs.rst diff --git a/docs/changes/748.docs.rst b/docs/changes/748.docs.rst new file mode 100644 index 000000000..07c169ad5 --- /dev/null +++ b/docs/changes/748.docs.rst @@ -0,0 +1 @@ +Improved main page of the documentation \ No newline at end of file From 2054c890d96f176888c4ba4d7eebe2b98d5f99b8 Mon Sep 17 00:00:00 2001 From: Matteo Bachetti Date: Thu, 24 Aug 2023 14:26:27 +0200 Subject: [PATCH 2/2] Reshape first page [docs only] --- docs/history.rst | 34 +++++- docs/index.rst | 263 ++++++++++++++++++++++++++++++++++++++++++++--- docs/install.rst | 172 ------------------------------- docs/intro.rst | 69 ------------- 4 files changed, 279 insertions(+), 259 deletions(-) delete mode 100644 docs/install.rst delete mode 100644 docs/intro.rst diff --git a/docs/history.rst b/docs/history.rst index 5cdea5f2d..b6a373925 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -2,10 +2,17 @@ History ******* -Changelog -========= +For a brief overview of the history and state-of-the-art in spectral timing, and for more information about the design and capabilities of Stingray, please refer to `Huppenkothen et al. (2019) `_. -.. include:: ../CHANGELOG.rst +Stingray originated during the 2016 workshop `The X-ray Spectral-Timing Revolution `_: a group of X-ray astronomers and developers decided to agree on a common platform to develop a new software package. +At that time, there were a number of official software packages for X-ray spectral fitting (XSPEC, ISIS, Sherpa, ...), but +such a widely used and standard software package did not exist for X-ray timing, that was mostly the domain of custom, proprietary software. +Our goals were to merge existing efforts towards a timing package in Python, following the best guidelines for modern open-source programming, thereby providing the basis for developing spectral-timing analysis tools. +We needed to provide an easily accessible scripting interface, a GUI, and an API for experienced coders. +Stingray's ultimate goal is to provide the community with a package that eases the learning curve for advanced spectral-timing techniques, with a correct statistical framework. + +Further spectral-timing functionality, in particularly command line scripts based on the API defined within Stingray, is available in the package `HENDRICS `_. +A graphical user interface is under development as part of the project `DAVE `_. Previous projects merged to Stingray ==================================== @@ -14,3 +21,24 @@ Previous projects merged to Stingray * Matteo Bachetti's `MaLTPyNT `_ * Abigail Stevens' RXTE power spectra code and phase-resolved spectroscopy code * Simone Migliari's and Paul Balm's X-ray data exploration GUI commissioned by ESA + + +Changelog +========= + +.. include:: ../CHANGELOG.rst + + +Presentations +============= + +Members of the Stingray team have given a number of presentations which introduce Stingray. +These include: + +- `2nd Severo Ochoa School on Statistics, Data Mining, and Machine Learning (2021) `_ +- `9th Microquasar Workshop (2021) `_ +- `European Week of Astronomy and Space Science (2018) `_ +- `ADASS (Astronomical Data Analysis Software and Systems; meeting 2017, proceedings 2020) `_ +- `AAS 16th High-Energy Astrophysics Division meeting (2017) `_ +- `European Week of Astronomy and Space Science 2017 `_ +- `Python in Astronomy (2016) `_ diff --git a/docs/index.rst b/docs/index.rst index 5940564fa..57760105f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,43 +2,276 @@ Stingray: Next-Generation Spectral Timing ***************************************** -Stingray is a community-developed astrophysical spectral-timing software package written in Python. - .. image:: images/stingray_logo.png :width: 700 :scale: 40% :alt: Stingray logo, outline of a stingray on top of a graph of the power spectrum of an X-ray binary :align: center -There are a number of official software packages for X-ray spectral fitting (XSPEC, ISIS, Sherpa, ...). -Such a widely used and standard software package does not exist for X-ray timing, so until now it has mainly been the domain of custom, proprietary software. -Stingray originated during the 2016 workshop `The X-ray Spectral-Timing Revolution `_: a group of X-ray astronomers and developers decided to agree on a common platform to develop a new software package. -The goals were to merge existing efforts towards a timing package in Python, following the best guidelines for modern open-source programming, thereby providing the basis for developing spectral-timing analysis tools. -This software provides an easily accessible scripting interface, a GUI, and an API for experienced coders. -Stingray's ultimate goal is to provide the community with a package that eases the learning curve for advanced spectral-timing techniques, with a correct statistical framework. - -Further spectral-timing functionality, in particularly command line scripts based on the API defined within Stingray, is available in the package `HENDRICS `_. -A graphical user interface is under development as part of the project `DAVE `_. +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. .. important:: If you use Stingray for work presented in a publication or talk, please help the project by providing a proper :doc:`citation `. -Contents +Features ======== +Current Capabilities +-------------------- + +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, :math:`Z^2_n` test + +Future Plans +------------ + +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 :doc:`get in touch `! + +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 + +Platform-specific issues +------------------------ + +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. + +Installation instructions +========================= + +There are currently three ways to install Stingray: + +* via ``conda`` +* via ``pip`` +* from source + +Below, you can find instructions for each of these methods. + +Dependencies +------------ +A **minimal installation** of Stingray requires the following dependencies: + ++ astropy>=4.0 ++ numpy>=1.17.0 ++ scipy>=1.1.0 ++ matplotlib>=3.0,!=3.4.0 + +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 + ++ pint-pulsar + +Some of the dependencies are available in ``conda``, the others via ``pip``. +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: + ++ pytest ++ pytest-astropy ++ tox ++ jinja2<=3.0.0 ++ docutils ++ sphinx-astropy ++ nbsphinx>=0.8.3,!=0.8.8 ++ pandoc ++ ipython ++ jupyter ++ notebook ++ towncrier<22.12.0 ++ black + +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 + +Installation +------------ +Installing via ``conda`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you manage your Python installation and packages +via Anaconda or miniconda, you can install ``stingray`` +via the ``conda-forge`` build: :: + + $ conda install -c conda-forge stingray + +That should be all you need to do! Just remember to :ref:`run the tests ` before +you use it! + +Installing via ``pip`` +~~~~~~~~~~~~~~~~~~~~~~ + +``pip``-installing Stingray is easy! Just do:: + + $ pip install stingray + +And you should be done! Just remember to :ref:`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 + +Now ``cd`` into the newly created ``stingray`` directory. +Finally, install ``stingray`` itself: :: + + $ 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//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 + +Finally, install ``stingray`` itself:: + + $ pip install -e "." + +.. _testsuite: + +Test Suite +---------- + +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 `_. + +Stingray uses `py.test `_ and `tox +`_ for testing. To run the tests, try:: + + $ 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: + +.. doctest-skip:: + + >>> import stingray + >>> stingray.test() + +Building the Documentation +-------------------------- + +The documentation including tutorials is hosted `here `_. +The documentation uses `sphinx `_ to build and requires the extensions `sphinx-astropy `_ and `nbsphinx `_. + +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 ``stingray`` root +directory and running the ``Makefile``: :: + + $ 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 ``./docs/_build/index.rst`` from +the stingray source directory. + +Using Stingray +=============== + +Getting started +--------------- .. toctree:: :maxdepth: 2 - intro - install core dataexplo + pulsar + +Advanced +-------- + +.. toctree:: + :maxdepth: 2 + modeling simulator - pulsar deadtime api + +Additional information +====================== + +.. toctree:: + :maxdepth: 2 + history contributing citing diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 6eb2dae0e..000000000 --- a/docs/install.rst +++ /dev/null @@ -1,172 +0,0 @@ -Dependencies -============ -A **minimal installation** of Stingray requires the following dependencies: - -+ astropy>=4.0 -+ numpy>=1.17.0 -+ scipy>=1.1.0 -+ matplotlib>=3.0,!=3.4.0 - -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 - -+ pint-pulsar - -Some of the dependencies are available in ``conda``, the others via ``pip``. -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: - -+ pytest -+ pytest-astropy -+ tox -+ jinja2<=3.0.0 -+ docutils -+ sphinx-astropy -+ nbsphinx>=0.8.3,!=0.8.8 -+ pandoc -+ ipython -+ jupyter -+ notebook -+ towncrier<22.12.0 -+ black - -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 - -Downloading and Installing Stingray -=================================== - -There are currently two ways to install Stingray: - -* via ``conda`` -* via ``pip`` -* from source - -Installing via ``conda`` ------------------------- - -If you manage your Python installation and packages -via Anaconda or miniconda, you can install ``stingray`` -via the ``conda-forge`` build: :: - - $ conda install -c conda-forge stingray - -That should be all you need to do! Just remember to :ref:`run the tests ` before -you use it! - -Installing via ``pip`` ----------------------- - -``pip``-installing Stingray is easy! Just do:: - - $ pip install stingray - -And you should be done! Just remember to :ref:`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 - -Now ``cd`` into the newly created ``stingray`` directory. -Finally, install ``stingray`` itself: :: - - $ 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//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 - -Finally, install ``stingray`` itself:: - - $ pip install -e "." - -.. _testsuite: - -Test Suite ----------- - -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 `_. - -Stingray uses `py.test `_ and `tox -`_ for testing. To run the tests, try:: - - $ 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: - -.. doctest-skip:: - - >>> import stingray - >>> stingray.test() - -Documentation -------------- - -The documentation including tutorials is hosted `here `_. -The documentation uses `sphinx `_ to build and requires the extensions `sphinx-astropy `_ and `nbsphinx `_. - -You can build the API reference yourself by going into the ``docs`` folder within the ``stingray`` root -directory and running the ``Makefile``: :: - - $ 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 ``./docs/_build/index.rst`` from -the stingray source directory. - diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index 0c733052f..000000000 --- a/docs/intro.rst +++ /dev/null @@ -1,69 +0,0 @@ -################################################## -Stingray and Spectral Timing: A Brief Introduction -################################################## - -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. - -For a brief overview of the history and state-of-the-art in spectral timing, and for more information about the design and capabilities of Stingray, please refer to `Huppenkothen et al. (2019) `_. - -Features -======== -Current Capabilities --------------------- - -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, :math:`Z^2_n` test - -Future Plans ------------- - -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 :doc:`get in touch `! - -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 - -Platform-specific issues ------------------------- - -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. - -Presentations -============= - -Members of the Stingray team have given a number of presentations which introduce Stingray. -These include: -- `2nd Severo Ochoa School on Statistics, Data Mining, and Machine Learning (2021) `_ -- `9th Microquasar Workshop (2021) `_ -- `European Week of Astronomy and Space Science (2018) `_ -- `ADASS (Astronomical Data Analysis Software and Systems; meeting 2017, proceedings 2020) `_ -- `AAS 16th High-Energy Astrophysics Division meeting (2017) `_ -- `European Week of Astronomy and Space Science 2017 `_ -- `Python in Astronomy (2016) `_