aepsych.transforms¶

Submodules¶

aepsych.transforms.parameters module¶

class aepsych.transforms.parameters.ParameterTransforms(**transforms)[source]¶

Bases: ChainedInputTransform, ConfigurableMixin

Holds set of transformations to be applied to parameters. The ParameterTransform objects can be used by themselves to transform values or can be passed to Generator or Model wrappers to consistently transform parameters. ParameterTransforms can transform values into transformed space and also untransform values from transformed space back into raw space.

Chaining of input transforms.

Parameters:: transforms (Transform) – The transforms to chain. Internally, the names of the kwargs are used as the keys for accessing the individual transforms on the module.

Example

>>> tf1 = Normalize(d=2)
>>> tf2 = Normalize(d=2)
>>> tf = ChainedInputTransform(tf1=tf1, tf2=tf2)
>>> list(tf.keys())
['tf1', 'tf2']
>>> tf["tf1"]
Normalize()

transform(X, **kwargs)[source]¶

Transform the inputs to a model.

Individual transforms are applied in sequence.

Parameters:: X (Union[Tensor, ndarray]) – A batch_shape x n x d-dim tensor of inputs.
Returns:: A batch_shape x n x d-dim tensor of transformed inputs.
Return type:: Union[Tensor, ndarray]

untransform(X, **kwargs)[source]¶

Un-transform the inputs to a model.

Un-transforms of the individual transforms are applied in reverse sequence.

Parameters:: X (Union[Tensor, ndarray]) – A batch_shape x n x d-dim tensor of transformed inputs.
Returns:: A batch_shape x n x d-dim tensor of un-transformed inputs.
Return type:: Union[Tensor, ndarray]

transform_bounds(X, **kwargs)[source]¶

Parameters:: X (Union[Tensor, ndarray]) –
Return type:: Union[Tensor, ndarray]

indices_to_str(X, **kwargs)[source]¶

Parameters:: X (Union[Tensor, ndarray]) –
Return type:: Union[Tensor, ndarray]

str_to_indices(X, **kwargs)[source]¶

Parameters:: X (Union[Tensor, ndarray]) –
Return type:: Union[Tensor, ndarray]

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of transforms in the order that they should be in, this dictionary can be used to initialize a ParameterTransforms.

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Name is ignored as transforms for all parameters will be made. Maintained for API conformity.
options (Dict[str, Any], optional) – options is ignored as all transforms will be reinitialized to ensure it is in the right order. To create transforms in an arbitrary order, initialize from the __init__.

Returns:

A dictionary of transforms to initialize this class.

Return type:

Dict[str, Any]

class aepsych.transforms.parameters.ParameterTransformWrapper[source]¶

Bases: ABC

Abstract base class for parameter transform wrappers. __getattr__ is overridden to allow base object attributes to be surfaced smoothly. Methods that require the transforms should be overridden in the wrapper class to apply the transform operations.

transforms: ChainedInputTransform¶

class aepsych.transforms.parameters.ParameterTransformedGenerator(generator, transforms=ChainedInputTransform(), **kwargs)[source]¶

Bases: ParameterTransformWrapper, ConfigurableMixin

Wraps a generator such that parameter inputs are transformed and generated parameters are untransformed back to the raw parameter space.

Wraps a Generator with parameter transforms. This will transform any relevant generator arguments (e.g., bounds) to be transformed into the transformed space and ensure all generator outputs to be untransformed into raw space. The wrapper surfaces critical components of the API of the generator such that the wrapper can be used much like the raw generator.

Bounds are returned in the transformed space, this is necessary to handle parameters that would not have sensible raw parameter space. If bounds are manually set (e.g., Wrapper(**kwargs).lb = lb), ensure that they are correctly transformed and in a correctly shaped Tensor. If the bounds are being set in init (e.g., Wrapper(Type, lb=lb, ub=ub), lb and ub should be in the raw parameter space.

The object’s name will be ParameterTransformed<Generator.__name__>.

Parameters:

model (Type | AEPsychGenerator) – Generator to wrap, this could either be a completely initialized generator or just the generator class. An initialized generator is expected to have been initialized in the transformed parameter space (i.e., bounds are transformed). If a generator class is passed, **kwargs will be used to initialize the generator, note that the bounds are expected to be in raw parameter space, thus the transforms are applied to it.
transforms (ChainedInputTransform, optional) – A set of transforms to apply to parameters of this generator. If no transforms are passed, it will default to an identity transform.
**kwargs – Keyword arguments to pass to the model to initialize it if model is a class.
generator (Union[Type, AEPsychGenerator]) –

gen(num_points=1, model=None, fixed_features=None, **kwargs)[source]¶

Query next point(s) to run from the generator and return them untransformed.

Parameters:

num_points (int) – Number of points to query, defaults to 1.
model (AEPsychMixin, optional) – The model to use to generate points, can be None if no model is needed.
fixed_features (Optional[Dict[int, float]]) – (Dict[int, float], optional): Parameters that are fixed to specific values.
**kwargs – Kwargs to pass to the generator’s generator.

Returns:

Next set of point(s) to evaluate, [num_points x dim] or [num_points x dim x stimuli_per_trial] if self.stimuli_per_trial != 1, which will be untransformed.

Return type:

torch.Tensor

property acqf: botorch.acquisition.acquisition.AcquisitionFunction | None¶

property acqf_kwargs: dict | None¶

property training: bool¶

train()[source]¶: Set transforms to train mode and attempts to set the underlying generator to train as well.

eval()[source]¶: Set transforms to eval mode and attempts to set the underlying generator to eval as well.

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of the relevant options to initialize a generator wrapped with a parameter transform.

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Strategy to look for the Generator and find options for.
options (Dict[str, Any], optional) – Options to override from the config.

Returns:

A diciontary of options to initialize this class with.

Return type:

Dict[str, Any]

class aepsych.transforms.parameters.ParameterTransformedModel(model, transforms=ChainedInputTransform(), **kwargs)[source]¶

Bases: ParameterTransformWrapper, ConfigurableMixin

Wraps a model such that it can work entirely in transformed space by transforming all parameter inputs (e.g., training data) to the model. This wrapper also untransforms any outputs from the model back to raw parameter space.

Wraps a Model with parameter transforms. This will transform any relevant model arguments (e.g., bounds) and model data (e.g., training data, x) to be transformed into the transformed space. The wrapper surfaces the API of the raw model such that the wrapper can be used like a raw model.

Bounds are returned in the transformed space, this is necessary to handle parameters that would not have sensible raw parameter space. If bounds are manually set (e.g., Wrapper(**kwargs).lb = lb), ensure that they are correctly transformed and in a correctly shaped Tensor. If the bounds are being set in init (e.g., Wrapper(Type, lb=lb, ub=ub), lb and ub should be in the raw parameter space.

The object’s name will be ParameterTransformed<Model.__name__>.

Parameters:

model (Union[Type, ModelProtocol]) – Model to wrap, this could either be a completely initialized model or just the model class. An initialized model is expected to have been initialized in the transformed parameter space (i.e., bounds are transformed). If a model class is passed, **kwargs will be used to initialize the model. Note that the bounds in this case are expected to be in raw parameter space, thus the transforms are applied to it.
transforms (ChainedInputTransform, optional) – A set of transforms to apply to parameters of this model. If no transforms are passed, it will default to an identity transform.
**kwargs – Keyword arguments to be passed to the model if the model is a class.

predict(*args, **kwargs)[source]¶

Return type:: Tensor

predict_probability(*args, **kwargs)[source]¶

Return type:: Tensor

sample(*args, **kwargs)[source]¶

Return type:: Tensor

posterior(X, **kwargs)[source]¶

Return the model’s posterior given a transformed X. Notice that this specific method requires transformed inputs.

Parameters:

X (torch.Tensor) – The points to evaluate, which will be transformed.
**kwargs – The keyword arguments to pass to the underlying model’s posterior method.

Returns:

The posterior of the model.

Return type:

Posterior

fit(*args, **kwargs)[source]¶

Return type:: Tensor

update(*args, **kwargs)[source]¶

Return type:: Tensor

p_below_threshold(x, f_thresh)[source]¶

Compute the probability that the latent function is below a threshold.

Parameters:

x (torch.Tensor) – Points at which to evaluate the probability.
f_thresh (torch.Tensor) – Threshold value.

Returns:

Probability that the latent function is below the threshold.

Return type:

torch.Tensor

property training: bool¶

train()[source]¶: Set transforms to train mode and attempts to set the underlying model to train as well.

eval()[source]¶: Set transforms to eval mode and attempts to set the underlying model to eval as well.

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of the relevant options to initialize a model wrapped with a parameter transform

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Strategy to find options for.
options (Dict[str, Any], optional) – Options to override from the config.

Returns:

A diciontary of options to initialize this class with.

Return type:

Dict[str, Any]

aepsych.transforms.parameters.transform_options(config, transforms=None)[source]¶

Return a copy of the config with the options transformed.

Parameters:

config (Config) – The config to be transformed.
transforms (Optional[ChainedInputTransform]) –

Returns:

A copy of the original config with relevant options transformed.

Return type:

Config

aepsych.transforms.ops module¶

class aepsych.transforms.ops.Log10Plus(*args, **kwargs)[source]¶

Bases: Log10, Transform

Base-10 log transform that we add a constant to the values

Initalize transform

Parameters:

indices (List[int]) – The indices of the parameters to log transform.
constant (float) – The constant to add to inputs before log transforming. Defaults to 0.0.
transform_on_train (bool) – A boolean indicating whether to apply the transforms in train() mode. Default: True.
transform_on_eval (bool) – A boolean indicating whether to apply the transform in eval() mode. Default: True.
transform_on_fantasize (bool) – A boolean indicating whether to apply the transform when called from within a fantasize call. Default: True.
reverse (bool) – A boolean indicating whether the forward pass should untransform the inputs. Default: False.
**kwargs – Accepted to conform to API.

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of the relevant options to initialize a Log10Plus transform for the named parameter within the config.

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Parameter to find options for.
options (Dict[str, Any], optional) – Options to override from the config.

Returns:

A dictionary of options to initialize this class with,: including the transformed bounds.

Return type:

Dict[str, Any]

class aepsych.transforms.ops.NormalizeScale(*args, **kwargs)[source]¶

Bases: Normalize, Transform

Normalizes the scale of the parameters.

Parameters:

d (int) – Total number of parameters (dimensions).
(Union[List[int] (indices) – inputs to normalize. If omitted, take all dimensions of the inputs into account.
torch.Tensor] – inputs to normalize. If omitted, take all dimensions of the inputs into account.
optional – inputs to normalize. If omitted, take all dimensions of the inputs into account.
bounds (torch.Tensor, optional) – If provided, use these bounds to normalize the parameters. If omitted, learn the bounds in train mode.
batch_shape (torch.Size) – The batch shape of the inputs (assuming input tensors of shape batch_shape x n x d). If provided, perform individual normalization per batch, otherwise uses a single normalization.
transform_on_train (bool) – A boolean indicating whether to apply the transforms in train() mode. Default: True.
transform_on_eval (bool) – A boolean indicating whether to apply the transform in eval() mode. Default: True.
transform_on_fantasize (bool) – A boolean indicating whether to apply the transform when called from within a fantasize call. Default: True.
reverse (bool) – A boolean indicating whether the forward pass should untransform the parameters. Default: False.
min_range (float) – If the range of a parameter is smaller than min_range, that parameter will not be normalized. This is equivalent to using bounds of [0, 1] for this dimension, and helps avoid division by zero errors and related numerical issues. See the example below. NOTE: This only applies if learn_bounds=True. Defaults to 1e-8.
learn_bounds (bool) – Whether to learn the bounds in train mode. Defaults to False if bounds are provided, otherwise defaults to True.
almost_zero (float) – Threshold to consider the range essentially 0 and turns into a no op. Defaults to 1e-12.
**kwargs – Accepted to conform to API.
indices (Optional[Union[List[int], Tensor]]) –

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of the relevant options to initialize a NormalizeScale transform for the named parameter within the config.

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Parameter to find options for.
options (Dict[str, Any], optional) – Options to override from the config.

Returns:

A dictionary of options to initialize this class with,: including the transformed bounds.

Return type:

Dict[str, Any]

class aepsych.transforms.ops.Round(*args, **kwargs)[source]¶

Bases: Transform, Module

Initialize a round transform. This operation rounds the inputs at the indices in both direction.

Parameters:

indices (List[int]) – The indices of the inputs to round.
transform_on_train (bool) – A boolean indicating whether to apply the transforms in train() mode. Default: True.
transform_on_eval (bool) – A boolean indicating whether to apply the transform in eval() mode. Default: True.
transform_on_fantasize (bool) – Currently will not do anything, here to conform to API.
reverse (bool) – Whether to round in forward or backward passes. Does not do anything, both direction rounds.
**kwargs – Accepted to conform to API.

transform_bounds(X, bound=None, **kwargs)[source]¶

Return the bounds X transformed.

Parameters:

X (torch.Tensor) – Either a [1, dim] or [2, dim] tensor of parameter bounds.
bound (Literal["lb", "ub"], optional) – The bound that this is, if None, we will assume the input is both bounds with a [2, dim] X.
**kwargs –
passed to _transform_bounds epsilon: will modify the offset for the rounding to ensure each discrete

value has equal space in the parameter space.

Returns:

A transformed set of parameter bounds.

Return type:

torch.Tensor

class aepsych.transforms.ops.Fixed(*args, **kwargs)[source]¶

Bases: Transform, StringParameterMixin, Module

Initialize a fixed transform. It will add and remove fixed values from tensors.

Parameters:

indices (List[int]) – The indices of the parameters to be fixed.
values (List[Union[float, int]]) – The values of the fixed parameters.
string_map (Dict[int, List[str]], optional) – A dictionary to allow some fixed elements to represent one element of a categorical parameter.
transform_on_train (bool) – A boolean indicating whether to apply the transforms in train() mode. Default: True.
transform_on_eval (bool) – A boolean indicating whether to apply the transform in eval() mode. Default: True.
transform_on_fantasize (bool) – A boolean indicating whether to apply the transform when called from within a fantasize call. Default: True.
reverse (bool) – A boolean indicating whether the forward pass should untransform the inputs. Default: False.
**kwargs – Accepted to conform to API.

classmethod get_config_options(config, name=None, options=None)[source]¶

Return a dictionary of the relevant options to initialize a Fixed parameter transform for the named parameter within the config.

Parameters:

config (Config) – Config to look for options in.
name (str, optional) – Parameter to find options for.
options (Dict[str, Any], optional) – Options to override from the config.

Returns:

A dictionary of options to initialize this class with,: including the transformed bounds.

Return type:

Dict[str, Any]

AEPsych

aepsych.transforms¶

Submodules¶

aepsych.transforms.parameters module¶

aepsych.transforms.ops module¶

AEPsych

Navigation

Related Topics