ParameterEstimationComposition

Contents

• Overview

• Data Fitting

• Parameter Optimization

• Supported Optimizers

• Class Reference

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 the model, the values of which are used to evaluate the fit of the different combination 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 the specification of outcome_variables.

• optimization_function - specifies the function used to compare the values of the outcome_variables with the data, and search over values of the parameters that maximize the fit. This must be either ParameterEstimationFunction or a subclass of that. By default, ParameterEstimationFunction uses maximum likelihood estimation (MLE) to compare the outcome_variables and the data, and for searching over parameter combinations.

Parameter Optimization

• objective_function - specifies a function used to evaluate the values of the outcome_variables, according to which combinations of parameters are assessed. The shape of the variable of the objective_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 in outcome_variables.

• optimization_function - specifies the function used to search over values of the parameters in order to optimize the objective_function. It can be any OptimizationFunction that accepts an objective_function as an argument or specifies one by default. By default GridSearch is used which exhaustively evaluates all combinations of parameter 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 the model, the values of which are either compared to a specified data when the ParameterEstimationComposition is used for Data Fitting, or used by the optimization_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 the model when the ParameterEstimationComposition is used for Parameter Optimization (see objective_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 specified objective_function; the shape of its variable of the objective_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 in outcome_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’s controller to set its num_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 of parameter values (see num_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 its initial_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’s controller to set its same_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

Composition

parameters

determines the parameters of the model used for Data Fitting or Parameter Optimization (see control for additional details).

Type

list[Parameters]

parameter_ranges_or_priors

determines the range of values evaluated for each parameter. These are assigned as the allocation_samples for the ControlSignal assigned to the ParameterEstimationComposition’s OptimizationControlMechanism corresponding to each of the specified parameters.

Type

List[Union[Iterator, Function, ist or Value]

outcome_variables

determines the OUTPUT Nodes of the model, the values of which are either compared to the data when the ParameterEstimationComposition is used for Data Fitting, or evaluated by the ParameterEstimationComposition’s optimization_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 specified outcome_variables (see data for additional details). The data are passed to the optimizer used by optimization_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 the model under each set of parameter values when the ParameterEstimationComposition is used for Parameter Optimization. It is passed to the ParameterEstimationComposition’s OptimizationControlMechanism as the function of its objective_mechanism, that is used to compute the net_outcome for of the model each time it is run (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 the data when the ParameterEstimationComposition is used for Data Fitting, or that achieve some maximum or minimum value of the the optimization_function when the ParameterEstimationComposition is used for Parameter Optimization. This is assigned as the function of the ParameterEstimationComposition’s OptimizationControlMechanism.

Type

OptimizationFunction

num_estimates

determines the number of estimates of the net_outcome of the model (i.e., number of calls to its evaluate method) for a given combination of parameter 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 its net_outcome by a call to its OptimizationControlMechanism’s evaluate_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’s run 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 (see initial_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's net_outcome is re-initialized to the same value for each combination of parameter values evaluated. Its values is stored on the ParameterEstimationComposition’s controller, and setting it sets the value of that Parameter (see same_seed_for_all_allocations for additional details).

Type

bool

optimized_parameter_values

contains the values of the parameters of the model that best fit the data when the ParameterEstimationComposition is used for Data Fitting, or that optimize performance of the model according to the optimization_function when the ParameterEstimationComposition is used for Parameter Optimization. If parameter values are specified as ranges of values, then each item of optimized_parameter_values is the optimized value of the corresponding parameter. If parameter values are specified as priors, then each item of optimized_parameter_values is an array containing the values of the corresponding parameter the distribution of which were determined to be optimal.

Type

list

results

contains the output_values of the OUTPUT Nodes in the model for every TRIAL executed (see Composition.results for more details). If the ParameterEstimationComposition is used for Data Fitting, and parameter values are specified as ranges of values, then each item of results is an array of output_values (sampled over num_estimates) obtained for the single optimized combination of parameter values contained in the corresponding item of optimized_parameter_values. If parameter values are specified as priors, then each item of results is an array of output_values (sampled over num_estimates), each of which corresponds to a combination of parameter values that were used to generate those results; it is the distribution of those parameter values that were found to best fit the data.

Type

list[list[list]]

class Parameters(owner, parent=None)

initial_seed

see input_specification

Default value

None

Type

int

same_seed_for_all_parameter_combinations

see input_specification

Default value

False

Type

bool