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. Useopen()
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 toHDUList.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
, andndarray
. It should be noted that if that memory is read-only (such as a Python string) the returnedHDUList
’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
- 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 toTrue
, 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:
- Returns:
hlet – A
HeaderletHDU
object for the givenHeaderlet
that can be attached as an extension to an existingHDUList
.- Return type:
- 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:
- 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:
fobj (str,
astropy.io.fits.HDUList
)kw (str) – Name of keyword to be read and reported
- 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 orastropy.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 inputfname (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:
source (
astropy.io.fits.Header
)dest (
astropy.io.fits.Header
)
- 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 objecthdrname (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:
- 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