GNU Astronomy Utilities


Next: , Previous: , Up: Invoking MakeCatalog   [Contents][Index]


7.4.6.3 MakeCatalog measurements

The final group of options particular to MakeCatalog are those that specify which measurements/columns should be written into the final output table. The current measurements in MakeCatalog are those which only produce one final value for each label (for example, its total brightness: a single number). All the different label’s measurements can be written as one column in a final table/catalog that contains other columns for other similar single-number measurements.

In this case, all the different label’s measurements can be written as one column in a final table/catalog that contains other columns for other similar single-number measurements. The majority of this section is devoted to MakeCatalog’s single-valued measurements. However, MakeCatalog can also do measurements that produce more than one value for each label. Currently the only such measurement is generation of spectra from 3D cubes with the --spectrum option and it is discussed in the end of this section.

Command-line options are used to identify which measurements you want in the final catalog(s) and in what order. If any of the options below is called on the command line or in any of the configuration files, it will be included as a column in the output catalog. The order of the columns is in the same order as the options were seen by MakeCatalog (see Configuration file precedence). Some of the columns apply to both “objects” and “clumps” and some are particular to only one of them (for the definition of “objects” and “clumps”, see Segment). Columns/options that are unique to one catalog (only objects, or only clumps), are explicitly marked with [Objects] or [Clumps] to specify the catalog they will be placed in.

--i
--ids

This is a unique option which can add multiple columns to the final catalog(s). Calling this option will put the object IDs (--objid) in the objects catalog and host-object-ID (--hostobjid) and ID-in-host-object (--idinhostobj) into the clumps catalog. Hence if only object catalogs are required, it has the same effect as --objid.

--objid

[Objects] ID of this object.

-j
--hostobjid

[Clumps] The ID of the object which hosts this clump.

--idinhostobj

[Clumps] The ID of this clump in its host object.

-x
--x

The flux weighted center of all objects and clumps along the first FITS axis (horizontal when viewed in SAO DS9), see \(\overline{x}\) in Measuring elliptical parameters. The weight has to have a positive value (pixel value larger than the Sky value) to be meaningful! Specially when doing matched photometry, this might not happen: no pixel value might be above the Sky value. For such detections, the geometric center will be reported in this column (see --geox). You can use --weightarea to see which was used.

-y
--y

The flux weighted center of all objects and clumps along the second FITS axis (vertical when viewed in SAO DS9). See --x.

-z
--z

The flux weighted center of all objects and clumps along the third FITS axis. See --x.

--geox

The geometric center of all objects and clumps along the first FITS axis axis. The geometric center is the average pixel positions irrespective of their pixel values.

--geoy

The geometric center of all objects and clumps along the second FITS axis axis, see --geox.

--geoz

The geometric center of all objects and clumps along the third FITS axis axis, see --geox.

--minvx

Position of pixel with minimum value in objects and clumps, along the first FITS axis.

--maxvx

Position of pixel with maximum value in objects and clumps, along the first FITS axis.

--minvy

Position of pixel with minimum value in objects and clumps, along the first FITS axis.

--maxvy

Position of pixel with maximum value in objects and clumps, along the first FITS axis.

--minvz

Position of pixel with minimum value in objects and clumps, along the first FITS axis.

--maxvz

Position of pixel with maximum value in objects and clumps, along the first FITS axis.

--minx

The minimum position of all objects and clumps along the first FITS axis.

--maxx

The maximum position of all objects and clumps along the first FITS axis.

--miny

The minimum position of all objects and clumps along the second FITS axis.

--maxy

The maximum position of all objects and clumps along the second FITS axis.

--minz

The minimum position of all objects and clumps along the third FITS axis.

--maxz

The maximum position of all objects and clumps along the third FITS axis.

--clumpsx

[Objects] The flux weighted center of all the clumps in this object along the first FITS axis. See --x.

--clumpsy

[Objects] The flux weighted center of all the clumps in this object along the second FITS axis. See --x.

--clumpsz

[Objects] The flux weighted center of all the clumps in this object along the third FITS axis. See --x.

--clumpsgeox

[Objects] The geometric center of all the clumps in this object along the first FITS axis. See --geox.

--clumpsgeoy

[Objects] The geometric center of all the clumps in this object along the second FITS axis. See --geox.

--clumpsgeoz

[Objects] The geometric center of all the clumps in this object along the third FITS axis. See --geoz.

-r
--ra

Flux weighted right ascension of all objects or clumps, see --x. This is just an alias for one of the lower-level --w1 or --w2 options. Using the FITS WCS keywords (CTYPE), MakeCatalog will determine which axis corresponds to the right ascension. If no CTYPE keywords start with RA, an error will be printed when requesting this column and MakeCatalog will abort.

-d
--dec

Flux weighted declination of all objects or clumps, see --x. This is just an alias for one of the lower-level --w1 or --w2 options. Using the FITS WCS keywords (CTYPE), MakeCatalog will determine which axis corresponds to the declination. If no CTYPE keywords start with DEC, an error will be printed when requesting this column and MakeCatalog will abort.

--w1

Flux weighted first WCS axis of all objects or clumps, see --x. The first WCS axis is commonly used as right ascension in images.

--w2

Flux weighted second WCS axis of all objects or clumps, see --x. The second WCS axis is commonly used as declination in images.

--w3

Flux weighted third WCS axis of all objects or clumps, see --x. The third WCS axis is commonly used as wavelength in integral field unit data cubes.

--geow1

Geometric center in first WCS axis of all objects or clumps, see --geox. The first WCS axis is commonly used as right ascension in images.

--geow2

Geometric center in second WCS axis of all objects or clumps, see --geox. The second WCS axis is commonly used as declination in images.

--geow3

Geometric center in third WCS axis of all objects or clumps, see --geox. The third WCS axis is commonly used as wavelength in integral field unit data cubes.

--clumpsw1

[Objects] Flux weighted center in first WCS axis of all clumps in this object, see --x. The first WCS axis is commonly used as right ascension in images.

--clumpsw2

[Objects] Flux weighted declination of all clumps in this object, see --x. The second WCS axis is commonly used as declination in images.

--clumpsw3

[Objects] Flux weighted center in third WCS axis of all clumps in this object, see --x. The third WCS axis is commonly used as wavelength in integral field unit data cubes.

--clumpsgeow1

[Objects] Geometric center right ascension of all clumps in this object, see --geox. The first WCS axis is commonly used as right ascension in images.

--clumpsgeow2

[Objects] Geometric center declination of all clumps in this object, see --geox. The second WCS axis is commonly used as declination in images.

--clumpsgeow3

[Objects] Geometric center in third WCS axis of all clumps in this object, see --geox. The third WCS axis is commonly used as wavelength in integral field unit data cubes.

-b
--brightness

The brightness (sum of all pixel values), see Brightness, Flux, Magnitude and Surface brightness. For clumps, the ambient brightness (flux of river pixels around the clump multiplied by the area of the clump) is removed, see --riverave. So the sum of all the clumps brightness in the clump catalog will be smaller than the total clump brightness in the --clumpbrightness column of the objects catalog.

If no usable pixels are present over the clump or object (for example, they are all blank), the returned value will be NaN (note that zero is meaningful).

--brightnesserr

The (\(1\sigma\)) error in measuring the brightness of a label (objects or clumps).

The returned value will be NaN when the label covers only NaN pixels in the values image, or a pixel is NaN in the --instd image, but non-NaN in the values image. The latter situation usually happens when there is a bug in the previous steps of your analysis, and is important because those pixels with a NaN in the --instd image may contribute significantly to the final error. If you want to ignore those pixels in the error measurement, set them to zero (which is a meaningful number in such scenarios).

--clumpbrightness

[Objects] The total brightness of the clumps within an object. This is simply the sum of the pixels associated with clumps in the object. If no usable pixels are present over the clump or object (for example, they are all blank), the stored value will be NaN (note that zero is meaningful).

--brightnessnoriver

[Clumps] The Sky (not river) subtracted clump brightness. By definition, for the clumps, the average brightness of the rivers surrounding it are subtracted from it for a first order accounting for contamination by neighbors. In cases where you will be calculating the flux brightness difference later (one example below) the contamination will be (mostly) removed at that stage, which is why this column was added.

If no usable pixels are present over the clump or object (for example, they are all blank), the stored value will be NaN (note that zero is meaningful).

--mean

The mean sky subtracted value of pixels within the object or clump. For clumps, the average river flux is subtracted from the sky subtracted mean.

--std

The standard deviation of the pixels within the object or clump. For clumps, the river pixels are not subtracted because that is a constant (per pixel) value and should not affect the standard deviation.

--median

The median sky subtracted value of pixels within the object or clump. For clumps, the average river flux is subtracted from the sky subtracted median.

--maximum

The maximum value of pixels within the object or clump. When the label (object or clump) is larger than three pixels, the maximum is actually derived by the mean of the brightest three pixels, not the largest pixel value of the same label. This is because noise fluctuations can be very strong in the extreme values of the objects/clumps due to Poisson noise (which gets stronger as the mean gets higher). Simply using the maximum pixel value will create a strong scatter in results that depend on the maximum (for example, the --fwhm option also uses this value internally).

--sigclip-number

The number of elements/pixels in the dataset after sigma-clipping the object or clump. The sigma-clipping parameters can be set with the --sigmaclip option described in MakeCatalog inputs and basic settings. For more on Sigma-clipping, see Sigma clipping.

--sigclip-median

The sigma-clipped median value of the object of clump’s pixel distribution. For more on sigma-clipping and how to define it, see --sigclip-number.

--sigclip-mean

The sigma-clipped mean value of the object of clump’s pixel distribution. For more on sigma-clipping and how to define it, see --sigclip-number.

--sigclip-std

The sigma-clipped standard deviation of the object of clump’s pixel distribution. For more on sigma-clipping and how to define it, see --sigclip-number.

-m
--magnitude

The magnitude of clumps or objects, see --brightness.

-e
--magnitudeerr

The magnitude error of clumps or objects. The magnitude error is calculated from the signal-to-noise ratio (see --sn and Quantifying measurement limits). Note that until now this error assumes uncorrelated pixel values and also does not include the error in estimating the aperture (or error in generating the labeled image).

For now these factors have to be found by other means. Task 14124 has been defined for work on adding these sources of error too.

The returned value will be NaN when the label covers only NaN pixels in the values image, or a pixel is NaN in the --instd image, but non-NaN in the values image. The latter situation usually happens when there is a bug in the previous steps of your analysis, and is important because those pixels with a NaN in the --instd image may contribute significantly to the final error. If you want to ignore those pixels in the error measurement, set them to zero (which is a meaningful number in such scenarios).

--clumpsmagnitude

[Objects] The magnitude of all clumps in this object, see --clumpbrightness.

--upperlimit

The upper limit value (in units of the input image) for this object or clump. This is the sigma-clipped standard deviation of the random distribution, multiplied by the value of --upnsigma). See Quantifying measurement limits and Upper-limit settings for a complete explanation. This is very important for the fainter and smaller objects in the image where the measured magnitudes are not reliable.

--upperlimitmag

The upper limit magnitude for this object or clump. See Quantifying measurement limits and Upper-limit settings for a complete explanation. This is very important for the fainter and smaller objects in the image where the measured magnitudes are not reliable.

--upperlimitsb

The upper-limit surface brightness (in units of mag/arcsec\(^2\)) of this labeled region (object or clump). This is just a simple wrapper over lower-level columns: setting B and A as the value in the columns --upperlimit and --areaarcsec2, we fill this column by simply use the surface brightness equation of Brightness, Flux, Magnitude and Surface brightness.

--upperlimitonesigma

The \(1\sigma\) upper limit value (in units of the input image) for this object or clump. See Quantifying measurement limits and Upper-limit settings for a complete explanation. When --upnsigma=1, this column’s values will be the same as --upperlimit.

--upperlimitsigma

The position of the total brightness measured within the distribution of randomly placed upperlimit measurements in units of the distribution’s \(\sigma\) or standard deviation. See Quantifying measurement limits and Upper-limit settings for a complete explanation.

--upperlimitquantile

The position of the total brightness measured within the distribution of randomly placed upperlimit measurements as a quantile (value between 0 or 1). See Quantifying measurement limits and Upper-limit settings for a complete explanation. If the object is brighter than the brightest randomly placed profile, a value of inf is returned. If it is less than the minimum, a value of -inf is reported.

--upperlimitskew

This column contains the non-parametric skew of the \(\sigma\)-clipped random distribution that was used to estimate the upper-limit magnitude. Taking \(\mu\) as the mean, \(\nu\) as the median and \(\sigma\) as the standard deviation, the traditional definition of skewness is defined as: \((\mu-\nu)/\sigma\).

This can be a good measure to see how much you can trust the random measurements, or in other words, how accurately the regions with signal have been masked/detected. If the skewness is strong (and to the positive), then you can tell that you have a lot of undetected signal in the dataset, and therefore that the upper-limit measurement (and other measurements) are not reliable.

--riverave

[Clumps] The average brightness of the river pixels around this clump. River pixels were defined in Akhlaghi and Ichikawa 2015. In short they are the pixels immediately outside of the clumps. This value is used internally to find the brightness (or magnitude) and signal to noise ratio of the clumps. It can generally also be used as a scale to gauge the base (ambient) flux surrounding the clump. In case there was no river pixels, then this column will have the value of the Sky under the clump. So note that this value is not sky subtracted.

--rivernum

[Clumps] The number of river pixels around this clump, see --riverave.

-n
--sn

The Signal to noise ratio (S/N) of all clumps or objects. See Akhlaghi and Ichikawa (2015) for the exact equations used.

The returned value will be NaN when the label covers only NaN pixels in the values image, or a pixel is NaN in the --instd image, but non-NaN in the values image. The latter situation usually happens when there is a bug in the previous steps of your analysis, and is important because those pixels with a NaN in the --instd image may contribute significantly to the final error. If you want to ignore those pixels in the error measurement, set them to zero (which is a meaningful number).

--sky

The sky flux (per pixel) value under this object or clump. This is actually the mean value of all the pixels in the sky image that lie on the same position as the object or clump.

--skystd

The sky value standard deviation (per pixel) for this clump or object. This is the square root of the mean variance under the object, or the root mean square.

-C
--numclumps

[Objects] The number of clumps in this object.

-a
--area

The raw area (number of pixels/voxels) in any clump or object independent of what pixel it lies over (if it is NaN/blank or unused for example).

--areaarcsec2

The used (non-blank in values image) area of the labeled region in units of arc-seconds squared. This column is just the value of the --area column, multiplied by the area of each pixel in the input image (in units of arcsec^2). Similar to the --ra or --dec columns, for this option to work, the objects extension used has to have a WCS structure.

--areaminv

The number of pixels that are equal to the minimum value of the labeled region (clump or object).

--areamaxv

The number of pixels that are equal to the maximum value of the labeled region (clump or object).

--surfacebrightness

The surface brightness (in units of mag/arcsec\(^2\)) of the labeled region (objects or clumps). For more on the definition of the surface brightness, see Brightness, Flux, Magnitude and Surface brightness.

--sberror

Error in measuring the surface brightness (the --surfacebrightness column). This column will use the value given to --spatialresolution in the processing (in pixels). For more on --spatialresolution, see MakeCatalog inputs and basic settings and for the equation used to derive the surface brightness error, see Surface brightness error of each detection.

--areaxy

Similar to --area, when the clump or object is projected onto the first two dimensions. This is only available for 3-dimensional datasets. When working with Integral Field Unit (IFU) datasets, this projection onto the first two dimensions would be a narrow-band image.

--fwhm

The full width at half maximum (in units of pixels, along the semi-major axis) of the labeled region (object or clump). The maximum value is estimated from the mean of the top-three pixels with the highest values, see the description under --maximum. The number of pixels that have half the value of that maximum are then found (value in the --halfmaxarea column) and a radius is estimated from the area. See the description under --halfsumradius for more on converting area to radius along major axis.

Because of its non-parametric nature, this column is most reliable on clumps and should only be used in objects with great caution. This is because objects can have more than one clump (peak with true signal) and multiple peaks are not treated separately in objects, so the result of this column will be biased.

Also, because of its non-parametric nature, this FWHM it does not account for the PSF, and it will be strongly affected by noise if the object is faint/diffuse So when half the maximum value (which can be requested using the --maximum column) is too close to the local noise level (which can be requested using the --skystd column), the value returned in this column is meaningless (its just noise peaks which are randomly distributed over the area). You can therefore use the --maximum and --skystd columns to remove, or flag, unreliable FWHMs. for example, if a labeled region’s maximum is less than 2 times the sky standard deviation, the value will certainly be unreliable (half of that is \(1\sigma\)!). For a more reliable value, this fraction should be around 4 (so half the maximum is 2\(\sigma\)).

--halfmaxarea

The number of pixels with values larger than half the maximum flux within the labeled region. This option is used to estimate --fwhm, so please read the notes there for the caveats and necessary precautions.

--halfmaxradius

The radius of region containing half the maximum flux within the labeled region. This is just half the value reported by --fwhm.

--halfmaxsum

The sum of the pixel values containing half the maximum flux within the labeled region (or those that are counted in --halfmaxarea). This option uses the pixels within --fwhm, so please read the notes there for the caveats and necessary precautions.

--halfmaxsb

The surface brightness (in units of mag/arcsec\(^2\)) within the region that contains half the maximum value of the labeled region. For more on the definition of the surface brightness, see Brightness, Flux, Magnitude and Surface brightness.

--halfsumarea

The number of pixels that contain half the object or clump’s total sum of pixels (half the value in the --brightness column). To count this area, all the non-blank values associated with the given label (object or clump) will be sorted and summed in order (starting from the maximum), until the sum becomes larger than half the total sum of the label’s pixels.

This option is thus good for clumps (which are defined to have a single peak in their morphology), but for objects you should be careful: if the object includes multiple peaks/clumps at roughly the same level, then the area reported by this option will be distributed over all the peaks.

--halfsumsb

Surface brightness (in units of mag/arcsec\(^2\)) within the area that contains half the total sum of the label’s pixels (object or clump). For more on the definition of the surface brightness, see Brightness, Flux, Magnitude and Surface brightness.

This column just plugs in the values of half the value of the --brightness column and the --halfsumarea column, into the surface brightness equation. Therefore please see the description in --halfsumarea to understand the systematics of this column and potential biases.

--halfsumradius

Radius (in units of pixels) derived from the area that contains half the total sum of the label’s pixels (value reported by --halfsumarea). If the area is \(A_h\) and the axis ratio is \(q\), then the value returned in this column is \(\sqrt{A_h/({\pi}q)}\). This option is a good measure of the concentration of the observed (after PSF convolution and noisy) object or clump, But as described below it underestimates the effective radius. Also, it should be used in caution with objects that may have multiple clumps. It is most reliable with clumps or objects that have one or zero clumps, see the note under --halfsumarea.

Recall that in general, for an ellipse with semi-major axis \(a\), semi-minor axis \(b\), and axis ratio \(q=b/a\) the area (\(A\)) is \(A={\pi}ab={\pi}qa^2\). For a circle (where \(q=1\)), this simplifies to the familiar \(A={\pi}a^2\).

This option should not be confused with the effective radius for Sérsic profiles, commonly written as \(r_e\). For more on the Sérsic profile and \(r_e\), please see Galaxies. Therefore, when \(r_e\) is meaningful for the target (the target is elliptically symmetric and can be parameterized as a Sérsic profile), \(r_e\) should be derived from fitting the profile with a Sérsic function which has been convolved with the PSF. But from the equation above, you see that this radius is derived from the raw image’s labeled values (after convolution, with no parametric profile), so this column’s value will generally be (much) smaller than \(r_e\), depending on the PSF, depth of the dataset, the morphology, or if a fraction of the profile falls on the edge of the image.

In other words, this option can only be interpreted as an effective radius if there is no noise and no PSF and the profile within the image extends to infinity (or a very large multiple of the effective radius) and it not near the edge of the image.

--fracmaxarea1
--fracmaxarea2

Number of pixels brighter than the given fraction(s) of the maximum pixel value. For the maximum value, see the description of --maximum column. The fraction(s) are given through the --fracmax option (that can take two values) and is described in MakeCatalog inputs and basic settings. Recall that in --halfmaxarea, the fraction is fixed to 0.5. Hence, added with these two columns, you can sample three parts of the profile area.

--fracmaxsum1
--fracmaxsum2

Sum of pixels brighter than the given fraction(s) of the maximum pixel value. For the maximum value, see the description of --maximum column below. The fraction(s) are given through the --fracmax option (that can take two values) and is described in MakeCatalog inputs and basic settings. Recall that in --halfmaxsum, the fraction is fixed to 0.5. Hence, added with these two columns, you can sample three parts of the profile’s sum of pixels.

--fracmaxradius1
--fracmaxradius2

Radius (in units of pixels) derived from the area that contains the given fractions of the maximum valued pixel(s) of the label’s pixels (value reported by --fracmaxarea1 or --fracmaxarea2). For the maximum value, see the description of --maximum column below. The fractions are given through the --fracmax option (that can take two values) and is described in MakeCatalog inputs and basic settings. Recall that in --fwhm, the fraction is fixed to 0.5. Hence, added with these two columns, you can sample three parts of the profile’s radius.

--clumpsarea

[Objects] The total area of all the clumps in this object.

--weightarea

The area (number of pixels) used in the flux weighted position calculations.

--geoarea

The area of all the pixels labeled with an object or clump. Note that unlike --area, pixel values are completely ignored in this column. For example, if a pixel value is blank, it will not be counted in --area, but will be counted here.

--geoareaxy

Similar to --geoarea, when the clump or object is projected onto the first two dimensions. This is only available for 3-dimensional datasets. When working with Integral Field Unit (IFU) datasets, this projection onto the first two dimensions would be a narrow-band image.

-A
--semimajor

The pixel-value weighted root mean square (RMS) along the semi-major axis of the profile (assuming it is an ellipse) in units of pixels. See Measuring elliptical parameters.

-B
--semiminor

The pixel-value weighted root mean square (RMS) along the semi-minor axis of the profile (assuming it is an ellipse) in units of pixels. See Measuring elliptical parameters.

--axisratio

The pixel-value weighted axis ratio (semi-minor/semi-major) of the object or clump.

-p
--positionangle

The pixel-value weighted angle of the semi-major axis with the first FITS axis in degrees. See Measuring elliptical parameters.

--geosemimajor

The geometric (ignoring pixel values) root mean square (RMS) along the semi-major axis of the profile, assuming it is an ellipse, in units of pixels.

--geosemiminor

The geometric (ignoring pixel values) root mean square (RMS) along the semi-minor axis of the profile, assuming it is an ellipse, in units of pixels.

--geoaxisratio

The geometric (ignoring pixel values) axis ratio of the profile, assuming it is an ellipse.

--geopositionangle

The geometric (ignoring pixel values) angle of the semi-major axis with the first FITS axis in degrees.

Above, all of MakeCatalog’s single-valued measurements were listed. As mentioned in the start of this section, MakeCatalog can also do multi-valued measurements per label. Currently the only such measurement is the creation of spectra from 3D data cubes as discussed below:

--spectrum

Generate a spectrum (measurement along the first two FITS dimensions) for each label when the input dataset is a 3D data cube. With this option, a seprate table/spectrum will be generated for every label. If the output is a FITS file, each label’s spectrum will be written into an extension of that file with a standard name of SPECTRUM_NN (the label will be replaced with NN). If the output is a plain text file, each label’s spectrum will be written into a separate file with the suffix spec-NN.txt. See MakeCatalog output for more on specifying MakeCatalog’s output file.

The spectra will contain one row for every slice (third FITS dimension) of the cube. Since the physical nature of the third dimension is different, two types of spectra (along with their errors) are measured: 1) Sum of values in each slice that only have the requested label. 2) Sum of values on the 2D projection of the whole label (the area of this projection can be requested with the --areaxy column above).

Labels can overlap when they are projected onto the first two FITS dimensions (the spatial domain). To help separate them, MakeCatalog does a third measurement on each slice: the area, sum of values and error of all pixels that belong to other labels but overlap with the 2D projection. This can be used to see how reliable the emission line measurement is (on the projected spectra) and also if multiple lines (labeled regions) belong to the same physical object.

--inbetweenints

Output will contain one row for all integers between 1 and the largest label in the input (irrespective of their existance in the input image). By default, MakeCatalog’s output will only contain rows with integers that actually corresponded to at least one pixel in the input dataset.

for example, if the input’s only labeled pixel values are 11 and 13, MakeCatalog’s default output will only have two rows. If you use this option, it will have 13 rows and all the columns corresponding to integer identifiers that did not correspond to any pixel will be 0 or NaN (depending on context).


Next: MakeCatalog output, Previous: Upper-limit settings, Up: Invoking MakeCatalog   [Contents][Index]