VOTable处理 (astropy.io.votable )#

介绍#

的 astropy.io.votable 子包将VOTable HTML文件转换成和转换成 numpy 记录数组。

备注

如果您想以VOTable格式读取或写入单个表，建议的方法是通过 高级统一文件I/O 接口.特别是，请参见 Unified I/O VO Tables 科.

入门#

读取VOTable文件#

要读取VOTable文件，请将文件路径传递给 parse

from astropy.io.votable import parse
votable = parse("votable.xml")

votable 是一个 VOTableFile 对象，可用于检索和操作数据并将其保存回磁盘。

编写VOTable文件#

方法以可投票格式写入表格数据。 votable 直接打包。然而，在某些情况下，高层 高级统一文件I/O 通常就足够了，而且使用起来也更方便一些。请参阅 Unified I/O VOTable 部分了解详细信息。

要保存VOTable文件，请调用 to_xml 方法。它接受字符串或Unicode路径，或类似于Python文件的对象：

votable.to_xml('output.xml')

支持多种数据存储格式 astropy.io.votable 。这个 TABLEDATA 格式是基于XML的，并将值存储为表示数字的字符串。这个 BINARY 格式更加紧凑，以Base64编码的二进制格式存储数字。Vvotable版本1.3增加了 BINARY2 格式，该格式允许屏蔽任何数据类型，包括无法在旧版本中屏蔽的整数和位域 BINARY 格式化。在每个表的基础上使用 format 属性，或全局使用 set_all_tables_format 方法：

votable.get_first_table().format = 'binary'
votable.set_all_tables_format('binary')
votable.to_xml('binary.xml')

VOTable元素#

VOTables由嵌套元素构建。例如，让我们构建一个包含 INFO 元素：：

>>> from astropy.io.votable.tree import VOTableFile, Info
>>> vot = VOTableFile()
>>> vot.infos.append(Info(name="date_obs", value="2025-01-01"))

这些要素可以是：

以下是对其中一些元素的一些详细解释：

使用 astropy.io.votable#

标准符合性#

astropy.io.votable.tree.TableElement 支持 VOTable Format Definition Version 1.1 , Version 1.2 , Version 1.3 , Version 1.4 ，而且 Version 1.5 ，提供了一些灵活性来支持1.0草案版本和其他野外非标准使用，请参阅 验证VOTables 了解更多详细信息。

备注

发出的每个警告和特定于VOTABLE的异常都有一个数字，在中有更详细的记录 警告 和 例外情况 .

输出始终符合1.1、1.2、1.3、1.4、1.5规范，具体取决于输入。

验证VOTables#

野外的许多可投票文件不符合可投票规范。方法设置遇到冲突时应发生的情况。 verify 关键字，可以接受三个值：

这个 verify 关键字可以与 parse() 或 parse_single_table() 功能：：

from astropy.io.votable import parse
votable = parse("votable.xml", verify='warn')

可以更改默认设置 verify 通过以下方式实现价值 astropy.io.votable.conf.verify 项目中的 配置系统 (astropy.config ） 。

请注意 'ignore' 或 'warn' 我的意思是 astropy 将尝试解析投票表，但如果违反了规范，则不能保证成功。

最好将任何错误报告给生成可投票文件的应用程序的作者，以使该文件符合规范。

数据序列化格式#

VOTable支持多种不同的序列化格式。

  • TABLEDATA 将数据存储在纯XML中，其中的数值作为人类可读的字符串写入。

  • BINARY 是数据的二进制表示，以不透明的形式存储在XML中 base64 -编码的blob。

  • BINARY2 是在VOTable 1.3中添加的，与“BINARY”相同，只是它显式地记录了缺失值的位置，而不是用一个特殊的值来标识它们。

  • FITS 将数据存储在外部FITS文件中。不支持此序列化 astropy.io.votable writer，因为它需要写入多个文件。

  • PARQUET 将数据存储在外部拼图文件中，类似于FITS序列化。读取和写入完全受 astropy.io.votable 作家和 astropy.io.votable.parse 读者。可以使用绝对路径和相对路径引用拼图文件。拼图序列化可以用作统一表I/O的一部分(请参阅下一节)，方法是设置 format 参数为 'votable.parquet' 。

可通过两种方式选择序列化格式：

1)通过设置 format 对象的属性 astropy.io.votable.tree.TableElement 对象：：

votable.get_first_table().format = "binary"
votable.to_xml("new_votable.xml")

2） 通过使用 tabledata_format 写出VOTable文件时的关键字参数：：

votable.to_xml("new_votable.xml", tabledata_format="binary")

转换为/从 astropy.table.Table#

VOTable标准在概念上并不映射到 astropy.table.Table . 但是，在 VOTable 文件可以转换为 astropy.table.Table ：：

from astropy.io.votable import parse_single_table
table = parse_single_table("votable.xml").to_table()

为了方便起见，还有一个函数可以创建一个完整的VOTable文件，其中只有一个表：

from astropy.io.votable import from_table, writeto
votable = from_table(table)
writeto(votable, "output.xml")

备注

默认情况下， to_table 将使用 ID 属性来创建 Table 对象。但是，您可能希望使用 name 而是属性。为此，设置 use_names_over_ids 关键字到 True . 请注意，因为字段 names 不保证在VOTable规范中是唯一的，但列名在中必须是唯一的 numpy 结构化数组（因此 astropy.table.Table 对象），在某些情况下，可以通过在末尾附加数字来重命名名称。

性能注意事项#

如果 TABLE 元素包括 nrows 属性。如果未指定行数，则必须在加载期间重复调整记录数组的大小。

数据源#

介绍#

从VOTable头提取基本出处信息。该信息在DataOrigin IVOA注释中描述：https://www.ivoa.net/documents/DataOrigin/。

DataOrigin包括查询信息（例如发布商、联系人、版本等）和数据集起源（例如创建者、书目链接、URL等）

此API从VOTable中的Info中检索元数据。

入门#

从VOTable提取DataOrigin

示例：VizieR目录J/AJ/167/18

>>> from astropy.io.votable import parse
>>> from astropy.io.votable.dataorigin import extract_data_origin
>>> votable = parse("https://vizier.cds.unistra.fr/viz-bin/conesearch/J/AJ/167/18/table4?RA=265.51&DEC=-22.71&SR=0.1")
>>> data_origin = extract_data_origin(votable)
>>> print(data_origin)
publisher: CDS
server_software: 7.4.5
service_protocol: ivo://ivoa.net/std/ConeSearch/v1.03
request_date: 2025-03-05T14:18:05
contact: cds-question@unistra.fr
publisher: CDS

ivoid: ivo://cds.vizier/j/aj/167/18
citation: doi:10.26093/cds/vizier.51670018
reference_url: https://cdsarc.cds.unistra.fr/viz-bin/cat/J/AJ/167/18
rights_uri: https://cds.unistra.fr/vizier-org/licences_vizier.html
creator: Hong K.
...

内容和元数据#

astropy.io.votable.dataorigin.extract_data_origin 返回一个 astropy.io.votable.dataorigin.DataOrigin （类）由以下材料制成的容器：

  • 一 astropy.io.votable.dataorigin.QueryOrigin （类）描述请求的容器。 QueryOrigin 被认为是整个VOTable中独一无二的。它包括出版商、联系人、执行日期、查询等元数据。

  • 的列表 astropy.io.votable.dataorigin.DatasetOrigin 每个具有DataOrigin信息的元素的（类）容器。 DataSetOrigin 是所查询数据集的基本出处。每个属性都是一个列表。它包括作者、ivoid、着陆页面等元数据..

实例#

获取（数据中心）发布者和数据集的创建者

>>> print(data_origin.query.publisher)
CDS
>>> print(data_origin.origin[0].creator)
['Hong K.']

其他能力#

DataOrigin容器包括VO元素：

  • 提取列表 astropy.io.votable.tree.Info

    >>> # get DataOrigin with the description of each INFO
>>> for dataset_origin in data_origin.origin:
...    for info in dataset_origin.infos:
...        print(f"{info.name}: {info.value} ({info.content})")
ivoid: ivo://cds.vizier/j/aj/167/18 (IVOID of underlying data collection)
creator: Hong K. (First author or institution)
cites: bibcode:2024AJ....167...18H (Article or Data origin sources)
editor: Astronomical Journal (AAS) (Editor name (article))
original_date: 2024 (Year of the article publication)
...

  • 提取树节点 astropy.io.votable.tree.Element

下面的示例从标题中提取引用（以APA风格）。

>>> # get the Title retrieved in Element
>>> origin = data_origin.origin[0]
>>> vo_elt = origin.get_votable_element()
>>> title = vo_elt.description if vo_elt else ""
>>> print(f"APA: {','.join(origin.creator)} ({origin.publication_date[0]}). {title} [Dataset]. {data_origin.query.publisher}. {origin.citation[0]}")
APA: Hong K. (2024-11-06). Period variations of 32 contact binaries (Hong+, 2024) [Dataset]. CDS. doi:10.26093/cds/vizier.51670018

  • 将数据源信息添加到VOTable：

>>> votable = parse("votable.xml")
>>> dataorigin.add_data_origin_info(votable, "query", "Data center name")
>>> dataorigin.add_data_origin_info(votable.resources[0], "creator", "Author name")

也见#

参考/API#