punchbowl.data#

Submodules#

Classes#

History

Representation of the history of edits done to a PUNCH data object.

NormalizedMetadata

Represent Metadata consistently.

Functions#

get_base_file_name(→ str)

Determine the base file name without file type extension.

load_ndcube_from_fits(→ ndcube.NDCube)

Load an NDCube from a FITS file.

write_ndcube_to_fits(→ None)

Write an NDCube as a FITS file.

write_ndcube_to_quicklook(→ None)

Write an NDCube to a Quicklook format as a jpeg.

load_trefoil_wcs(→ tuple[astropy.wcs.WCS, tuple[int, int]])

Load Level 2 trefoil world coordinate system and shape.

Package Contents#

class punchbowl.data.History#

Representation of the history of edits done to a PUNCH data object.

_entries: list[HistoryEntry] = []#
add_entry(entry: HistoryEntry) → None#

Add an entry to the History log.

Parameters:

entry (HistoryEntry) – A HistoryEntry object to add to the History log

Return type:

None

add_now(source: str, comment: str) → None#

Add a new history entry at the current time.

Parameters:

  • source (str) – what module of the code the history entry originates from

  • comment (str) – a note of what the history comment means

Return type:

None

clear() → None#

Clear all the history entries so the History is blank.

Return type:

None

__getitem__(index: int) → HistoryEntry#

Given an index, return the requested HistoryEntry.

Parameters:

index (int) – numerical index of the history entry, increasing number typically indicates an older entry

Returns:

history at specified index

Return type:

HistoryEntry

most_recent() → HistoryEntry#

Get the most recent HistoryEntry, i.e. the youngest.

Returns:

returns HistoryEntry that is the youngest

Return type:

HistoryEntry

__len__() → int#

Get length.

__str__() → str#

Format a string combining all the history entries.

Returns:

a combined record of the history entries

Return type:

str

__iter__() → History#

Iterate.

__next__() → HistoryEntry#

Get next.

__eq__(other: History) → bool#

Check equality of two History objects.

classmethod from_fits_header(head: astropy.io.fits.Header) → History#

Construct a history from a FITS header.

Parameters:

head (Header) – a FITS header to read from

Returns:

the history derived from a given FITS header

Return type:

History

class punchbowl.data.NormalizedMetadata(contents: OrderedDict[str, OrderedDict[str, MetaField]], history: punchbowl.data.history.History | None = None, provenance: list[str] | None = None, wcs_section_name: str = 'World Coordinate System')#

Bases: collections.abc.Mapping

Represent Metadata consistently.

The NormalizedMetadata object standardizes metadata and metadata access in the PUNCH pipeline. It does so by uniting the history and header fields while providing helpful accessors for commonly used formats of the metadata.

Internally, the keys are always stored as FITS compliant upper-case strings. These are stored in sections. So the contents dictionary should have a key of a section title mapped to a dictionary of field keys mapped to MetaFields.

__len__() → int#

Return number of entry cards in NormalizedMetadata object.

_contents#
_history = None#
_provenance = None#
_wcs_section_name = 'World Coordinate System'#
keys() → Iterable[str]#

Return FITS keys for collection.

__iter__() → Iterator[Any]#

Iterate.

__eq__(other: NormalizedMetadata) → bool#

Check equality.

to_fits_header(wcs: astropy.wcs.WCS | None = None, write_celestial_wcs: bool = True) → astropy.io.fits.Header#

Convert a constructed NormalizedMetdata object to an Astropy FITS compliant header object.

Returns:

Astropy FITS compliant header object

Return type:

Header

delete_section(section_name: str) → None#

Delete a section of NormalizedMetadata.

Parameters:

section_name (str) – the section to delete

Return type:

None

classmethod from_fits_header(h: astropy.io.fits.Header) → NormalizedMetadata#

Construct a normalized Metadata from a PUNCH FITS header.

Parameters:

h (Header) – a PUNCH FITS header from Astropy

Returns:

the corresponding NormalizedMetadata

Return type:

NormalizedMetadata

static _match_product_code_in_level_spec(product_code: str, level_spec: dict) → dict#

Parse the specified product code and level specification to find a corresponding set.

Parameters:

  • product_code – Specified data product code

  • level_spec – Data product level specifications, loaded from load_level_spec

Returns:

Product code specification parsed from file

Return type:

Dict

static _load_template_files(omniheader_path: str, level: str, level_spec_path: str, spacecraft: str, spacecraft_def_path: str) → tuple[dict, dict, dict]#

Load template files from specified locations.

Parameters:

  • omniheader_path – Path to full omniheader specifications

  • level – Specified data product level

  • level_spec_path – Path to data product level specifications

  • spacecraft – Specified spacecraft code

  • spacecraft_def_path – Path to spacecraft specifications

Returns:

Header specification entries

Return type:

Tuple

static _determine_omits_and_overrides(level_spec: dict, product_def: dict) → tuple[list[str], dict[str, str]]#

Read level specifications and product definitions and determines keywords to omit or overwrite.

Parameters:

  • level_spec – Data product level specifications

  • product_def – Data product specifications

Returns:

Keywords and values to omit and override

Return type:

Tuple

classmethod load_template(product_code: str, level: str | None = None, level_spec_path: str | None = None, omniheader_path: str | None = None, spacecraft_def_path: str | None = None) → NormalizedMetadata#

Given data product specification, loads relevant template files and constructs a NormalizedMetadata object.

Parameters:

  • product_code – Specified data product code, a three character code like PM1

  • level – Specified data product level

  • level_spec_path – Path to data product level specifications

  • omniheader_path – Path to full omniheader specifications

  • spacecraft_def_path – Path to spacecraft specifications

Returns:

Constructed NormalizedMetadata object from template specifications

Return type:

NormalizedMetadata

property sections: list[str]#

Returns header sections.

property fits_keys: list[str]#

Returns fits keys in header template.

property history: punchbowl.data.history.History#

Returns header history.

property provenance: list[str]#

Returns file provenance.

static _validate_key_is_str(key: str) → None#

Validate that the provided key is a valid header keyword string.

Parameters:

key – Header key string

Return type:

None

__setitem__(key: str, value: Any) → None#

Set specified pair of keyword and value in the NormalizedMetadata object.

Parameters:

  • key – Header key string

  • value – Header value

Return type:

None

get(key: str | tuple[str, int], default: Any | None = None) → Any#

Get a value given a key or use a default value.

__getitem__(key: str | tuple[str, int]) → Any#

Get specified keyword from NormalizedMetadata object.

Parameters:

key (str | tuple) – Header key string

Returns:

Returned header value

Return type:

t.Any

__delitem__(key: str) → None#

Delete specified keyword entry from the NormalizedMetadata object.

Parameters:

key – Header key string

Return type:

None

__contains__(key: str) → bool#

Determine if the specified keyword is contained within the NormalizedMetadata object.

Parameters:

key – Header key string

Returns:

Value indicating if the specified keyword is contained within the NormalizedMetadata object

Return type:

Boolean

property product_level: int#

Returns data product level if indicated in metadata.

property datetime: datetime.datetime#

Returns a datetime representation of the ‘DATE-OBS’ header keyword if indicated in metadata.

property shape: tuple#

Get the data shape in array order.

property astropy_time: astropy.time.Time#

Get the date-obs as an astropy Time object.

property product_code: str#

“Retrieve the product code.

punchbowl.data.get_base_file_name(cube: ndcube.NDCube) → str#

Determine the base file name without file type extension.

punchbowl.data.load_ndcube_from_fits(path: str | pathlib.Path, key: str = ' ', include_provenance: bool = True) → ndcube.NDCube#

Load an NDCube from a FITS file.

punchbowl.data.write_ndcube_to_fits(cube: ndcube.NDCube, filename: str, overwrite: bool = False, write_hash: bool = True, skip_stats: bool = False, uncertainty_quantize_level: float = 16) → None#

Write an NDCube as a FITS file.

punchbowl.data.write_ndcube_to_quicklook(cube: ndcube.NDCube, filename: str, layer: int | None = None, vmin: float = 1e-15, vmax: float = 8e-13, annotation: str | None = None) → None#

Write an NDCube to a Quicklook format as a jpeg.

Parameters:

  • cube (NDCube) – data cube to visualize

  • filename (str) – path to save output, must end in .jp2, .j2k, .jpeg, .jpg

  • layer (int | None) – if the cube is 3D, then selects cube.data[layer] for visualization

  • vmin (float) – the lower limit value to visualize

  • vmax (float) – the upper limit value to visualize

  • annotation (str | None) – a formatted string to add to the bottom of the image as a label can access metadata by key, e.g. “typecode={TYPECODE}” would write the data’s typecode into the image

Return type:

None

punchbowl.data.load_trefoil_wcs() → tuple[astropy.wcs.WCS, tuple[int, int]]#

Load Level 2 trefoil world coordinate system and shape.