可变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 属性。如果未指定行数，则必须在加载期间重复调整记录数组的大小。

也见¶

参考/API¶

astropy.io.votable公司包裹¶

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

功能¶

`parse` \(来源[, columns, invalid, verify, ...] )	解析A VOTABLE xml文件（或类似文件的对象），并返回 `VOTableFile` 对象。
`parse_single_table` \(来源，** Kwargs)	解析A VOTABLE xml文件（或类似文件的对象），只读取和返回第一个 `Table` 实例。
`validate` \(来源[, output, xmllint, filename] )	打印给定文件的验证报告。
`from_table` \(表[, table_id] )	给定一个 `Table` 对象，返回 `VOTableFile` 只包含那个表的文件结构。
`is_votable` \(源)	读取文件的头以确定它是否是VOTable文件。
`writeto` \(表、文件 [, 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` \(可投票的，字段[, ID, null, ref, ...] )	VALUES 元素：用于 FIELD 和 PARAM 元素来定义值的域。
`Field` \(可投票 [, ID, name, datatype, ...] )	FIELD 元素：描述特定数据列的数据类型。
`Param` \(可投票 [, ID, name, value, datatype, ...] )	PARAM 元素：数据中的常量值列。
`CooSys` \([ID, equinox, epoch, system, id, ...] )	COOSYS 元素：定义坐标系。
`TimeSys` \([ID, timeorigin, timescale, ...] )	TIMESYS 元素：定义时间系统。
`FieldRef` \(表，参考[, ucd, utype, config, pos] )	FIELDref 元素：用于 GROUP 要引用远程的元素 FIELD 元素。
`ParamRef` \(表，参考[, ucd, utype, config, pos] )	PARAMref 元素：用于 GROUP 要引用远程的元素 PARAM 元素。
`Group` \(表[, ID, name, ref, ucd, utype, ...] )	GROUP 元素：组 FIELD 和 PARAM 元素。
`Table` \(可投票 [, 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` \(字段[, config, pos] )	为给定字段获取适当的转换器实例。
`table_column_to_votable_datatype` \(列)	给出了一个 `astropy.table.Column` 实例，返回创建与列类型对应的VOTable字段元素所需的属性。

Classes¶

Converter \(字段[, 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` \(标记，属性_名称[, config, pos] )	提出一个 `ValueError` 如果令牌不是有效的XML标记。
`check_mime_content_type` \(内容_类型[, ...] )	提出一个 `VOTableSpecError` 如果 content_type 不是有效的MIME内容类型。
`check_anyuri` \(URI[, config, pos] )	提出一个 `VOTableSpecError` 如果 uri 不是有效的URI。
`validate_schema` \(文件名[, version] )	根据适当的VOTable架构验证给定的文件。

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

astropy.io.votable.exceptions

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

导航

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

介绍¶

入门¶

读取VOTable文件¶

实例¶

从头开始构建新表¶

例子¶

输出VOTable文件¶

使用 astropy.io.votable¶

标准符合性¶

迂腐模式¶

缺少值¶

数据类型映射¶

检查字段类型¶

例子¶

数据序列化格式¶

转换为/从 astropy.table.Table¶

性能注意事项¶

也见¶

参考/API¶

astropy.io.votable公司包裹¶

功能¶

Classes¶

astropy.io.votable公司.tree模块¶

Classes¶

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

功能¶

Classes¶

astropy.io.votable公司.ucd模块¶

功能¶

astropy.io.votable公司.util模块¶

功能¶

astropy.io.votable公司.validator包¶

功能¶

astropy.io.votable公司.xmlutil模块¶

功能¶

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

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

使用 `astropy.io.votable`¶

转换为/从 `astropy.table.Table`¶