FitsOutputArchive#

class lsst.images.fits.FitsOutputArchive(hdu_list: HDUList, compression_options: Mapping[str, FitsCompressionOptions | None] | None = None, opaque_metadata: Any = None, compression_seed: int | None = None)#

Bases: OutputArchive[TableCellReferenceModel]

An implementation of the serialization.OutputArchive interface that writes to FITS files.

Instances of this class should only be constructed via the open context manager.

Methods Summary

`add_array`(array, *[, name, update_header])	Add an array to the archive.
`add_structured_array`(array, *[, name, ...])	Add a table to the archive.
`add_table`(table, *[, name, update_header])	Add a table to the archive.
`add_tree`(tree)	Write the JSON tree to the archive.
`iter_frame_sets`()	Iterate over the frame sets already serialized to this archive.
`open`(filename[, compression_options, ...])	Create an output archive that writes to the given file.
`serialize_direct`(name, serializer)	Use a serializer function to save a nested object.
`serialize_frame_set`(name, frame_set, ...)	Serialize a frame set and make it available to objects saved later.
`serialize_pointer`(name, serializer, key)	Use a serializer function to save a nested object that may be referenced in multiple locations in the same archive.

Methods Documentation

add_array(array: ~numpy.ndarray, *, name: str | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → ArrayReferenceModel#

Add an array to the archive.

Parameters#

array: Array to save.
name: Name of the array. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
update_header: A callback that will be given the FITS header for the HDU containing this array in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

ArrayReferenceModel: A Pydantic model that references the stored array.

add_structured_array(array: ~numpy.ndarray, *, name: str | None = None, units: ~collections.abc.Mapping[str, ~astropy.units.core.Unit] | None = None, descriptions: ~collections.abc.Mapping[str, str] | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → TableReferenceModel#

Add a table to the archive.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
array: A structured numpy array.
name: Name of the array. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
units: A mapping of units for columns. Need not be complete.
descriptions: A mapping of descriptions for columns. Need not be complete.
update_header: A callback that will be given the FITS header for the HDU containing this table in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

TableReferenceModel: A Pydantic model that represents the table. Column definitions are included directly in the model while the actual data is stored elsewhere and referenced by the model.

add_table(table: ~astropy.table.table.Table, *, name: str | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → TableReferenceModel#

Add a table to the archive.

Parameters#

table: Table to save.
name: Name of the table. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
update_header: A callback that will be given the FITS header for the HDU containing this table in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

TableReferenceModel: A Pydantic model that represents the table. Column definitions are included directly in the model while the actual data is stored elsewhere and referenced by the model.

add_tree(tree: ArchiveTree) → None#

Write the JSON tree to the archive.

This method must be called exactly once, just before the open context is exited.

Parameters#

tree: Pydantic model that represents the tree.

iter_frame_sets() → Iterator[tuple[FrameSet, TableCellReferenceModel]]#

Iterate over the frame sets already serialized to this archive.

Yields#

frame_set: A frame set that has already been written to this archive.
reference: An implementation-specific reference model that points to the frame set.

classmethod open(filename: str, compression_options: ~collections.abc.Mapping[str, ~lsst.images.fits._common.FitsCompressionOptions | None] | None = None, opaque_metadata: ~typing.Any = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>, compression_seed: int | None = None) → Iterator[Self]#

Create an output archive that writes to the given file.

Parameters#

filename: Name of the file to write to. Must not already exist.
compression_options: Options for how to compress the FITS file, keyed by the name of the attribute (with JSON pointer / separators for nested attributes).
opaque_metadata: Metadata read from an input archive along with the object being written now. Ignored if the metadata is not from a FITS archive.
update_header: A callback that will be given the primary HDU FITS header and an opportunity to modify it.
compression_seed: A FITS tile compression seed to use whenever the configured compression seed is None or (for backwards compatibility) 0. This value is then incremented every time it is used.

Returns#

contextlib.AbstractContextManager [FitsOutputArchive]: A context manager that returns a FitsOutputArchive when entered.

serialize_direct(name: str, serializer: Callable[[OutputArchive[TableCellReferenceModel]], T]) → T#

Use a serializer function to save a nested object.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.

Returns#

T: Result of the call to the serializer.

serialize_frame_set(name: str, frame_set: FrameSet, serializer: Callable[[OutputArchive], T], key: Hashable) → TableCellReferenceModel#

Serialize a frame set and make it available to objects saved later.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
frame_set: The frame set being saved. This will be returned in later calls to iter_frame_sets, along with the returned reference object.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.
key: A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns#

T | P: Either the result of the call to the serializer, or a Pydantic model that can be considered a reference to it and added to a larger model in its place.

serialize_pointer(name: str, serializer: Callable[[OutputArchive[TableCellReferenceModel]], T], key: Hashable) → TableCellReferenceModel#

Use a serializer function to save a nested object that may be referenced in multiple locations in the same archive.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.
key: A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns#

T | P: Either the result of the call to the serializer, or a Pydantic model that can be considered a reference to it and added to a larger model in its place.