cedarkit-notebook

cedarkit-notebook 是 cedarkit 工具套件的示例 Jupyter 笔记本集合与在线指南，涵盖数据加载、处理、可视化，以及 cedar-graph 预定义绘图示例。

本仓库使用 Jupyter Book v2（基于 MyST Markdown）构建为静态网站。

内容概览

在线指南包含以下章节：

• 快速开始：环境安装、cedarkit 入门、数据加载入门、cedar-graph 入门
• 基本用法：cedarkit-plots 基础绘图（等值线 contour、填充等值线 contourf、风羽 barb、组合图 combine）
• 数据指南：
  • 使用 reki 加载本地数据与 CMADAAS 挂载目录中的业务系统数据
  • GRIB2 格式说明（参数、层次、GRIB key）
• 绘图指南：
  • 数据源：本地文件、cfgrib、CMA 气象数据接口（CMADaaS）
  • 区域底图：东亚、中国区域、北极、欧亚、全球等
  • 地图包配置：默认地图包、CEMC 地图包
• 绘图示例：使用 cedar-graph 绘制常规量、诊断量、降水量等预定义图形

注意：部分示例依赖 CMADAAS 挂载目录中的业务系统数据。运行前请使用 CMADAAS 提供的挂载工具（例如 music-dir）将远程数据目录挂载到本地，并确保 storage_base 指向正确的挂载点（例如 /CMADAAS）。

项目结构

.
├── cedarkit_notebook/      # Python 包：配置发现、本地数据管理、本地预览服务器、CLI
│   ├── cli/
│   │   └── build_doc.py    # cedarkit-notebook 命令实现
│   ├── config.py           # pyproject.toml 配置读取
│   ├── data.py             # 本地数据管理（下载/查询）
│   └── server.py           # 本地 HTTP 预览服务器
├── data/                   # 本地数据目录（作为 reki storage_base，内容被 git 忽略）
├── docs/                   # 指南源文件（MyST Markdown + Jupyter Notebook）
│   ├── myst.yml            # Jupyter Book v2 / MyST 站点配置
│   ├── intro.md            # 首页
│   ├── started/            # 快速开始
│   ├── plots/              # 基本用法、绘图指南、绘图示例
│   └── data/               # 数据指南
├── tool/
│   └── run_server.py       # 本地预览服务器脚本入口
├── pyproject.toml
├── LICENSE
└── README.md

安装

环境要求

• Python >= 3.11
• 访问 CMADAAS 数据需要先将远程目录挂载到本地文件系统（详见下方 CMADAAS 数据挂载）

使用 uv（推荐）

uv sync

或创建虚拟环境并安装：

uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

使用 pip

python -m venv .venv
source .venv/bin/activate
pip install -e .

CMADAAS 数据挂载

本项目的部分示例使用 CMADAAS（天擎大数据云平台）上的业务系统数据。读取这些数据前，需要先用 CMADAAS 提供的挂载工具将远程数据目录映射到本地文件系统。常见方式包括：

• music-dir 等 CMADAAS 挂载工具：按平台提供的说明，将数据目录挂载到本地挂载点（如 /CMADAAS）。
• 在 Windows 环境中，挂载点可能显示为盘符（如 M:），使用时将 storage_base 设为对应路径即可。

示例中使用 reki.data_finder.find_local_file 查找文件时，通过 data_class="cmadaas" 和 storage_base="/CMADAAS" 指定数据来源与挂载目录：

from reki.data_finder import find_local_file

file_path = find_local_file(
    "cma_gfs_gmf/grib2/orig",
    start_time=start_time,
    forecast_time=forecast_time,
    data_class="cmadaas",
    storage_base="/CMADAAS",
)

如果挂载点不在 /CMADAAS，请将 storage_base 替换为实际路径。

本地数据

绘图与数据格式示例（docs/plots/、docs/data/format/）默认使用拷贝到本地目录 data/ 的数据， 不再直接访问 CMADAAS 挂载点。下载时保留数据文件相对 storage_base 的 路径结构，因此 data/ 目录可直接作为 reki 的 storage_base 使用。

在挂载了 CMADAAS 的环境中执行一次下载（手动操作）：

# 下载 CMA-MESO-3KM 数据（绘图示例使用，24h/12h/0h 三个时效共约 3.3 GiB）
uv run cedarkit-notebook data download cma-meso-3km

# 下载 CMA-GFS 数据（基本用法与 GRIB2 格式示例使用，24h 时效约 1.4 GiB）
uv run cedarkit-notebook data download cma-gfs

# 指定起报时次与预报时效
uv run cedarkit-notebook data download cma-meso-3km --start-time 2026072500 --forecast-time 24h

# 查看已下载的数据
uv run cedarkit-notebook data list

降水类图形需要用两个时次的累计量相减（如 apcp(24h) - apcp(0h)）， 因此除主时效 24h 外还会下载附加时效（默认为 12h 与 0h，可用 --extra-forecast-time 覆盖）。

每个系统的数据信息（来源、起报时次、文件列表）记录在 data/metadata/<system>.yaml 中。Notebook 通过 cedarkit_notebook.data 获取本地数据配置：

from cedarkit_notebook.data import get_data_root, get_dataset_query

STORAGE_BASE = str(get_data_root())            # 本地数据根目录
query = get_dataset_query("cma-meso-3km")      # 已下载数据的起报时次与预报时效

数据根目录默认为项目根下的 data/，可用环境变量 CEDARKIT_NOTEBOOK_DATA_ROOT 覆盖。除 README.md 外，data/ 目录中的内容均被 git 忽略。

构建文档

本项目提供 cedarkit-notebook CLI 工具来管理文档的构建与预览。

# 构建文档（默认会执行 Notebook）
uv run cedarkit-notebook build

# 构建前清理输出目录
uv run cedarkit-notebook build --clean

# 强制重新执行所有 Notebook（清除执行缓存）
uv run cedarkit-notebook build --all

# 不执行 Notebook，仅使用已有输出构建
uv run cedarkit-notebook build --no-execute

构建完成后，生成的静态网站位于 docs/_build/html 目录。 每次构建后会自动清理 jupyter_book 执行 Notebook 时遗留的 后台 jupyter_server 及内核（ipykernel_launcher）进程， 避免构建积累孤儿进程。

也可以直接使用 jupyter-book：

cd docs
jupyter-book build --html --execute

本地预览

构建完成后，启动本地 HTTP 服务器预览：

uv run cedarkit-notebook serve

可选参数：

uv run cedarkit-notebook serve --host 127.0.0.1 --port 8080
uv run cedarkit-notebook serve --dir docs/_build/html

或使用脚本入口：

python tool/run_server.py docs/_build/html

默认在可用网卡地址上绑定随机端口，命令行会输出类似如下 URL：

Preview server started, visit: http://localhost:46925
LAN access:         http://10.40.150.29:46925

使用浏览器打开该 URL 即可查看生成的文档网站。

实时开发服务器

在编辑文档时，可以启动 Jupyter Book v2 内置的实时预览服务器：

uv run cedarkit-notebook start

CLI 命令参考

uv run cedarkit-notebook --help

可用子命令：

子命令	说明
build	构建文档
start	启动 Jupyter Book v2 实时预览服务器
serve	启动本地 HTTP 服务器预览已构建的 HTML
clean	删除构建目录 docs/_build
deploy	使用 rsync 将 docs/_build/html 部署到目标目录
data download	从 CMADAAS 下载数据到本地数据目录
data list	查看本地已下载的数据

部署

将构建好的 HTML 站点部署到目标目录：

uv run cedarkit-notebook deploy /path/to/target

使用 --dry-run 可查看 rsync 将要执行的操作而不实际复制文件：

uv run cedarkit-notebook deploy /path/to/target --dry-run

许可证

Copyright © 2024-2026, developers at cemc-oper.

cedarkit-notebook is licensed under Apache License, Version 2.0.