Trend Analysis

Track how your health metrics change over time.

Overview

VitalClaw uses linear regression to detect directional trends across all metrics. Each metric is classified into one of four directions:

Direction	Criteria	Meaning
`improving`	>2% change, positive direction	Metric moving toward healthier values
`stable`	≤2% change	Metric holding steady
`declining`	>2% change, negative direction	Metric moving away from healthier values
`insufficient_data`	<3 data points	Not enough data to determine trend

Usage

// Analyze all metrics over 7 days
const trends = engine.getTrends("7d");

console.log(trends.overallDirection);  // "improving"
console.log(trends.period);             // "7d"

for (const t of trends.metrics) {
  console.log(
    t.metric,              // "steps"
    t.direction,           // "improving"
    t.changePercent,       // 12.3
    t.dataPoints.length    // 7
  );
}

// Analyze specific metrics over 30 days
const sleepTrends = engine.getTrends("30d", ["sleep_duration", "sleep_score"]);

Direction Logic

VitalClaw understands that "higher" is not always "better". For each metric, it knows the healthy direction:

Higher is Better	Lower is Better
steps, distance, active_minutes, floors_climbed, sleep_duration, sleep_score, vo2_max, heart_rate_variability, blood_oxygen	resting_heart_rate (within range), stress_level, blood_glucose (within range), body_fat

TrendAnalysis Schema

interface TrendAnalysis {
  period: "7d" | "14d" | "30d" | "90d";
  metrics: MetricTrend[];
  overallDirection: TrendDirection;
}

interface MetricTrend {
  metric: MetricType;
  direction: "improving" | "stable" | "declining" | "insufficient_data";
  changePercent: number;
  dataPoints: { date: string; value: number }[];
  period: string;
}