`write_catalog`: writing source catalogs

The properties of the fitted Gaussians, sources, and shapelets may be written in a number of formats to a file using the write_catalog task. See below (Definition of output columns) for a detailed description of the output columns.

Note

For BBS and SAGECAL formats, the output catalogs always use the J2000 equinox. If the input image does not have an equinox of J2000, the coordinates of sources will be precessed to J2000. Catalogs in other formats will have the equinox of the image.

The task parameters are as follows:

WRITE_CATALOG: Write the Gaussian, source, or shapelet list to a file.
================================================================================
outfile ............... None : Output file name. None => file is named
                               automatically; 'SAMP' => send to SAMP hub (e.g., to
                               TOPCAT, ds9, or Aladin)
bbs_patches ........... None : For BBS format, type of patch to use: None => no
                               patches. 'single' => all Gaussians in one patch.
                               'gaussian' => each Gaussian gets its own patch.
                               'source' => all Gaussians belonging to a single
                               source are grouped into one patch. 'mask' => use mask
                               file specified by bbs_patches_mask
bbs_patches_mask ...... None : Name of the mask file (of same size as input image)
                               that defines the patches if bbs_patches = 'mask'
catalog_type .......... 'srl': Type of catalog to write:  'gaul' - Gaussian
                               list, 'srl' - source list (formed by grouping
                               Gaussians), 'shap' - shapelet list (FITS
                               format only)
clobber .............. False : Overwrite existing file?
correct_proj .......... True : Correct source parameters for image projection
                               (BBS format only)?
format ............... 'fits': Format of output Gaussian list: 'bbs', 'ds9',
                               'fits', 'star', 'kvis', 'ascii', 'csv', 'casabox', or
                               'sagecal'
incl_chan ............ False : Include fluxes from each channel (if any)?
incl_empty ........... False : Include islands without any valid Gaussians
                               (source list only)?
srcroot ............... None : Root name for entries in the output catalog. None
                               => use image file name

Each of the parameters is described in detail below.

outfile

This parameter is a string (default is None) that sets the name of the output file. If None, the file is named automatically. If ‘SAMP’ the full catalog (i.e., format = 'fits') is sent to a running SAMP Hub (e.g., to TOPCAT or Aladin).

bbs_patches

This parameter is a string (default is None) that sets the type of patch to use in BBS-formatted catalogs. When the Gaussian catalogue is written as a BBS-readable sky file, this option determines whether all Gaussians are in a single patch ('single'), there are no patches (None), all Gaussians for a given source are in a separate patch ('source'), each Gaussian gets its own patch ('gaussian'), or a mask image is used to define the patches ('mask').

If you wish to have patches defined by island, then set group_by_isl = True before fitting to force all Gaussians in an island to be in a single source. Then set bbs_patches = 'source' when writing the catalog.

bbs_patches_mask

This parameter is a string (default is None) that sets the file name of the mask file to use to define patches in BBS-formatted catalogs. The mask image should be 1 inside the patches and 0 elsewhere and should be the same size as the input image (before any trim_box is applied). Any Gaussians that fall outside of the patches will be ignored and will not appear in the output sky model.

catalog_type

This parameter is a string (default is 'srl') that sets the type of catalog to write: 'gaul' - Gaussian list, 'srl' - source list (formed by grouping Gaussians), 'shap' - shapelet list ('fits' format only)

Note

The choice of 'srl' or 'gaul' depends on whether you want all the source structure in your catalog or not. For example, if you are making a sky model for use as a model in calibration, you want to include all the source structure in your model, so you would use a Gaussian list ('gaul'), which writes each Gaussian. On the other hand, if you want to compare to other source catalogs, you want instead the total source flux densities, so use source lists ('srl'). For example, say you have a source that is unresolved in WENSS, but is resolved in your image into two nearby Gaussians that are grouped into a single source. In this case, you want to compare the sum of the Gaussians to the WENSS flux density, and hence should use a source list.

clobber

This parameter is a Boolean (default is False) that determines whether existing files are overwritten or not.

correct_proj

This parameter is a Boolean (default is True) that determines whether the source parameters in the output catalog will be corrected for first-order projection effects. If False, no correction is done. In this case, the position angle is relative to the +y axis, NOT true north, and source sizes are calculated assuming a constant pixel scale (equal to the scale at the image center).

If True, the position angle and source size are corrected using the average pixel size and angle offset (between the +y axis and north) at the location of the source center.

format

This parameter is a string (default is 'fits') that sets the format of the output catalog. The following formats are supported:

'bbs' - BlackBoard Selfcal sky model format (Gaussian list only)
'ds9' - ds9 region format
'fits' - FITS catalog format, readable by many software packages, including IDL, TOPCAT, Python, fv, Aladin, etc.
'star' - AIPS STAR format (Gaussian list only)
'kvis' - kvis format (Gaussian list only)
'ascii' - simple text file with spaces separating the values
'csv' - Comma-separated Values (CSV) text file
'casabox' - CASA region file (boxes only)
'sagecal' - SAGECAL sky model format (Gaussian list only)

Catalogues with the 'fits', 'ascii', and 'csv' formats include all available information (see Definition of output columns for column definitions). The other formats include only a subset of the full information.

incl_chan

This parameter is a Boolean (default is False) that determines whether the total flux densities of each source measured in each channel by the spectral index module are included in the output.

incl_empty

This parameter is a Boolean (default is False) that determines whether islands without any valid Gaussians are included in the output catalog. This option is only available for source lists. If True, islands for which Gaussian fitting failed will be included in the output catalog. In these cases, the source IDs are negative and only a subset of the standard columns will be populated (columns requiring information from Gaussian fits are left blank).

srcroot

This parameter is a string (default is None) that sets the root for source names in the output catalog.

Definition of output columns

The information included in the Gaussian and source catalogs varies by format and can include the following quantities.

Note

For ACSII, CSV, and FITS formats, the reference frequency (in Hz) and equinox are stored in the header of the catalog. The header in ASCII and CSV catalogs is the first few lines of the catalog. For FITS catalogs, this information is stored in the comments as well as in the FREQ0 and EQUINOX keywords in the primary header.

The shapelet catalog contains the following additional columns:

shapelet_basis: the basis coordinate system: ‘c’ for cartesian, ‘s’ for spherical
shapelet_beta: the \(\beta\) parameter of the shapelet decomposition
shapelet_nmax: the maximum order of the shapelet
shapelet_cf: a (flattened) array of the shapelet coefficients

write_catalog: writing source catalogs

Definition of output columns

`write_catalog`: writing source catalogs