pytransc.pseudoprior

 51def build_auto_pseudo_prior(
 52    ensemble_per_state: list[FloatArray],
 53    pseudo_prior_type: PseudoPriorBuilders = PseudoPriorBuilders.GAUSSIAN_MIXTURE,
 54    **builder_kwargs,
 55):
 56    """
 57    Build an automatic pseudo-prior function using a specified builder.
 58
 59    This function fits a statistical model (e.g., Gaussian mixture) to posterior
 60    ensembles from each state to create a pseudo-prior for trans-conceptual sampling.
 61
 62    Parameters
 63    ----------
 64    ensemble_per_state : list of FloatArray
 65        List of posterior samples for each state. Each array should have shape
 66        (n_samples, n_features) where n_features is the dimensionality of that state.
 67        Generate these samples using run_mcmc_per_state() or provide pre-existing
 68        posterior ensembles.
 69    pseudo_prior_type : PseudoPriorBuilders, optional
 70        Type of pseudo-prior builder to use. Default is GAUSSIAN_MIXTURE.
 71        Options include:
 72        - GAUSSIAN_MIXTURE: Standard GMM without standardization
 73        - MEAN_COVARIANCE: Simple Gaussian approximation
 74    **builder_kwargs : dict
 75        Additional arguments passed to the pseudo-prior builder (e.g., n_components,
 76        covariance_type for Gaussian mixture models).
 77
 78    Returns
 79    -------
 80    log_pseudo_prior : SampleableMultiStateDensity
 81        Callable pseudo-prior object with methods:
 82        - __call__(x, state): Evaluate log pseudo-prior at point x in given state
 83        - draw_deviate(state): Sample from pseudo-prior for given state
 84
 85    Examples
 86    --------
 87    >>> # Generate posterior ensembles for each state
 88    >>> ensemble_per_state, _ = run_mcmc_per_state(
 89    ...     n_states=3, n_dims=[2, 3, 4], n_walkers=32, n_steps=5000,
 90    ...     pos=initial_positions, log_posterior=log_post_func
 91    ... )
 92    >>>
 93    >>> # Build pseudo-prior from ensembles
 94    >>> pseudo_prior = build_auto_pseudo_prior(
 95    ...     ensemble_per_state=ensemble_per_state,
 96    ...     pseudo_prior_type=PseudoPriorBuilders.GAUSSIAN_MIXTURE,
 97    ...     n_components=3, covariance_type='full', standardize=True
 98    ... )
 99    >>>
100    >>> # Use in trans-conceptual sampler
101    >>> result = run_state_jump_sampler(..., log_pseudo_prior=pseudo_prior)
102
103    Notes
104    -----
105    This function no longer supports automatic ensemble generation. If you previously
106    used log_posterior and sampling_args parameters, please refactor to:
107
108    1. Generate ensembles explicitly using run_mcmc_per_state()
109    2. Pass the resulting ensemble_per_state to this function
110
111    This separation provides better control over sampling parameters and makes the
112    workflow more transparent.
113    """
114    if ensemble_per_state is None:
115        raise ValueError(
116            "ensemble_per_state is required and cannot be None.\n\n"
117            "The automatic ensemble generation feature has been removed for clarity.\n"
118            "Please generate posterior ensembles explicitly using run_mcmc_per_state():\n\n"
119            "  ensemble_per_state, _ = run_mcmc_per_state(\n"
120            "      n_states=n_states,\n"
121            "      n_dims=n_dims,\n"
122            "      n_walkers=n_walkers,\n"
123            "      n_steps=n_steps,\n"
124            "      pos=initial_positions,\n"
125            "      log_posterior=log_posterior_func,\n"
126            "      auto_thin=True\n"
127            "  )\n\n"
128            "Then pass the ensembles to build_auto_pseudo_prior():\n\n"
129            "  log_pseudo_prior = build_auto_pseudo_prior(\n"
130            "      ensemble_per_state=ensemble_per_state\n"
131            "  )"
132        )
133    try:
134        pseudo_prior_type = PseudoPriorBuilders(pseudo_prior_type)
135    except ValueError as e:
136        raise InputError(f"Invalid pseudo_prior_type: {pseudo_prior_type}") from e
137
138    log_pseudo_prior = pseudo_prior_factories[pseudo_prior_type](
139        ensemble_per_state, **builder_kwargs
140    )
141
142    return log_pseudo_prior

7def get_available_pseudo_priors() -> list[str]:
8    """Get a list of available pseudo-prior types."""
9    return [option.name for option in PseudoPriorBuilders]

16class PseudoPriorBuilders(StrEnum):
17    """Enum for available pseudo-prior builders."""
18
19    GAUSSIAN_MIXTURE = auto()
20    MEAN_COVARIANCE = auto()