asdf Documentation

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

Note

This is the Advanced Scientific Data Format - if you are looking for the Adaptable Seismic Data Format, go here: http://seismic-data.org/

Installation

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)
ff.write_to("example.asdf")

example.asdf

#ASDF 1.0.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.0.0
asdf_library: !core/software-1.0.0 {author: Space Telescope Science Institute, homepage: 'http://github.com/spacetelescope/asdf',
  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]
...
BLOCK 0:
    allocated_size: 512
    used_size: 512
    data_size: 512
    data: 13640012a5b1e13f36f5253a5741e03fc81940e4...
#ASDF BLOCK INDEX
%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.

Reference/API

asdf Package

Functions

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

Classes

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.stream.Stream, asdf.ValidationError

asdf.fits_embed Module

Classes

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

Class Inheritance Diagram

Inheritance diagram of asdf.fits_embed.AsdfInFits