ASDF (Advanced Scientific Data Format) is a next generation interchange format for scientific data
Clone or download
drdavella Merge pull request #572 from drdavella/tag-without-schema
Add test for serializing/deserializing type without schema
Latest commit c2fbf33 Oct 23, 2018
Permalink
Failed to load latest commit information.
asdf-standard @ 0bc7aa7 Update asdf-standard to reflect changes to complex schema Aug 3, 2018
asdf Add test for serializing/deserializing type without schema Oct 23, 2018
astropy_helpers @ ca63040 Update astropy_helpers to v3.0.2 release Jul 30, 2018
docs Update documentation Oct 12, 2018
licenses Use add_common_docstring decorator from sunpy [docs only] Apr 17, 2018
.gitignore Ignore tox directory and pytest cache Mar 5, 2018
.gitmodules Rename FINF to ASDF Jul 29, 2014
.rtd-environment.yml Add config files for building RTD using conda Feb 20, 2018
.travis.yml Update CI configs to use newer version of python/pytest Oct 19, 2018
CHANGES.rst Fix bug with tree creation when schema file is missing Oct 22, 2018
CODE_OF_CONDUCT.md Add code of conduct and contributing guidelines Jan 3, 2018
CONTRIBUTING.md Add code of conduct and contributing guidelines Jan 3, 2018
MANIFEST.in Change README.md to README.rst in MANIFEST.in [skip ci] Apr 17, 2018
README.rst Add the human-readable title Oct 17, 2018
ah_bootstrap.py Update ah_bootstrap.py to reflect astropy-helpers v2.0.1 Aug 1, 2017
appveyor.yml Update CI configs to use newer version of python/pytest Oct 19, 2018
conftest.py Move pytest_plugins to top-level conftest per pytest deprecation Oct 19, 2018
environment.yml Add conda environment configuration file [skip ci] Nov 15, 2017
ez_setup.py Update to newer ez_setup.py Apr 11, 2014
readthedocs.yml Add config files for building RTD using conda Feb 20, 2018
setup.cfg Merge pull request #534 from vmarkovtsev/patch-3 Aug 29, 2018
setup.py Update setup.py version and changelog for v2.2.0 Sep 25, 2018
setup_helpers.py Automatically adjust hyperlink targets in README Apr 19, 2018
tox.ini Update tox.ini Aug 9, 2018

README.rst

STScI Logo

ASDF - Advanced Scientific Data Format

Build Status Documentation Status Coverage Status license stsci astropy

OverviewInstallationTestingDocumentationContributing

The Advanced Scientific Data Format (ASDF) is a next-generation interchange format for scientific data. This package contains the Python implementation of the ASDF Standard. More information on the ASDF Standard itself can be found here.

The ASDF format has the following features:

  • A hierarchical, human-readable metadata format (implemented using YAML)
  • Numerical arrays are stored as binary data blocks which can be memory mapped. Data blocks can optionally be compressed.
  • The structure of the data can be automatically validated using schemas (implemented using JSON Schema)
  • Native Python data types (numerical types, strings, dicts, lists) are serialized automatically
  • ASDF can be extended to serialize custom data types

ASDF is under active development on github. More information on contributing can be found below.

Overview

This section outlines basic use cases of the ASDF package for creating and reading ASDF files.

Creating a file

We're going to store several numpy arrays and other data to an ASDF file. We do this by creating a "tree", which is simply a dict, and we provide it as input to the constructor of AsdfFile:

import asdf
import numpy as np

# Create some data
sequence = np.array([x for x in range(100)])
squares = np.array([x**2 for x in range(100)])
random = np.random.random(100)

# Store the data in an arbitrarily nested dictionary
tree = {
    'foo': 42,
    'name': 'Monty',
    'sequence': sequence,
    'powers': { 'squares' : squares },
    'random': random
}

# Create the ASDF file object from our data tree
af = asdf.AsdfFile(tree)

# Write the data to a new file
af.write_to('example.asdf')

If we open the newly created file, we can see some of the key features of ASDF on display:

#ASDF 1.0.0
#ASDF_STANDARD 1.2.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.1.0
asdf_library: !core/software-1.0.0 {author: Space Telescope Science Institute, homepage: 'http://github.com/spacetelescope/asdf',
  name: asdf, version: 2.0.0}
history:
  extensions:
  - !core/extension_metadata-1.0.0
    extension_class: asdf.extension.BuiltinExtension
    software: {name: asdf, version: 2.0.0}
foo: 42
name: Monty
powers:
  squares: !core/ndarray-1.0.0
    source: 1
    datatype: int64
    byteorder: little
    shape: [100]
random: !core/ndarray-1.0.0
  source: 2
  datatype: float64
  byteorder: little
  shape: [100]
sequence: !core/ndarray-1.0.0
  source: 0
  datatype: int64
  byteorder: little
  shape: [100]
...

The metadata in the file mirrors the structure of the tree that was stored. It is hierarchical and human-readable. Notice that metadata has been added to the tree that was not explicitly given by the user. Notice also that the numerical array data is not stored in the metadata tree itself. Instead, it is stored as binary data blocks below the metadata section (not shown here).

It is possible to compress the array data when writing the file:

af.write_to('compressed.asdf', all_array_compression='zlib')

Available compression algorithms are 'zlib', 'bzp2', and 'lz4'.

Reading a file

To read an existing ASDF file, we simply use the top-level open function of the asdf package:

import asdf

af = asdf.open('example.asdf')

The open function also works as a context handler:

with asdf.open('example.asdf') as af:
    ...

To access the data stored in the file, use the top-level AsdfFile.tree attribute:

>>> import asdf
>>> af = asdf.open('example.asdf')
>>> af.tree
{'asdf_library': {'author': 'Space Telescope Science Institute',
  'homepage': 'http://github.com/spacetelescope/asdf',
  'name': 'asdf',
  'version': '1.3.1'},
 'foo': 42,
 'name': 'Monty',
 'powers': {'squares': <array (unloaded) shape: [100] dtype: int64>},
 'random': <array (unloaded) shape: [100] dtype: float64>,
 'sequence': <array (unloaded) shape: [100] dtype: int64>}

The tree is simply a Python dict, and nodes are accessed like any other dictionary entry:

>>> af.tree['name']
'Monty'
>>> af.tree['powers']
{'squares': <array (unloaded) shape: [100] dtype: int64>}

Array data remains unloaded until it is explicitly accessed:

>>> af.tree['powers']['squares']
array([   0,    1,    4,    9,   16,   25,   36,   49,   64,   81,  100,
        121,  144,  169,  196,  225,  256,  289,  324,  361,  400,  441,
        484,  529,  576,  625,  676,  729,  784,  841,  900,  961, 1024,
       1089, 1156, 1225, 1296, 1369, 1444, 1521, 1600, 1681, 1764, 1849,
       1936, 2025, 2116, 2209, 2304, 2401, 2500, 2601, 2704, 2809, 2916,
       3025, 3136, 3249, 3364, 3481, 3600, 3721, 3844, 3969, 4096, 4225,
       4356, 4489, 4624, 4761, 4900, 5041, 5184, 5329, 5476, 5625, 5776,
       5929, 6084, 6241, 6400, 6561, 6724, 6889, 7056, 7225, 7396, 7569,
       7744, 7921, 8100, 8281, 8464, 8649, 8836, 9025, 9216, 9409, 9604,
       9801])

>>> import numpy as np
>>> expected = [x**2 for x in range(100)]
>>> np.equal(af.tree['powers']['squares'], expected).all()
True

By default, uncompressed data blocks are memory mapped for efficient access. Memory mapping can be disabled by using the copy_arrays option of open when reading:

af = asdf.open('example.asdf', copy_arrays=True)

For more information and for advanced usage examples, see the documentation.

Extending ASDF

Out of the box, the asdf package automatically serializes and deserializes native Python types. It is possible to extend asdf by implementing custom tag types that correspond to custom user types. More information on extending ASDF can be found in the official documentation.

Installation

Stable releases of the ASDF Python package are registered at PyPi. The latest stable version can be installed using pip:

$ pip install asdf

The latest development version of ASDF is available from the master branch on github. To clone the project:

$ git clone https://github.com/spacetelescope/asdf

To install:

$ cd asdf
$ python3 setup.py install

To install in development mode:

$ python3 setup.py develop

Note

The source repository makes use of a git submodule for referencing the schemas provided by the ASDF standard. While this submodule is automatically initialized when installing the package (including in development mode), it may be necessary for developers to manually update the submodule if changes are made upstream. See the documentation on git submodules for more information.

Testing

To run the unit tests from a source checkout of the repository:

$ python3 setup.py test

It is also possible to run the test suite from an installed version of the package. In a Python interpreter:

import asdf
asdf.test()

Please note that the astropy package must be installed to run the tests.

Documentation

More detailed documentation on this software package can be found here.

More information on the ASDF Standard itself can be found here.

If you are looking for the Adaptable Seismic Data Format, information can be found here.

Contributing

We welcome feedback and contributions to the project. Contributions of code, documentation, or general feedback are all appreciated. Please follow the contributing guidelines to submit an issue or a pull request.

We strive to provide a welcoming community to all of our users by abiding to the Code of Conduct.