ParameterEstimationComposition¶
Contents¶
Overview¶
A ParameterEstimationComposition is a subclass of Composition that is used to estimate specified parameters
of a model
Composition,
in order to fit the outputs
of the model
to a set of data (Data Fitting),
or to optimize its net_outcome
according to an objective_function
(Parameter Optimization). In either case, when the ParameterEstimationComposition is run
with a given set of inputs, it returns the set of
parameter values in its optimized_parameter_values
attribute that it estimates best satisfy either of those conditions, and the results of running the model
with those parameters in its results
attribute. The arguments below are the primary ones used to configure a ParameterEstimationComposition for either
Data Fitting or Parameter Optimization, followed by
sections that describe arguments specific to each.
model - this is a convenience argument that can be used to specify a Composition other than the ParameterEstimationComposition itself as the model. Alternatively, the model to be fit can be constructed within the ParameterEstimationComposition itself, using the nodes and/or pathways arguments of its constructor (see Using the Constructor for additional details). The model argument or the nodes, pathways, and/or projections arguments must be specified, but not both.
Note
Neither the controller nor any of its associated arguments can be specified in the constructor for a ParameterEstimationComposition; this is constructed automatically using the arguments described below.
parameters - specifies the parameters of the
model
to be estimated. These are specified in a dict, in which the key of each entry specifies a parameter to estimate, and its value either a range of values to sample for that parameter or a distribution from which to draw them.outcome_variables - specifies the
OUTPUT
Nodes of themodel
, thevalues
of which are used to evaluate the fit of the different combinations of parameter values sampled.num_estimates - specifies the number of independent samples that are estimated for a given combination of parameter values.
Data Fitting¶
The ParameterEstimationComposition can be used to find a set of parameters for the model
such that, when it is run with a given set of inputs, its results
best match a specified set of empirical data. This requires the following additional arguments to be specified:
data - specifies the data to which the
outcome_variables
are fit in the estimation process. They must be in a format that aligns with the specification of theoutcome_variables
.optimization_function - specifies the function used to compare the
values
of theoutcome_variables
with the data, and search over values of theparameters
that maximize the fit. This must be either aParameterEstimationFunction
or a subclass of that. By default, ParameterEstimationFunction uses maximum likelihood estimation (MLE) to compare theoutcome_variables
and the data, and for searching over parameter combinations.
Parameter Optimization¶
objective_function - specifies a function used to evaluate the
values
of theoutcome_variables
, according to which combinations ofparameters
are assessed. The shape of thevariable
of the objective_function (i.e., its first positional argument) must be the same as an array containing thevalue
of the OutputPort corresponding to each item specified inoutcome_variables
.optimization_function - specifies the function used to search over values of the
parameters
in order to optimize the objective_function. It can be anyOptimizationFunction
that accepts anobjective_function
as an argument or specifies one by default. By defaultGridSearch
is used which exhaustively evaluates all combinations ofparameter
values, and returns the set that either maximizes or minimizes the objective_function.
Supported Optimizers¶
TBD
Class Reference¶
- class psyneulink.core.compositions.parameterestimationcomposition.ParameterEstimationComposition(parameters, outcome_variables, optimization_function, model=None, data=None, objective_function=None, num_estimates=1, num_trials_per_estimate=None, initial_seed=None, same_seed_for_all_parameter_combinations=None, name=None, context=None, **kwargs)¶
- Composition( parameters,
outcome_variables, model=None, data=None, objective_function=None, optimization_function=None, num_estimates=1, number_trials_per_estimate=None, initial_seed=None, same_seed_for_all_parameter_combinations=False )
Subclass of Composition that estimates specified parameters either to fit the results of a Composition to a set of data or to optimize a specified function.
Automatically implements an OptimizationControlMechanism as its
controller
, that is constructed using arguments to the ParameterEstimationComposition’s constructor as described below.The following arguments are those specific to ParmeterEstimationComposition; see Composition for additional arguments
- Parameters
parameters (dict[Parameter:Union[Iterator, Function, List, value]) – specifies the parameters of the
model
used for Data Fitting or Parameter Optimization, and either the range of values to be evaluated for each parameter, or priors that define a distribution over those.outcome_variables (list[Composition output nodes]) – specifies the
OUTPUT
Nodes of themodel
, thevalues
of which are either compared to a specified data when the ParameterEstimationComposition is used for Data Fitting, or used by theoptimization_function
for Parameter Optimization.model (Composition : default None) – specifies an external Composition for which parameters are to be fit to data or optimized according to a specified
objective_function
. If model is None (the default), the ParameterEstimationComposition itself is used (see model for additional information).data (array : default None) – specifies the data to to be fit when the ParameterEstimationComposition is used for Data Fitting; structure must conform to format of outcome_variables (see
data
for additional information).objective_function (ObjectiveFunction, function or method) – specifies the function used to evaluate the
net_outcome
of themodel
when the ParameterEstimationComposition is used for Parameter Optimization (seeobjective_function
for additional information).optimization_function (OptimizationFunction, function or method) – specifies the function used to evaluate the fit to data or optimize the parameters of the
model
according to a specifiedobjective_function
; the shape of itsvariable
of theobjective_function (i.e., its first positional argument) must be the same as an array containing the `value
of the OutputPort corresponding to each item specified inoutcome_variables
.num_estimates (int : default 1) – specifies the number of estimates made for a each combination of parameter values (see
num_estimates
for additional information); it is passed to the ParameterEstimationComposition’scontroller
to set itsnum_estimates
Parameter.num_trials_per_estimate (int : default None) – specifies an exact number of trials to execute for each run of the
model
when estimating each combination ofparameter
values (seenum_trials_per_estimate
for additional information).initial_seed (int : default None) – specifies the seed used to initialize the random number generator at construction; it is passed to the ParameterEstimationComposition’s
controller
to set itsinitial_seed
Parameter.same_seed_for_all_parameter_combinations (bool : default False) – specifies whether the random number generator is re-initialized to the same value when estimating each combination of
parameter
values; it is passed to the ParameterEstimationComposition’scontroller
to set itssame_seed_for_all_allocations
Parameter.
- model¶
identifies the Composition used for Data Fitting or Parameter Optimization. If the model argument of the ParameterEstimationComposition’s constructor is not specified,
model
returns the ParameterEstimationComposition itself.- Type
- parameters¶
determines the parameters of the
model
used for Data Fitting or Parameter Optimization (seecontrol
for additional details).- Type
list[Parameters]
- parameter_ranges_or_priors¶
determines the range of values evaluated for each
parameter
. These are assigned as theallocation_samples
for the ControlSignal assigned to the ParameterEstimationComposition’s OptimizationControlMechanism corresponding to each of the specifiedparameters
.- Type
List[Union[Iterator, Function, ist or Value]
- outcome_variables¶
determines the
OUTPUT
Nodes of themodel
, thevalues
of which are either compared to the data when the ParameterEstimationComposition is used for Data Fitting, or evaluated by the ParameterEstimationComposition’soptimization_function
when it is used for Parameter Optimization.- Type
list[Composition Output Nodes]
- data¶
determines the data to be fit by the
model
when the ParameterEstimationComposition is used for Data Fitting. These must be structured in form that aligns with the specifiedoutcome_variables
(see data for additional details). The data are passed to the optimizer used byoptimization_function
. Returns None if the model is being used for Parameter Optimization.- Type
array
- objective_function¶
determines the function used to evaluate the
results
of themodel
under each set ofparameter
values when the ParameterEstimationComposition is used for Parameter Optimization. It is passed to the ParameterEstimationComposition’s OptimizationControlMechanism as the function of itsobjective_mechanism
, that is used to compute thenet_outcome
for of themodel
each time it isrun
(see objective_function for additional details).- Type
ObjectiveFunction, function or method
- optimization_function¶
determines the function used to estimate the parameters of the
model
that either best fit thedata
when the ParameterEstimationComposition is used for Data Fitting, or that achieve some maximum or minimum value of the theoptimization_function
when the ParameterEstimationComposition is used for Parameter Optimization. This is assigned as thefunction
of the ParameterEstimationComposition’s OptimizationControlMechanism.- Type
- num_estimates¶
determines the number of estimates of the
net_outcome
of themodel
(i.e., number of calls to itsevaluate
method) for a given combination ofparameter
values (i.e.,control_allocation
) evaluated.- Type
int
- num_trials_per_estimate¶
imposes an exact number of trials to be executed in each run of
model
used to evaluate itsnet_outcome
by a call to its OptimizationControlMechanism’sevaluate_agent_rep
method. If it is None (the default), then either the number of inputs or the value specified for num_trials in the ParameterEstimationComposition’srun
method used to determine the number of trials executed (see number of trials for additional information).- Type
int or None
- initial_seed¶
contains the seed used to initialize the random number generator at construction, that is stored on the ParameterEstimationComposition’s
controller
, and setting it sets the value of that Parameter (seeinitial_seed
for additional details).- Type
int or None
- same_seed_for_all_parameter_combinations¶
contains the setting for determining whether the random number generator used to select seeds for each estimate of the
model
'snet_outcome
is re-initialized to the same value for each combination of parameter values evaluated. Its values is stored on the ParameterEstimationComposition’scontroller
, and setting it sets the value of that Parameter (seesame_seed_for_all_allocations
for additional details).- Type
bool
- optimized_parameter_values¶
contains the values of the
parameters
of themodel
that best fit thedata
when the ParameterEstimationComposition is used for Data Fitting, or that optimize performance of themodel
according to theoptimization_function
when the ParameterEstimationComposition is used for Parameter Optimization. Ifparameter values
are specified as ranges of values, then each item ofoptimized_parameter_values
is the optimized value of the correspondingparameter
. Ifparameter values
are specified as priors, then each item ofoptimized_parameter_values
is an array containing the values of the correspondingparameter
the distribution of which were determined to be optimal.- Type
list
- results¶
contains the
output_values
of theOUTPUT
Nodes in themodel
for everyTRIAL
executed (seeComposition.results
for more details). If the ParameterEstimationComposition is used for Data Fitting, andparameter values
are specified as ranges of values, then each item ofresults
is an array ofoutput_values
(sampled overnum_estimates
) obtained for the single optimized combination ofparameter
values contained in the corresponding item ofoptimized_parameter_values
. Ifparameter values
are specified as priors, then each item ofresults
is an array ofoutput_values
(sampled overnum_estimates
), each of which corresponds to a combination ofparameter
values that were used to generate those results; it is the distribution of thoseparameter
values that were found to best fit the data.- Type
list[list[list]]