Release 1.1 to main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -14,6 +14,9 @@ What is the bug? What did you expect to happen vs. what actually happened?
 Include a minimal example that reproduces your issue. This should probably be a brief snippet of Python code along with a traceback. Please format [using triple backticks](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code).
 
 **Environment**
-- Dysh version
+Please provide the outputs of ``dysh.system_info()`` here (only available after dysh 1.1.0).
+To get the outputs use: ``dysh -s``.
+If using dysh<=1.1.0 provide:
+- dysh version
 - Python version
 - OS

.github/workflows/ci-latest-deps.yml

@@ -9,6 +9,7 @@ env:
   FORCE_COLOR: '1'
   MPLBACKEND: Agg
   QT_QPA_PLATFORM: offscreen
+  DYSH_DATA: ${{ github.workspace }}/.dysh_cache
 jobs:
   tests:
     runs-on: ${{ matrix.os }}
@@ -27,9 +28,11 @@ jobs:
           - os: windows-latest
             python-version: '3.13'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: 0.9.17
           python-version: ${{ matrix.python-version }}
@@ -38,6 +41,11 @@ jobs:
         run: uv sync -U --all-extras --dev
       - name: Log resolved dependency versions
         run: uv pip list
+      - name: Cache example data
+        uses: actions/cache@v5
+        with:
+          path: ${{ github.workspace }}/.dysh_cache
+          key: dysh-example-data-v1
       - name: Test with pytest
         run: |
           uv run pytest --numprocesses auto -m "not gbo_only" --timeout=0
@@ -49,7 +57,7 @@ jobs:
       issues: write
     steps:
       - name: Create or update failure issue
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const title = 'CI (Latest Deps) is failing';

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ env:
   FORCE_COLOR: '1' # Make tools pretty.
   MPLBACKEND: Agg # hard-force headless backend (tkagg bad!)
   QT_QPA_PLATFORM: offscreen # No real display. Renders to memory. Not sure if Qt ever gets pulled in though
+  DYSH_DATA: ${{ github.workspace }}/.dysh_cache
 jobs:
   tests:
     runs-on: ${{ matrix.os }}
@@ -26,15 +27,22 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: 0.9.17 # Update this occasionally to stay up to date!
           python-version: ${{ matrix.python-version }}
           enable-cache: true
       - name: Install the project
         run: uv sync --all-extras --dev
+      - name: Cache example data
+        uses: actions/cache@v5
+        with:
+          path: ${{ github.workspace }}/.dysh_cache
+          key: dysh-example-data-v1
       - name: Test with pytest
         env:
           COVERAGE_FILE: coverage.${{ matrix.os }}.${{ matrix.python-version }}
@@ -45,7 +53,7 @@ jobs:
       - name: Upload coverage data
         # Upload only ubuntu results, since we are only running the coverage step on ubuntu
         if: matrix.os == 'ubuntu-latest'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage.${{ matrix.os }}.${{ matrix.python-version }}
           path: coverage.ubuntu-latest*
@@ -54,9 +62,11 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: 0.9.17
           python-version: '3.13'
@@ -65,22 +75,29 @@ jobs:
         run: uv sync -U --all-extras --dev
       - name: Log resolved dependency versions
         run: uv pip list
+      - name: Cache example data
+        uses: actions/cache@v5
+        with:
+          path: ${{ github.workspace }}/.dysh_cache
+          key: dysh-example-data-v1
       - name: Test with pytest
         run: |
           uv run pytest --numprocesses auto -m "not gbo_only" --timeout=0
   coverage:
     needs: tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: 0.9.17 # Update this occasionally to stay up to date!
           enable-cache: true
       - name: Install the project
         run: uv sync --all-extras --dev
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           pattern: coverage.*
           path: coverage-data
@@ -96,7 +113,7 @@ jobs:
           # Report again and fail if under 100%.
           # coverage report --fail-under=100
       - name: Upload HTML report
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: html-report
           path: htmlcov

.github/workflows/release.yml

@@ -12,9 +12,9 @@ jobs:
       # See: https://github.com/pypa/gh-action-pypi-publish#trusted-publishing
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: 0.8.19 # Update this occasionally to stay up to date!
           python-version: '3.10'

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
     hooks:
       - id: yamlfmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.9
+    rev: v0.15.12
     hooks:
       - id: ruff-format
       - id: ruff-check

docs/source/reference/dysh-for-gbtidl-users.rst

@@ -23,8 +23,9 @@ Rough equivalents
 
 In the tables below, it is assumed you have executed the following commands in Python:
 
-`from dysh.fits.gbtfitsload import GBTFITSLoad`
+``from dysh.fits import GBTFITSLoad, GBTOnline, GBTOffline``
 
+If you are running from the dysh shell, then the above commands are already available.
 
 
 
@@ -60,3 +61,125 @@ Spectrum Operations
     :header-rows: 1
     :class: longtable
     :widths: 10 15 10
+
+
+Side-by-side Examples
+=====================
+
+The following are examples in GBTIDL and dysh that produce equivalent results.
+The dysh examples assume they are being run from the dysh shell, so that the modules imported on startup are available (e.g., ``from astropy import units as u``).
+
+OTF Mapping
+-----------
+
+This example is based on the observations under TGBT17A_506_11, the same observations used for the :doc:`on-the-fly data reduction section of the users guide </users_guide/on_the_fly>`.
+
+.. tab:: dysh
+
+    .. code-block:: python
+
+        sdfits = GBTFITSLoad("TGBT17A_506_11.raw.vegas")
+        scan_block = sdfits.getsigref(scan=list(range(14,27)), ref=27, fdnum=0, ifnum=0, plnum=0)
+        scan_block.write("dysh.fits")
+
+.. tab:: GBTIDL
+
+    .. code-block:: idl
+
+        filein,"TGBT17A_506_11.raw.vegas"
+        fileout,"gbtidl.fits"
+        for s=14,26,1 do begin &$
+            getsigref,s,27,/avgref,/keepints &$
+            keep &$
+        endfor
+
+Extragalactic 21 cm Observations using Position Switching
+---------------------------------------------------------
+
+This example was borrowed from `GBTdocs position switched tutorial <https://gbtdocs.readthedocs.io/en/latest/tutorials/hi_psw_tutorial.html#data-reduction-scripted>`_.
+A more thorough dysh example using the same data can be found in :doc:`example reduction of an HI survey </users_guide/hi_survey>`.
+The GBTIDL version of this example can only be run with a display.
+
+.. tab:: dysh
+
+    .. code-block:: python
+
+        sdfits = GBTFITSLoad("/home/astro-util/HIsurvey/Session02")
+
+        tp0 = sdfits.gettp(scan=299, ifnum=0, plnum=0, fdnum=0).timeaverage()
+        tsys0 = tp0.meta["TSYS"]
+        tp1 = sdfits.gettp(scan=299, ifnum=0, plnum=1, fdnum=0).timeaverage()
+        tsys1 = tp1.meta["TSYS"]
+
+        sigref0a = sdfits.getsigref(scan=[296], ref=295, ifnum=0, fdnum=0, plnum=0, t_sys=tsys0, units="flux", zenith_opacity=0.08).timeaverage()
+        sigref0b = sdfits.getsigref(scan=[298], ref=297, ifnum=0, fdnum=0, plnum=0, t_sys=tsys0, units="flux", zenith_opacity=0.08).timeaverage()
+        sigref0 = sigref0a.average(sigref0b)
+        sigref1a = sdfits.getsigref(scan=[296], ref=295, ifnum=0, fdnum=0, plnum=1, t_sys=tsys1, units="flux", zenith_opacity=0.08).timeaverage()
+        sigref1b = sdfits.getsigref(scan=[298], ref=297, ifnum=0, fdnum=0, plnum=1, t_sys=tsys1, units="flux", zenith_opacity=0.08).timeaverage()
+        sigref1 = sigref1a.average(sigref1b)
+        sigref = sigref0.average(sigref1)
+
+        sigref_smo = sigref.smooth(kernel="gauss", width=100, decimate=0)
+
+        region = [[1.402*u.GHz, 1.4045*u.GHz],
+                  [1.40506*u.GHz, 1.4054*u.GHz],
+                  [1.4072*u.GHz, 1.4115*u.GHz]]
+
+        sigref_smo.baseline(1, model="poly", include=region, remove=True)
+
+        kms = u.km/u.s
+        stats_b = sigref_smo[2000*kms:2500*kms].stats()
+        stats_r = sigref_smo[3500*kms:4000*kms].stats()
+
+        rms = (stats_b["rms"] + stats_r["rms"])/2.
+
+        cog = sigref_smo.cog(bchan=100, echan=200)
+
+
+.. tab:: GBTIDL
+
+    .. code-block:: idl
+
+        dirin,'/home/astro-util/HIsurvey/Session02'
+
+        freeze      ; keep from plotting on the screen, to speed up the processing
+
+        gettp, 299, plnum=0, /quiet
+        tsys0 = !g.s.tsys
+        gettp, 299, plnum=1, /quiet
+        tsys1 = !g.s.tsys
+
+        for i=295,297,2 do begin &$
+          for p=0,1 do begin &$
+            if (p eq 0) then tsys=tsys0[0] else tsys=tsys1[0] &$
+            getsigref, i+1, i, plnum=p, tsys=tsys, unit='Jy', /quiet &$
+            accum &$
+          endfor &$
+        endfor
+        ave
+
+        gsmooth, 100, /decimate
+
+        setxunit, 'GHz'
+        setx, 1.401, 1.412
+
+        show
+
+        region = [1.402, 1.4045, 1.40506, 1.4054, 1.4072, 1.4115]
+        reg1 = xtochan(region)
+        Nregion, reg1
+        nfit, 1
+        bshape
+        baseline
+
+        velo
+        show
+        stats, 2000, 2500, ret=mystats
+        rms1 = mystats.rms
+        stats, 3500, 4000, ret=mystats
+        rms2 = mystats.rms
+
+        rms = (rms1 + rms2) / 2
+
+        gmeasure, 1, 0.5, brange=2815, erange=3142, rms=rms
+        gmeasure, 1, 0.2, brange=2815, erange=3142, rms=rms

docs/source/reference/files/Calibration.csv

@@ -1,8 +1,8 @@
 GBTIDL,dysh,explanation
-select,"sdf.select( [col1]=[val1], [col2]=[val2] )","Select subsets of the GBTFITSLoad object `sdf` based on the constraints on `col1` and `col2` given by `val1` and `val2`"
-flag,"sdf.flag( [col1]=[val1], [col2]=[val2] )", "Create flagging rules of the GBTFITSLoad object `sdf` based on the constraints on `col1` and `col2` given by `val1` and `val2`. See flagging examples given in the Recipes."
-"gettp, [scan_num]",sdfits.gettp( scan=[scan_num] ),"Returns a Scan Block. Get a total power scan, with the option in dysh to optionally calibrate it."
-"getps, [scan_num]",sdfits.getps( scan=[scan_num] ),Returns a Scan Block. Retrieve and calibrate position-switched data.
-"getfs, [scan_num]",sdfits.getfs( scan=[scan_num] ),Returns a Scan Block. Retrieve and calibrate frequency-switched data.
-"getnod, [scan_num]",sdfits.getnod( scan=[scan_num] ),Returns a Scan Block.
-show,spec.plot(),Plot the spectrum `spec`. Calibration routines in GBTIDL do this automatically.
+select,"sdf.select( [col1]=[val1], [col2]=[val2] )","Select subsets of the `~dysh.fits.gbtfitsload.GBTFITSLoad` object ``sdf`` based on the constraints on ``col1`` and ``col2`` given by ``val1`` and ``val2``"
+flag,"sdf.flag( [col1]=[val1], [col2]=[val2] )", "Create flagging rules of the `~dysh.fits.gbtfitsload.GBTFITSLoad` object ``sdf`` based on the constraints on ``col1`` and ``col2`` given by ``val1`` and ``val2``. See flagging examples given in the Recipes."
+"gettp, [scan_num]",sdfits.gettp( scan=[scan_num] ),"Get a total power scan. Returns a `~dysh.spectra.scan.ScanBlock`."
+"getps, [scan_num]",sdfits.getps( scan=[scan_num] ),"Retrieve and calibrate position-switched data. Returns a `~dysh.spectra.scan.ScanBlock`."
+"getfs, [scan_num]",sdfits.getfs( scan=[scan_num] ),"Retrieve and calibrate frequency-switched data. Returns a `~dysh.spectra.scan.ScanBlock`."
+"getnod, [scan_num]",sdfits.getnod( scan=[scan_num] ),"Retrieve and calibrate nodding data. Returns a `~dysh.spectra.scan.ScanBlock`."
+show,spec.plot(),"Plot the spectrum ``spec``. Calibration routines in GBTIDL do this automatically."

docs/source/reference/files/FileIO.csv

@@ -1,10 +1,10 @@
 GBTIDL,dysh,Notes
-online,sdf = GBTOnline(); sdf = GBTOnline([projID]) ,Monitor the currently online project or a specific project `projID`. Load the SDFITS into `sdf`.
-offline,sdf = GBTOffline([projID]),Load data from project/session `projID` into `sdf`.
+online,sdf = GBTOnline(); sdf = GBTOnline([projID]) ,Monitor the currently online project or a specific project ``projID``. Load the SDFITS into ``sdf``.
+offline,sdf = GBTOffline([projID]),Load data from project/session ``projID`` into ``sdf``.
 "filein, [SDFITS file]",sdfits = GBTFITSLoad( [SDFITSfile] ),This will directly load a SDFITS file into python.
 "dirin, [SDFITS dir]",sdfits = GBTFITSLoad( [SDFITS dir] ),"This will load each SDFITS file in a directory into python, in the case it is a project directory where each file is a different VEGAS bank. (A, B, C, etc.). The implementation is identical to the single SDFITS file load."
-fileout,,"There is no direct translation; in dysh, simply specify a filename with the Spectrum.write or ScanBlock.write functions"
-keep,"spec.write( [SDFITSfile], format=[fmt] )","Write the spectrum `spec` to the output `SDFITS file` specified, using the format `fmt`"
+fileout,,"There is no direct translation; in dysh, simply specify a filename with the ``Spectrum.write`` or ``ScanBlock.write`` functions."
+keep,"spec.write( [SDFITSfile], format=[fmt] )","Write the spectrum ``spec`` to the output ``SDFITSfile`` specified, using the format ``fmt``."
 summary,sdfits.summary(),"In dysh, you can also input a list of scan numbers you would like to see, or modify which SDFITS columns are printed."
-list,sdfits.summary( verbose=True ),"Using the ""verbose=True"" option returns similar results to GBTIDL's ""list""."
-"header, scan_info",spec.meta,"Return meta information about the spectrum `spec`. In GBTIDL, this returns a text printout. In dysh, this returns a dictionary with all SDFITS keywords and values."
+list,sdfits.summary( verbose=True ),"Using the ``verbose=True`` option returns similar results to GBTIDL's ``list``. It is possible to provide a scan number as ``scan=x``."
+"header, scan_info",spec.meta,"Return meta information about the spectrum ``spec``. In GBTIDL, this returns a text printout. In dysh, this returns a dictionary with all SDFITS keywords and values."

docs/source/reference/files/Spectrum_ops.csv

@@ -1,15 +1,13 @@
 GBTIDL,dysh,Notes
-"baseline, bshape, bsubtract, nfit","spec.baseline( [deg], exclude=[ex_reg],remove=True/False )",Compute and optionally remove a baseline with degree `deg` and exclusion regions `ex_reg`
-"gsmooth, [int]","spec.smooth( ""gauss"", [int] )","Convolve spec with a Gaussian kernel. Default behavior is to decimate, which isn't true in GBTIDL"
-hanning,"spec.smooth( ""hann"" )","Convolve `spec` with a Hanning window. Default behavior is to decimate, which isn't true in GBTIDL"
-"boxcar, [int]","spec.smooth( ""box"", [int] )","Convolve `spec` with a boxcar window. This matches the GBTIDL results only when integer `int` is an odd number. Default behavior is to decimate, which isn't true in GBTIDL"
-add/subtract/divide/scale,"spec + other, spec - other, spec/other, spec*other",Perform element-wise math between spectrum `spec` and other vector/scalar `other`.
-"bias, [bias]",spec + bias,Add scalar `bias` to spectrum `spec`. The units of `bias` must match those of `spec.flux`.
-accum,average_spectra(list of spectra),
-ave,scanblock.timeaverage(); scan.timeaverage(),Average a set of scans inside Scan Block `scanblock` or Scan `scan`.
-stats,spec.stats(),Print statistics of spectrum `spec`.
-"fshift, vshift, xshift",spec.find_shift(other),Find the shift between `spec` and `other`.
-gshift,"spec.shift(shift)
-spec.align_to(other)","Shift `spec` by `shift`.
-Find the shift between `spec` and `other` and apply. Equivalent to `spec.shift(spec.find_shift(other))`."
-"write_ascii, filename","spec.write(filename, format=""ascii.basic"")",Write the contents of spec to a text file in ascii format with minimum header information.
+"baseline, bshape, bsubtract, nfit","spec.baseline( [deg], exclude=[ex_reg],remove=True/False )","Compute and optionally remove a baseline with degree ``deg`` and exclusion regions ``ex_reg``."
+"gsmooth, [int]","spec.smooth( ""gauss"", [int] )","Convolve spec with a Gaussian kernel. Default behavior is to decimate, which isn't true in GBTIDL."
+hanning,"spec.smooth( ""hann"" )","Convolve ``spec`` with a Hanning window. Default behavior is to decimate, which isn't true in GBTIDL."
+"boxcar, [int]","spec.smooth( ""box"", [int] )","Convolve ``spec`` with a boxcar window. This matches the GBTIDL results only when integer `int` is an odd number. Default behavior is to decimate, which isn't true in GBTIDL"
+add/subtract/divide/scale,"spec + other, spec - other, spec/other, spec*other",Perform element-wise math between spectrum ``spec`` and other vector/scalar ``other``.
+"bias, [bias]",spec + bias,Add scalar ``bias`` to spectrum ``spec``.
+accum,average_spectra(list of spectra),"``average_spectra`` has to be imported first (``from dysh.spectra import average_spectrum``). Alternatively, ``spec.average(list of other spectra)`` will average ``spec`` with the spectra in the list."
+ave,"scanblock.timeaverage(); scan.timeaverage()","Average a set of scans inside `~dysh.spectra.scan.ScanBlock` ``scanblock`` or `~dysh.spectra.scan.ScanBase` ``scan``."
+stats,spec.stats(),Print statistics of spectrum ``spec``.
+"fshift, vshift, xshift",spec.find_shift(other),Find the shift between ``spec`` and ``other``.
+gshift,"spec.shift(shift); spec.align_to(other)","Shift ``spec`` by ``shift``;Find the shift between ``spec`` and ``other`` and apply. Equivalent to ``spec.shift(spec.find_shift(other))``."
+"write_ascii, filename","spec.write(filename, format=""ascii.basic"")",Write the contents of ``spec`` to a text file in ascii format with minimum header information.

docs/source/reference/index.rst

@@ -77,7 +77,7 @@ Reference Guides
         :shadow: md
         :margin: 2 2 0 0
 
-        :octicon:`file;3em;green` **SDMATH**
+        **SDMATH**
 
         Single Dish math
 

docs/source/reference/modules/dysh.util.rst

@@ -42,3 +42,8 @@ Utility classes and functions
    :members:
    :undoc-members:
    :show-inheritance:
+
+.. automodule:: dysh.util.system_info
+   :members:
+   :undoc-members:
+   :show-inheritance: