mosastro takes a collection of data from mosaic CCD images, all individually astrometrized, and determines a single global astrometric solution for the complete system. In this process, it determines a distortion model for the telescope arising from the optical system, as well as mapping solutions relating the coordinate systems of the individual chip pixels to the focal plane. Both of these transformations may involve up to 3rd order polynomials.

The suggested operation is to use gastro (or gastro2) to determine linear astrometric solutions for the individual chips before running mosastro. Mosastro requires the individual chip astrometry have an accuracy of roughly 1 arcsec or better in order to select the match between the observed stars and the astrometric reference catalog. This two stage approach allows a more robust linear solution for the individual chips, which may have too few reference star matches to define reliable high-order solution. The mosaic analysis determines a single distortion model representing the physical contribution of the telescope optics. Mosastro is run assuming the user has a collection of Elixir-style astrometry / photometry files in one of the CMP/SMP/SMF set of formats. Mosastro will auto-detect the data format and load the stellar astrometric and photometric measurements. The collection of data is assumed to consist of one file per chip, with names which are sufficiently consistent that they can be identified with a single filename including wild-cards.

The user command looks like:

    mosastro (glob) (ext) (phu)

The first argument is an expression containing wild-cards which expands into the collection of files containing the astrometric data. The mosastro program must receive the wild-card expression without expansion by the shell. The user call needs to protect the wild-card against expansion, which can usually be done by placing the expression within double-quote marks. The second argument is the new output extension. The stellar photometry will be written out to files using the same names as the input, replacing the final filename extension with the provided extension. The standard input extensions are one of the following: 'cmp', 'smp' (used for dophot or sextractor output files in raw text format), 'cmf, 'smf' (used for dophot or sextractor output files in fits table format). The recommended output extensions replace the 'c' or 's' with 'x': 'xmp' for raw text format, or 'xmf' for FITS table format. The final argument is the name of the output 'primary header unit' file. The standard usage here is to use the filename root (without chip identifiers) with the extension 'phu'. The output telescope boresite and optical distortion terms are written to this primary header entry, which is constructed from the first of the chip files (true?). future expansions: allow input list of files from a file, allow input MEF collection of chip astrom/photom

In the following discussion, we refer to conversions between several coordinate frames. We use the term 'project' to describe the projection of the celestial coordinates to the linear (focal plane or chip) coordinates; we use the term 'deproject' to describe the conversion from the linear chip or focal-plane coordinates to the spherical celestial coordinates.

mosastro performs the following steps in the analysis.

- Load the raw stellar astrometry data from the chip files
- Deproject the stars using the approximate chip astrometry
- Determine the RA and DEC range of the observed star measurements
- Define the initial guess telescope boresite / distortion model
- Project the observed star coordinates to the focal plane
- Load the astrometric reference catalog.
- Project the reference catalog to the focal plane
- Match obs and ref on the focal plane
- Measure the local gradient of the matched star coordinate in the tangent plane as a function of focal plane coordinate.
- Fit the local gradient values as a function of focal plane coordinates
- Use the measured gradient model to modify the distortion model
- Fit low-order solution for the chip model
- Clip outlier matches
- Fit high-order solution for the chip model
- Perform several clip / fit iterations
- Write out the new solutions / data to the output file

### options

The following command-line options are available to the user:

- -help or -h : print summary help information
- -v : turn on verbosity
- -dump (selection) : write out matched stars data at some processing stage. The selection specifies where in the analysis to write out the result. The following options are available:
  - rawstars : write out the raw input observed star positions, after the initial projection
  - refcat : write out the reference catalog data (after initial projection).
  - rawmatch : write out the obs and ref stars after the first match, before any fit is performed
  - fitgrads : write out the obs and ref stars after correction for the local gradient
  - fitchips_unclip : write out the obs and ref stars after fitting the initial chip term
  - fitchips : write out the obs and ref stars after the clipping iterations.
- -save-residuals : save table of obs and ref star matches, with coordinates in the multiple frames, as an extension to the PHU file.
- -chips : load the initial chip focal-plane mapping (not yet implemented)
- -field : load the inital field rotation, boresite, plate-scale from reference file
- -order : define the polynomial order of the telescope distortion model (default is 0). -chiporder : define the polynomial order of the chip mapping model (default is 1).

### Elixir Configuration Data

Mosastro uses the following Elixir configuration variables:

- EXPTIME-KEYWORD : header keyword defining exposure time
- DATE-KEYWORD : header keyword defining the date
- DATE-MODE : mode for header date information: use a combination of Ys, Ms, Ds to specify order. If only 2 digits are specified for the year, numbers greater than 50 are assumed in the 1900s, less than in the 2000s. eg YYYY/MM/DD
- UT-KEYWORD : header keyword defining UT
- MJD-KEYWORD : header keyword defining MJD
- JD-KEYWORD : header keyword defining JD note that only one of the combination JD, MJD, or DATE/UT needs to be defined.
- ASTRO_REFCAT : desired astrometric reference catalog. allowed values are `GSC, USNO, 2MASS, PTOLEMY, STONE`.
- GSCDIR : location of the HST Guide Star Catalog
- USNO_CDROM : location of the USNO-A data
- STONE_DIR : location of the Stone et al reference data
- 2MASS_DIR : location of the 2MASS data
- CATDIR : location of the ptolemy data
- GSCFILE : location of the GSC layout file (for GSC and ptolemy) note that 'ptolemy' refers to data using the DVO format. 2MASS data must be in a DVO format database. USNO and GSC are both loaded from their idiosyncratic formats.
- RADIUS : matching radius in arcsec to select reference stars
- SIGMA_LIM : exclude stars with formal error larger than this
- ZERO_PT : default zero point, nominally 25.0. don't set this to a 'real' zero point. it is used only for reference.
- INST_MAG_MIN : exclude stars brighter than this instrumental magnitude
- INST_MAG_MAX : exclude stars fainter than this instrumental magnitude
- INST_BRIGHT : use stars brighter than this value to measure systematic error limit.