Events Pipeline

This page describes how Events are produced and kept current. PV and BESS processing follow asset-specific paths, then converge on saving Events, aggregating losses, and refreshing the active-Event list shown in the platform.

1. Project selection

PV projects run PV detection, BESS projects run BESS detection, and hybrid PV-plus-storage projects run both. A failure in one does not prevent the other, or later steps such as loss aggregation, from being attempted.

Only projects with Event integration enabled are processed.

2. Analysis-window selection

All window selection uses the project's local time zone. Events are reanalyzed on a regular cadence:

• At local midnight, the preceding three days are analyzed in one-day chunks.
• At each other six-hour boundary, the period from local midnight through the current five-minute boundary is reanalyzed.
• At other five-minute boundaries, the preceding hour is analyzed.
• When a specific range is reprocessed, ranges longer than one day are divided into one-day chunks.

Reanalysis is not just a recovery mechanism. It is part of normal correctness: delayed telemetry can change flags, recent open Events need to be extended or closed, and overlapping records must be reconciled.

The logical window convention is half-open: it includes the start and excludes the end. Samples are generally represented at five-minute resolution.

3. Metadata and existing Event retrieval

For each project and window, the pipeline loads the device and tag metadata needed for detection. It also retrieves existing Events that intersect the window.

Existing Events serve four purposes:

• seed the initial state of a device so an Event can continue across window boundaries;
• preserve the original Event ID, detection time, failure mode, root cause, and other durable metadata when intervals overlap;
• close open Events for which no detection evidence remains; and
• protect claim-linked Event records from deletion during overlap cleanup.

Before new detection, overlapping existing Events on the same device are consolidated. The retained Event covers the union of the overlapping intervals. The earliest Event is normally retained, but a claim-referenced Event takes precedence over an unclaimed Event. If more than one overlapping Event is claim-referenced, those records are kept rather than deleting a claim dependency.

4. Building detection flags

Both PV and BESS detection reduce heterogeneous telemetry to a flag for each device at each timestamp. Each flag is True, False, or NA:

• True: anomalous evidence is present.
• False: nominal or recovered evidence is present.
• NA: the method has insufficient evidence.

PV primarily uses power under an irradiance gate, with separate tracker and curtailment paths. BESS creates two independent evidence sets: one from decoded statuses and another from power or availability telemetry. Those results are merged so that True wins, but False combined with NA remains NA rather than being treated as healthy.

The exact detection logic is covered in Event Detection Methods.

5. Hierarchy transformation

The raw device flags are transformed before they become Events:

1. an active ancestor masks its descendants;
2. simultaneous flags from every sibling of the same device type can roll up to their parent;
3. rollup repeats until no higher-level change occurs; and
4. BESS applies singleton and imputed-parent corrections for particular hierarchy shapes.

The result is not a simple aggregation. NA is used intentionally to express dependence and prevent a masked child from becoming a separate Event. The detailed algorithm and edge cases are in Event Ancestral Hierarchy.

6. Temporal cleanup and Event intervals

The pipeline removes isolated anomalous samples before creating Event intervals. The PV and BESS paths then apply slightly different temporal rules.

PV

PV joins True–NA–True across an interior telemetry gap, but leading or trailing NA does not start or extend a new Event. Consecutive True samples become one interval. A new non-curtailment Event must normally contain at least 15 minutes of POA-qualified anomalous duration. Existing Events and explicitly exempt devices are not discarded by this new-Event duration filter.

BESS

BESS converts consecutive True samples into intervals after removing isolated True samples. A newly detected interval must normally be at least 10 minutes long. BESS additionally applies a six-hour recovery grace period: a recovery gap shorter than six hours is treated as continuous, preventing short nominal periods from prematurely closing an Event.

The BESS Event state still records the distinction between evidence and hysteresis. If an Event is open only because of the grace period, it is pending close. If direct evidence remains anomalous, or is indeterminate, it remains active.

7. Reconciliation with existing Events

New intervals are reconciled with existing intervals per device using half-open overlap semantics. Overlapping intervals are unioned:

• the earliest start time is retained;
• if either interval is open, the merged interval remains open;
• otherwise the latest end time is retained; and
• existing durable metadata and Event IDs are preferred.

Two intervals where one ends exactly when the other begins are not merged.

Open Events not represented by the current detection results are treated as orphans. They are closed at the analysis start unless they are protected by an asset-specific exception, such as tracker handling, or are already represented by a merged Event. BESS slow-close history is analyzed before this point so short recoveries are not mistaken for orphans.

If interval consolidation makes an existing unclaimed Event redundant, it may be removed. Claim-referenced Events are protected from deletion.

8. Failure-mode assignment

Failure mode describes the first observable cause supported by telemetry; it is not necessarily the physical root cause.

For status-based BESS detection, an abnormal status bit can carry a configured failure mode directly into the Event. When several bits are abnormal, their configured failure modes are retained as candidates and the Event window is used to infer the most representative value. If no specific status-derived mode survives, BESS assigns a device-type fallback such as PCS offline, bank offline, string offline, module-group offline, or module offline; unsupported types receive unknown.

PV assigns failure modes after interval reconciliation. Curtailment is stamped separately so that a generic failure-mode lookup does not overwrite a supported curtailment classification. Tracker stow and other PV modes use their corresponding telemetry and device context.

Root cause remains distinct. It can be populated through later operational analysis, claims, or field findings.

9. Saving Events

The pipeline checks Event state before saving. New Events are created, existing Events are updated, and redundant unclaimed overlapping Events may be removed. Any closed Event whose state is not closed is corrected.

Loss records are stored separately and keyed by Event and timestamp. They are updated in place so repeated analysis can revise recent loss estimates.

10. Loss calculation

PV energetic loss compares expected and actual production, with device- and hierarchy-aware allocation. The calculation prevents overlapping ancestor and descendant Events from double counting the same shortfall and caps allocated loss by the available meter-level shortfall. Curtailment loss uses the curtailment setpoint and is bounded by both expected shortfall and actual shortfall.

BESS currently uses a capacity-based financial proxy. For each five-minute sample in the Event interval, it applies a flat daily value of $0.357/kW/day to the Event device's AC capacity. It also emits a capacity loss record. Project-level BESS Events use POI capacity.

After all per-window processing, recent loss records are coalesced onto the Event:

• financial loss records become the Event's total financial loss;
• that total divided by the inclusive number of calendar days becomes daily financial loss; and
• energetic loss records become the Event's total energetic loss.

The coalesce step covers open Events and Events closed within the recent lookback, currently two days.

11. Notifications and active-Event refresh

PV and BESS notifications are generated only when notifications are enabled. A notification failure does not change the underlying Event interval.

At the end of processing for each project, the operational list of active Events is refreshed from the project's Event records. That list is a derived view rather than the source of truth; the Event and Event-loss records remain authoritative.