可变XML处理 (astropy.io.votable ）

介绍

这个 astropy.io.votable 子包将VOTable XML文件转换为 numpy 记录数组。

入门

读取VOTable文件

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

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

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

VOTable文件由嵌套的 RESOURCE 元素，每个元素可以包含一个或多个 TABLE 元素。这个 TABLE 元素包含数据数组。

到达 TABLE 元素，可以在 VOTABLE 文件：：

for resource in votable.resources:
    for table in resource.tables:
        # ... do something with the table ...
        pass

但是，如果资源的嵌套结构不重要，则可以使用 iter_tables 要返回所有表的简单列表：

for table in votable.iter_tables():
    # ... do something with the table ...
    pass

最后，如果希望文件中只有一个表，那么使用它可能最方便 get_first_table ：：

table = votable.get_first_table()

或者，有一种方便的方法来解析VOTable文件并在一个步骤中返回第一个表：

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

从A Table 对象，则可以在 array 成员变量：：

data = table.array

此数据是 numpy 记录数组。

列的名称来自 ID 和 name 的属性 FIELD 中的元素 VOTABLE 文件。

实例

假设我们有 FIELD 具体如下：

<FIELD ID="Dec" name="dec_targ" datatype="char" ucd="POS_EQ_DEC_MAIN"
       unit="deg">
 <DESCRIPTION>
  representing the ICRS declination of the center of the image.
 </DESCRIPTION>
</FIELD>

备注

VOTable映射 name 和 ID 属性到 numpy D型 names 和 titles 非常令人困惑。

在VOTable中， ID 保证是唯一的，但不是必需的。 name 不保证是唯一的，但是必需的。

在 numpy 记录数据类型， names 必须是唯一的，并且是必需的。 titles 不是必需的，也不要求是唯一的。

因此，VOTable的 ID 最接近于 numpy 的 names ，和VOTable的 name 最接近于 numpy 的 titles . 但是，在某些情况下 ID 未提供，a numpy name 将基于VOTable生成 name . 不幸的是，VOTable字段没有既唯一又必需的属性，这是唯一标识列的最方便的机制。

从 astropy.io.votable.tree.Table 反对 astropy.table.Table 对象，则可以指定是否将 name 或 ID 命名列时的属性。默认情况下， ID 优先考虑。给予 name 首选项，传递关键字参数 use_names_over_ids=True ：：

>>> votable.get_first_table().to_table(use_names_over_ids=True)

可以使用以下方法从记录数组中提取此数据列：

>>> table.array['dec_targ']
array([17.15153360566, 17.15153360566, 17.15153360566, 17.1516686826,
       17.1516686826, 17.1516686826, 17.1536197136, 17.1536197136,
       17.1536197136, 17.15375479055, 17.15375479055, 17.15375479055,
       17.1553884541, 17.15539736932, 17.15539752176,
       17.25736014763,
       # ...
       17.2765703], dtype=object)

或相当于：

>>> table.array['Dec']
array([17.15153360566, 17.15153360566, 17.15153360566, 17.1516686826,
       17.1516686826, 17.1516686826, 17.1536197136, 17.1536197136,
       17.1536197136, 17.15375479055, 17.15375479055, 17.15375479055,
       17.1553884541, 17.15539736932, 17.15539752176,
       17.25736014763,
       # ...
       17.2765703], dtype=object)

从头开始构建新表

还可以构建一个新表，定义一些字段数据类型，并用数据填充它。

例子

要从VOTable文件生成新表，请执行以下操作：

from astropy.io.votable.tree import VOTableFile, Resource, Table, Field

# Create a new VOTable file...
votable = VOTableFile()

# ...with one resource...
resource = Resource()
votable.resources.append(resource)

# ... with one table
table = Table(votable)
resource.tables.append(table)

# Define some fields
table.fields.extend([
        Field(votable, name="filename", datatype="char", arraysize="*"),
        Field(votable, name="matrix", datatype="double", arraysize="2x2")])

# Now, use those field definitions to create the numpy record arrays, with
# the given number of rows
table.create_arrays(2)

# Now table.array can be filled with data
table.array[0] = ('test1.xml', [[1, 0], [0, 1]])
table.array[1] = ('test2.xml', [[0.5, 0.3], [0.2, 0.1]])

# Now write the whole thing to a file.
# Note, we have to use the top-level votable file object
votable.to_xml("new_votable.xml")

输出VOTable文件

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

votable.to_xml('output.xml')

支持多种数据存储格式 astropy.io.votable . 这个 TABLEDATA 格式基于XML，并将值存储为表示数字的字符串。这个 BINARY 格式更紧凑，以base64编码的二进制文件存储数字。VOTable版本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')

使用 astropy.io.votable

标准符合性

astropy.io.votable.tree.Table 支持 VOTable Format Definition Version 1.1 ， Version 1.2 和 Version 1.3 proposed recommendation . 提供了一些灵活性来支持1.0草案版本和其他非标准的使用。要支持这些情况，请设置关键字参数 pedantic 到 False 解析时。

备注

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

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

迂腐模式

许多VOTable文件不符合VOTable规范。如果读取其中一个文件导致异常，则可以在中关闭pedantic模式 astropy.io.votable 旁路 pedantic=False 到 parse 或 parse_single_table 功能：：

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

但是，请注意，最好向生成VOTable文件的应用程序的作者报告这些错误，以使文件符合规范。

即使 pedantic 关闭后，许多警告仍可能被忽略。这些警告都属于这种类型 VOTableSpecWarning 并且可以使用标准Python关闭 warnings 模块。

缺少值

表中的任何值都可能是“缺少”。 astropy.io.votable 存储a numpy 每个中的屏蔽数组 Table 实例。这表现得像个普通人 numpy 屏蔽数组，可变长度字段除外。对于这些字段，列的数据类型是“object”和另一个 numpy 蒙面数组存储在那里。因此，对可变长度列的操作将不起作用-这是因为不直接支持可变长度列 numpy 屏蔽数组。

数据类型映射

由指定的数据类型 FIELD 元素映射到 numpy 根据下表键入：

VOTABLE类型	NumPy类型
布尔	地下一层
一点	地下一层
无符号字节	u1
字符( 可变长度 ）	O-A型 bytes() 对象。
字符( 固定长度 ）	S
独角兽( 可变长度 ）	O-A型 str 对象
独角兽( 固定长度 ）	U
短的	I2
利息	i4号
长的	十八
浮动	4层
双重的	8楼
漂浮物	第八章
双重复合体	c16型

如果字段是固定大小的数组，则数据存储为 numpy 固定大小数组。

如果数组的大小是一个变量， arraysize 包含“*”），则单元格将包含 numpy 价值观。每个值可以是数组或标量，具体取决于 arraysize 说明符。

检查字段类型

要在表中查找有关字段的更多信息，可以使用 get_field_by_id 方法，它返回 Field 具有给定ID的对象。

例子

要查找有关字段的更多信息，请执行以下操作：

>>> field = table.get_field_by_id('Dec')
>>> field.datatype
'char'
>>> field.unit
'deg'

备注

不应更改字段描述符。若要更改列集，请将表转换为 astropy.table.Table ，进行更改，然后将其转换回原处。

数据序列化格式

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

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

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

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

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

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

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

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 Format Definition Version 1.1

• VOTable Format Definition Version 1.2

• VOTable Format Definition Version 1.3, Proposed Recommendation

参考/API

astropy.io.votable公司包裹

这个包读取和写入虚拟天文台（VO）计划使用的数据格式，特别是VOTable XML格式。

功能

parse(source[, columns, invalid, verify, ...])	解析A VOTABLE xml文件（或类似文件的对象），并返回 VOTableFile 对象。
parse_single_table(source, **kwargs)	解析A VOTABLE xml文件（或类似文件的对象），只读取和返回第一个 Table 实例。
validate(source[, output, xmllint, filename])	打印给定文件的验证报告。
from_table(table[, table_id])	给定一个 Table 对象，返回 VOTableFile 只包含那个表的文件结构。
is_votable \(来源)	读取文件的头以确定它是否是VOTable文件。
writeto(table, file[, tabledata_format])	写入 VOTableFile 到A VOTABLE xml文件。

Classes

Conf \()

的配置参数 astropy.io.votable .

astropy.io.votable公司.tree模块

Classes

Link([ID, title, value, href, action, id, ...])	LINK 元素：用于通过URI引用外部文档和服务器。
Info([ID, name, value, id, xtype, ref, ...])	INFO 元素：标准扩展的任意键值对。
Values(votable, field[, ID, null, ref, ...])	VALUES 元素：用于 FIELD 和 PARAM 元素来定义值的域。
Field(votable[, ID, name, datatype, ...])	FIELD 元素：描述特定数据列的数据类型。
Param(votable[, ID, name, value, datatype, ...])	PARAM 元素：数据中的常量值列。
CooSys([ID, equinox, epoch, system, id, ...])	COOSYS 元素：定义坐标系。
TimeSys([ID, timeorigin, timescale, ...])	TIMESYS 元素：定义时间系统。
FieldRef(table, ref[, ucd, utype, config, pos])	FIELDref 元素：用于 GROUP 要引用远程的元素 FIELD 元素。
ParamRef(table, ref[, ucd, utype, config, pos])	PARAMref 元素：用于 GROUP 要引用远程的元素 PARAM 元素。
Group(table[, ID, name, ref, ucd, utype, ...])	GROUP 元素：组 FIELD 和 PARAM 元素。
Table(votable[, ID, name, ref, ucd, utype, ...])	TABLE 元素：可选地包含数据。
Resource([name, ID, utype, type, id, ...])	RESOURCE 图元组：图元 TABLE 和 RESOURCE 元素。
VOTableFile([ID, id, config, pos, version])	VOTABLE 元素：表示整个文件。
Element \()	表示可投票文件中的XML元素的所有类的基类。

astropy.io.votable公司.转换器模块

此模块处理各种VOTABLE数据类型到/来自的转换 TABLEDATA 和 BINARY 格式。

功能

get_converter(field[, config, pos])	为给定字段获取适当的转换器实例。
table_column_to_votable_datatype \(列)	给出了一个 astropy.table.Column 实例，返回创建与列类型对应的VOTable字段元素所需的属性。

Classes

Converter(field[, config, pos])

所有转换器的基类。

astropy.io.votable公司.ucd模块

此文件包含验证UCD字符串正确性的例程。

功能

parse_ucd(ucd[, ...])	将UCD解析为其组件。
check_ucd(ucd[, ...])	返回False if ucd 不是有效的 unified content descriptor .

astropy.io.votable公司.util模块

各种各样的公用事业和食谱之类的东西。

功能

convert_to_writable_filelike(fd[, compressed])	返回适合流式输出的可写的类似文件的对象。
coerce_range_list_param(p[, frames, numeric])	强制和/或验证对象 p 转换为有效的范围列表格式参数。

astropy.io.votable公司.validator包

验证可通过web访问的VOTable文件的大量集合，并将报告生成为HTML文件的目录树。

功能

make_validation_report([urls, destdir, ...])

验证可通过web访问的大量VOTable文件集合。

astropy.io.votable公司.xmlutil模块

各种与XML相关的实用程序

功能

check_id(ID[, name, config, pos])	提出一个 VOTableSpecError 如果 ID 不是有效的XML ID.
fix_id(ID[, config, pos])	给定一个任意字符串，创建一个可用作xml id的字符串。
check_token(token, attr_name[, config, pos])	提出一个 ValueError 如果 令牌 不是有效的XML标记。
check_mime_content_type(content_type[, ...])	提出一个 VOTableSpecError 如果 content_type 不是有效的MIME内容类型。
check_anyuri(uri[, config, pos])	提出一个 VOTableSpecError 如果 uri 不是有效的URI。
validate_schema(filename[, version])	根据适当的VOTable架构验证给定的文件。

astropy.io.votable公司.异常模块

• astropy.io.votable.exceptions