Help us shape the future of Go! Take the 2026 Go Developer Survey

overlayhost

package
v1.0.0-alpha.21 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: MIT Imports: 9 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 MinPeriodsParam = "min_periods"

MinPeriodsParam is the params key of the rolling warm-up.

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 BaselineIndexOutOfRange 

func BaselineIndexOutOfRange(kind types.OverlayKind, index, position, seriesLength int) *errors.CodedError

BaselineIndexOutOfRange is the refusal of a SERIES baseline-index kind (OVERLAY_INDEX_VS_BASELINE, OVERLAY_DELTA_VS_BASELINE) whose Ref.BaselineIndex.Position is outside a host series of seriesLength rows: PULSE_OVERLAY_REF_UNKNOWN {index, kind, baseline_index, series_length}, shared by predict (internal/descriptor, when every grouper bounds the series length by its dictionary; series_length then carries the bound) and the runtime resolver (processing.ResolveBaselineIndexFor, off the materialised host) so both raise the same code, message and details. An empty kind (the kind-free resolver) omits the kind from the message and details; a negative index omits Details.index (the runtime handler, whose dispatcher stamps it).

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 EffectivePairwisePSource 

func EffectivePairwisePSource(pSource string, mode types.CrosstabNormalize) string

EffectivePairwisePSource is the proportion-leg reading a pairwise proportion kind applies: the explicit p_source when set, else — the omitted default — cell_value on a normalised host (every cell is already a 0..1 share; dividing it by 100 would score the pair silently wrong, survey-tables E1-S3) and cell_value_pct otherwise. mode is the host crosstab's NormalizeOrDefault. The runtime (processing.runPairwiseOverlay) reads through it; predict's refusal below is its other half.

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 HeaderGrouperCount 

func HeaderGrouperCount(h types.AxisHeader) int

HeaderGrouperCount is the number of groupers behind a materialised axis header: its field count, except the implicit Total column, whose synthetic position stands for no grouper. The square-host arity rule (MarkovArityRefusal) counts groupers, so predict's len(CrosstabSpec.Columns) and runtime's header agree on zero.

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 MeasureHostRefusal 

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

MeasureHostRefusal refuses, on a multi-measure crosstab (types.CrosstabSpec.Cells, U47 #326), every overlay kind outside the pairwise family. The pairwise kinds run per measure against each measure's own single-measure host and fold into one layer, so a pair never crosses measures; every other kind reads the host matrix as one table — its margins, its grand total, its rows as one population — and on a MEASURE-folded payload that table mixes measures, so it is refused up front rather than computed over rows that are not one population. Predict (descriptor.ValidateOverlays) and runtime (processing.refuseWrongHostOverlays) both raise it ahead of any handler. route is the kind the rule keys on (an extension routed onto a pairwise kind runs; a hidden kind, route "", is left to its slot's unknown-kind branch); messages name the authored kind. nil when the kind runs.

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 PairwiseCountCell 

func PairwiseCountCell(t types.AggregationType) bool

PairwiseCountCell reports whether a BUILT-IN crosstab cell type's value is a count — of records, of a label, of distinct values, or the sum of a field (a sum of a 0/1 indicator is its count) — which the omitted p_source of a proportion pairwise kind keeps reading as cell_value_pct on an unnormalised host. Every other built-in is a statistic of its field (a mean, a quantile, a spread, a ratio), not a count or a percentage.

func PairwiseMeanCellRefusal 

func PairwiseMeanCellRefusal(kind types.OverlayKind, pSource string, mode types.CrosstabNormalize, cellType types.AggregationType) string

PairwiseMeanCellRefusal is the PULSE_OVERLAY_PARAM_MISSING message of a proportion pairwise kind whose p_source is OMITTED on an UNNORMALISED host whose cell is a built-in statistic of its field (not PairwiseCountCell) — "" when the pair is fine (survey-tables E4-S6). The omitted default there reads each cell as a 0..100 percentage (÷100), so a mean cell — AGG_AVERAGE of a 0/1 indicator, 0.86 read as 0.0086 — scored every pair silently wrong. An explicit p_source states the reading and is never refused here; an empty cell type (a caller-built host) or an extension type is not judged. The runtime (processing.pairwiseGate, per measure on a multi-measure host) and predict (descriptor.validateOverlayPairwise) raise it with this text and details {kind, param, cell_type}.

func PairwisePSourceRefusal 

func PairwisePSourceRefusal(kind types.OverlayKind, pSource string, mode types.CrosstabNormalize) string

PairwisePSourceRefusal is the PULSE_OVERLAY_PARAM_MISSING message of an EXPLICIT p_source cell_value_pct on a normalised host ("" when the pair is fine): the selector divides a 0..1 share by 100. The runtime (processing.runPairwiseOverlay) and predict (descriptor.validateOverlayPairwise) raise it with this text and details {kind, param, p_source, normalize}.

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 PriorColumnsRefusal 

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

PriorColumnsRefusal refuses a prior-period kind over a crosstab that HAS a column grouper: the kind's periods are the row keys of the one implicit Total column (crosstab.columns omitted), so a real column axis has no single series to walk. PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, details {index, kind, reason: "column_grouper"}. nil for every other kind. route keys the decision; kind is what message and details name.

func PriorComponentsRequiredMessage 

func PriorComponentsRequiredMessage(kind types.OverlayKind) string

PriorComponentsRequiredMessage is the PULSE_OVERLAY_COMPONENTS_REQUIRED message of a prior-period kind over a host built with components disabled: every leg's n (and the T / Z moments) is read off them.

func PriorLevelWithinMessage 

func PriorLevelWithinMessage(kind types.OverlayKind) string

PriorLevelWithinMessage is the PULSE_OVERLAY_LEVEL_OUT_OF_RANGE message of a prior-period kind whose Level or Within is non-zero.

func PriorMeasureBuiltin 

func PriorMeasureBuiltin(t types.AggregationType) bool

PriorMeasureBuiltin reports whether t is a built-in aggregation type (types.AllAggregationTypes): the prior-period measure rule judges a built-in by its type, an extension by its declared schema (predict) or its emitted keys (runtime).

func PriorMeasureRefusal 

func PriorMeasureRefusal(kind, route types.OverlayKind, measure types.AggregationType, index int) *errors.CodedError

PriorMeasureRefusal is the type half of the prior-period measure rule, raised identically by predict and the runtime: a T / Z kind whose scored measure is a built-in outside PriorWelfordMeasure, or the proportion kind whose measure is a built-in other than AGG_AVERAGE, is refused (PriorWelfordRefusal / PriorProportionRefusal). An empty or extension type is not judged here. nil for every other kind.

func PriorNormalizedRefusal 

func PriorNormalizedRefusal(kind, route types.OverlayKind, mode types.CrosstabNormalize, index int) *errors.CodedError

PriorNormalizedRefusal refuses the proportion prior-period kind over a NORMALISED crosstab: every cell is then a share of a base the periods share, so the two legs are not independent samples. PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, details {index, kind, normalize}. nil for any other kind or an unnormalised host (mode "" or none).

func PriorProportionMeasure 

func PriorProportionMeasure(t types.AggregationType) bool

PriorProportionMeasure reports whether a BUILT-IN aggregation type's value is a proportion a prior-period proportion leg reads: AGG_AVERAGE (of a 0/1 indicator — p̂ is the mean, the weighted mean when weighted). An extension type is admitted and judged per period at runtime (a value outside [0, 1] skips as PULSE_STATS_SKIP_PROPORTION_INVALID).

func PriorProportionRefusal 

func PriorProportionRefusal(kind types.OverlayKind, measure types.AggregationType, index int) *errors.CodedError

PriorProportionRefusal refuses the proportion prior-period kind whose scored measure is a built-in other than AGG_AVERAGE: PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, details {index, kind, measure_type}.

func PriorTestKind 

func PriorTestKind(route types.OverlayKind) bool

PriorTestKind reports whether route is one of the three inferential prior-period kinds.

func PriorTestUsesWelford 

func PriorTestUsesWelford(route types.OverlayKind) bool

PriorTestUsesWelford reports whether route reads the Welford triple {mean, variance, n} (the T and Z kinds); the proportion kind reads the measure's value and its floor's n.

func PriorWelfordMeasure 

func PriorWelfordMeasure(t types.AggregationType) bool

PriorWelfordMeasure reports whether a BUILT-IN aggregation type's components carry the Welford triple a T / Z prior-period leg reads: AGG_WELFORD (the sample variance), AGG_VARIANCE and AGG_STDDEV (the population variance, converted with SampleVariance). It is the set of built-ins whose declared ComponentSchema carries both `mean` and `variance` (pinned by a descriptor test); an extension type is judged by its declared schema (predict) and its emitted keys (runtime).

func PriorWelfordRefusal 

func PriorWelfordRefusal(kind types.OverlayKind, measure types.AggregationType, index int) *errors.CodedError

PriorWelfordRefusal refuses a T / Z prior-period kind whose scored measure carries no Welford triple: PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE, details {index, kind, measure_type}.

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 RollingMinPeriods 

func RollingMinPeriods(spec *types.OverlaySpec, route types.OverlayKind, params map[string]any, window, index int) (int, *errors.CodedError)

RollingMinPeriods resolves params.min_periods for a rolling kind whose window has already passed its own checks: absent → window; present → an integer in [RollingWindowMin(route), window], else PULSE_OVERLAY_LEVEL_OUT_OF_RANGE with Details {kind, param: "min_periods", min_periods, min, max} plus index when index >= 0. params is the decoded params object (a JSON number arrives float64).

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 (ValidateChainWithOptions) and the chain runtime share it.

func TotalColumnRefusal 

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

TotalColumnRefusal refuses, on a crosstab with no column grouper, a kind whose handler needs a contingency of at least two columns: the χ² matrix / per-row tests, the adjusted residuals and correspondence analysis. Their runtime handlers refuse a one-column host from the materialised counts (PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE); the implicit Total column is one column by construction, so predict refuses it up front with the same code and both sides raise this refusal ahead of the handler. route is the kind the rule keys on (an extension routed onto one of them counts); messages name the authored kind. nil for every other kind.

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.