文档
Bluesky的一个主要设计目标是通过与测量数据一起记录丰富的元数据为之后分析使用来支持更好的研究。文档是我们如何做这件事。
一个document是我们对应一个有schema的Python字典的术语-既是,用正式的指定方式组织-在计划执行中,由RunEngine创建。由执行这个计划产生的所有元数据和数据被组织进文档。
之后章节描述外部函数能够如何"订阅"一个这些文档的流,可视化,处理或者保存它们。本章提供文档自身的概要,目的为感受这个结构并且熟悉有用的组件。
一个"Run"的概要
每个文档属于一个run,笼统讲,一个数据集。执行任何内建预组装计划,如scan()和count(),创建一个run。
注意
基本上,一个run地范围是故意模糊并且灵活地。一个计划可能产生很多runs或者一个长的run。它仅取决于你想要如何组织你的数据,两者都在采集时和分析时。
教程Capure Data章节解释这个。
在每个run中的文档是:
1)一个Run启动文档,包含这个run开始时所知的所有元数据。重点:
- time:启动时间
- plan_name:例如,'scan'或'count'
- uid:标识这个run的唯一ID
- scan_id:人性化整数扫描ID(非必须唯一)
- 在执行时从计划或用户捕获的任何其他元数据
2)Event文档,包含实际的测量。这些是你的数据。
- time:一个对应此读数组的时间戳
- req_num:顺序编号,从1向上数。
- data:一个像{'temperaure':5.0, 'position':3.0}的读数字典。
- timestamps:一个每次读数的单独时间戳,来自硬件
3)Event描述符文档:为在Event文档中的数据提供一个schema。它们列出了Event的数据中的所有键,并且给出了有关它们的有用信息,诸如单位和精度。它们也包含了有关这个硬件的配置的信息。
4)一个Run停止文档,包含仅在这个run结束时知道的元数据。重点:
- time:当运行结束时的时间。
- exit_status:"success", "abort"或"fail"
每个文档有一个time(其创建时间)和一个单独的uid来标识它。这个事件文档也有一个描述符字段,它用它们的元数据链接它们到事件描述符。并且事件描述符和Run停止文档有一个run_start字段,它链接它们到它们的Run开始,在一个run中所有文档被链接回这个Run开始。
具体的文档
Run Start
一个'srart'文档标记这个run的开始。它包含了在我们开始采集数据前我们知道的所有东西,包括用户和计划提供的所有元数据。(下章更多有过这方面)。
所有内建计划提供一些有用的元数据,像使用的探测器和电机的名称。(用户定义的计划也可能做这件事)
命令:
from bluesky.plans import scan
from ophyd.sim import det, motor # 模拟的探测器,电机
# 用10步从-3到3扫描'motor',从'det'获取读数
RE(scan([det], motor, -3, 3, 16), purpose='calibration',
sample='kryptonite')
产生像这样的一个'start'文档:
# 'start' document
{'purpose': 'calibration',
'sample': 'kryptonite',
'detectors': ['det'],
'motors': ['motor'],
'plan_name': 'scan',
'plan_type': 'generator',
'plan_args': {'detectors': '[det]',
'motor': 'Mover(...)',
'num': '16',
'start': '-3',
'stop': '3'},
'scan_id': 282,
'time': 1442521005.6099606,
'uid': '<randomly-generated unique ID>',
}
注意:时间用UNIX时间给出(从1970以来的秒数)。用于查找数据的软件,当然,转换其为一个更适合人阅读的格式。
Event
一个'event'记录一个或多个具有相关联时间的测量。
# 'event' document
{'data':
{'temperature': 5.0,
'x_setpoint': 3.0,
'x_readback': 3.05},
'timestamps':
{'temperature': 1442521007.9258342,
'x_setpoint': 1442521007.5029348,
'x_readback': 1442521007.5029348},
'time': 1442521007.3438923,
'seq_num': 1
'uid': '<randomly-generated unique ID>',
'descriptor': '<reference to a descriptor document>'}
从一个数据分析的角度,这些读数是同时的,但实际上,它们在单独时间发生的。各自读数的单独时间没有被丢弃(它们被记录在'时间戳'中),但整个事件'time'经常更有用。
Run Stop
一个'stop'文档标记了这个run的结束。它包含了在run结束前未知的元数据。
这里最常见有用字段是'time'和'exit_status'。
# 'stop' document
{'exit_status': 'success', # or 'fail' or 'abort'
'reason': '', # The RunEngine can provide reason for failure here.
'time': 1442521012.1021606,
'uid': '<randomly-generated unique ID>',
'start': '<reference to the start document>',
'num_events': {'primary': 16}
}
Event描述符
如上所述,一个'描述符'文档为在Event文档中数据提供了一个纲要。它提供了有关数据中每个键的有用信息以及有关硬件的配置。一个描述符的结构是详细的,并且需要一些事件来讨论,因此,我们推迟它到之后章节。