Description

Class:: romancal.source_catalog.SourceCatalogStep
Alias:: source_catalog

This step detects sources in an image and generates a catalog of their properties, including photometric and shape measurements.

Background Subtraction

A two-dimensional background is estimated and subtracted from the data. The background and background noise are estimated using the photutils.background.Background2D class from Photutils. This class calculates the background by measuring the sigma-clipped median within user-defined boxes of a specified size (bkg_boxsize). The background RMS noise is then estimated using the sigma-clipped standard deviation within the same boxes.

Source Detection

Sources are detected using image segmentation, a process that assigns an integer label to each pixel in an image, such that pixels with the same label correspond to the same source. Source extraction is then performed using the Photutils segmentation tools.

The background-subtracted image is convolved with a Gaussian kernel to smooth the noise and enhance the detectability of objects with a shape similar to the kernel. The Gaussian kernel is defined by the kernel_fwhm parameter, which specifies the full-width at half-maximum (FWHM) of the kernel. The kernel is normalized to have a total flux of 1.0.

Detected sources must consist of a minimum number of connected pixels (npixels), each exceeding a specified threshold value in the convolved image. The threshold level is defined as a per-pixel multiple (snr_threshold) of the background RMS image.

Overlapping sources are deblended using the Photutils deblender. The deblending algorithm first applies a multi-thresholding approach to identify potentially overlapping sources, then uses watershed segmentation to separate them. For successful deblending, the sources must be separated enough that there is a saddle point between them. Currently, the deblend keyword must be set to deblend sources.

Source Photometry and Properties

After detecting sources using image segmentation, we measure their photometry, centroids, and shape/morphological properties.

The source centroids and shape properties are derived from 2D image moments of the pixel values within the source segments using photutils.segmentation.SourceCatalog. These properties include the semimajor and semiminor axes, ellipticity, and orientation of the major axis.

The image moments are computed in the pixel frame. Properties that are reported in sky units (semimajor, semiminor, fwhm, kron_radius, segment_area, and nn_distance) are converted using the pixel scale local to each source, and orientation_sky is measured from the direction of north local to each source rather than from a single direction for the whole image.

Only the size and rotation of the local pixel are accounted for, not its shape. Where pixels are not square, the sky-frame axis lengths and position angle carry a residual error of order the departure from squareness (1-3% for Roman). ellipticity and orientation_pix are pixel-frame quantities and are not corrected at all.

Circular aperture photometry is performed at several aperture sizes (\(r\) = 0.1, 0.2, 0.4, 0.8, 1.6 arcsec) for each source. These radii are converted to pixels using the pixel scale local to each source. Because a single aperture can only be measured at one radius at a time, sources are grouped into batches that share a common radius, chosen so that no source’s aperture radius is wrong by more than about one part in \(10^{4}\).

The circle_pix and annulus_pix entries in the catalog metadata report the mean radius over all sources rather than the exact radius used for any one of them. The circle_arcsec and annulus_arcsec entries are exact and are the same for every source.

Elliptical Kron aperture photometry is also performed, where the aperture size is determined by the source shape.

Isophotal photometry is measured using the total flux within the source segment.

Optionally, Point Spread Function (PSF) photometry can be performed by setting the fit_psf keyword. Enabling this option fits a model PSF to each source to measure its position and flux. The PSF model is generated using reference files on CRDS. PSF photometry is performed using the photutils.psf.PSFPhotometry class.

For Level 2 data, a gridded PSF model is generated for each individual detector using the reference files in CRDS. These PSF models account for jitter by deconvolving the amount of jitter indicated to be present in the PSF reference file, and reconvolving with the amount of jitter present in the individual image. Because the amount of jitter present in the reference file is small (~8 mas), this deconvolution does not introduce significant noise. The convolution process works in the Fourier domain using the approach of Lang (2020) because the jitter kernel would otherwise be badly undersampled.

For Level 3 data, since the data contains a mixture of individual detector PSFs with different orientations, further processing is done. The base PSF is calculated for the center of the WFI02 detector. It is then scaled and smoothed to roughly account for the different pixel scale of the coadded images relative to the detector images, and the effect of the image drizzling on the PSF. Finally, the PSF is azimuthally averaged to remove any azimuthal signatures, which will be different in the coadded product than in the individual input exposures.

Surface Brightness to Flux Conversion

Level 2 and Level 3 pixel values are surface brightnesses, not fluxes. Recovering the flux entering a pixel therefore requires multiplying its surface brightness by the solid angle of that particular pixel. The solid angle is computed directly from the WCS. Note that the variation in the pixel solid angle for WFI L2 images is of order 2%. For L3 coadds the variation in pixel solid angle is much smaller.

All fluxes are reported in nJy. To calculate AB magnitudes, use the following formula:

\[m_{\rm AB} = -2.5 \log_{10}(f_{\rm nJy}) + 31.4\]

Photometric errors are calculated from the resampled total-error array contained in the model.err array. Note that this array includes source Poisson noise.

A local background is estimated for each source measured within a circular annulus centered on the source. The circular annulus has an inner and outer radius of 2.4 and 2.8 arcsec, respectively, converted to pixels using the pixel scale local to each source. The local background flux is calculated as the sigma-clipped median value within the annulus, divided by the local pixel solid angle, and is a surface brightness (nJy/arcsec²) rather than a flux. Although this local background value is included in the source catalog, it is not subtracted from any of the measured fluxes.

Each source has a field, is_extended, intended to indicate whether the source is more extended than expected, were the object a point source. The determination is made on the basis of the ratio of aperture fluxes at 0.4 and 0.2 arcsec being more than 1.2x larger than expected for a point source.

Source Catalog Table

The source catalog table contains one row for each source, with the columns listed below (assuming PSF-photometry is requested, i.e., fit_psf=True).

All pixel coordinates are 0-indexed, following Python’s 0-based indexing. This means pixel coordinate 0 corresponds to the center of the first pixel.

All sky coordinates are in decimal degrees in the International Celestial Reference System (ICRS) reference frame.

Uncertainties are reported as the 1-sigma (68.27% confidence) errors.

Some column names contain templated strings that will be replaced with values specific to the generated file. For example ~band~ will be replaced with a filter wavelength band (for example f184) where appropriate and removed for single-filter files. ~radius~ will be replaced with the aperture radius in tenths of an arcsecond. For example, a single filter catalog with 0.1 arcsecond aperture photometry will contain an aper01_flux column. A catalog derived from multiple filters (including f184) and the same aperture radius will contain an aper01_f184_flux column.

Name	Unit	Description
aper_bkg_~band~_flux	nJy arcsec-2	Local background estimated within a circular annulus
aper_bkg_~band~_flux_err	nJy arcsec-2	Uncertainty in local background estimated in a circular annulus
aper_bkg_~band~m~band~_flux	nJy arcsec-2	Local background estimate for PSF-matched aperture photometry
aper_bkg_~band~m~band~_flux_err	nJy arcsec-2	Uncertainty in local background estimate for PSF-matched aperture photometry
aper~radius~_~band~_flux	nJy	Flux within circular aperture (radius in tenths of arcsec)
aper~radius~_~band~_flux_err	nJy	Uncertainty in flux within circular aperture
aper~radius~_~band~m~band~_flux	nJy	PSF-matched flux within circular aperture (radius in tenths of arcsec)
aper~radius~_~band~m~band~_flux_err	nJy	Uncertainty in PSF-matched flux within circular aperture
bbox_xmax	none	Column index of the right edge of the source bounding box (0 indexed)
bbox_xmin	none	Column index of the left edge of the source bounding box (0 indexed)
bbox_ymax	none	Row index of the top edge of the source bounding box (0 indexed)
bbox_ymin	none	Row index of the bottom edge of the source bounding box (0 indexed)
cxx	1/arcsec2	Coefficient for the x**2 term in the generalized quadratic ellipse equation
cxy	1/arcsec2	Coefficient for the x*y term in the generalized quadratic ellipse equation
cyy	1/arcsec2	Coefficient for the y**2 term in the generalized quadratic ellipse equation
dec	deg	Best estimate of the declination (ICRS)
dec_centroid	deg	Declination of the source centroid (ICRS)
dec_centroid_err	arcsec	Uncertainty in dec_centroid
dec_centroid_win	deg	Declination (ICRS) of the windowed source centroid
dec_centroid_win_err	arcsec	Uncertainty in dec_centroid_win
dec_psf_~band~	deg	Declination (ICRS) of the PSF-fitted position
dec_psf_~band~_err	arcsec	Uncertainty in dec_psf
dust_ebv	mag	Estimated dust extinction in B-V, taken by default from the map of Schlegel, Finkbeiner, and Davis (1998)
ellipticity	none	Source ellipticity as 1 - (semimajor / semiminor)
flagged_spatial_id	none	Bit flag encoding the overlap flag, projection, skycell and pixel coordinates of the source
fluxfrac_radius_50_~band~	arcsec	Radius of a circle centered on the source centroid that encloses 50% of the Kron flux
fwhm	arcsec	Circularized full width at half maximum (FWHM) calculated from the semimajor and semiminor axes as 2sqrt(ln(2) (semimajor2 + semiminor2))
image_flags	none	Image quality bit flags (0=good)
is_extended_~band~	none	Flag indicating that the source appears to be more extended than a point source
kron_radius	arcsec	First-moment radius measured in the detection image.
kron_~band~_abmag	mag(AB)	AB magnitude within the elliptical Kron aperture
kron_~band~_abmag_err	mag(AB)	Uncertainty in kron_abmag
kron_~band~_flux	nJy	Flux within the elliptical Kron aperture
kron_~band~_flux_err	nJy	Uncertainty in kron_<band>_flux_err
kron_~band~m~band~_flux	nJy	PSF-matched flux within the elliptical Kron aperture
kron_~band~m~band~_flux_err	nJy	Uncertainty in kron_<band>m<band>_abmag_err
label	none	Label of the source segment in the segmentation image
nn_distance	arcsec	Distance to the nearest neighbor in this skycell
nn_label	none	Segment label of the nearest neighbor in this skycell
orientation_pix	deg	Angle measured counter-clockwise from the positive X axis to the source major axis computed from image moments
orientation_sky	deg	Position angle from North of the source major axis computed from image moments
photoz	none	Recommended point estimate of photometric redshift
photoz_gof	none	Photo-z goodness of fit metric
photoz_high68	none	68% confidence upper bound on photometric redshift
photoz_high90	none	90% confidence upper bound on photometric redshift
photoz_high99	none	99% confidence upper bound on photometric redshift
photoz_low68	none	68% confidence lower bound on photometric redshift
photoz_low90	none	90% confidence lower bound on photometric redshift
photoz_low99	none	99% confidence lower bound on photometric redshift
photoz_sed	none	Best-fit spectral-energy distribution for this photometric redshift
psf_flags_~band~	none	PSF fitting bit flags (0 = good)
psf_gof_~band~	none	PSF goodness of fit metric
psf_~band~_flux	nJy	Total PSF flux
psf_~band~_flux_err	nJy	Uncertainty in psf_flux
ra	deg	Best estimate of the right ascension (ICRS)
ra_centroid	deg	Right ascension (ICRS) of the source centroid
ra_centroid_err	arcsec	Uncertainty in ra_centroid
ra_centroid_win	deg	Right ascension (ICRS) of the windowed source centroid
ra_centroid_win_err	arcsec	Uncertainty in ra_centroid_win
ra_psf_~band~	deg	Right ascension (ICRS) of the PSF-fitted position
ra_psf_~band~_err	arcsec	Uncertainty in ra_psf
roundness1_~band~	none	Photutils DAOFinder roundness1 statistic
segment_area	arcsec^2	Area of the source segment
segment_~band~_flux	nJy	Isophotal flux
segment_~band~_flux_err	nJy	Uncertainty in segment_flux
segment_~band~m~band~_flux	nJy	Isophotal flux after PSF matching to a reference band
segment_~band~m~band~_flux_err	nJy	Isophotal flux error after PSF matching to a reference band
semimajor	arcsec	Length of the source semimajor axis computed from image moments
semiminor	arcsec	Length of the source semiminor axis computed from image moments
sharpness_~band~	none	Photutils DAOFinder sharpness statistic
warning_flags	none	Warning bit flags (0=good)
x_centroid	pix	Column coordinate of the source centroid from image moments (0 indexed)
x_centroid_err	pix	Uncertainty x_centroid
x_centroid_win	pix	Column coordinate of the windowed source centroid in the detection image from image moments (0 indexed)
x_centroid_win_err	pix	Uncertainty on x_centroid_win
x_psf_~band~	pix	Column coordinate of the source from PSF fitting (0 indexed)
x_psf_~band~_err	pix	Uncertainty in x_psf
y_centroid	pix	Row coordinate of the source centroid in the detection image from image moments (0 indexed)
y_centroid_err	pix	Uncertainty on y_centroid
y_centroid_win	pix	Row coordinate of the windowed source centroid in the detection image from image moments (0 indexed)
y_centroid_win_err	pix	Uncertainty on y_centroid_win
y_psf_~band~	pix	Row coordinate of the source from PSF fitting (0 indexed)
y_psf_~band~_err	pix	Uncertainty on y_psf

Further details for some of the columns are provided below.

flagged_spatial_id is a bit flag encoding the overlap flag, projection, skycell, and pixel coordinates of the source. Bit positions are 0-indexed (i.e., bit N has value 2**N). From high to low, bit 59 is 1 if the object was outside of the core region of this skycell or projection region. There is likely to be a better measurement of the object in a different skycell with this bit set to 0. This bit is the same as bit TBD of warning_flags. Bits 46-58 encode the primary projection region for this object. Bits 32-38 and 39-45 encode the x and y skycell indices within this projection region, starting from (0, 0) at the lower left. Bits 0-15 and 16-31 encode the x and y pixel coordinates of the object within this skycell in virtual 0.05” pixels (regardless of the pixel scale of the skycell).

The psf_gof metric is the reduced chi-squared of the PSF fit.

Flag Columns

The warning_flags column contains the following bit flags:

0 : Good
1 :
- Level 2: sources whose rounded centroid pixel is not finite or has DO_NOT_USE set in the model DQ
- Level 3: sources whose rounded centroid pixel is not finite or has a weight of 0

The image_flags column contains the following bit flags:

0 : Good
1 : One or more pixels in the source segment was flagged

The psf_flags column contains the following bit flags defined by the photutils.psf.PSFPhotometry class:

0 : Good
1 : One or more pixels in the fit_shape region were masked
2 : The fitted source position is outside the bounds of the input image
4 : The fitted flux value is negative or zero
8 : The PSF fitting algorithm may not have converged to a stable solution
16 : Parameter covariance matrix is not available, preventing error estimation
32 : One or more fitted parameters are very close to their imposed bounds
64 : The source PSF fitting region has no overlap with valid data pixels
128 : All pixels in the source fitting region are masked
256 : Insufficient unmasked pixels available for reliable PSF fitting
512 : The fitted x or y position is NaN or inf, indicating an invalid or failed fit
1024 : The fitted flux value is NaN or inf, indicating an invalid or failed fit
2048 : The local background value is NaN or inf, so it was not subtracted before fitting

Output Products

Source Catalog Table

The output source catalog table is saved to a file in the Parquet format.

Segmentation Map

The segmentation map generated during the source-finding process is saved as an ASDF file. Each pixel in the image contains an integer value corresponding to a source label in the source catalog. Pixels that do not belong to any source are assigned a value of zero.

When sources are detected, the segmentation output also includes the following keys, which are needed to make forced source catalogs:

detection_image: The detection image used to measure the source positions and shapes. This is the convolved, background-subtracted image, or the multiband detection image for multiband catalogs.
detection_image_unit: A string giving the unit of detection_image ("nJy").

For L2 imaging products, when compute_skyvals=True (default), the segmentation output also includes skyvals and healpix11_cov arrays containing HEALPix-based sky summary values for downstream sky-matching workflows.

Multiband Catalogs

Multiband catalogs combine multiple images to create a deep detection image, which is used to detect sources and identify segments. The measured positions and shapes of the sources in these deep images are then used to perform aperture, Kron, isophotal, and PSF photometry for each filter.

The catalog fields are similar to those in the source catalog schema, but with the following differences:

Fields derived from individual filter images include the filter name from which they were derived. For example, fields like aper_flux_<filter>, segment_flux_<filter>, kron_flux_<filter>, and psf_flux_<filter> provide the aperture and PSF flux for each filter, respectively.
Fields derived from the detection image and segmentation map do not include the filter name.

Multiband catalogs are generated by the MultibandCatalogStep, which takes an association file as input. This file lists the images that need to be photometered simultaneously.

Forced Source Catalogs

Source catalogs can optionally be generated by using the segmentation image from one image (the “forcing” image) and computing shapes and fluxes for those same segments in another image (the “forced” image). For this to work, the two images must be perfectly aligned in pixel space.

Forced source catalogs can be generated by specifying a segmentation image with the forced_segmentation keyword when running the source catalog step.

The segmentation file must contain the detection_image array when it has sources. If the file has no detection_image_unit key, which is the case for files made by earlier versions of the pipeline, the detection image from a source catalog step file is assumed to be in nJy and a warning is logged. The detection image from a multiband catalog step file is assumed to be in the units of the input images. If the forcing segmentation has no sources, forced photometry returns an empty catalog.

In this mode, the source catalog contains fields with the forced prefix, in addition to the fields described above. Fields without the “forced” prefix contain position and shape information derived from the forcing image, indicating where measurements were taken on the forced image. Fields with the forced prefix represent values computed on the forced image, using the information from the forcing image. For example, the field forced_kron_flux represents the Kron flux measured on the forced image, using the centroid and shape information from the x_centroid, y_centroid, semimajor, semiminor, and orientation_pix fields.