2 Usage

Summary:

The options available are described in Table 1. String or integer values are given in the form –catalogue=usno@eso; those marked switch, such as –insert, can be specified as either –insert (meaning true) or –noinsert (false).

Those options which take values can have those values specified as either –option=value or –option value. The latter form is rather unfortunate (but currently unavoidable), since it means that if you forget to give a value, it gobbles the next option on the line as its value. The options of type switch below take no value; all of the others do.

2.1 Specifying positions

To work, autoastrom requires some initial estimate of the centre of the CCD frame. You can provide this with a WCS component in the NDF, or with a FITS (NDF-) extension, or with approximate astrometry given on the command line. By default, autoastrom searches for a WCS component, then a FITS extension, and fails if it finds neither. Because autoastrom ultimately sits on top of the AST library, it is able to make sense of a large variety of embedded FITS information, and get its initial astrometry from such pointing information.

You control this process using the –obsdata option.

If you wish to insert an initial approximate WCS component in the NDF, you can best do this using Gaia.

The initial calibration does not have to be particularly accurate; it need only be accurate enough that autoastrom is able to make a query to a catalogue server that will return a set of catalogue objects that has a substantial overlap with the imaged area of sky. The query covers the region of sky which maps to the four corners of the image, based on the initial astrometry, plus a small extra margin.

The default image scale is 1 arcsec per pixel. You will need to specify the scale if the actual scale is significantly different from this, as errors in this scale result in substantial errors in the patch of sky requested from the server. It is better to choose too small a scale than too large – that way, the area which autoastrom searches for will tend to lie within the observed area, rather than greatly overlap it.

autoastrom assumes that north is along the y-axis. The matching algorithms are generally insensitive to this angle. However, the only case where you need to specify this is if the CCD is significantly longer than it is wide, since in this case a wrong orientation would cause autoastrom to search for a patch of sky which was a different shape from the patch covered by the CCD. Similarly, you should specify any image inversion if you know it, but it is not always necessary.

2.2 Iterations

autoastrom comes to its solution iteratively. After acquiring both catalogues – the SkyCat catalogue and the detected objects catalogue – it enters an iteration loop, starting off by matching objects between the two catalogues. It then calculates an astrometric solution, and if certain criteria have been met, the calculated solution is used. Otherwise, the iteration loop is entered again. This has the effect that more objects are usually matched between the two catalogues after an improved astrometric solution has been found, which leads to a more accurate solution.

Iterations can be halted in one of three ways: by reaching an absolute RMS level in the astrometric solution; by reaching a limit in the difference between the current astrometric solution’s RMS and the prior solution’s; and by reaching a maximum number of iterations. By default autoastrom is set to halt after ten iterations. For more information on modifying these values, see Sections 2.5.8, 2.5.9, and 2.5.16.

2.3 Results

Results can be inserted into the input NDF (see Section 2.5.7), or else retained as a standalone FITS-WCS file (see Section 2.5.10). You can choose both, either, or even choose neither and throw the results away (strange person!).

The FITS files which autoastrom produces are in fact generated by ASTROM. As discussed in SUN/5, these employ a slight extension to the FITS-WCS standards, since they necessarily include distortion information which has been deferred until Paper III [6]. Nonetheless, they are perfectly conformant. If, however, autoastrom had to be configured with support for an old version of AST, then it might have had to generate FITS headers which conformed to the drafts of paper II, and thus do not conform to the final version – such FITS files should not be used outside of this application, and it would be best to update your version of AST to a current one, and reinstall autoastrom.

The calculated astrometry is inserted into the input NDF unless you suppress it with the –noinsert option. If you need to insert this by hand, into this or another NDF, you can do so with Kappa’s wcscopy command (you may need to initialise the Convert package, so that the conversions between FITS and NDF will happen automatically).

For further details, see the FITS standard [7] and the three published FITS-WCS papers, [5, FITS WCS Paper I], [4, FITS WCS Paper II] and [6, FITS WCS Paper III]; the web pages which cover the FITS-WCS process are at http://www.cv.nrao.edu/fits/documents/wcs/wcs.html.

2.4 Web proxies

In order to perform catalogue lookups, autoastrom needs to make HTTP (Web) queries. If your site enforces the use of proxies to get access to the web, these lookups will fail, and autoastrom will simply wait uselessly until its queries time out.

You can tell autoastrom how to use the proxies by using the standard HTTP_PROXY environment variable, which you set through something like

or

depending on whether you use a csh-like (tcsh) or sh-like (bash, zsh) shell.

Your local computing service can advise you on the appropriate value for this environment variable, or you can examine the appropriate part of the configuration of your web browser.

2.5 Options

The options are either switches, or have a string or integer argument.

The verbosity option is an example of a switch: it can be given as –verbose to make the program verbose, or –noverbose to make it quiet.

Some options take suboptions. For example, the –obsdata option might be given as

where the comma-separated list of suboptions is given as the –obsdata option argument.

There are no optional arguments: if an option is documented as having an argument (that is, if it is not a switch), an argument must be provided. The defaults documented below apply only if the option is not supplied.

2.5.1 –bestfitlog

When ASTROM finds a solution, information about the best fit is written to this file. This file is a textfile containing the number of terms, the central right ascension and declination, the average pixel RMS, the distortion factor (when applicable) and the FITS file containing the WCS headers for all of the fits found. For the best fit, this file also lists the number of stars used in the fit, the mean plate scale in arcseconds, and the RMS in fitted $r$, $x$, and $y$.

Type: string; default: none.

2.5.2 –catalogue

This is the name of the online catalogue to use to find reference stars. The argument should be one of the catalogue names recognised by SkyCat. The list of available catalogues depends on the configuration file used (see Section 2.5.22); the ‘short_name’ entries in the file are the allowable values of this option.

Type: string; default (presently): ‘usno@eso’

2.5.3 –ccdcatalogue

Specifies a pre-existing catalogue of objects in the CCD frame. The format is that produced as output by SExtractor when catalog_type is set to ASCII_HEAD. The file starts with a sequence of lines of the form

The colnum numbers run from 1 to the number of columns; the colname is one of a set of column named defined in the SExtractor documentation; and optional comment is some (ignored) annotation. The data immediately follows, in rows with the given number of columns in them. In each of these rows, any text following a # is ignored, and may be used for other annotation.

You control which columns SExtractor generates by specifying them in the SExtractor .param file. The catalogue must have all of the fields NUMBER, FLUX_ISO, X_IMAGE, Y_IMAGE, A_IMAGE, B_IMAGE, X2_IMAGE, Y2_IMAGE, ERRX2_IMAGE, ERRY2_IMAGE, ISOAREA_IMAGE, of which X2_IMAGE, Y2_IMAGE, A_IMAGE, B_IMAGE, ERRX2_IMAGE, ERRY2_IMAGE are not generated by default.

For further details about SExtractor, and details of these required columns, see Section 3.

If you include the option –keeptemps to avoid deleting the temporary work directory, you will be able to scavenge the extractor output from there if this is useful to you.

Type: string; default: none

2.5.4 –defects

This option is currently unsupported but will be reinstated at some point in the future. The following documentation is valid for older versions of autoastrom.

If this option is present, then when the application extracts the list of objects from the CCD, it will try to remove CCD blemishes. The algorithm is currently rather crude, and will likely change in future.

Some of the ‘objects’ detected by EXTRACTOR are in fact CCD defects, or readout errors, or the like. These are very bright, so they can confuse a matching program which examines only or preferentially the brightest objects.

By default, autoastrom will warn of the existence of anything it thinks is a defect, based on a plausible heuristic, and you can control this using this option. The options takes a list of keywords, which it processes as shown in Table 2.

The heuristic works by assigning a ’badness’ to each object on the CCD. Objects with a position variance, $<x^2>$ or $<y^2>$, smaller than one pixel, and objects whose flux density (counts/pixel) is significantly higher than the average, are given high scores. One can observe that line and point defects score high with this, with a badness greater than 1, but this is not completely reliable.

We can afford a few uncaught defects, and we can afford to discard a few real, but very small, sources, since the match algorithms will generally simply ignore these. What we need to avoid is a CCD catalogue which is dominated by bright sources which have no counterpart on the sky.

We emphasise that this defect-removal algorithm is not particularly sophisticated – if the object-extraction is producing spurious objects, you may need to mask the defects out by hand, using GAIA or similar.

If you have any observations on the reliability, or indeed usefulness, of this option, the author would be interested to receive them.

This option is not always necessary when used with the default FINDOFF matching algorithm, but it is vital when used with the ‘match’ matching algorithm (see Section 2.5.13), since that algorithm uses only the brightest objects detected.

Type: string; default: –defects=warn

2.5.5 –detectedcatalogue

Specifies a file which receives a dump of the objects detected in the NDF, with their astrometric positions corrected. The file is in the Cluster format with thirteen columns: a zero in the first column, followed by the item’s ID, the right ascension and declination in space-separated format, the x and y position of the source on the CCD, an instrumental magnitude, the error in the instrumental magnitude, and extraction flags.

Type: string; default: none.

2.5.6 –help

Print usage information, and defaults, and exit.

Type: switch; default: false.

2.5.7 –insert

If true, the final fit to the astrometry is inserted into the input NDF as an AST WCS component. If false (–noinsert), the insertion is not done, so presumably you have decided to handle the WCS information in a different way, and have set the –keepfits option to retain the WCS information.

Type: switch; default: true.

2.5.8 –iterrms_abs

When the absolute RMS of a fit reaches this value, iterations will cease and the current WCS will be used. For more information on autoastrom’s iteration process, see Section 2.2.

Type: real; default; none.

2.5.9 –iterrms_diff

When the difference between the current RMS and the previous fit’s RMS reaches this value, iterations will cease and the current WCS will be used. For more information on autoastrom’s iteration process, see Section 2.2.

Type: real; default; none.

2.5.10 –keepfits

The normal mode of operation is for the script to insert the final astrometry into the input NDF, as an AST WCS component (see Section 2.5.7). Instead, or additionally, you can save this information as a FITS-WCS file, named by this option.

Type: switch; default: false.

2.5.11 –keeptemps

If true, temporary files will not be deleted at the end of processing. This is useful for debugging, both at the low level when there is something wrong with the script itself, but also when you wish to examine the sequence of calls to FINDOFF and ASTROM, or examine the ASTROM input and output files.

All the temporary files are created in a temporary directory which is reported during the script’s execution.

Type: switch; default: false

2.5.12 –man

If true, print a man page and exit.

Type: switch; default: false

2.5.13 –match

Specifies an alternative matching algorithm. The default algorithm is ‘match’, which is an implementation of the FOCAS matching algorithm [9] by Michael W Richmond [8]. A version of this is distributed with autoastrom, but it should be compatible with any later version.

Alternatively, you can use the FINDOFF application, which is part of Ccdpack. This does work, but is rather slow, and is completely thrown by a CCD image with unequal X and Y scales, making it essentially unusable if the image NDF does not have some astrometry already, or if you try to specify a position with –obsdata (see Section 2.5.21). Since it has different characteristics, though, it may work in some circumstances where ‘match’ does not. Again, the author of autoastrom would welcome feedback on this point.

autoastrom supports ‘match’ through the more general plugin mechanism described in Section 3.2.

Type: string; default: ‘match’.

2.5.14 –matchcatalogue

Specifies a file which receives a dump of the set of positions matched by the matching process. The file is formatted like a SExtractor output file, with five columns, containing (1) running object number, (2 and 3) RA and Dec of the source on the sky, and (4 and 5) x and y positions of the source on the CCD.

Type: string; default: absent – no file written by default.

2.5.15 –maxfit

The maximum order fit to use. If not set, then 9 will be used.

Type: integer; default: 9.

2.5.16 –maxiter

The maximum number of iterations to perform. For more information on autoastrom’s iteration process, see Section 2.2.

Type: integer; default: 10.

2.5.17 –maxobj_corr

The maximum number of objects to use from either catalogue to perform correlation on. This will take the brightest objects in the catalogues.

Type: integer; default: 500.

2.5.18 –maxobj_image

The maximum number of objects to use from the image catalogue. This will take the brightest objects in the catalogue.

Type: integer; default: 500;

2.5.19 –maxobj_query

The maximum number of objects to fetch from the catalogue server. The default is generous, and it’s unlikely you’d need to change this.

Type: integer: default: 500

2.5.20 –messages

If true, the script will pass on messages from the Starlink applications which the script uses. These might be reassuring, but if you don’t like the chatter, they can be suppressed with –nomessages.

Type: switch; default: true

2.5.21 –obsdata

Specifies a source for the observation data, including WCS information. The keyword has the multiple role of specifying the source of WCS information, supplying approximate WCS information directly, and supplying the observation data (time, observatory, temperature andpressure, and colour) which ASTROM needs if it is to attempt one of its higher-order fits. This information is only needed if it is missing from the NDF or any FITS extension it incorporates, and if you wish to attempt the slight increase in accuracy of the more elaborate fits.

Do not specify a keyword more than once with distinct values.

The value of the –obsdata option can specify approximate astrometry through a comma-separated list of key=value pairs. For example, to supply a value for the centre of a CCD, overriding any astrometry in the file, you might write

This value indicates the centre of the CCD even when this is not the centre of distortion, which would be the case when, for example, the CCD represents an off-centre section of a Schmidt plate.

The program will take its astrometry from only one of the possible sources (see source below) – so that it will not, for example, take a position from the obsdata option and a plate scale from the file’s own astrometry. By default, a position given here overrides any other WCS information; thus to supply a position as a backup, in case there is no astrometry elsewhere, you could write

The available astrometry keywords are in Table 3.

The position angle is the same as the AIPS CROTA2 convention. Specifically (and by definition) these definitions map to the CDn_n conventions of [4] through $$\begin{array}{l}\hfill \end{array}$$CD1_1 = ±s cos(ϕ) CD1_2 = ±s sin(ϕ) CD2_1 = −s sin(ϕ) CD2_2 = s cos(ϕ),

where s is scale/3600 (ie, the scale in unites of degrees/pixel), $\varphi$ is the position angle pa, and $\pm$ is $+$ when invert is false, and $-$ when invert is true.

Additionally, there are keywords which specify observation data: time, station coordinates, meteorological data and colour. These are described in Table 4. For fuller details on these, see ASTROM. Note that the source keyword discussed above does not affect the priority of these keywords: if they are specified, they override any values obtained from the NDF or its FITS extensions.

Type: string; defaults: see above.

2.5.22 –skycatconfig

The SkyCat library has a default configuration file, which you can examine at http://archive.eso.org/skycat/skycat2.0.cfg. For some applications, it may be appropriate to use an alternative configuration file. If so, you can point to it using this option. For more information on SkyCat, catalogues, and the configuration file, see the SkyCat FAQ.

Type: string; default: built-in defaults.

2.5.23 –skycatcatalogue_in

Specifies a pre-existing catalogue of objects as retrieved from SkyCat. The format of this catalogue must be the Cluster format as described in Section 2.5.5.

Type: string; default: none.

2.5.24 –skycatcatalogue_out

After the SkyCat query has been performed, the catalogue returned can be saved to disk in this file. The format of this catalogue will be the Cluster format as described in Section 2.5.5.

If used in conjunction with the –skycatcatalogue_in option (see Section 2.5.23), this can be used as a poor-man’s cache, avoiding potentially timely SkyCat queries.

Type: string; default: none.

2.5.25 –temp

This option, if present, specifies the directory to be used for temporary files.

This has a double function: firstly and most straightforwardly, it indicates where temporary files should be created if, for some reason, the default location is unsuitable; secondly, if the script finds there a file (from a previous run) which it was about to generate, it does not regenerate it, but instead simply reuses it. The first function may be useful in some circumstances; the second is primarily a debugging facility, is subtle, and its use is discouraged.

Type: string; default: generated.

2.5.26 –timeout

If present, this specifies how long, in seconds, the script should wait for its slave applications to complete. The default is three minutes. In some circumstances – such as if you have a huge number of stars to match up – this might be too short, so that the script loses patience before the slave application has finished, and produces a rather messy error message. In this circumstance, you can increase the timeout here.

Type: integer; default: 180.

2.5.27 –verbose

If present, the script produces a good deal of chatter to the standard error; if false (–noverbose), this is suppressed.

Type: switch; default: false.

2.5.28 –version

If present, write the version number ot the standard output and exit.

Type: switch; default: false.