AstroHeader - EranOfek/AstroPack GitHub Wiki

Description

Class Hierarchy: Base -> Component -> AstroHeader

AstroHeader is a container class for astronomical images and catalog headers. A header contains triplets of: keyword, value, comment. Like all related classes, this class supports array of headers.

AstroHeader is contained within the <a href="https://github.com/EranOfek/AstroPack/wiki/AstroImage"AstroImage class.

The AstroHeader class allows the user to manipulate and query the headers.

Properties

Data - The Data property contains the actual header. This is stored as a 3 column cell array, in wich the columns correspond to key, val, and comment.
Key - This property contains a read-only copy of the header in a structure format (i.e., you can not update the header content by updating the structure). This is useful for quick access of the header by keyword.
File - File name from which the header was read.
HDU - HDU number from which the header originated.
KeyDict - A Dictionary object that contains keyword synonyms dictionary (e.g., 'EXPTIME', 'AEXPTIME' are synonyms of 'EXPTIME'). By default, this is read from the configuration file: Header.Synonyms.KeyNames.yml
ValDict - A Dictionary object that contains value synonyms dictionary (e.g., 'Dark', 'dark' are synonyms of 'Dark'). By default, this is read from the configuration file: Header.Synonyms.KeyVal.*.yml
CommentDict - A dictionary of default comments for select keywords. By default, this is read from the configuration file: Header.Comments.Default.yml
TimeDict - A dictionary object that allows identifying time-related keywords (e.g., 'OBS-DATE', 'JD', 'MJD',...) and translating them to JD. By default, this is stored in: Header.Time.KeyNames.yml

By default, all the dictionaries are uploaded from the Configuration files.

Methods

Static methods

createBasicHeader - Create an AstroHeader object with a basic header
unitTest - Test the AstroHeader class.

Examples

H = AstroHeader.createBasicHeader
% to view the header:
H.Data
% or
H.Key
% or
H.show

Read headers

To read headers from FITS file you can use the AstroHeader constructor:

H = AstroHeader('*.fits');

get keyword values

For quick and simple access you can use the Key property in the AstroHeader object.

H = AstroHeader.createBasicHeader;
H.Key.EXPTIME

The getVal can be used to get a single keyword value where the keyword appears first in a dictionary.

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
[Val, Key, Comment, Nfound] = getVal(H, 'EXPTIME')
[Val, Key, Comment, Nfound] = getVal(H, 'AEXPTIME','IsInputAlt',true)
[Val, Key, Comment, Nfound] = getVal(H, 'AEXPTIME'); % return NaN
[Val, Key, Comment, Nfound] = getVal(H, {'BB','EXPTIME','AA'})
[Val, Key, Comment, Nfound] = getVal(H, 'EXPTIME','UseDict',false)
[Val, Key, Comment, Nfound] = getVal(H, 'AEXPTIME','UseDict',false)

In order to get multiple keys from multiple headers, in structure format, you can use the getStructKey method.

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
[Result,C] = getStructKey(H, {'EXPTIME'})
[Result,C] = getStructKey(H, {'EXPTIME','A'})
[Result,C] = getStructKey(H, {'EXPTIME','A'},'UseDict',false)

The getCellKey stores the output in a cell array.

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
[Result,IK] = getCellKey([H,H], {'EXPTIME','bb'},'UseDict',false)
[Result,IK] = getCellKey([H,H], {'EXPTIME','bb'})
[Result,IK] = getCellKey([H,H], {'AEXPTIME','bb'})

Update the header

Given a header you can populate the keywords with default comments:

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
H.insertDefaultComments;

To delete keywords:

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
deleteKey(H,{'EXPTIME','A','COMMENT'})
% you can also use regular expressions:
deleteKey(H,{'EXPTIME','A','SKYSUB\d'})

Insert new keys: H=AstroHeader('WFPC2ASSNu5780205bx.fits'); % create a new key 'stam' H.insertKey('stam'); % Insert new keys 'A' and 'B' with some values. % end-1 indicate the position at which to insert the keys: H.insertKey({'A',1,'';'B','',''},'end-1')


To replace the value of existing keyword, you can use the _replaceVal_ method:
```matlab
H=AstroHeader('WFPC2ASSNu5780205bx.fits');
H.replaceVal({'COMMENT'},{''});

Additional functions includes:

deleteComments - delete comments from header.
deleteDistortionsWCS - delete WCS distortion keywords from header.

Check keywords and their value

isKeyVal - Check if a single keyword value equal to some value.
isKeyExist - Check if a single keyword value equal to some value.
isImType - Check if header IMTYPE keyword value equal some type

Examples

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
isKeyVal([H, H],'EXPTIME',300)
isKeyVal([H;H], 'KSPOTS','off')
isKeyVal([H;H], 'KSPOTS','off','ValCaseSens',true)

isKeyExist([H, H],'EXPTIME')
isKeyExist([H, H],'AEXPTIME')
isKeyExist([H; H],'AEXPTIME','IsInputAlt',true)
isKeyExist([H, H],'aaa')

H=AstroHeader('*.fits');
Ans = isImType(H, 'bias')
Ans = isImType(H, 'bias','CaseSens',false,'IsInputAlt',false)

Time

The AstroHeader julday method can be used to calculate mid-exposure JD and ExpTime for AstroHeader object. Given the header keywords, attempt calculating the mid-JD of the exposure. This is done by retrieving the relevant header keywords (default in config/Header.Time.KeyNames.yml). Each keyword is associated with conversion formulae.

Examples:

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
[JD,ExpTime] = julday(H)
[JD,ExpTime] = julday([H;H])

Group headers by keyword values

The groupByKeyVal method can be used to group a set of AstroHeaders by their unique keyword values. E.g., look for all images with the same EXPTIME and put them in different groups according to the EXPTIME value.

H=AstroHeader('WFPC2ASSNu5780205bx.fits');
Groups = groupByKeyVal([H,H],{'IMTYPE','FILTER1','EXPTIME'})

Get special keys

getObsCoo - Get Observatory geodetic position from Header
getCoo - get RA/Dec coordinates from the header.
selectKeys - Select a sub header from header, by keys.

Conversion to table

header2table - Convert an array of AstroHeader to a table/cell/AstroTable/AstroCatalog in which each column shows the same key for all headers.

Internal use functions

funUnary