Merge pull request #144 from StingraySoftware/update-docs

Zsearch plot
StingraySoftware · Apr 2, 2022 · aa02e89 · aa02e89
2 parents 0d3d64f + 4e621b5
commit aa02e89
Show file tree

Hide file tree

Showing 4 changed files with 110 additions and 87 deletions.
diff --git a/docs/images/zsearch_plot.jpeg b/docs/images/zsearch_plot.jpeg
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,26 +23,11 @@ Description
 This set of command-line scripts based on
 `Stingray <https://github.com/StingraySoftware/stingray>`__ is designed
 to do correctly and fairly easily a **quick-look (spectral-) timing
-analysis** of X-ray data, treating properly the gaps in the data due,
-e.g., to occultation from the Earth or passages through the SAA.
-
-Originally, its development as MaLTPyNT - Matteo's Libraries and Tools
-in Python for NuSTAR Timing - was driven by the need of performing
-aperiodic timing analysis on NuSTAR data, whose long dead time made it
-difficult to treat power density spectra with the usual tools. By
-exploiting the presence of two independent detectors, one could use the
-**cospectrum** as a proxy for the power density spectrum (for an
-explanation of why this is important, look at Bachetti et al., *ApJ*,
-800, 109 -`arXiv:1409.3248 <http://arxiv.org/abs/1409.3248>`__).
-
-Today, this set of command line scripts is much more complete and it is
-capable of working with the data of many more satellites. Among the
+analysis** of X-ray data. Among the
 features already implemented are power density and cross spectra, time
 lags, pulsar searches with the Epoch folding and the Z\_n^2 statistics,
-color-color and color-intensity diagrams. More is in preparation:
-rms-energy, lag-energy, covariance-energy spectra, Lomb-Scargle
-periodograms and in general all that is available in
-`Stingray <https://github.com/StingraySoftware/stingray>`__. The
+color-color and color-intensity diagrams, rms-energy, lag-energy,
+covariance-energy spectra. The
 analysis done in HENDRICS will be compatible with the graphical user
 interface `DAVE <https://github.com/StingraySoftware/dave>`__, so that
 users will have the choice to analyze single datasets with an easy
@@ -61,13 +46,15 @@ What's new
 HENDRICS 7.0
 ~~~~~~~~~~~~
 
-+ Based on [Stingray 1.0](https://github.com/StingraySoftware/stingray/releases/tag/v1.0-beta), bringing a huge bump in performance
++ Based on `Stingray 1.0 <https://github.com/StingraySoftware/stingray/releases/tag/v1.>`__, bringing a huge bump in performance
++ Accepts many more file formats for round-trip of Stingray objects, thanks to the new functionality of Stingray.
 + Energy-filtered periodograms
-+ A wider range of normalizations available for both HENfold and HENphaseogram, with more options (e.g. smoothing) and higher-contrast color map by default
++ A wider range of normalizations available for both ``HENfold`` and ``HENphaseogram``, with more options (e.g. smoothing) and higher-contrast color map by default
 + Many fixes to mission-specific files
-+ Better info returned by Z searches, including pulse amplitude estimates
++ Better info returned by Z/EF searches, including pulse amplitude estimates
++ New upper limit functionality in Z/EF searches with no candidates
++ ``HENplot`` now estimates the error of frequency and frequency derivative searches returned by ``HENzsearch``  and ``HENefsearch`` with option ``--fast``
 + Add ability to split files at a given MJD
-+ New upper limit functionality in Z searches with no candidates
 
 
 HENDRICS 6.0

diff --git a/docs/scripts/cli.rst b/docs/scripts/cli.rst
@@ -437,8 +437,9 @@ HENfold
 
     usage: HENfold [-h] [-f FREQ] [--fdot FDOT] [--fddot FDDOT] [--tref TREF]
                    [-n NBIN] [--nebin NEBIN] [--emin EMIN] [--emax EMAX]
-                   [--norm NORM] [--out-file-root OUT_FILE_ROOT] [--pepoch PEPOCH]
-                   [-p DEORBIT_PAR] [--loglevel LOGLEVEL] [--debug] [--test]
+                   [--out-file-root OUT_FILE_ROOT] [--pepoch PEPOCH] [--norm NORM]
+                   [--colormap COLORMAP] [-p DEORBIT_PAR] [--loglevel LOGLEVEL]
+                   [--debug] [--test]
                    file
 
     Plot a folded profile
@@ -456,11 +457,21 @@ HENfold
       --nebin NEBIN         Number of energy bins (Y axis) of the profile
       --emin EMIN           Minimum energy (or PI if uncalibrated) to plot
       --emax EMAX           Maximum energy (or PI if uncalibrated) to plot
-      --norm NORM           --norm to1: Normalize hist so that the maximum at each
-                            energy is one. --norm ratios: Divide by mean profile
       --out-file-root OUT_FILE_ROOT
                             Root of the output files (plots and csv tables)
       --pepoch PEPOCH       Reference epoch for timing parameters (MJD)
+      --norm NORM           Normalization for the dynamical phase plot. Can be:
+                            'to1' (each profile normalized from 0 to 1); 'std'
+                            (subtract the mean and divide by the standard
+                            deviation); 'sub' (just subtract the mean of each
+                            profile); 'ratios' (divide by the average profile, to
+                            highlight changes). Prepending 'median' to any of
+                            those options uses the median in place of the mean.
+                            Appending '_smooth' smooths the 2d array with a
+                            Gaussian filter. E.g. mediansub_smooth subtracts the
+                            median and smooths the imagedefault None
+      --colormap COLORMAP   Change the color map of the image. Any matplotlib
+                            colormap is valid
       -p DEORBIT_PAR, --deorbit-par DEORBIT_PAR
                             Deorbit data with this parameter file (requires PINT
                             installed)
@@ -524,7 +535,7 @@ HENjoinevents
 
 ::
 
-    usage: HENjoinevents [-h] [-o OUTPUT] files [files ...]
+    usage: HENjoinevents [-h] [-o OUTPUT] [--ignore-instr] files [files ...]
 
     Read a cleaned event files and saves the relevant information in a standard
     format
@@ -536,6 +547,7 @@ HENjoinevents
       -h, --help            show this help message and exit
       -o OUTPUT, --output OUTPUT
                             Name of output file
+      --ignore-instr        Ignore instrument names in channels
 
 
 HENlags
@@ -650,9 +662,9 @@ HENphaseogram
                          [--periodogram PERIODOGRAM] [-n NBIN] [--ntimes NTIMES]
                          [--binary]
                          [--binary-parameters BINARY_PARAMETERS BINARY_PARAMETERS BINARY_PARAMETERS]
-                         [--emin EMIN] [--emax EMAX] [--norm NORM] [--plot-only]
-                         [--pepoch PEPOCH] [-p DEORBIT_PAR] [--test]
-                         [--loglevel LOGLEVEL] [--debug]
+                         [--emin EMIN] [--emax EMAX] [--plot-only]
+                         [--pepoch PEPOCH] [--norm NORM] [--colormap COLORMAP]
+                         [-p DEORBIT_PAR] [--test] [--loglevel LOGLEVEL] [--debug]
                          file
 
     Plot an interactive phaseogram
@@ -675,11 +687,20 @@ HENphaseogram
                             Initial values for binary parameters
       --emin EMIN           Minimum energy (or PI if uncalibrated) to plot
       --emax EMAX           Maximum energy (or PI if uncalibrated) to plot
-      --norm NORM           Normalization for the phaseogram. Can be 'to1' (each
-                            profile normalized from 0 to 1); 'mediansub' (just
-                            subtract the median from each profile); default None
       --plot-only           Only plot the phaseogram
       --pepoch PEPOCH       Reference epoch for timing parameters (MJD)
+      --norm NORM           Normalization for the dynamical phase plot. Can be:
+                            'to1' (each profile normalized from 0 to 1); 'std'
+                            (subtract the mean and divide by the standard
+                            deviation); 'sub' (just subtract the mean of each
+                            profile); 'ratios' (divide by the average profile, to
+                            highlight changes). Prepending 'median' to any of
+                            those options uses the median in place of the mean.
+                            Appending '_smooth' smooths the 2d array with a
+                            Gaussian filter. E.g. mediansub_smooth subtracts the
+                            median and smooths the imagedefault None
+      --colormap COLORMAP   Change the color map of the image. Any matplotlib
+                            colormap is valid
       -p DEORBIT_PAR, --deorbit-par DEORBIT_PAR
                             Deorbit data with this parameter file (requires PINT
                             installed)
@@ -943,7 +964,7 @@ HENsumfspec
       -h, --help            show this help message and exit
       -o OUTNAME, --outname OUTNAME
                             Output file name for summed (C)PDS. Default:
-                            tot_(c)pds.nc
+                            tot_(c)pds.p
 
 
 HENvarenergy

diff --git a/docs/tutorials/pulsars.rst b/docs/tutorials/pulsars.rst
@@ -25,54 +25,7 @@ mission-specific event file, we have a HENRICS-format event file (ending with
     $ ls
     002A.evt 002A_ev.nc
 
-To look for pulsations with the epoch folding around the candidate frequency
-9.9 Hz, we can run `HENefsearch` as such:
-
-::
-
-    $ HENefsearch -f 9.85 -F 9.95 -n 64 --fit-candidates
-
-where the options `-f` and `-F` give the minimum and maximum frequencies to
-search, `-n` the number of bins in the pulsed profile and with `--fit-candidates`
-we specify to not limit the search to the epoch folding, but also look for
-peaks and fit them to find their centroids.
-
-The output of the search is in a file ending with `_EF.nc` or `_EF.p`, while
-the best-fit model is recorded in pickle files
-
-::
-
-    $ ls
-        002A.evt 002A_ev.nc 002A_EF.nc 002A_EF__mod0__.p
-
-To use the Z search, we can use the `HENzsearch` script with very similar options:
-
-::
-
-    $ HENzsearch -f 9.85 -F 9.95 -N 2 --fit-candidates
-
-where the `-N` option specifies the number of harmonics to use for the search.
-
-The output of the search and the fit is recorded in similar files as Epoch folding
-
-::
-
-    $ ls
-        002A.evt 002A_ev.nc 002A_Z2n.nc 002A_Z2n__mod0__.p
-
-We can plot the results of this search with `HENplot`, as such:
-
-::
-
-    $ HENplot 002A_Z2n.nc
-
-|zn_search.png|
-
-
-.. |zn_search.png| image:: ../images/zn_search.png
-
-
-NEW: Accelerated searches
+Accelerated searches
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 HENDRICS now implements the accelerated search à la Ransom+2002: starting from a single
 FFT, we convolve it with responses corresponding to different values of "acceleration",
@@ -108,11 +61,19 @@ Example with a *NuSTAR* observation of a famous X-ray binary pulsar:
 See ``HENaccelsearch -h`` for more details.
 
 
-NEW: Fast Z2n searches
-~~~~~~~~~~~~~~~~~~~~~~
-HENDRICS now implements a much faster, experimental algorithm for pulsation searches
+Fast Z2n searches
+~~~~~~~~~~~~~~~~~
+HENDRICS implements a fast algorithm for pulsation searches
 with the Z^2_n statistics.
 Select this algorithm with the ``--fast`` option on the command line of `HENzsearch`.
+
+::
+
+    $ HENefsearch -f 9.85 -F 9.95 -n 64 --fast -N 3 mistery_psrA_nustar_fpma_ev.nc
+
+Here, we are searching from 9.85 to 9.95 Hz, using 3 harmonics (so, ..math:`Z^2_3`
+stats), pre-binning the pulse profile with 64 bins.
+
 Instead of calculating the phase of all photons at each trial value of frequency and
 derivative, we pre-bin the data in small chunks and shift the different chunks to the
 amount required by different trial values.
@@ -135,12 +96,66 @@ The only actions the user can do are the selection of the mean fdot and the para
 frequency/fdot combination (npfact=2 means that the number of trial values will be
 double for both the frequency and the fdot, so four times the trials in the end).
 
-The results of this Z search can be plotted with `HENplot`. There is at the moment
-no automatic fitting being performed as in the slow option.
+The results of this Z search can be plotted with `HENplot`. HENplot does more than just
+plotting the results: it also creates contours around the best solution, and uses
+the ..math:`\chi^2_n` statistics to estimate the error bars on frequency and frequency
+derivative.
 
+|zsearch_plot.jpeg|
+
+.. |zsearch_plot.jpeg| image:: ../images/zsearch_plot.jpeg
 .. |fast_zsearch.jpeg| image:: ../images/fast_zsearch.jpeg
 
 
+Slow (and outdated) method
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+To look for pulsations with the epoch folding around the candidate frequency
+9.9 Hz, we can run `HENefsearch` as such:
+
+::
+
+    $ HENefsearch -f 9.85 -F 9.95 -n 64 --fit-candidates mistery_psrA_nustar_fpma_ev.nc
+
+where the options `-f` and `-F` give the minimum and maximum frequencies to
+search, `-n` the number of bins in the pulsed profile and with `--fit-candidates`
+we specify to not limit the search to the epoch folding, but also look for
+peaks and fit them to find their centroids.
+
+The output of the search is in a file ending with `_EF.nc` or `_EF.p`, while
+the best-fit model is recorded in pickle files
+
+::
+
+    $ ls
+        002A.evt 002A_ev.nc 002A_EF.nc 002A_EF__mod0__.p
+
+To use the Z search, we can use the `HENzsearch` script with very similar options:
+
+::
+
+    $ HENzsearch -f 9.85 -F 9.95 -N 2 --fit-candidates
+
+where the `-N` option specifies the number of harmonics to use for the search.
+
+The output of the search and the fit is recorded in similar files as Epoch folding
+
+::
+
+    $ ls
+        002A.evt 002A_ev.nc 002A_Z2n.nc 002A_Z2n__mod0__.p
+
+We can plot the results of this search with `HENplot`, as such:
+
+::
+
+    $ HENplot 002A_Z2n.nc
+
+|zn_search.png|
+
+
+.. |zn_search.png| image:: ../images/zn_search.png
+
+
 Measuring frequency derivatives interactively
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~