pyredshift 1.10__tar.gz → 1.11__tar.gz

{pyredshift-1.10 → pyredshift-1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyredshift
-Version: 1.10
+Version: 1.11
 Summary: Interactive redshifting of 1D astronomical spectra (Python successor of pdlredshift / redshift.f)
 Home-page: https://github.com/karlglazebrook/pyredshift
 Author: Karl Glazebrook

{pyredshift-1.10 → pyredshift-1.11}/pyredshift

@@ -264,9 +264,14 @@ def read_spectrum(fname, fmt=None):
 def main():
     ap = argparse.ArgumentParser(
         prog="pyredshift",
+        usage="pyredshift [-help] [-f FORMAT] [-z REDSHIFT] [--retro] "
+              "[--microns] file",
         description="Interactive redshifting of 1D spectra (port of pdlredshift).",
-        epilog="Formats: ascii csv fits sdss table (=jwst,jwst2,gabe,dja) "
-               "xs xs2 outthere.  Default is auto-detection.")
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        # format documentation lives in the module (FORMAT_HELP) so the
+        # -h epilog and the '?' help page cannot drift apart
+        epilog=redshift_module.formats_text())
+    ap.add_argument("-help", action="help", help=argparse.SUPPRESS)
     ap.add_argument("file", help="spectrum file (FITS, CSV or 2-column ascii)")
     ap.add_argument("-f", "--format", default=None, metavar="FORMAT",
                     help="force the input format instead of auto-detecting")

{pyredshift-1.10 → pyredshift-1.11}/setup.py

@@ -13,7 +13,7 @@ from setuptools import setup
 
 setup(
     name="pyredshift",
-    version="1.10",
+    version="1.11",
     description="Interactive redshifting of 1D astronomical spectra "
                 "(Python successor of pdlredshift / redshift.f)",
     long_description=open("README.md").read(),

{pyredshift-1.10 → pyredshift-1.11}/src/pyredshift/pyredshift-help.html

@@ -98,13 +98,16 @@ colours as plotted):</p>
 <h2>Guide</h2>
 <p>pyredshift is a tool for measuring the redshift of a galaxy or quasar
 from a 1D spectrum, by eye. Run it as <code>pyredshift file</code> &mdash;
-the format (FITS image or table, SDSS, JWST, XSHOOTER, OutThere, CSV,
-2-column ascii) is auto-detected, with <code>-f</code> to force one,
-<code>-z</code> to start from a known redshift and <code>--retro</code>
-for a retro PGPLOT-style black background. It plots the spectrum histogram-style with a
+the file format is auto-detected (see the table below), with
+<code>-f</code> to force one, <code>-z</code> to start from a known
+redshift and <code>--retro</code> for a retro PGPLOT-style black
+background. It plots the spectrum histogram-style with a
 crosshair cursor, and overlays rest-frame line identifications that
 follow the trial redshift shown at top left.</p>
 
+<h2>File formats</h2>
+{formats}
+
 <p>The basic game: spot a feature you can identify, put the crosshair on
 it and press <code>ESC</code> then the line's shortcut key (or
 <code>g</code> to type any rest wavelength) &mdash; the line labels jump

{pyredshift-1.10 → pyredshift-1.11}/src/pyredshift/redshift.py

@@ -49,6 +49,9 @@ V1.10 - The cursor works over the whole window, as PGPLOT's did: keys and
        'x'/'y'/'e' can be pressed just outside the axis, pdlredshift
        style), the crosshair and the readout follow into the margins,
        and rubber-band drags may extend past the plot edge.
+V1.11 - Proper file-format documentation: a per-format table in the
+       script's -h and a File formats section in the help page, both
+       generated from FORMAT_HELP here so they cannot drift apart.
 """
 
 import ctypes
@@ -88,12 +91,33 @@ try:
 except AttributeError:
     pass
 
-__version__ = "1.10"
+__version__ = "1.11"
 
 C_LIGHT = 2.99792458e8  # m/s
 
 TEMPLATE_NAME = "GNIRS_N4608"  # template for the 't' key
 
+# One description per reader in the pyredshift script - the single source
+# for both the script's -h epilog and the Formats section of the help page.
+# Keep in sync when adding a reader to the script.
+FORMAT_HELP = [
+    ("fits", "1D (or 2D - row 1 used) FITS image with WCS; CD1_1 "
+             "overrides CDELT1, IRAF/SDSS log-lambda flags handled"),
+    ("sdss", "SDSS/BOSS binary table (LOGLAM/FLUX, either case)"),
+    ("table", "generic binary table with wave+flux columns; TUNIT "
+              "(um, nm, A) converted automatically "
+              "(aliases: jwst, jwst2, gabe, dja)"),
+    ("xs", "XSHOOTER 1D table spectrum (nm)"),
+    ("xs2", "XSHOOTER as a FITS image in extension 1"),
+    ("outthere", "OutThere multi-extension grism spectra, stitched "
+                 "and flat-calibrated"),
+    ("csv", "comma-separated, header rows skipped"),
+    ("ascii", "2-column text"),
+]
+FORMAT_NOTES = ("Default is auto-detection. Wavelengths that look like "
+                "microns are converted to Angstroms (--microns keeps them); "
+                "NaNs are treated as bad pixels and plot as gaps.")
+
 CONFIG_FILE = os.path.expanduser("~/.pyredshift.json")  # remembers window size
 DEFAULT_FIGSIZE = (13.0, 5.5)  # inches
 
@@ -215,11 +239,35 @@ def linelist_html():
     return "<table class='linelist'>\n%s\n</table>" % "\n".join(rows)
 
 
+def formats_html():
+    """FORMAT_HELP as table rows + notes for the help page."""
+    rows = ["<tr><th>Format</th><th>Description</th></tr>"]
+    for name, desc in FORMAT_HELP:
+        rows.append("<tr><td><code>%s</code></td><td>%s</td></tr>"
+                    % (name, desc))
+    return ("<table>\n%s\n</table>\n<p>%s</p>"
+            % ("\n".join(rows), FORMAT_NOTES))
+
+
+def formats_text():
+    """FORMAT_HELP as aligned plain text for the script's -h epilog."""
+    import textwrap
+    width = max(len(name) for name, _ in FORMAT_HELP)
+    lines = ["Formats (-f):"]
+    for name, desc in FORMAT_HELP:
+        lines.append(textwrap.fill(
+            desc, width=79, initial_indent="  %-*s  " % (width, name),
+            subsequent_indent=" " * (width + 4)))
+    lines.append(textwrap.fill(FORMAT_NOTES, width=79))
+    return "\n".join(lines)
+
+
 def help_html():
     """The help HTML body with the placeholders filled in."""
     if HELP_RAW is None:
         return None
-    return HELP_RAW.format(template=TEMPLATE_NAME, linelist=linelist_html())
+    return HELP_RAW.format(template=TEMPLATE_NAME, linelist=linelist_html(),
+                           formats=formats_html())
 
 
 # ---------------------------------------------------------------------------

{pyredshift-1.10 → pyredshift-1.11}/src/pyredshift.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyredshift
-Version: 1.10
+Version: 1.11
 Summary: Interactive redshifting of 1D astronomical spectra (Python successor of pdlredshift / redshift.f)
 Home-page: https://github.com/karlglazebrook/pyredshift
 Author: Karl Glazebrook