mixle.stats.latent.effective_sample module¶
Shared effective-sample and sufficient-statistic contracts for latent models.
An outer observation with weight w_i contributes finite non-negative effective
mass. A latent responsibility vector may distribute that mass among children, but
must never create mass. Child estimators receive their assigned posterior mass,
not the outer row count. Positive-weight observations impossible under every
latent branch may remain unassigned only when the family explicitly opts into
that support policy.
- class EffectiveSampleReceipt(declared_mass, assigned_mass, unassigned_mass, allows_unassigned, schema_version=1, contract='mixle.latent_effective_sample/v1')[source]
Bases:
objectValidated relationship between declared and assigned effective mass.
- validated_positive_integer(value, label)[source]
Return a positive exact non-boolean integer.
- validated_observation_weight(value, label='observation weight')[source]
Return one finite non-negative, non-boolean observation weight.
- validated_observation_weights(values, rows, label='observation weights')[source]
Return an owned finite non-negative weight vector with exact row geometry.
- validated_count_array(values, shape, label='sufficient-statistic counts')[source]
Return an owned finite non-negative count array with exact geometry.
- validated_statistic_tuple(values, arity, label)[source]
Return a statistic tuple only when its public schema arity is exact.
- validate_effective_sample_mass(declared_mass, assigned_mass, *, label, allow_unassigned=False)[source]
Validate declared outer mass against mass assigned to latent children.
declared_mass=Nonemeans the caller did not provide outer-mass metadata. Otherwise exact agreement is required, except that families whose documented impossible-evidence policy assigns zero responsibility may setallow_unassigned=True. Assigned mass may never exceed declared mass.
- validated_weighted_responsibilities(values, weights, components, *, label, allow_unassigned=False)[source]
Validate an owned
(rows, components)matrix of assigned posterior mass.
- require_finite_count_totals(named_arrays, *, label)[source]
Every element AND every aggregate must be finite.
Validating only what ARRIVES is not enough: two individually valid statistics whose elements are each 4.6e307 combine to finite elements with an infinite total, a valid statistic scaled by a valid factor of 3.0 overflows outright, and keyed pooling reaches the same state through addition (STAT-RR8-1). Finiteness has to be a postcondition of every public mutator, not a precondition of ingestion, so this runs on the RESULT and each mutator rolls back if it fails. This is the canonical home; the chain/tree HMM implementation aliases it, and the latent-family mutator audit applies it family-wide.
- snapshot_accumulator_statistics(acc, *, count_attrs=(), child_attrs=(), single_child_attrs=())[source]
Snapshot the named count arrays, child-accumulator lists, and single children of
acc.Taken by a mutator BEFORE it changes anything, so a failure at any later point can hand the snapshot to
restore_accumulator_statistics()and put the accumulator back exactly as it was – counts, children, and the identity of the child containers included. Child lists are captured as (container reference, child references, serialized values): the container reference matters because keyed replacement can REBIND the attribute to an adopted list, and rollback must restore the original object, not a copy.Attributes the object does not carry are skipped: the keyed-pooling protocol tests build accumulators via
__new__with only the fields under test, and an attribute an object lacks cannot need restoring either.Count arrays are captured as (original object, value copy) pairs, not value copies alone: mutators change counts IN PLACE (
+=,*=), so a rollback that merely rebinds the attribute to a pristine copy abandons the mutated original – an external alias to the count array then keeps the doubled values while the attribute looks restored, and the attribute’s identity changes (STAT-RR11-3). Restoration writes the values back INTO the original object and rebinds that original.
- restore_accumulator_statistics(acc, snapshot)[source]
Best-effort rollback of a failed mutator from a prior snapshot.
Count attributes are healed by writing the snapshotted values back INTO the original array object and rebinding that original – both an external alias and the attribute itself then observe the rollback, with identity preserved (STAT-RR11-3: rebinding a copy left a caller-held alias doubled after a rejected in-place
*=/+=). Child containers are rebound to their ORIGINAL objects and every child restored throughfrom_value; single children (length accumulators and kin) likewise. Restoration errors are deliberately suppressed: the original rejection is the signal, and a failure while rolling back must not mask it.
- heal_pooled_statistics(stats_dict, snapshot)[source]
Restore a keyed-statistics mapping after a failed mutator, healing in-place damage.
Swapping restored COPIES into the mapping is not enough: merges mutate pooled arrays with
+=and pooled emission accumulators withcombine, so state reachable through a pre-existing reference – a caller’s alias to a pooled array, the shared child list a tied site adopted – stayed corrupted while the mapping itself looked restored (STAT-RR10-1). Entries the failed mutator added are removed; surviving entries are healed in place via_healed_in_place()so external aliases observe the rollback too. Take the snapshot withcopy.deepcopy(stats_dict)before the first mutation.