To help you get started, we've collected the most common ways that asdf is being used within popular public projects.

spacetelescope / asdf / asdf / block.py View on Github

# since not reading an index isn't a deal breaker --
        # everything can still be read from the file, only slower.
        # Importantly, it must remain "transactionally clean", and not
        # create any blocks until we're sure the block index makes
        # sense.

        if not fd.seekable():
            return

        if not len(self._internal_blocks):
            return

        first_block = self._internal_blocks[0]
        first_block_end = first_block.end_offset

        fd.seek(0, generic_io.SEEK_END)
        file_size = block_end = fd.tell()
        # We want to read on filesystem block boundaries.  We use
        # "block_end - 5" here because we need to read at least 5
        # bytes in the first block.
        block_start = ((block_end - 5) // fd.block_size) * fd.block_size
        buff_size = block_end - block_start

        content = b''

        fd.seek(block_start, generic_io.SEEK_SET)
        buff = fd.read(buff_size)

        # Extra '\0' bytes are allowed after the ..., mainly to
        # workaround poor truncation support on Windows
        buff = buff.rstrip(b'\0')
        content = buff

View more ways to use asdf

ASDF - Advanced Scientific Data Format

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

Overview

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

Creating a file

import asdf
import numpy as np

# Create some data
sequence = np.arange(100)
squares = sequence**2
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's metadata section, 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: The ASDF Developers, homepage: 'http://github.com/asdf-format/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]
...

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

The built-in compression algorithms are 'zlib', and 'bzp2'. The 'lz4' algorithm becomes available when the lz4 package is installed. Other compression algorithms may be available via extensions.

Reading a file

import asdf

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

The open function also works as a context handler:

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

To get a quick overview of the data stored in the file, use the top-level AsdfFile.info() method:

>>> import asdf
>>> af = asdf.open("example.asdf")
>>> af.info()
root (AsdfObject)
├─asdf_library (Software)
│ ├─author (str): The ASDF Developers
│ ├─homepage (str): http://github.com/asdf-format/asdf
│ ├─name (str): asdf
│ └─version (str): 2.8.0
├─history (dict)
│ └─extensions (list)
│   └─[0] (ExtensionMetadata)
│     ├─extension_class (str): asdf.extension.BuiltinExtension
│     └─software (Software)
│       ├─name (str): asdf
│       └─version (str): 2.8.0
├─foo (int): 42
├─name (str): Monty
├─powers (dict)
│ └─squares (NDArrayType): shape=(100,), dtype=int64
├─random (NDArrayType): shape=(100,), dtype=float64
└─sequence (NDArrayType): shape=(100,), dtype=int64

The AsdfFile behaves like a Python dict, and nodes are accessed like any other dictionary entry:

>>> af["name"]
'Monty'
>>> af["powers"]
{'squares': }

Array data remains unloaded until it is explicitly accessed:

>>> af["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["powers"]["squares"], expected).all()
True

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

af = asdf.open("example.asdf", memmap=False)

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 tags that correspond to custom user types. More information on extending ASDF can be found in the official documentation.

Installation

$ pip install asdf

$ git clone https://github.com/asdf-format/asdf

To install:

$ cd asdf
$ pip install .

To install in development mode:

$ pip install -e .

Testing

$ pip install -e ".[tests]"

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

$ pytest

It is also possible to run the test suite from an installed version of the package.

$ pip install "asdf[tests]"
$ pytest --pyargs asdf

It is also possible to run the tests using tox.

$ pip install tox

To list all available environments:

$ tox -va

To run a specific environment:

$ tox -e 

Documentation

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

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

There are two mailing lists for ASDF:

• asdf-users

• asdf-developers

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

License

ASDF is licensed under a BSD 3-clause style license. See LICENSE.rst for the licenses folder for licenses for any included software.

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.