Merge pull request #137 from GreenBankObservatory/update_docs

Updates docs and adds sphinx-inline-tabs
GreenBankObservatory · Nov 28, 2023 · 7533bce · 7533bce
2 parents 8f20006 + 14f6d14
commit 7533bce
Show file tree

Hide file tree

Showing 7 changed files with 114 additions and 38 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -57,6 +57,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.mermaid",
     "numpydoc",
+    "sphinx_inline_tabs",
 ]
 
 numpydoc_show_class_members = True

diff --git a/docs/source/examples/positionswitch.rst b/docs/source/examples/positionswitch.rst
@@ -103,26 +103,37 @@ Single beam position-switched (PS) data is retrieved using :meth:`~dysh.fits.gbt
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
     >>> import astropy.units as u
+    >>> import wget
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
+Download the data from GBO
+
+.. code:: python
+
+    >>> filename = wget.download("http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits")
+    >>> print(filename)
+        TGBT21A_501_11.raw.vegas.fits
+
+.. note::
+    The data used for this tutorial is ~800 MB. Make sure you have enough disk space and bandwidth to download it.
+
 Then load your SDFITS file containing PS data. In this example, we use a
 `GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_
 
 .. code:: python
 
-    >>> f = 'TGBT21A_501_11.raw.vegas.fits'
-    >>> sdfits = GBTFITSLoad(f)
+    >>> sdfits = GBTFITSLoad(filename)
 
 The returned `sdfits` can be probed for information
 
 .. code:: python
 
     >>> sdfits.info()
-        Filename: /data/gbt/examples/onoff-L/data/TGBT21A_501_11.raw.vegas.fits
-        No.    Name      Ver    Type      Cards   Dimensions   Format
-          0  PRIMARY       1 PrimaryHDU      12   ()
-          1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']
+    Filename: TGBT21A_501_11.raw.vegas.fits
+    No.    Name      Ver    Type      Cards   Dimensions   Format
+      0  PRIMARY       1 PrimaryHDU      12   ()
+        1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']
 
 You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
 
@@ -138,8 +149,6 @@ Retrieve a scan and its partner ON or OFF, selecting an IF number and polarizati
 .. code:: python
 
     >>> psscan = sdfits.getps(152, ifnum=0, plnum=0)
-    >>> psscan.calibrate() # this will be eventually be subsumed into `calibrate=True` in `getps`
-        PSSCAN nrows = 302
 
 The system temperature array (`numpy.ndarray`) is stored in `tsys`
 
@@ -148,7 +157,7 @@ The system temperature array (`numpy.ndarray`) is stored in `tsys`
     >>> print(f"T_sys = {psscan[0].tsys.mean():.2f} K")
         T_sys = 17.17 K
 
-Then time average the data, using system temperature weighting (other option is 'equal' weighting; 'tsys' is the default if no `weights` parameter is given. Future upgrade will allow the user to provide a numeric weights array). The returned object is :class:`~dysh.spectra.spectrum.Spectrum`, which has a default `matplotlib`-based plotter attached
+Then time average the data, using system temperature weighting (other option is 'equal' weighting; 'tsys' is the default if no `weights` parameter is given. (Future upgrades will allow the user to provide a numeric weights array.) The returned object is :class:`~dysh.spectra.spectrum.Spectrum`, which has a default `matplotlib`-based plotter attached
 
 .. code:: python
 
@@ -162,7 +171,7 @@ The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis
 
 .. code:: python
 
-    >>> ta[0].plot(xaxis_unit="km/s",yaxis_unit="mK",ymin=-100,ymax=500,xmin=3000,xmax=4500)
+    >>> ta[0].plot(xaxis_unit="km/s", yaxis_unit="mK", ymin=-100, ymax=500, xmin=3000, xmax=4500)
 
 .. figure:: img/ps_152_zoom.png
     :alt: The spectrum plot zoomed in along both axes to frame a central emission line.
@@ -175,18 +184,23 @@ The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis
 Removing a baseline
 ===================
 
-Baselines can be removed from :class:`~dysh.spectra.spectrum.Spectrum` with the :meth:`~dysh.spectra.spectrum.Spectrum.baseline` function.   Users provide baseline degree and optionally exclude region in any conformable x-axis unit (e.g., frequency, velocity, channel).  The default model is polynomial (:class:`~astropy.modeling.polynomial.Polynomial1D`) but a Chebyshev series (:class:`~astropy.modeling.polynomial.Chebyshev1D`)
-is also .  The baseline is removed if `remove=True`.
+Baselines can be removed from :class:`~dysh.spectra.spectrum.Spectrum` with the :meth:`~dysh.spectra.spectrum.Spectrum.baseline` function.
+Users provide baseline degree and optionally exclude region in any conformable x-axis unit (e.g., frequency, velocity, channel).
+The default model is polynomial (:class:`~astropy.modeling.polynomial.Polynomial1D`) but a Chebyshev series (:class:`~astropy.modeling.polynomial.Chebyshev1D`) is also available.
+The baseline is removed if `remove=True`.
 
 .. code:: python
 
     >>> kms = u.km/u.s
-    >>> ta.baseline(degree=2, exclude=[3600,4100]*kms, remove=True)
+    >>> ta[0].baseline(degree=2, exclude=[3600*kms,4100*kms], remove=True)
     EXCLUDING [Spectral Region, 1 sub-regions:
       (1401242184.363393 Hz, 1403551474.1090915 Hz)
     ]
-    >>> ta.plot(ymin=-200)
-    >>> print(ta.baseline_model)Model: Polynomial1D
+    WARNING: The fit may be poorly conditioned
+     [astropy.modeling.fitting]
+    >>> ta[0].plot(ymin=-200)
+    >>> print(ta[0].baseline_model)
+    Model: Polynomial1D
     Inputs: ('x',)
     Outputs: ('y',)
     Model set size: 1

diff --git a/docs/source/examples/subbeamnod.rst b/docs/source/examples/subbeamnod.rst
@@ -74,4 +74,5 @@ The SubBeamNod scans are 43, 46, and 54.  Retrieve and calibrate a SubBeamNod sc
 .. code:: python
 
     >>> sbn = sdfits.subbeamnod(scan=43, fdnum=1, ifnum=0, weights='tsys')
-    >>> sbn[0].plot()
+    >>> ta = sbn.timeaverage(weights="tsys")
+    >>> ta[0].plot()
diff --git a/docs/source/examples/totalpower.rst b/docs/source/examples/totalpower.rst
@@ -10,27 +10,38 @@ Single beam total power (TP) data is retrieved using :meth:`~dysh.fits.gbtfitslo
 .. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
+    >>> import wget
     >>> import numpy as np
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
+Download the data from GBO
+
+.. code:: python
+
+    >>> filename = wget.download("http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits")
+    >>> print(filename)
+        TGBT21A_501_11.raw.vegas.fits
+
+.. note::
+    The data used for this tutorial is ~800 MB. Make sure you have enough disk space and bandwidth to download it.
+
 Then load your SDFITS file containing TP data. In this example, we use a
 `GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_
 
 .. code:: python
 
-    >>> f = 'TGBT21A_501_11.raw.vegas.fits'
-    >>> sdfits = GBTFITSLoad(f)
+    >>> sdfits = GBTFITSLoad(filename)
 
 The returned `sdfits` can be probed for information
 
 .. code:: python
 
     >>> sdfits.info()
-        Filename: /data/gbt/examples/onoff-L/data/TGBT21A_501_11.raw.vegas.fits
-        No.    Name      Ver    Type      Cards   Dimensions   Format
-          0  PRIMARY       1 PrimaryHDU      12   ()
-          1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']
+    Filename: TGBT21A_501_11.raw.vegas.fits
+    No.    Name      Ver    Type      Cards   Dimensions   Format
+      0  PRIMARY       1 PrimaryHDU      12   ()
+      1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']
 
 You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
 
@@ -52,19 +63,19 @@ The `~dysh.spectra.scan.GBTTPScan` contains the individual integrations.  The sy
 .. code:: python
 
     >>> print('%s' % (np.array2string(tpscan[0].tsys, precision=2)))
-        [16.89 16.89 16.94 16.77 16.96 16.94 16.87 16.86 16.92 16.86 16.85 16.97
-         16.79 16.86 16.96 17.02 16.94 16.89 16.87 16.92 16.88 16.86 16.92 17.02
-         16.77 16.8  17.   16.91 16.91 16.86 16.98 16.81 16.88 17.03 16.96 16.95
-         16.8  16.86 16.91 17.02 16.77 17.03 17.03 16.88 16.78 16.88 16.83 16.84
-         16.88 17.03 17.01 16.98 16.99 16.92 16.88 16.74 16.87 16.92 16.81 16.88
-         16.99 16.97 16.92 17.03 16.94 16.84 16.86 17.05 16.87 16.97 16.82 16.83
-         16.98 17.06 17.11 16.98 16.86 17.02 16.88 16.94 16.93 16.98 16.81 16.83
-         16.98 17.   16.87 16.91 16.91 16.93 17.   16.91 17.08 16.85 16.9  16.85
-         16.89 16.95 17.03 16.98 16.9  16.98 16.98 16.93 16.83 17.03 16.97 16.92
-         16.87 16.99 16.87 16.84 16.97 16.84 16.89 16.89 16.98 16.89 16.81 16.76
-         16.94 16.95 16.89 16.87 16.94 16.91 17.1  16.91 16.84 16.84 16.88 16.95
-         17.04 16.88 16.9  17.03 16.9  16.84 16.99 16.95 16.94 17.02 17.01 16.91
-         16.95 16.91 16.92 17.08 16.67 17.06 17.14]
+    [17.46 17.47 17.51 17.48 17.27 17.24 17.43 17.51 17.36 17.41 17.27 17.36
+     17.28 17.31 17.15 17.   17.54 17.21 17.4  17.38 17.49 17.43 17.15 17.2
+     17.45 17.15 17.31 17.31 17.1  17.48 17.29 17.24 17.52 17.31 17.19 17.1
+     17.35 17.14 17.38 17.48 17.22 17.5  17.33 17.27 17.41 17.2  17.48 17.21
+     17.37 17.47 17.25 17.18 17.25 17.17 17.14 17.36 17.25 17.28 17.25 17.19
+     17.36 17.14 17.48 17.17 17.36 17.43 17.51 17.38 17.29 17.19 17.4  17.63
+     17.36 17.27 17.19 17.45 17.39 17.48 17.24 17.31 17.13 17.22 17.24 17.42
+     17.1  17.5  17.38 17.24 17.42 17.32 17.27 17.35 17.29 17.49 17.4  17.18
+     17.18 17.28 17.26 17.48 17.38 17.35 17.28 17.25 17.28 17.39 17.25 17.24
+     17.08 17.28 17.28 17.36 17.53 17.38 17.34 17.48 17.43 17.49 17.29 17.44
+     17.32 17.5  17.11 17.38 17.24 17.2  17.37 17.21 17.19 17.32 17.01 17.48
+     17.34 17.35 17.5  17.01 17.44 17.45 17.4  17.38 17.18 17.44 17.22 17.25
+     17.28 17.19 17.38 17.34 17.3  17.26 17.37]
 
 You can time-average the data, in this example with equal weighting per integration, and plot it
 

diff --git a/docs/source/for_beta_testers/beta_testing.rst b/docs/source/for_beta_testers/beta_testing.rst
@@ -38,4 +38,53 @@ Example feedback
 Here are examples of feedback on GitHub
 
 * reporting an issue, `Issue #88 <https://github.com/GreenBankObservatory/dysh/issues/88>`_
-* requesting a modification, `Issue #78, <https://github.com/GreenBankObservatory/dysh/issues/78>`_
+* requesting a modification, `Issue #78 <https://github.com/GreenBankObservatory/dysh/issues/78>`_
+
+
+Installing `dysh`
+=================
+
+Here we provide additional installation steps that include creating a virtual environment to keep `dysh` isolated from your system `Python` version.
+We provide steps for working in one of `GBO data reduction hosts <https://greenbankobservatory.org/science/gbt-observers/public-access-data-reduction/>`_ (e.g., fourier), and if you're working outside one of the GBO data reduction hosts.
+
+.. tab:: At GBO
+
+    Create a `Python3.11` virtual environment
+
+    .. code:: bash
+
+        /users/gbosdd/python/bin/python3.11 -m venv /home/scratch/$USER/dysh-0.2-env
+
+    Activate your virtual environment
+
+    .. code:: bash
+
+        source /home/scratch/$USER/dysh-0.2-env/bin/activate
+
+    Install `dysh` and Jupyter Lab
+
+    .. code:: bash
+
+        pip install jupyterlab dysh==0.2.0b
+
+.. tab:: Outside of GBO
+
+    Create a `Python3.9+` virtual environment
+
+    .. code:: bash
+
+        python3 -m venv /path/to/venv
+
+    Activate your virtual environment
+
+    .. code:: bash
+
+        source /path/to/venv/bin/activate
+
+    Install `dysh` and Jupyter Lab
+
+    .. code:: bash
+
+        pip install jupyterlab dysh==0.2.0b
+
+In the future we will provide `dysh` executables at GBO.
diff --git a/docs/source/getting_started/tutorials/GBT/tutorial-positionswitch.rst b/docs/source/getting_started/tutorials/GBT/tutorial-positionswitch.rst
@@ -82,15 +82,14 @@ The following lines will let you calibrate and time average the position switche
 .. code:: python
 
     >>> psscan = sdfits.getps(152, ifnum=0, plnum=0)
-    >>> psscan.calibrate()
     >>> ta = psscan.timeaverage(weights='tsys')
 
 Plotting the calibrated data
 ----------------------------
 
 .. code:: python
 
-    >>> ta[0].plot(xaxis_unit="km/s",yaxis_unit="mK",ymin=-100,ymax=500,xmin=3000,xmax=4500)
+    >>> ta[0].plot(xaxis_unit="km/s", yaxis_unit="mK", ymin=-100, ymax=500, xmin=3000, xmax=4500)
 
 .. figure:: img/ps_152_zoom.png
     :alt: The spectrum plot zoomed in along both axes to frame a central emission line.

diff --git a/pyproject.toml b/pyproject.toml
@@ -31,6 +31,7 @@ dependencies = [
   "specutils",
   "sphinx",
   "myst-parser",
+  "sphinx-inline-tabs",
   "ipython",
   "wget"
  ]