rake

type CategoryReport struct {
	// Values holds the category, one entry per margin field.
	Values []string `json:"values"`
	// ObservedN is the number of records in the category.
	ObservedN int64 `json:"observed_n"`
	// Observed is its share before raking (under the base weight, when
	// one is given).
	Observed float64 `json:"observed"`
	// Target is its requested share (targets normalised by their sum).
	Target float64 `json:"target"`
	// Achieved is its share under the output weights.
	Achieved float64 `json:"achieved"`
}

type Cell struct {
	// Values holds one category per Margin.Fields entry.
	Values []string `json:"values"`
	// Target is the cell's share or count.
	Target float64 `json:"target"`
}

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

type Efficiency struct {
	// N is the number of weighted records.
	N int64 `json:"n"`
	// SumWeights is Σw.
	SumWeights float64 `json:"sum_weights"`
	// NEff is Kish's effective sample size (Σw)²/Σw².
	NEff float64 `json:"n_eff"`
	// DeffKish is n / n_eff.
	DeffKish float64 `json:"deff_kish"`
	// EfficiencyPct is 100 · n_eff / n.
	EfficiencyPct float64 `json:"efficiency_pct"`
	// WeightMin / WeightMax are the smallest and largest weight.
	WeightMin float64 `json:"weight_min"`
	WeightMax float64 `json:"weight_max"`
	// WeightRangeRatio is max / min (null when min is 0).
	WeightRangeRatio float64 `json:"weight_range_ratio"`
	// WeightCV is the weights' coefficient of variation, population
	// standard deviation over the mean.
	WeightCV float64 `json:"weight_cv"`
	// NCapped counts records the final sweep held at a cap.
	NCapped int64 `json:"n_capped"`
}

type GroupReport struct {
	// Value is the group's by-field category.
	Value      string         `json:"value"`
	Records    int64          `json:"records"`
	Iterations int            `json:"iterations"`
	Converged  bool           `json:"converged"`
	Residual   float64        `json:"residual"`
	Margins    []MarginReport `json:"margins"`
	Efficiency Efficiency     `json:"efficiency"`
}

type Margin struct {
	// Field is the single margin field.
	Field string `json:"field,omitempty"`
	// Targets maps each category of Field (its dictionary label, its
	// decimal integer, or "true" / "false") to its target.
	Targets map[string]float64 `json:"targets,omitempty"`
	// Fields are the joint margin's fields, in Cell.Values order.
	Fields []string `json:"fields,omitempty"`
	// Cells are the joint margin's targets, one per category tuple.
	Cells []Cell `json:"cells,omitempty"`
	// TargetsAs is "shares" (default) or "counts".
	TargetsAs string `json:"targets_as,omitempty"`
}

type MarginReport struct {
	// Fields names the margin's field(s).
	Fields []string `json:"fields"`
	// NMissing counts records with no value for the margin (missing
	// "base"); the shares are over the other records.
	NMissing   int64            `json:"n_missing"`
	Categories []CategoryReport `json:"categories"`
}

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

type Report struct {
	Iterations int            `json:"iterations"`
	Converged  bool           `json:"converged"`
	Residual   float64        `json:"residual"`
	Margins    []MarginReport `json:"margins"`
	Groups     []GroupReport  `json:"groups,omitempty"`
	Efficiency Efficiency     `json:"efficiency"`
}

type Request struct {
	// Cohort is the source cohort path (a single file, a shard archive
	// or an anchored shard).
	Cohort string `json:"cohort"`
	// Out is the path of the NEW single-file cohort written: every source
	// column verbatim plus the nullable f64 weight column.
	Out string `json:"out"`
	// WeightField names the output weight column; empty selects
	// DefaultWeightField. A name the source already carries is refused
	// unless Overwrite is set, which replaces that column in place.
	WeightField string `json:"weight_field,omitempty"`
	// Margins are the target distributions the weights reproduce. One
	// margin of several fields is cell weighting (post-stratification).
	Margins []Margin `json:"margins"`
	// By rakes every group of this field separately to the SAME targets
	// (per-wave weighting of a tracker); each group is normalised on its
	// own.
	By string `json:"by,omitempty"`
	// BaseWeight names a design-weight column the raking starts from: the
	// output is that weight times the raking adjustment.
	BaseWeight string `json:"base_weight,omitempty"`
	// Missing is the null-margin-value policy: "refuse" (default) or
	// "base".
	Missing string `json:"missing,omitempty"`
	// MinWeight / MaxWeight cap every weight relative to the mean weight
	// of its group (0 = no cap), applied after every sweep.
	MinWeight float64 `json:"min_weight,omitempty"`
	MaxWeight float64 `json:"max_weight,omitempty"`
	// MaxIter is the sweep ceiling (0 = DefaultMaxIter).
	MaxIter int `json:"max_iter,omitempty"`
	// Tol is the convergence tolerance on shares (0 = DefaultTol).
	Tol float64 `json:"tol,omitempty"`
	// Total normalises every group's weights to sum to this value; 0
	// (the default) normalises to the group's record count, so the mean
	// weight is 1.
	Total float64 `json:"total,omitempty"`
	// Overwrite replaces an existing cohort at Out and an existing source
	// column named WeightField.
	Overwrite bool `json:"overwrite,omitempty"`
}

type Solution struct {
	// Weights holds record i's output weight.
	Weights  []float64
	Report   Report
	Warnings []*errors.CodedError
}