astro py:docs

- Index
- Modules

### Navigation

- next »
- asdf v1.3.3 »

# 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:

- python 2.7, 3.3, 3.4 or 3.5.
- numpy 1.6 or later
- jsonschema 2.3.0 or later
- pyyaml 3.10 or later
- six 1.9.0 or later

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

- astropy 1.1 or later

## 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

    b'#ASDF' 1.1.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.3.3}
    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: b'032ceec9baa4ec3fec2abb6ff973d33f4fb2f8d4...'

    #ASDF BLOCK INDEX
    %YAML 1.1
    --- [370]
    ...

Other Examples are provided below.

- Examples
  - Hello World
  - Saving arrays
  - Schema validation
  - Sharing of data
  - Saving inline arrays
  - Saving external arrays
  - Streaming array data
  - References
  - Compression
  - Saving history entries
  - Saving ASDF in FITS
- Writing ASDF extensions
  - An Example
  - Explicit version support
  - Adding custom validators

## 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.

## See also

- The Advanced Scientific Data Format (ASDF) standard

## 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.
`CustomType` | Base class for all user-defined types.
`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

## asdf.fits_embed Module

### Classes

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

### Class Inheritance Diagram