Pulse Documentation

name: op-overlay-share-of-total
kind: operator
category: OVERLAY
operator: OVERLAY_SHARE_OF_TOTAL
description: Share-of-grand-total ratio — dual-shape (matrix per-cell or series per-group); raw share sums to 1.0.
type: reference
applies_to: process, compose
examples_tags: [overlay, proportion-analysis, streaming-friendly]

Overlays decorate the host; no Response.Components.

Use when

Each crosstab cell or group of a grouped result as a share of the grand total (0 to 1): what part of the whole each piece makes up.

Questions it answers:

• What share of all revenue does each region bring in?
• What part of all responses falls in each segment-by-answer cell?

Use something else:

• OVERLAY_SHARE_OF_ROW when you want the share within each row of a crosstab.

Params

Scope required — cell (MATRIX) or group (SERIES). Ref.Margin.Axis required on MATRIX dispatch (grand-axis-locked, value ignored), empty on SERIES. Level / Within must be 0.

Host shape

Dual-shape: MATRIX crosstab (Ref.Margin required, grand-axis) → cell / grand_total; SERIES grouped Process host (implicit grand-total, empty Ref) → group_val / grand_total.

Output

MATRIX or SERIES — raw share (no ×100). A whole matrix / complete partition sums to 1.0 within ULP. Layer Baseline = 1.

Gotchas

• Streamable via SERIES dispatch — same computeSeriesGrandTotal accumulator as the total index; MATRIX buffers.
• Empty Ref.Margin on MATRIX, or a populated Ref on SERIES → PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
• grand_total == 0 → NaN + ONE PULSE_OVERLAY_REF_ZERO per layer.
• Absent host coordinate → unset entry, no contribution to the grand total.
• A share, not an index (×100); the kind names are kept distinct.
• Weighted host → weighted figure (reads the host payload).

See

• Skills: overlay-system, crosstab-guide, op-overlay-share-of-row, op-overlay-index-vs-total.