model

package
v1.0.0-alpha.15 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package model is the one bound-model namespace: the in-memory form of a fitted regression a request reads by name, the set those names resolve in, and the structural rules a ComposedRequest `fits` list must satisfy.

It is a leaf over the standard library plus types and errors (TestModel_ImportBoundary), so the runtime (internal/service, the engine) and the no-execute predict path (internal/descriptor) share ONE rule set and ONE resolver — predict refuses exactly what the runtime refuses, with the same code, message and details.

Index

Constants

View Source 
const (
	// StatPoint is the coefficient (REG_BAYES_LINEAR: the posterior
	// mean). The default.
	StatPoint = "point"
	// StatLower is the coefficient's lower confidence bound.
	StatLower = "lower"
	// StatUpper is the coefficient's upper confidence bound.
	StatUpper = "upper"
	// StatSE is the coefficient's standard error.
	StatSE = "se"
)

The stat values coef() reads (its optional third argument).

View Source 
const (
	ReasonSavePathEmpty   = "path_empty"
	ReasonSaveSuffix      = "suffix"
	ReasonSaveEscapesRoot = "escapes_root"
	ReasonSaveNameMissing = "name_missing"
)

The PULSE_MODEL_SAVE_INVALID reasons.

View Source 
const (
	ReasonFileJSON           = "json"
	ReasonFileVersionMissing = "version_missing"
	ReasonFileSchema         = "schema"
)

The PULSE_MODEL_FILE_INVALID reasons.

View Source 
const (
	ReasonNameMissing     = "name_missing"
	ReasonRequestMissing  = "request_missing"
	ReasonRegressionCount = "regression_count"
	ReasonGrouped         = "grouped"
	// ReasonKindAmbiguous: a fit request holding a regression AND a
	// vector battery (a fit is one kind).
	ReasonKindAmbiguous = "kind_ambiguous"
	// ReasonVectorCount: more than one vector battery.
	ReasonVectorCount = "vector_count"
	// ReasonVectorSource: a battery whose fold has no single listwise
	// state (params.missing pairwise, MAT_DISTANCE's per-group
	// centroids) or folds transformed values (MAT_RELIABILITY
	// params.reverse).
	ReasonVectorSource = "vector_source"
)

The PULSE_FIT_INVALID reasons.

View Source 
const (
	SlotFits   = "fits"
	SlotModels = "models"
)

The Source slots.

View Source 
const (
	ReasonFileMissing    = "missing"
	ReasonFileUnreadable = "unreadable"
)

The PULSE_MODEL_FILE_UNREADABLE reasons.

View Source 
const (
	// ScaleResponse scores a GLM on the response scale: the inverse link
	// of the linear predictor (the fit's own fitted means). The default.
	ScaleResponse = "response"
	// ScaleLink scores a GLM on the link scale: the linear predictor.
	ScaleLink = "link"
)

Scale values of ATTR_REG_PREDICT's params.scale (REG_GLM only).

View Source 
const (
	ReasonParamsInvalid   = "params_invalid"
	ReasonFitMissing      = "fit_missing"
	ReasonSlotFields      = "slot_fields"
	ReasonTermsEmpty      = "terms_empty"
	ReasonTermDuplicate   = "term_duplicate"
	ReasonScaleUnknown    = "scale_unknown"
	ReasonScaleNotGLM     = "scale_not_glm"
	ReasonTypeUnsupported = "type_unsupported"
	ReasonBoundUnknown    = "bound_unknown"
	ReasonBoundTerms      = "bound_terms"
)

The PULSE_MODEL_SCORE_INVALID reasons.

View Source 
const (
	// BoundPoint scores with the coefficient itself. The default.
	BoundPoint = "point"
	// BoundLower scores with the coefficient's lower confidence bound
	// (RegressionResult.CILower) — single-term only.
	BoundLower = "lower"
	// BoundUpper scores with the coefficient's upper confidence bound
	// (RegressionResult.CIUpper) — single-term only.
	BoundUpper = "upper"
)

Bound values of ATTR_REG_PREDICT's params.bound: which coefficient figure a single-term score multiplies its column by.

View Source 
const CoefFunc = "coef"

CoefFunc is the expression function that reads a bound model's figures: coef(fit, term[, stat]) in ATTR_FORMULA and FILTER_EXPRESSION.

View Source 
const FileFormatVersion = 2

FileFormatVersion is the newest model_format_version this build writes. The version is a function of the content, never a flag (the .pulse header's rule): a fit whose standard errors came from a robust RegressionSpec.Covariance writes 2 — version 1 plus the `covariance` echo — and every other fit writes 1, byte-identical to the files earlier builds wrote. Both stay readable (FileFormatVersions).

View Source 
const FileSuffix = ".pulse-model.json"

FileSuffix is the model file name suffix every save path carries. The label- and range-table directory loaders skip it (a model file beside a table is not a table).

View Source 
const InterceptKey = "(intercept)"

InterceptKey is the RegressionResult.Coefficients / StdErrors key of the intercept term (the engine's synthesized "(intercept)").

View Source 
const PopulationFormatVersion = 1

PopulationFormatVersion is the newest population_format_version this build writes and reads.

View Source 
const PopulationSuffix = ".pulse-population.json"

PopulationSuffix is the population file name suffix every vector-fit save path and every `populations` entry carries. The label- and range-table directory loaders skip it (a population file beside a table is not a table).

View Source 
const ReasonRefNameEmpty = "name_empty"

The PULSE_MODEL_REF_INVALID reasons beyond the shared path reasons (ReasonSavePathEmpty, ReasonSaveSuffix, ReasonSaveNameMissing, ReasonSaveEscapesRoot — the one model-file path rule).

View Source 
const ReasonSaveDuplicate = "duplicate"

ReasonSaveDuplicate is the PULSE_MODEL_SAVE_INVALID reason of a second save naming a file an earlier save in the same tree writes.

View Source 
const SlotPopulations = "populations"

SlotPopulations is the Source slot of a `populations` entry.

View Source 
const SlotRegistered = "registered"

SlotRegistered is the Source slot of a registered population.

Variables

This section is empty.

Functions

func CheckChainModels 

func CheckChainModels(stages []*types.ChainStage, outer Catalog) *errors.CodedError

CheckChainModels is the chain pre-pass rule, run by the runtime before the cohort opens and by PredictChain: every stage's `models` and `populations` (CheckRefs against outer — the instance's registered populations, nil for none; each stage its own namespace above it; details.stage). A chain writes no model file — the chain gate refuses a regression on every stage (PULSE_CHAIN_NOT_MERGEABLE), stage 0 before it runs — so its saves need no rule here.

func CheckCoef 

func CheckCoef(cat Catalog, fit, term, stat string) *errors.CodedError

CheckCoef is the static rule over one coef(fit, term, stat) call — what can be judged from the names alone, so the runtime (every call) and predict (every all-literal call) refuse the same call the same way. In order: fit resolves in cat (PULSE_MODEL_UNKNOWN), term is InterceptKey or one of the fit's terms (PULSE_MODEL_TERM_UNKNOWN), stat is one of CoefStats (PULSE_MODEL_STAT_UNKNOWN). The first fault wins. Whether the fit reports the stat is the runtime's call (Coef): predict cannot see a fit's numbers.

func CheckComposeBatch 

func CheckComposeBatch(fits []types.FitSpec, requests []*types.Request, outer Catalog) *errors.CodedError

CheckComposeBatch is the Compose pre-pass rule, run right after CheckFits by the runtime (serial and parallel, before any fit or slot runs) and by PredictCompose, in this order, the first fault winning:

  1. every slot's regression save path (CheckRegressionSaves, details.request = the slot index) — the fits' own were CheckFits';
  2. the uniqueness of every save in the batch — fits[i], fits[i].request.regressions[j], requests[k].regressions[j] (CheckSaveDuplicates);
  3. every fit's name against outer — the instance's registered populations (PULSE_MODEL_NAME_COLLISION, details.fit);
  4. every fit request's `models` and `populations` (CheckRefs against outer alone — a fit runs before the batch binds; details.fit);
  5. every slot's `models` and `populations` against the fits' names layered over outer (CheckRefs, details.request).

requests are the effective slots (sweep slots included). outer is what every request sees bound before its own entries — the instance's registered populations; nil for none.

func CheckFits 

func CheckFits(fits []types.FitSpec) error

CheckFits is the structural rule set over a ComposedRequest `fits` list, run by the runtime (before any fit or slot runs) and by PredictCompose alike, so both refuse the same batch with the same error. Entries are judged in order, each fully before the next; the first fault wins:

  • an empty name — PULSE_FIT_INVALID name_missing
  • no request — PULSE_FIT_INVALID request_missing
  • a regression AND a vector battery — PULSE_FIT_INVALID kind_ambiguous
  • more than one vector battery — PULSE_FIT_INVALID vector_count
  • no battery, or more than one regression — PULSE_FIT_INVALID regression_count
  • groups or a crosstab — PULSE_FIT_INVALID grouped
  • a vector battery with no single listwise state (VectorSourceRefusal) — PULSE_FIT_INVALID vector_source
  • an invalid `save` path (CheckSavePath on a regression fit's own and its regression's, CheckPopulationSavePath on a vector fit's) — PULSE_MODEL_SAVE_INVALID
  • a name an earlier entry already binds — PULSE_MODEL_NAME_COLLISION

A vector battery is a Matrices spec or a VectorFitAttributeTypes attribute (VectorBatteries). Every refusal carries details.fit (the 0-based entry index) and details.name. Nil for an empty list. Every save path is judged here, before any fit runs, so no fit writes a model or population file in a batch a later entry's path would refuse.

func CheckModelRefs 

func CheckModelRefs(refs []types.ModelRef, outer Catalog) *errors.CodedError

CheckModelRefs is the static rule over a `models` list, judged entry by entry in order, the first fault winning: a blank name (PULSE_MODEL_REF_INVALID name_empty), a path the save-path rule refuses (PULSE_MODEL_REF_INVALID, the path reason), then a name an earlier entry or outer already binds (PULSE_MODEL_NAME_COLLISION, details.sources). outer is what the request already sees bound — a Compose slot's fits; nil for none. No file is read.

func CheckPopulationSavePath 

func CheckPopulationSavePath(p string) *errors.CodedError

CheckPopulationSavePath is the rule over a vector fit's `save` path — CheckSavePath's, with PopulationSuffix: non-blank, a file name ending .pulse-population.json with a stem before it, never above the filesystem root. A violation is PULSE_MODEL_SAVE_INVALID with details.path and details.reason.

func CheckRefs 

func CheckRefs(refs Refs, outer Catalog) *errors.CodedError

CheckRefs is the static rule over a request's loads: its `models` (CheckModelRefs against outer), then its `populations`, entry by entry in order, the first fault winning — a blank name (PULSE_MODEL_REF_INVALID name_empty), a path the population save-path rule refuses (PULSE_MODEL_REF_INVALID, the path reason), then a name a `models` entry, an earlier population or outer already binds (PULSE_MODEL_NAME_COLLISION, details.sources). No file is read.

func CheckRegressionSaves 

func CheckRegressionSaves(regs []*types.RegressionSpec) *errors.CodedError

CheckRegressionSaves applies CheckSavePath to every RegressionSpec that sets Save, in order; the first fault wins and gains details.regression (the 0-based spec index).

func CheckRequestSaves 

func CheckRequestSaves(req *types.Request) *errors.CodedError

CheckRequestSaves is the standalone request's save rule: every regression save path (CheckRegressionSaves), then their uniqueness.

func CheckSaveDuplicates 

func CheckSaveDuplicates(sites []SaveSite) *errors.CodedError

CheckSaveDuplicates refuses the first site whose path (cleaned) an earlier site already writes: PULSE_MODEL_SAVE_INVALID reason duplicate, details.path and details.sites (the earlier site, then this one). Nil when every path is distinct.

func CheckSavePath 

func CheckSavePath(p string) *errors.CodedError

CheckSavePath is the rule over a `save` path, shared by the runtime and predict: non-blank, a file name ending in FileSuffix with a stem before it, and never above the filesystem root (no leading ".." once cleaned). A violation is PULSE_MODEL_SAVE_INVALID with details.path and details.reason. Nil for a valid path.

func CheckScore 

func CheckScore(attr *types.Attribute, cat Catalog) (ScoreParams, Signature, *errors.CodedError)

CheckScore is the one rule over a scoring reference (an ATTR_REG_PREDICT slot), run by the runtime's field-reference pass, the attribute's own bind and predict alike: params decode, the slot carries none of the refit attributes' fields, the fit name resolves in cat, the fit type is scorable, `terms` lists distinct names of the fit's terms (InterceptKey included), `scale` is a GLM-only response|link and `bound` is point|lower|upper, a non-point one with exactly one predictor term. The first fault wins. It does not judge the scoring frame's columns — the caller's field-reference walk does, with PredictorMissing / PredictorNotNumeric over Signature.Terms.

func CheckVectorFit 

func CheckVectorFit(cat Catalog, name string) *errors.CodedError

CheckVectorFit is the static rule over one vector-fit reference (a fitted attribute's or a MAT_* slot's params.fit) against cat — the runtime's Set or predict's FitCatalog, so both refuse the same name the same way: an unbound name is PULSE_MODEL_UNKNOWN listing the bound vector fits; a regression name is PULSE_MODEL_KIND_MISMATCH.

func Coef 

func Coef(set *Set, fit, term, stat string) (float64, *errors.CodedError)

Coef is coef(fit, term, stat) over the request's bound models, at full float64 precision: CheckCoef, then the figure. stat lower / upper on a fit that reports no intervals, or se on one that reports no standard errors, is PULSE_MODEL_INTERVALS_UNAVAILABLE. A figure the fit reports for other terms but not this one — a lasso-dropped predictor's interval, an undefined (df ≤ 0) bound — is NaN, an undefined figure (null on the wire), never 0. A candidate predictor the fit's selection dropped has point coefficient 0 (it scores 0 in ATTR_REG_PREDICT) and NaN for every other stat.

func CoefStats 

func CoefStats() []string

CoefStats are the stats coef() reads, in documentation order.

func DefaultScoreLabel 

func DefaultScoreLabel(attr *types.Attribute) string

DefaultScoreLabel is ATTR_REG_PREDICT's output label when the slot sets none: "ATTR_REG_PREDICT_<fit>" (params unreadable: no suffix).

func FileFormatVersions 

func FileFormatVersions() []int

FileFormatVersions are the model_format_version values this build reads, oldest first.

func FitKindOf 

func FitKindOf(req *types.Request) types.FitKind

FitKindOf is the kind a fit request binds: a regression fit (exactly one non-null regression, no vector battery), a vector fit (no regression, exactly one vector battery), or "" for a request CheckFits refuses.

func FitRequest 

func FitRequest(spec types.FitSpec) *types.Request

FitRequest returns the request a fit runs: a shallow clone of spec.Request with its `return` cleared. The fit's figures surface whole as ComposedResponse.Fits[name] (outside every `return`), and a `return` that skipped the regressions slot would leave nothing to bind. The caller's request is never mutated.

func IntervalsUnavailable 

func IntervalsUnavailable(fit, key, value string) *errors.CodedError

IntervalsUnavailable is the PULSE_MODEL_INTERVALS_UNAVAILABLE refusal: a reference reads a coefficient interval (or standard error) from a fit that reports none. key names the reference's knob — "stat" for coef(), "bound" for ATTR_REG_PREDICT — and value its setting.

func IsVectorFitAttribute 

func IsVectorFitAttribute(t types.AttributeType) bool

IsVectorFitAttribute reports whether t is a VectorFitAttributeTypes entry.

func KindMismatch 

func KindMismatch(name string, expected, kind types.FitKind) *errors.CodedError

KindMismatch is the PULSE_MODEL_KIND_MISMATCH refusal of a reference to name, bound as kind, where a fit of kind expected is read: a regression consumer (ATTR_REG_PREDICT, coef()) naming a vector fit, or a vector consumer (a fitted attribute's or MAT_* slot's params.fit) naming a regression. One namespace, two kinds: details carry name, fit (the same name), kind and expected.

func NameCollision 

func NameCollision(name string, first, second Source) *errors.CodedError

NameCollision is the PULSE_MODEL_NAME_COLLISION refusal of a `models` entry (second) whose name first already binds — details.name and details.sources (both bindings, first then second).

func NamesOfKind 

func NamesOfKind(cat Catalog, kind types.FitKind) []string

NamesOfKind returns cat's bound names of kind, sorted (nil-safe for a nil interface).

func Overwritten 

func Overwritten(p, name string) *errors.CodedError

Overwritten is the PULSE_MODEL_OVERWRITTEN warning: a save replaced an existing file at path.

func PopulationFormatVersions 

func PopulationFormatVersions() []int

PopulationFormatVersions are the population_format_version values this build reads, oldest first.

func PopulationOverwritten 

func PopulationOverwritten(p, name string) *errors.CodedError

PopulationOverwritten is the PULSE_MODEL_OVERWRITTEN warning of a vector fit's save that replaced an existing file at path.

func PopulationWriteFailed 

func PopulationWriteFailed(p, name, stage string, cause error) *errors.CodedError

PopulationWriteFailed is the PULSE_MODEL_WRITE_FAILED refusal of a vector fit's save of population name to path, failed at stage. The target is left as it was.

func PredictorMissing 

func PredictorMissing(fit, column string) *errors.CodedError

PredictorMissing is the PULSE_MODEL_PREDICTOR_MISSING refusal: the scoring frame (schema, feature outputs and earlier attribute labels) has no column for one of fit's predictors.

func PredictorNotNumeric 

func PredictorNotNumeric(fit, column, fieldType string) *errors.CodedError

PredictorNotNumeric is the PULSE_MODEL_PREDICTOR_NOT_NUMERIC refusal: a predictor column of fit is a schema field of a type a regression cannot read (fieldType is its type name).

func ScorableType 

func ScorableType(t types.RegressionType) bool

ScorableType reports whether a fit of type t can be scored: the linear-predictor regressions (REG_OLS — penalties and selection included — REG_GLM, REG_BAYES_LINEAR at its posterior mean).

func StatUnknown 

func StatUnknown(fit, stat string) *errors.CodedError

StatUnknown is the PULSE_MODEL_STAT_UNKNOWN refusal: a coef() stat other than point, lower, upper or se.

func TermUnknown 

func TermUnknown(fit, term string, terms []string) *errors.CodedError

TermUnknown is the PULSE_MODEL_TERM_UNKNOWN refusal: term is neither one of fit's terms nor InterceptKey. available lists the terms a reference may name, intercept first.

func UnknownModel 

func UnknownModel(name string, available []string) *errors.CodedError

UnknownModel is the PULSE_MODEL_UNKNOWN refusal for name against the bound names available — the one constructor the runtime resolver and predict share.

func VectorBatteries 

func VectorBatteries(req *types.Request) int

VectorBatteries counts req's vector batteries: its Matrices specs plus its VectorFitAttributeTypes attributes.

func VectorFitAttributeTypes 

func VectorFitAttributeTypes() []types.AttributeType

VectorFitAttributeTypes are the fitted vector attributes a vector fit request may hold as its battery (the attribute folds the battery's listwise co-moment). ATTR_VEC_DISTANCE is not one: its fit exists only under a fitted metric.

func VectorSourceRefusal 

func VectorSourceRefusal(req *types.Request) (string, map[string]any)

VectorSourceRefusal judges a vector fit request's one Matrices battery (a fitted attribute battery always folds one listwise state): MAT_DISTANCE (per-group centroids, not one state), params.missing "pairwise" (no single listwise state) and a MAT_RELIABILITY params.reverse list (the fold reads reverse-keyed values, not the members') are refused — the message tail and the details; "" when the battery is a valid source. Params are read loosely: a malformed params object is the slot resolution's to refuse.

func WithSet 

func WithSet(ctx context.Context, set *Set) context.Context

WithSet returns ctx carrying set (a nil set leaves ctx unchanged).

func WriteFailed 

func WriteFailed(p, name, stage string, cause error) *errors.CodedError

WriteFailed is the PULSE_MODEL_WRITE_FAILED refusal: the save of model name to path failed at stage (mkdir, create, write, sync, close, rename, stat). The target is left as it was.

Types

type Bound 

type Bound struct {
	// Name is the bound name (the `fits` entry name).
	Name string

	// Type is the regression operator that produced the fit.
	Type types.RegressionType

	// Target is the fit's response field.
	Target string

	// Predictors are the predictor columns in fit order: the spec's
	// predictors, or — under Selection — the predictors the selection
	// retained. The list is authoritative: a scorer never infers a
	// column the fit did not use (an absent one-hot column is the
	// reference level).
	Predictors []string

	// Terms are the predictor columns the fit was offered, in spec
	// order — Predictors without Selection, the candidate superset
	// under it. A scoring reference may name any of them in `terms` (a
	// candidate the selection dropped scores 0) and a scoring frame must
	// hold all of them, so predict, which sees only the spec, judges a
	// reference exactly as the runtime does.
	Terms []string

	// Intercept is the fitted intercept.
	Intercept float64

	// Coefficients are the fitted coefficients aligned with Predictors
	// (REG_BAYES_LINEAR: the posterior mean).
	Coefficients []float64

	// InterceptStdErr is the intercept's standard error (NaN when the
	// fit reports none).
	InterceptStdErr float64

	// StdErrors are the coefficients' standard errors aligned with
	// Predictors (NaN where the fit reports none).
	StdErrors []float64

	// InterceptCILower / InterceptCIUpper are the intercept's
	// confidence bounds and CILower / CIUpper the coefficients' aligned
	// with Predictors, at ConfLevel (RegressionResult.CILower /
	// CIUpper, full precision); NaN where the fit reports none.
	InterceptCILower float64
	InterceptCIUpper float64
	CILower          []float64
	CIUpper          []float64

	// ConfLevel is the intervals' coverage (0 when the fit reports no
	// intervals).
	ConfLevel float64

	// Family and Link are the GLM error family and link ("" otherwise).
	Family string
	Link   string

	// Vcov is the coefficient covariance matrix when the fit computed
	// it (RegressionSpec.Vcov), nil otherwise.
	Vcov *types.MatrixValues

	// Result is the fit's full RegressionResult (shared, read-only).
	Result *types.RegressionResult

	// Source is where the name was bound: a `fits` entry or a `models`
	// entry (the zero value when unknown). A name collision names both
	// bindings' sources.
	Source Source
}

Bound is one fitted regression bound under a name: everything a scorer needs, at full float64 precision, in the fit's own predictor order. Built from the engine's RegressionResult before any rounding (a `return` precision applies to the wire only, never to a Bound).

func Bind 

func Bind(name string, spec *types.RegressionSpec, res *types.RegressionResult) (*Bound, error)

Bind builds the Bound for a finished fit: spec is the regression as the fit ran it, res its result. A coefficient the result lacks for a fitted predictor is an engine invariant violation (PROCESSING_INTERNAL).

func (*Bound) ReportsIntervals 

func (b *Bound) ReportsIntervals() bool

ReportsIntervals reports whether the fit carries coefficient confidence intervals (RegressionResult.ConfLevel set). A fit without standard errors — a degenerate intercept-only GLM — has none.

func (*Bound) ReportsStdErrors 

func (b *Bound) ReportsStdErrors() bool

ReportsStdErrors reports whether the fit carries any standard error.

func (*Bound) Signature 

func (b *Bound) Signature() Signature

Signature is b's static face.

type Catalog 

type Catalog interface {
	// Signature returns name's signature and whether name is bound.
	Signature(name string) (Signature, bool)
	// Names returns the bound names, sorted.
	Names() []string
}

Catalog resolves bound names to their Signatures: the runtime's Set, or predict's FitCatalog. A nil Catalog binds nothing.

func WithinCatalog 

func WithinCatalog(outer Catalog, inner FitCatalog) Catalog

WithinCatalog is inner layered over outer: outer's signatures plus inner's. A nil outer returns inner unchanged (a Compose batch on an instance with no registered populations judges exactly the fits catalog it always did). inner's names never collide with outer's — CheckComposeBatch refuses that first.

type File 

type File struct {
	// ModelFormatVersion is 2 when Covariance is set, else 1.
	ModelFormatVersion int `json:"model_format_version"`
	// Name is the name the model was saved under (informational: a load
	// binds the name the loading request gives it).
	Name string `json:"name"`
	// Type is the regression operator that produced the fit.
	Type types.RegressionType `json:"type"`
	// Family and Link are the GLM error family and link.
	Family string `json:"family,omitempty"`
	Link   string `json:"link,omitempty"`
	// Penalty, Selection and Resample echo the fit's modifiers.
	Penalty   string `json:"penalty,omitempty"`
	Selection string `json:"selection,omitempty"`
	Resample  string `json:"resample,omitempty"`
	// Target is the fit's response field.
	Target string `json:"target"`
	// Predictors are the predictor columns the fit uses, in fit order —
	// under Selection the retained ones only.
	Predictors []string `json:"predictors"`
	// Terms are the predictor columns the fit was offered, in spec
	// order (equal to Predictors without Selection).
	Terms []string `json:"terms"`
	// Coefficients, StdErrors, CILower and CIUpper are the fit's
	// per-term figures.
	Coefficients map[string]Float `json:"coefficients"`
	StdErrors    map[string]Float `json:"std_errors,omitempty"`
	CILower      map[string]Float `json:"ci_lower,omitempty"`
	CIUpper      map[string]Float `json:"ci_upper,omitempty"`
	// DF is the intervals' Student-t degrees of freedom (absent: Wald;
	// null: undefined).
	DF Float `json:"df,omitempty"`
	// ConfLevel is the intervals' coverage (absent: no intervals).
	ConfLevel Float `json:"conf_level,omitempty"`
	// Vcov is the coefficient covariance when the fit computed one.
	Vcov *FileMatrix `json:"vcov,omitempty"`
	// Covariance (version 2 only, and required there) names the robust
	// estimator the standard errors, intervals, df and vcov came from —
	// RegressionResult.Covariance: type, and the cluster field and its
	// level count or the order_by field and resolved lag. Absent: the
	// fit's classical covariance.
	Covariance *types.RegressionCovarianceResult `json:"covariance,omitempty"`
	// NObs, SumWeights and NEff are the fit's sample sizes (the last
	// two present on a weighted fit only).
	NObs       int   `json:"n_obs"`
	SumWeights Float `json:"sum_weights,omitempty"`
	NEff       Float `json:"n_eff,omitempty"`
	// Provenance records where the fit came from. Informational only:
	// a load never compares it with anything.
	Provenance Provenance `json:"provenance"`
}

File is one model file document (model_format_version 1 or 2): the fitted regression's scoring figures at full float64 precision plus informational provenance. Maps are keyed like RegressionResult's (InterceptKey included); a term absent from a map has no figure.

func DecodeFile 

func DecodeFile(source string, data []byte) (*File, error)

DecodeFile parses a model file. The version is read first: absent or not an integer is PULSE_MODEL_FILE_INVALID (reason version_missing / schema), any value outside FileFormatVersions PULSE_MODEL_VERSION_UNSUPPORTED. The document is then decoded strictly — an unknown key, a wrong type or a structural fault (no type or target, a predictor without a coefficient, a predictor outside terms, a malformed vcov, a covariance on a version 1 file or none on a version 2 one, a covariance type outside the robust estimators) is PULSE_MODEL_FILE_INVALID reason schema; malformed JSON reason json. source names the file in messages and details.path.

func LoadModelFiles 

func LoadModelFiles(refs []types.ModelRef, read ReadFunc) ([]*File, *errors.CodedError)

LoadModelFiles reads and decodes every `models` entry in order (the refs passed CheckModelRefs): a read error is PULSE_MODEL_FILE_UNREADABLE (missing / unreadable), a decode fault DecodeFile's PULSE_MODEL_FILE_INVALID / _VERSION_UNSUPPORTED — every refusal gaining details.model (the entry index) and details.name. The first fault wins. The files are index-aligned with refs.

func NewFile 

func NewFile(name string, spec *types.RegressionSpec, res *types.RegressionResult, prov Provenance) (*File, error)

NewFile builds the model file of a finished fit: spec is the regression as the fit ran it, res its full-precision result (never a `return`-rounded one). It holds what Bind needs to rebuild the same Bound — under Selection the retained predictors, with the candidate set as Terms.

func (*File) Bind 

func (f *File) Bind(name string) (*Bound, error)

Bind rebuilds the Bound the saved fit had, under name: the same predictors, terms and figures, bit for bit. Its Result carries the saved figures only (no R² or deviance).

func (*File) Encode 

func (f *File) Encode() ([]byte, error)

Encode writes f as the model file's bytes: indented JSON (map keys sorted, so a file is deterministic) with a trailing newline.

func (*File) Result 

func (f *File) Result() *types.RegressionResult

Result is the RegressionResult the file's figures describe.

type FileMatrix 

type FileMatrix struct {
	Kind       types.MatrixKind     `json:"kind"`
	Encoding   types.MatrixEncoding `json:"encoding"`
	RowKeys    []string             `json:"row_keys"`
	ColumnKeys []string             `json:"column_keys"`
	Labels     []string             `json:"labels,omitempty"`
	Values     [][]Float            `json:"values"`
}

FileMatrix is a model file's matrix (the vcov): MatrixValues with bit-exact floats.

type FitCatalog 

type FitCatalog map[string]Signature

FitCatalog is the static Catalog of a ComposedRequest `fits` list — predict's view of the names the runtime's pre-pass binds. Entries CheckFits would refuse are skipped (that refusal comes first).

func CatalogFromFits 

func CatalogFromFits(fits []types.FitSpec) FitCatalog

CatalogFromFits builds the FitCatalog of fits: a regression fit's signature (type, terms), or a vector fit's (kind vector; members unknown statically — FitKindOf).

func CatalogWithLoaded 

func CatalogWithLoaded(outer Catalog, refs Refs, l *Loaded) FitCatalog

CatalogWithLoaded is predict's WithLoaded: outer's signatures plus every loaded model's (CatalogWithModels) and every loaded population's — kind vector, its member labels — under its entry's name. outer may be nil.

func CatalogWithModels 

func CatalogWithModels(outer Catalog, refs []types.ModelRef, files []*File) FitCatalog

CatalogWithModels is predict's WithModels: outer's signatures plus every loaded file's, under its entry's name — the static view of the names the runtime binds. outer may be nil.

func (FitCatalog) Names 

func (c FitCatalog) Names() []string

Names satisfies Catalog.

func (FitCatalog) Signature 

func (c FitCatalog) Signature(name string) (Signature, bool)

Signature satisfies Catalog.

type Float 

type Float float64

Float is a model-file float64: shortest round-trip form when finite, null for NaN, "+Inf" / "-Inf" for the infinities.

func (Float) MarshalJSON 

func (f Float) MarshalJSON() ([]byte, error)

MarshalJSON writes f bit-exactly (see Float).

func (*Float) UnmarshalJSON 

func (f *Float) UnmarshalJSON(b []byte) error

UnmarshalJSON reads what MarshalJSON writes: null is NaN.

type Loaded 

type Loaded struct {
	Models      []*File
	Populations []*PopulationFile
}

Loaded is a request's decoded files, index-aligned with its Refs.

func LoadFiles 

func LoadFiles(refs Refs, read ReadFunc) (*Loaded, *errors.CodedError)

LoadFiles reads and decodes a request's loads (refs passed CheckRefs): every `models` file (LoadModelFiles), then every population file in order — a read error PULSE_MODEL_FILE_UNREADABLE (missing / unreadable), a decode fault DecodePopulationFile's PULSE_MODEL_FILE_INVALID / _VERSION_UNSUPPORTED, each gaining details.population (the entry index) and details.name. The first fault wins. Nothing to load returns nil.

type PopulationFile 

type PopulationFile struct {
	// PopulationFormatVersion is the document version.
	PopulationFormatVersion int `json:"population_format_version"`
	// Name is the name the population was saved under (informational: a
	// load binds the name the loading request gives it).
	Name string `json:"name"`
	// Operator is the battery the fit was taken from — the fit
	// request's MAT_* type or fitted attribute type.
	Operator string `json:"operator,omitempty"`
	// Labels are the member labels in axis order: what a consuming slot
	// aligns to, by label. Members are the fit's member columns.
	Labels  []string `json:"labels"`
	Members []string `json:"members"`
	// Basis is the weight basis: unweighted, frequency or probability.
	Basis VectorBasis `json:"basis"`
	// N, NMass and NWeightInvalid are the fit's row counts
	// (VectorFit).
	N              int64 `json:"n"`
	NMass          int64 `json:"n_mass"`
	NWeightInvalid int64 `json:"n_weight_invalid"`
	// SumWeights and SumWeightsSq are Σw and Σw².
	SumWeights   Float `json:"sum_weights"`
	SumWeightsSq Float `json:"sum_weights_sq"`
	// Mean is the stored (weighted) mean; M2 the raw co-moment, a full
	// symmetric p × p matrix — both axis order.
	Mean []Float   `json:"mean"`
	M2   [][]Float `json:"m2"`
	// Provenance records where the fit came from. Informational only:
	// a load never compares it with anything.
	Provenance Provenance `json:"provenance"`
}

PopulationFile is one population file document: a vector fit's stored state at full float64 precision, in axis (Labels) order, plus informational provenance.

func DecodePopulationFile 

func DecodePopulationFile(source string, data []byte) (*PopulationFile, error)

DecodePopulationFile parses a population file — DecodeFile's rule set. The version is read first: absent is PULSE_MODEL_FILE_INVALID reason version_missing, not an integer reason schema, any value outside PopulationFormatVersions PULSE_MODEL_VERSION_UNSUPPORTED. The document is then decoded strictly — an unknown key, a wrong type or a structural fault (no labels, a blank or repeated label, members unlike the labels, an unknown basis, a negative count, n_mass above n, a weight sum that is not finite and non-negative, a mean or m2 whose shape is not the labels', an m2 that is not symmetric) is PULSE_MODEL_FILE_INVALID reason schema; malformed JSON reason json. source names the file in messages and details.path.

func NewPopulationFile 

func NewPopulationFile(name string, v *VectorFit, prov Provenance) (*PopulationFile, error)

NewPopulationFile builds the population file of a closed vector fit under name. A malformed fit (one the decode would refuse) is an engine invariant violation (PROCESSING_INTERNAL): it is never saved.

func (*PopulationFile) Encode 

func (f *PopulationFile) Encode() ([]byte, error)

Encode writes f as the population file's bytes: indented JSON with a trailing newline (deterministic: no maps).

func (*PopulationFile) VectorFit 

func (f *PopulationFile) VectorFit(name string) *VectorFit

VectorFit rebuilds the saved fit under name: every stored figure copied, none recomputed, so a slot binding it scores exactly as one binding the fit it was saved from.

type Provenance 

type Provenance struct {
	// Cohort is the training request's cohort path.
	Cohort string `json:"cohort,omitempty"`
	// Fingerprint is "sha256:<hex>" of the training cohort file's bytes
	// at save time (absent when it could not be computed).
	Fingerprint string `json:"fingerprint,omitempty"`
	// RequestDigest is the training request's canonical hash
	// (types.Request.Hash).
	RequestDigest string `json:"request_digest,omitempty"`
}

Provenance is a model file's informational origin.

type ReadFunc 

type ReadFunc func(path string) ([]byte, error)

ReadFunc reads a model file's bytes at a path relative to the instance filesystem root.

type RecordBinding 

type RecordBinding struct {
	Record StoredRecord
	Err    error
}

RecordBinding is one {record} reference's resolution: the record, or the refusal its lookup raised (exactly one is set).

type Refs 

type Refs struct {
	Models      []types.ModelRef
	Populations []types.PopulationRef
}

Refs are one request's file loads: its `models` and `populations` entries. A FacetRequest carries models only.

func RequestRefs 

func RequestRefs(req *types.Request) Refs

RequestRefs returns req's loads (the zero Refs for nil).

func (Refs) Empty 

func (r Refs) Empty() bool

Empty reports whether r loads nothing.

type SaveSite 

type SaveSite struct {
	Site string
	Path string
}

SaveSite is one `save` in a request tree: where it sits (e.g. "regressions[0]", "fits[1]", "requests[2].regressions[0]") and the path it writes.

func RequestSaveSites 

func RequestSaveSites(prefix string, req *types.Request) []SaveSite

RequestSaveSites lists req's regression saves, in order, each site prefixed by prefix ("" for a standalone request).

type ScoreParams 

type ScoreParams struct {
	// Fit names the bound model to score.
	Fit string `json:"fit"`
	// Terms restricts the score to a subset of the model's terms — its
	// predictor names, plus InterceptKey to include the intercept. Nil
	// scores the whole model, intercept included.
	Terms []string `json:"terms,omitempty"`
	// Scale is ScaleResponse (default) or ScaleLink; REG_GLM only.
	Scale string `json:"scale,omitempty"`
	// Bound is BoundPoint (default), BoundLower or BoundUpper. A
	// non-point bound needs Terms to list exactly one predictor: it is
	// that term's coefficient-interval contribution (bound × column),
	// never a prediction interval.
	Bound string `json:"bound,omitempty"`
}

ScoreParams is ATTR_REG_PREDICT's params block, decoded by the one function both the runtime and predict call (DecodeScoreParams).

func DecodeScoreParams 

func DecodeScoreParams(raw json.RawMessage) (ScoreParams, *errors.CodedError)

DecodeScoreParams decodes ATTR_REG_PREDICT's params; anything but a JSON object of the ScoreParams keys (with their types) is PULSE_MODEL_SCORE_INVALID reason params_invalid. Absent params decode to the zero ScoreParams (and then refuse as fit_missing).

type Set 

type Set struct {
	// contains filtered or unexported fields
}

Set is the request's bound-model namespace: every name a reference may resolve. The zero value and nil are empty sets. A Set is built once, before any slot runs, and only read afterwards — safe for concurrent readers.

func RegisteredSet 

func RegisteredSet(files map[string]*PopulationFile) (*Set, error)

RegisteredSet binds every registered population file as a vector fit under its registered name (Source RegisteredSource), the set every request's own bindings layer over. No files returns nil (binds nothing). Names are bound in sorted order; the map keys are unique, so no name collides.

func SetFrom 

func SetFrom(ctx context.Context) *Set

SetFrom returns the bound-model Set ctx carries, or nil.

func (*Set) Add 

func (s *Set) Add(b *Bound) error

Add binds b under b.Name; a name already bound is PULSE_MODEL_NAME_COLLISION.

func (*Set) AddVector 

func (s *Set) AddVector(v *VectorFit) error

AddVector binds v under v.Name. The namespace is shared with the bound regressions: a name already bound as either kind is PULSE_MODEL_NAME_COLLISION.

func (*Set) Capture 

func (s *Set) Capture() *VectorCapture

Capture returns the vector capture s carries (nil for none). Nil-receiver-safe.

func (*Set) Clone 

func (s *Set) Clone() *Set

Clone returns a new Set holding s's bindings (nil s: an empty set); s is never mutated, and the bound fits themselves are shared read-only. It carries no capture.

func (*Set) Len 

func (s *Set) Len() int

Len is the number of bound names, both kinds. Nil-receiver-safe.

func (*Set) Lookup 

func (s *Set) Lookup(name string) (*Bound, error)

Lookup resolves name to a bound regression; an unbound name is PULSE_MODEL_UNKNOWN with the bound regressions under details.available, a vector fit's name PULSE_MODEL_KIND_MISMATCH. Nil-receiver-safe.

func (*Set) LookupRecord 

func (s *Set) LookupRecord(key string) (StoredRecord, error)

LookupRecord returns the stored record bound under key, or its lookup's refusal. A key the Service never resolved (a processor driven without it) is PROCESSING_INTERNAL. Nil-receiver-safe.

func (*Set) LookupVector 

func (s *Set) LookupVector(name string) (*VectorFit, error)

LookupVector resolves name to a bound vector fit. An unbound name is PULSE_MODEL_UNKNOWN with the bound vector fits under details.available; a name bound as a regression is PULSE_MODEL_KIND_MISMATCH (KindMismatch: expected vector, kind regression). Nil-receiver-safe.

func (*Set) Names 

func (s *Set) Names() []string

Names returns every bound name, both kinds, sorted — the one namespace (RegressionNames / VectorNames list one kind each). Nil-receiver-safe.

func (*Set) RegressionNames 

func (s *Set) RegressionNames() []string

RegressionNames returns the bound regression names, sorted. Nil-receiver-safe.

func (*Set) Signature 

func (s *Set) Signature(name string) (Signature, bool)

Signature satisfies Catalog. Nil-receiver-safe.

func (*Set) VectorNames 

func (s *Set) VectorNames() []string

VectorNames returns the bound vector fit names, sorted. Nil-receiver-safe.

func (*Set) WithCapture 

func (s *Set) WithCapture(c *VectorCapture) *Set

WithCapture returns a copy of s (nil s: an empty set) carrying c; s is never mutated.

func (*Set) WithLoaded 

func (s *Set) WithLoaded(refs Refs, l *Loaded) (*Set, error)

WithLoaded returns a new Set holding s's bindings plus every loaded model (WithModels) and every loaded population bound as a vector fit under its entry's name (Source populations[k]). refs passed CheckRefs against s, so no name collides; l is LoadFiles' result. s is never mutated; nil s is empty; nothing loaded returns s.

func (*Set) WithModels 

func (s *Set) WithModels(refs []types.ModelRef, files []*File) (*Set, error)

WithModels returns a new Set holding s's bindings plus every loaded file bound under its entry's name (Source models[j]). refs passed CheckModelRefs against s, so no name collides; files are LoadModelFiles' result. s is never mutated; nil s is empty.

func (*Set) WithRecords 

func (s *Set) WithRecords(recs map[string]RecordBinding) *Set

WithRecords returns a copy of s (nil s: an empty set) carrying s's records plus recs (a key in both takes recs'); s is never mutated, and every other binding — models, vector fits, the capture — is shared.

type Signature 

type Signature struct {
	// Name is the bound name.
	Name string
	// Type is the regression operator that produces the fit.
	Type types.RegressionType
	// Terms are the predictor columns the fit was offered, in spec
	// order: the names `terms` may list and the columns a scoring frame
	// must hold. Under Selection it is the candidate set, a superset of
	// the predictors the fit keeps (a dropped candidate scores 0).
	Terms []string

	// Source is where the name is bound (a `fits` or `models` entry).
	Source Source

	// Kind is the bound fit's kind: types.FitKindRegression (the zero
	// value reads as it — EffectiveKind) or types.FitKindVector. One
	// namespace holds both; a reference of the other kind is
	// PULSE_MODEL_KIND_MISMATCH.
	Kind types.FitKind

	// Members are a vector fit's member labels in axis order — the
	// names a consuming slot aligns to — when known: the runtime's Set
	// always knows them; predict's static FitCatalog never resolves a
	// battery, so it leaves them nil. Nil on a regression.
	Members []string
}

Signature is the static face of a bound model: what a scoring reference is judged against without the fit's numbers. The runtime takes it from a Bound, predict from the fit request as written, so both judge one reference the same way.

func RegisteredSignature 

func RegisteredSignature(name string, labels []string) Signature

RegisteredSignature is predict's static face of a registered population: kind vector, its member labels in axis order — the same signature the runtime's RegisteredSet answers.

func (Signature) EffectiveKind 

func (s Signature) EffectiveKind() types.FitKind

EffectiveKind is Kind, types.FitKindRegression when unset.

type Source 

type Source struct {
	// Slot is SlotFits, SlotModels, SlotPopulations or SlotRegistered
	// ("" when unknown).
	Slot string
	// Index is the 0-based entry index in that slot.
	Index int
	// Path is a `models` entry's file path ("" for a fit).
	Path string
}

Source names where a bound name came from: the `fits` entry or the `models` entry (with its file path) that bound it.

func FitSource 

func FitSource(i int) Source

FitSource is the Source of fits[i].

func ModelSource 

func ModelSource(j int, path string) Source

ModelSource is the Source of models[j] loading path.

func PopulationSource 

func PopulationSource(k int, path string) Source

PopulationSource is the Source of populations[k] loading path.

func RegisteredSource 

func RegisteredSource() Source

RegisteredSource is the Source of a registered population.

func (Source) String 

func (s Source) String() string

String is "fits[i]", "models[j]" or "populations[k]" — or, for a population the instance registered (SlotRegistered), "the instance's registered populations".

type StoredRecord 

type StoredRecord interface {
	// Member reads member column name: its value, present false for a
	// null (a missing element); known false when the record's cohort
	// holds no column a vector member may be under that name.
	Member(name string) (value float64, present, known bool)
	// Cohort is the cohort path the record was read from.
	Cohort() string
}

StoredRecord is one resolved stored record, read by member column name. The engine implements it over the decoded record (this package stays a leaf: it never sees a schema).

type VectorBasis 

type VectorBasis string

VectorBasis names how a vector fit's Σw became the sample size N* its covariance divides by (the weighting rule every fitted vector operator shares): Σw unweighted or under frequency weights, Kish's n_eff under probability weights. 

const (
	VectorBasisUnweighted  VectorBasis = "unweighted"
	VectorBasisFrequency   VectorBasis = "frequency"
	VectorBasisProbability VectorBasis = "probability"
)

The vector fit bases.

type VectorCapture 

type VectorCapture struct {
	// contains filtered or unexported fields
}

VectorCapture receives the vector fit a Compose vector-fit request's battery closes: the one MAT_* slot or fitted attribute (FitKindOf) offers its closed listwise state at finalize, and the fit pre-pass binds it under the fit's name. It rides the fit request's own Set (WithCapture) — the namespace every engine arm already receives — so whichever arm runs the request (buffered, streaming, two-pass, the shard reducers) offers through the one handle. Safe for concurrent offers.

func (*VectorCapture) Fits 

func (c *VectorCapture) Fits() []*VectorFit

Fits returns the offered fits in offer order.

func (*VectorCapture) Offer 

func (c *VectorCapture) Offer(v *VectorFit)

Offer records a closed vector fit. Nil-receiver-safe (a set without a capture ignores the offer).

type VectorFit 

type VectorFit struct {
	// Name is the bound name.
	Name string

	// Labels are the member labels in axis order — the names a
	// consuming slot's members are aligned to (by label, never by
	// position). Members are the fit's member columns, informational.
	Labels  []string
	Members []string

	// Basis is the weight basis the fit was taken under.
	Basis VectorBasis

	// N counts the listwise-complete fit rows with a valid weight (zero
	// weights included), NMass those with w > 0, NWeightInvalid the rows
	// skipped for an invalid weight.
	N, NMass, NWeightInvalid int64

	// SumWeights and SumWeightsSq are Σw and Σw² over the rows N counts.
	SumWeights, SumWeightsSq float64

	// Mean is the stored (weighted) mean, axis order.
	Mean []float64

	// M2 is the raw weighted co-moment Σw(xi−mi)(xj−mj), a full
	// symmetric p × p matrix in axis order.
	M2 [][]float64

	// Operator is the battery the fit was taken from — the fit
	// request's MAT_* type or fitted attribute type ("" when unknown).
	Operator string

	// Source is where the name was bound (the zero value when unknown).
	Source Source
}

VectorFit is one fitted vector state bound under a name: the complete listwise co-moment of a member battery — everything a fitted vector operator (ATTR_MAHALANOBIS, ATTR_PC_SCORE, ATTR_FACTOR_SCORE, a fitted ATTR_VEC_DISTANCE metric) decomposes — at full precision, in Labels order. Derived blocks (covariance, correlation, Cholesky factor, eigen-decomposition, loadings, rotation) are never stored: every consumer recomputes them from these figures by the one deterministic arithmetic, so a score against a bound VectorFit is bit-identical to the score its own fit_on fold would give on the same rows.

The figures mirror linalg.ListwiseState (this package stays a leaf over the standard library, types and errors; the engine converts).

func (*VectorFit) NStar 

func (v *VectorFit) NStar() float64

NStar is the fit's N*: Kish's n_eff (Σw)²/Σw² under a probability basis (0 with no mass), Σw otherwise — the same arithmetic the fold uses (linalg.CoMoment.NEff / W).

func (*VectorFit) P 

func (v *VectorFit) P() int

P is the member count.

func (*VectorFit) Signature 

func (v *VectorFit) Signature() Signature

Signature is v's static face: kind vector, its member labels.

Source Files

View all Source files

Directories

Path Synopsis
Package coefcall finds the coef(fit, term[, stat]) calls an ATTR_FORMULA / FILTER_EXPRESSION expression makes with literal arguments and judges them by internal/model.CheckCoef — the static half of the coef() rule, shared by the engine's build (internal/ processing) and the no-execute field-reference pass (internal/ descriptor: predict and the runtime's entry check), so both refuse the same call with the same code, message and details.
 Package coefcall finds the coef(fit, term[, stat]) calls an ATTR_FORMULA / FILTER_EXPRESSION expression makes with literal arguments and judges them by internal/model.CheckCoef — the static half of the coef() rule, shared by the engine's build (internal/ processing) and the no-execute field-reference pass (internal/ descriptor: predict and the runtime's entry check), so both refuse the same call with the same code, message and details.

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.