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:: License

class drizzlepac.catalogs.Catalog(wcs, catalog_source, **kwargs)[source]

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.

This class requires the input of a WCS and a source for the catalog, along with any arguments necessary for interpreting the catalog.

Parameters:

wcsobj: Input WCS object generated using STWCS or HSTWCS
catalog_sourcestr: Name of the file from which to read the catalog.
kwargsdict: Parameters for interpreting the catalog file or for performing the source extraction from the image. These will be set differently depending on the type of catalog being instantiated.

PAR_NBRIGHT_PREFIX = ''

PAR_PREFIX = ''

apply_exclusions(exclusions)[source]: Trim sky catalog to remove any sources within regions specified by exclusions file.

apply_flux_limits()[source]: Apply any user-specified limits on source selection Limits based on fluxes.

buildCatalogs(exclusions=None, **kwargs)[source]: Primary interface to build catalogs based on user inputs.

generateRaDec()[source]: Convert XY positions into sky coordinates using STWCS methods.

generateXY(**kwargs)[source]: Method to generate source catalog in XY positions Implemented by each subclass

plotXYCatalog(**kwargs)[source]

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()[source]: Method to define how to interpret a catalog file Only needed when provided a source catalog as input

writeXYCatalog(filename)[source]: Write out the X,Y catalog to a file

class drizzlepac.catalogs.ImageCatalog(wcs, catalog_source, src_find_filters=None, **kwargs)[source]

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

Parameters:

src_find_filtersdict, optional

Dictionary containing region file information for source finding.

computesigbool, optional

This parameter controls whether or not to automatically compute a sigma value to be used for object identification. If set to True, then the value computed will override any user input for the parameter skysigma. The automatic sigma value gets computed from each input exposure as:

\[\sigma = \sqrt{2\left|mode\right|}\]

This single value will then be used for object identification for all input exposures. Default: True

skysigmafloat, optional

The standard deviation of the sky pixels. This value will only be used if computesig is False. Default: 0.0

thresholdfloat, optional

The object detection threshold above the local background in units of sigma. Default: 4.0

peakminfloat or None, optional

This parameter allows the user to select only those sources whose peak value (in the units of the input image) is greater than this value. Default: None

peakmaxfloat or None, optional

This parameter allows the user to select only those sources whose peak value (in the units of the input image) is less than this value. Default: None

hminfloat or None, optional

Threshold in sigma for feature detection. Default: 4.0

conv_widthfloat, optional

The convolution kernel width in pixels. Recommended values (~2x the PSF FWHM): ACS/WFC & WFC3/UVIS ~3.5 pix and WFC3/IR ~2.5 pix. Default: 3.5

use_sharp_roundbool, optional

This parameter controls whether or not to enable selection of sources based on their sharpness and roundness statistics. Default: False

sharplofloat, optional

sharplo and sharphi are designed to eliminate brightness maxima that are due to bad pixels rather than to astronomical objects. Only sources with sharpness above the sharplo value will be selected. Default: 0.2

sharphifloat, optional

sharplo and sharphi are designed to eliminate brightness maxima that are due to bad pixels rather than to astronomical objects. Only sources with sharpness below the sharphi value will be selected. Default: 1.0

roundlofloat, optional

roundlo and roundhi are designed to eliminate brightness maxima that are due to bad rows or columns, rather than to astronomical objects. Only sources with roundness above the roundlo value will be selected. Default: -1.0

roundhifloat, optional

roundlo and roundhi are designed to eliminate brightness maxima that are due to bad rows or columns, rather than to astronomical objects. Only sources with roundness below the roundhi value will be selected. Default: 1.0

nsigmafloat, optional

The semi-major axis of the Gaussian convolution kernel used to compute the density enhancement and mean density images in Gaussian sigma. Default: 1.5

ratiofloat, optional

The ratio of the sigma of the Gaussian convolution kernel along the minor axis direction to the sigma along the major axis direction. For a circularly-symmetric kernel use ratio = 1.0. Default: 1.0

thetafloat, optional

The position angle (degrees) of the major axis of the Gaussian convolution kernel. Theta is measured counter-clockwise from the x axis. Default: 0.0

fluxminfloat or None, optional

This parameter allows the user to select only those sources whose total flux (in the units of the input image) is greater than this value. Default: None

fluxmaxfloat or None, optional

This parameter allows the user to select only those sources whose total flux (in the units of the input image) is less than this value. Default: None

dqbitsint, str, or None, optional

Integer sum of all the DQ bit values from the input image’s DQ array that should be considered “good” when building masks for source finding. For example, if pixels in the DQ array can be combinations of 1, 2, 4, and 8 flags and one wants to consider DQ “defects” having flags 2 and 4 as being acceptable for source finding, then dqbits should be set to 2+4=6. Then a DQ pixel having values 2,4, or 6 will be considered a good pixel, while a DQ pixel with a value, e.g., 1+2=3, 4+8=12, etc. will be flagged as a “bad” pixel.

Alternatively, one can enter a comma- or ‘+’-separated list of integer bit flags that should be added to obtain the final “good” bits. For example, both 4,8 and 4+8 are equivalent to setting dqbits to 12.

Setting dqbits to 0 will make all non-zero pixels in the DQ mask to be considered “bad” pixels, and the corresponding image pixels will not be used for source finding.

The default value of None will turn off the use of image’s DQ array for source finding.

In order to reverse the meaning of the dqbits parameter from indicating values of the “good” DQ flags to indicating the “bad” DQ flags, prepend ‘~’ to the string value. For example, in order not to use pixels with DQ flags 4 and 8 for source finding and to consider as “good” all other pixels (regardless of their DQ flag), set dqbits to ~4+8, or ~4,8. To obtain the same effect with an int input value (except for 0), enter -(4+8+1)=-13. Following this convention, a dqbits string value of '~0' would be equivalent to setting dqbits=None. Default: None

This class requires the input of a WCS and a source for the catalog, along with any arguments necessary for interpreting the catalog.

Parameters:

wcsobj: Input WCS object generated using STWCS or HSTWCS
catalog_sourcestr: Name of the file from which to read the catalog.
kwargsdict: Parameters for interpreting the catalog file or for performing the source extraction from the image. These will be set differently depending on the type of catalog being instantiated.

class drizzlepac.catalogs.UserCatalog(wcs, catalog_source, **kwargs)[source]

Bases: Catalog

Class to manage user-supplied catalogs as inputs.

Parameters:

xyunitsstr

Units of the input catalog positions. Valid values are:

‘pixels’: Positions are in pixel coordinates.
‘degrees’: Positions are in world coordinates (RA/Dec) in degrees.

xcolint

Column number for the x-coordinate (1-based).

ycolint

Column number for the y-coordinate (1-based).

fluxcolint

Column number for the flux (1-based).

kwargsdict

Parameters for interpreting the catalog file or for performing the source extraction from the image. These will be set differently depending on the type of catalog being instantiated.

This class requires the input of a WCS and a source for the catalog, along with any arguments necessary for interpreting the catalog.

Parameters:

wcsobj: Input WCS object generated using STWCS or HSTWCS
catalog_sourcestr: Name of the file from which to read the catalog.
kwargsdict: Parameters for interpreting the catalog file or for performing the source extraction from the image. These will be set differently depending on the type of catalog being instantiated.

COLNAMES = ['xcol', 'ycol', 'fluxcol']

IN_UNITS = None

generateXY(**kwargs)[source]: Method to interpret input catalog file as columns of positions and fluxes.

plotXYCatalog(**kwargs)[source]

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()[source]: 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)[source]

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

This class requires the input of a WCS and a source for the catalog, along with any arguments necessary for interpreting the catalog.

Parameters:

wcsobj: Input WCS object generated using STWCS or HSTWCS
catalog_sourcestr: Name of the file from which to read the catalog.
kwargsdict: Parameters for interpreting the catalog file or for performing the source extraction from the image. These will be set differently depending on the type of catalog being instantiated.

COLNAMES = ['refxcol', 'refycol', 'rfluxcol']

IN_UNITS = 'degrees'

PAR_NBRIGHT_PREFIX = 'ref'

PAR_PREFIX = 'r'

buildXY(catalogs)[source]

generateRaDec()[source]: Convert XY positions into sky coordinates using STWCS methods.

generateXY(**kwargs)[source]: Method to interpret input catalog file as columns of positions and fluxes.

drizzlepac.catalogs.generateCatalog(wcs, mode='automatic', catalog=None, src_find_filters=None, **kwargs)[source]

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

Parameters:

wcsobj: WCS object generated by STWCS or PyWCS
catalogstr or ndarray: Filename of existing catalog or ndarray of image for generation of source catalog.
kwargsdict: Parameters needed to interpret source catalog from input catalog with findmode being required.

Returns:

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