Astrometry Database Interface

This module provides an interface for accessing a database which contains updated WCS solutions for many images in the HST archive. The exact set of images with new solutions in this database will change over time, with the initial release containing updates only for ACS and WFC3 direct images. This database will be designed to provide multiple WCS solutions for each exposure depending on what astrometric frame was used to define the new WCS solution; for example, an image may be matched to Pan-STARRS sources in one solution and to GAIA sources in another solution.

Each new WCS solution will be appended to the exposure by this module as a headerlet extension, taking advantage of the headerlet definition provided by the STWCS package, found in Headerlet documentation. The headerlet library allows a user to manage all appended solutions and determine which one gets used by the exposure at anytime, since only 1 WCS can be used at a time.

Usage

This interface defines an object that provides the services for updating an exposure with new WCS solutions. Only 2 calls are typically necessary to update any exposure or set of exposures.

0. Import the package

>>> from stwcs.updatewcs import astrometry_utils as stwcsau

1. Establish a working connection with the database

>>> db = stwcsau.AstrometryDB()

2. For each exposure, query the database and update with any new WCS solutions

>>> db.updateObs(filename)

The environment variables used by this module can be defined by the user to change what database is being accessed, whether to raise exceptions instead of warnings when problems arise in connecting to the database or otherwise updating an exposure, or to completely turn on/off use of this module. These allow external code, such as updatewcs (see updatewcs), to include this code and control it as necessary.

API

Interface for Astrometry database service.

This module contains interface functions for the AstrometryDB Restful service based on interfaces/code provided by B. McLean 11-Oct-2017.

The code checks for the existence of environmental variables to help control the operation of this interface; namely,

RAISE_PIPELINE_ERRORS - boolean to specify whether to raise exceptions

during processing or simply log errors and quit gracefully. If not set, default behavior will be to log errors and quit gracefully.

ASTROMETRY_SERVICE_URL - URL pointing to user-specified web service that

will provide updated astrometry solutions for observations being processed. This will replace the built-in URL included in the base class. This value will also be replaced by any URL provided by the user as an input parameter url.

ASTROMETRY_STEP_CONTROL - String specifying whether or not to perform the

astrometry update processing at all. Valid Values: “ON”, “On”, “on”, “OFF”, “Off”, “off” If not set, default value is “ON”.

GSSS_WEBSERVICES_URL - URL point to user-specified web service which provides

information on the guide stars used for taking HST observations. This value will replace the default URL included in this module as the gsss_url variable.

class stwcs.updatewcs.astrometry_utils.AstrometryDB(url=None, raise_errors=None, perform_step=True, write_log=False, testing=False)

Bases: object

Base class for astrometry database interface.

apply_new_apriori(obsname)

Compute and apply a new a priori WCS based on offsets from astrometry database.

Parameters:

obsname (str) – Full filename or astropy.io.fits.HDUList object for the observation to be corrected

Returns:

wcsname – Value of WCSNAME keyword for this new WCS

Return type:

str

findObservation(observationID)

Find whether there are any entries in the AstrometryDB for the observation with observationID.

Parameters:

observationID (str) – base rootname for observation to be updated (eg., iab001a1q)

Returns:

entry – Database entry for this observation, if found. It will return None if there was an error in accessing the database and self.raise_errors was not set to True.

Return type:

obj

getObservation(observationID)

Get solutions for observation from AstrometryDB.

Parameters:

observationID (str) – base rootname for observation to be updated (eg., iab001a1q)

Returns:

  • headerlets (dict) – Dictionary containing all solutions found for exposure in the form of headerlets labelled by the name given to the solution in the database.

  • best_solution_id (str) – WCSNAME of the WCS solution flagged as ‘best’ in the astrometry database for the observation. The ‘best’ solution should be the one that aligns the observation as close to the GAIA frame as possible.

isAvailable(max_tries=3, force_timeout=False)

Tests the availability of the astrometry database

Parameters:

  • max_tries (int, optional) – Number of attempts to query the db, by default 3

  • force_timeout (bool, optional) – If True, forces a timeout to test error handling, by default False

Raises:

  • ConnectionRefusedError – If the service is unavailable after max_tries attempts and raise_errors is True

  • ConnectionError – If there is a network-related error during the request and raise_errors is True

updateObs(obsname, all_wcs=False, remove_duplicates=True)

Update observation with any available solutions.

Parameters:

  • obsname (str) – Filename for observation to be updated

  • all_wcs (bool) – If True, all solutions from the Astrometry database are appended to the input file as separate FITS extensions. If False, only those solutions based on the same IDCTAB will be appended.

  • remove_duplicates (bool) – If True, any headerlet extensions with the same HDRNAME are found, the copies will be deleted until only the first version added remains.

stwcs.updatewcs.astrometry_utils.apply_astrometric_updates(obsnames, **pars)

Apply new astrometric solutions to observation.

Functional stand-alone interface for applying new astrometric solutions found in the astrometry dB to the given observation(s).

Parameters:

  • obsnames (str, list) – Filename or list of filenames of observation(s) to be updated

  • url (str, optional) – URL of astrometry database web-interface to use. If None (default), it will use built-in URL for STScI web-interface

  • raise_errors (bool, optional) – Specify whether or not to raise Exceptions and stop processing when an error in either accessing the database, retrieving a solution from the database or applying the new solution to the observation. If None, it will look to see whether the environmental variable RAISE_PIPELINE_ERRORS was set, otherwise, it will default to ‘False’.

stwcs.updatewcs.astrometry_utils.find_gsc_offset(obsname)

Find the GSC to GAIA offset based on guide star coordinates

Parameters:

obsname (str) – Full filename or (preferably)`astropy.io.fits.HDUList` object of image to be processed.

Notes

The default transform is GSC2-GAIA. The options were primarily for transforming individual objects from the catalogs and that is not specified in the limited documentation. The ipppssoot input is a special case where it pulls the gsids, epoch and refframe from the dms databases and overrides the transform using this logic:

REFFRAME=GSC1 sets GSC1-GAIA
REFFRAME=ICRS and EPOCH < 2017.75 sets GSC2-GAIA
REFFRAME=ICRS and EPOCH > 2017.75 sets no-offset since it's already in GAIA frame
Returns:

response – Dict of offset, roll and scale in decimal degrees and pixels for image based on correction to guide star coordinates relative to GAIA. Keys: delta_x, delta_y, delta_ra, delta_dec, roll, scale, expwcs, catalog, dGSinputRA, dGSoutputRA, dGSinputDEC, dGSoutputDEC

Return type:

dict

The find_gsc_offset() function uses a web service to provide an improved position for both the reference guide star and the secondary (roll) guide star used in an HST observation. The Guide Star Catalog astrometry has improved a lot over the years. The original version of GSC (GSC-1) had errors in astrometry as large as 1 or 2 arcseconds. GSC-2 reduced those errors to about 0.25 arcseconds. More recent versions of the catalog (now up to GSC 3) reduce the errors further using Gaia positions, typically 0.01 arcsecond or less, depending on the epoch of the observation. By knowing what the guide star position was thought to be at the time (from the original catalog), and what the position really is (from the improved catalog), one can get a more accurate value for where the telescope was actually pointing.

Version

stwcs.__version__ = '1.7.8.dev7+g7888bdbbd.d20260603'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.