数据评估 Python SDK

安装

pip install timecho-ai

快速开始

import pandas as pd
from timecho_ai import TimechoAIClient

client = TimechoAIClient(api_key="your-api-key")

df = pd.DataFrame({
    "time": pd.date_range("2024-01-01", periods=100, freq="h"),
    "temperature": [20 + i * 0.1 for i in range(100)],
    "humidity":    [60 + i * 0.05 for i in range(100)],
})

result = client.evaluate(df)

print(result.overall_score)  # 综合分，如 85.3
print(result.scores)         # 每条序列的详细评分 DataFrame

evaluate() 方法

result = client.evaluate(
    data,
    dimensions=None,   # 省略则运行全部三个维度
    time_col=None,     # 省略则自动识别名为 "time" 的列
    params=None,       # 各维度的超参数，见下文
)

参数

参数	类型	必填	说明
data	DataFrame	是	时间序列数据，含时间列和一个或多个数值列
dimensions	List[str]	否	指定维度，如 ["integrity", "pearson"]，省略则运行全部
time_col	str	否	时间列名，自动识别 "time"（不区分大小写）
params	Dict	否	超参数，如 {"downtime": True}

返回值属性

属性	类型	说明
overall_score	float	综合质量评分（0–100），所有指标加权平均
scores	DataFrame	每条序列的详细分项评分
correlation_matrix	DataFrame | None	Pearson 相关系数矩阵（仅请求 pearson 维度时返回）

查询可用维度

dimensions = client.evaluate_dimensions_list()
print(dimensions)
# name              description              supported_params
# integrity         统一的时间戳完整性检查    [{"name": "downtime", ...}]
# forecastability   基于频域的可预测性度量    []
# pearson           皮尔逊相关系数            [{"name": "targets", ...}]

维度说明

完整性（integrity）

通过检测缺失点（间隔 ≥ 2× 中位数间隔）、冗余点（间隔 ≤ 0.5× 中位数间隔）和时效性异常（间隔缺口后的突发数据）来评估时间戳完整性。

子维度：

• Completeness（完整性） — 缺失数据点（间隔 ≥ 2× 中位数间隔）
• Consistency（一致性） — 冗余数据点（间隔 ≤ 0.5× 中位数间隔）
• Timeliness（时效性） — 延迟到达的数据（间隔缺口后出现的密集突发数据）

超参数：

参数	默认值	说明
downtime	True	将间隔 ≥ 9× 中位数的段排除在缺失统计之外（设备停机）

可预测性（forecastability）

通过傅里叶分解的归一化谱熵衡量序列的可预测程度。频谱越集中，得分越高；接近白噪声则得分趋近 0。

谱熵越低的序列越适合直接做预测。

皮尔逊相关性（pearson）

计算所有数值序列之间的两两皮尔逊相关系数，评估序列间的线性关系强度。至少需要 2 条序列，单序列返回 0 分。