Data Evaluation Python SDK

Install

pip install timecho-ai

Quick start

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)  # Overall score, e.g. 85.3
print(result.scores)         # Per-series detailed scores DataFrame

evaluate() method

result = client.evaluate(
    data,
    dimensions=None,   # omit to run all three dimensions
    time_col=None,     # omit to auto-detect a column named "time"
    params=None,       # per-dimension hyperparameters
)

Parameters

Parameter	Type	Required	Description
data	DataFrame	Yes	Time-series data with a time column and one or more numeric columns
dimensions	List[str]	No	Dimensions to run, e.g. ["integrity", "pearson"]; omit to run all
time_col	str	No	Time column name; defaults to auto-detecting a column named "time" (case-insensitive)
params	Dict	No	Hyperparameters, e.g. {"downtime": True}

Return value attributes

Attribute	Type	Description
overall_score	float	Overall quality score (0–100), weighted across indicators
scores	DataFrame	Per-series detailed scores
correlation_matrix	DataFrame | None	Pearson correlation matrix (only returned when pearson dimension is requested)

List available dimensions

dimensions = client.evaluate_dimensions_list()
print(dimensions)
# name              description                        supported_params
# integrity         Unified timestamp integrity check    [{"name": "downtime", ...}]
# forecastability   Frequency-domain forecastability     []
# pearson           Pearson correlation                  [{"name": "targets", ...}]

Dimension details

Integrity

Evaluates timestamp integrity by detecting missing points (interval ≥ 2× median), redundant points (interval ≤ 0.5× median), and timeliness anomalies (bursts after gaps).

Sub-dimensions:

• Completeness — Missing points (interval ≥ 2× median interval)
• Consistency — Redundant points (interval ≤ 0.5× median interval)
• Timeliness — Late-arriving points (bursts after a gap)

Hyperparameters:

Parameter	Default	Description
downtime	True	Exclude intervals ≥ 9× median (device downtime) from missing statistics

Forecastability

Measures forecastability via normalized spectral entropy from Fourier decomposition. More concentrated spectra yield higher scores; near-white-noise series score close to 0.

Series with lower spectral entropy are better candidates for direct forecasting.

Pearson correlation

Computes pairwise Pearson correlation coefficients among all numeric series to assess linear relationship strength. Requires at least 2 series; returns 0 for a single series.