AsdfInFits

class asdf.fits_embed.AsdfInFits(hdulist=None, tree=None, **kwargs)

Bases: AsdfFile

Embed ASDF tree content in a FITS file.

The YAML rendering of the tree is stored in a special FITS extension with the EXTNAME of ASDF. Arrays in the ASDF tree may refer to binary data in other FITS extensions by setting source to a string with the prefix fits: followed by an EXTNAME, EXTVER pair, e.g. fits:SCI,0.

Examples

Create a FITS file with ASDF structure, based on an existing FITS file:

import numpy as np
from astropy.io import fits

from asdf import fits_embed

hdulist = fits.HDUList([
    fits.PrimaryHDU(),
    fits.ImageHDU(np.arange(512, dtype=np.float32), name='SCI'),
    fits.ImageHDU(np.zeros(512, dtype=np.int16), name='DQ')])

tree = {
    'model': {
        'sci': {
            'data': hdulist['SCI'].data,
            'wcs': 'WCS info'
        },
        'dq': {
            'data': hdulist['DQ'].data,
            'wcs': 'WCS info'
        }
    }
}

ff = fits_embed.AsdfInFits(hdulist, tree)
ff.write_to('test.fits')  # doctest: +SKIP

Parameters:

treedict or AsdfFile, optional

The main tree data in the ASDF file. Must conform to the ASDF schema.

uristr, optional

The URI for this ASDF file. Used to resolve relative references against. If not provided, will be automatically determined from the associated file object, if possible and if created from asdf.AsdfFile.open.

extensionsobject, optional

Additional extensions to use when reading and writing the file. May be any of the following: asdf.extension.AsdfExtension, asdf.extension.Extension, asdf.extension.AsdfExtensionList or a list of extensions.

versionstr, optional

The ASDF Standard version. If not provided, defaults to the configured default version. See asdf.config.AsdfConfig.default_version.

ignore_version_mismatchbool, optional

When True, do not raise warnings for mismatched schema versions. Set to True by default.

ignore_unrecognized_tagbool, optional

When True, do not raise warnings for unrecognized tags. Set to False by default.

ignore_implicit_conversionbool

When True, do not raise warnings when types in the tree are implicitly converted into a serializable object. The motivating case for this is currently namedtuple, which cannot be serialized as-is.

copy_arraysbool, optional

When False, when reading files, attempt to memmap underlying data arrays when possible.

lazy_loadbool, optional

When True and the underlying file handle is seekable, data arrays will only be loaded lazily: i.e. when they are accessed for the first time. In this case the underlying file must stay open during the lifetime of the tree. Setting to False causes all data arrays to be loaded up front, which means that they can be accessed even after the underlying file is closed. Note: even if lazy_load is False, copy_arrays is still taken into account.

custom_schemastr, optional

Path to a custom schema file that will be used for a secondary validation pass. This can be used to ensure that particular ASDF files follow custom conventions beyond those enforced by the standard.

Methods Summary

close()	Close the file handles associated with the asdf.AsdfFile.
open(fd[, uri, validate_checksums, ...])	Creates a new AsdfInFits object based on given input data
update([all_array_storage, ...])	Update the file on disk in place.
write_to(filename[, all_array_storage, ...])	Write the ASDF file to the given file-like object.

Methods Documentation

close()

Close the file handles associated with the asdf.AsdfFile.

classmethod open(fd, uri=None, validate_checksums=False, extensions=None, ignore_version_mismatch=True, ignore_unrecognized_tag=False, strict_extension_check=False, ignore_missing_extensions=False, **kwargs)

Creates a new AsdfInFits object based on given input data

Parameters:

fdFITS HDUList instance, URI string, or file-like object

May be an already opened instance of a FITS HDUList instance, string file or http URI, or a Python file-like object.

uristr, optional

The URI for this ASDF file. Used to resolve relative references against. If not provided, will be automatically determined from the associated file object, if possible and if created from asdf.open.

validate_checksumsbool, optional

If True, validate the blocks against their checksums. Requires reading the entire file, so disabled by default.

extensionsobject, optional

Additional extensions to use when reading and writing the file. May be any of the following: asdf.extension.AsdfExtension, asdf.extension.Extension, asdf.extension.AsdfExtensionList or a list extensions.

ignore_version_mismatchbool, optional

When True, do not raise warnings for mismatched schema versions.

strict_extension_checkbool, optional

When True, if the given ASDF file contains metadata about the extensions used to create it, and if those extensions are not installed, opening the file will fail. When False, opening a file under such conditions will cause only a warning. Defaults to False.

ignore_missing_extensionsbool, optional

When True, do not raise warnings when a file is read that contains metadata about extensions that are not available. Defaults to False.

validate_on_readbool, optional

DEPRECATED. When True, validate the newly opened file against tag and custom schemas. Recommended unless the file is already known to be valid.

update(all_array_storage=None, all_array_compression=None, pad_blocks=False, **kwargs)

Update the file on disk in place.

Parameters:

all_array_storagestring, optional

If provided, override the array storage type of all blocks in the file immediately before writing. Must be one of:

• internal: The default. The array data will be stored in a binary block in the same ASDF file.

• external: Store the data in a binary block in a separate ASDF file.

• inline: Store the data as YAML inline in the tree.

all_array_compressionstring, optional

If provided, set the compression type on all binary blocks in the file. Must be one of:

• '' or None: No compression.

• zlib: Use zlib compression.

• bzp2: Use bzip2 compression.

• lz4: Use lz4 compression.

• input: Use the same compression as in the file read. If there is no prior file, acts as None

pad_blocksfloat or bool, optional

Add extra space between blocks to allow for updating of the file. If False (default), add no padding (always return 0). If True, add a default amount of padding of 10% If a float, it is a factor to multiple content_size by to get the new total size.

include_block_indexbool, optional

If False, don’t include a block index at the end of the file. (Default: True) A block index is never written if the file has a streamed block.

versionstr, optional

Update the ASDF Standard version of this AsdfFile before writing.

auto_inlineint, optional

DEPRECATED. When the number of elements in an array is less than this threshold, store the array as inline YAML, rather than a binary block. This only works on arrays that do not share data with other arrays. Default is the value specified in asdf.get_config().array_inline_threshold.

write_to(filename, all_array_storage=None, all_array_compression=None, pad_blocks=False, use_image_hdu=False, *args, **kwargs)

Write the ASDF file to the given file-like object.

write_to does not change the underlying file descriptor in the asdf.AsdfFile object, but merely copies the content to a new file.

Parameters:

fdstring or file-like object

May be a string path to a file, or a Python file-like object. If a string path, the file is automatically closed after writing. If not a string path, it is the caller’s responsibility to close the object.

all_array_storagestring, optional

If provided, override the array storage type of all blocks in the file immediately before writing. Must be one of:

• internal: The default. The array data will be stored in a binary block in the same ASDF file.

• external: Store the data in a binary block in a separate ASDF file.

• inline: Store the data as YAML inline in the tree.

all_array_compressionstring, optional

If provided, set the compression type on all binary blocks in the file. Must be one of:

• '' or None: No compression.

• zlib: Use zlib compression.

• bzp2: Use bzip2 compression.

• lz4: Use lz4 compression.

• input: Use the same compression as in the file read. If there is no prior file, acts as None.

pad_blocksfloat or bool, optional

Add extra space between blocks to allow for updating of the file. If False (default), add no padding (always return 0). If True, add a default amount of padding of 10% If a float, it is a factor to multiple content_size by to get the new total size.

include_block_indexbool, optional

If False, don’t include a block index at the end of the file. (Default: True) A block index is never written if the file has a streamed block.

versionstr, optional

Update the ASDF Standard version of this AsdfFile before writing.

auto_inlineint, optional

DEPRECATED. When the number of elements in an array is less than this threshold, store the array as inline YAML, rather than a binary block. This only works on arrays that do not share data with other arrays. Default is the value specified in asdf.get_config().array_inline_threshold.