Description

Overview

This step takes as input image catalogs of point-like sources, which are used to compute corrections to the WCS of the input images such that sky catalogs obtained from the image catalogs using the corrected WCS will align on the sky.

Source Catalogs

The input catalog must be in a format automatically recognized by ~astropy.table.Table.read. The catalog must contain either 'x' and 'y' or 'xcentroid' and 'ycentroid' columns which indicate source image coordinates (in pixels). Pixel coordinates are 0-indexed. An optional column in the catalog is the 'weight' column, which when present, will be used in fitting.

Relative Alignment

Relative alignment is performed by the ~stcal.tweakreg.relative_align function. 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 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.

Absolute Alignment

Absolute alignment is performed by the ~stcal.tweakreg.absolute_align function. If the parameter abs_refcat is set to ‘GAIAREFCAT’, ‘GAIADR3’, ‘GAIADR2’, or ‘GAIADR1’, 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 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 abs_refcat is set to ‘GAIADR3_S3’ the HATS package will be used to access an S3 bucket containing a partitioned Gaia data release 3 catalog. When using the S3 catalog and a specified epoch, source positions are corrected internally by propagating the position to the given epoch using the Gaia proper motions and parallaxes (and throwing away any sources without computed proper motions and parallaxes). Parallaxes are computed as if the observer were located at the Earth barycenter.

The combined source catalog then gets cross-matched and fit to this astrometric reference catalog. 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 one of the above Gaia catalogs, 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 ~astropy.table.Table.read.

Grouping

Images taken at the same time (e.g., NIRCam images from all short-wave detectors) can be aligned together; that is, a single correction can be computed and applied to all these images because any error in telescope pointing will be identical in all these images and it is assumed that the relative positions of (e.g., NIRCam) detectors do not change. Identification of images that belong to the same “exposure” and therefore can be grouped together is based on several attributes change from here to end of section described in ~jwst.datamodels.ModelContainer. This grouping is performed automatically in the tweakreg step using the ~jwst.datamodels.ModelContainer.models_grouped property, which assigns a group ID to each input image model in meta.group_id.

However, when detector calibrations are not accurate, alignment of groups of images may fail (or result in poor alignment). In this case, it may be desirable to align each image independently. This can be achieved either by setting the image_model.meta.group_id attribute to a unique string or integer value for each image, or by adding the group_id attribute to the members of the input ASN table - see ~jwst.datamodels.ModelContainer for more details.

Note

Group ID (group_id) is used by both tweakreg and skymatch steps and so modifying it for one step will affect the results in another step. If it is desirable to apply different grouping strategies to the tweakreg and skymatch steps, one may need to run each step individually and provide a different ASN as input to each step.

WCS Correction

The linear coordinate transformation computed in the previous step is used to define tangent-plane corrections that need to be applied to the GWCS pipeline in order to correct input image WCS. This correction is implemented by inserting a v2v3corr frame with tangent plane corrections into the GWCS pipeline of the image’s WCS.

Arguments

The tweakreg step has the following optional arguments:

Relative alignment parameters:

Parameters used for relative alignment between input images. These parameters are passed into the ~stcal.tweakreg.relative_align function.

  • expand_refcat: A boolean indicating whether or not to expand reference catalog with new sources from other input images that have been already aligned to the reference image. (Default=False)

  • minobj: A positive int indicating minimum number of objects acceptable for matching. (Default=15)

  • searchrad: A float indicating the search radius in arcsec for a match. (Default=2.0)

  • use2dhist: A boolean indicating whether to use 2D histogram to find initial offset. (Default=True)

  • separation: Minimum object separation in arcsec. It must be at least sqrt(2) times larger than tolerance. (Default=1.0)

  • tolerance: Matching tolerance for xyxymatch in arcsec. (Default=0.7)

  • xoffset: Initial guess for X offset in arcsec. (Default=0.0)

  • yoffset: Initial guess for Y offset in arcsec. (Default=0.0)

  • fitgeometry: A str value indicating the type of affine transformation to be considered when fitting catalogs. Allowed values:

    • 'shift': x/y shifts only

    • 'rshift': rotation and shifts

    • 'rscale': rotation and scale

    • 'general': shift, rotation, and scale

    The default value is “rshift”.

    Note

    Mathematically, alignment of images observed in different tangent planes requires fitgeometry='general' in order to fit source catalogs in the different images even if misalignment is caused only by a shift or rotation in the tangent plane of one of the images.

    However, under certain circumstances, such as small alignment errors or minimal dithering during observations that keep tangent planes of the images to be aligned almost parallel, then it may be more robust to use a fitgeometry setting with fewer degrees of freedom such as 'rshift', especially for “ill-conditioned” source catalogs such as catalogs with very few sources, or large errors in source positions, or sources placed along a line or bunched in a corner of the image (not spread across/covering the entire image).

  • nclip: A non-negative integer number of clipping iterations to use in the fit. (Default=3)

  • sigma: A positive float indicating the clipping limit, in sigma units, used when performing fit. (Default=3.0)

Absolute Astrometric fitting parameters:

Parameters used for absolute astrometry to a reference catalog. These parameters are passed into the ~stcal.tweakreg.absolute_align function.

  • abs_refcat: String indicating what astrometric catalog should be used. Currently supported options: ‘GAIAREFCAT’, ‘GAIADR1’, ‘GAIADR2’, ‘GAIADR3’, ‘GAIADR3_S3’, a path to an existing reference catalog, None, or ‘’. See stcal.tweakreg.tweakreg.SINGLE_GROUP_REFCAT for an up-to-date list of supported built-in reference catalogs.

    When abs_refcat is None or an empty string, alignment to the absolute astrometry catalog will be turned off. (Default= ‘’)

  • abs_minobj: A positive int indicating minimum number of objects acceptable for matching. (Default=15)

  • abs_searchrad: A float indicating the search radius in arcsec for a match. It is recommended that a value larger than searchrad be used for this parameter (e.g. 3 times larger) (Default=6.0)

  • abs_use2dhist: A boolean indicating whether to use 2D histogram to find initial offset. It is strongly recommended setting this parameter to True. Otherwise the initial guess for the offsets will be set to zero (Default=True)

  • abs_separation: Minimum object separation in arcsec. It must be at least sqrt(2) times larger than abs_tolerance. (Default=1.0)

  • abs_tolerance: Matching tolerance for xyxymatch in arcsec. (Default=0.7)

  • abs_fitgeometry: A str value indicating the type of affine transformation to be considered when fitting catalogs. Allowed values:

    • 'shift': x/y shifts only

    • 'rshift': rotation and shifts

    • 'rscale': rotation and scale

    • 'general': shift, rotation, and scale

    The default value is “rshift”. Note that the same conditions/restrictions that apply to fitgeometry also apply to abs_fitgeometry.

  • abs_nclip: A non-negative integer number of clipping iterations to use in the fit. (Default=3)

  • abs_sigma: A positive float indicating the clipping limit, in sigma units, used when performing fit. (Default=3.0)

  • save_abs_catalog: A boolean specifying whether or not to write out the astrometric catalog used for the fit as a separate product. (Default=False)

Further Documentation

The underlying algorithms as well as formats of source catalogs are described in more detail at

https://tweakwcs.readthedocs.io/en/latest/

stcal.tweakreg.tweakreg Module

Functions

relative_align(correctors[, searchrad, ...])

absolute_align(correctors, abs_refcat, ...)

filter_catalog_by_bounding_box(catalog, ...)

Given a catalog of x,y positions, only return sources that fall inside the bounding box.