edges-io 4.1.7

CLI

要运行检查工具，只需执行以下操作

$ edges-io check PATH

PATH 应该是校准观测的顶级目录（即包含子文件夹 25C/ 的文件夹，其中包含 Spectra/、Resistance/ 和 S11 等子文件夹）。您可以使用一些选项，例如更改观测温度和启用自动修复。后者可以通过 --fix 标志简单地实现。如果您发现某种特定类型的错误经常发生，请创建一个问题，以便我们可以添加修复程序。

库

库用于收集整个观测并对其数据进行操作。库公开了校准对象的层次结构，包括基对象，如 Spectrum、Resistance 或 S1P 文件，以及容器对象如 Spectra 或 S11。整个观测可以加载为 CalibrationObservation，它包含对所有子对象的引用。

例如

>>> from edges_io import io
>>> obs = io.CalibrationObservation("path_to_observation")
>>> print(obs.s11.path)
"path_to_observation/25C/S11"
>>> print(obs.spectra.ambient.path)
"path_to_observation/25C/Spectra/Ambient_XXX.acq"
>>> ambient_spectrum = obs.spectra.ambient.read()

查看 edges-cal 中 edges-io 的使用，以了解更复杂的示例。

定义观测

edges-io 的一个主要目标是使“校准观测”的定义尽可能清晰、健壮且无错误。任何特定的观测都包含许多文件——光谱、电阻测量和 S11 测量——这些都是形成校准解决方案（然后可以独立应用于现场数据）所必需的。此代码提供了这些文件必须如何布局的清晰结构，以便它们可以自动读取和使用。这在 此文档 中以正式的方式呈现，但也实现了代码本身。

在上面的文档中，规范尽可能正式地列出，该文档对允许的内容有最终决定权。然而，这可能意味着它有点难以理解，因此我们在此提供了一份更简单的指南，说明什么构成了“校准观测”。

单个自然“观测”（下面将说明如何将多个观测组合成一个单个的“虚拟”观测）是一个包含多个文件/子目录的单个目录。该目录必须按照一定规则命名，以记录时间戳并提供一些有用的观测元数据（如测量的是哪个接收器编号）。未来，观测内的元数据文件可能指定大部分这些信息，但有一个独特的标签对观测也是很有用的。

在所有这些定义中，一个重要的问题是在以下情况下应该怎么做：1) 存在一个不应该存在的文件，或2) 存在一个应该存在的文件却不存在。忽略不应该存在的额外文件可能会很有诱惑力。然而，它们可能成为错误的原因。例如，光谱可能会分布在多个文件中，我们使用文件模式来查找应该读取的文件。如果一个不应该存在的额外文件存在并且文件模式匹配它，那么可能会发生错误（如果该文件的内容能够被光谱读取器读取，但对应的是不同的加载或其他类型，结果将不正确，但不会抛出错误）。因此，在检查观察的完整性时，我们将额外文件标记为错误，并要求用户修复它们。为了使这个过程更简单一些，并让这些文件保留在目录中（这样我们就不会丢失可能有价值的信息），可以在额外文件上添加一些扩展名：

• .old：对于包含有效数据但被更新的测量所取代应被忽略的文件；

• .invalid：对于存在问题的数据（设备损坏、输入参数错误等）；

• .ignore：因为任何其他原因要忽略的文件。

如果文件没有这些扩展名，并且不在观察接受的文件列表中，检查器将抛出错误。

另一方面，如果必须存在的文件丢失，在不同情况下可能会发生不同的事情。默认情况是将此视为警告，这可能不符合直觉（显然丢失必要的文件应该是错误？！）。这样做的原因是，该文件可能被另一个观察补充。也许这个观察是不完整的——也许所有采集的数据都是一组光谱，这是为了补充一个具有完整测量集的先前观察。在这种情况下，虽然“自然”观察是不完整的，但只要给出警告，指出它必须与另一个观察组合，就不需要给出错误。尽管如此，某些文件组合必须是在同一物理观察中采集的，以确保一致性（即在给定负载中的每个标准S11测量）。如果缺少特定的标准，将抛出错误。

在下面讨论“必需”的目录/文件时，应该记住这些注意事项。“必需”将意味着在结合我们想要/需要的所有观察后（参见下一节），我们需要这个特定的文件。

在顶级观察目录中，有一些目录表示观察时所处的环境温度。这些通常为15°C、25°C或35°C。不应在不同环境温度之间混合文件。因此，实际上，观察包含在这些文件夹之一中，在实践中，CalibrationObservation 的 path 属性被设置为温度目录。

在此目录中最多可以有两个文件和恰好三个文件夹。其中一个文件是名为Notes.txt的文件，该文件总结了关于观测的可读性笔记（“我们先运行了环境光谱，但因为xxx而延迟……”）。另一个文件名为definition.yaml，其中包含观测的元数据，采用特定格式（此文件还允许您用其他观测补充观测，但稍后再谈）。例如男性/女性电阻等测量/数据应放在此处（到目前为止，它们已被分析师在执行校准时手动输入到某个地方，这是非常危险的且易于出错——它们是测量本身的一部分，而不是分析师的选择）。

这三个文件夹是Spectra、Resistance和S11。请注意，观测必须包含这三个（以及合并观测后没有其他东西）。

在Spectra中存在一些光谱，这些光谱是在实验室中针对四个“校准源”在约12-24小时内拍摄的：它们是“Ambient”、“HotLoad”、“LongCableOpen”和“LongCableShorted”（在代码中通常简称为它们的简单别名“ambient”、“hot_load”、“open”和“short”）。这些光谱将采用.acq或.h5格式，具体取决于进行测量的fastspec版本。由于fastspec获取数据的方式，每个源可能有一个单一的测量文件（每次积分都保存到文件的新行中，但每天在特定本地时间创建新文件）。因此，通常希望读取并连接该负载的所有文件，以使用所有数据。除此之外，对于给定的源/负载，可能有两种完全独立的“运行”。在这种情况下，将“运行编号”标识符放入文件名中。实际上，用于任何特定校准的运行编号只有一个。在实践中，对于任何特定负载，只有一个“可用的”运行编号是非常罕见的。通常，只有在第一个运行由于某些原因无效时，才会进行第二次运行。如果这种情况发生，应在Notes.txt和/或definition.yaml中注明。

Resistance文件夹几乎与Spectra完全相同。每个源在此处再次表示（使用相同的名称），文件名格式也相同，只是文件本身都是.csv格式。这些文件测量源的电阻读数，这些读数用于推导负载的物理温度（光谱以此进行校准）。同样，每个源都允许有多个由“运行编号”指定的“运行”。然而，在实践中，只有一个可用的运行是极其罕见的。

S11 文件夹包含源反射系数的测量数据，以及LNA本身和内部开关。这些测量都使用VNA完成，每次读数大约需要一分钟。因此，可以对这些测量进行多次读取——通常也是这样做的。在S11文件夹内部，每个主要负载（或源）都有一个文件夹，其中包含四个标准（开路、短路、匹配和外部）的测量。每个标准都可以测量多次，因此每个文件都采用格式<standard-name><rep-num>.s1p，其中rep-num从1到99。然而，对于负载的每个标准，测量都是依次在同一连接上进行的（即它们之间没有断开连接，以避免标准之间不同连接特性引起的问题）。因此，不能选择为环境源使用重复编号01为开路，重复编号2为短路。对于给定的源，所使用的所有标准必须是相同的重复编号（但可以为源存在多个运行）。除了源的S11之外，还需要测量LNA的反射和内部开关。这些分别存在于ReceiverReadingXX和SwitchingStateXX文件夹中。这里的XX对应于我们所说的“运行”编号，它对应于观察过程中不同点的完整重新测量标准。可以执行任意数量的这些运行（最多99个），但只需要一个。

在所有情况下，edges-io的默认行为是使用任何给定测量的最后运行的编号和重复编号。

使用HDF5Object

edges-io 包含一个方便的 HDF5Object 类，其目的是使处理 HDF5 文件更加正式（并且可以说更加简单）。通过继承它，您可以指定一个精确的文件布局，该布局在读取时可以验证，以确保文件格式正确（不仅仅是 HDF5，还必须有正确的数据结构、组和元数据）。

使用此类是为了在文件上提供一个非常薄的包装。例如，如果您有一个文件 my_hdf5_format_file.h5，其结构由 CustomH5Format 类定义，您可以创建如下对象

>>> fl = CustomH5Format("my_hdf5_format_file.h5")

在创建时，将检查文件的兼容性，如果文件包含多余的键或缺少所需的键，则返回错误。

创建后，fl 变量现在具有可以“查看”文件并加载数据的操作。它支持延迟加载，因此执行

>>> print(fl['dataset'].max())

将加载“数据集”数据，并获取最大值，但不会在内存中保留数据，也不会加载其他数据集。如果您在组中有数据，可以轻松地这样做

>>> print(fl['group']['dataset'].min())

要永久将数据加载到对象中，请使用 .load 方法

>>> fl.load('group')

实际上，这样做将加载“group”下的所有数据。如果您只想加载“group”中的“数据集”

>>> fl['group'].load('dataset')

如何定义 HDF5Object 的子类的示例可以在 HDF5RawSpectrum 类中看到，该类用于定义 fastspec 输出文件。

代码的工作原理稍微详细一些

为了开发者的方便（诚实地讲，这个特定仓库的大多数用户也应该是开发者），我们将试图更详细地解释代码的工作原理。这将重点介绍代码如何处理校准观测的组织，以及它是如何执行检查和进行修复的。

基本思想是每个目录和每种类型的文件都由一个独特的类表示，描述这类事物。例如，顶层目录（实际上，顶层加上环境温度目录）由 CalibrationObservation 类表示，而 Spectra 目录由 Spectra 类表示，S1P 文件由 S1P 类表示。

所有这些类都是 _DataContainer（如果是文件夹）或 _DataFile（如果是文件）的子类。它们都有一个指向其磁盘上自己的路径的 path 属性。_DataFile 类非常简单，通常只知道如何检查其自己的文件名是否符合规范，以及如何读取特定文件类型的数据（它们对它们的父类一无所知）。_DataContainer 类了解自己的 path，但也可以确定它们所包含的文件/子文件夹的列表（它们对它们的父类一无所知），并且知道如何将这些文件/文件夹映射到它们的相应定义类。它们能够检查自己的路径是否一致，确保所有相关子文件都存在，确保没有多余的文件存在，并通过调用它们的检查方法递归地检查子文件和文件夹的一致性。观测中的每个文件和文件夹都成为这些类中的一个特定 实例（对于所有 S11 测量，将有多个 S1P 实例，每个实例可能都有一个不同的 name 属性来识别它所代表的规范）。

这种自上而下的层次结构很有用，类似于Unix文件系统的工作方式。然而，这也意味着特定的实例不一定唯一：标准S11“匹配”将在所有源中存在，而且由于每个类不知道其父类，因此无法区分Ambient/Match01.s1p和HotLoad/Match01.s1p。但是，在顶层的CalibrationObservation上存在一种方法，可以将特定的输入路径与唯一定义它的实例的序列相匹配（即，第一个将包含一个具有name=Ambient的LoadS11类的序列，第二个将包含一个具有name=HotLoad的LoadS11类的序列）。

关于设置要注意的另一件事是类及其类的实例之间的差异。系统的大部分功能都是通过类本身实现的——例如，不需要创建类的实例来执行文件系统检查。在这种情况下，路径被传递给类的check()方法，例如CalibrationObservation.check(path)，它将调用其子代中的任何check方法等。这永远不会读取任何数据，它只是检查文件名格式和目录内容。然而，可以创建一个CalibrationObservation的实例，它将本身去创建所有子代实例，并以一种优雅的层次方式将它们存储在顶层类中，其中每个子代都可以独立使用。默认情况下，当创建此类实例时，它将首先执行本应执行的完整检查（但在这种情况下，它应该在第一个错误发生时退出并引发错误，而不是继续并打印所有错误）。值得注意的是，这些实例可以用于读取文件中的数据。实例还将决定在观察中使用哪些文件（即，哪些运行编号和重复编号）。