pdr 0.7.0

自述文件.md

行星数据阅读器 (pdr)

这个工具提供了一个命令--- read(‘/path/to/file’)---用于摄取 所有常见的行星数据类型。它目前正在开发中。目前存档在 PDS（在 PDS3 或 PDS4 下）中的几乎所有类型的“主要观测数据”产品最终都应该被涵盖。当前支持的数据集在此处列出。

如果软件在尝试从我们列为支持的数据集读取数据时失败，请提交一个问题，其中包含指向文件的链接和有关错误的信息（如果适用）。可能还有一些有效但未列出的数据集。我们也想听听这些。如果您希望我们考虑优先考虑的数据集尚不支持，请填写此申请表。

安装

pdr现在打开conda并且pip. 我们建议（并且仅官方支持）安装到conda环境中。你可以这样做：

conda create --name pdrenv
conda activate pdrenv
conda install -c conda-forge pdr

支持的最低 Python 版本是3.9。

使用 conda install 将安装 pdr 的 environment.yml 文件中的所有依赖项（必需的和可选的）。如果您希望放弃可选依赖项，请在安装中使用 minimum_environment.yml。如上所述，直接安装 conda 不支持此操作，需要执行其他步骤。下面列出了可选的依赖项和它们支持的附加功能：

• pvl: 允许Data.load("LABEL", as_pvl=True)将 PDS3 标签作为pvl对象而不是纯文本加载
• astropy: 添加对 FITS 文件的支持
• jupyter：允许使用示例 Jupyter Notebook（以及您创建的其他 Jupyter Notebook）
• pillow: 添加对 TIFF 文件和浏览图像渲染的支持
• matplotlib：允许使用save_sparklines，一个实验性的浏览功能

用法

（您可以查看我们在 Binder 上的示例 Notebook 以获得快速的交互式功能演示 ：）

只需运行import pdr然后pdr.read(filename)，其中filename是数据文件或元数据/标签文件（扩展名 .LBL、.lbl 或 .xml）的完整路径。read()将在同一路径中查找相应的数据或元数据文件，或者如果数据文件带有附加标签，则直接从数据文件中读取元数据。

read返回一个pdr.Data对象，其属性包括所有数据和元数据。数据属性的名称直接取自产品标签。它们可以作为属性访问，也可以使用 dict-style [] 索引表示法访问。例如，PDS3 图像对象通常被命名为“IMAGE”，因此您可以将 PDS3 图像作为一个数组来检查：

>>> data = pdr.read("/path/to/cr0_398560467edr_f0030004ccam02012m1.LBL")
>>> data['IMAGE']
array([[21, 21, 20, ..., 19, 19, 20],
       [21, 21, 21, ..., 19, 20, 20],
       [21, 21, 20, ..., 20, 20, 20],
       ...,
       [25, 25, 25, ..., 26, 26, 26],
       [25, 25, 25, ..., 27, 26, 26],
       [24, 25, 25, ..., 26, 26, 26]], dtype=int16)

解析后的元数据存储在对象中并作为对象的属性pdr.Metadata公开 。您可以使用-style [] 索引表示法或便捷方法访问元数据值。例如：metadatapdr.Datadictmetaget

>>> data.metaget('INSTRUMENT_HOST_NAME')
'MARS SCIENCE LABORATORY'

一些 PDS 产品（比如这个）包含多个数据对象。您可以查看与产品关联的所有对象.keys()：

>>> data.keys()
['LABEL',
 'IMAGE_HEADER',
 'ANCILLARY_TABLE',
 'CMD_REPLY_FRAME_SOHB_TABLE',
 'SOH_BEFORE_CHECKSUM_TABLE',
 'TAKE_IMAGE_TIME_TABLE',
 'CMD_REPLY_FRAME_SOHA_TABLE',
 'SOH_AFTER_CHECKSUM_TABLE',
 'MUHEADER_TABLE',
 'MUFOOTER_TABLE',
 'IMAGE_REPLY_TABLE',
 'IMAGE',
 'MODEL_DESC']

输出数据类型

一般来说：

• 图像数据以 NumPyndarray对象的形式呈现。
• 表数据以 pandasDataFrame对象的形式呈现。
• 解析的标签内容（元数据字段 + 值）呈现在一个 pdr.Metadata对象中（行为很像 a dict）。
• 标题和标签内容显示为纯文本（str对象） bytes，或者，对于 PDS4 标签，pds4_tools.reader.label_objects.Label对象。
• 其他数据显示为简单的 Python 类型（str、、、tuple）dict。
• 可能有极少数例外。

注意事项和注意事项

附加处理

一些数据，尤其是校准的图像数据，需要应用额外的偏移量或比例因子来将存储单位转换为有意义的物理单位。有关如何以及何时应用此类调整的信息通常存储（作为纯文本）在仪器 SIS 中，并且比例因子本身通常（但不总是）存储在标签中。图像数据还经常包含特殊常量（如缺失或无效数据），而这些常量通常没有在标签中明确指定。 pdr因此不能保证正确应用——甚至不知道——这些常量。

pdr.Data对象提供了一种方便的方法，该方法尝试屏蔽无效值并应用标签中指定的任何缩放和偏移。像这样使用它： scaled_image = data.get_scaled('IMAGE'). 但是，我们不对这些输出进行科学验证，因此不要相信它们已准备好进行分析而无需进一步处理或验证。非常欢迎为使特定数据产品类型更有效的贡献做出贡献。

如果您想可视化由此创建的输出，该dump_browse 方法会为您的工作目录中的所有当前加载的对象（如 .jpg、.txt. 或 .csv）创建单独的浏览文件。像这样使用它： data.dump_browse(). 这将使用get_scaled图像的方法，并且还将输出用于表格和标签的浏览产品。

.FMT 文件

一些 PDS3 表格格式在外部参考文件中定义（通常带有.FMT扩展名）。您通常可以在数据存档卷的 LABEL 或 DOCUMENT 子目录中找到它们。如果您将相关格式文件与您尝试读取的数据文件放在同一目录中，pdr 将能够使用它们来解释表数据。如果您尝试读取需要不存在格式文件的表格对象，pdr将无法打开表格对象，并且会抛出包含格式文件名的警告，以帮助您找到它。未来的功能可能会使这个过程更顺畅。

数据属性命名

对象的观察和元数据属性（或键）pdr.Data 直接取自元数据文件的名称。我们认为，保持语言中数据表示和文件中数据表示之间的这种强相关性很重要，即使它导致我们违反了严格的 PEP-8 属性大写标准。目前有三个例外：

1. 某些表格格式包含重复的列名。为了可用性和兼容性，我们通过添加 0 索引递增整数后缀来强制它们是唯一的。因此，包含两个名为“COLUMN”的单独列的表定义将返回一个包含名为“COLUMN_0”和“COLUMN_1”的列的 pandas DataFrame。
2. PDS3 数据对象名称有时包含空格。pdr用下划线替换空格，以使它们可用作属性。

PDS4 产品

pdr.Data换pds4_tools 行以读取 PDS4 产品。应完全支持所有有效的 PDS4 产品。pdr 修改一些pds4_tools输出以提供接口和行为的一致性。一般来说，您应该能够像使用pdrPDS3 产品一样使用 PDS4 产品。

一些 PDS 数据产品同时具有 PDS3 和 PDS4 标签。数据对象名称、元数据，甚至数据字段名称和格式规范通常在这些标签之间略有不同，因此pdr根据您用于初始化它的标签，可能会产生略有不同的输出。这不是错误。但是，一般来说，如果 PDS3 标签可用，我们建议从 PDS3 标签而不是 PDS4 标签初始化对象。

延迟加载

由于许多行星数据对象非常大，因此pdr可以通过延迟加载它们来节省您的时间和内存。它将数据对象在显式引用时加载到内存中，而不是在pdr.Data初始化时加载。例如，data.IMAGE如果 IMAGE 对象尚未加载，引用将立即加载它。或者，您可以使用load方法加载对象，例如data.load("IMAGE"). 您还可以传递 'all' 参数来加载所有数据对象，例如data.load("all").

缺少文件

如果标签引用的文件丢失，pdr将抛出警告并从标签中提及该文件的部分填充相关属性。对于文档格式（如 .TXT）的说明文件，您最有可能遇到这种情况。这些警告不会阻止您使用从文件系统中实际存在的文件加载的对象。

大文件（如 HiRISE）

pdr目前不执行特殊的内存管理，因此在尝试读取非常大的文件时要小心。我们打算在未来实现内存管理。

测试

我们的pdr测试方法目前侧重于端到端集成测试，以确保一致性、支持的数据集的覆盖范围以及（在我们可以验证的范围内）输出的正确性。

pdr的测试套件位于不同的存储库中： https ://github.com/MillionConcepts/pdr-tests 。它的核心是一个名为 ix的应用程序。它应该被认为是一个相当完整的 alpha；我们正在积极地将其用作回归测试套件和积极的开发工具。

这项工作得到了 NASA 资助号 80NSSC21K0885 的支持。