Backport PR #9301 on branch release/1.18.x (JP-3686: Test using source catalog output as tweakreg abs_refcat) (#9346)

Co-authored-by: Ned Molter <[email protected]>

Author: meeseeksmachine

changes/9301.tweakreg.rst

@@ -0,0 +1 @@
+Update docs to clarify format of tweakreg catalogs

docs/jwst/tweakreg/README.rst

@@ -135,25 +135,22 @@ measured sources in the combined field-of-view of the set of input
 images. This catalog is generated from the catalogs available
 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.
+of the input data. If ``abs_refcat`` is set to a path to an existing
+file, i.e., a user-supplied external reference catalog,
+then the catalog will be read from that file. The catalog must be readable
+into an :py:meth:`~astropy.table.Table` object and contain either
+``'RA'`` and ``'DEC'`` columns (in degrees) or an Astropy-readable ``sky_centroid``.
+An optional column in the catalog is the ``'weight'`` column, which when present,
+will be used in fitting.
 
 .. _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.
-The pipeline initially supports fitting to the
-GAIADR3 catalog, with the option to select the GAIADR2 or GAIADR1 instead.
 The results of this one fit then gets back-propagated to all the
 input images to align them all to the astrometric reference frame while
 maintaining the relative alignment between the images.
 
-For this part of alignment, instead of 'GAIADR1', 'GAIADR2', or 'GAIADR3', users can
-supply an external reference catalog by providing a path to an existing
-file. A user-supplied catalog must contain ``'RA'`` and ``'DEC'`` columns
-indicating reference source world coordinates (in degrees). An optional column
-in the catalog is the ``'weight'`` column, which when present, will be used
-in fitting. The catalog must be in a format automatically recognized by
-:py:meth:`~astropy.table.Table.read`.
 
 Grouping
 --------
@@ -212,6 +209,10 @@ The ``tweakreg`` step has the following optional arguments:
   (Default= `'ecsv'`)
 
 * ``catfile``: Name of the file with a list of custom user-provided catalogs.
+  The file must contain a two-column list of format
+  ``<input file name> <catalog file name>`` with one entry per input filename
+  in the input association.
+  This parameter has no effect if ``use_custom_catalogs`` is `False`.
   (Default= `''`)
 
 * ``bkg_boxsize``: A positive `int` indicating the background mesh box size

jwst/regtest/test_nircam_align_to_gaia.py

@@ -4,6 +4,7 @@
 
 from stdatamodels.jwst import datamodels
 from jwst.stpipe import Step
+from jwst.tweakreg import TweakRegStep
 
 
 @pytest.fixture(scope="module")
@@ -40,3 +41,20 @@ def test_tweakreg_with_gaia(run_image3pipeline, rtdata_module, root):
 
         assert_allclose(ra, ra_truth)
         assert_allclose(dec, dec_truth)
+
+
+@pytest.mark.bigdata
+def test_sourcecat_as_abs_refcat(run_image3pipeline, rtdata_module):
+    """
+    Test that source catalog output is compatible with tweakreg.
+    
+    Some workflows require using source catalog step output as the
+    absolute reference catalog for tweakreg. This test ensures that
+    this is possible. This is not nircam-specific, but is included here
+    to avoid adding an additional test run through image3.
+    """
+    rtdata = rtdata_module
+    rtdata.output = "LMC_F277W_modA_dither_mosaic_cat.ecsv" # output from source catalog step
+    rtdata.get_asn("nircam/image/level3_F277W_3img_asn.json")
+
+    TweakRegStep.call(rtdata.input, abs_refcat = rtdata.output)

jwst/tweakreg/tweakreg_step.py

@@ -297,6 +297,7 @@ def process(self, input_data):
         # absolute alignment to the reference catalog
         # can (and does) occur after alignment between groups
         if align_to_abs_refcat:
+            self.log.info(f"Aligning to absolute reference catalog: {self.abs_refcat}")
             with images:
                 ref_image = images.borrow(0)
                 try: