pcntoolkit.regression_model.hbr#

Classes#

HBR

Hierarchical Bayesian Regression model implementation.

Module Contents#

class HBR(name: str = 'template', likelihood: pcntoolkit.math_functions.likelihood.Likelihood = get_default_normal_likelihood(), draws: int = 1500, tune: int = 500, cores: int = 4, chains: int = 4, nuts_sampler: str = 'nutpie', init: str = 'auto', progressbar: bool = True, is_fitted: bool = False, is_from_dict: bool = False, inference_method: str = 'mcmc', vi_iterations: int = 30000, vi_draws: int = 1000, vi_kwargs: Dict[str, Any] | None = None)#

Bases: pcntoolkit.regression_model.regression_model.RegressionModel

Hierarchical Bayesian Regression model implementation.

This class implements a Bayesian hierarchical regression model using PyMC for posterior sampling. It supports multiple likelihood functions and provides methods for model fitting, prediction, and analysis.

This class implements a Bayesian hierarchical regression model using PyMC for posterior sampling.

Parameters:

  • name (str) – Unique identifier for the model instance

  • likelihood (Likelihood) – Likelihood function to use for the model

  • draws (int, optional) – Number of samples to draw from the posterior distribution per chain, by default 1000

  • tune (int, optional) – Number of tuning samples to draw from the posterior distribution per chain, by default 500

  • cores (int, optional) – Number of cores to use for parallel sampling, by default 4

  • chains (int, optional) – Number of chains to use for parallel sampling, by default 4

  • nuts_sampler (str, optional) – NUTS sampler to use for parallel sampling, by default “nutpie”

  • init (str, optional) – Initialization method for the model, by default “auto”. External samplers such as nutpie ignore this and use their own initialization.

  • progressbar (bool, optional) – Whether to display a progress bar during sampling, by default True

  • is_fitted (bool, optional) – Whether the model has been fitted, by default False

  • is_from_dict (bool, optional) – Whether the model was created from a dictionary, by default False

  • inference_method (str, optional) – How to approximate the posterior, by default “mcmc”. One of “mcmc” (NUTS sampling), “advi” (mean-field variational inference), “pathfinder” or “laplace” (a Gaussian centred on the posterior mode, with covariance from the Hessian there); the last two are provided by pymc-extras. The variational methods are much faster but return an approximate posterior; in particular they can misestimate the width of the posterior, which propagates into the z-scores.

  • vi_iterations (int, optional) – Number of optimizer steps for inference_method=”advi”, by default 30000

  • vi_draws (int, optional) – Number of draws taken from the fitted variational approximation, by default 1000. Ignored when inference_method=”mcmc”.

  • vi_kwargs (dict, optional) – Extra keyword arguments forwarded to the variational fitter: pm.fit for “advi” (e.g. obj_optimizer, callbacks, method) and pymc_extras.fit for “pathfinder” (e.g. num_paths, jitter, importance_sampling, maxcor) and “laplace” (e.g. optimize_method, use_hessp). Ignored when inference_method=”mcmc”.

backward(X, be, Z) → xarray.DataArray#

Map Z values to Y space using MCMC samples

Parameters:

  • X (xr.DataArray) – Covariate data

  • be (xr.) – Batch effect data

  • Z (xr.DataArray) – Z-score data

Returns:

Z-values mapped to Y space

Return type:

xr.DataArray

compute_yhat(data, responsevar, X, be)#
elemwise_logp(X, be, Y) → xarray.DataArray#

Compute log-probabilities for each observation in the data.

Parameters:

  • X (xr.DataArray) – Covariate data

  • be (xr.DataArray) – Batch effect data

  • be_maps (dict[str, dict[str, int]]) – Batch effect maps

  • Y (xr.DataArray) – Response variable data

Returns:

Log-probabilities of the data

Return type:

xr.DataArray

extract_and_reshape(post_pred, observations, var_name: str) → xarray.DataArray#
fit(X: xarray.DataArray, be: xarray.DataArray, be_maps: dict[str, dict[str, int]], Y: xarray.DataArray) → None#

Fit the model to training data using MCMC sampling.

Parameters:

  • X (xr.DataArray) – Covariate data

  • be (xr.DataArray) – Batch effect data

  • be_maps (dict[str, dict[str, int]]) – Batch effect maps

  • Y (xr.DataArray) – Response variable data

Return type:

None

forward(X: xarray.DataArray, be: xarray.DataArray, Y: xarray.DataArray) → xarray.DataArray#

Map Y values to Z space using MCMC samples

Parameters:

  • X (xr.DataArray) – Covariate data

  • be (xr.DataArray) – Batch effect data

  • Y (xr.DataArray) – Response variable data

Returns:

Z-values mapped to Y space

Return type:

xr.DataArray

classmethod from_args(name: str, args: Dict[str, Any]) → HBR#

Create model instance from command line arguments.

Parameters:

  • name (str) – Name for new model instance

  • args (Dict[str, Any]) – Dictionary of command line arguments

Returns:

New model instance

Return type:

HBR

classmethod from_dict(my_dict: Dict[str, Any], path: str | None = None) → HBR#

Create model instance from serialized dictionary.

Parameters:

  • dict (Dict[str, Any]) – Dictionary containing serialized model

  • path (Optional[str], optional) – Path to load inference data from, by default None

Returns:

New model instance

Return type:

HBR

generic_MCMC_apply(X, be, Y, fn, kwargs)#

Apply a generic function to likelihood parameters

has_batch_effect() → bool#

Check if model includes batch effects.

Returns:

True if model includes batch effects, False otherwise

Return type:

bool

load_idata(path: str) → None#

Load inference data from NetCDF file.

Parameters:

path (str) – Path to load inference data from. Should end in ‘.nc’

Return type:

None

Raises:

RuntimeError – If model is fitted but inference data cannot be loaded from path

model_specific_evaluation(path: str) → None#

Save model-specific evaluation metrics.

save_idata(path: str) → None#

Save inference data to NetCDF file.

Parameters:

path (str) – Path to save inference data to. Should end in ‘.nc’

Return type:

None

Raises:

RuntimeError – If model is fitted but does not have inference data

to_dict(path: str | None = None) → Dict[str, Any]#

Serialize model to dictionary format.

Parameters:

path (Optional[str], optional) – Path to save inference data, by default None

Returns:

Dictionary containing serialized model

Return type:

Dict[str, Any]

transfer(X: xarray.DataArray, be: xarray.DataArray, be_maps: dict[str, dict[str, int]], Y: xarray.DataArray, **kwargs) → HBR#

Perform transfer learning using existing model as prior.

hbrconfHBRConf

Configuration for new model

transferdataHBRData

Data for transfer learning

freedomfloat

Parameter controlling influence of prior model (0-1)

x
HBR

New model instance with transferred knowledge

be_maps: dict = None#
chains = 4#
cores = 4#
draws = 1500#
idata: xarray.DataTree = None#
inference_method = 'mcmc'#
init = 'auto'#
likelihood#
nuts_sampler = 'nutpie'#
progressbar = True#
pymc_model: pymc.Model = None#
tune = 500#
vi_draws = 1000#
vi_iterations = 30000#
vi_kwargs#
vi_loss: pcntoolkit.math_functions.factorize.np.ndarray | None = None#