可变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 记录数组。

列的名称来自 IDname 的属性 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映射 nameID 属性到 numpy D型 namestitles 非常令人困惑。

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

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

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

astropy.io.votable.tree.Table 反对 astropy.table.Table 对象,则可以指定是否将 nameID 命名列时的属性。默认情况下, 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.1Version 1.2Version 1.3 proposed recommendation . 提供了一些灵活性来支持1.0草案版本和其他非标准的使用。要支持这些情况,请设置关键字参数 pedanticFalse 解析时。

注解

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

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

迂腐模式

许多VOTable文件不符合VOTable规范。如果读取其中一个文件导致异常,则可以在中关闭pedantic模式 astropy.io.votable 旁路 pedantic=Falseparseparse_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 \(来源, *  * 克瓦格斯)

解析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 \(votable,字段[, ID, null, ref, ...] )

VALUES 元素:用于 FIELDPARAM 元素来定义值的域。

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 元素:组 FIELDPARAM 元素。

Table \(可有可无[, ID, name, ref, ucd, utype, ...] )

TABLE 元素:可选地包含数据。

Resource \ [name, ID, utype, type, id, ...] )

RESOURCE 图元组:图元 TABLERESOURCE 元素。

VOTableFile \ [ID, id, config, pos, version] )

VOTABLE 元素:表示整个文件。

Element \()

表示可投票文件中的XML元素的所有类的基类。

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

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

功能

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 \(令牌,属性u名称[, 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公司.异常模块