最新提交
历史记录
2 次提交2 次提交文件夹和文件
仓库文件导航
LingSante-Pulse面向生理时间序列的表征学习,涵盖波形编码和连续血糖监测(CGM)工作流。
LingSante-Pulse 为 ECG、EEG 和 PPG 等信号提供可复用的表征。其 CGM 分支支持每日血糖表征、纵向历史建模、公共数据预训练和下游评估。
功能特性
| 分支 | 输入 | 输出 | 工作流 |
|---|---|---|---|
| 波形 | 信号窗口、实际采样率和通道元数据 | 每个通道的 256 维 CLS / PatchMean 特征;可选的补丁序列 | 为下游任务提取预训练表征 |
| 连续血糖监测(CGM) | 每日血糖窗口、观测掩码、受试者 ID 和时间戳 | 每日 146 维表征以及参与计算的历史窗口数量 | 表征提取、公共数据预训练、分类、固定模型评估和候选选择评估 |
CGM 分支实现了可迁移证据重建(TER),融合每日表征、物理尺度、时间动态和跨日因果历史。训练与评估共用项目的安装、文档和版本控制体系。
每个分支均提供适合其输入的预处理:波形采用采样率和物理通道,CGM 则采用血糖单位、每日网格和受试者历史记录。入口程序提供默认设置和预训练权重加载功能。
安装
使用 Python 3.11 或 3.12。在仓库根目录运行:
python -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python -m pip install . --no-deps
根目录 requirements.txt 同时涵盖两个分支,并保留 CGM 评估所依赖的软件包版本。GPU 训练需要与加速器兼容的 PyTorch 构建版本。两个分支均支持 CPU 推理和合成示例。
预训练权重
| 分支 | 来源 | 内容 |
|---|---|---|
| 波形 | Hugging Face:inclusionAI/LingSante-Pulse-1.0 | 官方编码器、配置和固定通道资源 |
| CGM | src/lingsante_pulse/cgm/assets/checkpoints/ |
每日编码器、动态分支、纵向模型和物理尺度参数 |
波形编码器从 Hugging Face 下载权重,并默认使用本地缓存。也支持本地模型目录。CGM 部署权重已包含在仓库和安装包中。
快速开始
波形特征
加载波形编码器并提取特征:
import numpy as np
from lingsante_pulse import LingSantePulse
model = LingSantePulse.from_pretrained()
# Two synthetic single-channel ECG windows, each 10 seconds at 128 Hz.
signals = np.random.default_rng(42).normal(size=(2, 1, 1280)).astype(np.float32)
features = model.encode(
signals,
sample_rate=128,
channels=[{"modality": "ECG", "lead": "II"}],
)
print(features["cls"].shape) # torch.Size([2, 256])
print(features["patch_mean"].shape) # torch.Size([2, 256])
要加载本地模型目录,请将加载代码行替换为:
model = LingSantePulse.from_pretrained("models/pulse", local_files_only=True)
该目录必须包含 model.safetensors, config.json, channels.npz, 和 channels.json也可以将明确的 Hugging Face 仓库 ID 传递给 from_pretrained.
CGM 特征
仓库中包含 CGM 部署权重和一个合成示例:
python -m lingsante_pulse.cgm extract \ --input examples/cgm_synthetic.npz \ --output results/cgm_example_embeddings.npz
此命令默认使用打包的部署权重并在 CPU 上进行推理。其输出包含 embedding, history_days, 以及相应的窗口、受试者和时间戳元数据。现有输出不会被覆盖;再次运行示例时请选择新的输出路径。
Python 接口:
import numpy as np
from lingsante_pulse.cgm import extract
with np.load("examples/cgm_synthetic.npz", allow_pickle=False) as archive:
payload = dict(archive)
embedding, history_days = extract(
payload,
device="cpu",
)
print(embedding.shape) # (6, 146)
print(history_days.shape) # (6,)
输入和输出
波形
- 数组的形状可以是
[T],[C, T], 或[B, C, T]。对于单通道批次,请使用[B, 1, T]。也支持通道字典。 - 请指定实际的
sample_rate。波形采用固定的 128 Hz 预处理;输入通道必须在时间上对齐。 - 请提供
channels按输入顺序提供,可指定模态和可选导联,例如{"modality": "ECG", "lead": "II"}. - 名称不区分大小写,并忽略首尾空白。ECG 导联
II,ii,"2", 以及2均映射到导联 II。省略或留空导联时,将使用通用 ECG 标识。 - 可使用以下命令查看支持的标识:
model.channel_names和model.channel_descriptions。IMU 等不受支持的标识会引发错误。 - 可选的布尔掩码
observed和sample_present必须与输入形状一致。它们分别用于标识物理观测值和存储填充。
| 输出 | 形状 | 含义 |
|---|---|---|
cls |
[B, C*256] |
按输入顺序拼接的各通道 CLS 特征 |
patch_mean |
[B, C*256] |
各通道有效补丁的平均特征 |
channel_names |
C 个名称 | 规范通道标识 |
patch_tokens |
[B, P, C*256] |
随附返回的补丁特征 return_tokens=True |
patch_valid |
[B, P, C] |
可选的逐通道补丁有效性掩码 |
patch_times |
[P] |
可选的相对补丁起始时间(秒) |
各通道独立编码,并将其特征拼接在一起。对于波形,使用每个通道/窗口内观测样本的均值和标准差。数值通道采用零阶保持重采样和固定物理尺度:
| 数值通道 | 输入单位 | 中心值 | 尺度 |
|---|---|---|---|
spo2 |
百分比,例如 97 | 95 | 5 |
heart_rate, pulse_rate |
次/分钟 | 70 | 30 |
rr_primus, rr_solar |
次呼吸/分钟 | 20 | 20 |
bis_emg_power |
dB | 0 | 100 |
数值按以下方式转换: (value - center) / scale 并裁剪至 [-10, 10]。NaN/Inf 值视为未观测;零是有效样本。若窗口中没有观测样本,则会引发错误。
CGM
CGM 输入由按 5 分钟网格划分且互不重叠的 24 小时时间窗组成,每个时间窗包含 288 个点:
| 字段 | 形状 | 含义 |
|---|---|---|
glucose_mg_dl |
[N, 288] |
血糖值,单位为 mg/dL |
observed_mask |
[N, 288] |
原始物理观测值的布尔掩码;插值点仍视为未观测 |
window_id |
[N] |
唯一的时间窗标识符 |
subject_id |
[N] |
用于历史记录分组的匿名受试者标识符,并非数值模型特征 |
start_time |
[N] |
实际时间窗起始时间,保留当地时刻惯例 |
episode_index |
可选 [N] |
记录时段标识符,用于防止历史记录跨越不相关的记录时段 |
在同一次调用中包含同一受试者/记录时段的所有可用历史时间窗。模型根据时间戳构建最多七天的因果上下文。如果没有受支持的历史记录,则返回当天的表征。请保留数据集构建者提供的字段,例如 native_cadence_min 。
在构建时间窗之前,将 mmol/L 转换为 mg/dL。可包含可选字段以供单独评估;编码器不会使用这些字段。请参阅 label_* 字段可包含在内以供单独评估;编码器不会使用它们。请参阅 CGM 数据文档 ,了解完整的输入和预处理规则。
CGM 下游分类
分别提取训练受试者和新受试者的特征,同时保留每位受试者的可用历史记录。使用训练受试者及其标签拟合分类器:
python -m lingsante_pulse.cgm downstream fit \ --input results/train_embeddings.npz \ --label label_diabetes \ --model results/diabetes_classifier.joblib python -m lingsante_pulse.cgm downstream predict \ --input results/new_participants_embeddings.npz \ --model results/diabetes_classifier.joblib \ --output results/diabetes_predictions.npz
这些命令需要你的特征文件和训练标签。该示例使用 StandardScaler + LogisticRegression,两者都仅在训练受试者上进行拟合。请加载本地创建或从可信来源获取的分类器文件。预训练编码器生成的是表征,而非预训练的疾病预测结果。
CGM 公共数据预训练
该代码仓库包含数据准备和多阶段训练流程。请获取其中所述的公共数据集: DATA.md,然后构建预训练语料库:
python -m lingsante_pulse.cgm prepare-data \ --shanghai-root data/raw/shanghai \ --stanford-root data/raw/stanford \ --big-ideas-root data/raw/big_ideas_1.1.2 \ --colas-root data/raw/colas2019/S1 \ --output-dir data/processed/public_pretraining \ --shanghai-policy subject_disjoint --seed 43 python -m lingsante_pulse.cgm train \ --corpus data/processed/public_pretraining/glucofm_public_pretrain_subject_disjoint_v1.npz \ --output results/cgm_public_pretraining \ --device cuda:0
替换示例中的 data/raw/ 路径替换为你的数据集位置。训练流程依次运行每日编码器、动力学分支、跨日上下文阶段和最终记忆阶段,然后将可直接用于推理的资产导出到 results/cgm_public_pretraining/checkpoints/。公开方案在每个优化阶段使用随机种子 43,并运行 6,960 个步骤。需要兼容 CUDA 的加速器。
语料库必须排除表型标签,且训练受试者与验证受试者不得重叠。所提供的 CGM 权重还使用了私有的无标签 CGM 数据。这些命令复现的是基于公开数据的训练流程,而不是使用私有数据训练的原始权重。请参阅 CGM 代码导览图 ,了解模型和训练模块。
CGM 评估
公开评估涵盖 CGMacros、上海、斯坦福和 Hall 的 14 项任务。请按照 DATA.md 作为 data/processed/glucofm_public/COHORT/COHORT_glucofm_windows_v1.npz,其中 COHORT 为 cgmacros, shanghai_t2dm, stanford,或 hall.
固定模型评估
评估打包的部署权重:
python -m lingsante_pulse.cgm evaluate \ --data-root data/processed/glucofm_public \ --output results/cgm_fixed_model \ --device cpu
要评估你自己训练的模型,请添加 --checkpoint-dir ,使其指向导出的 checkpoints/ 目录。使用 --embeddings-root 来评估现有的按队列划分的特征文件。
可选的论文主表复现
论文主表在 24 个候选项中采用嵌套选择。此工作流程需要单独的候选项权重及其 manifest.json;默认包包含一个部署模型。
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 \ python -m lingsante_pulse.cgm evaluate-nested \ --data-root data/processed/glucofm_public \ --candidates-dir reproduction/candidates \ --output results/cgm_nested_evaluation \ --device cpu --workers 8
将 指向准备好的候选项目录。 --candidates-dir 该方案使用 10 次重复、5 个外层折和 3 个内层折。在每个外层训练人群中选定一个共享表征,然后再进行外层测试评估。来自同一生物学参与者的所有记录均保留在同一个折中。固定部署模型的结果与主表候选项选择结果分别报告。
代码仓库结构
.
├── README.md
├── README_zh.md
├── LICENSE
├── LEGAL.md
├── pyproject.toml
├── requirements.txt
├── src/lingsante_pulse/
│ ├── __init__.py
│ ├── waveform/
│ │ ├── api.py
│ │ ├── model.py
│ │ ├── preprocessing.py
│ │ ├── channels.py
│ │ └── hub.py
│ └── cgm/
│ ├── __main__.py
│ ├── models/
│ ├── data/
│ ├── inference/
│ ├── training/
│ ├── evaluation/
│ ├── downstream.py
│ ├── checkpoints.py
│ ├── baselines/
│ ├── diagnostics/
│ └── assets/
│ ├── checkpoints/
│ ├── configs/
│ └── benchmarks/
├── examples/
├── scripts/cgm/
├── tests/
│ ├── waveform/
│ └── cgm/
└── docs/cgm/
许可证与数据来源
项目自有代码和随附的模型权重采用 MIT 许可证。该代码仓库保留了 LEGAL.md 和 CGM 第三方声明。第三方数据集和模型资产必须依照其各自的许可证和访问条件获取;此处不对其进行再分发。本次发布不包含私有原始数据、表型标签和个人标识符。
LingSante-Pulse 支持表征学习和算法研究。针对特定任务的预测性能必须按照适当的评估方案在目标数据上进行评估。
AI 热点