aepsych.generators

Submodules

aepsych.generators.base module

class aepsych.generators.base.AEPsychGenerator[source]

Bases: abc.ABC, Generic[aepsych.generators.base.AEPsychModelType]

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

Return type

None

baseline_requiring_acqfs = [<class 'botorch.acquisition.monte_carlo.qNoisyExpectedImprovement'>, <class 'botorch.acquisition.analytic.NoisyExpectedImprovement'>]
abstract gen(num_points, model)[source]
Parameters

  • num_points (int) –

  • model (aepsych.generators.base.AEPsychModelType) –

Return type

numpy.ndarray

abstract classmethod from_config(config)[source]
Parameters

config (aepsych.config.Config) –

aepsych.generators.epsilon_greedy_generator module

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

Bases: aepsych.generators.base.AEPsychGenerator

Parameters
classmethod from_config(config)[source]
Parameters

config (aepsych.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: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

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

  • points (Union[numpy.ndarray, torch.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 (aepsych.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: aepsych.generators.base.AEPsychGenerator[aepsych.models.monotonic_rejection_gp.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 (aepsych.acquisition.monotonic_rejection.MonotonicMCAcquisition) –

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

Return type

None

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 (aepsych.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: aepsych.generators.base.AEPsychGenerator[aepsych.models.monotonic_rejection_gp.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) –

Return type

None

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 (aepsych.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)[source]

Bases: aepsych.generators.base.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. This is only loosely followed by scipy’s optimizer, so consider using a number about 1/3 or less of what your true upper bound is.

  • acqf (botorch.acquisition.acquisition.AcquisitionFunction) –

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

Return type

None

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: 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 (aepsych.config.Config) –

aepsych.generators.random_generator module

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

Bases: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

  • ub (Union[numpy.ndarray, torch.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 (aepsych.config.Config) –

aepsych.generators.sobol_generator module

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

Bases: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

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

  • dim (Optional[int]) –

  • seed (Optional[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 (aepsych.config.Config) –

Module contents

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

Bases: aepsych.generators.base.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. This is only loosely followed by scipy’s optimizer, so consider using a number about 1/3 or less of what your true upper bound is.

  • acqf (botorch.acquisition.acquisition.AcquisitionFunction) –

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

Return type

None

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: 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 (aepsych.config.Config) –

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

Bases: aepsych.generators.base.AEPsychGenerator[aepsych.models.monotonic_rejection_gp.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 (aepsych.acquisition.monotonic_rejection.MonotonicMCAcquisition) –

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

Return type

None

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 (aepsych.config.Config) –

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

Bases: aepsych.generators.base.AEPsychGenerator[aepsych.models.monotonic_rejection_gp.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) –

Return type

None

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 (aepsych.config.Config) –

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

Bases: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

  • ub (Union[numpy.ndarray, torch.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 (aepsych.config.Config) –

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

Bases: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

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

  • dim (Optional[int]) –

  • seed (Optional[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 (aepsych.config.Config) –

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

Bases: aepsych.generators.base.AEPsychGenerator

Parameters
classmethod from_config(config)[source]
Parameters

config (aepsych.config.Config) –

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

Bases: aepsych.generators.base.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[numpy.ndarray, torch.Tensor]) –

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

  • points (Union[numpy.ndarray, torch.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 (aepsych.config.Config) –