GUPPIHeader¶
-
class
baseband.guppi.
GUPPIHeader
(*args, **kwargs)[source] [edit on github]¶ Bases:
astropy.io.fits.Header
GUPPI baseband file format header.
Parameters: *args : str or iterable
If a string, parsed as a GUPPI header from a file, otherwise as for the
astropy.io.fits.Header
baseclass.verify : bool, optional
Whether to do minimal verification that the header is consistent with the GUPPI standard. Default:
True
.mutable : bool, optional
Whether to allow the header to be changed after initialisation. Default:
True
.**kwargs
Any further header keywords to be set.
Notes
Like
Header
, the initialiser does not accept keyword arguments to populate an array - instead, one must pass an iterable. In order to ensure keywords are kept in the right order, one should pass on values as a tuple, not as a dict. E.g., to copy a header, one should not doGUPPIHeader({key: header[key] for key in header})
, but rather:GUPPIHeader(((key, header[key]) for key in header))
or, to also keep the comments:
GUPPIHeader(((key, (header[key], header.comments[key])) for key in header))
Attributes Summary
bps
Bits per elementary sample. cards
The underlying physical cards that make up this Header; it can be looked at, but it should not be modified directly. channels_first
True if encoded payload ordering is (nchan, nsample, npol). comments
View the comments associated with each keyword, if any. complex_data
Whether the data are complex. frame_nbytes
Size of the frame in bytes. nbytes
Size of the header in bytes. nchan
Number of channels. npol
Number of polarisations. offset
Offset from start of observation in units of time. overlap
Number of complete samples that overlap with the next frame. payload_nbytes
Size of the payload in bytes. sample_rate
Number of complete samples per second. sample_shape
Shape of a sample in the payload (npol, nchan). samples_per_frame
Number of complete samples in the frame, including overlap. sideband
True if upper sideband. start_time
Start time of the observation. time
Start time of the part of the observation covered by this header. Methods Summary
add_blank
([value, before, after])Add a blank card. add_comment
(value[, before, after])Add a COMMENT
card.add_history
(value[, before, after])Add a HISTORY
card.append
([card, useblanks, bottom, end])Appends a new keyword+value card to the end of the Header, similar to list.append
.clear
()Remove all cards from the header. copy
()Create a mutable and independent copy of the header. count
(keyword)Returns the count of the given keyword in the header, similar to list.count
if the Header object is treated as a list of keywords.extend
(cards[, strip, unique, update, …])Appends multiple keyword+value cards to the end of the header, similar to list.extend
.fromfile
(fh[, verify])Reads in GUPPI header block from a file. fromkeys
(*args, **kwargs)Initialise a header from keyword values. fromstring
(data[, sep])Creates an HDU header from a byte string containing the entire header data. fromtextfile
(fileobj[, endcard])Read a header from a simple text file or file-like object. fromvalues
(**kwargs)Initialise a header from parsed values. get
(key[, default])Similar to dict.get()
–returns the value associated with keyword in the header, or a default value if the keyword is not found.index
(keyword[, start, stop])Returns the index if the first instance of the given keyword in the header, similar to list.index
if the Header object is treated as a list of keywords.insert
(key, card[, useblanks, after])Inserts a new keyword+value card into the Header at a given location, similar to list.insert
.items
()Like dict.items()
.iteritems
()Like dict.iteritems()
.iterkeys
()Like dict.iterkeys()
–iterating directly over theHeader
instance has the same behavior.itervalues
()Like dict.itervalues()
.keys
()Return a list of keywords in the header in the order they appear–like dict.keys()
but ordered.pop
(*args)Works like list.pop()
if no arguments or an index argument are supplied; otherwise works likedict.pop()
.popitem
()Similar to dict.popitem()
.remove
(keyword[, ignore_missing, remove_all])Removes the first instance of the given keyword from the header similar to list.remove
if the Header object is treated as a list of keywords.rename_keyword
(oldkeyword, newkeyword[, force])Rename a card’s keyword in the header. set
(keyword[, value, comment, before, after])Set the value and/or comment and/or position of a specified keyword. setdefault
(key[, default])Similar to dict.setdefault()
.tofile
(fh)Write GUPPI file header to filehandle. tostring
([sep, endcard, padding])Returns a string representation of the header. totextfile
(**kwargs)Write the header as text to a file or a file-like object. update
(**kwargs)Update the header with new values. values
()Returns a list of the values of all cards in the header. verify
()Basic check of integrity. Attributes Documentation
-
bps
¶ Bits per elementary sample.
-
cards
¶ The underlying physical cards that make up this Header; it can be looked at, but it should not be modified directly.
-
channels_first
¶ True if encoded payload ordering is (nchan, nsample, npol).
-
comments
¶ View the comments associated with each keyword, if any.
For example, to see the comment on the NAXIS keyword:
>>> header.comments['NAXIS'] number of data axes
Comments can also be updated through this interface:
>>> header.comments['NAXIS'] = 'Number of data axes'
-
complex_data
¶ Whether the data are complex.
-
frame_nbytes
¶ Size of the frame in bytes.
-
nbytes
¶ Size of the header in bytes.
-
nchan
¶ Number of channels.
-
npol
¶ Number of polarisations.
-
offset
¶ Offset from start of observation in units of time.
-
overlap
¶ Number of complete samples that overlap with the next frame.
-
payload_nbytes
¶ Size of the payload in bytes.
-
sample_rate
¶ Number of complete samples per second.
Can be set with a negative quantity to set
sideband
. Overlap samples are not included in the rate.
-
sample_shape
¶ Shape of a sample in the payload (npol, nchan).
-
samples_per_frame
¶ Number of complete samples in the frame, including overlap.
-
sideband
¶ True if upper sideband.
-
start_time
¶ Start time of the observation.
-
time
¶ Start time of the part of the observation covered by this header.
Methods Documentation
-
add_blank
(value='', before=None, after=None) [edit on github]¶ Add a blank card.
Parameters: value : str, optional
Text to be added.
before : str or int, optional
Same as in
Header.update
after : str or int, optional
Same as in
Header.update
-
add_comment
(value, before=None, after=None) [edit on github]¶ Add a
COMMENT
card.Parameters: value : str
Text to be added.
before : str or int, optional
Same as in
Header.update
after : str or int, optional
Same as in
Header.update
-
add_history
(value, before=None, after=None) [edit on github]¶ Add a
HISTORY
card.Parameters: value : str
History text to be added.
before : str or int, optional
Same as in
Header.update
after : str or int, optional
Same as in
Header.update
-
append
(card=None, useblanks=True, bottom=False, end=False) [edit on github]¶ Appends a new keyword+value card to the end of the Header, similar to
list.append
.By default if the last cards in the Header have commentary keywords, this will append the new keyword before the commentary (unless the new keyword is also commentary).
Also differs from
list.append
in that it can be called with no arguments: In this case a blank card is appended to the end of the Header. In the case all the keyword arguments are ignored.Parameters: card : str, tuple
A keyword or a (keyword, value, [comment]) tuple representing a single header card; the comment is optional in which case a 2-tuple may be used
useblanks : bool, optional
If there are blank cards at the end of the Header, replace the first blank card so that the total number of cards in the Header does not increase. Otherwise preserve the number of blank cards.
bottom : bool, optional
If True, instead of appending after the last non-commentary card, append after the last non-blank card.
end : bool, optional
If True, ignore the useblanks and bottom options, and append at the very end of the Header.
-
clear
() [edit on github]¶ Remove all cards from the header.
-
copy
()[source] [edit on github]¶ Create a mutable and independent copy of the header.
-
count
(keyword) [edit on github]¶ Returns the count of the given keyword in the header, similar to
list.count
if the Header object is treated as a list of keywords.Parameters: keyword : str
The keyword to count instances of in the header
-
extend
(cards, strip=True, unique=False, update=False, update_first=False, useblanks=True, bottom=False, end=False) [edit on github]¶ Appends multiple keyword+value cards to the end of the header, similar to
list.extend
.Parameters: cards : iterable
An iterable of (keyword, value, [comment]) tuples; see
Header.append
.strip : bool, optional
Remove any keywords that have meaning only to specific types of HDUs, so that only more general keywords are added from extension Header or Card list (default:
True
).unique : bool, optional
If
True
, ensures that no duplicate keywords are appended; keywords already in this header are simply discarded. The exception is commentary keywords (COMMENT, HISTORY, etc.): they are only treated as duplicates if their values match.update : bool, optional
If
True
, update the current header with the values and comments from duplicate keywords in the input header. This supercedes theunique
argument. Commentary keywords are treated the same as ifunique=True
.update_first : bool, optional
If the first keyword in the header is ‘SIMPLE’, and the first keyword in the input header is ‘XTENSION’, the ‘SIMPLE’ keyword is replaced by the ‘XTENSION’ keyword. Likewise if the first keyword in the header is ‘XTENSION’ and the first keyword in the input header is ‘SIMPLE’, the ‘XTENSION’ keyword is replaced by the ‘SIMPLE’ keyword. This behavior is otherwise dumb as to whether or not the resulting header is a valid primary or extension header. This is mostly provided to support backwards compatibility with the old
Header.fromTxtFile
method, and only applies ifupdate=True
.useblanks, bottom, end : bool, optional
These arguments are passed to
Header.append()
while appending new cards to the header.
-
classmethod
fromfile
(fh, verify=True)[source] [edit on github]¶ Reads in GUPPI header block from a file.
Parameters: fh : filehandle
To read data from.
verify: bool, optional
Whether to do basic checks on whether the header is valid. Verify is automatically called by
fromstring
, so this flag exists only to standardize the API.
-
classmethod
fromkeys
(*args, **kwargs)[source] [edit on github]¶ Initialise a header from keyword values.
Like fromvalues, but without any interpretation of keywords.
This extracts ‘verify’ and ‘mutable’, then passes the remaining kwargs to the class initializer as a dict (for compatibility with fits.Header). It is present for compatibility with other header classes only.
-
classmethod
fromstring
(data, sep='') [edit on github]¶ Creates an HDU header from a byte string containing the entire header data.
Parameters: data : str
String containing the entire header.
sep : str, optional
The string separating cards from each other, such as a newline. By default there is no card separator (as is the case in a raw FITS file).
Returns: header
A new
Header
instance.
-
classmethod
fromtextfile
(fileobj, endcard=False) [edit on github]¶ Read a header from a simple text file or file-like object.
Equivalent to:
>>> Header.fromfile(fileobj, sep='\n', endcard=False, ... padding=False)
See also
-
classmethod
fromvalues
(**kwargs)[source] [edit on github]¶ Initialise a header from parsed values.
Here, the parsed values must be given as keyword arguments, i.e., for any
header
,cls.fromvalues(**header) == header
.However, unlike for the
fromkeys
class method, data can also be set using arguments named after header methods, such astime
.Furthermore, some header defaults are set in
GUPPIHeader._defaults
.
-
get
(key, default=None) [edit on github]¶ Similar to
dict.get()
–returns the value associated with keyword in the header, or a default value if the keyword is not found.Parameters: key : str
A keyword that may or may not be in the header.
default : optional
A default value to return if the keyword is not found in the header.
Returns: value
The value associated with the given keyword, or the default value if the keyword is not in the header.
-
index
(keyword, start=None, stop=None) [edit on github]¶ Returns the index if the first instance of the given keyword in the header, similar to
list.index
if the Header object is treated as a list of keywords.Parameters: keyword : str
The keyword to look up in the list of all keywords in the header
start : int, optional
The lower bound for the index
stop : int, optional
The upper bound for the index
-
insert
(key, card, useblanks=True, after=False) [edit on github]¶ Inserts a new keyword+value card into the Header at a given location, similar to
list.insert
.Parameters: key : int, str, or tuple
The index into the list of header keywords before which the new keyword should be inserted, or the name of a keyword before which the new keyword should be inserted. Can also accept a (keyword, index) tuple for inserting around duplicate keywords.
card : str, tuple
A keyword or a (keyword, value, [comment]) tuple; see
Header.append
useblanks : bool, optional
If there are blank cards at the end of the Header, replace the first blank card so that the total number of cards in the Header does not increase. Otherwise preserve the number of blank cards.
after : bool, optional
-
items
() [edit on github]¶ Like
dict.items()
.
-
iteritems
() [edit on github]¶ Like
dict.iteritems()
.
-
iterkeys
() [edit on github]¶ Like
dict.iterkeys()
–iterating directly over theHeader
instance has the same behavior.
-
itervalues
() [edit on github]¶ Like
dict.itervalues()
.
-
keys
() [edit on github]¶ Return a list of keywords in the header in the order they appear–like
dict.keys()
but ordered.
-
pop
(*args) [edit on github]¶ Works like
list.pop()
if no arguments or an index argument are supplied; otherwise works likedict.pop()
.
-
popitem
() [edit on github]¶ Similar to
dict.popitem()
.
-
remove
(keyword, ignore_missing=False, remove_all=False) [edit on github]¶ Removes the first instance of the given keyword from the header similar to
list.remove
if the Header object is treated as a list of keywords.Parameters: keyword : str
The keyword of which to remove the first instance in the header.
ignore_missing : bool, optional
When True, ignores missing keywords. Otherwise, if the keyword is not present in the header a KeyError is raised.
remove_all : bool, optional
When True, all instances of keyword will be removed. Otherwise only the first instance of the given keyword is removed.
-
rename_keyword
(oldkeyword, newkeyword, force=False) [edit on github]¶ Rename a card’s keyword in the header.
Parameters: oldkeyword : str or int
Old keyword or card index
newkeyword : str
New keyword
force : bool, optional
When
True
, if the new keyword already exists in the header, force the creation of a duplicate keyword. Otherwise aValueError
is raised.
-
set
(keyword, value=None, comment=None, before=None, after=None) [edit on github]¶ Set the value and/or comment and/or position of a specified keyword.
If the keyword does not already exist in the header, a new keyword is created in the specified position, or appended to the end of the header if no position is specified.
This method is similar to
Header.update()
prior to Astropy v0.1.Note
It should be noted that
header.set(keyword, value)
andheader.set(keyword, value, comment)
are equivalent toheader[keyword] = value
andheader[keyword] = (value, comment)
respectively.New keywords can also be inserted relative to existing keywords using, for example:
>>> header.insert('NAXIS1', ('NAXIS', 2, 'Number of axes'))
to insert before an existing keyword, or:
>>> header.insert('NAXIS', ('NAXIS1', 4096), after=True)
to insert after an existing keyword.
The only advantage of using
Header.set()
is that it easily replaces the old usage ofHeader.update()
both conceptually and in terms of function signature.Parameters: keyword : str
A header keyword
value : str, optional
The value to set for the given keyword; if None the existing value is kept, but ‘’ may be used to set a blank value
comment : str, optional
The comment to set for the given keyword; if None the existing comment is kept, but
''
may be used to set a blank commentbefore : str, int, optional
Name of the keyword, or index of the
Card
before which this card should be located in the header. The argumentbefore
takes precedence overafter
if both specified.after : str, int, optional
Name of the keyword, or index of the
Card
after which this card should be located in the header.
-
setdefault
(key, default=None) [edit on github]¶ Similar to
dict.setdefault()
.
-
tofile
(fh)[source] [edit on github]¶ Write GUPPI file header to filehandle.
Uses
tostring
.
-
tostring
(sep='', endcard=True, padding=True) [edit on github]¶ Returns a string representation of the header.
By default this uses no separator between cards, adds the END card, and pads the string with spaces to the next multiple of 2880 bytes. That is, it returns the header exactly as it would appear in a FITS file.
Parameters: sep : str, optional
The character or string with which to separate cards. By default there is no separator, but one could use
'\\n'
, for example, to separate each card with a new lineendcard : bool, optional
If True (default) adds the END card to the end of the header string
padding : bool, optional
If True (default) pads the string with spaces out to the next multiple of 2880 characters
Returns: s : str
A string representing a FITS header.
-
totextfile
(**kwargs) [edit on github]¶ Write the header as text to a file or a file-like object.
Equivalent to:
>>> Header.tofile(fileobj, sep='\n', endcard=False, ... padding=False, overwrite=overwrite)
Changed in version 1.3:
overwrite
replaces the deprecatedclobber
argument.See also
-
update
(**kwargs)[source] [edit on github]¶ Update the header with new values.
Here, any keywords matching properties are processed as well, in the order set by the class (in
_properties
), and after all other keywords have been processed.Parameters: verify : bool, optional
If
True
(default), verify integrity after updating.**kwargs
Arguments used to set keywords and properties.
-
values
() [edit on github]¶ Returns a list of the values of all cards in the header.
-
verify
()[source] [edit on github]¶ Basic check of integrity.
-