Metaclass

pyrenew helper classes

Model

Model(**kwargs: object)

Abstract base class for models

Source code in pyrenew/metaclass.py

@abstractmethod
def __init__(self, **kwargs: object) -> None:  # numpydoc ignore=GL08
    pass

model

model(**kwargs: object) -> tuple

Alias for the sample method.

Parameters:

Name	Type	Description	Default
**kwargs	object	Additional keyword arguments passed through to internal sample calls, should there be any.	{}

Returns:

Type	Description
tuple

Source code in pyrenew/metaclass.py

def model(self, **kwargs: object) -> tuple:
    """
    Alias for the sample method.

    Parameters
    ----------
    **kwargs
        Additional keyword arguments passed through to
        internal `sample` calls, should there be any.

    Returns
    -------
    tuple
    """
    return self.sample(**kwargs)

posterior_predictive

posterior_predictive(
    rng_key: ArrayLike | None = None,
    numpyro_predictive_args: dict = {},
    **kwargs: object,
) -> dict

A wrapper of numpyro.infer.util.Predictive to generate posterior predictive samples.

Parameters:

Name	Type	Description	Default
rng_key	ArrayLike | None	Random key for the Predictive function call. Defaults to None.	None
numpyro_predictive_args	dict	Dictionary of arguments to be passed to the numpyro.infer.util.Predictive constructor.	{}
**kwargs	object	Additional named arguments passed to the __call__() method of numpyro.infer.util.Predictive.	{}

Returns:

Type	Description
dict

Source code in pyrenew/metaclass.py

def posterior_predictive(
    self,
    rng_key: ArrayLike | None = None,
    numpyro_predictive_args: dict = {},
    **kwargs: object,
) -> dict:
    """
    A wrapper of [`numpyro.infer.util.Predictive`][] to generate
    posterior predictive samples.

    Parameters
    ----------
    rng_key
        Random key for the Predictive function call. Defaults to None.
    numpyro_predictive_args
        Dictionary of arguments to be passed to the
        [`numpyro.infer.util.Predictive`][] constructor.
    **kwargs
        Additional named arguments passed to the
        `__call__()` method of
        [`numpyro.infer.util.Predictive`][].

    Returns
    -------
    dict
    """
    if self.mcmc is None:
        raise ValueError(
            "No posterior samples available. Run model with model.run()."
        )

    if rng_key is None:
        rand_int = np.random.randint(np.iinfo(np.int64).min, np.iinfo(np.int64).max)
        rng_key = jr.key(rand_int)

    predictive = Predictive(
        model=self.model,
        posterior_samples=self.mcmc.get_samples(),
        **numpyro_predictive_args,
    )

    return predictive(rng_key, **kwargs)

print_summary

print_summary(prob: float = 0.9, exclude_deterministic: bool = True) -> None

A wrapper of numpyro.infer.mcmc.MCMC.print_summary.

Parameters:

Name	Type	Description	Default
prob	float	The width of the credible interval to show. Default 0.9	0.9
exclude_deterministic	bool	Whether to print deterministic sites in the summary. Defaults to True.	True

Returns:

Type	Description
None

Source code in pyrenew/metaclass.py

def print_summary(
    self,
    prob: float = 0.9,
    exclude_deterministic: bool = True,
) -> None:
    """
    A wrapper of [`numpyro.infer.mcmc.MCMC.print_summary`][].

    Parameters
    ----------
    prob
        The width of the credible interval to show. Default 0.9
    exclude_deterministic
        Whether to print deterministic sites in the summary.
        Defaults to True.

    Returns
    -------
    None
    """
    return self.mcmc.print_summary(prob, exclude_deterministic)

prior_predictive

prior_predictive(
    rng_key: ArrayLike | None = None,
    numpyro_predictive_args: dict = {},
    **kwargs: object,
) -> dict

A wrapper for numpyro.infer.util.Predictive to generate prior predictive samples.

Parameters:

Name	Type	Description	Default
rng_key	ArrayLike | None	Random key for the Predictive function call. Default None.	None
numpyro_predictive_args	dict	Dictionary of arguments to be passed to the numpyro.infer.util.Predictive constructor. Default None.	{}
**kwargs	object	Additional named arguments passed to the __call__() method of numpyro.infer.util.Predictive.	{}

Returns:

Type	Description
dict

Source code in pyrenew/metaclass.py

def prior_predictive(
    self,
    rng_key: ArrayLike | None = None,
    numpyro_predictive_args: dict = {},
    **kwargs: object,
) -> dict:
    """
    A wrapper for [`numpyro.infer.util.Predictive`][]
    to generate prior predictive samples.

    Parameters
    ----------
    rng_key
        Random key for the Predictive function call.
        Default None.
    numpyro_predictive_args
        Dictionary of arguments to be passed to
        the [`numpyro.infer.util.Predictive`][]
        constructor. Default None.
    **kwargs
        Additional named arguments passed to the
        `__call__()` method of
        [`numpyro.infer.util.Predictive`][].

    Returns
    -------
    dict
    """

    if rng_key is None:
        rand_int = np.random.randint(np.iinfo(np.int64).min, np.iinfo(np.int64).max)
        rng_key = jr.key(rand_int)

    predictive = Predictive(
        model=self.model,
        posterior_samples=None,
        **numpyro_predictive_args,
    )

    return predictive(rng_key, **kwargs)

run

run(
    num_warmup: int,
    num_samples: int,
    rng_key: ArrayLike | None = None,
    nuts_args: dict = None,
    mcmc_args: dict = None,
    **kwargs: object,
) -> None

Run the model after validating model-specific arguments.

Validation occurs before the NumPyro kernel and MCMC objects are initialized. Models without model-specific run validation proceed unchanged. If validation, initialization, or sampling fails, kernel and mcmc are reset to None.

Parameters:

Name	Type	Description	Default
nuts_args	dict	Dictionary of arguments passed to the kernel numpyro.infer.hmc.NUTS constructor. Defaults to None.	None
mcmc_args	dict	Dictionary of arguments passed to the MCMC runner numpyro.infer.mcmc.MCMC constructor. Defaults to None.	None
**kwargs	object	Model-specific arguments. These are validated before MCMC initialization and then forwarded to the model's sample() method by the MCMC runner.	{}

Returns:

Type	Description
None

Source code in pyrenew/metaclass.py

def run(
    self,
    num_warmup: int,
    num_samples: int,
    rng_key: ArrayLike | None = None,
    nuts_args: dict = None,
    mcmc_args: dict = None,
    **kwargs: object,
) -> None:
    """
    Run the model after validating model-specific arguments.

    Validation occurs before the NumPyro kernel and MCMC objects are
    initialized. Models without model-specific run validation proceed
    unchanged. If validation, initialization, or sampling fails, ``kernel``
    and ``mcmc`` are reset to ``None``.

    Parameters
    ----------
    nuts_args
        Dictionary of arguments passed to the kernel
        [`numpyro.infer.hmc.NUTS`][] constructor.
        Defaults to None.
    mcmc_args
        Dictionary of arguments passed to the MCMC runner
        [`numpyro.infer.mcmc.MCMC`][] constructor.
        Defaults to None.
    **kwargs
        Model-specific arguments. These are validated before MCMC
        initialization and then forwarded to the model's ``sample()``
        method by the MCMC runner.

    Returns
    -------
    None
    """

    # A failed run must not leave samples from a previous run, or a
    # partially initialized runner, attached to the model.
    self.kernel = None
    self.mcmc = None

    try:
        self._validate_run_args(**kwargs)

        self._init_model(
            num_warmup=num_warmup,
            num_samples=num_samples,
            nuts_args=nuts_args,
            mcmc_args=mcmc_args,
        )
        if rng_key is None:
            rand_int = np.random.randint(
                np.iinfo(np.int64).min, np.iinfo(np.int64).max
            )
            rng_key = jr.key(rand_int)

        self.mcmc.run(rng_key=rng_key, **kwargs)
    except BaseException:
        self.kernel = None
        self.mcmc = None
        raise

    return None

sample abstractmethod

sample(**kwargs: object) -> tuple

Sample method of the model.

The method design in the class should have at least kwargs.

Parameters:

Name	Type	Description	Default
**kwargs	object	Additional keyword arguments passed through to internal sample calls, should there be any.	{}

Returns:

Type	Description
tuple

Source code in pyrenew/metaclass.py

@abstractmethod
def sample(
    self,
    **kwargs: object,
) -> tuple:
    """
    Sample method of the model.

    The method design in the class should have at least kwargs.

    Parameters
    ----------
    **kwargs
        Additional keyword arguments passed through to internal
        `sample` calls, should there be any.

    Returns
    -------
    tuple
    """
    pass

RandomVariable

RandomVariable(name: str, **kwargs: object)

Abstract base class for latent and observed random variables.

Parameters:

Name	Type	Description	Default
name	str	A non-empty string identifying this random variable.	required

Default constructor.

Parameters:

Name	Type	Description	Default
name	str	A non-empty string identifying this random variable.	required
**kwargs	object	Additional keyword arguments.	{}

Raises:

Type	Description
ValueError	If name is not a non-empty string.

Source code in pyrenew/metaclass.py

def __init__(self, name: str, **kwargs: object) -> None:
    """
    Default constructor.

    Parameters
    ----------
    name
        A non-empty string identifying this random variable.
    **kwargs
        Additional keyword arguments.

    Raises
    ------
    ValueError
        If ``name`` is not a non-empty string.
    """
    if not isinstance(name, str) or len(name) == 0:
        raise ValueError(
            f"name must be a non-empty string. Got {type(name).__name__}: {name!r}"
        )
    self.name = name

__call__

__call__(**kwargs: object) -> tuple

Alias for sample.

Source code in pyrenew/metaclass.py

def __call__(self, **kwargs: object) -> tuple:
    """
    Alias for `sample`.
    """
    return self.sample(**kwargs)

sample abstractmethod

sample(**kwargs: object) -> tuple

Sample method of the process

The method design in the class should have at least kwargs.

Parameters:

Name	Type	Description	Default
**kwargs	object	Additional keyword arguments passed through to internal sample calls, should there be any.	{}

Returns:

Type	Description
tuple

Source code in pyrenew/metaclass.py

@abstractmethod
def sample(
    self,
    **kwargs: object,
) -> tuple:
    """
    Sample method of the process

    The method design in the class should have at least kwargs.

    Parameters
    ----------
    **kwargs
        Additional keyword arguments passed through to internal
        `sample` calls, should there be any.

    Returns
    -------
    tuple
    """
    pass