overlayhost

package
v1.0.0-alpha.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package overlayhost is the one declaration of WHICH overlay slot each catalog kind runs on, and the one refusal a kind authored on any other slot gets.

Four slots carry overlay specs: Request.Overlays (a Process host — crosstab MATRIX or grouped SERIES), ComposedRequest.Overlays, ChainRequest.Overlays and FacetRequest.Overlays. Each runtime dispatcher (internal/processing) and each predict validator (internal/descriptor) calls Refusal for every spec before any per-kind rule, so a kind on the wrong slot is refused identically — code, message and Details — on both sides, instead of predict accepting it and the runtime answering PULSE_OVERLAY_KIND_UNKNOWN (or an empty stub layer). The processing-side test pins this table to the four runtime handler tables, so it cannot drift from what actually executes.

Within a Process host (Request.Overlays) it also declares the host SHAPE(s) each Process kind runs on — MATRIX (a crosstab), SERIES (a grouped request with aggregations), both, or MATRIX_RESULT (the Request.Matrices results of a request without a crosstab; ShapeMatrixResult, judged per kind by JudgedShape) — and owns the one refusal a kind authored over the other shape gets (ShapeRefusal), raised right after the slot refusal and before any per-kind rule, on predict and runtime alike. The processing-side drift test pins the shape table to the MATRIX and SERIES handler tables.

Leaf: stdlib + types + errors. No-execute.

Index

Constants

View Source 
const (
	// CorrespondenceSymmetric plots rows and columns both in principal
	// coordinates (the default, R ca's "symmetric" map).
	CorrespondenceSymmetric = "symmetric"
	// CorrespondenceRowPrincipal plots rows in principal and columns in
	// standard coordinates (R ca's "rowprincipal").
	CorrespondenceRowPrincipal = "row_principal"
	// CorrespondenceColumnPrincipal plots rows in standard and columns in
	// principal coordinates (R ca's "colprincipal").
	CorrespondenceColumnPrincipal = "column_principal"
	// CorrespondenceDefaultDimensions is the retained dimension count
	// when params.dimensions is omitted (capped at min(r, c) − 1).
	CorrespondenceDefaultDimensions = 2
)

Correspondence normalizations — which coordinates the map plots.

View Source 
const (
	// MarkovMaxStep is the largest accepted params.steps entry.
	MarkovMaxStep = 1000
	// MarkovMaxStepCount caps how many params.steps entries one spec may
	// list: each one is a k × k part.
	MarkovMaxStepCount = 64
	// MarkovInitialMargin is the params.initial string naming the
	// observed row-margin distribution.
	MarkovInitialMargin = "margin"
)
View Source 
const (
	GroupSummaryPartMin     = "min"
	GroupSummaryPartMax     = "max"
	GroupSummaryPartRange   = "range"
	GroupSummaryPartNGroups = "n_groups"
)

The OVERLAY_MATRIX_GROUP_SUMMARY parts beside its primary per-cell mean (every one a MATRIX on the union of the buckets' keys).

View Source 
const (
	// RakeTargetsShares is the default params.targets_as: each axis's
	// targets are normalized by their sum and scaled to the host grand
	// total.
	RakeTargetsShares = "shares"
	// RakeTargetsCounts reads the targets as the fitted margins
	// themselves; the row and column totals must agree.
	RakeTargetsCounts = "counts"
	// RakeDefaultMaxIter is params.max_iter when omitted.
	RakeDefaultMaxIter = 100
	// RakeMaxMaxIter is the largest accepted params.max_iter.
	RakeMaxMaxIter = 100000
	// RakeDefaultTolerance is params.tolerance when omitted: the largest
	// relative margin error a converged fit may keep.
	RakeDefaultTolerance = 1e-8

	// RakeAxisRow / RakeAxisColumn name the axis in a key-mismatch
	// refusal.
	RakeAxisRow    = "row"
	RakeAxisColumn = "column"
)
View Source 
const DimAxisKeyPrefix = "dim_"

DimAxisKeyPrefix is the prefix of the synthetic dimension AxisKeys a coordinate-style overlay part (points × dimensions) keys its columns with: "dim_1", "dim_2", … in dimension order. A dimension is not a host coordinate, so it gets a stable synthetic key instead of borrowing a host axis tuple.

View Source 
const ShapeMatrixResult types.OverlayShape = "matrix_result"

ShapeMatrixResult is the MATRIX_RESULT Process host shape: the Response.Matrices results of a request carrying Request.Matrices and no Request.Crosstab (Crosstab + Matrices is refused, so a request never carries both a crosstab overlay and a matrix-result one). It is a host-judging value only — no overlay payload ever carries it — so it lives here, not among the payload shapes in types.

Variables

This section is empty.

Functions

func Accepts 

func Accepts(host Host, kind types.OverlayKind) bool

Accepts reports whether kind runs on host. A kind outside the catalog is accepted: the slot's own unknown-kind gate owns it.

func AcceptsShape 

func AcceptsShape(shape types.OverlayShape, kind types.OverlayKind) bool

AcceptsShape reports whether kind runs on a Process host of shape. MATRIX, SERIES and MATRIX_RESULT hosts run exactly the kinds that declare them. A SCALAR (ungrouped, no matrices) host accepts every kind but a MATRIX_RESULT one — nothing runs on it, and the per-kind rules own the refusal — while a MATRIX_RESULT kind needs its matrix results. A kind outside the Process table (the slot refusal owns it) and a kind outside the catalog are accepted here.

func ComponentsRequiredMessage 

func ComponentsRequiredMessage(kind types.OverlayKind) string

ComponentsRequiredMessage is the PULSE_OVERLAY_COMPONENTS_REQUIRED message of an OVERLAY_PAIRWISE_* kind over a crosstab built with components disabled (Options.DisableComponents, or the request's own disable_components: true — a request's false re-opens an Options-disabled instance). Every pairwise kind reads its sample-size legs off the cell components, so the runtime (processing.runPairwiseOverlay) refuses it and predict (descriptor.validateOverlayPairwise) reports it with the same text.

func ComposeSlotRefusals 

func ComposeSlotRefusals(spec *types.ComposeOverlaySpec, index int, known func(label string) bool) []*errors.CodedError

ComposeSlotRefusals returns the label refusals of the Compose-host spec at index, in order: a Reference that is empty or names no slot (known reports a slot label) → PULSE_OVERLAY_REFERENCE_UNKNOWN {index, kind, which: "reference"[, slot_label]} alone; else no Targets → PULSE_OVERLAY_TARGET_UNKNOWN {index, kind, which: "targets"} alone; else one PULSE_OVERLAY_TARGET_UNKNOWN {index, kind, target_index, which: "target"[, slot_label]} per empty or unknown target. The runtime raises the first; predict reports them all. nil when every label resolves.

func CorrespondenceDimensionsRefusal 

func CorrespondenceDimensionsRefusal(kind types.OverlayKind, p CorrespondenceParams, rows, cols, index int) *errors.CodedError

CorrespondenceDimensionsRefusal refuses an EXPLICIT dimensions above the table's min(rows, cols) − 1 non-trivial dimensions (PULSE_OVERLAY_PARAM_MISSING, details {kind, param: "dimensions", dimensions, max_dimensions, rows, cols} plus index when >= 0). The omitted default is capped instead, never refused; a table below 2 × 2 is left to the shape refusal.

func CrosstabSpecKinds 

func CrosstabSpecKinds() []types.OverlayKind

CrosstabSpecKinds returns every kind CrosstabSpecRefusal judges, in no particular order (tests pin it against the MATRIX handler table).

func CrosstabSpecRefusal 

func CrosstabSpecRefusal(spec *types.OverlaySpec, route types.OverlayKind, index int) *errors.CodedError

CrosstabSpecRefusal is the Ref / Scope refusal of the crosstab (MATRIX host) spec at index of Request.Overlays (index < 0 leaves it out of details). route is the kind every decision keys on (the empty route of a hidden kind has no rule); spec.Kind is what message and details name. nil when the spec passes or route has no rule. Judged in order:

  • refEmpty kinds: any Ref arm set → PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE {index, kind}, "must leave Ref empty (<why>)".
  • refMargin kinds: Ref.Margin unset → PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE {index, kind}; an unknown Margin.Axis → the same code, {index, kind, axis}.
  • a scope outside the kind's set → PULSE_OVERLAY_SCOPE_UNSUPPORTED {index, kind, scope}, "(supports: a, b)".

OVERLAY_SHARE_OF_TOTAL's row is its MATRIX dispatch only; its SERIES dispatch keeps its own rule, so call this on a crosstab host only.

func CrosstabSpecScopes 

func CrosstabSpecScopes(kind types.OverlayKind) []types.OverlayScope

CrosstabSpecScopes returns the scopes kind supports on a crosstab host (nil for a kind without a rule).

func DimAxisKeys 

func DimAxisKeys(n int) []types.AxisKey

DimAxisKeys returns the n synthetic dimension keys ["dim_1"], …, ["dim_n"] — each a single-element AxisKey, so a renderer reads them exactly like a one-grouper host axis. n <= 0 returns an empty, non-nil slice (a matrix payload with no columns still marshals its column_keys as []).

func FacetSpecRefusal 

func FacetSpecRefusal(spec *types.OverlaySpec, route types.OverlayKind, index int) *errors.CodedError

FacetSpecRefusal is the Ref / Scope / Level contract of a FACET-host spec (FacetRequest.Overlays, the four population-comparison kinds), shared by predict (descriptor.validateFacetOverlaySpec) and the runtime FACET loop (service.applyFacetOverlays), both right after the wrong-slot refusal and before the host-field and population work, so both raise the same code, message and details. Before it the runtime checked only that Ref.Population.Cohort was set (in other words): an unsupported scope, a foreign Ref arm or a non-zero Level / Within predict refused ran silently. nil when spec passes, or when route is outside the catalog (the slot's unknown-kind gate owns it) or does not run on the FACET slot (the wrong-slot refusal owns it). Judged in order:

  • any Ref arm but Population set → PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE {index, kind};
  • Ref.Population unset, then Ref.Population.Cohort empty → the same;
  • a scope other than group → PULSE_OVERLAY_SCOPE_UNSUPPORTED {index, kind, scope};
  • Level or Within non-zero → PULSE_OVERLAY_LEVEL_OUT_OF_RANGE {index, kind, level, within};
  • a set `weight` (a field name or a {field, kind} object) → PULSE_WEIGHT_UNSUPPORTED {slot: "overlays[i]", operator, field, reason}: facets are never weighted, so the weight used to be ignored silently. An absent weight and `null` (the explicit "run unweighted" opt-out — what a facet does anyway) pass.

func GroupSummaryParts 

func GroupSummaryParts() []string

GroupSummaryParts lists the OVERLAY_MATRIX_GROUP_SUMMARY part names in emission order.

func HostRequiredRefusal 

func HostRequiredRefusal(spec *types.OverlaySpec, route types.OverlayKind, grouped bool, index int) *errors.CodedError

HostRequiredRefusal is the refusal of the Request.Overlays spec at index whose kind's Process host is absent: PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE,

  • a MATRIX kind: "overlay K requires a MATRIX host (Request.Crosstab); none present", details {index, kind}, plus axis (Ref.Margin.Axis) for an axis-margin kind;
  • a SERIES kind: "overlay K requires a SERIES host (grouped Process result: Request.Groups and Request.Aggregations non-empty, Request.Crosstab nil)", details {index, kind};
  • OVERLAY_SHARE_OF_TOTAL on a request with groups (its SERIES dispatch): "overlay K SERIES dispatch requires a SERIES host (…)", details {index, kind, host: "series"}.

route keys the decision (nil for a kind without a rule — the empty route of a hidden kind included); spec.Kind is what message and details name. grouped is len(Request.Groups) > 0. Predict's per-kind validators raise it as their host guard; ScalarSpecRefusal raises it after the kind's Ref / Scope table.

func JudgedShape 

func JudgedShape(authored types.OverlayShape, matrices bool, route types.OverlayKind) types.OverlayShape

JudgedShape is the Process host shape a Request.Overlays spec whose kind routes to route is judged against, given the request's authored shape (crosstab MATRIX, grouped-with-aggregations SERIES, else SCALAR) and whether it carries Request.Matrices. A request with matrices and no crosstab offers the MATRIX_RESULT host beside its authored one: a MATRIX_RESULT kind is judged against it, and so is every other kind over a SCALAR authored shape (a crosstab or series kind on a matrices-only request is refused, not silently run on nothing). A SERIES kind on a grouped request that also carries matrices keeps its SERIES host. Predict (ValidateOverlays) and every runtime hook judge by it.

func MarkovArityRefusal 

func MarkovArityRefusal(kind types.OverlayKind, rowGroupers, columnGroupers, index int) *errors.CodedError

MarkovArityRefusal refuses a host whose row and column axes carry a different number of groupers — their keys can never name the same states (PULSE_OVERLAY_MATRIX_NOT_SQUARE, details {kind, row_groupers, column_groupers} plus index when >= 0). Predict judges the request's crosstab axes, runtime the host's axis headers.

func MarkovDefaultSteps 

func MarkovDefaultSteps() []int

MarkovDefaultSteps is params.steps when omitted.

func MarkovKeySetRefusal 

func MarkovKeySetRefusal(kind types.OverlayKind, rowOnly, columnOnly []string, index int) *errors.CodedError

MarkovKeySetRefusal refuses a host whose row and column key sets differ (runtime only: predict reads no record) once the handler has synthesized the column-only states declared in params.absorbing — PULSE_OVERLAY_MATRIX_NOT_SQUARE, details {kind, row_only, column_only} (sorted state names) plus index when >= 0. nil when both lists are empty.

func MarkovStateName 

func MarkovStateName(key types.AxisKey) string

MarkovStateName is the name a params key (absorbing, initial) uses for a host axis key, and the identity the row and column axes are aligned by: a one-element string key is the string itself; any other key is its JSON encoding (a number 3 → "3", a two-grouper key ["a","b"] → `["a","b"]`).

func MarkovStateRefusal 

func MarkovStateRefusal(kind types.OverlayKind, param string, unknown, states []string, index int) *errors.CodedError

MarkovStateRefusal refuses a params key (absorbing, initial) that names no host state (runtime only) — PULSE_OVERLAY_PARAM_MISSING, details {kind, param, unknown (sorted), states} plus index when >= 0. nil when unknown is empty.

func MatrixResultRefusal 

func MatrixResultRefusal(req *types.Request, spec *types.OverlaySpec, route types.OverlayKind, index int) *errors.CodedError

MatrixResultRefusal judges the Request.Overlays spec at index whose kind routes to route, when route runs on the MATRIX_RESULT host (any other route: nil). Predict (descriptor.ValidateOverlays) and the runtime dispatcher (processing.ApplyMatrixResultOverlays) both call it after the slot and shape refusals, so the refusal — code, message and Details — is identical on both sides. First hit wins:

  • PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE: Ref.Matrix unset or empty, or another Ref arm populated.
  • PULSE_OVERLAY_SCOPE_UNSUPPORTED: Scope other than matrix.
  • PULSE_OVERLAY_LEVEL_OUT_OF_RANGE: a non-zero Level / Within (no crosstab axis to address).
  • PULSE_OVERLAY_PARAM_MISSING: any params (the kind takes none).
  • PULSE_OVERLAY_REFERENCE_UNKNOWN (which "matrix"): Ref.Matrix.Name names no Request.Matrices spec's effective name.
  • PULSE_OVERLAY_GROUPS_REQUIRED: the request carries no Request.Groups (one result: nothing to summarize across).

func MaxCorrespondenceDimensions 

func MaxCorrespondenceDimensions(rows, cols int) int

MaxCorrespondenceDimensions is the number of non-trivial dimensions of an rows × cols table: min(rows, cols) − 1 (0 below 2 × 2).

func NonnegativeCellRefusal 

func NonnegativeCellRefusal(kind types.OverlayKind, cellType types.AggregationType, index int) *errors.CodedError

NonnegativeCellRefusal refuses a non-negative-mass overlay kind over a crosstab whose cell aggregation is neither AGG_COUNT nor AGG_SUM — PULSE_OVERLAY_NONNEGATIVE_REQUIRED, details {kind, aggregation, slot: "crosstab.cell"} plus index when >= 0. A nil cell or an empty type (not yet known) passes.

func NonnegativeValueRefusal 

func NonnegativeValueRefusal(kind types.OverlayKind, row, column types.AxisKey, v float64) *errors.CodedError

NonnegativeValueRefusal refuses a negative or non-finite host cell value (runtime only: predict reads no record) — PULSE_OVERLAY_NONNEGATIVE_REQUIRED, details {kind, row, column, value}; value is null on the wire when it is not finite. nil when v is a finite non-negative number.

func PartsRefusal 

func PartsRefusal(layer *types.OverlayLayer, index int) *errors.CodedError

PartsRefusal judges a handler-built layer's OverlayPayload.Parts: every part has a non-empty name, is non-nil, declares one of the three payload shapes and carries no Parts of its own (parts never nest). A layer with no parts passes. The violation is the handler's, never the caller's — no request can author a part — so it is PROCESSING_INTERNAL, raised by every overlay dispatcher right after a handler returns. Parts are judged in name order so the refusal is deterministic.

func PopulationVarianceCell 

func PopulationVarianceCell(t types.AggregationType) bool

PopulationVarianceCell reports whether a built-in crosstab cell type emits the POPULATION variance m2 / n under its `variance` component key: AGG_VARIANCE and AGG_STDDEV. AGG_WELFORD emits the sample variance m2 / (n - 1) the moment pairwise kinds (OVERLAY_PAIRWISE_WELCH_T / _TWO_MEANS_Z) are defined on, so their leg reader (processing.CrosstabHostView.MeanLeg) converts an unweighted population cell with SampleVariance; a weighted cell's variance is recomputed from m2 and N* either way. A component schema cannot declare which variance it carries, so an extension cell is read as is: it must expose the sample variance.

func ProcessSpecRefusal 

func ProcessSpecRefusal(shape types.OverlayShape, spec *types.OverlaySpec, route types.OverlayKind, grouped bool, index int) *errors.CodedError

ProcessSpecRefusal is the Ref / Scope refusal of the Request.Overlays spec at index judged on a Process host of shape: the crosstab table on a MATRIX host, the SERIES table on a SERIES host, the SCALAR host rule (ScalarSpecRefusal: nothing runs there; grouped is len(Request.Groups) > 0) on a SCALAR host, nil on a MATRIX_RESULT host (it owns its own rule, MatrixResultRefusal). The chain pre-pass calls it per stage.

func RakeKeyName 

func RakeKeyName(key types.AxisKey) string

RakeKeyName is the name a target map uses for a host axis key: a one-element string key is the string itself; any other key is its JSON encoding (the same identity OVERLAY_MARKOV aligns states by).

func RakeKeyRefusal 

func RakeKeyRefusal(kind types.OverlayKind, axis string, targetOnly, hostOnly []string, index int) *errors.CodedError

RakeKeyRefusal refuses an axis whose target keys and host keys differ — PULSE_OVERLAY_RAKE_TARGET_MISMATCH, details {kind, reason: "keys", axis, target_only, host_only} (sorted; never null) plus index when >= 0. nil when both lists are empty. Predict passes the target keys a categorical dictionary cannot hold (host_only empty); runtime passes both sides of the observed host axis.

func RakeTargetSum 

func RakeTargetSum(targets map[string]float64) float64

RakeTargetSum sums a target map in sorted key order, so predict and runtime see the same rounding.

func RakeTotalsRefusal 

func RakeTotalsRefusal(kind types.OverlayKind, rowTotal, columnTotal, tolerance float64, index int) *errors.CodedError

RakeTotalsRefusal refuses counts targets whose row total and column total differ by more than tolerance relative to the larger — PULSE_OVERLAY_RAKE_TARGET_MISMATCH, details {kind, reason: "totals_differ", row_total, column_total} plus index when >= 0. nil when they agree.

func ReadsCellValue 

func ReadsCellValue(kind types.OverlayKind) bool

ReadsCellValue reports whether kind, on a MATRIX Process host, reads the crosstab cell aggregation's VALUE — the one number per cell and per margin (CellAt / MarginFor): the share / index / delta / z-score vs-margin kinds, the χ², Fisher, STD_RESIDUAL, CORRESPONDENCE, MARKOV, RAKE, SYMMETRY and RETENTION kinds (cell values as observed counts), the proportion pairwise kinds (OVERLAY_PAIRWISE_PROP_Z / _PROBIT_T: the cell value as a proportion) and OVERLAY_FORMULA (`cell`, the margins and their SDs). The moment pairwise kinds (types.PairwiseKindUsesWelford, PairwiseKindUsesWeightedMoments) read only the cell's component moments and counts, never its value, and are false; so is every kind that does not run on a MATRIX host. The categorical-code overlay rule refuses a value-reading kind over a crosstab whose cell is a code; processing's TestOverlayReadsCellValue_MatchesHandlers pins this to what each MATRIX handler reads.

func Refusal 

func Refusal(host Host, kind, route types.OverlayKind, index int) *errors.CodedError

Refusal returns the wrong-slot refusal for the spec at index on host, or nil when the slot runs it. route is the kind every decision keys on (the authored kind, or the empty route of a hidden kind, which is never refused here); kind is the authored kind the message and Details name.

Code PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, Details {index, kind, host, hosts}: host is the slot it was authored on, hosts every slot it runs on.

func ResolveStageRef 

func ResolveStageRef(ref types.StageRef, count int, named map[string]int, target bool, index int) (int, *errors.CodedError)

ResolveStageRef resolves a whole-chain overlay StageRef (Ref, or Target when target is set) against count stages and the stage-name table named (empty names absent; last write wins) for the spec at index. Code PULSE_OVERLAY_TARGET_UNKNOWN for a Target, PULSE_OVERLAY_REFERENCE_UNKNOWN for a Ref; details {index, which} plus the named extras. Judged in order:

  • Index and Name both set → refused;
  • neither set → a Target defaults to the last stage (refused when there is none); a Ref is refused;
  • Index outside [0, count) → refused {…, stage_index, stages_count};
  • Name not in named → refused {…, stage_name}.

func RollingWindowFloorRefusal 

func RollingWindowFloorRefusal(spec *types.OverlaySpec, route types.OverlayKind, window, index int) *errors.CodedError

RollingWindowFloorRefusal refuses a positive window below RollingWindowMin(route) — PULSE_OVERLAY_LEVEL_OUT_OF_RANGE, Details {kind, param: "window", window, min} plus index when index >= 0. nil when window meets the floor; a non-positive window is the caller's own "must be > 0" refusal, judged first.

func RollingWindowMin 

func RollingWindowMin(route types.OverlayKind) int

RollingWindowMin is the smallest Params["window"] route accepts: 2 for OVERLAY_ZSCORE_VS_ROLLING, else 1.

func RunsOnMatrixResult 

func RunsOnMatrixResult(kind types.OverlayKind) bool

RunsOnMatrixResult reports whether kind runs on the MATRIX_RESULT Process host (Request.Matrices results).

func SampleVariance 

func SampleVariance(popVariance, m2 float64, hasM2 bool, n float64) float64

SampleVariance is the sample variance of an unweighted cell of n non-null values whose components carry the population variance popVariance and, when hasM2, the second central moment m2: m2 / (n - 1) — bit-identical to AGG_WELFORD's own — or popVariance · n / (n - 1) without m2. Undefined (NaN, JSON null) when n < 2, never 0.

func ScalarSpecKinds 

func ScalarSpecKinds() []types.OverlayKind

ScalarSpecKinds returns every kind ScalarSpecRefusal judges, in no particular order (tests pin it against the Process shape table).

func ScalarSpecRefusal 

func ScalarSpecRefusal(spec *types.OverlaySpec, route types.OverlayKind, grouped bool, index int) *errors.CodedError

ScalarSpecRefusal is the refusal of the Request.Overlays spec at index on a SCALAR Process host — every Process kind is refused there. In order: the Ref / Scope table of the host the kind needs (CrosstabSpecRefusal for a MATRIX kind — none for OVERLAY_FORMULA — SeriesSpecRefusal for a SERIES kind; OVERLAY_SHARE_OF_TOTAL by its dispatch, SERIES when grouped), then HostRequiredRefusal. route, spec.Kind and grouped follow HostRequiredRefusal; nil for a kind without a rule.

func SeriesSpecKinds 

func SeriesSpecKinds() []types.OverlayKind

SeriesSpecKinds returns every kind SeriesSpecRefusal judges, in no particular order (tests pin it against the SERIES shape table).

func SeriesSpecRefusal 

func SeriesSpecRefusal(spec *types.OverlaySpec, route types.OverlayKind, index int) *errors.CodedError

SeriesSpecRefusal is the Ref / Scope refusal of the SERIES-host spec at index of Request.Overlays (index < 0 leaves it out of details). route is the kind every decision keys on (the empty route of a hidden kind has no rule); spec.Kind is what message and details name. nil when the spec passes or route has no rule. Judged in order, every refusal PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE {index, kind} unless noted:

  • a Ref arm the kind does not read is set (every arm is judged);
  • the kind's own arm is required and unset (rolling-mean, YoY, baseline, sibling kinds);
  • Ref.Prior.Lag != 0 ({…, lag}); an empty Ref.Sibling.Field, then Ref.Sibling.Value ({…, field});
  • a scope other than group → PULSE_OVERLAY_SCOPE_UNSUPPORTED {index, kind, scope}.

OVERLAY_SHARE_OF_TOTAL's row is its SERIES dispatch only (its details add host "series"); call this on a SERIES host only.

func ShapeRefusal 

func ShapeRefusal(shape types.OverlayShape, kind, route types.OverlayKind, index int) *errors.CodedError

ShapeRefusal returns the wrong-shape refusal for the Request.Overlays spec at index over a Process host of shape, or nil when kind runs on it. route and kind follow Refusal.

Code PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, Details {index, kind, host, shape, shapes}: host is always "request", shape the host shape authored, shapes every Process shape the kind runs on.

func Shapes 

func Shapes(kind types.OverlayKind) []types.OverlayShape

Shapes returns the Process host shapes kind runs on, or nil for a kind that does not run on Request.Overlays (or is outside the catalog).

func StageRefusal 

func StageRefusal(kind, route types.OverlayKind, stage, index int) *errors.CodedError

StageRefusal refuses a MATRIX_RESULT kind (route) on a ProcessChain stage's own Request.Overlays: the MATRIX_RESULT host reaches a process request and a Compose slot only. Code PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, Details {index, kind, host: "chain", stage}. nil for any other route. Predict (ValidateChain) and the chain runtime share it.

func WelfordCellMessage 

func WelfordCellMessage(kind types.OverlayKind) string

WelfordCellMessage is the PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE message of a moment pairwise kind (types.PairwiseKindUsesWelford) over a crosstab whose cells carry no Welford triple {mean, variance, n}. The runtime (processing.runPairwiseOverlay, off the materialised host) and predict (descriptor.validateOverlayPairwise, off the cell type's declared ComponentSchema) raise it with the same text.

Types

type CorrespondenceParams 

type CorrespondenceParams struct {
	Dimensions    int
	Normalization string
}

CorrespondenceParams is a decoded OVERLAY_CORRESPONDENCE params block. Dimensions 0 means omitted (the default, capped by the table); Normalization is never empty after ParseCorrespondenceParams.

func ParseCorrespondenceParams 

func ParseCorrespondenceParams(spec *types.OverlaySpec, index int) (CorrespondenceParams, *errors.CodedError)

ParseCorrespondenceParams decodes spec.Params strictly: only `dimensions` (an integer >= 1) and `normalization` (symmetric | row_principal | column_principal) are accepted. Anything else — an unknown key, a malformed block, a non-integer or < 1 dimensions, an unknown normalization — is PULSE_OVERLAY_PARAM_MISSING (the overlay param-validation code) with details {kind, param, supported?} plus index when index >= 0 (predict knows it, a runtime handler does not).

func (CorrespondenceParams) ResolveDimensions 

func (p CorrespondenceParams) ResolveDimensions(maxDims int) int

ResolveDimensions is the retained dimension count over a table with maxDims non-trivial dimensions: the explicit value, else the default capped at maxDims.

type Host 

type Host string

Host names an overlay slot. 

const (
	// Request is Request.Overlays: a Process host (crosstab MATRIX or
	// grouped SERIES).
	Request Host = "request"
	// Compose is ComposedRequest.Overlays.
	Compose Host = "compose"
	// Chain is ChainRequest.Overlays.
	Chain Host = "chain"
	// Facet is FacetRequest.Overlays.
	Facet Host = "facet"
)

func Hosts 

func Hosts(kind types.OverlayKind) []Host

Hosts returns the slots kind runs on, or nil for a kind outside the catalog (the empty route of a hidden kind included).

func (Host) Slot 

func (h Host) Slot() string

Slot returns the request field the host's overlay specs live on.

type MarkovParams 

type MarkovParams struct {
	// Steps lists the Pⁿ powers to emit (step_<n> parts), in the order
	// given; never empty after ParseMarkovParams.
	Steps []int
	// Absorbing lists the declared absorbing state names (nil when
	// omitted); the absorption_time part rides it.
	Absorbing []string
	// Initial is set when params.initial is present: InitialMargin
	// selects the observed row-margin distribution, otherwise
	// InitialShares holds the key → share map (raw, not normalized).
	Initial       bool
	InitialMargin bool
	InitialShares map[string]float64
}

MarkovParams is a decoded OVERLAY_MARKOV params block.

func ParseMarkovParams 

func ParseMarkovParams(spec *types.OverlaySpec, index int) (MarkovParams, *errors.CodedError)

ParseMarkovParams decodes spec.Params strictly: only `steps` (a non-empty array of distinct integers 1–MarkovMaxStep, at most MarkovMaxStepCount of them), `absorbing` (a non-empty array of distinct non-empty state names) and `initial` ("margin", or a non-empty object of state → finite share >= 0 with a positive sum) are accepted. Anything else is PULSE_OVERLAY_PARAM_MISSING (the overlay param-validation code) with details {kind, param?, ...} plus index when index >= 0. Whether a named state exists is the runtime's call (MarkovStateRefusal): predict reads no record.

type RakeParams 

type RakeParams struct {
	// RowTargets / ColTargets map a host key name (RakeKeyName) to its
	// raw target (a share or a count, per TargetsAs).
	RowTargets map[string]float64
	ColTargets map[string]float64
	// TargetsAs is RakeTargetsShares or RakeTargetsCounts.
	TargetsAs string
	MaxIter   int
	Tolerance float64
}

RakeParams is a decoded OVERLAY_RAKE params block.

func ParseRakeParams 

func ParseRakeParams(spec *types.OverlaySpec, index int) (RakeParams, *errors.CodedError)

ParseRakeParams decodes spec.Params strictly: `row_targets` and `col_targets` (required, each a non-empty object of key → finite value >= 0 with a positive sum), `targets_as` ("shares" default | "counts"), `max_iter` (an integer 1–RakeMaxMaxIter, default 100) and `tolerance` (finite, > 0 and < 1, default 1e-8). Anything else is PULSE_OVERLAY_PARAM_MISSING with details {kind, param?, ...} plus index when index >= 0. Counts targets whose row and column totals differ by more than the tolerance (relative) are PULSE_OVERLAY_RAKE_TARGET_MISMATCH (RakeTotalsRefusal) — a params-only rule, so predict and runtime raise it alike. Whether a target key exists on the host is RakeKeyRefusal's call.

type RetentionParams 

type RetentionParams struct {
	// Absorbing lists the named absorbing states a move into counts as
	// churn (nil when omitted: no churn split, switch = 1 − stay).
	Absorbing []string
}

RetentionParams is a decoded OVERLAY_RETENTION params block.

func ParseRetentionParams 

func ParseRetentionParams(spec *types.OverlaySpec, index int) (RetentionParams, *errors.CodedError)

ParseRetentionParams decodes spec.Params strictly: only `absorbing` (a non-empty array of distinct non-empty state names, OVERLAY_MARKOV's form) is accepted. Anything else is PULSE_OVERLAY_PARAM_MISSING with details {kind, param?, ...} plus index when index >= 0.

type SymmetryParams 

type SymmetryParams struct {
	// Correct applies Edwards' continuity correction to a 2 × 2 table
	// (McNemar): (|n_12 − n_21| − 1)². Default true, R's
	// mcnemar.test(correct = TRUE); inert on a k × k table (Bowker).
	Correct bool
}

SymmetryParams is a decoded OVERLAY_SYMMETRY params block.

func ParseSymmetryParams 

func ParseSymmetryParams(spec *types.OverlaySpec, index int) (SymmetryParams, *errors.CodedError)

ParseSymmetryParams decodes spec.Params strictly: only `correct` (a JSON boolean) is accepted. Anything else is PULSE_OVERLAY_PARAM_MISSING with details {kind, param?, ...} plus index when index >= 0.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.