GNU Astronomy Utilities

7.4 MakeCatalog

At the lowest level, a dataset (for example, an image) is just a collection of values, placed after each other in any number of dimensions (for example, an image is a 2D dataset). Each data-element (pixel) just has two properties: its position (relative to the rest) and its value. In higher-level analysis, an entire dataset (an image for example) is rarely treated as a singular entity205. You usually want to know/measure the properties of the (separate) scientifically interesting targets that are embedded in it. For example, the magnitudes, positions and elliptical properties of the galaxies that are in the image.

MakeCatalog is Gnuastro’s program for localized measurements over a dataset. In other words, MakeCatalog is Gnuastro’s program to convert low-level datasets (like images), to high level catalogs. The role of MakeCatalog in a scientific analysis and the benefits of its model (where detection/segmentation is separated from measurement) is discussed in Akhlaghi 2016206 and summarized in Detection and catalog production. We strongly recommend reading this short paper for a better understanding of this methodology. Understanding the effective usage of MakeCatalog, will thus also help effective use of other (lower-level) Gnuastro’s programs like NoiseChisel or Segment.

It is important to define your regions of interest for measurements before running MakeCatalog. MakeCatalog is specialized in doing measurements accurately and efficiently. Therefore MakeCatalog will not do detection, segmentation, or defining apertures on requested positions in your dataset. Following Gnuastro’s modularity principle, there are separate and highly specialized and customizable programs in Gnuastro for these other jobs as shown below (for a usage example in a real-world analysis, see General program usage tutorial and Detecting large extended targets).

These programs will/can return labeled dataset(s) to be fed into MakeCatalog. A labeled dataset for measurement has the same size/dimensions as the input, but with integer valued pixels that have the label/counter for each sub-set of pixels that must be measured together. For example, all the pixels covering one galaxy in an image, get the same label.

The requested measurements are then done on similarly labeled pixels. The final result is a catalog where each row corresponds to the measurements on pixels with a specific label. For example, the flux weighted average position of all the pixels with a label of 42 will be written into the 42nd row of the output catalog/table’s central position column207. Similarly, the sum of all these pixels will be the 42nd row in the sum column, etc. Pixels with labels equal to, or smaller than, zero will be ignored by MakeCatalog. In other words, the number of rows in MakeCatalog’s output is already known before running it (the maximum value of the labeled dataset).

Before getting into the details of running MakeCatalog (in Invoking MakeCatalog, we will start with a discussion on the basics of its approach to separating detection from measurements in Detection and catalog production. A very important factor in any measurement is understanding its validity range, or limits. Therefore in Quantifying measurement limits, we will discuss how to estimate the reliability of the detection and basic measurements. This section will continue with a derivation of elliptical parameters from the labeled datasets in Measuring elliptical parameters. For those who feel MakeCatalog’s existing measurements/columns are not enough and would like to add further measurements, in Adding new columns to MakeCatalog, a checklist of steps is provided for readily adding your own new measurements/columns.



You can derive the over-all properties of a complete dataset (1D table column, 2D image, or 3D data-cube) treated as a single entity with Gnuastro’s Statistics program (see Statistics).


A published paper cannot undergo any more change, so this manual is the definitive guide.


See Measuring elliptical parameters for a discussion on this and the derivation of positional parameters, which includes the center.