tsb — Energy Anomaly Monitoring

Skills you'll use: merge, derived intensity metrics, rolling baselines, filters, nlargestDataFrame, groupby().agg(), and pivot-table alert summaries.

1 · Enrich smart-meter readings

Join telemetry with building metadata and normalize energy use by floor area and occupancy.

TypeScript

import { DataFrame, merge } from "tsb";

const readings = DataFrame.fromRecords([
  { hour: "08:00", building_id: "B01", meter: "main", kwh: 72, outdoor_c: 19, occupancy: 118 },
  { hour: "08:00", building_id: "B02", meter: "main", kwh: 54, outdoor_c: 18, occupancy: 76 },
  { hour: "08:00", building_id: "B03", meter: "main", kwh: 91, outdoor_c: 22, occupancy: 140 },
  { hour: "09:00", building_id: "B01", meter: "main", kwh: 78, outdoor_c: 21, occupancy: 132 },
  { hour: "09:00", building_id: "B02", meter: "main", kwh: 58, outdoor_c: 20, occupancy: 82 },
  { hour: "09:00", building_id: "B03", meter: "main", kwh: 116, outdoor_c: 24, occupancy: 148 },
  { hour: "10:00", building_id: "B01", meter: "main", kwh: 84, outdoor_c: 22, occupancy: 138 },
  { hour: "10:00", building_id: "B02", meter: "main", kwh: 61, outdoor_c: 22, occupancy: 89 },
  { hour: "10:00", building_id: "B03", meter: "main", kwh: 143, outdoor_c: 26, occupancy: 151 },
]);
const buildings = DataFrame.fromRecords([
  { building_id: "B01", campus: "North", sqft: 42000, system: "mixed-use" },
  { building_id: "B02", campus: "North", sqft: 28000, system: "office" },
  { building_id: "B03", campus: "South", sqft: 51000, system: "lab" },
]);

const enriched = merge(readings, buildings, { on: "building_id", how: "left" }).assign({
  kwh_per_ksqft: (df) => df.col("kwh").div(df.col("sqft")).mul(1000),
  occupant_kwh: (df) => df.col("kwh").div(df.col("occupancy")),
  weather_adjusted_kwh: (df) => df.col("kwh").sub(df.col("outdoor_c").sub(18).mul(1.5)),
});
console.log(enriched.select(["hour", "building_id", "campus", "kwh", "kwh_per_ksqft", "occupant_kwh", "weather_adjusted_kwh"]).toString());

const campusSummary = enriched
  .groupby("campus")
  .agg({ kwh: "sum", kwh_per_ksqft: "mean", occupant_kwh: "mean" }, false)
  .sortValues("kwh", false);
console.log("\nCampus intensity summary:");
console.log(campusSummary.toString());

import pandas as pd

readings = pd.DataFrame([
    {"hour": "08:00", "building_id": "B01", "meter": "main", "kwh": 72, "outdoor_c": 19, "occupancy": 118},
    {"hour": "08:00", "building_id": "B02", "meter": "main", "kwh": 54, "outdoor_c": 18, "occupancy": 76},
    {"hour": "08:00", "building_id": "B03", "meter": "main", "kwh": 91, "outdoor_c": 22, "occupancy": 140},
    {"hour": "09:00", "building_id": "B01", "meter": "main", "kwh": 78, "outdoor_c": 21, "occupancy": 132},
    {"hour": "09:00", "building_id": "B02", "meter": "main", "kwh": 58, "outdoor_c": 20, "occupancy": 82},
    {"hour": "09:00", "building_id": "B03", "meter": "main", "kwh": 116, "outdoor_c": 24, "occupancy": 148},
    {"hour": "10:00", "building_id": "B01", "meter": "main", "kwh": 84, "outdoor_c": 22, "occupancy": 138},
    {"hour": "10:00", "building_id": "B02", "meter": "main", "kwh": 61, "outdoor_c": 22, "occupancy": 89},
    {"hour": "10:00", "building_id": "B03", "meter": "main", "kwh": 143, "outdoor_c": 26, "occupancy": 151},
])
buildings = pd.DataFrame([
    {"building_id": "B01", "campus": "North", "sqft": 42000, "system": "mixed-use"},
    {"building_id": "B02", "campus": "North", "sqft": 28000, "system": "office"},
    {"building_id": "B03", "campus": "South", "sqft": 51000, "system": "lab"},
])
enriched = readings.merge(buildings, on="building_id", how="left")
enriched["kwh_per_ksqft"] = enriched["kwh"] / enriched["sqft"] * 1000
enriched["occupant_kwh"] = enriched["kwh"] / enriched["occupancy"]
enriched["weather_adjusted_kwh"] = enriched["kwh"] - (enriched["outdoor_c"] - 18) * 1.5
print(enriched[["hour", "building_id", "campus", "kwh", "kwh_per_ksqft", "occupant_kwh", "weather_adjusted_kwh"]])
print(enriched.groupby("campus", as_index=False).agg({"kwh": "sum", "kwh_per_ksqft": "mean", "occupant_kwh": "mean"}).sort_values("kwh", ascending=False))

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

2 · Flag spikes against a rolling baseline

Use recent same-building history as a simple expected-consumption baseline.

TypeScript

import { DataFrame, nlargestDataFrame, pivotTableFull } from "tsb";

const rows = [
  { hour: "08:00", building_id: "B01", kwh: 72 },
  { hour: "08:00", building_id: "B02", kwh: 54 },
  { hour: "08:00", building_id: "B03", kwh: 91 },
  { hour: "09:00", building_id: "B01", kwh: 78 },
  { hour: "09:00", building_id: "B02", kwh: 58 },
  { hour: "09:00", building_id: "B03", kwh: 116 },
  { hour: "10:00", building_id: "B01", kwh: 84 },
  { hour: "10:00", building_id: "B02", kwh: 61 },
  { hour: "10:00", building_id: "B03", kwh: 143 },
  { hour: "11:00", building_id: "B01", kwh: 88 },
  { hour: "11:00", building_id: "B02", kwh: 63 },
  { hour: "11:00", building_id: "B03", kwh: 181 },
];
function round1(value: number): number {
  return Math.round(value * 10) / 10;
}

console.log(flagged.toString());

const alerts = flagged.filter(flagged.col("anomaly_pct").ge(15));
console.log("\nAlert queue:");
console.log(nlargestDataFrame(alerts, 5, { columns: "anomaly_pct" }).select(["hour", "building_id", "kwh", "baseline_kwh", "anomaly_pct", "severity"]).toString());

const heatmap = pivotTableFull(flagged, {
  index: "building_id",
  columns: "severity",
  values: "alert_flag",
  aggfunc: "sum",
  fill_value: 0,
  margins: true,
});
console.log("\nAlert counts by building:");
console.log(heatmap.toString());

import numpy as np
import pandas as pd

rows = pd.DataFrame([
    {"hour": "08:00", "building_id": "B01", "kwh": 72},
    {"hour": "08:00", "building_id": "B02", "kwh": 54},
    {"hour": "08:00", "building_id": "B03", "kwh": 91},
    {"hour": "09:00", "building_id": "B01", "kwh": 78},
    {"hour": "09:00", "building_id": "B02", "kwh": 58},
    {"hour": "09:00", "building_id": "B03", "kwh": 116},
    {"hour": "10:00", "building_id": "B01", "kwh": 84},
    {"hour": "10:00", "building_id": "B02", "kwh": 61},
    {"hour": "10:00", "building_id": "B03", "kwh": 143},
    {"hour": "11:00", "building_id": "B01", "kwh": 88},
    {"hour": "11:00", "building_id": "B02", "kwh": 63},
    {"hour": "11:00", "building_id": "B03", "kwh": 181},
])
rows["baseline_kwh"] = (
    rows.groupby("building_id")["kwh"]
    .transform(lambda s: s.shift(1).rolling(3, min_periods=1).mean())
    .fillna(rows["kwh"])
    .round(1)
)
rows["anomaly_pct"] = ((rows["kwh"] - rows["baseline_kwh"]) / rows["baseline_kwh"] * 100).round(1)
rows["severity"] = np.select(
    [rows["anomaly_pct"] >= 25, rows["anomaly_pct"] >= 15],
    ["critical", "watch"],
    default="normal",
)
rows["alert_flag"] = np.where(rows["severity"] == "normal", 0, 1)
print(rows)
alerts = rows[rows["anomaly_pct"] >= 15]
print(alerts.nlargest(5, "anomaly_pct")[["hour", "building_id", "kwh", "baseline_kwh", "anomaly_pct", "severity"]])
print(pd.pivot_table(rows, index="building_id", columns="severity", values="alert_flag", aggfunc="sum", fill_value=0, margins=True))

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

3 · Convert alerts into maintenance economics

Join alert records to tariff and building context, then estimate savings opportunity.

TypeScript

import { DataFrame, merge, nlargestDataFrame, pivotTableFull } from "tsb";

const tickets = DataFrame.fromRecords([
  { ticket_id: "m301", building_id: "B03", system: "chiller", severity: "critical", excess_kwh: 55, status: "open" },
  { ticket_id: "m302", building_id: "B03", system: "ventilation", severity: "watch", excess_kwh: 27, status: "open" },
  { ticket_id: "m303", building_id: "B01", system: "lighting", severity: "watch", excess_kwh: 14, status: "scheduled" },
  { ticket_id: "m304", building_id: "B02", system: "plug load", severity: "watch", excess_kwh: 9, status: "scheduled" },
  { ticket_id: "m305", building_id: "B03", system: "chiller", severity: "critical", excess_kwh: 38, status: "open" },
  { ticket_id: "m306", building_id: "B01", system: "air handling", severity: "normal", excess_kwh: 6, status: "monitor" },
]);
const buildingContext = DataFrame.fromRecords([
  { building_id: "B01", campus: "North", rate_per_kwh: 0.18 },
  { building_id: "B02", campus: "North", rate_per_kwh: 0.18 },
  { building_id: "B03", campus: "South", rate_per_kwh: 0.24 },
]);

const enriched = merge(tickets, buildingContext, { on: "building_id", how: "left" }).assign({
  estimated_cost: (df) => df.col("excess_kwh").mul(df.col("rate_per_kwh")),
});
console.log(enriched.select(["ticket_id", "building_id", "campus", "system", "severity", "excess_kwh", "estimated_cost", "status"]).toString());

const systemSummary = enriched
  .groupby("system")
  .agg({ excess_kwh: "sum", estimated_cost: "sum" }, false)
  .sortValues("estimated_cost", false);
console.log("\nSavings opportunity by system:");
console.log(systemSummary.toString());

const costByStatus = pivotTableFull(enriched, {
  index: "system",
  columns: "status",
  values: "estimated_cost",
  aggfunc: "sum",
  fill_value: 0,
  margins: true,
});
console.log("\nEstimated cost by system/status:");
console.log(costByStatus.toString());

console.log("\nTickets to dispatch first:");
console.log(nlargestDataFrame(enriched, 3, { columns: "estimated_cost" }).select(["ticket_id", "building_id", "system", "estimated_cost", "status"]).toString());

import pandas as pd

tickets = pd.DataFrame([
    {"ticket_id": "m301", "building_id": "B03", "system": "chiller", "severity": "critical", "excess_kwh": 55, "status": "open"},
    {"ticket_id": "m302", "building_id": "B03", "system": "ventilation", "severity": "watch", "excess_kwh": 27, "status": "open"},
    {"ticket_id": "m303", "building_id": "B01", "system": "lighting", "severity": "watch", "excess_kwh": 14, "status": "scheduled"},
    {"ticket_id": "m304", "building_id": "B02", "system": "plug load", "severity": "watch", "excess_kwh": 9, "status": "scheduled"},
    {"ticket_id": "m305", "building_id": "B03", "system": "chiller", "severity": "critical", "excess_kwh": 38, "status": "open"},
    {"ticket_id": "m306", "building_id": "B01", "system": "air handling", "severity": "normal", "excess_kwh": 6, "status": "monitor"},
])
building_context = pd.DataFrame([
    {"building_id": "B01", "campus": "North", "rate_per_kwh": 0.18},
    {"building_id": "B02", "campus": "North", "rate_per_kwh": 0.18},
    {"building_id": "B03", "campus": "South", "rate_per_kwh": 0.24},
])
enriched = tickets.merge(building_context, on="building_id", how="left")
enriched["estimated_cost"] = enriched["excess_kwh"] * enriched["rate_per_kwh"]
print(enriched[["ticket_id", "building_id", "campus", "system", "severity", "excess_kwh", "estimated_cost", "status"]])
print(enriched.groupby("system", as_index=False).agg({"excess_kwh": "sum", "estimated_cost": "sum"}).sort_values("estimated_cost", ascending=False))
print(pd.pivot_table(enriched, index="system", columns="status", values="estimated_cost", aggfunc="sum", fill_value=0, margins=True))
print(enriched.nlargest(3, "estimated_cost")[["ticket_id", "building_id", "system", "estimated_cost", "status"]])

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

⚡ Energy Anomaly Monitoring

1 · Enrich smart-meter readings

2 · Flag spikes against a rolling baseline

3 · Convert alerts into maintenance economics