Custom response families¶
A custom family binds a checked distribution contract to a native distribution factory. The contract states parameter types, intrinsic dimensions, sample support, and sampling capabilities; the factory supplies the corresponding PyTorch distribution. The same law then supplies fitting densities, raw held-out likelihoods, response expectations, and predictive draws through the existing formula workflow.
FamilyCatalog is immutable and local to a compilation. Extending one catalog
does not change another model's laws or the built-in registry. Thus two models
may use the same custom source name with different implementations, while their
checked caches and fitted recipes retain the appropriate catalog identity.
Constructor parameters and predictor parameters¶
custom_family maps native constructor parameters onto existing formula roles:
(i) location receives the linked main predictor mu; (ii) auxiliary supplies
ordinary scalar priors or distributional regressions; and (iii) data supplies
deterministic parameters from typed numeric columns. An auxiliary mapping can
separate the constructor name from the regression name. For instance, native
scale can receive formula parameter sigma.
The following factory returns a symmetric two-component Normal mixture. Its component locations differ by two, and a known per-row shift enters both components. The example uses a small optimization budget to exercise the API.
import pandas as pd
import torch
from torch.distributions import Categorical, MixtureSameFamily, Normal
from quivers.family_catalog import FamilyCatalog
from quivers.formulas import AuxParam, custom_family, fit, links
from quivers.qiec.families import DistributionFamily, FamilyParameter
from quivers.qiec.types import REAL
contract = DistributionFamily(
name="TwoMode",
parameters=(
FamilyParameter(name="center", constraint="real", rank=0),
FamilyParameter(name="scale", constraint="positive", rank=0),
FamilyParameter(name="bias", constraint="real", rank=0),
),
support="real", element=REAL, event_rank=0, event_sources=(),
discrete=False, reparameterizable=False, compositional=False,
)
def two_mode(parameters):
center = parameters["center"] + parameters["bias"]
locations = torch.stack((center - 1, center + 1), dim=-1)
scales = parameters["scale"].unsqueeze(-1).expand_as(locations)
weights = Categorical(probs=torch.full_like(locations, 0.5))
return MixtureSameFamily(weights, Normal(locations, scales))
catalog = FamilyCatalog().with_family(contract, two_mode)
response_family = custom_family(
"TwoMode", catalog=catalog, location="center",
auxiliary={
"scale": AuxParam(
name="sigma", prior="LogNormal(0.0, 0.3)", link=links["log"],
),
},
data={"bias": "known_shift"},
)
frame = pd.DataFrame({
"y": [-0.7, 0.8, -0.4, 1.2],
"x": [-1.0, 0.0, 0.5, 1.0],
"known_shift": [0.1, -0.2, 0.3, 0.0],
})
result = fit(
"y ~ x", data=frame, family=response_family,
distributional={"sigma": "~x"},
method="svi", num_steps=2, seed=7,
)
fresh = frame.iloc[[3, 1]].copy()
expected = result.posterior_epred(
new_data=fresh.drop(columns="y"), num_samples=5, seed=11,
)
scores = result.log_likelihood(new_data=fresh, num_samples=5, seed=11)["y"]
assert expected.shape == scores.shape == (1, 5, 2)
assert result.posterior_predict(
new_data=fresh.drop(columns="y"), num_samples=5, seed=11,
).shape == expected.shape
Deterministic data parameters introduce no latent coefficient or prior. They enter the existing checked predictor graph, preserving their fitted numeric carriers and row identities during new-data prediction, subsets, and refits. The native and formula parameter names need not coincide. Location and auxiliary predictors retain ordinary group effects, nonlinear expressions, priors, and likelihood weights; raw posterior likelihoods remain unweighted.
Capabilities and ownership¶
The factory must return the normalized law described by its contract. QVR
checks constructor argument names, intrinsic dimensions, batch broadcasting,
and declared reparameterization at the native boundary. These checks cannot
prove that a user-written log_prob integrates to one or that its sampler has
the claimed law; those mathematical properties require independent tests.
A custom torch.distributions.Distribution subclass can supply an arbitrary
log_prob, sample or rsample, and mean. Existing response helpers use those
operations directly. Censoring and truncation additionally require the existing
interval-mass or CDF capabilities and a truthful atomicity contract. The
catalog API describes typed native inputs and execution
capacity. Host implementations do not acquire external target implementations
through a name alone; unsupported source targets report their capabilities.
Catalogs retain live native factories by identity. Updates and cross-validation reuse that binding, while durable fitted artifacts require an explicit factory key and configuration when restoring it. The stored semantic contract is checked against the supplied implementation catalog.
custom_family
¶
custom_family(name: str, *, catalog: FamilyCatalog, location: str, link: str | Link = 'identity', auxiliary: tuple[AuxParam, ...] | Mapping[str, AuxParam] = (), data: Mapping[str, str] | None = None) -> Family
Bind an arbitrary checked native law to ordinary regression predictors.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Custom distribution name already defined in the supplied catalog.
TYPE:
|
catalog
|
Immutable semantic contracts and native distribution factories.
TYPE:
|
location
|
Native parameter receiving the linked main predictor named
TYPE:
|
link
|
Existing inverse link for that predictor.
TYPE:
|
auxiliary
|
Other native parameters, with ordinary priors and distributional links.
A mapping separates native names from formula names, for instance
native
TYPE:
|
data
|
Native parameters supplied by typed numeric data columns. These enter the existing predictor graph as deterministic identity-linked roots.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Family
|
Response law using the same compiler, inference and replay operations. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If parameter roles overlap, omit a constructor parameter, or use an unknown link, noncustom name, or invalid deterministic input name. |
Source code in src/quivers/formulas/_custom_family.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 | |
CustomFamilySpec
didactic-model
¶
CustomFamilySpec(*, catalog: FamilyCatalog = field(opaque=True, extras=OPAQUE_BY_IDENTITY), bindings: tuple[tuple[str, str], ...] = field(opaque=True, extras=OPAQUE_BY_VALUE), data: tuple[tuple[str, str], ...] = field(default=(), opaque=True, extras=OPAQUE_BY_VALUE))
Bases: ValueModel
One immutable custom-law binding, with a compilation-local implementation.
| PARAMETER | DESCRIPTION |
|---|---|
catalog
|
Checked semantic contracts and native implementations, held by identity.
TYPE:
|
bindings
|
Native constructor parameters paired with formula predictor bindings.
TYPE:
|
data
|
Deterministic distributional parameters paired with source data columns.
TYPE:
|