katdal 0.23

快速教程

通过单个函数打开任何数据集以获取数据集对象

import katdal
d = katdal.open('1234567890.h5')

open函数会自动确定数据集的版本和存储位置。版本大致对应于各种仪器

- v1 : Fringe Finder (HDF5 file)
- v2 : KAT-7 (HDF5 file)
- v3 : MeerKAT (HDF5 file)
- v4 : MeerKAT (RDB file + chunk store based on objects in Ceph)

每个MVFv4数据集被拆分为一个Redis转储（即RDB）文件，其中包含以望远镜状态数据库形式的元数据，以及一个包含可见数据的小块或数据块（通常通过网络上的Ceph对象存储提供服务）的数据块存储。RDB文件是数据集的主要入口点，如果您有适当的权限，可以直接从MeerKAT SDP存档访问它

# This is just for illustration - the real URL looks a bit different
d = katdal.open('https://archive/1234567890/1234567890_sdp_l0.rdb?token=AsD3')

多个数据集（甚至是不同版本的）也可以连接在一起（只要它们具有相同的转储速率）

d = katdal.open(['1234567890.h5', '1234567891.h5'])

通过打印对象来检查数据集的内容

print(d)

以下是一个典型的输出

===============================================================================
Name: 1313067732.h5 (version 2.0)
===============================================================================
Observer: someone  Experiment ID: 2118d346-c41a-11e0-b2df-a4badb44fe9f
Description: 'Track on Hyd A,Vir A, 3C 286 and 3C 273'
Observed from 2011-08-11 15:02:14.072 SAST to 2011-08-11 15:19:47.810 SAST
Dump rate: 1.00025 Hz
Subarrays: 1
ID  Antennas                            Inputs  Corrprods
 0  ant1,ant2,ant3,ant4,ant5,ant6,ant7  14      112
Spectral Windows: 1
ID  CentreFreq(MHz)  Bandwidth(MHz)  Channels  ChannelWidth(kHz)
 0  1822.000         400.000          1024      390.625
-------------------------------------------------------------------------------
Data selected according to the following criteria:
subarray=0
ants=['ant1', 'ant2', 'ant3', 'ant4', 'ant5', 'ant6', 'ant7']
spw=0
-------------------------------------------------------------------------------
Shape: (1054 dumps, 1024 channels, 112 correlation products) => Size: 967.049 MB
Antennas: *ant1,ant2,ant3,ant4,ant5,ant6,ant7  Inputs: 14  Autocorr: yes  Crosscorr: yes
Channels: 1024 (index 0 - 1023, 2021.805 MHz - 1622.195 MHz), each 390.625 kHz wide
Targets: 4 selected out of 4 in catalogue
ID  Name    Type      RA(J2000)     DEC(J2000)  Tags  Dumps  ModelFlux(Jy)
 0  Hyd A   radec      9:18:05.28  -12:05:48.9          333      33.63
 1  Vir A   radec     12:30:49.42   12:23:28.0          251     166.50
 2  3C 286  radec     13:31:08.29   30:30:33.0          230      12.97
 3  3C 273  radec     12:29:06.70    2:03:08.6          240      39.96
Scans: 8 selected out of 8 total       Compscans: 1 selected out of 1 total
Date        Timerange(UTC)       ScanState  CompScanLabel  Dumps  Target
11-Aug-2011/13:02:14 - 13:04:26    0:slew     0:             133    0:Hyd A
            13:04:27 - 13:07:46    1:track    0:             200    0:Hyd A
            13:07:47 - 13:08:37    2:slew     0:              51    1:Vir A
            13:08:38 - 13:11:57    3:track    0:             200    1:Vir A
            13:11:58 - 13:12:27    4:slew     0:              30    2:3C 286
            13:12:28 - 13:15:47    5:track    0:             200    2:3C 286
            13:15:48 - 13:16:27    6:slew     0:              40    3:3C 273
            13:16:28 - 13:19:47    7:track    0:             200    3:3C 273

打印输出的第一部分显示了数据集的静态信息，包括观测者、转储速率以及数据集中所有可用的子阵列和频谱窗口。第二部分（在虚线之间）突出了活动的选择标准。最后一部分显示了受选择影响的动态信息，包括整体可见性数组形状、天线、信道频率、目标和信息。

数据集围绕三维可见性数组的概念构建，其维度为时间、频率和相关性乘积。这反映在数据集的形状上

d.shape

它返回(1054, 1024, 112)，表示1054次转储、1024个信道和112个相关性乘积。

让我们选择数据集的一个子集

d.select(scans='track', channels=slice(200, 300), ants='ant4')
print(d)

这导致以下打印输出

===============================================================================
Name: /Users/schwardt/Downloads/1313067732.h5 (version 2.0)
===============================================================================
Observer: siphelele  Experiment ID: 2118d346-c41a-11e0-b2df-a4badb44fe9f
Description: 'track on Hyd A,Vir A, 3C 286 and 3C 273 for Lud'
Observed from 2011-08-11 15:02:14.072 SAST to 2011-08-11 15:19:47.810 SAST
Dump rate: 1.00025 Hz
Subarrays: 1
ID  Antennas                            Inputs  Corrprods
 0  ant1,ant2,ant3,ant4,ant5,ant6,ant7  14      112
Spectral Windows: 1
ID  CentreFreq(MHz)  Bandwidth(MHz)  Channels  ChannelWidth(kHz)
 0  1822.000         400.000          1024      390.625
-------------------------------------------------------------------------------
Data selected according to the following criteria:
channels=slice(200, 300, None)
subarray=0
scans='track'
ants='ant4'
spw=0
-------------------------------------------------------------------------------
Shape: (800 dumps, 100 channels, 4 correlation products) => Size: 2.560 MB
Antennas: ant4  Inputs: 2  Autocorr: yes  Crosscorr: no
Channels: 100 (index 200 - 299, 1943.680 MHz - 1905.008 MHz), each 390.625 kHz wide
Targets: 4 selected out of 4 in catalogue
ID  Name    Type      RA(J2000)     DEC(J2000)  Tags  Dumps  ModelFlux(Jy)
 0  Hyd A   radec      9:18:05.28  -12:05:48.9          200      31.83
 1  Vir A   radec     12:30:49.42   12:23:28.0          200     159.06
 2  3C 286  radec     13:31:08.29   30:30:33.0          200      12.61
 3  3C 273  radec     12:29:06.70    2:03:08.6          200      39.32
Scans: 4 selected out of 8 total       Compscans: 1 selected out of 1 total
Date        Timerange(UTC)       ScanState  CompScanLabel  Dumps  Target
11-Aug-2011/13:04:27 - 13:07:46    1:track    0:             200    0:Hyd A
            13:08:38 - 13:11:57    3:track    0:             200    1:Vir A
            13:12:28 - 13:15:47    5:track    0:             200    2:3C 286
            13:16:28 - 13:19:47    7:track    0:             200    3:3C 273

与第一个打印输出相比，静态信息保持不变，而动态信息现在反映了选定的子集。有许多可能的选择标准，如下所示

d.select(timerange=('2011-08-11 13:10:00', '2011-08-11 13:15:00'), targets=[1, 2])
d.select(spw=0, subarray=0)
d.select(ants='ant1,ant2', pol='H', scans=(0,1,2), freqrange=(1700e6, 1800e6))

有关更多详细信息，请参阅DataSet.select的文档字符串（即在IPython中执行d.select?）。请注意，必须选择一个子阵列和一个频谱窗口。

一旦选择了数据集的一个子集，就可以访问数据集对象上的数据和时间戳

vis = d.vis[:]
timestamps = d.timestamps[:]

请注意[:]索引，因为vis和timestamps属性是特殊的LazyIndexer对象，只有在您使用索引时才会提供实际数据，以避免意外地将整个数组加载到内存中。

对于示例数据集和没有选择的情况，vis数组将具有(1054, 1024, 112)的形状。时间维度由d.timestamps标记，频率维度由d.channel_freqs标记，相关性乘积维度由d.corr_products标记。

数据集对象中的另一个关键概念是传感器。这些是任意数据的命名时间序列，可以是从数据集中加载的（实际传感器）或实时计算的（虚拟传感器）。两种变体都通过传感器缓存（可用为d.sensor）访问，并在第一次访问后进行缓存。数据集对象还提供了方便的属性，以暴露常用传感器，如下面的绘图示例所示

import matplotlib.pyplot as plt
plt.plot(d.az, d.el, 'o')
plt.xlabel('Azimuth (degrees)')
plt.ylabel('Elevation (degrees)')

其他有用的属性包括 ra、dec、lst、mjd、u、v、w、target_x 和 target_y。这些都是一维 NumPy 数组，其长度会根据活动选择动态变化。

与 katdal 的前辈（scape）一样，存在一个 DataSet.scans 生成器，允许您遍历数据集中的扫描。它返回每次迭代的扫描索引、扫描状态和目标对象，并更新数据集中的活动选择，仅包括当前扫描。也可以使用 DataSet.compscans 生成器遍历复合扫描，它在每次迭代时提供复合扫描索引、标签和第一个目标，方便使用。这两个迭代器也可以一起使用来遍历数据集结构。

for compscan, label, target in d.compscans():
    plt.figure()
    for scan, state, target in d.scans():
        if state in ('scan', 'track'):
            plt.plot(d.ra, d.dec, 'o')
    plt.xlabel('Right ascension (J2000 degrees)')
    plt.ylabel('Declination (J2000 degrees)')
    plt.title(target.name)

最后，数据集中的所有目标（或字段）都存储在位于 d.catalogue 的目录中，对于单个文件数据集（v3 或更早版本），原始 HDF5 文件仍然可以通过安装在其上的后门在 d.file 中访问。在 v4 数据集中，d.source 提供了对底层 telstate 的访问权限，用于元数据，以及用于数据的 chunk 存储。

0.23 (2024-06-28)

• 新的 mvf_download 脚本（同时推广 mvf_copy 并删除垃圾）(#380)

• 按标签选择目标(#377)

• 将 np.product 重命名为支持 numpy >= 2.0 并使单元测试更加健壮(#372)

0.22 (2023-11-28)

• 在 Numba 平均函数中恢复 np.bool 以防止 mvftoms 崩溃(#370)

• 在从 RDB 加载旧桶时将下划线替换为破折号(#370)

• 选择具有相同名称的多个目标，以避免 MS 中的扫描丢失(#369)

• 在 mvftoms 中支持即时（OTF）扫描(#366)

0.21 (2023-05-12)

• 修复对 numpy >= 1.24 的支持，并将单元测试从 nose 移动到 pytest(#361)

• 重新编写 S3ChunkStore 重试以实现更健壮的存档下载(#363)

• 从 MS 中删除充满零的 IMAGING_WEIGHT 列(#356)

• 使用 ES256 编码的 JWT 令牌改进测试，以及更健壮的 MinIO 健康检查(#360)

0.20.1 (2022-04-29)

• 修复由于 DaskLazyIndexer / ChunkStore 交互导致的损坏的 dataset.vis[n](#355)

0.20 (2022-04-14)

• 修复对 dask >= 2022.01.1 的支持，并将单元测试从 nose 移动到 pytest(#351)

• 在干扰后允许 mvftoms 继续使用部分 MS(#348)

• 新的 mvf_copy.py 脚本，可以用于仅提取自相关(#349)

• 在 S3ChunkStore 中适当处理 Ceph 403 错误(#352)

0.19 (2021-11-23)

• 在 mvftoms 中支持扫描和非 radec 目标，如行星(#333)

• 公开 MVF4 数据集的原始标志(#335)

• 公开 CBF F-engine 传感器：应用延迟、相位和增益(#338)

• 验证 S3 存储桶不为空，以检测存档到磁带的数据集(#344)

• 在 mvftoms 中填充 SIGMA_SPECTRUM 并重新执行 SIGMA 和 WEIGHT(#347)

• 有意义的 DataSet.name，同时添加单独的 DataSet.url(#337)

• 允许使用“~m0XX”取消选择天线(#340)

• 允许嵌套 DaskLazyIndexers(#336)

• 修复 macOS 和 Python 3.8+ 上的 mvftoms(#339)

0.18 (2021-04-20)

• 切换到 PyJWT 2 和 Python 3.6，清理 Python 2 稀遗物(#321 - #323)

• 允许在 katdal.open() 上预选通道和转储，以节省时间和内存(#324)

• 允许用户在 mvftoms 中选择字段、扫描和天线(#269)

• 支持 MVF3 中的 h5py 3.0 字符串处理(#331)

• 重构需求文件以删除递归依赖(#329)

0.17 (2021-01-27)

• 这是最后一个将支持 Python 3.5 的版本(#329)

• 将 PyJWT 版本固定为 1.x 以避免破坏 API 更改(#320)

• Van Vleck 校正！(仅针对自相关)

• 公开裁剪，即原始权重(#308)

• 改进DataSource和S3ChunkStore的一般单元测试（#319）

• 支持索引telstate键（杀死Python 2的1000次切割）（#304）

• 为Minio分离出单独的实用类（#310）

• 修复无效状态下的传感器事件过滤（#306）

0.16 (2020-08-28)

• 这是最后一个将支持Python 2的版本（python2维护分支）

• 新增“time_offset”传感器属性，调整任何传感器的时间戳（#307）

• 修复“wide”/“narrowN”仪器cbf_dump_period的计算（#301）

• 将katstore搜索窗口增加600秒以找到不频繁的更新（#302）

• 重构SensorData以成为无缓存的懒抽象接口（#292）

• 重构SensorCache以使用MutableMapping（#300）

• 修复MVFv3文件中rx_serial传感器使用和文件模式警告（#298, #299）

0.15 (2020-03-13)

• 改进S3块存储：检查令牌，改进超时和重试（#272 - #277）

• 重试截断读取和S3服务器过载导致的50x错误（#274）

• 如有可用，应用flux校准（#278, #279）

• 改进mvf_rechunk和mvf_read_benchmark脚本（#280, #281, #284）

• 修复按目标描述选择的问题（#271）

• 标记Python 2支持为已弃用（#282）

0.14 (2019-10-02)

• 通过应用自校准校正来创建L2产品（#253 - #256）

• 加速uvw计算（#252, #262）

• 在readthedocs.org上生成文档（#244, #245, #247, #250, #261）

• 清理mvftoms并修复SOURCE子表中的REST_FREQUENCY（#258）

• 支持katstore64 API（#265）

• 改进块存储：检测短读取，加快处理丢失数据（#259, #260）

• 使用katpoint 0.9和dask 1.2.1功能（#262, #243）

0.13 (2019-05-09)

• 直接从存档加载RDB文件（#233, #241）

• 从CAM katstore检索原始传感器数据（#234）

• 解决一个CBF-dump偏移问题（#238）

• 改进MS输出：修复RECEPTOR_ANGLE（#230），添加WEIGHT_SPECTRUM（#231）

• 对applycal（#224）、权重（#226）、S3读取（#229）进行各种优化

• 使用katsdptelstate 0.8和dask 1.1功能（#228, #233, #240）

0.12 (2019-02-12)

• 可选地通过应用校准校正来制作L1产品（#194 - #198）

• 让v4数据集中的默认参考天线为“array”天线（#202, #220）

• 使用katsdptelstate v0.7：通用编码，内存后端（#196, #201, #212）

• 为多转储块做准备（#213, #214, #216, #217, #219）

• 允许忽略L1标志（#209, #210）

• 处理已弃用的dask功能（#204, #215）

• 移除RADOS块存储（从现在起全部通过S3访问）

0.11 (2018-10-15)

• 通过python-future支持Python 3（终于！）

• 如有可用，加载L1标志（#164）

• 减少内存使用（#165）和加速（#155, #169, #170, #171, #182）

• S3块存储现在直接使用requests而不是通过botocore

• 让懒索引器使用过去oindex语义（#180）

• 修复连接数据集（#161）

• 修复IPython / Jupyter传感器缓存tab完成（#176）

0.10.1 (2018-05-18)

• 恢复NumPy 1.14支持（否则所有数据都会被标记）

0.10 (2018-05-17)

• 团结在MeerKAT可见性格式（MVF）周围

• MVF v4到MS的第一优化转换器：mvftoms

• 最新的v4修复（合成时间戳、自动检测、Ceph中的NPY文件）

• 标记并置零缺失块

• 现在需要katsdptelstate（已发布）、dask、h5py 2.3和Python 2.7

• 恢复S3单元测试和NumPy 1.11（在Ubuntu 16.04上的）支持

0.9.5 (2018-02-22)

• 为v4预期的新HDF5 v3.9文件格式做准备（影响obs_params）

• 修复最近的MeerKAT数据集中的接收器序列号

• 将dask支持添加到ChunkStore

• katdal.open()可以在v4 RDB文件上工作

0.9 (2018-01-16)

• 为未来的v4格式创建新的ChunkStore和telstate解析器

• 使用python-casacore（>=2.2.1）创建测量集而不是blank.ms

• 读取新样式噪声二极管传感器名称、序列号和L0流元数据

• 选择多个偏振（对交叉偏振很有用）

• 放宽“预期转载数量”检查以避免虚假警告

• 修复NumPy 1.14警告

0.8 (2017-08-08)

• 修复颠倒的 MeerKAT 图像

• 对 SensorData 进行重工作业，以加载增益解决方案并高效访问 telstate

• 改进传感器事件映射到转储的过程，尤其是对于长时间（8秒）的转储

• 修复 NumPy 1.13 警告和错误

• 支持 UHF 接收器

0.7.1 (2017-01-19)

• 修复 h5toms 中 MODEL_DATA / CORRECTED_DATA 的形状

• 在 h5toms 中生成校准解决方案表并改进错误信息

• 在较旧的 RTS 文件中自动检测接收器频段

0.7 (2016-12-14)

• 支持文件中的权重并改进 vis / weights / flags API

• 支持多个接收器并改进中心频率提取

• 通过按时间排序可见性加快 h5toms 的速度

• 修复最新 SDP（cam2telstate）的频段选择和纠错产品

• 在 h5toms 中允许显式 MS 名称

0.6 (2016-09-16)

• katdal 的初始发布