Description

Class

jwst.tweakreg.TweakRegStep

Alias

tweakreg

Overview

This step creates image catalogs of point-like sources whose centroids are then 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 Detection

If meta.tweakreg_catalog attribute of input data models is a non-empty string and use_custom_catalogs is True, then it will be interpretted as a file name of a user-provided source catalog. The catalog must be in a format automatically recognized by read().

When meta.tweakreg_catalog attribute of input data models is None or an empty string, then tweakreg step will attempt to detect sources in the input images. Stars are detected in the image using the Photutils “daofind” function. Photutils.daofind is an implementation of the DAOFIND algorithm (Stetson 1987, PASP 99, 191). It searches images for local density maxima that have a peak amplitude greater than a specified threshold (the threshold is applied to a convolved image) and have a size and shape similar to a defined 2D Gaussian kernel. photutils.daofind also provides an estimate of the objects roundness and sharpness, whose lower and upper bounds can be specified.

Custom Source Catalogs

Source detection built-in into the tweakreg step can be disabled by providing a file name to a custom source catalog in the meta.tweakreg_catalog attribute of input data models. The catalog must be in a format automatically recognized by 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.

For the tweakreg step to use user-provided input source catalogs, use_custom_catalogs parameter of the tweakreg step must be set to True.

In addition to setting the meta.tweakreg_catalog attribute of input data models to the custom catalog file name, the tweakreg_step also supports two other ways of supplying custom source catalogs to the step:

  1. Adding tweakreg_catalog attribute to the members of the input ASN table - see ModelContainer for more details. Catalog file names are relative to ASN file path.

  2. Providing a simple two-column text file, specified via step’s parameter catfile, that contains input data models’ file names in the first column 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 catfile, will update input data models’ meta.tweakreg_catalog attributes to the catalog file names provided in either in the ASN table 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.

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 "" – 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, 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 that data model.

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 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.

If the step parameter abs_refcat is set to ‘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 gets generated from the catalogs available through the GSSS STScI web services at GSSSCATALOGS.

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 GAIADR2 catalog, with the option to select the 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’ or ‘GAIADR2’, users can supply an external reference catalog by providing a path to an existing file. User-supplied catalog must contain 'RA' and 'DEC' columns which indicate 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 read().

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.

Step Arguments

The tweakreg step has the following optional arguments:

Source finding parameters:

  • save_catalogs: A boolean indicating whether or not the catalogs should be written out. This parameter is ignored for input data models whose meta.tweakreg_catalog is a non-empty string pointing to a user-supplied source catalog. (Default=`False`)

  • use_custom_catalogs: A boolean that indicates whether to ignore source catalog in the input data model’s meta.tweakreg_catalog attribute. If False, new catalogs will be generated by the tweakreg step. (Default=`False`)

  • catalog_format: A str indicating catalog output file format. (Default=’ecsv’)

  • catfile: Name of the file with a list of custom user-provided catalogs. (Default=’’)

  • kernel_fwhm: A float value indicating the Gaussian kernel FWHM in pixels. (Default=2.5)

  • snr_threshold: A float value indicating SNR threshold above the background. (Default=5.0)

  • sharplo: A float value indicating The lower bound on sharpness for object detection. (Default=0.2)

  • sharphi: A float value indicating the upper bound on sharpness for object detection. (Default=1.0)

  • roundlo: A float value indicating the lower bound on roundness for object detection. (Default=-1.0)

  • roundhi: float value indicating the upper bound on roundness for object detection. (Default=1.0)

  • brightest: A positive int value indicating the number of brightest objects to keep. (Default=200)

  • peakmax: A float value used to filter out objects with pixel values >= peakmax. (Default=None)

  • bkg_boxsize: A positive int indicating the background mesh box size in pixels. (Default=400)

Optimize alignment order:

  • enforce_user_order: a boolean value indicating whether or not take the first image as a reference image and then align the rest of the images to that reference image in the order in which input images have been provided or to optimize order in which images are aligned. (Default=`False`)

Reference Catalog parameters:

  • 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)

Object matching parameters:

  • 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. (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)

Catalog fitting parameters:

  • 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 mis-alignment 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.

  • abs_refcat: String indicating what astrometric catalog should be used. Currently supported options: ‘GAIADR1’, ‘GAIADR2’ a path to an existing reference catalog, None, or ‘’. See jwst.tweakreg.tweakreg_step.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 is recommended that a value smaller than separation be used for this parameter (e.g. 10 times smaller) (Default=0.1)

  • 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/

Reference Files

The tweakreg step uses the PARS-TWEAKREGSTEP parameter reference file.

PARS-TWEAKREGSTEP Parameter Reference File

REFTYPE

PARS-TWEAKREGSTEP

Data model

N/A

Reference Selection Keywords

CRDS selects appropriate pars-tweakregstep references based on the following keywords.

Instrument

Keywords

FGS

EXP_TYPE

MIRI

EXP_TYPE, FILTER

NIRCAM

EXP_TYPE, FILTER, PUPIL

NIRISS

EXP_TYPE, FILTER, PUPIL

Standard Keywords

The following table lists the keywords that are required to be present in all reference files. The first column gives the FITS keyword names. The second column gives the jwst data model name for each keyword, which is useful when using data models in creating and populating a new reference file. The third column gives the equivalent meta tag in ASDF reference file headers, which is the same as the name within the data model meta tree (second column).

FITS Keyword

Data Model Name

ASDF meta tag

AUTHOR

model.meta.author

author

DATAMODL

model.meta.model_type

model_type

DATE

model.meta.date

date

DESCRIP

model.meta.description

description

FILENAME

model.meta.filename

N/A

INSTRUME

model.meta.instrument.name

instrument: {name}

PEDIGREE

model.meta.pedigree

pedigree

REFTYPE

model.meta.reftype

reftype

TELESCOP

model.meta.telescope

telescope

USEAFTER

model.meta.useafter

useafter

NOTE: More information on standard required keywords can be found here: Standard Required Keywords