diff --git a/CHANGES.rst b/CHANGES.rst index 93e775416d..95b4ca065a 100644 --- a/CHANGES.rst +++ b/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 ---------- diff --git a/docs/jwst/tweakreg/README.rst b/docs/jwst/tweakreg/README.rst index 65e1949d41..03f4e0334e 100644 --- a/docs/jwst/tweakreg/README.rst +++ b/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. diff --git a/jwst/tweakreg/utils.py b/jwst/tweakreg/utils.py index 9e6ea643c7..9b3fbaf6e4 100644 --- a/jwst/tweakreg/utils.py +++ b/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 `_. 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