WTTE-RNN

威布尔时间至事件循环神经网络

一种更优雅的机器学习框架，用于流失率和时间至事件预测。从服务器监控到地震预测、流失率预测等多样化的预测问题，都可以被建模为预测某个事件发生的时间。WTTE-RNN 既是一种算法，也是一种关于如何进行此类预测的理念。

• 博客文章
• 硕士论文
• 模型的快速可视化介绍：模型
• Jupyter 笔记本：基础、进阶
• Gianmario Spacagna 的 实现 用于故障前时间预测。
• 韩语 README

安装

Python

请参阅 Python 包的 README。

如果觉得过于复杂，也可以在 Jupyter 笔记本 中找到基本实现。

思想与基础

你有一组由多个事件时间序列组成的数据，并希望利用历史数据来预测下一个事件发生的时间（TTE）。如果最后一个事件尚未发生，那么我们只能观测到 TTE 的下限作为训练依据。这就产生了所谓的 删失数据（红色部分）：

与其直接预测 TTE，不如让机器学习模型输出 分布的参数。这些参数可以是任意形式，但我们倾向于使用 威布尔分布，因为它非常强大（参见文章）。用于训练的算法可以是任何基于梯度的方法，而我们特别喜欢 RNN，因为它们也非常强大（参见文章）。

下一步是使用一种能够处理删失数据的特殊对数损失函数来训练所选算法。其背后的直觉是：对于未删失的事件，我们希望模型为其分配较高的概率；而对于已删失的数据，则应分配较低的概率：

最终得到的是每一步关于 TTE 分布 的清晰预测（这里以单个事件为例）：

一个有趣的副产品是，预测出的参数实际上是一个二维嵌入，可用于可视化和分组预测结果，分别表示“多久会发生”（alpha）和“有多确定”（beta）。以下是按时间轴堆叠的 alpha（左）和 beta（右）预测结果：

警告

有许多数学理论证明了在特定情况下使用这种损失函数的合理性：

因此，对于删失数据，该损失函数只会奖励那些将分布“推高”到超过删失点的行为。要使这一方法奏效，删失机制必须独立于你的特征数据。如果特征中包含了有关删失点的信息，算法可能会通过根据删失概率而非实际 TTE 来预测较远的时间，从而产生一种过拟合或伪相关现象。全局特征如果没有得到妥善处理，就可能产生这种影响。

状态与路线图

该项目仍在开发中。我们的目标是创建一个可复用且易于部署的模型框架。WTTE 是核心算法，但整个项目旨在提供更多价值——它不仅是一种算法，更是一种视觉化哲学和关于如何让流失率监测与报告变得美观易懂的观点。

欢迎 Pull 请求、建议、评论和贡献。

仓库内容

• 数据转换
  • 数据管道转换（将符合预期格式的 pandas.DataFrame 转换为 numpy）
  • 时间至事件及删失标志的计算
• 威布尔函数（CDF、PDF、分位数、均值等）
• 目标函数：
  • TensorFlow
  • Keras（TensorFlow + Theano）
• Keras 辅助工具
  • 威布尔输出层
  • 损失函数
  • 回调函数
• ~~ 大量示例实现 ~~
  • 基础笔记本 将保留在这里，但为了节省空间并鼓励可视化，请访问 示例仓库，或在此基础上 fork 您自己的笔记本。

许可证

• MIT 许可证

引用

@MastersThesis{martinsson:Thesis:2016,
    author = {Egil Martinsson},
    title  = {{WTTE-RNN : Weibull Time To Event Recurrent Neural Network}},
    school = {查尔姆斯理工大学},
    year   = {2016},
}

贡献

欢迎任何形式的贡献、PR 或评论！如有疑问，请提交 issue；也欢迎随时联系 egil.martinsson[at]gmail.com。

贡献者（按提交顺序）

• Egil Martinsson
• Dayne Batten（完成了首个 Keras 实现）
• Clay Kim
• Jannik Hoffjann
• Daniel Klevebring
• Jeongkyu Shin
• Joongi Kim
• Jonghyun Park

WTTE-RNN 快速上手指南

WTTE-RNN (Weibull Time To Event Recurrent Neural Network) 是一个用于预测“事件发生时间”（Time-To-Event, TTE）的机器学习框架，特别适用于客户流失预测、服务器监控及故障预警等场景。它通过让模型输出韦伯分布（Weibull Distribution）的参数，优雅地处理了删失数据（Censored Data，即尚未观察到事件发生的数据）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 推荐 Python 3.6+
• 核心依赖:
  • TensorFlow (后端引擎)
  • Keras (模型构建接口)
  • NumPy, Pandas, Matplotlib (数据处理与可视化)
• 知识储备: 了解基本的循环神经网络 (RNN/LSTM) 概念及生存分析基础更佳。

提示: 建议使用虚拟环境（如 venv 或 conda）隔离依赖。

安装步骤

方式一：安装 Python 包（推荐）

该项目提供了独立的 Python 包。您可以直接通过 pip 安装：

pip install wtte-rnn

如果下载速度较慢，可以使用国内镜像源加速：

pip install wtte-rnn -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：源码安装（获取最新特性）

如果您需要最新的开发版本或想贡献代码，可以克隆仓库并安装：

git clone https://github.com/ragulpr/wtte-rnn.git
cd wtte-rnn/python
pip install -e .

方式三：零依赖快速体验（Jupyter Notebook）

如果您不想配置完整环境，只想快速理解原理，可以直接运行项目提供的独立 Notebook 示例（需本地安装 Jupyter 和 Keras/TensorFlow）：

# 克隆示例仓库
git clone https://github.com/ragulpr/wtte-rnn-examples.git
# 启动 Jupyter
jupyter notebook wtte-rnn-examples/examples/keras/standalone_simple_example.ipynb

基本使用

WTTE-RNN 的核心思想是将传统的回归问题转化为预测韦伯分布的两个参数：Alpha (α) 决定事件发生的快慢，Beta (β) 决定预测的确定性。

以下是一个基于 Keras 的最简使用流程：

1. 数据准备

您需要将时间序列数据转换为模型可接受的格式，关键是要计算出每个样本的 time_to_event (TTE) 和 is_censored (是否删失) 标签。

import numpy as np
import pandas as pd

# 假设您有一个包含时间步长和事件标记的 DataFrame
# X: 输入特征 (samples, time_steps, features)
# y_tte: 距离下一个事件的时间
# y_event: 事件是否发生 (1=发生，0=未发生/删失)

# 示例：构造简单的虚拟数据
n_samples = 1000
time_steps = 20
features = 5

X = np.random.rand(n_samples, time_steps, features)
# 模拟 TTE 和 删失标记 (实际使用中需根据业务逻辑计算)
y_tte = np.random.exponential(scale=5.0, size=(n_samples,))
y_event = np.random.binomial(1, 0.7, size=(n_samples,)) 

2. 构建模型

使用 wtte-rnn 提供的自定义输出层和损失函数构建 Keras 模型。

from keras.models import Sequential
from keras.layers import LSTM, Dense
from wtte.rnn import WeibullOutputLayer
from wtte.loss import weibull_loglikelihood_loss

# 构建 RNN 模型
model = Sequential()
model.add(LSTM(32, input_shape=(time_steps, features), return_sequences=True))
model.add(LSTM(16))

# 添加专用的韦伯分布输出层 (输出 alpha 和 beta)
model.add(WeibullOutputLayer())

# 编译模型，使用专用的对数似然损失函数以处理删失数据
model.compile(optimizer='adam', loss=weibull_loglikelihood_loss)

model.summary()

3. 训练模型

直接使用准备好的数据进行训练。损失函数会自动处理删失样本，最大化观测事件的概率或最小化未观测事件区域的概率密度。

# 注意：y 需要组合成模型期望的格式 [y_tte, y_event]
y_train = np.stack([y_tte, y_event], axis=-1)

history = model.fit(
    X, 
    y_train, 
    batch_size=32, 
    epochs=10, 
    validation_split=0.2,
    verbose=1
)

4. 预测与解读

模型预测出的结果是韦伯分布的参数。您可以利用这些参数计算任意时间点的风险率、生存概率或期望剩余时间。

from wtte import utils as wtte_utils

# 获取预测参数 (alpha, beta)
predictions = model.predict(X)
alpha_pred = predictions[:, 0]
beta_pred = predictions[:, 1]

# 计算期望发生时间 (Mean Time To Event)
expected_tte = wtte_utils.weibull_mean(alpha_pred, beta_pred)

print(f"预测的平均事件发生时间：{expected_tte[:5]}")

通过以上步骤，您即可利用 WTTE-RNN 构建一个能够处理复杂时间序列和删失数据的强大预测模型。更多高级用法（如可视化 Alpha/Beta 嵌入、自定义回调等）请参考官方示例仓库。