punchbowl.data.meta#

Attributes#

`ValueType`
`_ROOT`
`REQUIRED_HEADER_KEYWORDS`
`WCS_OMITTED_KEYWORDS`
`DateLike`

Classes#

`MetaField`	The MetaField object describes a single field within the NormalizedMetadata object.
`NormalizedMetadata`	Represent Metadata consistently.

Functions#

`load_omniheader`(→ pandas.DataFrame)	Load full metadata specifications.
`load_level_spec`(→ dict[str, Any])	Load data product metadata specifications.
`load_spacecraft_def`(→ dict[str, Any])	Load spacecraft metadata specifications.
`construct_all_product_codes`(→ list[str])	Generate all data product codes.
`set_spacecraft_location_to_earth`(→ ndcube.NDCube)	Update the spacecraft location metadata.
`check_moon_in_fov`(→ tuple[list[datetime.datetime], ...)	Forecast the moon in PUNCH FOV in a given time range.

Module Contents#

punchbowl.data.meta.ValueType#

punchbowl.data.meta._ROOT = b'.'#

punchbowl.data.meta.REQUIRED_HEADER_KEYWORDS = ['SIMPLE', 'BITPIX', 'NAXIS', 'EXTEND']#

punchbowl.data.meta.WCS_OMITTED_KEYWORDS = ['TIMESYS', 'DATE-OBS', 'DATE-BEG', 'DATE-AVG', 'DATE-END', 'TELAPSE', 'RSUN_REF', 'DSUN_OBS',...#

punchbowl.data.meta.load_omniheader(path: str | None = None) → pandas.DataFrame[source]#: Load full metadata specifications.

punchbowl.data.meta.load_level_spec(path: str) → dict[str, Any][source]#: Load data product metadata specifications.

punchbowl.data.meta.load_spacecraft_def(path: str | None = None) → dict[str, Any][source]#

Load spacecraft metadata specifications.

If path is None, then it loads a default from the package.

punchbowl.data.meta.construct_all_product_codes(level: str) → list[str][source]#: Generate all data product codes.

class punchbowl.data.meta.MetaField(keyword: str, comment: str, value: ValueType | None, datatype: Any, nullable: bool, mutable: bool, default: ValueType | None)[source]#

The MetaField object describes a single field within the NormalizedMetadata object.

_keyword#

_comment#

_value#

_datatype#

nullable#

_mutable#

_default#

property datatype: Any#: Get the data type.

property keyword: str#: Returns MetaField keyword.

property comment: str#: Returns MetaField comment.

property value: ValueType#: Returns MetaField value if set, otherwise get the default. Raise an error if no default is available.

property default: ValueType#: Get the default value.

static _type_matches(value: ValueType, field_type: Any) → bool[source]#

__eq__(other: MetaField) → bool[source]#: Check equality.

__int__() → int[source]#: Get an int.

__float__() → float[source]#: Get a float.

__str__() → str[source]#: Get a string.

__hash__() → int[source]#: Hash the field.

class punchbowl.data.meta.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')[source]#

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.

__str__() → str[source]#: Return the header as a string.

__len__() → int[source]#: Return number of entry cards in NormalizedMetadata object.

_contents#

_history#

_provenance#

_wcs_section_name = 'World Coordinate System'#

__hash__() → int[source]#: Hash a NormalizedMetadata object.

keys() → Iterable[str][source]#: Return FITS keys for collection.

__iter__() → Iterator[Any][source]#: Iterate.

__eq__(other: NormalizedMetadata) → bool[source]#: Check equality.

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

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[source]#

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[source]#

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[source]#

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][source]#

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]][source]#

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[source]#

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[source]#

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[source]#

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[source]#: Get a value given a key or use a default value.

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

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[source]#

Delete specified keyword entry from the NormalizedMetadata object.

Parameters:: key – Header key string
Return type:: None

__contains__(key: str) → bool[source]#

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.meta.set_spacecraft_location_to_earth(input_data: ndcube.NDCube) → ndcube.NDCube[source]#: Update the spacecraft location metadata.

punchbowl.data.meta.DateLike#

punchbowl.data.meta.check_moon_in_fov(time_obs_start: DateLike, time_end: str | None = None, resolution_minutes: int = 30, fov_deg: float = 90.0, wcs: astropy.wcs.WCS | None = None, image_shape: tuple[int, int] | None = None) → tuple[list[datetime.datetime], list[float], float, list[tuple[str, float]], list[float] | None, list[float] | None, list[float] | None][source]#

Forecast the moon in PUNCH FOV in a given time range.

It supports two modes:

Single-time mode: pass a DATE-OBS (string or FITS header)
Time-range mode: pass DATE-OBS as start time and time_end

If wcs and image_shape are given then it also computes:

angular distance of the Moon from the image center (deg)

2) Moon center (x, y) pixel coordinates in image. If out of image, it returns -1.

Parameters:

time_obs_start (str | Header | Mapping[str, Any]) –

Start time (or single observation time). If a header-like object is
provided, DATE-OBS is extracted.
time_end (str) – End time in ISO format (UTC). If None, single-time mode is used.
resolution_minutes (int, optional) – Time cadence resolution in minutes, by default 30.
fov_deg (float, optional) – Total field of view in degrees, by default 90.0.
wcs (astropy.wcs.WCS | None) – WCS of the image.
image_shape ((ny, nx) | None) – Image shape needed to define the image center pixel.

Returns:

times (list[datetime]) – Sampled times in UTC.
angle_sun_center (list[float]) – Moon-Sun angular separation at each sampled time (degrees).
fov_half (float) –

Half-angle of the field of view (degrees). It will be required
mainly when plotting the angular distance.
in_fov_times (list[(iso, angle)]) – Times where Moon-Sun separation <= fov_half.
angles_image_center (list[float] | None) – Moon angular separation from image center (deg), if wcs provided.
moon_xpix (list[float] | None) – Moon center x pixel coordinate (float). If outside the image, -1.
moon_ypix (list[float] | None) – Moon center y pixel coordinate (float). If outside the image, -1.