asdf Documentation

asdf is a tool for reading and writing Advanced Scientific Data Format (ASDF) files.


asdf requires:

Support for units, time, transform, wcs, or running the tests also requires:

Getting Started

The fundamental data model in ASDF is the tree, which is a nested combination of basic data structures: dictionaries, lists, strings and numbers. In addition, ASDF understands how to handle other types, such as Numpy arrays.

In the simplest example, you create a tree, and write it to a ASDF file. asdf handles saving the Numpy array as a binary block transparently:

from asdf import AsdfFile
import numpy as np

tree = {
  'author': 'John Doe',
  'my_array': np.random.rand(8, 8)
ff = AsdfFile(tree)


#ASDF 1.0.0
%YAML 1.1
%TAG !
--- !core/asdf-1.0.0
asdf_library: !core/software-1.0.0 {author: Space Telescope Science Institute, homepage: '',
  name: asdf, version: 1.2.1}
author: John Doe
my_array: !core/ndarray-1.0.0
  source: 0
  datatype: float64
  byteorder: little
  shape: [8, 8]
    allocated_size: 512
    used_size: 512
    data_size: 512
    data: 0462bb047110df3fe9460b758360eb3faa70d6d4...
%YAML 1.1
--- [370]

Other Examples are provided below.

Commandline tool

asdf includes a command-line tool, asdftool that performs a number of basic operations:

  • explode: Convert a self-contained ASDF file into exploded form.
  • implode: Convert an ASDF file in exploded form into a self-contained file.
  • to_yaml: Inline all of the data in an ASDF file so that it is pure YAML.
  • defragment: Remove unused blocks and extra space.

Run asdftool --help for more information.


asdf Package


open Open an existing ASDF file.
test([package, test_path, args, plugins, ...]) Run the tests using py.test.


AsdfFile([tree, uri, extensions, version]) The main class that represents a ASDF file.
AsdfType The base class of all custom types in the tree.
AsdfExtension Subclass to define an extension to ASDF.
Stream(shape, dtype[, strides]) Used to put a streamed array into the tree.
ValidationError(message[, validator, path, ...])

Class Inheritance Diagram

Inheritance diagram of asdf.asdf.AsdfFile, asdf.asdftypes.AsdfType, asdf.extension.AsdfExtension,, asdf.ValidationError

asdf.fits_embed Module


AsdfInFits([hdulist, tree, uri, extensions]) Embed ASDF tree content in a FITS file.

Class Inheritance Diagram

Inheritance diagram of asdf.fits_embed.AsdfInFits