class baseband.guppi.GUPPIHeader(*args, verify=True, mutable=True, **kwargs)[source] [edit on github]

Parameters
*argsstr or iterable

If a string, parsed as a GUPPI header from a file, otherwise as for the astropy.io.fits.Header baseclass.

verifybool, optional

Whether to do minimal verification that the header is consistent with the GUPPI standard. Default: True.

mutablebool, 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 do GUPPIHeader({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]))


Construct a Header from an iterable and/or text file.

Parameters
cardsA list of Card objects, optional

The cards to initialize the header with. Also allowed are other Header (or dict-like) objects.

Changed in version 1.2: Allowed cards to be a dict-like object.

copybool, optional

If True copies the cards if they were another Header instance. Default is False.

New in version 1.3.

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. supported_formats GUPPI formats that are known to work. 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. Remove all cards from the header. 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[, verify, mutable]) 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. Like dict.keys()–iterating directly over the Header instance has the same behavior. pop(*args) Works like list.pop() if no arguments or an index argument are supplied; otherwise works like dict.pop(). 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(fileobj[, endcard, overwrite]) Write the header as text to a file or a file-like object. update(*[, verify]) Update the header with new values. 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.

supported_formats = {'1SFA', 'SIMPLE'}

GUPPI formats that are known to work.

‘1SFA’ is used for all modes other than FAST4K (which is only used for total intensity). ‘SIMPLE’ is from DSPSR, and used to support time-first payloads. See https://safe.nrao.edu/wiki/pub/Main/JoeBrandt/guppi_status_shmem.pdf

If a format is not in this set, yet is known to work, a PR would be most welcome.

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]

Parameters
valuestr, optional

beforestr or int, optional

Same as in Header.update

afterstr or int, optional

Same as in Header.update

add_comment(value, before=None, after=None) [edit on github]

Add a COMMENT card.

Parameters
valuestr

beforestr or int, optional

Same as in Header.update

afterstr or int, optional

Same as in Header.update

add_history(value, before=None, after=None) [edit on github]

Add a HISTORY card.

Parameters
valuestr

beforestr or int, optional

Same as in Header.update

afterstr 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
cardstr, 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

useblanksbool, 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.

bottombool, optional

If True, instead of appending after the last non-commentary card, append after the last non-blank card.

endbool, 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
keywordstr

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
cardsiterable

An iterable of (keyword, value, [comment]) tuples; see Header.append.

stripbool, 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).

uniquebool, 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.

updatebool, optional

If True, update the current header with the values and comments from duplicate keywords in the input header. This supersedes the unique argument. Commentary keywords are treated the same as if unique=True.

update_firstbool, 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 if update=True.

useblanks, bottom, endbool, optional

These arguments are passed to Header.append() while appending new cards to the header.

classmethod fromfile(fh, verify=True)[source] [edit on github]

Parameters
fhfilehandle

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, verify=True, mutable=True, **kwargs)[source] [edit on github]

Initialise a header from keyword values.

Like fromvalues, but without any interpretation of keywords.

Note that this just passes 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
datastr or bytes

String or bytes containing the entire header. In the case of bytes they will be decoded using latin-1 (only plain ASCII characters are allowed in FITS headers but latin-1 allows us to retain any invalid bytes that might appear in malformatted FITS files).

sepstr, 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). In general this is only used in cases where a header was printed as text (e.g. with newlines after each card) and you want to create a new Header from it by copy/pasting.

Returns

A new Header instance.

Examples

>>> from astropy.io.fits import Header
True


If you want to create a Header from printed text it’s not necessary to have the exact binary structure as it would appear in a FITS file, with the full 80 byte card length. Rather, each “card” can end in a newline and does not have to be padded out to a full card length as long as it “looks like” a FITS header:

>>> hdr = Header.fromstring("""\
... SIMPLE  =                    T / conforms to FITS standard
... BITPIX  =                    8 / array data type
... NAXIS   =                    0 / number of array dimensions
... EXTEND  =                    T
... """, sep='\n')
>>> hdr['SIMPLE']
True
>>> hdr['BITPIX']
8
>>> len(hdr)
4

classmethod fromtextfile(fileobj, endcard=False) [edit on github]

Equivalent to:

>>> Header.fromfile(fileobj, sep='\n', endcard=False,

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 as time.

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
keystr

A keyword that may or may not be in the header.

defaultoptional

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
keywordstr

The keyword to look up in the list of all keywords in the header

startint, optional

The lower bound for the index

stopint, 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
keyint, 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.

cardstr, tuple

A keyword or a (keyword, value, [comment]) tuple; see Header.append

useblanksbool, 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.

afterbool, optional

If set to True, insert after the specified index or keyword, rather than before it. Defaults to False.

items() [edit on github]
keys() [edit on github]

Like dict.keys()–iterating directly over the Header instance has the same behavior.

pop(*args) [edit on github]

Works like list.pop() if no arguments or an index argument are supplied; otherwise works like dict.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
keywordstr

The keyword of which to remove the first instance in the header.

ignore_missingbool, optional

When True, ignores missing keywords. Otherwise, if the keyword is not present in the header a KeyError is raised.

remove_allbool, 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
oldkeywordstr or int

Old keyword or card index

newkeywordstr

New keyword

forcebool, optional

When True, if the new keyword already exists in the header, force the creation of a duplicate keyword. Otherwise a ValueError 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) and header.set(keyword, value, comment) are equivalent to header[keyword] = value and header[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 of Header.update() both conceptually and in terms of function signature.

Parameters
keywordstr

valuestr, 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

The comment to set for the given keyword; if None the existing comment is kept, but '' may be used to set a blank comment

beforestr, int, optional

Name of the keyword, or index of the Card before which this card should be located in the header. The argument before takes precedence over after if both specified.

afterstr, 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
sepstr, 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 line

endcardbool, optional

If True (default) adds the END card to the end of the header string

If True (default) pads the string with spaces out to the next multiple of 2880 characters

Returns
sstr

A string representing a FITS header.

totextfile(fileobj, endcard=False, overwrite=False) [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,


Changed in version 1.3: overwrite replaces the deprecated clobber argument.

update(*, verify=True, **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
verifybool, optional

If True (default), verify integrity after updating.

**kwargs

Arguments used to set keywords and properties.

values() [edit on github]
verify()[source] [edit on github]

Basic check of integrity.