parametric_family

Parametric family definitions and management infrastructure.

This module contains the main class for defining parametric families of distributions, including support for multiple parameterizations, distribution characteristics, sampling strategies, and computation methods.

class pysatl_core.families.parametric_family.ParametricFamily(name, distr_type, distr_parametrizations, distr_characteristics, support_by_parametrization=None, base_score=None)[source]

Bases: object

A family of distributions with multiple parametrizations.

Represents a parametric family of distributions (e.g., normal, lognormal) that can be parameterized in different ways. Manages parametrizations, distribution characteristics, and provides factory methods for creating distribution instances.

Parameters:

  • name (str) – Name of the distribution family.

  • distr_type (DistributionType or Callable[[Parametrization], DistributionType]) – Distribution type or function that infers type from base parametrization.

  • distr_parametrizations (list[ParametrizationName]) – List of parametrization names (first is base parametrization).

  • distr_characteristics (CharacteristicsMap) –

    Mapping from characteristic names to analytical provider callables.

    Each provider callable may accept a parametrization instance as the first argument. The remaining signature is characteristic-specific:

    • nullary characteristics (e.g., mean, var): provider(params, **kwargs) -> Any

    • pointwise characteristics (e.g., pdf, cdf, ppf): provider(params, x, **kwargs) -> Any

    Providers are grouped by parametrization and may define multiple labeled methods. If a single callable is provided, it is treated as the base-parametrization method under DEFAULT_ANALYTICAL_COMPUTATION_LABEL.

  • support_by_parametrization (Callable or None, optional) – Function that returns support for given parameters.

  • base_score (Callable[[Parametrization, NumericArray], NumericArray] | None)

__init__(name, distr_type, distr_parametrizations, distr_characteristics, support_by_parametrization=None, base_score=None)[source]
Parameters:
property name: str

Get the family name.

property parametrizations: dict[ParametrizationName, type[pysatl_core.families.parametrizations.Parametrization]]

Get mapping from parametrization names to classes.

property base: type[pysatl_core.families.parametrizations.Parametrization]

Get the base parametrization class.

Raises:

ValueError – If base parametrization is not registered.

property support_resolver: SupportResolver

Support resolver callable.

register_parametrization(name, parametrization_class)[source]

Register a parametrization class.

Parameters:

  • name (ParametrizationName) – Unique parametrization name.

  • parametrization_class (type[Parametrization]) – Parametrization class to register.

Raises:

ValueError – If name is already registered.

Return type:

None

get_parametrization(name)[source]

Fetch a parametrization class by name.

Raises:

KeyError – If name is not registered.

Return type:

type[pysatl_core.families.parametrizations.Parametrization]

Parameters:

name (ParametrizationName)

to_base(parameters)[source]

Convert parameters to the base parametrization.

Parameters:

parameters (Parametrization) – Parameters in any parametrization.

Returns:

Equivalent parameters in base parametrization.

Return type:

Parametrization

distribution(parametrization_name=None, sampling_strategy=None, computation_strategy=None, **parameters_values)[source]

Create a distribution instance with given parameters.

Parameters:

  • parametrization_name (ParametrizationName | None, optional) – Name of parametrization to use (defaults to base).

  • sampling_strategy (SamplingStrategy) – Strategy for generating random samples. Such an object is unique for each distribution.

  • computation_strategy (ComputationStrategy) – Strategy for computing characteristics and conversions. Such an object is unique for each distribution.

  • **parameters_values (Any) – Parameter values for the distribution.

Returns:

Distribution instance with specified parameters.

Return type:

ParametricFamilyDistribution

Raises:

  • KeyError – If parametrization name is not registered.

  • ValueError – If parameters don’t satisfy constraints.

parametrization(*, name)[source]

Create a class decorator that registers a parametrization.

If you want to use this syntax and so that Mypy doesn’t swear, you should mark your class as a dataclass. At the moment, Mypy cannot identify dataclass_transform if the decorator is a class method.

Parameters:

name (str) – Name of the parametrization.

Returns:

Class decorator for registering parametrizations.

Return type:

Callable[[type[Parametrization]], type[Parametrization]]

score(parameters, x)[source]

Compute the score (gradient of log‑PDF) for the given parametrization.

Parameters:

  • parameters (Parametrization) – Parametrization instance of the family.

  • x (NumericArray) – Points at which to evaluate the gradient.

Returns:

Gradient with respect to the parameters of the given parametrization. Shape is (…, d), where d is the number of parameters of the parametrization.

Return type:

NumericArray

view(*, parametrization_name=None, **fixed_params)[source]

Create a view of this family with partially fixed parameters.

Parameters:

  • parametrization_name (str, optional) – Name of the parametrization in which the fixed parameters are given. If not provided, the base parametrization of the family is used.

  • **fixed_params (Any) – Parameter names and values to fix.

Returns:

A view that behaves like the original family but with the specified parameters fixed.

Return type:

PartialParametricFamily

Examples

>>> uniform = ParametricFamilyRegister.get("uniform")
>>> uniform_lower0 = uniform.view(lower_bound=0)
>>> dist = uniform_lower0.distribution(upper_bound=1)  # Uniform(0,1)
__call__(parametrization_name=None, sampling_strategy=None, computation_strategy=None, **parameters_values)

Create a distribution instance with given parameters.

Parameters:

  • parametrization_name (ParametrizationName | None, optional) – Name of parametrization to use (defaults to base).

  • sampling_strategy (SamplingStrategy) – Strategy for generating random samples. Such an object is unique for each distribution.

  • computation_strategy (ComputationStrategy) – Strategy for computing characteristics and conversions. Such an object is unique for each distribution.

  • **parameters_values (Any) – Parameter values for the distribution.

Returns:

Distribution instance with specified parameters.

Return type:

ParametricFamilyDistribution

Raises:

  • KeyError – If parametrization name is not registered.

  • ValueError – If parameters don’t satisfy constraints.

class pysatl_core.families.parametric_family.PartialParametricFamily(base_family, fixed_params, parametrization_name=None)[source]

Bases: ParametricFamily

View on a parametric family with partially fixed parameters.

This class represents a parametric family where some parameters have been fixed to specific values. It inherits all behaviour from ParametricFamily but restricts the available parametrization to the one in which parameters are fixed. All analytical characteristics are preserved via delegation to the base parametrization of the original family.

Parameters:

  • base_family (ParametricFamily) – The original parametric family.

  • fixed_params (dict[str, Any]) – Dictionary of fixed parameter names and their values.

  • parametrization_name (str, optional) – Name of the parametrization in which the fixed parameters are specified. If not provided, the base parametrization of the family is used.

Raises:

ValueError – If all parameters of the chosen parametrization are fixed (use .distribution() directly), or if any fixed parameter name is unknown for that parametrization, or if the parametrization name is not registered in the family.

__init__(base_family, fixed_params, parametrization_name=None)[source]
Parameters:
Return type:

None

property parametrizations: dict[str, type[pysatl_core.families.parametrizations.Parametrization]]

Return a dictionary containing only the fixed (free‑parameter) parametrization.

property parent_family: pysatl_core.families.parametric_family.ParametricFamily

Original family this view was created from.

property fixed_parameters: Mapping[str, Any]

Fixed parameter values.

property fixed_parameter_names: frozenset[str]

Names of fixed parameters.

property free_parameter_names: tuple[str, ...]

Names of parameters that remain free in this view.

get_parametrization(name=None)[source]

Return the lightweight parametrization class with only free parameters.

If name is omitted, returns the fixed parametrization class. If name is given, it must match the fixed parametrization name.

Raises KeyError for any other name.

Return type:

type[pysatl_core.families.parametrizations.Parametrization]

Parameters:

name (ParametrizationName | None)

property base: type[pysatl_core.families.parametrizations.Parametrization]

Return a lightweight parametrization class with only free parameters.

Its transform_to_base_parametrization substitutes fixed values and delegates to the original parametrization.

to_base(parameters)[source]

Convert view parameters to the original family’s base parametrization. The view’s own base is the lightweight class, but the true base is the original family’s base. We always transform through the full parametrization.

Return type:

pysatl_core.families.parametrizations.Parametrization

Parameters:

parameters (pysatl_core.families.parametrizations.Parametrization)

distribution(parametrization_name=None, sampling_strategy=None, computation_strategy=None, **kwargs)[source]

Create a distribution instance with given parameters.

Parameters:

  • parametrization_name (ParametrizationName | None, optional) – Name of parametrization to use (defaults to base).

  • sampling_strategy (SamplingStrategy) – Strategy for generating random samples. Such an object is unique for each distribution.

  • computation_strategy (ComputationStrategy) – Strategy for computing characteristics and conversions. Such an object is unique for each distribution.

  • **parameters_values – Parameter values for the distribution.

  • kwargs (Any)

Returns:

Distribution instance with specified parameters.

Return type:

ParametricFamilyDistribution

Raises:

  • KeyError – If parametrization name is not registered.

  • ValueError – If parameters don’t satisfy constraints.

view(*, parametrization_name=None, **additional_params)[source]

Create a view of this family with partially fixed parameters.

Parameters:

  • parametrization_name (str, optional) – Name of the parametrization in which the fixed parameters are given. If not provided, the base parametrization of the family is used.

  • **fixed_params (Any) – Parameter names and values to fix.

  • additional_params (Any)

Returns:

A view that behaves like the original family but with the specified parameters fixed.

Return type:

PartialParametricFamily

Examples

>>> uniform = ParametricFamilyRegister.get("uniform")
>>> uniform_lower0 = uniform.view(lower_bound=0)
>>> dist = uniform_lower0.distribution(upper_bound=1)  # Uniform(0,1)