---

7.4.7.3 MakeCatalog output ¶

After it has completed all the requested measurements (see MakeCatalog measurements), MakeCatalog will store its measurements in table(s). If an output filename is given (see --output in Input/Output options), the format of the table will be deduced from the name. When it is not given, the input name will be appended with a _cat suffix (see Automatic output) and its format will be determined from the --tableformat option, which is also discussed in Input/Output options. --tableformat is also necessary when the requested output name is a FITS table (recall that FITS can accept ASCII and binary tables, see Table).

By default (when --spectrum or --clumpscat are not called) only a single catalog/table will be created for the labeled “objects”.

• if --clumpscat is called, a secondary catalog/table will also be created for “clumps” (one of the outputs of the Segment program, for more on “objects” and “clumps”, see Segment). In short, if you only have one labeled image, you do not have to worry about clumps and just ignore this.
• When --spectrum is called, it is not mandatory to specify any single-valued measurement columns. In this case, the output will only be the spectra of each labeled region within a 3D data cube. For more, see the description of --spectrum in MakeCatalog measurements.

When possible, MakeCatalog will also measure the full input’s noise level (also known as surface brightness limit, see Quantifying measurement limits). Since these measurements are related to the noise and not any particular labeled object, they are stored as keywords in the output table. Furthermore, they are only possible when a standard deviation image has been loaded (done automatically for any column measurement that involves noise, for example, --sn, --magnitude-error or --sky-std). But if you just want the surface brightness limit and no noise-related column, you can use --forcereadstd. All these keywords start with SBL (for “surface brightness limit”) and are described below:

SBLSTD

Per-pixel standard deviation. If a MEDSTD keyword exists in the standard deviation dataset, then that value is directly used.

SBLNSIG

Sigma multiple for surface brightness limit (value you gave to --sfmagnsigma), used for SBLMAGPX and SBLMAG.

SBLMAGPX

Per-pixel surface brightness limit (in units of magnitudes/pixel).

SBLAREA

Area (in units of arcsec\(^2\)) used in SBLMAG (value you gave to --sfmagarea).

SBLMAG

Surface brightness limit of data calculated over SBLAREA (in units of mag/arcsec\(^2\)).

When any of the upper-limit measurements are requested, the input parameters for the upper-limit measurement are stored in the keywords starting with UP: UPNSIGMA, UPNUMBER, UPRNGNAM, UPRNGSEE, UPSCMLTP, UPSCTOL. These are primarily input arguments, so they correspond to the options with a similar name.

The full list of MakeCatalog’s options relating to the output file format and keywords are listed below. See MakeCatalog measurements for specifying which columns you want in the final catalog.

-C

--clumpscat

Do measurements on clumps and produce a second catalog (only devoted to clumps). When this option is given, MakeCatalog will also look for a secondary labeled dataset (identifying substructure) and produce a catalog from that. For more on the definition on “clumps”, see Segment.

When the output is a FITS file, the objects and clumps catalogs/tables will be stored as multiple extensions of one FITS file. You can use Table to inspect the column meta-data and contents in this case. However, in plain text format (see Gnuastro text table format), it is only possible to keep one table per file. Therefore, if the output is a text file, two output files will be created, ending in _o.txt (for objects) and _c.txt (for clumps).

--noclumpsort

Do not sort the clumps catalog based on object ID (only relevant with --clumpscat). This option will benefit the performance²²⁵ of MakeCatalog when it is run on multiple threads and the position of the rows in the clumps catalog is irrelevant (for example, you just want the number-counts).

MakeCatalog does all its measurements on each object independently and in parallel. As a result, while it is writing the measurements on each object’s clumps, it does not know how many clumps there were in previous objects. Each thread will just fetch the first available row and write the information of clumps (in order) starting from that row. After all the measurements are done, by default (when this option is not called), MakeCatalog will reorder/permute the clumps catalog to have both the object and clump ID in an ascending order.

If you would like to order the catalog later (when it is a plain text file), you can run the following command to sort the rows by object ID (and clump ID within each object), assuming they are respectively the first and second columns:

$ awk '!/^#/' out_c.txt | sort -g -k1,1 -k2,2

--sfmagnsigma=FLT

Value to multiply with the median standard deviation (from a MEDSTD keyword in the Sky standard deviation image) for estimating the surface brightness limit. Note that the surface brightness limit is only reported when a standard deviation image is read, in other words a column using it is requested (for example, --sn) or --forcereadstd is called.

This value is a per-pixel value, not per object/clump and is not found over an area or aperture, like the common \(5\sigma\) values that are commonly reported as a measure of depth or the upper-limit measurements (see Quantifying measurement limits).

--sfmagarea=FLT

Area (in arc-seconds squared) to convert the per-pixel estimation of --sfmagnsigma in the comments section of the output tables. Note that the surface brightness limit is only reported when a standard deviation image is read, in other words a column using it is requested (for example, --sn) or --forcereadstd is called.

Note that this is just a unit conversion using the World Coordinate System (WCS) information in the input’s header. It does not actually do any measurements on this area. For random measurements on any area, please use the upper-limit columns of MakeCatalog (see the discussion on upper-limit measurements in Quantifying measurement limits).