(Created page with "__NOTOC__ === Synopsis === : grmatch [options] -r <reference> -i <input> [-o <output>] === Description === : The program `grmatch` matches lines read from two input files, na...") |
m (Apal moved page grmatch:synopsis to man/grmatch) |
||
(4 intermediate revisions by one user not shown) | |||
Line 43: | Line 43: | ||
: In all of the above input/output file specifications, the replacement of the file name by "-" (a single minus sign) forces the reading from stdin or writing to stdout. Note that all parts of the any line after "#" (hashmark) are treated as a comment, therefore ignored. | : In all of the above input/output file specifications, the replacement of the file name by "-" (a single minus sign) forces the reading from stdin or writing to stdout. Note that all parts of the any line after "#" (hashmark) are treated as a comment, therefore ignored. | ||
− | |||
=== General options for point matching: === | === General options for point matching: === | ||
Line 60: | Line 59: | ||
: See more options concerning to point matching in the section "Fine-Tuning of Point Matching" below. That section also describes the tuning of the triangulation used by the point matching algorithm. For a more detailed description about the point matching algorithms based on pattern and triangle matching see [1], [2] or [3]. | : See more options concerning to point matching in the section "Fine-Tuning of Point Matching" below. That section also describes the tuning of the triangulation used by the point matching algorithm. For a more detailed description about the point matching algorithms based on pattern and triangle matching see [1], [2] or [3]. | ||
− | |||
=== General options for coordinate matching: === | === General options for coordinate matching: === | ||
Line 72: | Line 70: | ||
: '''--max-distance''' <maxdist> | : '''--max-distance''' <maxdist> | ||
:: The maximal accepted distance between the matched points. Possible pairs (which are valid pairs due to the symmetric coordinate matching algorihms) are excluded if their Eucledian distance is larger than maxdist. Note that this option has no initial value, therefore, if omitted, all possible pairs due to the symmetric matching are resulted (see also point matching, above). | :: The maximal accepted distance between the matched points. Possible pairs (which are valid pairs due to the symmetric coordinate matching algorihms) are excluded if their Eucledian distance is larger than maxdist. Note that this option has no initial value, therefore, if omitted, all possible pairs due to the symmetric matching are resulted (see also point matching, above). | ||
− | |||
=== General options for identifier matching: === | === General options for identifier matching: === | ||
Line 79: | Line 76: | ||
:: This switch forces the usage of the identifier matching method. | :: This switch forces the usage of the identifier matching method. | ||
− | : '''--col-ref-id''' | + | : '''--col-ref-id''' <i>[,<j>,[<k>...]] '''--col-inp-id''' <i>[,<j>,[<k>...]] |
:: Column index or indices containing the identifiers, from the reference and from the input file, respectively. | :: Column index or indices containing the identifiers, from the reference and from the input file, respectively. | ||
: '''--no-ambiguity,''' '''--first-ambiguity,''' '''--any-ambiguity,''' '''--full-ambiguity''' | : '''--no-ambiguity,''' '''--first-ambiguity,''' '''--any-ambiguity,''' '''--full-ambiguity''' | ||
− | :: These options tune the behaviour of the matching when there is more than one occurrence of a given identifier in the reference and/or input file. If '''--no-ambiguity''' is specified, these identifiers are discarded, this is the default method. If '''--first-ambiguity''' is specified, only the first occurence is treated as a matched line, independently from the number of occurrences. If the switch '''--any-ambiguity''' is specified, the lines are paired sequentally, until there is any left from the reference and from the input. For example, if there is 4 occurrences in the reference and 6 in the input file of a given identifier, 4 matched pairs are returned. Otherwise, if '''--full-ambiguity''' is specified, all possible combinations of the lines are treated as matched lines. For example, if there is 4 occurrences in the reference and 6 in the input file of a given identifier, all 4*6=24 combinations are returned as matched pairs. | + | :: These options tune the behaviour of the matching when there is more than one occurrence of a given identifier in the reference and/or input file. If '''--no-ambiguity''' is specified, these identifiers are discarded, this is the default method. If '''--first-ambiguity''' is specified, only the first occurence is treated as a matched line, independently from the number of occurrences. If the switch '''--any-ambiguity''' is specified, the lines are paired sequentally, until there is any left from the reference and from the input. For example, if there is 4 occurrences in the reference and 6 in the input file of a given identifier, 4 matched pairs are returned. Otherwise, if '''--full-ambiguity''' is specified, all possible combinations of the lines are treated as matched lines. For example, if there is 4 occurrences in the reference and 6 in the input file of a given identifier, all 4*6=24 combinations are returned as matched pairs. |
=== Fine-tuning of point matching: === | === Fine-tuning of point matching: === | ||
Line 90: | Line 87: | ||
:: This switch is followed by comma-separated directives, which specify the parameters of the triangulation-based point matching algorithm: | :: This switch is followed by comma-separated directives, which specify the parameters of the triangulation-based point matching algorithm: | ||
− | : delaunay, level=<level>, full, auto, unitarity= | + | : delaunay, level=<level>, full, auto, unitarity=<U> |
:: These directives specify the triangulation level used for point matching. delaunay forces the usage only of the Delaunay-triangles. This is the fastest method, however, it is only working if the points in the reference and input lists are almost competely overlapping and describe almost the same point sets (within a ratio of common points above 60-70%). The level specifies the level of the expansion of the Delaunay-triangulation (see [1] for more details). In practice, the lower the ratio of common points and/or the ratio of the overlapping, the higher level should be used. Specifying level=1 or level=2 gives a robust but still fast method for general usage. The directive full forces full triangulation. This can be overwhelmingly slow and annoying and requires tons of memory if there are more than 40-50 points (the amounts of these resources are proportional to the 6th(!) and 3rd power of the number of the points, respectively). The directive auto increases the level of the triangulation expansion automatically until a proper match is found. A match is considered as a good match if the unitarity of the transformation is less than the unitarity U specified by the unitarity=U directive (see also the section Notes/Unitarity below). | :: These directives specify the triangulation level used for point matching. delaunay forces the usage only of the Delaunay-triangles. This is the fastest method, however, it is only working if the points in the reference and input lists are almost competely overlapping and describe almost the same point sets (within a ratio of common points above 60-70%). The level specifies the level of the expansion of the Delaunay-triangulation (see [1] for more details). In practice, the lower the ratio of common points and/or the ratio of the overlapping, the higher level should be used. Specifying level=1 or level=2 gives a robust but still fast method for general usage. The directive full forces full triangulation. This can be overwhelmingly slow and annoying and requires tons of memory if there are more than 40-50 points (the amounts of these resources are proportional to the 6th(!) and 3rd power of the number of the points, respectively). The directive auto increases the level of the triangulation expansion automatically until a proper match is found. A match is considered as a good match if the unitarity of the transformation is less than the unitarity U specified by the unitarity=U directive (see also the section Notes/Unitarity below). | ||
Line 100: | Line 97: | ||
: (Note that there should be only one --triangulation switch, all desired directives should be written in the same argument, separated by commas.) | : (Note that there should be only one --triangulation switch, all desired directives should be written in the same argument, separated by commas.) | ||
− | |||
: '''--col-ref-ordering''' [-]<w>, '''--col-inp-ordering''' [-]<w>. | : '''--col-ref-ordering''' [-]<w>, '''--col-inp-ordering''' [-]<w>. | ||
:: These switches specify one-one column index from the reference and from the input files which are used to order these lists and select the first maxref and maxinp points (see above) for the generation of the two triangle meshes. Both columns should contain valid real numbers, otherwise the whole(!) line is excluded (not only from sorting but from the whole matching procedure). If there is no negative sign before the column index, the data are sorted in descending(!) order, therefore the lines with the lines with the highest(!) values are selected for triangulation. If there is a negative sign before the index, the data are sorted in ascending order by these values, therefore the lines with the smallest(!) values are selected for triangulation. For example, if we want to match star lists, we might want to use only the brightest ones to generate the triangle sets. If the brightnesses of the stars are specified by their fluxes, we should not use the negative sign (the list should be sorted in descending order to select the first few lines as the brightest stars), and if the brightness is known by the magnitude, we have to use the negative sign. | :: These switches specify one-one column index from the reference and from the input files which are used to order these lists and select the first maxref and maxinp points (see above) for the generation of the two triangle meshes. Both columns should contain valid real numbers, otherwise the whole(!) line is excluded (not only from sorting but from the whole matching procedure). If there is no negative sign before the column index, the data are sorted in descending(!) order, therefore the lines with the lines with the highest(!) values are selected for triangulation. If there is a negative sign before the index, the data are sorted in ascending order by these values, therefore the lines with the smallest(!) values are selected for triangulation. For example, if we want to match star lists, we might want to use only the brightest ones to generate the triangle sets. If the brightnesses of the stars are specified by their fluxes, we should not use the negative sign (the list should be sorted in descending order to select the first few lines as the brightest stars), and if the brightness is known by the magnitude, we have to use the negative sign. | ||
− | : '''--fit''' iterations=<N>,firstrejection=<F>,sigma=& | + | : '''--fit''' iterations=<N>,firstrejection=<F>,sigma=<S> |
− | :: Like '''--triangulation,''' this switch is followed by some directives. These directives specify the number <N> of iterations (iterations=<N>) for point matching. The firstrejection directive speciy the serial number <F> of the first iteration where points farer than & | + | :: Like '''--triangulation,''' this switch is followed by some directives. These directives specify the number <N> of iterations (iterations=<N>) for point matching. The firstrejection directive speciy the serial number <F> of the first iteration where points farer than <S;gt; sigma level are excluded in the next iteration. Note that in practice these type of iteration is really not important (due to, for instance, the limitations of the outliers by the '''--max-distance''' switch), however, some suspicious users can be convinced by such arguments. |
− | : '''--weight''' reference|input,column=<wi>,[magnitude],[power= | + | : '''--weight''' reference|input,column=<wi>,[magnitude],[power=<p>] |
:: These directives specify the weights which are used during the fit of the geometrical transformation. For example, in practice it is useful in the following situation. We try to match star lists, then the fainter stars are believed to have higher astrometrical errors, therefore they should have smaller influence in the fit. We can take the weights from the reference (specify reference) and from the input (specify input), from the column specified by the weight-index. The weights can be derived from stellar magnitudes, if so, specify magnitude to convert the read values in magnitude to flux. The real weights then is the powerth power of the flux. The default value of the power is 1, however, for the maximum-likelihood estimation of an assumed Gaussian distribution, the weights should be the second power of the fluxes. | :: These directives specify the weights which are used during the fit of the geometrical transformation. For example, in practice it is useful in the following situation. We try to match star lists, then the fainter stars are believed to have higher astrometrical errors, therefore they should have smaller influence in the fit. We can take the weights from the reference (specify reference) and from the input (specify input), from the column specified by the weight-index. The weights can be derived from stellar magnitudes, if so, specify magnitude to convert the read values in magnitude to flux. The real weights then is the powerth power of the flux. The default value of the power is 1, however, for the maximum-likelihood estimation of an assumed Gaussian distribution, the weights should be the second power of the fluxes. | ||
: Some notes on unitarity. The unitarity of a geometrical transformation measures how it differs from the closest transformation which is affine and a combination of dilation, rotation and shift. For such a transformation the unitarity is 0 and if the second-order terms in a transformation distort a such unitary transformation, the unitarity will have the same magnitude like the magnitude of this second-order effect. For example, to map a part of a sphere with the size of d degrees will have an unitarity of 1-cos(d). Therefore, for astrometrical purposes, a reasonable value of the critical unitarity in "auto" triangulation mode can be estimated as 2 or 3 times 1-cos(d/2) where d is the size of the field in which astrometry should be performed. | : Some notes on unitarity. The unitarity of a geometrical transformation measures how it differs from the closest transformation which is affine and a combination of dilation, rotation and shift. For such a transformation the unitarity is 0 and if the second-order terms in a transformation distort a such unitary transformation, the unitarity will have the same magnitude like the magnitude of this second-order effect. For example, to map a part of a sphere with the size of d degrees will have an unitarity of 1-cos(d). Therefore, for astrometrical purposes, a reasonable value of the critical unitarity in "auto" triangulation mode can be estimated as 2 or 3 times 1-cos(d/2) where d is the size of the field in which astrometry should be performed. |