Headerlet - User Interface

This module implements headerlets.

A headerlet serves as a mechanism for encapsulating WCS information which can be used to update the WCS solution of an image. The idea came up first from the desire for passing improved astrometric solutions for HST data and provide those solutions in a manner that would not require getting entirely new images from the archive when only the WCS information has been updated.

NOTE ::

This module defines a FileHandler for the logging in the current working directory for the user when this module first gets imported. If that directory is removed later by the user, it will cause an Exception when performing headerlet operations later.

The file handler can be identified using:

rl = logging.getLogger('stwcs.wcsutil.headerlet')
rl.handlers
del rl.handlers[-1]  # if FileHandler was the last one, remove it
class stwcs.wcsutil.headerlet.FuncNameLoggingFormatter(fmt=None, datefmt=None)
format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class stwcs.wcsutil.headerlet.Headerlet(hdus=[], file=None, logging=False, logmode='w')

A Headerlet class Ref: http://mediawiki.stsci.edu/mediawiki/index.php/Telescopedia:Headerlets

apply_as_alternate(fobj, attach=True, wcskey=None, wcsname=None)

Copy this headerlet as an alternate WCS to fobj

Parameters:

  • fobj (string, HDUList) – science file/HDUList to which the headerlet should be applied

  • attach (bool) – flag indicating if the headerlet should be attached as a HeaderletHDU to fobj. If True checks that HDRNAME is unique in the fobj and stops if not.

  • wcskey (string) – Key value (A-Z, except O) for this alternate WCS If None, the next available key will be used

  • wcsname (string) – Name to be assigned to this alternate WCS WCSNAME is a required keyword in a Headerlet but this allows the user to change it as desired.

apply_as_primary(fobj, attach=True, archive=True, force=False)

Copy this headerlet as a primary WCS to fobj

Parameters:

  • fobj (string, HDUList) – science file to which the headerlet should be applied

  • attach (bool) – flag indicating if the headerlet should be attached as a HeaderletHDU to fobj. If True checks that HDRNAME is unique in the fobj and stops if not.

  • archive (bool (default is True)) – When the distortion model in the headerlet is the same as the distortion model of the science file, this flag indicates if the primary WCS should be saved as an alternate and a headerlet extension. When the distortion models do not match this flag indicates if the current primary and alternate WCSs should be archived as headerlet extensions and alternate WCS.

  • force (bool (default is False)) – When the distortion models of the headerlet and the primary do not match, and archive is False this flag forces an update of the primary

attach_to_file(fobj, archive=False)

Attach Headerlet as an HeaderletHDU to a science file

Parameters:

  • fobj (string, HDUList) – science file/HDUList to which the headerlet should be applied

  • archive (string) – Specifies whether or not to update WCSCORR table when attaching

Notes

The algorithm used by this method: - verify headerlet can be applied to this file (based on DESTIM) - verify that HDRNAME is unique for this file - attach as HeaderletHDU to fobj

build_distname(dest)

Builds the DISTNAME for dest based on reference file names.

equal_distmodel(dmodel)
classmethod fromfile(fileobj, mode='readonly', memmap=False, save_backup=False, logging=False, logmode='w', **kwargs)

Creates an HDUList instance from a file-like object.

The actual implementation of fitsopen(), and generally shouldn’t be used directly. Use open() instead (and see its documentation for details of the parameters accepted by this method).

classmethod fromstring(data, **kwargs)

Creates an HDUList instance from a string or other in-memory data buffer containing an entire FITS file. Similar to HDUList.fromfile(), but does not accept the mode or memmap arguments, as they are only relevant to reading from a file on disk.

This is useful for interfacing with other libraries such as CFITSIO, and may also be useful for streaming applications.

Parameters:

  • data (str, buffer-like, etc.) – A string or other memory buffer containing an entire FITS file. Buffer-like objects include bytes, bytearray, memoryview, and ndarray. It should be noted that if that memory is read-only (such as a Python string) the returned HDUList’s data portions will also be read-only.

  • **kwargs (dict) – Optional keyword arguments. See astropy.io.fits.open() for details.

Returns:

hdul – An HDUList object representing the in-memory FITS file.

Return type:

HDUList

get_destination_model(dest)

Verifies that the headerlet can be applied to the observation

Determines whether or not the file specifies the same distortion model/reference files.

hverify()

Verify the headerlet file is a valid fits file and has the required Primary Header keywords

info(columns=None, pad=2, maxwidth=None, output=None, clobber=True, quiet=False)

Prints a summary of this headerlet The summary includes: HDRNAME WCSNAME DISTNAME SIPNAME NPOLFILE D2IMFILE

Parameters:

  • columns (list) – List of headerlet PRIMARY header keywords to report in summary By default (set to None), it will use the default set of keywords defined as the global list DEFAULT_SUMMARY_COLS

  • pad (int) – Number of padding spaces to put between printed columns [Default: 2]

  • maxwidth (int) – Maximum column width(not counting padding) for any column in summary By default (set to None), each column’s full width will be used

  • output (string (optional)) – Name of optional output file to record summary. This filename can contain environment variables. [Default: None]

  • clobber (bool) – If True, will overwrite any previous output file of same name

  • quiet (bool) – If True, will NOT report info to STDOUT

init_attrs()
summary(columns=None)

Returns a summary of this headerlet as a dictionary

The summary includes a summary of the distortion model as :

HDRNAME WCSNAME DISTNAME SIPNAME NPOLFILE D2IMFILE

Parameters:

columns (list) – List of headerlet PRIMARY header keywords to report in summary By default(set to None), it will use the default set of keywords defined as the global list DEFAULT_SUMMARY_COLS

Returns:

summary – Dictionary of values for summary

Return type:

dict

tofile(fname, destim=None, hdrname=None, clobber=False)

Write this headerlet to a file

Parameters:

  • fname (string) – file name

  • destim (string (optional)) – provide a value for DESTIM keyword

  • hdrname (string (optional)) – provide a value for HDRNAME keyword

  • clobber (bool) – a flag which allows to overwrte an existing file

verify_dest(dest, fname)

verifies that the headerlet can be applied to the observation

DESTIM in the primary header of the headerlet must match ROOTNAME of the science file (or the name of the destination file)

verify_hdrname(dest)

Verifies that the headerlet can be applied to the observation

Reports whether or not this file already has a headerlet with this HDRNAME.

class stwcs.wcsutil.headerlet.HeaderletHDU(data=None, header=None, name=None, ver=None, **kwargs)

A non-standard extension HDU for encapsulating Headerlets in a file. These HDUs have an extension type of HDRLET and their EXTNAME is derived from the Headerlet’s HDRNAME.

The data itself is a FITS file embedded within the HDU data. The file name is derived from the HDRNAME keyword, and should be in the form <HDRNAME>_hdr.fits. If the COMPRESS keyword evaluates to True, the tar file is compressed with gzip compression.

The structure of this HDU is the same as that proposed for the ‘FITS’ extension type proposed here: http://listmgr.cv.nrao.edu/pipermail/fitsbits/2002-April/thread.html

The Headerlet contained in the HDU’s data can be accessed by the headerlet attribute.

classmethod fromheaderlet(headerlet, compress=False)

Creates a new HeaderletHDU from a given Headerlet object.

Parameters:

  • headerlet (Headerlet) – A valid Headerlet object.

  • compress (bool, optional) – Gzip compress the headerlet data.

Returns:

hlet – A HeaderletHDU object for the given Headerlet that can be attached as an extension to an existing HDUList.

Return type:

HeaderletHDU

property headerlet

Return the encapsulated headerlet as a Headerlet object.

This is similar to the hdulist property inherited from the FitsHDU class, though the hdulist property returns a normal HDUList object.

stwcs.wcsutil.headerlet.apply_headerlet_as_alternate(filename, hdrlet, attach=True, wcskey=None, wcsname=None, logging=False, logmode='w')

Apply headerlet to a science observation as an alternate WCS

Parameters:

  • filename (string or list of strings) – File name(s) of science observation whose WCS solution will be updated

  • hdrlet (string or list of strings) – Headerlet file(s), must match 1-to-1 with input filename(s)

  • attach (bool) – flag indicating if the headerlet should be attached as a HeaderletHDU to fobj. If True checks that HDRNAME is unique in the fobj and stops if not.

  • wcskey (string) – Key value (A-Z, except O) for this alternate WCS If None, the next available key will be used

  • wcsname (string) – Name to be assigned to this alternate WCS WCSNAME is a required keyword in a Headerlet but this allows the user to change it as desired.

  • logging (bool) – enable file logging

  • logmode ('a' or 'w') –

stwcs.wcsutil.headerlet.apply_headerlet_as_primary(filename, hdrlet, attach=True, archive=True, force=False, logging=False, logmode='a')

Apply headerlet ‘hdrfile’ to a science observation ‘destfile’ as the primary WCS

Parameters:

  • filename (string or list of strings) – File name(s) of science observation whose WCS solution will be updated

  • hdrlet (string or list of strings) – Headerlet file(s), must match 1-to-1 with input filename(s)

  • attach (bool) – True (default): append headerlet to FITS file as a new extension.

  • archive (bool) – True (default): before updating, create a headerlet with the WCS old solution.

  • force (bool) – If True, this will cause the headerlet to replace the current PRIMARY WCS even if it has a different distortion model. [Default: False]

  • logging (bool) – enable file logging

  • logmode ('w' or 'a') – log file open mode

stwcs.wcsutil.headerlet.archive_as_headerlet(filename, hdrname, sciext='SCI', wcsname=None, wcskey=None, destim=None, sipname=None, npolfile=None, d2imfile=None, author=None, descrip=None, history=None, nmatch=None, catalog=None, logging=False, logmode='w')

Save a WCS as a headerlet extension and write it out to a file.

This function will create a headerlet, attach it as an extension to the science image (if it has not already been archived) then, optionally, write out the headerlet to a separate headerlet file.

Either wcsname or wcskey must be provided, if both are given, they must match a valid WCS Updates wcscorr if necessary.

Parameters:

  • filename (string or HDUList) –

    Either a filename or PyFITS HDUList object for the input science file

    An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • hdrname (string) – Unique name for this headerlet, stored as HDRNAME keyword

  • sciext (string) – name (EXTNAME) of extension that contains WCS to be saved

  • wcsname (string) – name of WCS to be archived, if “ “: stop

  • wcskey (one of A...Z or " " or "PRIMARY") – if “ “ or “PRIMARY” - archive the primary WCS

  • destim (string) – DESTIM keyword if NOne, use ROOTNAME or science file name

  • sipname (string or None (default)) – Name of unique file where the polynomial distortion coefficients were read from. If None, the behavior is: The code looks for a keyword ‘SIPNAME’ in the science header If not found, for HST it defaults to ‘IDCTAB’ If there is no SIP model the value is ‘NOMODEL’ If there is a SIP model but no SIPNAME, it is set to ‘UNKNOWN’

  • npolfile (string or None (default)) – Name of a unique file where the non-polynomial distortion was stored. If None: The code looks for ‘NPOLFILE’ in science header. If ‘NPOLFILE’ was not found and there is no npol model, it is set to ‘NOMODEL’ If npol model exists, it is set to ‘UNKNOWN’

  • d2imfile (string) – Name of a unique file where the detector to image correction was stored. If None: The code looks for ‘D2IMFILE’ in the science header. If ‘D2IMFILE’ is not found and there is no d2im correction, it is set to ‘NOMODEL’ If d2im correction exists, but ‘D2IMFILE’ is missing from science header, it is set to ‘UNKNOWN’

  • author (string) – Name of user who created the headerlet, added as ‘AUTHOR’ keyword to headerlet PRIMARY header

  • descrip (string) – Short description of the solution provided by the headerlet This description will be added as the single ‘DESCRIP’ keyword to the headerlet PRIMARY header

  • history (filename, string or list of strings) – Long (possibly multi-line) description of the solution provided by the headerlet. These comments will be added as ‘HISTORY’ cards to the headerlet PRIMARY header If filename is specified, it will format and attach all text from that file as the history.

  • logging (bool) – enable file folling

  • logmode ('w' or 'a') – log file open mode

stwcs.wcsutil.headerlet.attach_headerlet(filename, hdrlet, logging=False, logmode='a')

Attach Headerlet as an HeaderletHDU to a science file

Parameters:

  • filename (HDUList or list of HDULists) – science file(s) to which the headerlet should be applied

  • hdrlet (string, Headerlet object or list of strings or Headerlet objects) – string representing a headerlet file(s), must match 1-to-1 input filename(s)

  • logging (bool) – enable file logging

  • logmode ('a' or 'w') –

stwcs.wcsutil.headerlet.create_headerlet(filename, sciext='SCI', hdrname=None, destim=None, wcskey=' ', wcsname=None, sipname=None, npolfile=None, d2imfile=None, author=None, descrip=None, history=None, nmatch=None, catalog=None, logging=False, logmode='w')

Create a headerlet from a WCS in a science file If both wcskey and wcsname are given they should match, if not raise an Exception

Parameters:

  • filename (string or HDUList) – Either a filename or PyFITS HDUList object for the input science file An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • sciext (string or python list (default: 'SCI')) – Extension in which the science data with the linear WCS is. The headerlet will be created from these extensions. If string - a valid EXTNAME is expected If int - specifies an extension with a valid WCS, such as 0 for a simple FITS file If list - a list of FITS extension numbers or strings representing extension tuples, e.g. (‘SCI, 1’) is expected.

  • hdrname (string) – value of HDRNAME keyword Takes the value from the HDRNAME<wcskey> keyword, if not available from WCSNAME<wcskey> It stops if neither is found in the science file and a value is not provided

  • destim (string or None) – name of file this headerlet can be applied to if None, use ROOTNAME keyword

  • wcskey (char (A...Z) or " " or "PRIMARY" or None) – a char representing an alternate WCS to be used for the headerlet if “ “, use the primary (default) if None use wcsname

  • wcsname (string or None) – if wcskey is None use wcsname specified here to choose an alternate WCS for the headerlet

  • sipname (string or None (default)) – Name of unique file where the polynomial distortion coefficients were read from. If None, the behavior is: The code looks for a keyword ‘SIPNAME’ in the science header If not found, for HST it defaults to ‘IDCTAB’ If there is no SIP model the value is ‘NOMODEL’ If there is a SIP model but no SIPNAME, it is set to ‘UNKNOWN’

  • npolfile (string or None (default)) – Name of a unique file where the non-polynomial distortion was stored. If None: The code looks for ‘NPOLFILE’ in science header. If ‘NPOLFILE’ was not found and there is no npol model, it is set to ‘NOMODEL’ If npol model exists, it is set to ‘UNKNOWN’

  • d2imfile (string) – Name of a unique file where the detector to image correction was If None: The code looks for ‘D2IMFILE’ in the science header. If ‘D2IMFILE’ is not found and there is no d2im correction, it is set to ‘NOMODEL’ If d2im correction exists, but ‘D2IMFILE’ is missing from science header, it is set to ‘UNKNOWN’

  • author (string) – Name of user who created the headerlet, added as ‘AUTHOR’ keyword to headerlet PRIMARY header

  • descrip (string) – Short description of the solution provided by the headerlet This description will be added as the single ‘DESCRIP’ keyword to the headerlet PRIMARY header

  • history (filename, string or list of strings) – Long (possibly multi-line) description of the solution provided by the headerlet. These comments will be added as ‘HISTORY’ cards to the headerlet PRIMARY header If filename is specified, it will format and attach all text from that file as the history.

  • nmatch (int (optional)) – Number of sources used in the new solution fit

  • catalog (string (optional)) – Astrometric catalog used for headerlet solution

  • logging (bool) – enable file logging

  • logmode ('w' or 'a') – log file open mode

Return type:

Headerlet object

stwcs.wcsutil.headerlet.delete_headerlet(filename, hdrname=None, hdrext=None, distname=None, keep_first=False, logging=False, logmode='w')

Deletes all HeaderletHDUs with same HDRNAME from science files

Notes

One of hdrname, hdrext or distname should be given. If hdrname is given - delete all HeaderletHDUs with a name HDRNAME from fobj. If hdrext is given - delete specified HeaderletHDU(s) extension(s). If distname is given - deletes all HeaderletHDUs with a specific distortion model from fobj. Updates wcscorr

Parameters:

  • filename (string, HDUList or list of strings) – Filename can be specified as a single filename or HDUList, or a list of filenames Each input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • hdrname (string or None) – HeaderletHDU primary header keyword HDRNAME

  • hdrext (int, tuple or None) – HeaderletHDU FITS extension number tuple has the form (‘HDRLET’, 1)

  • distname (string or None) – distortion model as specified in the DISTNAME keyword

  • keep_first (bool, optional) – If True, the first matching HeaderletHDU found will be NOT deleted.

  • logging (bool) – enable file logging

  • logmode ('a' or 'w') –

stwcs.wcsutil.headerlet.extract_headerlet(filename, output, extnum=None, hdrname=None, clobber=False, logging=True)

Finds a headerlet extension in a science file and writes it out as a headerlet FITS file.

If both hdrname and extnum are given they should match, if not raise an Exception

Parameters:

  • filename (string or HDUList or Python list) –

    This specifies the name(s) of science file(s) from which headerlets will be extracted.

    String input formats supported include use of wild-cards, IRAF-style ‘@’-files (given as ‘@<filename>’) and comma-separated list of names. An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename. If a list of filenames has been specified, it will extract a headerlet from the same extnum from all filenames.

  • output (string) – Filename or just rootname of output headerlet FITS file If string does not contain ‘.fits’, it will create a filename with ‘_hlet.fits’ suffix

  • extnum (int) – Extension number which contains the headerlet to be written out

  • hdrname (string) – Unique name for headerlet, stored as the HDRNAME keyword It stops if a value is not provided and no extnum has been specified

  • clobber (bool) – If output file already exists, this parameter specifies whether or not to overwrite that file [Default: False]

  • logging (bool) – enable logging to a file

stwcs.wcsutil.headerlet.find_headerlet_HDUs(fobj, hdrext=None, hdrname=None, distname=None, strict=True, logging=False, logmode='w')

Returns all HeaderletHDU extensions in a science file that matches the inputs specified by the user. If no hdrext, hdrname or distname are specified, this function will return a list of all HeaderletHDU objects.

Parameters:

  • fobj (str, astropy.io.fits.HDUList) – Name of FITS file or open fits object (astropy.io.fits.HDUList instance)

  • hdrext (int, tuple or None) – index number(EXTVER) or extension tuple of HeaderletHDU to be returned

  • hdrname (string) – value of HDRNAME for HeaderletHDU to be returned

  • distname (string) – value of DISTNAME for HeaderletHDUs to be returned

  • strict (bool [Default: True]) – Specifies whether or not at least one parameter needs to be provided If False, all extension indices returned if hdrext, hdrname and distname are all None. If True and hdrext, hdrname, and distname are all None, raise an Exception requiring one to be specified.

  • logging (bool) – enable logging to a file called headerlet.log

  • logmode ('w' or 'a') – log file open mode

Returns:

hdrlets – A list of all matching HeaderletHDU extension indices (could be just one)

Return type:

list

stwcs.wcsutil.headerlet.get_extname_extver_list(fobj, sciext)

Create a list of (EXTNAME, EXTVER) tuples

Based on sciext keyword (see docstring for create_headerlet) walk throughh the file and convert extensions in sciext to valid (EXTNAME, EXTVER) tuples.

stwcs.wcsutil.headerlet.get_header_kw_vals(hdr, kwname, kwval, default=0)
stwcs.wcsutil.headerlet.get_headerlet_kw_names(fobj, kw='HDRNAME')

Returns a list of specified keywords from all HeaderletHDU extensions in a science file.

Parameters:
stwcs.wcsutil.headerlet.headerlet_summary(filename, columns=None, pad=2, maxwidth=None, output=None, clobber=True, quiet=False)

Print a summary of all HeaderletHDUs in a science file to STDOUT, and optionally to a text file The summary includes: HDRLET_ext_number HDRNAME WCSNAME DISTNAME SIPNAME NPOLFILE D2IMFILE

Parameters:

  • filename (string or HDUList) – Either a filename or PyFITS HDUList object for the input science file An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • columns (list) – List of headerlet PRIMARY header keywords to report in summary By default (set to None), it will use the default set of keywords defined as the global list DEFAULT_SUMMARY_COLS

  • pad (int) – Number of padding spaces to put between printed columns [Default: 2]

  • maxwidth (int) – Maximum column width(not counting padding) for any column in summary By default (set to None), each column’s full width will be used

  • output (string (optional)) – Name of optional output file to record summary. This filename can contain environment variables. [Default: None]

  • clobber (bool) – If True, will overwrite any previous output file of same name

  • quiet (bool) – If True, will NOT report info to STDOUT

stwcs.wcsutil.headerlet.init_logging(funcname=None, level=100, mode='w', **kwargs)

Initialize logging for a function

Parameters:

  • funcname (string) – Name of function which will be recorded in log

  • level (int, or bool, or string) – int or string : Logging level bool: False - switch off logging Text logging level for the message (“DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”)

  • mode ('w' or 'a') – attach to logfile (‘a’ or start a new logfile (‘w’)

stwcs.wcsutil.headerlet.is_par_blank(par)
stwcs.wcsutil.headerlet.parse_filename(fname, mode='readonly')

Interprets the input as either a filename of a file that needs to be opened or a PyFITS object.

Parameters:

  • fname (str, astropy.io.fits.HDUList) – Input pointing to a file or astropy.io.fits.HDUList object. An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • mode (string) – Specifies what mode to use when opening the file, if it needs to open the file at all [Default: ‘readonly’]

Returns:

  • fobj (astropy.io.fits.HDUList) – FITS file handle for input

  • fname (str) – Name of input file

  • close_fobj (bool) – Flag specifying whether or not fobj needs to be closed since it was opened by this function. This allows a program to know whether they need to worry about closing the FITS object as opposed to letting the higher level interface close the object.

stwcs.wcsutil.headerlet.print_summary(summary_cols, summary_dict, pad=2, maxwidth=None, idcol=None, output=None, clobber=True, quiet=False)

Print out summary dictionary to STDOUT, and possibly an output file

stwcs.wcsutil.headerlet.restore_all_with_distname(filename, distname, primary, archive=True, sciext='SCI', logging=False, logmode='w')

Restores all HeaderletHDUs with a given distortion model as alternate WCSs and a primary

Parameters:

  • filename (string or HDUList) –

    Either a filename or PyFITS HDUList object for the input science file

    An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • distname (string) – distortion model as represented by a DISTNAME keyword

  • primary (int or string or None) – HeaderletHDU to be restored as primary if int - a fits extension if string - HDRNAME if None - use first HeaderletHDU

  • archive (bool (default True)) – flag indicating if HeaderletHDUs should be created from the primary and alternate WCSs in fname before restoring all matching headerlet extensions

  • logging (bool) – enable file logging

  • logmode ('a' or 'w') –

stwcs.wcsutil.headerlet.restore_from_headerlet(filename, hdrname=None, hdrext=None, archive=True, force=False, logging=False, logmode='w')

Restores a headerlet as a primary WCS

Parameters:

  • filename (string or HDUList) –

    Either a filename or PyFITS HDUList object for the input science file

    An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • hdrname (string) – HDRNAME keyword of HeaderletHDU

  • hdrext (int or tuple) – Headerlet extension number of tuple (‘HDRLET’,2)

  • archive (bool (default: True)) – When the distortion model in the headerlet is the same as the distortion model of the science file, this flag indicates if the primary WCS should be saved as an alternate nd a headerlet extension. When the distortion models do not match this flag indicates if the current primary and alternate WCSs should be archived as headerlet extensions and alternate WCS.

  • force (bool (default:False)) – When the distortion models of the headerlet and the primary do not match, and archive is False, this flag forces an update of the primary.

  • logging (bool) – enable file logging

  • logmode ('a' or 'w') –

stwcs.wcsutil.headerlet.update_ref_files(source, dest)

Update the reference files name in the primary header of ‘dest’ using values from ‘source’

Parameters:
stwcs.wcsutil.headerlet.update_versions(sourcehdr, desthdr)

Update keywords which store version numbers

stwcs.wcsutil.headerlet.verify_hdrname_is_unique(fobj, hdrname)

Verifies that no other HeaderletHDU extension has the specified hdrname.

Parameters:

  • fobj (str, astropy.io.fits.HDUList) – Name of FITS file or open fits file object

  • hdrname (str) – value of HDRNAME for HeaderletHDU to be compared as unique

Returns:

unique – If True, no other HeaderletHDU has the specified HDRNAME value

Return type:

bool

stwcs.wcsutil.headerlet.with_logging(func)
stwcs.wcsutil.headerlet.write_headerlet(filename, hdrname, output=None, sciext='SCI', wcsname=None, wcskey=None, destim=None, sipname=None, npolfile=None, d2imfile=None, author=None, descrip=None, history=None, nmatch=None, catalog=None, attach=True, clobber=False, logging=False)

Save a WCS as a headerlet FITS file.

This function will create a headerlet, write out the headerlet to a separate headerlet file, then, optionally, attach it as an extension to the science image (if it has not already been archived)

Either wcsname or wcskey must be provided; if both are given, they must match a valid WCS.

Updates wcscorr if necessary.

Parameters:

  • filename (string or HDUList or Python list) – This specifies the name(s) of science file(s) from which headerlets will be created and written out. String input formats supported include use of wild-cards, IRAF-style ‘@’-files (given as ‘@<filename>’) and comma-separated list of names. An input filename (str) will be expanded as necessary to interpret any environmental variables included in the filename.

  • hdrname (string) – Unique name for this headerlet, stored as HDRNAME keyword

  • output (string or None) – Filename or just rootname of output headerlet FITS file If string does not contain ‘.fits’, it will create a filename starting with the science filename and ending with ‘_hlet.fits’. If None, a default filename based on the input filename will be generated for the headerlet FITS filename

  • sciext (string) – name (EXTNAME) of extension that contains WCS to be saved

  • wcsname (string) – name of WCS to be archived, if “ “: stop

  • wcskey (one of A...Z or " " or "PRIMARY") – if “ “ or “PRIMARY” - archive the primary WCS

  • destim (string) – DESTIM keyword if NOne, use ROOTNAME or science file name

  • sipname (string or None (default)) – Name of unique file where the polynomial distortion coefficients were read from. If None, the behavior is: The code looks for a keyword ‘SIPNAME’ in the science header If not found, for HST it defaults to ‘IDCTAB’ If there is no SIP model the value is ‘NOMODEL’ If there is a SIP model but no SIPNAME, it is set to ‘UNKNOWN’

  • npolfile (string or None (default)) – Name of a unique file where the non-polynomial distortion was stored. If None: The code looks for ‘NPOLFILE’ in science header. If ‘NPOLFILE’ was not found and there is no npol model, it is set to ‘NOMODEL’ If npol model exists, it is set to ‘UNKNOWN’

  • d2imfile (string) – Name of a unique file where the detector to image correction was stored. If None: The code looks for ‘D2IMFILE’ in the science header. If ‘D2IMFILE’ is not found and there is no d2im correction, it is set to ‘NOMODEL’ If d2im correction exists, but ‘D2IMFILE’ is missing from science header, it is set to ‘UNKNOWN’

  • author (string) – Name of user who created the headerlet, added as ‘AUTHOR’ keyword to headerlet PRIMARY header

  • descrip (string) – Short description of the solution provided by the headerlet This description will be added as the single ‘DESCRIP’ keyword to the headerlet PRIMARY header

  • history (filename, string or list of strings) – Long (possibly multi-line) description of the solution provided by the headerlet. These comments will be added as ‘HISTORY’ cards to the headerlet PRIMARY header If filename is specified, it will format and attach all text from that file as the history.

  • attach (bool) – Specify whether or not to attach this headerlet as a new extension It will verify that no other headerlet extension has been created with the same ‘hdrname’ value.

  • clobber (bool) – If output file already exists, this parameter specifies whether or not to overwrite that file [Default: False]

  • logging (bool) – enable file logging