asdf-format/asdf · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈
ASDF - 高级科学数据格式
.. _begin-badges:
.. image:: https://github.com/asdf-format/asdf/workflows/ci.yml/badge.svg :target: https://github.com/asdf-format/asdf/actions/workflows/ci.yml :alt: CI 状态
.. image:: https://readthedocs.org/projects/asdf/badge/?version=latest :target: https://asdf.readthedocs.io/en/latest/
.. image:: https://codecov.io/gh/asdf-format/asdf/branch/main/graphs/badge.svg :target: https://codecov.io/gh/asdf-format/asdf
.. _begin-zenodo:
.. image:: https://zenodo.org/badge/18112754.svg :target: https://zenodo.org/badge/latestdoi/18112754
.. _end-zenodo:
.. image:: https://img.shields.io/pypi/l/asdf.svg :target: https://img.shields.io/pypi/l/asdf.svg
.. _end-badges:
.. _begin-summary-text:
A\ dvanced S\ cientific D\ ata F\ ormat (ASDF) 是一种
用于科学数据的下一代交换格式。本软件包
包含 ASDF 规范的 Python 实现。有关 ASDF 文件格式的更多信息，包括规范，可参见
here <https://asdf-standard.readthedocs.io>__。
ASDF 格式具有以下特性：
- 以
YAML <http://yaml.org>__ 格式存储的层次化且人类可读的元数据 - 支持内存映射和灵活压缩的高效二进制数组存储
- 使用模式进行内容验证（使用
JSON Schema <http://json-schema.org>__） - 原生且透明地支持大多数基本 Python 数据类型， 并提供扩展 API 以支持任何自定义 Python 对象。
.. _end-summary-text:
ASDF 正在 github <https://github.com/asdf-format/asdf>__ 上积极开发中。有关贡献的更多信息
可在下文找到。
概述
本节概述了 ASDF 包用于创建 和读取 ASDF 文件的基本用例。
创建文件
.. _begin-create-file-text:
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`:
.. code:: python
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:
.. _begin-example-asdf-metadata:
.. code:: yaml
#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]
...
.. _end-example-asdf-metadata:
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 above).
.. _end-create-file-text:
.. _begin-compress-file:
It is possible to compress the array data when writing the file:
.. code:: python
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 <https://python-lz4.readthedocs.io/>`__ package
is installed. Other compression algorithms may be available via extensions.
.. _end-compress-file:
Reading a file
~~~~~~~~~~~~~~
.. _begin-read-file-text:
To read an existing ASDF file, we simply use the top-level `open` function of
the `asdf` package:
.. code:: python
import asdf
af = asdf.open("example.asdf")
The `open` function also works as a context handler:
.. code:: python
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:
.. code:: pycon
>>> 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:
.. code:: pycon
>>> af["name"]
'Monty'
>>> af["powers"]
{'squares': <array (unloaded) shape: [100] dtype: int64>}
Array data remains unloaded until it is explicitly accessed:
.. code:: pycon
>>> 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
Memory mapping can be enabled by providing ``memmap=True``
to `open`:
.. code:: python
af = asdf.open("example.asdf", memmap=True)
.. _end-read-file-text:
For more information and for advanced usage examples, see the
`documentation <http://asdf.readthedocs.io/en/latest/>`__.
Extending ASDF
~~~~~~~~~~~~~~
开箱即用，``asdf`` 包会自动序列化并
反序列化原生 Python 类型。可以通过
实现对应于自定义用户类型的自定义标签来扩展 ``asdf``。有关扩展 ASDF 的更多信息
可在 `官方
文档 <http://asdf.readthedocs.io/en/latest/#extending-asdf>`__ 中找到。
安装
------------
.. _begin-pip-install-text:
ASDF Python 包的稳定版本已注册在 `PyPi
<https://pypi.python.org/pypi/asdf>`__ 上。可以使用 ``pip`` 安装
最新稳定版本：
::
$ pip install asdf
.. _begin-source-install-text:
ASDF 的最新开发版本可从 ``main`` 分支
`on github <https://github.com/asdf-format/asdf>`__ 获取。要克隆该项目：
::
$ git clone https://github.com/asdf-format/asdf
安装方法：
::
$ cd asdf
$ pip install .
要在 `development
mode <https://packaging.python.org/tutorials/distributing-packages/#working-in-development-mode>`__:: 中安装：
$ pip install -e .
.. _end-source-install-text:
测试
-------
.. _begin-testing-text:
要从仓库的源代码检出中安装测试依赖项：
::
$ pip install -e ".[tests]"
要从仓库的源代码检出运行单元测试：
::
$ pytest
也可以从已安装的包版本运行测试套件。
::
$ pip install "asdf[tests]"
$ pytest --pyargs asdf
也可以使用 `nox
<https://nox.thea.codes/>`__ 运行测试。
::
$ pip install nox
要列出所有可用的会话：
::
$ nox -l
要运行特定会话：
::
$ nox -s "core-3.12" # 在 Python 3.12 中运行核心 ASDF 测试
会话组也可以通过标签指定：
::
$ nox -t downstream # 运行所有下游会话
.. _end-testing-text:
文档
-------------
有关此软件包的更详细文档，请参阅
`here <https://asdf.readthedocs.io>`__。
有关 ASDF 文件格式本身的更多信息，请参阅
`here <https://asdf-standard.readthedocs.io>`__。
如果您正在寻找 **A**\ daptable **S**\ eismic **D**\ ata
**F**\ ormat，相关信息可在
`here <https://seismic-data.org/>`__ 中找到。
许可证
-------
ASDF 采用 BSD 3-clause 风格的许可证。请参阅 `LICENSE <https://github.com/asdf-format/asdf/blob/main/LICENSE>`_
以获取 `licenses folder <https://github.com/asdf-format/asdf/tree/main/licenses>`_ 中
关于任何包含软件的许可证信息。
贡献
------------
我们欢迎对该项目的反馈和贡献。代码、文档或一般性反馈均受赞赏。请
遵循 `contributing guidelines <https://github.com/asdf-format/asdf/blob/main/CONTRIBUTING.rst>`__ 提交
问题或拉取请求。
我们致力于通过遵守 `Code of Conduct <https://github.com/asdf-format/asdf?tab=coc-ov-file>`__ 为所有用户提供
一个友好的社区。