Source Catalogs

A module that manages catalogs and source finding algorithms (i.e., SExtractor source finding).

Author

Mihai Cara (for help, contact HST Help Desk)

License

LICENSE

class subpixal.catalogs.ImageCatalog

A class for finding sources in images and handling catalog data: storing, filtering, and retrieving sources.

append_filters(self, fcond)

Add one or more conditions for selecting sources from the raw catalog to already set filters. See set_filters() for description of parameter fcond.

catalog(self)

Get catalog (after applying masks and selection filters).

compute_position_std(self, catalog)

This function is called to compute source position error estimate. This function uses the following simplified estimate: \(\sigma_{\mathrm{pos}}=\sigma_{\mathrm{Gaussian}} / \mathrm{SNR}=\mathrm{FWHM}/(2\sqrt{2 \ln 2}\mathrm{SNR})\). Sub-classes can implement more accurate position error computation.

Parameters

catalogastropy.table.Table

A table containing required_colnames columns.

Returns

pos_stdnumpy.ndarray

Position error computed from input catalog data.

compute_weights(self, catalog)

This function is called to compute source weights in a catalog. Currently, all weights are set equal to 1. Sub-classes should implement more meaningful weight computation.

Parameters

catalogastropy.table.Table

A table containing required_colnames columns.

Returns

weightsnumpy.ndarray

Weights computed from input catalog data.

abstract execute(self)

Find sources in the image. Compute catalog applying masks and selecting only sources that satisfy all set filters.

property filters

Get a list of all active selection filters.

get_segmentation_image(self)

Get segmentation image used to identify catalog’s sources.

property image_extn

Get image extension number when the image was set using a string file name. When image was set (in py:meth:set_image) using a numpy.ndarray, this property is None.

property mask_type

Get mask type: ‘coords’, ‘image’, or None (mask not set).

remove_all_filters(self)

Remove all selection filters.

remove_filter(self, key, op=None)

Remove a specific filter by column name and, optionally, by comparison operator.

Parameters

keystr

Column name to which selection criteria (filter) is applied. If more conditions match a column name vale, all of them will be removed.

opstr, optional

Specifies the comparison operation used in a filter. This allows narrowing down which filters should be removed.

property required_colnames

Get a list of the minimum column names that are required to be present in the raw catalog after catalog column name mapping has been applied.

set_default_filters(self)

Set default source selection criteria.

set_filters(self, fcond)

Set conditions for selecting sources from the raw catalog.

Parameters

fcondtuple, list of tuples

Each selection condition must be specified as a tuple of the form (colname, cond, value) OR (colname, nrows) where:

• colname is a column name from the raw catalog after catalog column name mapping has been applied. Use rawcat_colnames to get a list of available column names.

• cond is a string representing a selection condition, i.e., a comparison operator. The following operators are suported: ['>', '>=', '==', '!=', '<', '<=', 'h', 'l']. The 'h' or 'l' operators are used to select a specific number of rows (specified by the value) that have highest or lowest values in the column specified by colname. Selection of highest/lowest values is performed last, after all other comparison-based filters have been applied.

• value is a numeric value to be used for comparison of column values. When cond is either 'h' or 'l', this value must be a positive integer number of rows to be .

Multiple selection conditions can be provided as a list of the condition tuples described above.

set_image(self, image)

Set image to be used for source finding.

Parameters

image: numpy.ndarray, str

When setting an image either a numpy.ndarray of image data or a string file name is acceptable. Image file name may be followed by an extension specification such as 'file1.fits[1]' or 'file1.fits[(sci,1)]' (by default, the first image-like extension will be used).

set_mask(self, mask)

Get/Set mask used to ignore (mask) “bad” sources from the catalog.

Parameters

maskstr, tuple of two 1D lists of int, 2D numpy.ndarray

A mask can be provided in several ways:

• When mask is a string, it is assumed to be the name of a simple FITS file contaning a boolean mask indicating “bad” pixels using value True (=ignore these pixels) and “good” pixels using value False (=no need to mask).

• mask can also be provided directly as a boolean 2D “image” in the form of a boolean numpy.ndarray.

• Finally, mask can be a tuple of exactly two lists (or 1D numpy.ndarray) containing integer coordinates of the “pixels” to be masked as “bad”. Any source with coordinates within such a “pixel” will be excluded from the catalog.

class subpixal.catalogs.SExImageCatalog(image=None, sexconfig=None, max_stellarity=1.0, sextractor_cmd='sex')

A catalog class specialized in finding sources using SExtractor and then loading and processing raw SExtractor catalogs and its output files.

Parameters

imagestr

A FITS image file name.

sexconfigstr

File name of the SExtractor configuration file to be used for finding sources in the image.

max_stellarityfloat, None, optional

Maximum stellarity for selecting sources from the catalog. When max_stellarity is None, source filtering by ‘stellarity’ is turned off.

sextractor_cmdstr, optional

Command to invoke SExtractor.

append_filters(self, fcond)

Add one or more conditions for selecting sources from the raw catalog to already set filters. See set_filters() for description of parameter fcond.

property catalog

Get catalog (after applying masks and selection filters).

compute_position_std(self, catalog)

This function is called to compute source position error estimate. This function uses the following simplified estimate: \(\sigma_{\mathrm{pos}}=\sigma_{\mathrm{Gaussian}} / \mathrm{SNR}=\mathrm{FWHM}/(2\sqrt{2 \ln 2}\mathrm{SNR})\). Sub-classes can implement more accurate position error computation.

Parameters

catalogastropy.table.Table

A table containing required_colnames columns.

Returns

pos_stdnumpy.ndarray

Position error computed from input catalog data.

compute_weights(self, catalog)

This function is called to compute source weights in a catalog. This function estimates weights as \(1/\sigma_{\mathrm{pos}}\).

Parameters

catalogastropy.table.Table

A table containing required_colnames columns.

Returns

weightsastropy.table.Column

Weights computed from input catalog data.

execute(self)

Find sources in the image. Compute catalog applying masks and selecting only sources that satisfy all set filters.

property filters

Get a list of all active selection filters.

get_segmentation_image(self)

Get segmentation file name stored in the SExtractor’s configuration file or None.

property image_extn

Get image extension number when the image was set using a string file name. When image was set (in py:meth:set_image) using a numpy.ndarray, this property is None.

property mask_type

Get mask type: ‘coords’, ‘image’, or None (mask not set).

remove_all_filters(self)

Remove all selection filters.

remove_filter(self, key, op=None)

property required_colnames

Get a list of the minimum column names that are required to be present in the raw catalog after catalog column name mapping has been applied.

set_default_filters(self)

Sets default filters for selecting sources from the raw catalog.

Default selection criteria are: flux > 0 AND fwhm > 0 AND semi-major-a > 0 AND semi-major-b > 0 (AND stellarity <= max_stellarity, if max_stellarity is not None).

set_filters(self, fcond)

Set conditions for selecting sources from the raw catalog.

Parameters

fcondtuple, list of tuples

Each selection condition must be specified as a tuple of the form (colname, cond, value) OR (colname, nrows) where:

• colname is a column name from the raw catalog after catalog column name mapping has been applied. Use rawcat_colnames to get a list of available column names.

• cond is a string representing a selection condition, i.e., a comparison operator. The following operators are suported: ['>', '>=', '==', '!=', '<', '<=', 'h', 'l']. The 'h' or 'l' operators are used to select a specific number of rows (specified by the value) that have highest or lowest values in the column specified by colname. Selection of highest/lowest values is performed last, after all other comparison-based filters have been applied.

• value is a numeric value to be used for comparison of column values. When cond is either 'h' or 'l', this value must be a positive integer number of rows to be .

Multiple selection conditions can be provided as a list of the condition tuples described above.

set_image(self, image)

Set image to be used for source finding.

Parameters

image: numpy.ndarray, str

When setting an image either a numpy.ndarray of image data or a string file name is acceptable. Image file name may be followed by an extension specification such as 'file1.fits[1]' or 'file1.fits[(sci,1)]' (by default, the first image-like extension will be used).

set_mask(self, mask)

Get/Set mask used to ignore (mask) “bad” sources from the catalog.

Parameters

maskstr, tuple of two 1D lists of int, 2D numpy.ndarray

A mask can be provided in several ways:

• When mask is a string, it is assumed to be the name of a simple FITS file contaning a boolean mask indicating “bad” pixels using value True (=ignore these pixels) and “good” pixels using value False (=no need to mask).

• mask can also be provided directly as a boolean 2D “image” in the form of a boolean numpy.ndarray.

• Finally, mask can be a tuple of exactly two lists (or 1D numpy.ndarray) containing integer coordinates of the “pixels” to be masked as “bad”. Any source with coordinates within such a “pixel” will be excluded from the catalog.

property sexconfig

Set/Get SExtractor configuration file.