Event Ancestral Hierarchy

The Events pipeline uses the project device hierarchy to answer a practical question: at what device level is an observed condition most actionable without double-reporting dependent symptoms?

The hierarchy process has two complementary operations:

• ancestor sweep suppresses descendants while an ancestor is already anomalous; and
• child rollup replaces a complete set of simultaneous sibling conditions with one parent condition.

These operations occur on time-indexed flags before Event intervals are created. Consequently, hierarchy can affect an Event's device, start, end, continuity, failure mode, and loss attribution.

Hierarchy representation

Each device has a parent and, where available, an ordered ancestry of devices from the project down to itself. The device itself is excluded from its ancestor list.

The parent is used for direct sibling groups and rollup. The full ancestry is used to identify all ancestors, not only the immediate parent. Incorrect or incomplete hierarchy metadata therefore changes attribution even if the telemetry itself is correct.

Operation 1: ancestor sweep

At each timestamp, if an ancestor flag is True, every represented descendant of that ancestor is set to NA.

Example before sweep:

Project: False
PCS:     True
Module:  True
String:  True

Example after sweep:

Project: False
PCS:     True
Module:  NA
String:  NA

The descendants become unknown rather than healthy. False would assert that the child had positively recovered, which is not supported when the ancestor condition can explain the child's behavior. NA prevents dependent child symptoms from becoming separate Events while preserving the distinction from nominal operation.

The sweep considers every ancestor present among the devices being evaluated, so a high-level Event can suppress descendants across multiple hierarchy levels in one pass.

Operation 2: complete-sibling rollup

Rollup groups direct children by both parent and device type. For each group and timestamp, rollup occurs only when:

1. every configured child of that type under the parent is among the devices being evaluated; and
2. every one of those children is True at that timestamp.

When both conditions hold, all grouped child flags become NA and the parent becomes True.

Example with three PCS modules under one PCS:

Before: module A=True, module B=True, module C=True, PCS=False
After:  module A=NA,   module B=NA,   module C=NA,   PCS=True

If module C is False, NA, or present in metadata but missing from the devices being evaluated, the complete-sibling rollup does not occur. A sibling missing from metadata cannot be counted at all and may therefore make the configured group appear complete; this is one reason hierarchy metadata quality is critical.

Children are grouped by type. If a parent has two banks and three PCS modules, all banks being anomalous can roll up independently of the module group. The pipeline does not require every child of every type under the parent to be anomalous.

Rollup repeats until no further change occurs. A complete set of module Events can first become a PCS condition; a complete set of PCS conditions can then become a collector, transformer, or project condition on a later iteration.

Project-level BESS exception

BESS treats Project, Meter, and PPC devices as project-level evidence. An active Meter or PPC condition is moved to the Project device even when there is only one such device. This avoids leaving a project-wide condition represented as a meter-component Event.

The PV rollup differs: it avoids ordinary rollup directly into the Project parent. Project-level PV evidence is principally supplied by the meter/project power logic rather than by arbitrary complete child sets.

Singleton correction in BESS

Complete-sibling rollup has a degenerate case: a group containing one child is trivially “all true.” Blindly retaining that rollup would move many Events to a parent that adds no useful aggregation.

After iterative BESS rollup, the singleton correction walks an inferred parent flag back down to its sole child of that type. It repeats until no more moves occur.

There are two important guards:

• A parent flag that was present in the original evidence remains on the parent. Only a flag inferred by rollup is moved down.
• Walk-down skips a BESS DC skid singleton. For example, a module condition that rolls through one DC skid to a PCS is allowed to remain on the PCS rather than being forced back to the skid.

This distinction preserves real parent telemetry while correcting hierarchy artifacts introduced by one-child groups.

Imputed BESS ancestors

Some BESS ancestors may not have direct detection telemetry but are still meaningful Event devices. The current imputed-parent device types include:

• MV collector circuit;
• medium-voltage transformer;
• Project; and
• Meter.

Before intervals are created, the pipeline attempts to derive these parent flags from descendant PCS evidence.

The preferred derivation runs the normal rollup algorithm on leaf flags with existing imputed-parent results temporarily set aside. If ordinary hierarchy rollup reaches the parent, that result is used.

If it does not, a fallback examines all descendant PCS devices:

• all PCS flags True, or a mixture of True and NA with no False, produces parent True;
• any PCS False produces parent False; and
• all PCS NA produces parent NA.

All descendant PCS devices must be present. Missing a PCS series prevents the fallback from asserting a parent condition.

When a parent also has direct status or status-less evidence, inferred evidence is combined carefully:

• inferred True can establish the parent condition;
• inferred False is closing evidence; and
• inferred NA does not overwrite an existing parent True.

The last rule is crucial: missing leaf telemetry cannot erase direct evidence on the parent.

Existing ancestor Events and continuity

Hierarchy must remain consistent across overlapping analysis windows. A child may have current telemetry while its ancestor has an existing open Event but no direct telemetry in the current window.

The BESS path collects all ancestors of flagged devices and relevant existing Event devices, then constructs an ancestor-active mask:

• if the ancestor has raw telemetry, that telemetry is authoritative;
• if it is an imputed-parent type, its derived flag is authoritative; and
• otherwise, existing Event intervals are applied onto the current timestamps.

The six-hour recovery grace period is applied to each ancestor-active mask. While that mask is active, the later ancestor sweep suppresses descendant flags. This prevents a child Event from appearing merely because the current window did not include or produce a direct ancestor tag.

Existing Event intervals use the half-open convention described in Events Overview. A closed ancestor ceases to suppress descendants at its first recovered sample.

Continuity across analysis windows

Before hierarchy processing and interval creation, preexisting Events seed a True value just before the available timestamps. That state is then carried forward from the seed.

This solves a boundary problem: a window that begins in the middle of an Event should extend the existing Event rather than create a new Event at the window start.

Imputed BESS parent Events are excluded from ordinary preexisting seeding. Their current state must be re-derived from the leaves; otherwise a stale imputed parent could perpetuate itself without descendant evidence.

An Event ending exactly at the analysis start is also excluded. Since the end time is exclusive, that Event is already recovered and must not reopen through seeding.

Why NA is central to hierarchy

Hierarchy uses NA for two different but compatible meanings:

• the detector lacks sufficient telemetry; or
• an ancestor explains the descendant, so the descendant's independent state is intentionally not asserted.

Both meanings say “do not create an independent Event here.” They differ from False, which says “we have positive evidence of nominal operation.”

This produces several important outcomes:

• a swept child does not immediately close as healthy merely because its parent is active;
• a communications gap does not become an outage solely through missing data;
• all-unknown leaves do not create an imputed parent Event; and
• a clear child can provide closing evidence for an imputed parent.

Event continuity when parent and child timing differ

Hierarchy is evaluated per timestamp, not once per analysis window. The represented device can therefore change as the condition evolves.

Consider two sibling modules:

1. Module A fails first, so its flag remains on Module A.
2. Module B later fails, making every module True; both module flags roll up to the PCS.
3. During the PCS-level interval, module flags are NA.
4. Module B recovers while Module A remains failed; complete rollup ends and Module A can again carry a device-level condition.

The reconciliation stage then compares these generated intervals with existing Events. It preserves overlapping Event IDs on the same device, but it does not merge intervals across different devices merely because they share ancestry. Operators may therefore see a child Event followed by a parent Event, or the reverse, when the breadth of the condition changes.

An existing child Event is not automatically deleted just because a later parent Event appears. This is intentional when timing supports distinct addressable conditions. Dependent simultaneous samples are suppressed prospectively by the flag hierarchy, while historical Event reconciliation remains device-specific.

Failure modes and losses after hierarchy

Hierarchy chooses the Event device before final failure-mode fallback and loss assignment.

For BESS, a status-derived failure mode may be inferred over the Event window before device-type fallback. If no specific mode is available after rollup, the ancestor's device type may receive unknown because only PCS, bank, string, module-group, and module types currently have explicit offline fallbacks.

For PV, a rolled PV Block Event is reassigned to the first inverter below the block, optionally through an MV transformer. This is a later correction intended to keep the Event on an actionable inverter device.

Loss allocation also follows the final hierarchy. PV explicitly masks loss on descendants while an ancestor Event is active to avoid double counting. BESS capacity-based loss uses the final Event device's capacity, with Project Events using POI.

When hierarchy attribution looks wrong

When an Event appears on an unexpected device, inspect these items in order:

1. Verify that the device's ancestry includes every expected ancestor in the correct order.
2. Verify each device's direct parent.
3. Verify sibling device types; rollup groups by type as well as parent.
4. Confirm that every configured sibling is being evaluated and has evidence rather than a gap.
5. Determine whether the parent flag was direct, rolled up, imputed, continued from an existing Event, or seeded from a preexisting Event.
6. Check singleton correction and the DC-skid exception.
7. Check whether a six-hour BESS grace mask is holding the ancestor active.
8. Inspect the pre-hierarchy and post-hierarchy flags at the exact timestamp.
9. Finally, inspect Event reconciliation and claim references before concluding that a redundant Event should have been deleted.

The hierarchy output is only as reliable as device metadata. A missing sibling, incorrect parent, malformed ancestry, or wrong device type can prevent rollup, over-suppress descendants, or attach the Event to an inappropriate ancestor even when detection evidence is correct.