update docs

GreenBankObservatory · Oct 5, 2023 · 2f5046d · 2f5046d
1 parent ff25fed
commit 2f5046d
Show file tree

Hide file tree

Showing 32 changed files with 233 additions and 163 deletions.
diff --git a/docs/.env.template b/docs/.env.template
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/source/background/img/.gitkeep b/docs/source/background/img/.gitkeep
diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst
@@ -8,4 +8,4 @@ Why does this exist?
    :maxdepth: 2
 
    gbo_context
-   sdfits_files
+   sdfits_files/index
diff --git a/docs/source/background/sdfits_files.rst → ...ce/background/sdfits_files/gbt_sdfits.rst b/docs/source/background/sdfits_files.rst → ...ce/background/sdfits_files/gbt_sdfits.rst
@@ -1,15 +1,10 @@
-************
-SDFITS Files 
-************
+****************
+GBT SDFITS Files 
+****************
 
-Overview
-========
-The single-dish FITS (SDFITS) convention is used for observer-facing GBT data. The GBT records raw data to FITS files, and then the SDFITS filler populates SDFITS files with information the observer needs. 
-
-GBT Convention
-=================
-
-GBT SDFITS files contain 2 Header-Data Units (HDUs). Note that keys sometimes appear to be truncated because they can only have up to 8 letters. 
+Convention
+==========
+The single-dish FITS (SDFITS) convention is used for observer-facing GBT data. The GBT records raw data to FITS files, and then the SDFITS filler populates SDFITS files with information the observer needs. GBT SDFITS files contain 2 or more Header-Data Units (HDUs). Note that keys sometimes appear to be truncated because they can only have up to 8 letters. 
 
 HDU 0 (PRIMARY)
 ---------------

diff --git a/docs/source/background/sdfits_files/index.rst b/docs/source/background/sdfits_files/index.rst
@@ -0,0 +1,10 @@
+************
+SDFITS Files
+************
+
+Here are some of the telescopes which use SDFITS files.
+
+.. toctree::
+   :maxdepth: 2
+
+   gbt_sdfits
diff --git a/docs/source/design/img/.gitkeep b/docs/source/design/img/.gitkeep
diff --git a/docs/source/design/index.rst b/docs/source/design/index.rst
@@ -7,4 +7,5 @@ Stuff about the overall design
 .. toctree::
    :maxdepth: 2
 
-   sdfits_loaders
+   sdfits_loaders
+   structure
diff --git a/docs/source/design/structure.rst b/docs/source/design/structure.rst
@@ -0,0 +1,30 @@
+*********
+Structure
+*********
+
+.. mermaid::
+
+    erDiagram
+        SESSION {
+            int session_id PK, FK
+            int obsblock_id FK
+        }
+        OBSBLOCK {
+            int obsblock_id PK, FK
+            int spectrum_id FK
+            int flag
+        }
+        SPECTRUM {
+            int spectrum_id PK, FK
+            int flag
+        }
+        SPECTRUM_DATA {
+            int spectrum_id PK, FK
+            list flags
+            list frequencies
+            list intensities
+        }
+
+        SESSION ||--|{ OBSBLOCK : "has one or more"
+        OBSBLOCK ||--|{ SPECTRUM : "has one or more"
+        SPECTRUM ||--|| SPECTRUM_DATA : "has one"
diff --git a/docs/source/examples/img/gbt_ps_2.gif b/docs/source/examples/img/gbt_ps_2.gif
diff --git a/docs/source/examples/img/ps_152.png b/docs/source/examples/img/ps_152.png
diff --git a/docs/source/examples/img/ps_152_baseline_removed.png b/docs/source/examples/img/ps_152_baseline_removed.png
diff --git a/docs/source/examples/img/ps_152_zoom.png b/docs/source/examples/img/ps_152_zoom.png
diff --git a/docs/source/examples/img/tp_153_eqweight.png b/docs/source/examples/img/tp_153_eqweight.png
diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -4,6 +4,7 @@ Examples for GBT Data
 
 .. toctree::
    :maxdepth: 2
+   :glob:
 
    positionswitch
    totalpower

diff --git a/docs/source/examples/positionswitch.rst b/docs/source/examples/positionswitch.rst
@@ -5,9 +5,10 @@ Position-Switched Data
 Background
 ==========
 
-Position switched observations are those in which the telescope observes a target (the ON position or signal) and another part of the sky, assumed to be devoid of emission (the OFF position or reference).
+Position-switched observations are those in which the telescope observes a target (the ON position or signal) and another part of the sky, assumed to be devoid of emission (the OFF position or reference).
 
-.. image:: ../_static/examples/gbt_ps_2.gif
+.. figure:: img/gbt_ps_2.gif
+    :alt: A GIF showing the GBT nod back and forth in elevation to demonstrate position switching. 
 
 While observing this is accomplished using the functions `OnOff` or `OffOn` in a scheduling block. For more details about these functions see Sections |gbtog_onoff_link| and |gbtog_offon_link| of the |gbtog_link|.
 
@@ -23,7 +24,9 @@ While observing this is accomplished using the functions `OnOff` or `OffOn` in a
 
    <a href="http://www.gb.nrao.edu/scienceDocs/GBTog.pdf" target="_blank">GBT observer's guide</a>
 
-A modified version of the scheduling block for the observations used in this example is copied below::
+A modified version of the scheduling block for the observations used in this example is copied below
+
+.. code:: python
 
     # Observing script for NGC 2415
 
@@ -94,60 +97,75 @@ A modified version of the scheduling block for the observations used in this exa
 Calibrating Position-Switched Data
 ==================================
 
-Single beam position-switched (PS) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.getps` which returns a :class:`~dysh.spectra.scan.GBTPSScan` position-switched scan object that is used to calibrate and average the data.  First, import the relevant modules::
+Single beam position-switched (PS) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.getps` which returns a :class:`~dysh.spectra.scan.GBTPSScan` position-switched scan object that is used to calibrate and average the data.  First, import the relevant modules
+
+.. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
     >>> import astropy.units as u
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
 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>`_::
+`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)
 
-The returned `sdfits` can be probed for information::
+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']   
 
-You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data::
+You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
 
+.. code:: python
 
     >>> sdfits.summary()
         SCAN   OBJECT VELOCITY   PROC PROCSEQN  RESTFREQ   DOPFREQ # IF # POL # INT # FEED     AZIMUTH   ELEVATIO
     0    152  NGC2415   3784.0  OnOff        1  1.617185  1.420406    5     2   151      1  286.218008   41.62843
     1    153  NGC2415   3784.0  OnOff        2  1.617185  1.420406    5     2   151      1  286.886521  41.118134
 
-Retrieve a scan and its partner ON or OFF, selecting an IF number and polarization, then calibrate it::
+Retrieve a scan and its partner ON or OFF, selecting an IF number and polarization, then calibrate it
+
+.. 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`::
+The system temperature array (`numpy.ndarray`) is stored in `tsys`
+
+.. code:: python
 
     >>> print(f"T_sys = {pscan.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 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
 
+.. code:: python
 
     >>> ta = psscan.timeaverage(weights='tsys')
     >>> ta.plot()
 
-.. image:: ../_static/examples/ps_152.png
+.. figure:: img/ps_152.png
+    :alt: A frequency versus temperature spectrum plot. The spectrum is noisy and spans 1.390 to 1.415 GHz. 
 
+The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis units and also recognizes a number matplolib-like keywords
 
-The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis units and also recognizes a number matplolib-like keywords::
+.. code:: python
 
     >>> ta.plot(xaxis_unit="km/s",yaxis_unit="mK",ymin=-100,ymax=500,xmin=3000,xmax=4500)
 
-.. image:: ../_static/examples/ps_152_zoom.png
+.. figure:: img/ps_152_zoom.png
+    :alt: The spectrum plot zoomed in along both axes to frame a central emission line. 
 
 .. WARNING::
     At this point, `dysh` does not handle Doppler corrections. So the frequency and velocity information will be wrong for observations requesting a reference frame other than Topocentric.
@@ -159,6 +177,8 @@ 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`. 
 
+.. code:: python
+    
     >>> kms = u.km/u.s
     >>> ta.baseline(order=2,exclude=[3600,4100]*kms, remove=True)
     EXCLUDING [Spectral Region, 1 sub-regions:
@@ -176,5 +196,5 @@ is also .  The baseline is removed if `remove=True`.
         ------------------- --------------------- ----------------------
         0.16984671256725348 6.155580136474429e-29 2.2305011385559243e-56
 
-.. image:: ../_static/examples/ps_152_baseline_removed.png
-
+.. figure:: img/ps_152_baseline_removed.png
+    :alt: A plot of a spectrum after its baseline was removed.
diff --git a/docs/source/examples/subbeamnod.rst b/docs/source/examples/subbeamnod.rst
@@ -7,7 +7,9 @@ SubBeamNod scans with the GBT consist of using the subreflector to alternate bet
 Calibrating SubBeamNod Data
 ===========================
 
-For this example we will be using data from a receiver checkout, TRCO_230413_Ka. The data can be downloaded from this `link <http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits>`_. Or, using `wget`::
+For this example we will be using data from a receiver checkout, TRCO_230413_Ka. The data can be downloaded from this `link <http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits>`_. Or, using `wget`
+
+.. code:: python
 
     >>> import wget
     >>> url = "http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits"
@@ -17,26 +19,34 @@ For this example we will be using data from a receiver checkout, TRCO_230413_Ka.
 
 SubBeamNod data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.subbeamnod` which returns a :class:`~dysh.spectra.spectra.Spectrum` object.
 
-First, import the relevant module::
+First, import the relevant module
+
+.. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
-Then load your SDFITS file containing SubBeamNod data::
+Then load your SDFITS file containing SubBeamNod data
+
+.. code:: python
 
     >>> filename = 'TRCO_230413_Ka.raw.vegas.A.fits'
     >>> sdfits = GBTFITSLoad(filename)
 
-The returned `sdfits` can be probed for information::
+The returned `sdfits` can be probed for information
+
+.. code:: python
 
     >>> sdfits.info()
     Filename: /data/gbt/examples/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits
     No.    Name      Ver    Type      Cards   Dimensions   Format
       0  PRIMARY       1 PrimaryHDU      12   ()      
       1  SINGLE DISH    1 BinTableHDU    245   5280R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '1024E', '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`) :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data::
+You can also print a concise (or verbose if you choose `verbose=True`) :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
+
+.. code:: python
 
     >>> sdfits.summary()
         SCAN     OBJECT VELOCITY        PROC  PROCSEQN RESTFREQ DOPFREQ # IF # POL # INT # FEED     AZIMUTH   ELEVATIO
@@ -59,7 +69,9 @@ You can also print a concise (or verbose if you choose `verbose=True`) :meth:`~d
     16    53  1256-0547      0.0         Nod         2     30.5    30.5    1     2    60      2  170.175815  45.201877
     17    54  1256-0547      0.0  SubBeamNod         1     30.5    30.5    1     2   120      2  170.518885  45.232575
 
-The SubBeamNod scans are 43, 46, and 54.  Retrieve and calibrate a SubBeamNod scan, then plot it::
+The SubBeamNod scans are 43, 46, and 54.  Retrieve and calibrate a SubBeamNod scan, then plot it
+
+.. code:: python
 
     >>> sbn = sdfits.subbeamnod(scan=43, fdnum=1, ifnum=0, weights='tsys')
     >>> sbn.plot()