Merge pull request #652 from StingraySoftware/abigailstev-docs-update

Docs update for v1

CHANGELOG.rst

@@ -1,9 +1,9 @@
 Changelog
 =========
 
-v1.0beta (2022-02-25)
+v1.0 (2022-03-29)
 ---------------------
-TL,DR: these things will break your code with v1.0beta:
+TL,DR: these things will break your code with v1.0:
 
 - Python version < 3.8
 - The ``gtis`` keyword in `pulse/pulsar.py` (it is now ``gti``, without the 's')
@@ -18,7 +18,7 @@ New
 - New infrastructure for converting ``EventList`` and ``LightCurve`` objects into Astropy ``TimeSeries``
 - New infrastructure for converting most Stingray classes into Astropy ``Table`` objects, Xarray and Pandas data frames.
 - Save and load of most Stingray classes to/from many different file formats (``pickle``, ``ECSV``, ``HDF5``, ``FITS``, and all formats compatible with Astropy Table)
-- Accept input ``EventList`` in ``DynamicalPowerSpectrum`` 
+- Accept input ``EventList`` in ``DynamicalPowerSpectrum``
 - New ``stingray.fourier`` module containing the basic timing products, usable on ``numpy`` arrays, and centralizes fft import
 - New methods in ``Crossspectrum`` and ``Powerspectrum`` to load data from specific inputs: ``from_events``, ``from_lightcurve``, ``from_time_array``, ``from_lc_list`` (``from_time_array`` was also tested using memory-mapped event lists as inputs: useful in very large datasets)
 - New and improved spectral timing methods: ``ComplexCovarianceSpectrum``, ``CovarianceSpectrum``, ``LagSpectrum``, ``RmsSpectrum``
@@ -52,7 +52,9 @@ Bug fixes
 
 `Full list of changes`__
 
-__ https://github.com/StingraySoftware/stingray/compare/v0.3...v1.0-beta
+__ https://github.com/StingraySoftware/stingray/compare/v0.3...v1.0
+
+v1.0beta was released on 2022-02-25.
 
 v0.3 (2021-05-31)
 -----------------

CONTRIBUTING.md

@@ -4,21 +4,33 @@
 
 > All great things have small beginnings.
 
-Hello there! We love and appreciate every small contribution you can make to improve stingray!
-We are proudly open source and believe our(yes! yours as well) work will help enhance the quality of research around the world.  We want to make contributing to stingray as easy and transparent as possible, whether it's:
+Hello there! We love and appreciate every small contribution you can make to
+improve Stingray! We are proudly open source and believe our(yes! yours as
+well) work will help enhance the quality of research around the world.  We
+want to make contributing to stingray as easy and transparent as possible,
+whether it's:
 
 - Reporting a bug
 - Discussing the current state of the code
 - Submitting a fix
 - Proposing new features
 
-A successful project is not just built by amazing programmers but by the combined, unrelenting efforts of coders, testers, reviewers, and documentation writers. There are a few guidelines that we need all contributors to follow so that we can have a chance of keeping on top of things.
+A successful project is not just built by amazing programmers but by the
+combined, unrelenting efforts of coders, testers, reviewers, and documentation
+writers. There are a few guidelines that we need all contributors to follow so
+that we can have a chance of keeping on top of things.
 
 ## Contribution Guidelines
 
 ---
 
-Contributions from everyone, experienced and inexperienced, are welcome! If you don't know where to start, look at the [Open Issues](https://github.com/StingraySoftware/stingray/issues) and/or get involved in our [Slack channel](http://slack-invite.timelabtechnologies.com/) . This code is written in Python 3.8+, but in general we will follow the Astropy/Numpy minimum Python versions. Tests run at each commit during Pull Requests, so it is easy to single out points in the code that break this compatibility.
+Contributions from everyone, experienced and inexperienced, are welcome! If
+you don't know where to start, look at the
+[Open Issues](https://github.com/StingraySoftware/stingray/issues) and/or get
+involved in our [Slack channel](http://slack-invite.timelabtechnologies.com/).
+This code is written in Python 3.8+, but in general we will follow the Astropy/
+Numpy minimum Python versions. Tests run at each commit during Pull Requests,
+so it is easy to single out points in the code that break this compatibility.
 
 - **Branches:**
     - Don't use your main **branch (forked) for anything. Consider deleting your main** branch.
@@ -36,7 +48,10 @@ Contributions from everyone, experienced and inexperienced, are welcome! If you
 
 ### Contribution Workflow
 
-These, conceptually, are the steps you will follow in contributing to stingray. These steps keep work well organized, with readable history. This in turn makes it easier for project maintainers (that might be you) to see what you’ve done, and why you did it:
+These, conceptually, are the steps you will follow in contributing to
+Stingray. These steps keep work well organized, with readable history. This in
+turn makes it easier for project maintainers (that might be you) to see what
+you’ve done, and why you did it:
 
 1. Regularly fetch latest stingray development version `stingray/main` from GitHub.
 2. Make a new feature branch. **Recommended:** Use virtual environments to work on branch.
@@ -118,7 +133,9 @@ Code Reviews are super-useful: another contributor can review the code, which me
 
 ---
 
-The testing framework used by stingray is the pytest framework with tox. To run the tests, you will need to make sure you have the pytest package (version 3.1 or later) as well as the tox tool installed.
+The testing framework used by stingray is the pytest framework with tox. To
+run the tests, you will need to make sure you have the pytest package (version
+3.1 or later) as well as the tox tool installed.
 
 - Execute tests using the ```tox -e <test environment>``` command.
 - All tests should be py.test compliant: [http://pytest.org/latest/](http://pytest.org/latest/).
@@ -130,4 +147,4 @@ The testing framework used by stingray is the pytest framework with tox. To run
 
 ---
 
-- Please refer [CODE_OF_CONDUCT.md](https://github.com/StingraySoftware/stingray/blob/master/CODE_OF_CONDUCT.md) to read about the Community Guidelines
+- Please refer to [CODE_OF_CONDUCT.md](https://github.com/StingraySoftware/stingray/blob/main/CODE_OF_CONDUCT.md) to read about the Community Guidelines

CREDITS.rst

@@ -14,10 +14,44 @@ Stingray Project Coordinators
 Contributors
 ============
 
+* Riccardo Campana
+* Meg Davis
+* Amogh Desai
+* Omar Gamal
+* Nitish Garg
+* Nick Gorgone
+* Anurag Hota
+* Ajit Jadhav
+* Usman Khan
+* Sambhav Kothari
+* Sandeep Kumar
+* Max Mahlke
+* Evandro Martinez Ribeiro
+* Himanshu Mishra
+* Sashank Mishra
+* Stuart Mumford
+* paopaofi
+* parkma99
+* Francesco Pisanu
+* Rashmi Raj
+* Haroon Rashid
+* Achilles Rasquinha
+* Saurav Sachidanand
+* Parul Sethi
+* Swapnil Sharma
+* Brigitta Sipocz
+* Arfon Smith
+* John Swinbank
+* Akash Tandon
+* tappina
+* Mihir Tripathi
+* Ricardo Vallés Blanco
+* Dhruv Vats
+
 If you have contributed to Stingray and your name is missing,
 please send an email to the coordinators, or
-`open a pull request for this page <https://github.com/StingraySoftware/stingray/CREDITS.rst>`_
-in the `Stingray repository <https://github.com/StingraySoftware/stingray>`_)
+`open a pull request for this page <https://github.com/StingraySoftware/stingray/blob/main/CREDITS.rst>`_
+in the `Stingray repository <https://github.com/StingraySoftware/stingray>`_.
 
 Acknowledgements
 ================

docs/api.rst

@@ -88,6 +88,8 @@ Dynamical Powerspectrum
 .. autoclass:: stingray.DynamicalPowerspectrum
    :members:
    :inherited-members:
+
+----
 
 CrossCorrelation
 ----------------

docs/citing.rst

@@ -3,7 +3,7 @@ Citing Stingray
 ***************
 
 Citations are still the main currency of the academic world, and *the* best way to ensure that Stingray continues to be supported and we can continue to work on it.
-If you use Stingray in data analysis leading to a publication, we ask that you cite *both* a `DOI <https://www.doi.org>`_ which points to the software itself *and* our papers describing the Stingray project.
+If you use Stingray in data analysis leading to a publication, we ask that you cite *both* a `DOI <https://www.doi.org>`_, which points to the software itself, *and* our papers describing the Stingray project.
 
 DOI
 ===
@@ -74,27 +74,6 @@ Please cite both of the following papers:
            document.body.removeChild(el);
        }
 
-       function copyAsclBib() {
-           var bibtex = `@MISC{2016ascl.soft08001H,
-             author = {{Huppenkothen}, Daniela and {Bachetti}, Matteo and {Stevens}, Abigail L. and {Migliari}, Simone and {Balm}, Paul},
-             title = "{Stingray: Spectral-timing software}",
-             keywords = {Software},
-             year = 2016,
-             month = aug,
-             eid = {ascl:1608.001},
-             pages = {ascl:1608.001},
-             archivePrefix = {ascl},
-             eprint = {1608.001},
-             adsurl = {https://ui.adsabs.harvard.edu/abs/2016ascl.soft08001H},
-             adsnote = {Provided by the SAO/NASA Astrophysics Data System}
-           }`;
-           const el = document.createElement('textarea');
-           el.value = bibtex;
-           document.body.appendChild(el);
-           el.select();
-           document.execCommand('copy');
-           document.body.removeChild(el);
-       }
    </script>
 
    <ul>

docs/contributing.rst

@@ -20,7 +20,6 @@ We encourage you to get involved with Stingray in any way you can!
 First, read through the `README <https://github.com/StingraySoftware/stingray/blob/master/README.rst>`_.
 Then, fork the `stingray <https://github.com/StingraySoftware/stingray>`_ and `notebooks <https://github.com/StingraySoftware/notebooks>`_ repositories (if you need a primer on GitHub and git version control, `look here <https://www.webpagefx.com/blog/web-design/git-tutorials-beginners/>`_) and work your way through the Jupyter notebook tutorials for the main modules.
 Once you've familiarized yourself with the basics of Stingray, go to the `Stingray issues page <https://github.com/StingraySoftware/stingray>`_ and try to tackle one!
-Other ways to get involved are outlined on the `project ideas <http://timelabtechnologies.com/ideas.html>`_ page, along with some astrophysical background/motivation.
-Finally, you can read `these slides <https://speakerdeck.com/abigailstev/stingray-pyastro16>`_ from an early talk on Stingray at the Python in Astronomy 2016 conference.
+Finally, you can read `these slides <https://speakerdeck.com/abigailstev/time-series-exploration-with-stingray>`_ from a talk on Stingray in 2021 at the 9th Microquasar Workshop.
 
 For organizing and coordinating the software development, we have a Slack group and a mailing list -- please use `this link <https://stingray-slack.herokuapp.com>`_ for Slack or send `one of us <https://github.com/orgs/StingraySoftware/people>`_ an email to join.

docs/dataexplo.rst

@@ -0,0 +1,28 @@
+Data Exploration
+****************
+
+These notebook tutorials show some ways to explore data with
+Stingray.
+
+A quick look at a NuSTAR observation
+====================================
+
+Stingray transparently loads datasets from many HEASOFT-supported missions.
+In this Tutorial, we will show an example quicklook of a NuSTAR observation.
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/DataQuickLook/Quicklook NuSTAR data with Stingray.ipynb
+
+
+Spectral timing exploration with NICER
+======================================
+
+In this Tutorial, we will show an example spectral timing exploration of a
+black hole binary using NICER data.
+
+.. toctree::
+   :maxdepth: 2
+
+   notebooks/Spectral Timing/Spectral Timing Exploration.ipynb

docs/history.rst

@@ -4,13 +4,6 @@ History
 
 .. include:: ../CHANGELOG.rst
 
-Performance improvements
-========================
-
-Version 0.2 introduced a few performance improvements when ``Lightcurve`` objects are created.
-Once the user defines either the counts per bin or the count rates, the other quantity will be evaluated _lazily_, the first time it is requested.
-Also, we introduce a new ``low_memory`` option in ``Lightcurve``: if selected, and users define e.g. ``counts``, ``countrate`` will be calculated _every_time it is requested, and will not be stored in order to free up RAM.
-
 Previous projects merged to Stingray
 ====================================
 

docs/index.rst

@@ -14,7 +14,7 @@ There are a number of official software packages for X-ray spectral fitting (XSP
 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 <http://www.lorentzcenter.nl/lc/web/2016/720/info.php3?wsid=720&venue=Oort/>`_: 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 (possibly a GUI) and an API for power users.
+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 <https://github.com/StingraySoftware/HENDRICS>`_.
@@ -33,9 +33,8 @@ Contents
    intro
    install
    core
-   quicklook
+   dataexplo
    modeling
-   spectime
    simulator
    pulsar
    deadtime

docs/install.rst

@@ -88,6 +88,11 @@ 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::
 
@@ -104,7 +109,7 @@ Documentation
 -------------
 
 The documentation including tutorials is hosted `here <https://docs.stingray.science/>`_.
-The documentation uses `sphinx <https://www.sphinx-doc.org/en/stable/>`_ to build and requires the extension sphinx-astropy <https://pypi.org/project/sphinx-astropy/>`_.
+The documentation uses `sphinx <https://www.sphinx-doc.org/en/stable/>`_ to build and requires the extensions `sphinx-astropy <https://pypi.org/project/sphinx-astropy/>`_ and `nbsphinx <https://pypi.org/project/nbsphinx/>`_.
 
 You can build the API reference yourself by going into the ``docs`` folder within the ``stingray`` root
 directory and running the ``Makefile``: ::
@@ -115,7 +120,7 @@ directory and running the ``Makefile``: ::
 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
+    $ 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.

docs/intro.rst

@@ -15,7 +15,7 @@ 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)
+* 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
@@ -60,7 +60,8 @@ 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) <https://github.com/abigailStev/timeseries-tutorial>`_
+- `9th Microquasar Workshop (2021) <https://speakerdeck.com/abigailstev/time-series-exploration-with-stingray>`_
 - `European Week of Astronomy and Space Science (2018) <http://ascl.net/wordpress/2018/05/24/software-in-astronomy-symposium-presentations-part-3/>`_
 - `ADASS (Astronomical Data Analysis Software and Systems; meeting 2017, proceedings 2020) <https://ui.adsabs.harvard.edu/abs/2020ASPC..522..521M/abstract>`_
 - `AAS 16th High-Energy Astrophysics Division meeting (2017) <https://speakerdeck.com/abigailstev/stingray-open-source-spectral-timing-software>`_

setup.cfg

@@ -4,7 +4,7 @@ author = Stingray Developers
 author_email = [email protected]
 license = MIT
 license_file = LICENSE.rst
-url = https://stingray.readthedocs.io/
+url = https://docs.stingray.science
 description = Time Series Methods For Astronomical X-ray Data
 long_description = file: README.rst
 long_description_content_type = text/x-rst
@@ -49,6 +49,7 @@ test =
     pytest
     pytest-astropy
 docs =
+    jinja2<=3.0.0
     docutils
     sphinx-astropy
     nbsphinx>=0.8.3,!=0.8.8