---

7.4.5 Adding new columns to MakeCatalog ¶

MakeCatalog is designed to allow easy addition of different measurements over a labeled image; see Akhlaghi 2016. A check-list style description of necessary steps to do that is described in this section. The common development characteristics of MakeCatalog and other Gnuastro programs is explained in Developing. We strongly encourage you to have a look at that chapter to greatly simplify your navigation in the code. After adding and testing your column, you are most welcome (and encouraged) to share it with us so we can add to the next release of Gnuastro for everyone else to also benefit from your efforts.

MakeCatalog will first pass over each label’s pixels two times and do necessary raw/internal calculations. Once the passes are done, it will use the raw information for filling the final catalog’s columns. In the first pass it will gather mainly object information and in the second run, it will mainly focus on the clumps, or any other measurement that needs an output from the first pass. These two passes are designed to be raw summations: no extra processing. This will allow parallel processing and simplicity/clarity. So if your new calculation, needs new raw information from the pixels, then you will need to also modify the respective mkcatalog_first_pass and mkcatalog_second_pass functions (both in bin/mkcatalog/mkcatalog.c) and define new raw table columns in main.h (hopefully the comments in the code are clear enough).

In all these different places, the final columns are sorted in the same order (same order as Invoking MakeCatalog). This allows a particular column/option to be easily found in all steps. Therefore in adding your new option, be sure to keep it in the same relative place in the list in all the separate places (it does not necessarily have to be in the end), and near conceptually similar options.

main.h

The objectcols and clumpcols enumerated variables (enum) define the raw/internal calculation columns. If your new column requires new raw calculations, add a row to the respective list. If your calculation requires any other settings parameters, you should add a variable to the mkcatalogparams structure.

ui.c

If the new column needs raw calculations (an entry was added in objectcols and clumpcols), specify which inputs it needs in ui_necessary_inputs, similar to the other options. Afterwards, if your column includes any particular settings (you needed to add a variable to the mkcatalogparams structure in main.h), you should do the sanity checks and preparations for it here.

ui.h

The option_keys_enum associates a unique value for each option to MakeCatalog. The options that have a short option version, the single character short comment is used for the value. Those that do not have a short option version, get a large integer automatically. You should add a variable here to identify your desired column.

args.h ¶

This file specifies all the parameters for the GNU C library, Argp structure that is in charge of reading the user’s options. To define your new column, just copy an existing set of parameters and change the first, second and 5th values (the only ones that differ between all the columns), you should use the macro you defined in ui.h here.

columns.c

This file contains the main definition and high-level calculation of your new column through the columns_define_alloc and columns_fill functions. In the first, you specify the basic information about the column: its name, units, comments, type (see Numeric data types) and how it should be printed if the output is a text file. You should also specify the raw/internal columns that are necessary for this column here as the many existing examples show. Through the types for objects and rows, you can specify if this column is only for clumps, objects or both.

The second main function (columns_fill) writes the final value into the appropriate column for each object and clump. As you can see in the many existing examples, you can define your processing on the raw/internal calculations here and save them in the output.

mkcatalog.c

This file contains the low-level parsing functions. To be optimized, the parsing is done in parallel through the mkcatalog_single_object function. This function initializes the necessary arrays and calls the lower-level parse_objects and parse_clumps for actually going over the pixels. They are all heavily commented, so you should be able to follow where to add your necessary low-level calculations.

doc/gnuastro.texi

Update this manual and add a description for the new column.