options-data

从 Deribit 历史快照接口增量下载期权数据到 Parquet，或将本地 Parquet 导出为 CSV。

安装依赖

python -m pip install -r requirements.txt

下载数据

python options_data\cli.py download --currency BTC --interval 1h --start-time 2026-06-01 --end-time 2026-06-30

--start-time 和 --end-time 支持 Unix timestamp 或 UTC 日期 YYYY-MM-DD。数据默认写入 data\{currency}_{interval}.parquet；可通过 --data-dir、--max-points-per-request 和 --timeout 调整保存目录、单次请求跨度及超时时间。

清洗异常快照

python options_data\cli.py clean-data BTC_1h.parquet

完整参数示例：

python options_data\cli.py clean-data BTC_1h.parquet --data-dir data --drop-threshold 0.30 --max-lookback-minutes 10 --timeout 30 --interval 1h

参数	是否必填 / 默认值	说明
filename	必填	--data-dir 目录下的源 Parquet 文件名，例如 BTC_1h.parquet。源文件不会被修改。
--data-dir	可选，默认 data	源文件和清洗结果所在目录。
--drop-threshold	可选，默认 0.30	strike 数下降阈值，必须大于 0 且小于 1。例如 0.30 表示当前数量比相邻正常基准下降至少 30% 时判为低值异常。
--max-lookback-minutes	可选，默认 10	从异常时间开始向前回溯的最大分钟数，必须为正整数。该值也会写入输出文件的 lookback_Nm 后缀。
--timeout	可选，默认 30	单次原始 API 请求的超时时间，单位为秒，必须为正数。
--interval	可选	源 Parquet 的快照间隔，可选值：1m、5m、15m、30m、1h、4h、1d。省略时从文件名末尾推导，例如 BTC_1h.parquet 推导为 1h；无法推导时必须显式指定。
-h, --help	可选	显示 clean-data 命令帮助并退出。

命令按 (date, expiration_date) 统计有效 strike 数。有效 strike 必须大于 0、为有限数值，且 claim_type 为 call 或 put。默认在当前数量满足以下公式时判为低值异常：

current <= min(previous, next) × (1 - 0.30)

前后快照必须与目标时间恰好相隔一个源数据 interval。如果同一到期日前后都有数据、目标时间整组缺失， 也会判为异常。--drop-threshold 可调整默认的 30% 下降阈值；--interval 可覆盖从 BTC_1h.parquet 文件名推导出的 1h。

清洗时使用原始 API 的 1m 数据，从异常时间向前最多搜索 10 分钟，可通过 --max-lookback-minutes 调整。找到正常替代组后，替代行保留 API 来源分钟的 date，并增加：

• anomaly_time：原异常时间的 Unix 秒；正常行为空。
• is_anomaly：替代行或未修复低值行写 Y，正常行写 N。

API 请求失败会按 1 秒、2 秒间隔重试两次。仍失败或未找到替代时，低值异常保留原数据并标记； 完全缺失组继续保持缺失，控制台会汇总未修复项。结果原子写入 data\BTC_1h_cleaned_lookback_10m.parquet，不会修改 data\BTC_1h.parquet；已有同名清洗文件会在新文件完整生成后覆盖。lookback_10m 后缀表示本次清洗向前回溯 10 分钟；使用其他 --max-lookback-minutes 值时，文件名中的分钟数会同步变化。

导出 CSV

python options_data\cli.py export-csv BTC_1h.parquet

该命令读取 data\BTC_1h.parquet 并生成 data\BTC_1h.csv，不会修改源 Parquet 文件。 使用 --data-dir 可指定其他目录。

如需只导出指定时间段的数据，可同时传入 --start-time 和 --end-time：

python options_data\cli.py export-csv BTC_1h.parquet --start-time "2026-06-01 02:05:01" --end-time "2026-06-01 11:15:00"

时间按 UTC 解析，支持 Unix timestamp、YYYY-MM-DD 和 YYYY-MM-DD HH:MM:SS 格式。 筛选结果包含开始和结束时刻。上述命令生成 data\BTC_1h_20260601_020501-20260601_111500.csv，以时间段后缀区分不同的导出文件。 --start-time 和 --end-time 必须同时提供。

计算到期日指标

安装依赖后，可为指定到期日预计算 Strikes、Calls 和 Puts 数量时间序列：

python options_data\cli.py compute-metrics BTC_1h.parquet --expiration 2026-06-26

--expiration 支持 UTC 日期 YYYY-MM-DD 或精确的 Unix timestamp。统计口径如下：

• 有效记录必须同时满足 strike > 0、strike 为有限数值且 claim_type 严格为 call 或 put；其余记录作为异常值忽略。
• Strikes：每个快照时刻、有效记录中的唯一 strike 数。
• Calls：每个快照时刻、有效 Call 记录中的唯一 strike 数。
• Puts：每个快照时刻、有效 Put 记录中的唯一 strike 数。

计算由 DuckDB 直接在 Parquet 上执行，只扫描所需列并按到期日过滤，不需要启动或维护数据库服务。 结果使用临时文件写完后再原子替换，默认保存为 data\BTC_1h_metrics\20260626.parquet。重复运行会全量重算该到期日，但不会修改源数据。 使用 --metrics-dir 可指定其他指标目录。

交互式分析面板

python options_data\cli.py dashboard

命令默认在 127.0.0.1:8050 启动本地服务并打开浏览器。 未提供文件名时默认打开 data\BTC_1h.parquet；如果默认文件不存在，则打开 --data-dir 第一层按名称排序后的第一个 Parquet 文件。也可以继续在命令行指定初始文件：

python options_data\cli.py dashboard ETH_1h.parquet

“到期日指标”和“原始数据”页面各自提供独立的“数据文件”下拉框，可分别选择 --data-dir 第一层的不同 Parquet 文件；指标缓存子目录不会被列入。

页面支持：

• 单选到期日（页面使用 Deribit 格式显示，例如 2JUN26），并在右侧勾选需要展示的指标。
• 点击“计算 / 刷新”直接从原始 Parquet 动态计算；该操作只展示结果，不写回指标缓存。
• 缩放、拖动时间轴，使用范围滑块和 1D、7D、1M、All 快捷范围；快捷按钮与指标图例分行展示。
• 使用左侧导航列表切换“到期日指标”和“原始数据”页面，后续可继续增加其它页面；原始数据查询不受指标图表到期日影响。
• 原始数据默认查询 UTC 时间范围内的所有到期日和 Claim Type，可按到期日、claim_type 和精确 strike 独立筛选。
• 原始数据默认按 date ASC, strike ASC, claim_type ASC 正序展示，并采用服务端分页，不会一次加载全部数据。
• 原始 date 右侧显示对应的 Date (UTC+8)，格式为 YYYY-MM-DD HH:MM。
• 对原始数据列进行排序。

可用 --host、--port 和 --metrics-dir 调整服务与指标目录；如果不希望自动打开浏览器， 增加 --no-open-browser。