Priors

Declarative, serializable prior distributions for model parameters.

Priors are inert data containers that describe numpyro distributions. At model-build time, a topological sort of their dependencies determines sampling order, and each prior’s to_dist() method receives a context dict of already-sampled values to resolve parameter expressions.

Examples

Simple fixed-bound prior:

>>> from unite.prior import Uniform
>>> p = Uniform(0, 750)
>>> p.to_dist({})
Uniform(low=0, high=750)

Dependent prior using arithmetic on parameter tokens:

>>> from unite.line.config import FWHM
>>> from unite.prior import Uniform
>>> narrow = FWHM('narrow', prior=Uniform(0, 750))
>>> broad = FWHM('broad', prior=Uniform(low=narrow * 2 + 150, high=2500))

Ratio constraint tying a flux diagnostic across two kinematic components:

>>> flux_5007_narrow = Flux('5007_narrow')
>>> flux_5007_broad = Flux('5007_broad')
>>> flux_4363_narrow = Flux('4363_narrow')
>>> flux_4363_broad = Flux('4363_broad',
...     prior=Fixed(flux_4363_narrow * flux_5007_broad / flux_5007_narrow))

unite.prior.Bound = float | unite.prior._Expr

Type for a prior bound: either a fixed float or a parameter expression.

class unite.prior.Prior

Bases: ABC

Abstract base class for declarative prior descriptions.

Subclasses must implement to_dist(), dependencies(), to_dict(), and the classmethod from_dict().

abstractmethod to_dist(context)

Convert to a numpyro distribution, or None for fixed values.

Return type:

Distribution | None

Parameters:

contextdict

Mapping of parameter token objects to already-sampled values. Required for resolving parameter expressions in bounds.

Returns:

numpyro.distributions.Distribution or None

None indicates the parameter is fixed and must not be sampled. The caller is responsible for injecting the fixed value (from resolved_value()) into the model context.

Parameters:

context (dict)

abstractmethod dependencies()

Return parameter token objects this prior depends on.

Return type:

set

Returns:

set

Set of Parameter objects. Empty for independent priors.

abstractmethod to_dict(param_namer=None)

Serialize to a YAML-safe dictionary.

Return type:

dict

Parameters:

param_namerdict, optional

Mapping from parameter token objects to string names, used to serialize parameter expressions in bounds.

Parameters:

param_namer (dict | None)

abstractmethod classmethod from_dict(d)

Deserialize from a dictionary.

Return type:

Prior

Parameters:

d (dict)

class unite.prior.Uniform(low=0, high=1)

Bases: Prior

Uniform prior with bounds that may reference other parameters.

Parameters:

lowfloat, or arithmetic expression on Parameter tokens

Lower bound.

highfloat, or arithmetic expression on Parameter tokens

Upper bound.

Parameters:

• low (Bound)

• high (Bound)

Examples

Fixed bounds:

>>> Uniform(0, 750)

Dependent bound (broad fwhm > narrow fwhm + 150 km/s):

>>> Uniform(low=narrow_fwhm * 2 + 150, high=2500)

Direct parameter reference:

>>> Uniform(low=base_redshift, high=base_redshift + 0.1)

to_dist(context)

Convert to a numpyro distribution, or None for fixed values.

Return type:

Distribution

Parameters:

contextdict

Mapping of parameter token objects to already-sampled values. Required for resolving parameter expressions in bounds.

Returns:

numpyro.distributions.Distribution or None

None indicates the parameter is fixed and must not be sampled. The caller is responsible for injecting the fixed value (from resolved_value()) into the model context.

Parameters:

context (dict)

dependencies()

Return parameter token objects this prior depends on.

Return type:

set

Returns:

set

Set of Parameter objects. Empty for independent priors.

to_dict(param_namer=None)

Serialize to a YAML-safe dictionary.

Return type:

dict

Parameters:

param_namerdict, optional

Mapping from parameter token objects to string names, used to serialize parameter expressions in bounds.

Parameters:

param_namer (dict | None)

classmethod from_dict(d, token_registry=None)

Deserialize from a dictionary.

Return type:

Uniform

Parameters:

• d (dict)

• token_registry (dict | None)

class unite.prior.TruncatedNormal(loc, scale, low, high)

Bases: Prior

Truncated normal prior with bounds that may reference other parameters.

Parameters:

locfloat, or arithmetic expression on Parameter tokens

Mean of the underlying normal distribution.

scalefloat

Standard deviation of the underlying normal distribution.

lowfloat, or arithmetic expression on Parameter tokens

Lower truncation bound.

highfloat, or arithmetic expression on Parameter tokens

Upper truncation bound.

Parameters:

• loc (Bound)

• scale (float)

• low (Bound)

• high (Bound)

to_dist(context)

Convert to a numpyro distribution, or None for fixed values.

Return type:

Distribution

Parameters:

contextdict

Mapping of parameter token objects to already-sampled values. Required for resolving parameter expressions in bounds.

Returns:

numpyro.distributions.Distribution or None

None indicates the parameter is fixed and must not be sampled. The caller is responsible for injecting the fixed value (from resolved_value()) into the model context.

Parameters:

context (dict)

dependencies()

Return parameter token objects this prior depends on.

Return type:

set

Returns:

set

Set of Parameter objects. Empty for independent priors.

to_dict(param_namer=None)

Serialize to a YAML-safe dictionary.

Return type:

dict

Parameters:

param_namerdict, optional

Mapping from parameter token objects to string names, used to serialize parameter expressions in bounds.

Parameters:

param_namer (dict | None)

classmethod from_dict(d, token_registry=None)

Deserialize from a dictionary.

Return type:

TruncatedNormal

Parameters:

• d (dict)

• token_registry (dict | None)

class unite.prior.Fixed(value)

Bases: Prior

A fixed (non-sampled) constant value or deterministic expression.

Fixed parameters are injected directly into the model context as constants rather than being drawn from a distribution. This avoids Delta distributions, which are not differentiable and would break gradient-based samplers.

The value may be a literal number, a Parameter token (automatically converted to an expression), or any arithmetic expression built from Parameter tokens (e.g. flux_a * flux_b / flux_c). Expressions are evaluated at model-build time after their dependencies have been sampled, enabling deterministic relationships between parameters.

Parameters:

valuefloat, int, or arithmetic expression on Parameter tokens

The constant value or deterministic expression.

Parameters:

value (Bound | Parameter)

Examples

Literal value:

>>> Fixed(6564.61)
Fixed(6564.61)

Tie a redshift to another parameter:

>>> Fixed(narrow_z)

Tie the [OIII] 4363 flux ratio across narrow and broad components (same electron temperature in both):

>>> Fixed(flux_4363_narrow * flux_5007_broad / flux_5007_narrow)

to_dist(context)

Return None — the parameter is constant and must not be sampled.

Return type:

None

Parameters:

context (dict)

resolved_value(context)

Evaluate the fixed value against a context of sampled parameters.

For literal values, returns the value directly. For expression values (including single-parameter references), evaluates the expression tree against already-sampled parameter values.

Return type:

float

Parameters:

contextdict

Mapping of parameter token objects to their sampled values.

Returns:

float

Parameters:

context (dict)

dependencies()

Return parameter token objects this prior depends on.

Return type:

set

Returns:

set

Set of Parameter objects. Empty for independent priors.

to_dict(param_namer=None)

Serialize to a YAML-safe dictionary.

Return type:

dict

Parameters:

param_namerdict, optional

Mapping from parameter token objects to string names, used to serialize parameter expressions in bounds.

Parameters:

param_namer (dict | None)

classmethod from_dict(d, token_registry=None)

Deserialize from a dictionary.

Return type:

Fixed

Parameters:

• d (dict)

• token_registry (dict | None)

unite.prior.prior_from_dict(d, token_registry=None)

Deserialize a Prior from a dictionary using the ‘type’ key.

Return type:

Prior

Parameters:

ddict

Dictionary with a 'type' key matching a registered prior class.

token_registrydict, optional

Mapping from string names to parameter token objects.

Returns:

Prior

Raises:

KeyError

If the type is not registered.

Parameters:

• d (dict)

• token_registry (dict | None)

class unite.prior.Parameter(name=None, *, prior)

Bases: object

A named, shareable model parameter token.

Any object referencing the same Parameter instance shares a single sampled value in the fitted model. Sharing is identity-based — pass the same instance to multiple lines or dispersers.

Arithmetic on a Parameter produces an expression tree that can be used as a prior bound, enabling dependent priors such as broad_fwhm > narrow_fwhm + 150 km/s or ratio constraints such as flux_4363_broad = flux_4363_narrow * flux_5007_broad / flux_5007_narrow.

Parameters:

namestr, optional

Human-readable label used as the numpyro site name. May be None when the token will be auto-named later (e.g. by LineConfiguration).

priorPrior

Prior distribution for this parameter.

Raises:

TypeError

If any dependency of prior references a parameter that is not an instance of the same subclass as self. Cross-kind expressions (e.g. an FWHM expression used as a Redshift prior bound) are forbidden.

Parameters:

• name (str | None)

• prior (Prior)

label: str | None

property name: str

NumPyro site name. Set at registration; asserts the token has been registered.

unite.prior.topological_sort(named_priors, param_to_name)

Sort parameter names so that dependencies are sampled first.

Return type:

list[str]

Parameters:

named_priorsdict

Mapping of parameter string names to Prior objects.

param_to_namedict

Mapping of parameter token objects to their string names.

Returns:

list of str

Parameter names in valid sampling order.

Raises:

ValueError

If there is a circular dependency.

Parameters:

• named_priors (dict[str, Prior])

• param_to_name (dict[object, str])