Power Trace — Analysis Rules Guide

📖 Overview

The Rules page configures the thresholds, weights and message templates used by the Analysis Engine — the component that turns raw collected data into the Health Score, insights, events and forecast you see on the Analysis page. Everything here is stored in rules.yaml.

Sections are collapsible — click a section header to expand or collapse it. Frequently-tuned sections (Grid Quality, Load Analysis, Power Factor, Energy) are open by default; deeper, rarely-touched sections (Anomaly Detection, Detective Engine, Forecast, System State, Health Score, Messages) start collapsed.

💡 Rules are read by the engine each time an analysis runs. Saving new rules does not retroactively change past reports — click Run Analysis on the Analysis page afterwards to see the effect.

✅ Where to start: the defaults are tuned for a typical single-phase 230V household relay. Only change a value if you have a specific reason — for example, a 110V grid, a workshop with heavy motor loads, or a tariff period long enough to need a longer lookback.

📅 Schedule Optional

Controls how much history each analysis run looks at.

Lookback days

Range: 1–365, default: 30. How many days back the main report (Grid, Load, Power Factor, Energy, Events) covers on each run.

Min gap (min)

Range: 1–10, default: 3. Data gaps shorter than this are treated as normal jitter between ticks (the relay reports roughly every 60 seconds) and are not counted as a real data gap in Health Score penalties or the Data Coverage section.

⚡ Grid Quality Frequently tuned

Voltage nominal (V)

Range: 100–500, default: 230. The expected voltage of your grid. Used as the reference point for the stability (CV) calculation and for measuring how far voltage drops during a sag — set to 110 or 120 if you are on a split-phase North American supply. Must lie between Warn low and Warn high, otherwise every reading would be out of range by definition; the page blocks saving if it doesn't.

Voltage thresholds

Warn low / Warn high (V)

Defaults: 207 / 253. Voltage outside this band triggers a yellow (warn) sag or swell event. Typically ±10% of nominal.

Alert low / Alert high (V)

Defaults: 196 / 264. Voltage outside this wider band triggers a red (alert) sag or swell event, and contributes a larger penalty to the Health Score. Typically ±15% of nominal.

Event duration

Sag min duration / Swell min duration (sec)

Defaults: 60 / 60, range 60–3600 each, in steps of 60. A voltage dip or rise must persist at least this long to be logged as a sag/swell event. The relay reports roughly once every 60 seconds, so 60 seconds is the shortest event that physically exists: 60 means “report the first bad reading”, 120 means “require two in a row”, and so on. Values below 60 are indistinguishable from 60 and are raised automatically when the page loads.

Stability

CV warn / CV alert

Defaults: 0.03 / 0.07, range 0.001–0.5 each. Coefficient of variation (standard deviation ÷ average) of voltage over the period. Above the warn threshold the grid is marked marginal; above the alert threshold it is marked unstable.

🔌 Input Capacity Optional

These limits describe your own electrical installation, so PowerTrace ships with them empty and the section stays silent until you fill them in. There is no sensible default: a 25 A apartment and a 40 A house would each get hundreds of false events from the other one's setting. Fill in what you know and leave the rest blank.

⚠ This detector sees thermal overloads — tens of seconds and longer. It cannot see inrush currents from compressors and pumps, which last a second or two and are exactly what trips a breaker on its magnetic release. The relay reports roughly once a minute, so anything shorter never reaches the database. Silence here does not mean your breaker will hold.

Current limit

Breaker rating (A)

Range: 1–200, empty by default. The rating of the breaker protecting the line the relay sits on — the input breaker if the relay meters your whole supply, or that circuit's breaker if it meters one group. Trace the wire upwards from the relay and read the number off that breaker. Leave empty if you are not sure; an empty field simply disables current detection.

Alert current (A)

Range: 1–300, filled in automatically as 1.45 × rating when you enter the rating above. That multiplier comes from the breaker's time-current characteristic: 1.13× can be carried indefinitely, while 1.45× is the current at which a trip is guaranteed within an hour. Below this level an excursion is a yellow warn; at or above it, a red alert. Edit it and the automatic value stops overwriting your choice.

Current min duration (sec)

Default: 60, range 60–3600 in steps of 60. How long the current must stay above the threshold before an event is recorded. As with voltage events, 60 seconds is the shortest event that physically exists at the relay's reporting rate.

Power limit

⚠ Fill the power limit in only if the relay meters the whole property. Contracted power applies to everything behind your meter, so with partial metering the analysis sees a fraction of the load and will never notice a real breach — leaving you with a detector that reports nothing and thereby confirms all is well. A wrong current rating produces noisy false events, which you notice; a wrong power limit produces silence, which you do not.

Contracted power (W)

Range: 100–100000, empty by default. The supply limit agreed with your utility. This is an independent limit, not the current one expressed differently: 25 A at 230 V is about 5750 W, so a 3000 W contract is reached at less than half the breaker's rating. One limit is about fire, the other about your bill, and both are worth watching. The page warns you — without blocking — if the figure you enter exceeds what the breaker rating physically allows, since such a limit could never trigger.

Alert power (W)

Range: 100–200000, empty by default and not filled in automatically. Unlike the breaker, a contract has no time-current curve to derive a hard level from, so any multiplier here would be invented; pick a figure your own agreement justifies, or leave it blank and work with the warn level alone.

Shared

Hysteresis (%)

Default: 10, range 0–50. How far below a threshold the load must fall before the event is considered over, as a percentage of that threshold. Without it a load hovering at the limit shatters into dozens of one-minute events: a water heater sitting at 2.9 kW plus a fridge cycling its 150 W crosses a 3 kW limit back and forth every half hour. A percentage rather than a fixed figure because load runs from zero to the limit, and it gives the heavier alert level proportionally more room, which is what you want. Raising it merges events without inflating Time out of range — that figure counts only the minutes genuinely past the threshold.

📈 Load Analysis Frequently tuned

Peak percentile / Base percentile

Defaults: P95 / P10. Instead of using the raw maximum (which can be a one-off spike) and raw minimum (which can be a data glitch), the engine uses the 95th percentile as a robust peak estimate and the 10th percentile as a robust base load estimate.

Change warn / Change alert (%)

Defaults: 25% / 50%. Compares average load against the previous period of the same length. A change of at least Change warn raises a Load Increased / Load Decreased insight; a rise of at least Change alert promotes it to warning level. A drop is always informational — using less power is not a fault.

Peak profile multiplier

Range: 1–5, default: 1.3. If the average load during the morning or evening window is at least this many times the overall average, the day is classified with a morning peak or evening peak profile.

Daily profile windows

Morning peak from / to (hour)

Default: 6 – 9. The hour range checked for a morning consumption peak, in your local time (the timezone set on the Settings page). From must be earlier than to — equal or reversed bounds would make the window empty and silently disable profile detection, so the page blocks saving.

Evening peak from / to (hour)

Default: 17 – 21. The hour range checked for an evening consumption peak, in your local time. Same from < to rule as the morning window.

📉 Power Factor Frequently tuned

Good / Acceptable / Poor thresholds

Defaults: 0.95 / 0.85 / 0.70, range 0.1–1 each. Power factor above the good threshold is rated good; between acceptable and good it's acceptable; below poor it's flagged as poor and contributes to the Health Score penalty.

Low duration warn / Low duration alert (%)

Defaults: 10% / 25%. If power factor stays below the poor threshold for at least this share of the period, the engine raises a Low PF Sustained warning or alert — useful for spotting motors or electronics running without correction. The Low duration warn threshold drives more than the recommendation: it is the same value that triggers the Low PF sustained penalty in Health Score, so both fire on one and the same number.

🏠 Energy Consumption Frequently tuned

How daily totals are counted

Worth knowing before you read the numbers. A day's consumption is measured from the last meter reading of the previous day to the last reading of that day, using your local calendar days — so a daylight-saving transition day correctly gets 23 or 25 hours instead of a flat 24. The current, still-running day is excluded from the average, minimum, maximum, trend and forecast (it only holds a partial figure so far, and counting it would drag every statistic down); it is reported separately in the summary text. If the collector was offline for a full day or more, the days spanning that outage are left out entirely rather than having the whole gap's consumption dumped onto one day — the unattributed total is stated in the summary instead.

Trend min days

Range: 3–90, default: 14. Minimum number of days of data required before the engine will attempt to calculate a rising/falling/stable energy trend.

Trend stable slope (kWh/day)

Range: 0–10, default: 0.05. If the day-over-day change in consumption (the slope) is smaller than this, the trend is reported as stable rather than rising or falling.

🚩 Anomaly Detection Advanced

Statistical outlier detection for both single-day energy totals and short power bursts.

Z-score threshold

Range: 1–10, default: 3.0. A daily value more than this many standard deviations from the recent average is flagged as an energy anomaly. This check runs against every day in the analysis window, not just the most recent one — each day is compared to the history of days before it.

Outlier fence multiplier (IQR)

Range: 0.5–5, default: 1.5. Multiplier applied to the interquartile range to build the outlier “fence” — an alternative, more robust check alongside the Z-score.

Trim percent

Range: 0–20, default: 5. Percentage trimmed from each end of the distribution before computing average/std-dev, so a handful of extreme values don't skew the baseline.

Min history points

Range: 10–1000, default: 48. Minimum number of historical data points required before anomaly detection is attempted at all.

Burst multiplier / Burst min duration (min)

Defaults: 3.0× / 3 min. A power spike must reach at least this multiple of the median load and last at least this long to be logged as a Load Burst event.

🕵 Detective Engine Advanced

Looks for recurring daily patterns and cause-effect correlations between events (e.g. voltage sagging whenever load surges), shown as cards on the Analysis page.

Correlation window (min)

Range: 1–120, default: 10. Two events within this many minutes of each other are considered for a possible cause-effect correlation.

Pattern min occurrences / Pattern lookback days

Defaults: 3 times / 14 days. A recurring behaviour must repeat at least this many times within the lookback window to be reported as a pattern. This window is independent of Schedule → Lookback days — pattern search always runs in its own window, so the number of days quoted in a recurring-pattern message stays the same whether the main report covers 7 days or 90.

Min confidence

Range: 0.1–1, default: 0.60. Patterns and correlations below this confidence score (0–1) are not shown.

Surge percentile

Range: 50–99, default: 75. Power percentile used as the “surge” threshold when searching for load-vs-voltage correlations. At the default, the top quarter of all readings counts as a surge.

Min lift

Range: 1–10, default: 1.5. Guards against reading meaning into coincidence. A surge showing up before a voltage sag proves nothing on its own — if a quarter of all readings are surges, one will land in the window before a sag most of the time purely by chance. So the engine also measures how often surges appear in any window of the same length, and reports the correlation only when the observed rate exceeds that background rate by at least this multiple. Raise it if you still see correlations you don't trust; lower it towards 1.0 to see weaker associations.

Peak hour multiplier

Range: 1–5, default: 1.4. An hour's average load must exceed the overall average by at least this multiple to be reported as a recurring peak hour.

🔮 Forecast Advanced

Predicts tomorrow's and next month's energy consumption using a weighted moving average (WMA) — more recent days count more than older ones.

Window days

Range: 3–30, default: 7. Number of most-recent days fed into the forecast.

Confidence interval

Range: 0.5–0.99, default: 0.80. Probability range used to compute the forecast's upper/lower bounds — 0.80 means an 80% confidence band around the predicted value.

WMA weights

Comma-separated list, oldest → newest, default 1, 1, 2, 2, 3, 3, 4. The number of weights must match Window days. Higher numbers for recent days make the forecast react faster to changes in usage.

📊 System State Advanced

Temp warn / Temp alert (°C)

Defaults: 60°C / 75°C. The relay's onboard temperature at or above these thresholds raises a High Temperature insight — a warning at the first threshold, an alert at the second — and deducts the matching penalty from the Health Score.

Frequency

No settings. Grid frequency is reported alongside temperature with a stability badge, but has no thresholds on this page — the engine judges it on its own. It is listed here only to explain why it is absent from the settings.

💡 Temperature and frequency are the only figures in the report that describe this moment rather than the whole period. The device stores only its current reading, with no history, so the temperature insight and its penalty reflect how hot the relay is when you press Run Analysis — not whether it ever overheated during the past 30 days.

📜 Health Score Advanced

The single 0–100 number shown at the top of the Analysis page, built from six weighted components.

Component weights (must sum to 1.0)

Voltage stability · Power factor · Load balance · Energy trend · Event rate · Data continuity

Defaults: 0.25 / 0.20 / 0.15 / 0.15 / 0.15 / 0.10. How much each component contributes to the final score. The page blocks saving until the six weights add up to exactly 1.0 — a live error message shows the current sum.

Penalties (points deducted per event per day)

Voltage alert event / Voltage warn event

Defaults: 15 / 5 points, charged per event per day. Each value is multiplied by the event rate — red/yellow voltage events in the period divided by the length of that period in days — not by the raw event count. Two alert events over two days and twenty over twenty days therefore cost the same, so a longer analysis period no longer inflates the deduction on its own. The result passes through Voltage alert cap / Voltage warning cap first, and only then through the overall Penalty cap below.

Low PF sustained

Default: 10 points. Deducted once when power factor stays below the poor threshold for longer than the warn share of the period. This one describes a state, not a series of events, so it is not normalised by rate — it is charged in full or not at all.

High temperature (warn) / High temperature (critical)

Defaults: 8 / 20 points. The two are mutually exclusive — a device at or above Temp alert costs the critical penalty instead of, not on top of, the warn one. The gap between them is deliberate: a relay running at 80°C is a different kind of problem from one at 65°C. Like Low PF sustained, these describe a state rather than a series of events: they carry no per-day normalisation and are charged in full.

Voltage alert cap

Range: 0–100, default: 25. The most that voltage alert events alone can subtract from the score, however frequent they are. It is applied first, ahead of the overall Penalty cap, so a grid that does nothing but sag still leaves room for the other penalty classes to register in the score.

Voltage warning cap

Range: 0–100, default: 10. The same ceiling for voltage warning events, counted separately from alerts — a long run of yellow events cannot eat into the budget reserved for red ones.

Penalty cap

Range: 0–100, default: 40. The last and most general ceiling: it applies only after every class of penalty has already run into its own — the two voltage caps above, and the fixed state penalties. Now that event penalties are counted per day rather than per event, this cap is meant as a backstop for the case where several classes fire at once (bad voltage and a hot relay and sustained low PF), not as a mode the score sits in day after day. Without any ceiling the deductions would be unbounded and would pin the score at zero, which makes it useless exactly when you most need it to tell “bad” apart from “catastrophic”.

Score levels

Excellent / Good / Fair (minimum score)

Defaults: 90 / 75 / 55. The minimum score needed to reach each label. Anything below the Fair threshold is labelled poor.

Score calculation parameters

PF score min / PF score max

Defaults: 0.60 / 1.00. Power factor values mapped to the 0–100 range: a PF at or below the min maps to a component score of 0, at or above the max maps to 100.

CV penalty factor

Default: 2000. The voltage-stability component score is reduced by CV × CV penalty factor.

Load balance ratio threshold / Load balance penalty factor

Defaults: 2.0 / 20. Once the peak/average load ratio exceeds the threshold, the load-balance component is reduced by (ratio − threshold) × penalty factor.

Worst component threshold

Range: 0–100, default: 70. Any component scoring below this triggers a “main factor reducing Health Score” insight naming that component.

💬 Messages Advanced

Every insight, event and recommendation shown on the Analysis page is built from an editable text template here — you can rewrite the wording (make it more casual, add detail) without touching code.

💡 Leave a field empty to use the default wording for your interface language — the grey placeholder text shows exactly what will be used. Only fields you actually type into are written to rules.yaml. To translate the interface, install a language pack instead (see Settings → Interface Language); these fields are for overriding individual messages on top of it.

⚠ Templates use placeholders in curly braces, e.g. {min_voltage}, {duration_min}. Do not remove or rename placeholders — the page validates this and blocks saving if a placeholder used by the engine is missing from your edited text.

💡 A template that is absent from rules.yaml is normal, not an error: the report then uses the wording from your language pack, falling back to the engine's own built-in English rather than printing a bare code like VOLTAGE_SAG. Saving through this page will, however, reject an unknown message key or a template that has dropped a placeholder the engine needs.

Message	Fires when…
VOLTAGE_SAG / VOLTAGE_SWELL	Voltage sags below or swells above a threshold for at least the minimum duration.
LOAD_BURST	A short power spike exceeds the burst multiplier for at least the minimum burst duration.
ENERGY_ANOMALY	A day's total consumption is a statistical outlier (Z-score/IQR).
LOW_PF_SUSTAINED	Power factor stays below the poor threshold for longer than the warn/alert duration share.
VOLTAGE_UNSTABLE	Voltage coefficient of variation exceeds the CV warn threshold.
DATA_GAP	One or more gaps in the collected data are found for the period.
HIGH_TEMP	Device temperature is at or above the warn threshold right now (see System State — this one describes the present moment, not the period).
LOAD_INCREASED / LOAD_DECREASED	Average load changed vs. the previous period by more than the warn percentage (a rise past the alert percentage becomes a warning).
ENERGY_TREND_RISING / ENERGY_TREND_FALLING	The energy trend slope is above/below the stable-slope threshold.
HIGH_ANOMALY_RATE	The number of anomaly events in the period is unusually high.
LOAD_BALANCE_POOR	Peak/average load ratio exceeds the load-balance threshold.
RECURRING_PATTERN_DETECTED / VOLTAGE_SAG_FOLLOWS_LOAD	The Detective Engine finds a repeating daily pattern, or a load→voltage correlation that clears both the confidence and the lift thresholds.
*_MAIN_ISSUE (PF, Voltage, Load Balance, Energy Trend, Anomaly Rate, Data Continuity, System)	That component is the single worst-scoring one behind a reduced Health Score.
HEALTH_SCORE_IMPROVED / DECLINED	Shown when the score differs from the previous run. An unchanged score produces no message.
NO_CRITICAL_EVENTS / ALL_COMPONENTS_HEALTHY	Shown when nothing needs attention, so the report doesn't look empty.

💾 Save Buttons

💾 Save Rules

Writes all rules to rules.yaml. Blocked if any field is out of its valid range, if the six Health Score weights don't sum to 1.0, if a message template is missing a required placeholder, or if two fields contradict each other — see below.

Conflicting values

Some fields are only valid relative to each other, and a contradiction between them breaks the analysis quietly rather than loudly. Setting Alert low above Warn low, for instance, would make every single reading count as a red-level sag and drive the Health Score to zero with no explanation. The page therefore also checks that voltage thresholds run in order (alert low < warn low < warn high < alert high), that nominal voltage sits inside the warn band, that power-factor and temperature thresholds ascend, that score levels ascend, that each percentage warn threshold is below its alert counterpart, that daily-profile windows start before they end, and that the number of WMA weights matches the forecast window. Offending fields are highlighted as you type.

↺ Reset to Saved

Discards unsaved changes and reloads the values currently stored in rules.yaml.

⚠ Reset to Defaults

Resets every field on the page to the factory defaults shown throughout this guide. Click Save Rules afterwards to actually write them to disk.

💡 After saving, go to the Analysis page and click Run Analysis to generate a fresh report using the new rules.