aepsych.acquisition

Submodules

aepsych.acquisition.bvn module

aepsych.acquisition.bvn.bvn_cdf(xu, yu, r)[source]

Evaluate the bivariate normal CDF.

WARNING: Implements only the routine for moderate levels of correlation. Will be inaccurate and should not be used for correlations larger than 0.925.

Standard (mean 0, var 1) bivariate normal distribution with correlation r. Evaluated from -inf to xu, and -inf to yu.

Based on function developed by Alan Genz: http://www.math.wsu.edu/faculty/genz/software/matlab/bvn.m

based in turn on Drezner, Z and G.O. Wesolowsky, (1989), On the computation of the bivariate normal inegral, Journal of Statist. Comput. Simul. 35, pp. 101-107.

Parameters:

  • xu (Tensor) – Upper limits for cdf evaluation in x

  • yu (Tensor) – Upper limits for cdf evaluation in y

  • r (Tensor) – BVN correlation

Return type:

Tensor

Returns: Tensor of cdf evaluations of same size as xu, yu, and r.

aepsych.acquisition.lookahead module

aepsych.acquisition.lookahead.Hb(p)[source]

Binary entropy.

Parameters:

p (Tensor) – Tensor of probabilities.

Returns: Binary entropy for each probability.

aepsych.acquisition.lookahead.MI_fn(Px, P1, P0, py1)[source]

Average mutual information. H(p) - E_y*[H(p | y*)]

Parameters:

  • Px (Tensor) – (b x m) Level-set posterior before observation

  • P1 (Tensor) – (b x m) Level-set posterior given observation of 1

  • P0 (Tensor) – (b x m) Level-set posterior given observation of 0

  • py1 (Tensor) – (b x 1) Probability of observing 1

Return type:

Tensor

Returns: (b) tensor of mutual information averaged over Xq.

aepsych.acquisition.lookahead.ClassErr(p)[source]

Expected classification error, min(p, 1-p).

Parameters:

p (Tensor) –

Return type:

Tensor

aepsych.acquisition.lookahead.SUR_fn(Px, P1, P0, py1)[source]

Stepwise uncertainty reduction.

Expected reduction in expected classification error given observation at Xstar, averaged over Xq.

Parameters:

  • Px (Tensor) – (b x m) Level-set posterior before observation

  • P1 (Tensor) – (b x m) Level-set posterior given observation of 1

  • P0 (Tensor) – (b x m) Level-set posterior given observation of 0

  • py1 (Tensor) – (b x 1) Probability of observing 1

Return type:

Tensor

Returns: (b) tensor of SUR values.

aepsych.acquisition.lookahead.EAVC_fn(Px, P1, P0, py1)[source]

Expected absolute value change.

Expected absolute change in expected level-set volume given observation at Xstar.

Parameters:

  • Px (Tensor) – (b x m) Level-set posterior before observation

  • P1 (Tensor) – (b x m) Level-set posterior given observation of 1

  • P0 (Tensor) – (b x m) Level-set posterior given observation of 0

  • py1 (Tensor) – (b x 1) Probability of observing 1

Return type:

Tensor

Returns: (b) tensor of EAVC values.

class aepsych.acquisition.lookahead.LookaheadAcquisitionFunction(*args, **kwargs)[source]

Bases: AcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) – The gpytorch model.

  • target (Optional[float]) – Threshold value to target in p-space.

  • lookahead_type (str) –

class aepsych.acquisition.lookahead.LocalLookaheadAcquisitionFunction(*args, **kwargs)[source]

Bases: LookaheadAcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) – The gpytorch model.

  • target (Optional[float]) – Threshold value to target in p-space.

  • lookahead_type (str) –

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

forward(X)

Evaluate acquisition function at X.

Parameters:

X (Tensor) – (b x 1 x d) point at which to evalaute acquisition function.

Return type:

Tensor

Returns: (b) tensor of acquisition values.

class aepsych.acquisition.lookahead.LocalMI(*args, **kwargs)[source]

Bases: LocalLookaheadAcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.lookahead.LocalSUR(*args, **kwargs)[source]

Bases: LocalLookaheadAcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

aepsych.acquisition.lookahead.construct_inputs_local_lookahead(model, training_data, lookahead_type='levelset', target=None, posterior_transform=None, **kwargs)
Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) –

  • target (Optional[float]) –

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

class aepsych.acquisition.lookahead.GlobalLookaheadAcquisitionFunction(*args, **kwargs)[source]

Bases: LookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) – The gpytorch model.

  • target (Optional[float]) – Threshold value to target in p-space.

  • Xq (Optional[Tensor]) – (m x d) global reference set.

  • lookahead_type (str) –

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

  • query_set_size (Optional[int]) –

forward(X)

Evaluate acquisition function at X.

Parameters:

X (Tensor) – (b x 1 x d) point at which to evalaute acquisition function.

Return type:

Tensor

Returns: (b) tensor of acquisition values.

class aepsych.acquisition.lookahead.GlobalMI(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.lookahead.GlobalSUR(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.lookahead.ApproxGlobalSUR(*args, **kwargs)[source]

Bases: GlobalSUR

A global look-ahead acquisition function.

Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) – The gpytorch model.

  • target (Optional[float]) – Threshold value to target in p-space.

  • Xq (Optional[Tensor]) – (m x d) global reference set.

  • query_set_size (Optional[int]) –

class aepsych.acquisition.lookahead.EAVC(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.lookahead.MOCU(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

MOCU acquisition function given in expr. 4 of:

Zhao, Guang, et al. “Uncertainty-aware active learning for optimal Bayesian classifier.” International Conference on Learning Representations (ICLR) 2021.

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.lookahead.SMOCU(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

SMOCU acquisition function given in expr. 11 of:

Zhao, Guang, et al. “Bayesian active learning by soft mean objective cost of uncertainty.” International Conference on Artificial Intelligence and Statistics (AISTATS) 2021.

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

class aepsych.acquisition.lookahead.BEMPS(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

BEMPS acquisition function given in:

Tan, Wei, et al. “Diversity Enhanced Active Learning with Strictly Proper Scoring Rules.” Advances in Neural Information Processing Systems 34 (2021).

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

aepsych.acquisition.lookahead.construct_inputs_global_lookahead(model, training_data, lookahead_type='levelset', target=None, posterior_transform=None, query_set_size=256, Xq=None, **kwargs)
Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) –

  • target (Optional[float]) –

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

  • query_set_size (Optional[int]) –

  • Xq (Optional[Tensor]) –

aepsych.acquisition.lookahead_utils module

aepsych.acquisition.lookahead_utils.posterior_at_xstar_xq(model, Xstar, Xq, posterior_transform=None)[source]

Evaluate the posteriors of f at single point Xstar and set of points Xq.

Parameters:

  • model (GP) – The model to evaluate.

  • Xstar (Tensor) – (b x 1 x d) tensor.

  • Xq (Tensor) – (b x m x d) tensor.

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

Returns:

(b x 1) mean at Xstar. Sigma2_s: (b x 1) variance at Xstar. Mu_q: (b x m) mean at Xq. Sigma2_q: (b x m) variance at Xq. Sigma_sq: (b x m) covariance between Xstar and each point in Xq.

Return type:

Mu_s

aepsych.acquisition.lookahead_utils.lookahead_levelset_at_xstar(model, Xstar, Xq, posterior_transform=None, **kwargs)[source]

Evaluate the look-ahead level-set posterior at Xq given observation at xstar.

Parameters:

  • model (GP) – The model to evaluate.

  • Xstar (Tensor) – (b x 1 x d) observation point.

  • Xq (Tensor) – (b x m x d) reference points.

  • gamma – Threshold in f-space.

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

  • kwargs (Dict[str, Any]) –

Returns:

(b x m) Level-set posterior at Xq, before observation at xstar. P1: (b x m) Level-set posterior at Xq, given observation of 1 at xstar. P0: (b x m) Level-set posterior at Xq, given observation of 0 at xstar. py1: (b x 1) Probability of observing 1 at xstar.

Return type:

Px

aepsych.acquisition.lookahead_utils.lookahead_p_at_xstar(model, Xstar, Xq, posterior_transform=None, **kwargs)[source]

Evaluate the look-ahead response probability posterior at Xq given observation at xstar.

Uses the approximation given in expr. 9 in: Zhao, Guang, et al. “Efficient active learning for Gaussian process classification by error reduction.” Advances in Neural Information Processing Systems 34 (2021): 9734-9746.

Parameters:

  • model (GP) – The model to evaluate.

  • Xstar (Tensor) – (b x 1 x d) observation point.

  • Xq (Tensor) – (b x m x d) reference points.

  • kwargs (Dict[str, Any]) – ignored (here for compatibility with other kinds of lookahead)

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

Returns:

(b x m) Response posterior at Xq, before observation at xstar. P1: (b x m) Response posterior at Xq, given observation of 1 at xstar. P0: (b x m) Response posterior at Xq, given observation of 0 at xstar. py1: (b x 1) Probability of observing 1 at xstar.

Return type:

Px

aepsych.acquisition.lookahead_utils.approximate_lookahead_levelset_at_xstar(model, Xstar, Xq, gamma, posterior_transform=None)[source]

The look-ahead posterior approximation of Lyu et al.

Parameters:

  • model (GP) – The model to evaluate.

  • Xstar (Tensor) – (b x 1 x d) observation point.

  • Xq (Tensor) – (b x m x d) reference points.

  • gamma (float) – Threshold in f-space.

  • posterior_transform (Optional[botorch.acquisition.objective.PosteriorTransform]) –

Returns:

(b x m) Level-set posterior at Xq, before observation at xstar. P1: (b x m) Level-set posterior at Xq, given observation of 1 at xstar. P0: (b x m) Level-set posterior at Xq, given observation of 0 at xstar. py1: (b x 1) Probability of observing 1 at xstar.

Return type:

Px

aepsych.acquisition.lse module

class aepsych.acquisition.lse.MCLevelSetEstimation(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Monte-carlo level set estimation.

Parameters:

  • model (botorch.models.model.Model) – A fitted model.

  • target (Union[float, Tensor]) – the level set (after objective transform) to be estimated

  • beta (Union[float, Tensor]) – a parameter that governs explore-exploit tradeoff

  • objective (Optional[botorch.acquisition.monte_carlo.MCAcquisitionObjective]) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit.) applied on the samples. Can be implemented via GenericMCObjective.

  • sampler (Optional[botorch.acquisition.monte_carlo.MCSampler]) – The sampler used for drawing MC samples.

acquisition(obj_samples)[source]

Evaluate the acquisition based on objective samples.

Usually you should not call this directly unless you are subclassing this class and modifying how objective samples are generated.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed by the objective. Should be samples x batch_shape.

Returns:

Acquisition function at the sampled values.

Return type:

torch.Tensor

forward(X)

Evaluate the acquisition function

Parameters:

X (torch.Tensor) – Points at which to evaluate.

Returns:

Value of the acquisition functiona at these points.

Return type:

torch.Tensor

aepsych.acquisition.lse.construct_inputs_lse(model, training_data, objective=None, target=0.75, beta=3.84, sampler=None, **kwargs)

aepsych.acquisition.mc_posterior_variance module

aepsych.acquisition.mc_posterior_variance.balv_acq(obj_samps)[source]

Evaluate BALV (posterior variance) on a set of objective samples.

Parameters:

obj_samps (torch.Tensor) – Samples from the GP, transformed by the objective. Should be samples x batch_shape.

Returns:

Acquisition function value.

Return type:

torch.Tensor

class aepsych.acquisition.mc_posterior_variance.MCPosteriorVariance(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Posterior variance, computed using samples so we can use objective/transform

Posterior Variance of Link Function

Parameters:

  • model (botorch.models.model.Model) – A fitted model.

  • objective (Optional[botorch.acquisition.objective.MCAcquisitionObjective]) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit.) applied on the difference of (usually 1-d) two samples. Can be implemented via GenericMCObjective.

  • sampler (Optional[botorch.sampling.base.MCSampler]) – The sampler used for drawing MC samples.

forward(X)

Evaluate MCPosteriorVariance on the candidate set X.

Parameters:

X (Tensor) – A batch_size x q x d-dim Tensor

Returns:

Posterior variance of link function at X that active learning hopes to maximize

Return type:

Tensor

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

aepsych.acquisition.mc_posterior_variance.construct_inputs(model, training_data, objective=None, sampler=None, **kwargs)
class aepsych.acquisition.mc_posterior_variance.MonotonicMCPosteriorVariance(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Initialize MonotonicMCAcquisition

Parameters:

  • model (Model) – Model to use, usually a MonotonicRejectionGP.

  • num_samples (int, optional) – Number of samples to keep from the rejection sampler. . Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples to draw. Defaults to 1024.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform of the GP output before evaluating the acquisition. Defaults to identity transform.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

aepsych.acquisition.monotonic_rejection module

class aepsych.acquisition.monotonic_rejection.MonotonicMCAcquisition(*args, **kwargs)[source]

Bases: AcquisitionFunction

Acquisition function base class for use with the rejection sampling

monotonic GP. This handles the bookkeeping of the derivative constraint points – implement specific monotonic MC acquisition in subclasses.

Initialize MonotonicMCAcquisition

Parameters:

  • model (Model) – Model to use, usually a MonotonicRejectionGP.

  • num_samples (int, optional) – Number of samples to keep from the rejection sampler. . Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples to draw. Defaults to 1024.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform of the GP output before evaluating the acquisition. Defaults to identity transform.

  • deriv_constraint_points (torch.Tensor) –

forward(X)[source]

Evaluate the acquisition function at a set of points.

Parameters:

X (Tensor) – Points at which to evaluate the acquisition function. Should be (b) x q x d, and q should be 1.

Returns:

Acquisition function value at these points.

Return type:

Tensor

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

class aepsych.acquisition.monotonic_rejection.MonotonicMCLSE(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Level set estimation acquisition function for use with monotonic models.

Parameters:

  • model (Model) – Underlying model object, usually should be MonotonicRejectionGP.

  • target (float) – Level set value to target (after the objective).

  • num_samples (int, optional) – Number of MC samples to draw in MC acquisition. Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples from which to subsample monotonic ones. Defaults to 1024.

  • beta (float, optional) – Parameter of the LSE acquisition function that governs exploration vs exploitation (similarly to the same parameter in UCB). Defaults to 3.84 (1.96 ** 2), which maps to the straddle heuristic of Bryan et al. 2005.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform. Defaults to identity transform.

  • deriv_constraint_points (torch.Tensor) –

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

aepsych.acquisition.mutual_information module

aepsych.acquisition.mutual_information.bald_acq(obj_samples)[source]

Evaluate Mutual Information acquisition function.

With latent function F and X a hypothetical observation at a new point, I(F; X) = I(X; F) = H(X) - H(X |F), H(X |F ) = E_{f} (H(X |F =f ) i.e., we take the posterior entropy of the (Bernoulli) observation X given the current model posterior and subtract the conditional entropy on F, that being the mean entropy over the posterior for F. This is equivalent to the BALD acquisition function in Houlsby et al. NeurIPS 2012.

Parameters:

obj_samples (torch.Tensor) – Objective samples from the GP, of shape num_samples x batch_shape x d_out

Returns:

Value of acquisition at samples.

Return type:

torch.Tensor

class aepsych.acquisition.mutual_information.BernoulliMCMutualInformation(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Mutual Information acquisition function for a bernoulli outcome.

Given a model and an objective link function, calculate the mutual information of a trial at a new point and the distribution on the latent function.

Objective here should give values in (0, 1) (e.g. logit or probit).

Single Bernoulli mutual information for active learning

Parameters:

  • model (Model) – A fitted model.

  • objective (MCAcquisitionObjective) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit)

  • sampler (MCSampler, optional) – The sampler used for drawing MC samples.

forward(X)

Evaluate mutual information on the candidate set X.

Parameters:

X (Tensor) – A batch_size x q x d-dim Tensor.

Returns:

Tensor of shape batch_size x q representing the mutual information of a hypothetical trial at X that active learning hopes to maximize.

Return type:

Tensor

acquisition(obj_samples)[source]

Evaluate the acquisition function value based on samples.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed through the objective.

Returns:

value of the acquisition function (BALD) at the input samples.

Return type:

torch.Tensor

aepsych.acquisition.mutual_information.construct_inputs_mi(model, training_data, objective=None, sampler=None, **kwargs)
class aepsych.acquisition.mutual_information.MonotonicBernoulliMCMutualInformation(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Initialize MonotonicMCAcquisition

Parameters:

  • model (Model) – Model to use, usually a MonotonicRejectionGP.

  • num_samples (int, optional) – Number of samples to keep from the rejection sampler. . Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples to draw. Defaults to 1024.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform of the GP output before evaluating the acquisition. Defaults to identity transform.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

acquisition(obj_samples)[source]

Evaluate the acquisition function value based on samples.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed through the objective.

Returns:

value of the acquisition function (BALD) at the input samples.

Return type:

torch.Tensor

aepsych.acquisition.objective module

class aepsych.acquisition.objective.AEPsychObjective(*args, **kwargs)[source]

Bases: MCAcquisitionObjective

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

inverse(samples, X=None)[source]
Parameters:

  • samples (Tensor) –

  • X (Optional[Tensor]) –

Return type:

Tensor

class aepsych.acquisition.objective.FloorGumbelObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Gumbel CDF but with a floor so that its output is between floor and 1.0. Note that this is not the standard Gumbel distribution, but rather the left-skewed Gumbel that arises as the log of the Weibull distribution, e.g. Treutwein 1995, doi:10.1016/0042-6989(95)00016-X.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.objective.FloorLogitObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Logistic sigmoid (aka expit, aka logistic CDF), but with a floor so that its output is between floor and 1.0.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.objective.FloorProbitObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Probit (aka Gaussian CDF), but with a floor so that its output is between floor and 1.0.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.objective.ProbitObjective(*args, **kwargs)[source]

Bases: AEPsychObjective

Probit objective

Transforms the input through the normal CDF (probit).

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

forward(samples, X=None)[source]

Evaluates the objective (normal CDF).

Parameters:

  • samples (Tensor) – GP samples.

  • X (Optional[Tensor], optional) – ignored, here for compatibility with MCAcquisitionObjective.

Returns:

[description]

Return type:

Tensor

inverse(samples, X=None)[source]

Evaluates the inverse of the objective (normal PPF).

Parameters:

  • samples (Tensor) – GP samples.

  • X (Optional[Tensor], optional) – ignored, here for compatibility with MCAcquisitionObjective.

Returns:

[description]

Return type:

Tensor

class aepsych.acquisition.objective.SemiPProbabilityObjective(*args, **kwargs)[source]

Bases: SemiPObjectiveBase

Wraps the semi-parametric transform into an objective that gives outcome probabilities

Evaluates the probability objective.

Parameters:

  • likelihood (Likelihood). Underlying SemiP likelihood (which we use for its objective/link) –

  • class (other arguments are passed to the base) –

forward(samples, X)[source]

Evaluates the probability objective.

Parameters:

  • samples (Tensor) – GP samples.

  • X (Tensor) – Inputs at which to evaluate objective. Unlike most AEPsych objectives, we need X here to split out the intensity dimension.

Returns:

Response probabilities at the specific X values and function samples.

Return type:

Tensor

classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.acquisition.objective.SemiPThresholdObjective(*args, **kwargs)[source]

Bases: SemiPObjectiveBase

Wraps the semi-parametric transform into an objective that gives the threshold distribution.

Evaluates the probability objective.

Parameters:

  • target (float) – the threshold to evaluate.

  • likelihood (Likelihood) – Underlying SemiP likelihood (which we use for its inverse link)

  • class (other arguments are passed to the base) –

forward(samples, X=None)[source]

Evaluates the probability objective.

Parameters:

  • samples (Tensor) – GP samples.

  • X (Tensor, optional) – Ignored, here for compatibility with the objective API.

Returns:

Threshold probabilities at the specific GP sample values.

Return type:

Tensor

classmethod from_config(config)[source]
Parameters:

config (Config) –

aepsych.acquisition.rejection_sampler module

class aepsych.acquisition.rejection_sampler.RejectionSampler(*args, **kwargs)[source]

Bases: MCSampler

Samples from a posterior subject to the constraint that samples in constrained_idx should be >= 0.

If not enough feasible samples are generated, will return the least violating samples.

Initialize RejectionSampler

Parameters:

  • num_samples (int) – Number of samples to return. Note that if fewer samples than this number are positive in the required dimension, the remaining samples returned will be the “least violating”, i.e. closest to 0.

  • num_rejection_samples (int) – Number of samples to draw before rejecting.

  • constrained_idx (Tensor) – Indices of input dimensions that should be constrained positive.

forward(posterior)[source]

Run the rejection sampler.

Parameters:

posterior (Posterior) – The unconstrained GP posterior object to perform rejection samples on.

Returns:

Kept samples.

Return type:

Tensor

Module contents

class aepsych.acquisition.BernoulliMCMutualInformation(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Mutual Information acquisition function for a bernoulli outcome.

Given a model and an objective link function, calculate the mutual information of a trial at a new point and the distribution on the latent function.

Objective here should give values in (0, 1) (e.g. logit or probit).

Single Bernoulli mutual information for active learning

Parameters:

  • model (Model) – A fitted model.

  • objective (MCAcquisitionObjective) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit)

  • sampler (MCSampler, optional) – The sampler used for drawing MC samples.

forward(X)

Evaluate mutual information on the candidate set X.

Parameters:

X (Tensor) – A batch_size x q x d-dim Tensor.

Returns:

Tensor of shape batch_size x q representing the mutual information of a hypothetical trial at X that active learning hopes to maximize.

Return type:

Tensor

acquisition(obj_samples)[source]

Evaluate the acquisition function value based on samples.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed through the objective.

Returns:

value of the acquisition function (BALD) at the input samples.

Return type:

torch.Tensor

class aepsych.acquisition.MonotonicBernoulliMCMutualInformation(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Initialize MonotonicMCAcquisition

Parameters:

  • model (Model) – Model to use, usually a MonotonicRejectionGP.

  • num_samples (int, optional) – Number of samples to keep from the rejection sampler. . Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples to draw. Defaults to 1024.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform of the GP output before evaluating the acquisition. Defaults to identity transform.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

acquisition(obj_samples)[source]

Evaluate the acquisition function value based on samples.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed through the objective.

Returns:

value of the acquisition function (BALD) at the input samples.

Return type:

torch.Tensor

class aepsych.acquisition.MonotonicMCLSE(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Level set estimation acquisition function for use with monotonic models.

Parameters:

  • model (Model) – Underlying model object, usually should be MonotonicRejectionGP.

  • target (float) – Level set value to target (after the objective).

  • num_samples (int, optional) – Number of MC samples to draw in MC acquisition. Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples from which to subsample monotonic ones. Defaults to 1024.

  • beta (float, optional) – Parameter of the LSE acquisition function that governs exploration vs exploitation (similarly to the same parameter in UCB). Defaults to 3.84 (1.96 ** 2), which maps to the straddle heuristic of Bryan et al. 2005.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform. Defaults to identity transform.

  • deriv_constraint_points (torch.Tensor) –

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

class aepsych.acquisition.MCPosteriorVariance(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Posterior variance, computed using samples so we can use objective/transform

Posterior Variance of Link Function

Parameters:

  • model (botorch.models.model.Model) – A fitted model.

  • objective (Optional[botorch.acquisition.objective.MCAcquisitionObjective]) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit.) applied on the difference of (usually 1-d) two samples. Can be implemented via GenericMCObjective.

  • sampler (Optional[botorch.sampling.base.MCSampler]) – The sampler used for drawing MC samples.

forward(X)

Evaluate MCPosteriorVariance on the candidate set X.

Parameters:

X (Tensor) – A batch_size x q x d-dim Tensor

Returns:

Posterior variance of link function at X that active learning hopes to maximize

Return type:

Tensor

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

class aepsych.acquisition.MonotonicMCPosteriorVariance(*args, **kwargs)[source]

Bases: MonotonicMCAcquisition

Initialize MonotonicMCAcquisition

Parameters:

  • model (Model) – Model to use, usually a MonotonicRejectionGP.

  • num_samples (int, optional) – Number of samples to keep from the rejection sampler. . Defaults to 32.

  • num_rejection_samples (int, optional) – Number of rejection samples to draw. Defaults to 1024.

  • objective (Optional[MCAcquisitionObjective], optional) – Objective transform of the GP output before evaluating the acquisition. Defaults to identity transform.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

acquisition(obj_samples)[source]
Parameters:

obj_samples (Tensor) –

Return type:

Tensor

class aepsych.acquisition.MCLevelSetEstimation(*args, **kwargs)[source]

Bases: MCAcquisitionFunction

Monte-carlo level set estimation.

Parameters:

  • model (botorch.models.model.Model) – A fitted model.

  • target (Union[float, Tensor]) – the level set (after objective transform) to be estimated

  • beta (Union[float, Tensor]) – a parameter that governs explore-exploit tradeoff

  • objective (Optional[botorch.acquisition.monte_carlo.MCAcquisitionObjective]) – An MCAcquisitionObjective representing the link function (e.g., logistic or probit.) applied on the samples. Can be implemented via GenericMCObjective.

  • sampler (Optional[botorch.acquisition.monte_carlo.MCSampler]) – The sampler used for drawing MC samples.

acquisition(obj_samples)[source]

Evaluate the acquisition based on objective samples.

Usually you should not call this directly unless you are subclassing this class and modifying how objective samples are generated.

Parameters:

obj_samples (torch.Tensor) – Samples from the model, transformed by the objective. Should be samples x batch_shape.

Returns:

Acquisition function at the sampled values.

Return type:

torch.Tensor

forward(X)

Evaluate the acquisition function

Parameters:

X (torch.Tensor) – Points at which to evaluate.

Returns:

Value of the acquisition functiona at these points.

Return type:

torch.Tensor

class aepsych.acquisition.ProbitObjective(*args, **kwargs)[source]

Bases: AEPsychObjective

Probit objective

Transforms the input through the normal CDF (probit).

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

forward(samples, X=None)[source]

Evaluates the objective (normal CDF).

Parameters:

  • samples (Tensor) – GP samples.

  • X (Optional[Tensor], optional) – ignored, here for compatibility with MCAcquisitionObjective.

Returns:

[description]

Return type:

Tensor

inverse(samples, X=None)[source]

Evaluates the inverse of the objective (normal PPF).

Parameters:

  • samples (Tensor) – GP samples.

  • X (Optional[Tensor], optional) – ignored, here for compatibility with MCAcquisitionObjective.

Returns:

[description]

Return type:

Tensor

class aepsych.acquisition.FloorProbitObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Probit (aka Gaussian CDF), but with a floor so that its output is between floor and 1.0.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.FloorLogitObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Logistic sigmoid (aka expit, aka logistic CDF), but with a floor so that its output is between floor and 1.0.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.FloorGumbelObjective(*args, **kwargs)[source]

Bases: FloorLinkObjective

Gumbel CDF but with a floor so that its output is between floor and 1.0. Note that this is not the standard Gumbel distribution, but rather the left-skewed Gumbel that arises as the log of the Weibull distribution, e.g. Treutwein 1995, doi:10.1016/0042-6989(95)00016-X.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.GlobalMI(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.GlobalSUR(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.ApproxGlobalSUR(*args, **kwargs)[source]

Bases: GlobalSUR

A global look-ahead acquisition function.

Parameters:

  • model (botorch.models.gpytorch.GPyTorchModel) – The gpytorch model.

  • target (Optional[float]) – Threshold value to target in p-space.

  • Xq (Optional[Tensor]) – (m x d) global reference set.

  • query_set_size (Optional[int]) –

class aepsych.acquisition.EAVC(*args, **kwargs)[source]

Bases: GlobalLookaheadAcquisitionFunction

A global look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • Xq – (m x d) global reference set.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.LocalMI(*args, **kwargs)[source]

Bases: LocalLookaheadAcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

class aepsych.acquisition.LocalSUR(*args, **kwargs)[source]

Bases: LocalLookaheadAcquisitionFunction

A localized look-ahead acquisition function.

Parameters:

  • model – The gpytorch model.

  • target – Threshold value to target in p-space.

  • args (Any) –

  • kwargs (Any) –

Return type:

Any