Advanced Parameter Configuration
This page provides an overview of additional controls for parameters, including
parameter transformations. Generally, parameters should be defined in the natural raw
parameter space and AEPsych will handle transforming the parameters into a form usable
by the models. This means that the server will always suggest parameters in response to
an ask
in raw parameter space and you should always tell
the server the
results of a trial also in the raw parameter space. This remains true no matter
what parameter types are used and whatever transformations are used.
Parameter types
Currently, we only support continuous parameters. More parameter types soon to come!Continuous
[parameter]
par_type = continuous
lower_bound = 0 # any real number
upper_bound = 1 # any real number
Continuous parameters requires a lower bound and an upper bound to be set. Continuous parameters can have any non-infinite ranges. This means that continuous parameters can include negative values (e.g., lower bound = -1, upper bound = 1) or have very large ranges (e.g., lower bound = 0, upper bound = 1,000,000).
Integer
[parameter]
par_type = integer
lower_bound = -5
upper_bound = 5
Integer parameters are similar to continuous parameters insofar as its possible range and necessity of bounds. However, integer parameters will use continuous relaxation to allow the models and generators to handle integer input/outputs. For example, this could represent the number of lights are on for a detection threshold experiment.
Binary
[parameter]
par_type = binary
Binary parameters are useful for modeling any parameters that can take two distinct values, such as whether or not a distractor is present or whether a visual task is done with one eye or two, whether a haptics task is done with the left hand or the right hand, or whether an auditory task is done with background noise or not. Binary parameters are implemented as a special case of a integer parameter. No bounds should be set. It will be treated as a integer parameter that will either be 0 or 1. Binary parameters are equivalent to this:
[parameter]
par_type = discrete
lower_bound = 0
upper_bound = 1
Fixed
[parameter]
par_type = fixed
value = 4.5
Fixed parameters always take the same specified value, and thus are not actually modeled, but they are still included in ask and tell messages. This is useful when you would like to make changes to your experiment without having to change client code. For example, you could run the same experiment multiple times with a different fixed value for one parameter just by changing the value in the config. and added to tells and asks, respectively. Fixed parameters when running multiple conditions with certain parameters fixed; instead of removing the parameter entirely, a parameter can be set to fixed at a certain value in certain configs.
Parameter Transformations
Currently, we only support a log scale transformation to parameters. More parameter transformations to come! In general, you can define your parameters in the raw parameter space and AEPsych will handle the transformations for you seamlessly.Log scale
The log scale transformation can be applied to parameters as an extra option in a parameter-specific block.[parameter]
par_type = continuous
lower_bound = 1 # any real number
upper_bound = 100 # any real number
log_scale = True # turn it on with any of true/yes/on, turn it off with any of false/no/off; case insensitive
You can log scale a parameter by adding the log_scale
option to a parameter-specific
block and setting it to True (or true, yes, on). Log scaling is by default off. This
will transform this parameter by applying a Log10(x)
operation to it to get to the
transformed space and apply a 10^x
operation to transformed parameters to get back to
raw parameter space.
If you use the log scale transformation on a parameter that includes values less than 1
(e.g., lower bound = -1), we will add a constant to the parameter right before we
apply the Log10 operation and subtract that constant when untransforming the parameter.
For parameters with lower bounds that are positive but still less 1, we will always use
a constant value of 1 (i.e., Log10(x + 1)
and 10 ^ (x - 1)
). For parameters with
lower bounds that are negative, we will use a constant value of the absolute value of
the lower bound + 1 (i.e., Log10(x + |lb| + 1)
and 10 ^ (x - |lb| - 1)
).
Normalize scale
By default, all parameters will have their scale min-max normalized to the range of [0, 1]. This prevents any particular parameter with a large scale to completely dominate the other parameters. Very rarely, this behavior may not be desired and can be turned off for specific parameters.[parameter]
par_type = continuous
lower_bound = 1
upper_bound = 100
normalize_scale = False # turn it on with any of true/yes/on, turn it off with any of false/no/off; case insensitive
By setting the normalize_scale
option to False, this parameter will not be scaled
before being given to the model and therefore maintain its original magnitude. This is
very rarely necessary and should be used with caution.
Order of operations
Parameter types and parameter-specific transforms are all handled by theParameterTransform
API. Transforms built from config files will have a specific order
of operation, regardless of how the options were set in the config file. Each parameter
is transformed entirely separately.
Currently, the order is as follows:
- Rounding for integer parameters (rounding is applied in both directions)
- Log scale
- Normalize scale
- Fixed parameters are removed