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 :py:meth:`~astropy.table.Table.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
<http://adsabs.harvard.edu/abs/1987PASP...99..191S>`_).  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.

.. _DAOFIND: http://stsdas.stsci.edu/cgi-bin/gethelp.cgi?daofind

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
:py:meth:`~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.

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 `~jwst.datamodels.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 '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 GSSS STScI web services at `GSSSCATALOGS`_ 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.

.. _GSSSCATALOGS: http://gsss.stsci.edu/Catalogs/Catalogs.htm

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. 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
:py:meth:`~astropy.table.Table.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', 'GAIADR3', a path to an existing
  reference catalog, `None`, or ''. See
  :py:data:`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.

.. include:: ../references_general/pars-tweakregstep_reffile.inc
