aepsych.generators

Submodules

aepsych.generators.base module

class aepsych.generators.base.AcqArgProtocol(*args, **kwargs)[source]

Bases: Protocol

classmethod from_config(config)[source]
Parameters:

config (Config) –

Return type:

Any

class aepsych.generators.base.AEPsychGenerator[source]

Bases: ABC, Generic[AEPsychModelType]

Abstract base class for generators, which are responsible for generating new points to sample.

baseline_requiring_acqfs = [botorch.acquisition.qNoisyExpectedImprovement, botorch.acquisition.NoisyExpectedImprovement]
stimuli_per_trial = 1
max_asks: Optional[int] = None
abstract gen(num_points, model)[source]
Parameters:

  • num_points (int) –

  • model (AEPsychModelType) –

Return type:

Tensor

abstract classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.base.AEPsychGenerationStep(name, **kwargs)[source]

Bases: GenerationStep, ConfigurableMixin, ABC

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

finished(experiment)[source]
Parameters:

experiment (Experiment) –

aepsych.generators.epsilon_greedy_generator module

class aepsych.generators.epsilon_greedy_generator.EpsilonGreedyGenerator(subgenerator, epsilon=0.1)[source]

Bases: AEPsychGenerator

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

gen(num_points, model)[source]
Parameters:

aepsych.generators.manual_generator module

class aepsych.generators.manual_generator.ManualGenerator(lb, ub, points, dim=None, shuffle=True)[source]

Bases: AEPsychGenerator

Generator that generates points from the Sobol Sequence.

Iniatialize SobolGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param points: The points that will be generated. :type points: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional :param shuffle: Whether or not to shuffle the order of the points. True by default. :type shuffle: bool

Parameters:

  • lb (Union[ndarray, Tensor]) –

  • ub (Union[ndarray, Tensor]) –

  • points (Union[ndarray, Tensor]) –

  • dim (Optional[int]) –

  • shuffle (bool) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by quasi-randomly sampling the parameter space. :param num_points: Number of points to query. :type num_points: int

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

aepsych.generators.monotonic_rejection_generator module

aepsych.generators.monotonic_rejection_generator.default_loss_constraint_fun(loss, candidates)[source]

Identity transform for constrained optimization.

This simply returns loss as-is. Write your own versions of this for constrained optimization by e.g. interior point method.

Parameters:

  • loss (torch.Tensor) – Value of loss at candidate points.

  • candidates (torch.Tensor) – Location of candidate points.

Returns:

New loss (unchanged)

Return type:

torch.Tensor

class aepsych.generators.monotonic_rejection_generator.MonotonicRejectionGenerator(acqf, acqf_kwargs=None, model_gen_options=None, explore_features=None)[source]

Bases: AEPsychGenerator[MonotonicRejectionGP]

Generator specifically to be used with MonotonicRejectionGP, which generates new points to sample by minimizing an acquisition function through stochastic gradient descent.

Initialize MonotonicRejectionGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • model_gen_options (Optional[Dict[str, Any]]) – Dictionary with options for generating candidate, such as SGD parameters. See code for all options and their defaults.

  • explore_features (Optional[Sequence[int]]) – List of features that will be selected randomly and then fixed for acquisition fn optimization.

  • acqf (MonotonicMCAcquisition) –

  • acqf_kwargs (Dict[str, object], optional) –

gen(num_points, model)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: AEPsychMixin

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

aepsych.generators.monotonic_thompson_sampler_generator module

class aepsych.generators.monotonic_thompson_sampler_generator.MonotonicThompsonSamplerGenerator(n_samples, n_rejection_samples, num_ts_points, target_value, objective, explore_features=None)[source]

Bases: AEPsychGenerator[MonotonicRejectionGP]

A generator specifically to be used with MonotonicRejectionGP that uses a Thompson-sampling-style approach for gen, rather than using an acquisition function. We draw a posterior sample at a large number of points, and then choose the point that is closest to the target value.

Initialize MonotonicMCAcquisition

Parameters:

  • n_samples (int) – Number of samples to select point from.

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

  • num_ts_points (int) – Number of points at which to sample.

  • target_value (float) – target value that is being looked for

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

  • explore_features (Sequence[int], optional) –

  • n_rejection_samples (int) –

gen(num_points, model)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: AEPsychMixin

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

aepsych.generators.optimize_acqf_generator module

class aepsych.generators.optimize_acqf_generator.OptimizeAcqfGenerator(acqf, acqf_kwargs=None, restarts=10, samps=1000, max_gen_time=None, stimuli_per_trial=1)[source]

Bases: AEPsychGenerator

Generator that chooses points by minimizing an acquisition function.

Initialize OptimizeAcqfGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • restarts (int) – Number of restarts for acquisition function optimization.

  • samps (int) – Number of samples for quasi-random initialization of the acquisition function optimizer.

  • max_gen_time (optional, float) – Maximum time (in seconds) to optimize the acquisition function.

  • acqf (AcquisitionFunction) –

  • acqf_kwargs (Dict[str, object], optional) –

  • stimuli_per_trial (int) –

gen(num_points, model, **gen_options)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: ModelProtocol

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

class aepsych.generators.optimize_acqf_generator.AxOptimizeAcqfGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep, ConfigurableMixin

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

aepsych.generators.random_generator module

class aepsych.generators.random_generator.RandomGenerator(lb, ub, dim=None)[source]

Bases: AEPsychGenerator

Generator that generates points randomly without an acquisition function.

Iniatialize RandomGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional

Parameters:

  • lb (Union[ndarray, Tensor]) –

  • ub (Union[ndarray, Tensor]) –

  • dim (Optional[int]) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by randomly sampling the parameter space. :param num_points: Number of points to query. Currently, only 1 point can be queried at a time. :type num_points: int, optional

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.random_generator.AxRandomGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep

classname = 'RandomGenerator'
model: Union[ModelRegistryBase, Callable[..., ModelBridge]] = 'Uniform'
classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

aepsych.generators.sobol_generator module

class aepsych.generators.sobol_generator.SobolGenerator(lb, ub, dim=None, seed=None, stimuli_per_trial=1)[source]

Bases: AEPsychGenerator

Generator that generates points from the Sobol Sequence.

Iniatialize SobolGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional :param seed: Random seed. :type seed: int, optional

Parameters:

  • lb (Union[np.ndarray, torch.Tensor]) –

  • ub (Union[np.ndarray, torch.Tensor]) –

  • dim (Optional[int]) –

  • seed (Optional[int]) –

  • stimuli_per_trial (int) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by quasi-randomly sampling the parameter space. :param num_points: Number of points to query. :type num_points: int, optional

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

class aepsych.generators.sobol_generator.AxSobolGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

Module contents

class aepsych.generators.OptimizeAcqfGenerator(acqf, acqf_kwargs=None, restarts=10, samps=1000, max_gen_time=None, stimuli_per_trial=1)[source]

Bases: AEPsychGenerator

Generator that chooses points by minimizing an acquisition function.

Initialize OptimizeAcqfGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • restarts (int) – Number of restarts for acquisition function optimization.

  • samps (int) – Number of samples for quasi-random initialization of the acquisition function optimizer.

  • max_gen_time (optional, float) – Maximum time (in seconds) to optimize the acquisition function.

  • acqf (AcquisitionFunction) –

  • acqf_kwargs (Dict[str, object], optional) –

  • stimuli_per_trial (int) –

gen(num_points, model, **gen_options)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: ModelProtocol

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

class aepsych.generators.MonotonicRejectionGenerator(acqf, acqf_kwargs=None, model_gen_options=None, explore_features=None)[source]

Bases: AEPsychGenerator[MonotonicRejectionGP]

Generator specifically to be used with MonotonicRejectionGP, which generates new points to sample by minimizing an acquisition function through stochastic gradient descent.

Initialize MonotonicRejectionGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • model_gen_options (Optional[Dict[str, Any]]) – Dictionary with options for generating candidate, such as SGD parameters. See code for all options and their defaults.

  • explore_features (Optional[Sequence[int]]) – List of features that will be selected randomly and then fixed for acquisition fn optimization.

  • acqf (MonotonicMCAcquisition) –

  • acqf_kwargs (Dict[str, object], optional) –

gen(num_points, model)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: AEPsychMixin

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.MonotonicThompsonSamplerGenerator(n_samples, n_rejection_samples, num_ts_points, target_value, objective, explore_features=None)[source]

Bases: AEPsychGenerator[MonotonicRejectionGP]

A generator specifically to be used with MonotonicRejectionGP that uses a Thompson-sampling-style approach for gen, rather than using an acquisition function. We draw a posterior sample at a large number of points, and then choose the point that is closest to the target value.

Initialize MonotonicMCAcquisition

Parameters:

  • n_samples (int) – Number of samples to select point from.

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

  • num_ts_points (int) – Number of points at which to sample.

  • target_value (float) – target value that is being looked for

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

  • explore_features (Sequence[int], optional) –

  • n_rejection_samples (int) –

gen(num_points, model)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: AEPsychMixin

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.RandomGenerator(lb, ub, dim=None)[source]

Bases: AEPsychGenerator

Generator that generates points randomly without an acquisition function.

Iniatialize RandomGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional

Parameters:

  • lb (Union[ndarray, Tensor]) –

  • ub (Union[ndarray, Tensor]) –

  • dim (Optional[int]) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by randomly sampling the parameter space. :param num_points: Number of points to query. Currently, only 1 point can be queried at a time. :type num_points: int, optional

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.SobolGenerator(lb, ub, dim=None, seed=None, stimuli_per_trial=1)[source]

Bases: AEPsychGenerator

Generator that generates points from the Sobol Sequence.

Iniatialize SobolGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional :param seed: Random seed. :type seed: int, optional

Parameters:

  • lb (Union[np.ndarray, torch.Tensor]) –

  • ub (Union[np.ndarray, torch.Tensor]) –

  • dim (Optional[int]) –

  • seed (Optional[int]) –

  • stimuli_per_trial (int) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by quasi-randomly sampling the parameter space. :param num_points: Number of points to query. :type num_points: int, optional

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

class aepsych.generators.EpsilonGreedyGenerator(subgenerator, epsilon=0.1)[source]

Bases: AEPsychGenerator

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

gen(num_points, model)[source]
Parameters:
class aepsych.generators.ManualGenerator(lb, ub, points, dim=None, shuffle=True)[source]

Bases: AEPsychGenerator

Generator that generates points from the Sobol Sequence.

Iniatialize SobolGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param points: The points that will be generated. :type points: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional :param shuffle: Whether or not to shuffle the order of the points. True by default. :type shuffle: bool

Parameters:

  • lb (Union[ndarray, Tensor]) –

  • ub (Union[ndarray, Tensor]) –

  • points (Union[ndarray, Tensor]) –

  • dim (Optional[int]) –

  • shuffle (bool) –

gen(num_points=1, model=None)[source]

Query next point(s) to run by quasi-randomly sampling the parameter space. :param num_points: Number of points to query. :type num_points: int

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.PairwiseOptimizeAcqfGenerator(acqf, acqf_kwargs=None, restarts=10, samps=1000, max_gen_time=None, stimuli_per_trial=1)[source]

Bases: OptimizeAcqfGenerator

Deprecated. Use OptimizeAcqfGenerator instead.

Initialize OptimizeAcqfGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • restarts (int) – Number of restarts for acquisition function optimization.

  • samps (int) – Number of samples for quasi-random initialization of the acquisition function optimizer.

  • max_gen_time (optional, float) – Maximum time (in seconds) to optimize the acquisition function.

  • acqf (AcquisitionFunction) –

  • acqf_kwargs (Dict[str, object], optional) –

  • stimuli_per_trial (int) –

stimuli_per_trial = 2
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.PairwiseSobolGenerator(lb, ub, dim=None, seed=None, stimuli_per_trial=1)[source]

Bases: SobolGenerator

Deprecated. Use SobolGenerator instead.

Iniatialize SobolGenerator. :param lb: Lower bounds of each parameter. :type lb: Union[np.ndarray, torch.Tensor] :param ub: Upper bounds of each parameter. :type ub: Union[np.ndarray, torch.Tensor] :param dim: Dimensionality of the parameter space. If None, it is inferred from lb and ub. :type dim: int, optional :param seed: Random seed. :type seed: int, optional

Parameters:

  • lb (Union[np.ndarray, torch.Tensor]) –

  • ub (Union[np.ndarray, torch.Tensor]) –

  • dim (Optional[int]) –

  • seed (Optional[int]) –

  • stimuli_per_trial (int) –

stimuli_per_trial = 2
classmethod from_config(config)[source]
Parameters:

config (Config) –

class aepsych.generators.AxOptimizeAcqfGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep, ConfigurableMixin

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

class aepsych.generators.AxSobolGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep

classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

class aepsych.generators.IntensityAwareSemiPGenerator(acqf, acqf_kwargs=None, restarts=10, samps=1000, max_gen_time=None, stimuli_per_trial=1)[source]

Bases: OptimizeAcqfGenerator

Generator for SemiP. With botorch machinery, in order to optimize acquisition separately over context and intensity, we need two ingredients. 1. An objective that samples from some posterior w.r.t. the context. From the

paper, this is ThresholdBALV and needs the threshold posterior. SemiPThresholdObjective implements this for ThresholdBALV but theoretically this can be any subclass of SemiPObjectiveBase.

  1. A way to do acquisition over context and intensity separately, which is

    provided by this class. We optimize the acquisition function over context dimensions, then conditioned on the optimum we evaluate the intensity at the objective to obtain the intensity value.

We only developed ThresholdBALV that is specific to SemiP, which is what we tested with this generator. It should work with other similar acquisition functions.

Initialize OptimizeAcqfGenerator. :param acqf: Acquisition function to use. :type acqf: AcquisitionFunction :param acqf_kwargs: Extra arguments to

pass to acquisition function. Defaults to no arguments.

Parameters:

  • restarts (int) – Number of restarts for acquisition function optimization.

  • samps (int) – Number of samples for quasi-random initialization of the acquisition function optimizer.

  • max_gen_time (optional, float) – Maximum time (in seconds) to optimize the acquisition function.

  • acqf (AcquisitionFunction) –

  • acqf_kwargs (Dict[str, object], optional) –

  • stimuli_per_trial (int) –

gen(num_points, model, context_objective=<class 'aepsych.acquisition.objective.semi_p.SemiPThresholdObjective'>)[source]

Query next point(s) to run by optimizing the acquisition function. :param num_points: Number of points to query. :type num_points: int, optional :param model: Fitted model of the data. :type model: ModelProtocol

Returns:

Next set of point(s) to evaluate, [num_points x dim].

Return type:

np.ndarray

Parameters:
class aepsych.generators.AxRandomGenerator(name, **kwargs)[source]

Bases: AEPsychGenerationStep

classname = 'RandomGenerator'
model: Union[ModelRegistryBase, Callable[..., ModelBridge]] = 'Uniform'
classmethod get_config_options(config, name)[source]
Parameters:

  • config (Config) –

  • name (str) –

Return type:

Dict

num_trials: int
completion_criteria: Sequence[TransitionCriterion]
model_name: str
model_specs: List[ModelSpec]