# Classes to manage Catalogs and WCS’s

This module provides the classes used to generate and manage source catalogs for each input chip. Those positions can be transformed to undistorted sky positions, written out to files, or plotted using various methods defined for these classes.

Authors: | Warren Hack
License: | http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

`drizzlepac.catalogs.``generateCatalog`(wcs, mode='automatic', catalog=None, src_find_filters=None, **kwargs)

  Function which determines what type of catalog object needs to be instantiated based on what type of source selection algorithm the user specified.

  Parameters:

  wcs : obj

    WCS object generated by STWCS or PyWCS

  catalog : str or ndarray

    Filename of existing catalog or ndarray of image for generation of source catalog.

  kwargs : dict

    Parameters needed to interpret source catalog from input catalog with `findmode` being required.

  Returns:

  catalog : obj

    A Catalog-based class instance for keeping track of WCS and associated source catalog

class `drizzlepac.catalogs.``ImageCatalog`(wcs, catalog_source, src_find_filters=None, **kwargs)

  Bases: `drizzlepac.catalogs.Catalog`

  Class which generates a source catalog from an image using Python-based, daofind-like algorithms

  Required input `kwargs` parameters:

      computesig, skysigma, threshold, peakmin, peakmax,
      hmin, conv_width, [roundlim, sharplim]

  Methods

  `apply_exclusions`(exclusions) | Trim sky catalog to remove any sources within regions specified by exclusions file
  `apply_flux_limits`() | Apply any user-specified limits on source selection Limits based on fluxes
  `buildCatalogs`([exclusions]) | Primary interface to build catalogs based on user inputs.
  `generateRaDec`() | Convert XY positions into sky coordinates using STWCS methods
  `generateXY`(**kwargs) | Generate source catalog from input image using DAOFIND-style algorithm
  `plotXYCatalog`(**kwargs) | Method which displays the original image and overlays the positions of the detected sources from this image’s catalog.
  `set_colnames`() | Method to define how to interpret a catalog file Only needed when provided a source catalog as input
  `writeXYCatalog`(filename) | Write out the X,Y catalog to a file

  `generateXY`(**kwargs)

    Generate source catalog from input image using DAOFIND-style algorithm

class `drizzlepac.catalogs.``UserCatalog`(wcs, catalog_source, **kwargs)

  Bases: `drizzlepac.catalogs.Catalog`

  Class to manage user-supplied catalogs as inputs.

  Required input `kwargs` parameters:

      xyunits, xcol, ycol[, fluxcol, [idcol]]

  Attributes:

  IN_UNITS

  Methods

  `apply_exclusions`(exclusions) | Trim sky catalog to remove any sources within regions specified by exclusions file
  `apply_flux_limits`() | Apply any user-specified limits on source selection Limits based on fluxes
  `buildCatalogs`([exclusions]) | Primary interface to build catalogs based on user inputs.
  `generateRaDec`() | Convert XY positions into sky coordinates using STWCS methods
  `generateXY`(**kwargs) | Method to interpret input catalog file as columns of positions and fluxes.
  `plotXYCatalog`(**kwargs) | Plots the source catalog positions using matplotlib’s `pyplot.plot()`
  `set_colnames`() | Method to define how to interpret a catalog file Only needed when provided a source catalog as input
  `writeXYCatalog`(filename) | Write out the X,Y catalog to a file

  `COLNAMES` = ['xcol', 'ycol', 'fluxcol']
  `IN_UNITS` = None
  `generateXY`(**kwargs)

    Method to interpret input catalog file as columns of positions and fluxes.

  `plotXYCatalog`(**kwargs)

    Plots the source catalog positions using matplotlib’s `pyplot.plot()`

    Plotting `kwargs` that can also be passed include any keywords understood by matplotlib’s `pyplot.plot()` function such as:

        vmin, vmax, cmap, marker

  `set_colnames`()

    Method to define how to interpret a catalog file Only needed when provided a source catalog as input

class `drizzlepac.catalogs.``RefCatalog`(wcs, catalog_source, **kwargs)

  Bases: `drizzlepac.catalogs.UserCatalog`

  Class which manages a reference catalog.

  Notes

  A reference catalog is defined as a catalog of undistorted source positions given in RA/Dec which would be used as the master list for subsequent matching and fitting.

  Methods

  `apply_exclusions`(exclusions) | Trim sky catalog to remove any sources within regions specified by exclusions file
  `apply_flux_limits`() | Apply any user-specified limits on source selection Limits based on fluxes
  `buildCatalogs`([exclusions]) | Primary interface to build catalogs based on user inputs.
  `generateRaDec`() | Convert XY positions into sky coordinates using STWCS methods
  `generateXY`(**kwargs) | Method to interpret input catalog file as columns of positions and fluxes.
  `plotXYCatalog`(**kwargs) | Plots the source catalog positions using matplotlib’s `pyplot.plot()`
  `set_colnames`() | Method to define how to interpret a catalog file Only needed when provided a source catalog as input
  `writeXYCatalog`(filename) | Write out the X,Y catalog to a file

  buildXY |

  `COLNAMES` = ['refxcol', 'refycol', 'rfluxcol']
  `IN_UNITS` = 'degrees'
  `PAR_NBRIGHT_PREFIX` = 'ref'
  `PAR_PREFIX` = 'r'
  `buildXY`(catalogs)
  `generateRaDec`()

    Convert XY positions into sky coordinates using STWCS methods

  `generateXY`(**kwargs)

    Method to interpret input catalog file as columns of positions and fluxes.

class `drizzlepac.catalogs.``Catalog`(wcs, catalog_source, **kwargs)

  Bases: `object`

  Base class for keeping track of a source catalog for an input WCS

  Warning

  This class should never be instantiated by itself, as necessary methods are not defined yet.

  Methods

  `apply_exclusions`(exclusions) | Trim sky catalog to remove any sources within regions specified by exclusions file
  `apply_flux_limits`() | Apply any user-specified limits on source selection Limits based on fluxes
  `buildCatalogs`([exclusions]) | Primary interface to build catalogs based on user inputs.
  `generateRaDec`() | Convert XY positions into sky coordinates using STWCS methods
  `generateXY`(**kwargs) | Method to generate source catalog in XY positions Implemented by each subclass
  `plotXYCatalog`(**kwargs) | Method which displays the original image and overlays the positions of the detected sources from this image’s catalog.
  `set_colnames`() | Method to define how to interpret a catalog file Only needed when provided a source catalog as input
  `writeXYCatalog`(filename) | Write out the X,Y catalog to a file

  `PAR_NBRIGHT_PREFIX` = ''
  `PAR_PREFIX` = ''
  `apply_exclusions`(exclusions)

    Trim sky catalog to remove any sources within regions specified by exclusions file

  `apply_flux_limits`()

    Apply any user-specified limits on source selection Limits based on fluxes

  `buildCatalogs`(exclusions=None, **kwargs)

    Primary interface to build catalogs based on user inputs.

  `generateRaDec`()

    Convert XY positions into sky coordinates using STWCS methods

  `generateXY`(**kwargs)

    Method to generate source catalog in XY positions Implemented by each subclass

  `plotXYCatalog`(**kwargs)

    Method which displays the original image and overlays the positions of the detected sources from this image’s catalog.

    Plotting `kwargs` that can be provided are:

    > vmin, vmax, cmap, marker

    Default colormap is `summer`.

  `set_colnames`()

    Method to define how to interpret a catalog file Only needed when provided a source catalog as input

  `writeXYCatalog`(filename)

    Write out the X,Y catalog to a file