GNU Astronomy Utilities

Previous: , Up: Match   [Contents][Index]

7.5.1 Invoking Match

When given two catalogs, Match finds the rows that are nearest to each other within an input aperture. The executable name is astmatch with the following general template

$ astmatch [OPTION ...] input-1 input-2

One line examples:

## 1D wavelength match (within 5 angstroms) of the two inputs.
## The wavelengths are in the 5th and 10th columns respectively.
$ astmatch --aperture=5e-10 --ccol1=5 --ccol2=10 in1.fits in2.txt

## Match the two catalogs with a circular aperture of width 2.
## (Units same as given positional columns).
## (By default two columns are given for `--ccol1' and `--ccol2',
##  The number of values to these determines the dimensions).
$ astmatch --aperture=2 input1.txt input2.fits

## Similar to before, but the output is created by merging various
## columns from the two inputs: columns 1, RA, DEC from the first
## input, followed by all columns starting with `MAG' and the `BRG'
## column from second input and finally the 10th from first input.
$ astmatch --aperture=2 input1.txt input2.fits                   \

## Match the two catalogs within an elliptical aperture of 1 and 2
## arcseconds along RA and Dec respectively.
$ astmatch --aperture=1/3600,2/3600 in1.fits in2.txt

## Match the RA and DEC columns of the first input with the RA_D
## and DEC_D columns of the second within a 0.5 arcseconds aperture.
$ astmatch --ccol1=RA,DEC --ccol2=RA_D,DEC_D --aperture=0.5/3600  \
           in1.fits in2.fits

Two inputs are necessary for Match to start processing. The inputs can be plain text tables or FITS tables, see Tables. If only one argument is provided, Match will assume look for the first input in Standard input (see Standard input).

Match follows the same basic behavior of all Gnuastro programs as fully described in Common program behavior. If the first input is a FITS file, the common --hdu option (see Input/Output options) should be used to identify the extension. When the second input is FITS, the extension must be specified with --hdu2.

When --quiet is not called, Match will print the number of matches found in standard output (on the command-line). When matches are found, by default, the output file(s) will be the re-arranged input tables such that the rows match each other: both output tables will have the same number of rows which are matched with each other. If --outcols is called, the output is a single table with rows chosen from either of the two inputs in any order, see the description of --outcols. If the --logasoutput option is called, the output will be a single table with the contents of the log file, see below. If no matches are found, the columns of the output table(s) will have zero rows (with proper meta-data).

If no output file name is given with the --output option, then automatic output Automatic output will be used to determine the output name(s). Depending on --tableformat (see Input/Output options), the output will then be a (possibly multi-extension) FITS file or (possibly two) plain text file(s). When the output is a FITS file, the default re-arranged inputs will be two extensions of the output FITS file. With --outcols and --logasoutput, the FITS output will be a single table (in one extension).

When the --log option is called (see Operating mode options), and there was a match, Match will also create a file named astmatch.fits (or astmatch.txt, depending on --tableformat, see Input/Output options) in the directory it is run in. This log table will have three columns. The first and second columns show the matching row/record number (counting from 1) of the first and second input catalogs respectively. The third column is the distance between the two matched positions. The units of the distance are the same as the given coordinates (given the possible ellipticity, see description of --aperture below). When --logasoutput is called, no log file (with a fixed name) will be created. In this case, the output file (possibly given by the --output option) will have the contents of this log file.

--log isn’t thread-safe: As described above, when --logasoutput is not called, the Log file has a fixed name for all calls to Match. Therefore if a separate log is requested in two simultaneous calls to Match in the same directory, Match will try to write to the same file. This will cause problems like unreasonable log file, undefined behavior, or a crash.


The extension/HDU of the second input if it is a FITS file. When it isn’t a FITS file, this option’s value is ignored. For the first input, the common option --hdu must be used.


Columns from both inputs to write into a single matched table output. The value to --outcols must be a comma-separated list of strings, for example --outcols=a1,bRA,bDEC. The first character of each string specifies the input catalog: a for the first and b for the second. The rest of the characters of the string will be directly used to identify the proper column(s) in the respective table. See Selecting table columns for how columns can be specified in Gnuastro. In this example, the output will have three columns: the first column of the first input and the RA and DEC columns of the second input.

Another example is given in the one-line examples above. Compared to the default case (where two tables with all their columns) are printed, using this option is much faster: it will only read and re-arrange the necessary columns and it will write a single output table. Combined with regular expressions in large tables, this can be a very powerful and convenient way to retrieve your desired information and do the match at the same time.


The output file will have the contents of the log file: indexes in the two catalogs that match with each other along with their distance. See description above. When this option is called, a log file called astmatch.txt will not be created. With this option, the default output behavior (two tables containing the re-arranged inputs) will be


Write the non-matching rows into the outputs, not the matched ones. Note that with this option, the two output tables will not necessarily have the same number of rows. Therefore, this option cannot be called with --outcols. --outcols prints mixed columns from both inputs, so they must all have the same number of elements and must correspond to each other.


The coordinate columns of the first input. The number of dimensions for the match is determined by the number of comma-separated values given to this option. The values can be the column number (counting from 1), exact column name or a regular expression. For more, see Selecting table columns. See the one-line examples above for some usages of this option.


The coordinate columns of the second input. See the example in --ccol1 for more.

-a FLT[,FLT[,FLT]]

Parameters of the aperture for matching. The values given to this option can be fractions, for example when the position columns are in units of degrees, 1/3600 can be used to ask for one arcsecond. The interpretation of the values depends on the requested dimensions (determined from --ccol1 and --ccol2) and how many values are given to this option.

1D match

The aperture/interval can only take one value: half of the interval around each point (maximum distance from each point).

2D match

In a 2D match, the aperture can be a circle, an ellipse aligned in the axes or an ellipse with a rotated major axis. To simply the usage, you can determine the shape based on the number of free parameters for each.

1 number

For example --aperture=2. The aperture will be a circle of the given radius. The value will be in the same units as the columns in --ccol1 and --ccol2).

2 numbers

For example --aperture=3,4e-10. The aperture will be an ellipse (if the two numbers are different) with the respective value along each dimension. The numbers are in units of the first and second axis. In the example above, the semi-axis value along the first axis will be 3 (in units of the first coordinate) and along the second axis will be \(4\times10^{-10}\) (in units of the second coordinate). Such values can happen if you are comparing catalogs of a spectra for example. If more than one object exists in the aperture, the nearest will be found along the major axis as described in Defining an ellipse.

3 numbers

For example --aperture=2,0.6,30. The aperture will be an ellipse (if the second value is not 1). The first number is the semi-major axis, the second is the axis ratio and the third is the position angle (in degrees). If multiple matches are found within the ellipse, the distance (to find the nearest) is calculated along the major axis in the elliptical space, see Defining an ellipse.

Previous: , Up: Match   [Contents][Index]