JP-3351: Corrections for tweakreg documentation (#8084)

Co-authored-by: Howard Bushouse <[email protected]>

CHANGES.rst

@@ -20,6 +20,10 @@ documentation
 
 - Improve Step.spec formatting [#8101]
 
+- Added warnings about incompatibility of models modified with ``adjust_wcs``
+  with ``tweakreg`` step and ``transfer_wcs_correction`` function. Fixed
+  reported typos in ``tweakreg`` documentation. [#8084]
+
 extract_1d
 ----------
 

docs/jwst/tweakreg/README.rst

@@ -62,26 +62,26 @@ other ways of supplying custom source catalogs to the step:
    and the file names of the corresponding catalogs in the second column.
    Catalog file names are relative to ``catfile`` file path.
 
-Specifying custom source catalogs via either the input ASN table or
+Specifying custom source catalogs via either the input ASN file or
 ``catfile``, will update input data models' ``meta.tweakreg_catalog``
-attributes to the catalog file names provided in either in the ASN table or
+attributes to the catalog file names provided in either in the ASN file or
 ``catfile``.
 
 .. note::
     When custom source catalogs are provided via both ``catfile`` and
-    ASN table members' attributes, the ``catfile`` takes precedence and
-    catalogs specified via ASN table are ignored altogether.
+    ASN file members' attributes, the ``catfile`` takes precedence and
+    catalogs specified via ASN file are ignored altogether.
 
 .. note::
     1. Providing a data model file name in the ``catfile`` and leaving
        the corresponding source catalog file name empty -- same as setting
-       ``'tweakreg_catalog'`` in the ASN table to an empty string ``""`` --
+       ``'tweakreg_catalog'`` in the ASN file to an empty string ``""`` --
        would set corresponding input data model's ``meta.tweakreg_catalog``
        attribute to `None`. In this case, ``tweakreg_step`` will automatically
        generate a source catalog for that data model.
 
     2. If an input data model is not listed in the ``catfile`` or does not
-       have ``'tweakreg_catalog'`` attribute provided in the ASN table,
+       have ``'tweakreg_catalog'`` attribute provided in the ASN file,
        then the catalog file name in that model's ``meta.tweakreg_catalog``
        attribute will be used. If ``model.meta.tweakreg_catalog`` is `None`,
        ``tweakreg_step`` will automatically generate a source catalog for
@@ -91,7 +91,7 @@ Alignment
 ---------
 The source catalogs for each input image are compared to each other
 and linear (affine) coordinate transformations that align these
-catalogs are derived.  This fit insures that all the input images
+catalogs are derived.  This fit ensures that all the input images
 are aligned relative to each other.  This step produces a combined
 source catalog for the entire set of input images as if they were
 combined into a single mosaic.
@@ -101,12 +101,11 @@ an astrometric reference catalog then gets generated by querying
 a GAIA-based astrometric catalog web service for all astrometrically
 measured sources in the combined field-of-view of the set of input
 images. This catalog is generated from the catalogs available
-through the GSSS STScI web services at `GSSSCATALOGS`_ and has the ability to account
+through the `STScI MAST Catalogs`_ and has the ability to account
 for proper motion to a given epoch. The epoch is computed from the observation date and time
-of the input data. If for any reason the epoch cannot be computed from the data, it defaults to 2016.0,
-which results in no proper motion correction.
+of the input data.
 
-.. _GSSSCATALOGS: http://gsss.stsci.edu/Catalogs/Catalogs.htm
+.. _STScI MAST Catalogs: https://outerspace.stsci.edu/display/MASTDATA/Catalog+Access
 
 The combined source catalog derived in the first step
 then gets cross-matched and fit to this astrometric reference catalog.

jwst/tweakreg/utils.py

@@ -68,6 +68,13 @@ def adjust_wcs(wcs, delta_ra=0.0, delta_dec=0.0, delta_roll=0.0,
         calibrated imaging data models that can be used as input to Stage 3
         of the JWST pipeline (with suffixes '_cal', '_tweakreg', '_skymatch').
 
+    .. warning::
+        This function modifies the WCS of calibrated imaging data models in a
+        way that is NOT compatible with ``tweakreg``: once a WCS
+        was modified using ``adjust_wcs()``, the corresponding imaging data
+        model (whose WCS was modified) no longer be aligned using the
+        ``tweakreg`` step.
+
     Parameters
     ----------
     wcs : `gwcs.WCS`
@@ -148,10 +155,10 @@ def adjust_wcs(wcs, delta_ra=0.0, delta_dec=0.0, delta_roll=0.0,
 
 def transfer_wcs_correction(to_image, from_image, matrix=None, shift=None):
     """
-    Applies the same *total* WCS correction that was applied to the WCS in the
-    ``from_image`` data model to the WCS of the ``to_image`` data model.
-    In some ways this function is analogous function to the ``tweakback``
-    function for HST available in the
+    Applies the same *total* WCS correction that was applied by ``tweakreg`` (!)
+    to the WCS in the ``from_image`` data model to the WCS of the ``to_image``
+    data model. In some ways this function is analogous function to the
+    ``tweakback`` function for HST available in the
     `drizzlepac package <https://github.com/spacetelescope/drizzlepac>`_.
 
     One fundamental difference between this function and ``tweakback``
@@ -177,6 +184,11 @@ def transfer_wcs_correction(to_image, from_image, matrix=None, shift=None):
         will be written out to the same file. BACKUP the file in ``to_image``
         argument before calling this function.
 
+    .. warning::
+        This function does not support input data models whose WCS were
+        modified by :py:func:`adjust_wcs`. Only WCS corrections computed by
+        either the ``tweakreg`` step or by ``tweakwcs`` package are supported.
+
     Parameters
     ----------
 
@@ -195,7 +207,7 @@ def transfer_wcs_correction(to_image, from_image, matrix=None, shift=None):
         WCS.
 
         If the WCS of the ``from_image`` data model does not contain
-        corections, then *both* ``matrix`` *and* ``shift`` arguments *must be
+        corrections, then *both* ``matrix`` *and* ``shift`` arguments *must be
         supplied*.
 
     matrix : 2D list, 2D numpy.ndarray, None, optional