frambi_parameters
Handles FrAMBI parameter configurations

Usage:

varargout = frambi_parameters(operation, params, names, varargin);
new_params = frambi_parameters('init', params, names, new_value, new_fit, new_trans, new_bounds);
new_params = frambi_parameters('set', params, names, values, fit, trans, bounds);
new_params = frambi_parameters('assign', params, names, new_values);
values = frambi_parameters('get', params, names);
new_values = frambi_parameters('transform', params, names, values);

Input parameters:

`operation`	String specifying the operation to be performed: `'init'`: Initializes a parameter structure with defaults. `'set'`: Set and/or add properties of parameter(s). `'assign'`: Assign value(s) to existing parameter(s). `'get'`: Return value(s) of existing parameter(s). `'transform'`: Apply transformation to the values by using the transformation type given by the parameter name(s). `'itransform'`: Apply inverse transformation to the values by using the transformation type given by the parameter name(s). `'isimplausible'`: Test if values are within parameters' plausible boundaries. `'isoutofbounds'`: Test if values are within parameters' (strict) boundaries.
`params`	Structure with existing parameters to be manipulated. params can be an empty structure, i.e., `struct`. It can also be the structure with the agent state parameters, i.e., `agent.state.parameters` obtained from the definition of the agent, e.g., barumerli2024_itdlateral.
`names`	Cell array of strings representing the names of the parameters to be manipulated.
`varargin`	Further parameters depend on the operation.

Output parameters:

varargout

The returned output depends on the operation.

Description:

frambi_parameters(..) handles parameter configurations within FrAMBI in various ways. The following operations are implemented:

Initialize parameter(s):

new_params = frambi_parameters('init', params, names, new_value, new_fit, new_trans, new_bounds) initializes parameters in params defined by names. If names are not member of params, they will be created. The parameters will be initialized the optional new_value, new_fit, new_trans, and new_bounds:

params: The structure with parameters.
names: Optional cell array with the names of the parameters to be initialized. If a parameter does not exist in params, it will be created. Default: All parameters in params will be initialized.
new_value: Optional value for each the parameters to be initialized. Default: NaN, for each of the initialized parameters.
new_fit: Optional binary flag stating that the initialized parameters needs fitting. Default: False, for each of the initialized parameters.
new_trans: Optional string defining the type of transformation in the fitting procedure for each of the initialized parameters. The following strings are supported:
- 'log': Logarithmic transformation will be performed.
- 'logit': Logistic transformation will be performed.
- 'none': No transformation will be performed.
Default: 'none', for each of the initialized parameters.
new_bounds: Optional row vector defining the bounds in the fitting procedure for each of the initialized parameters. The following columns must be specified:
- 1: The lower bound.
- 2: The plausible lower bound. See the parametrization of the optimizer for the correct interpretation.
- 3: The plausible upper bound.
- 4: The upper bound.
Default: [-Inf -Inf Inf Inf], for each of the initialized parameters.
new_params: Updated structure with initialized parameters.

Examples:

% Create parameters "p1" and "p2", both with the value of 5.
params = frambi_parameters('init', struct, {'p1','p2'}, 5);
% Initialize "p2" only to the value of 10 and log transform.
params = frambi_parameters('init', params, {'p2'}, 10, true, 'log',[1, 2, 120, 150]);

This code produces the following output::

params =

  struct with fields:

    p1: [1x1 struct]
    p2: [1x1 struct]

Set properties and/or add parameter(s):

new_params = frambi_parameters('set', params, names, values, fit, trans, bounds) set the properties values, fit, trans, bounds of parameters specifed by names. If names are not member of params, they will be created:

params: Structure with parameters.
names: Cell array with the names of the parameters to be set and/or created. The returned structure new_params will contain these fields.
values: Column vector with the new values of the parameters.
fit: Optional column vector with the new boolean flags stating that a parameter needs fitting. Default: False, for all parameters named by names.
trans: Optional cell array with strings defining the type of transformation in the fitting procedure. The following strings are supported:
- 'log': Logarithmic transformation will be performed.
- 'logit': Logistic transformation will be performed.
- 'none': No transformation will be performed.
Default: 'none', for all parameters named by names.
new_bounds: Optional matrix defining the bounds of each parameter in the fitting procedure. The following columns must be specified:
- 1: The lower bound.
- 2: The plausible lower bound. See the parametrization of the optimizer for the correct interpretation.
- 3: The plausible upper bound.
- 4: The upper bound.
Default: [-Inf -Inf Inf Inf], for all parameters named by names.
new_params: Structure with updated parameters.

Examples:

% Create a new structure with the parameter "level".
params = frambi_parameters('set', struct, {'level'}, 100)
% Update the value of "level" and create a new parameter "elevation".
params2 = frambi_parameters('set', params, {'level', 'elevation'}, [45, -90])
% Add an additional parameter "azimuth" as a variable to be fitted logarithmically.
params3 = frambi_parameters('set', params2, {'azimuth'}, 100, true, {'log'}, [0, 1, 100, 200])

This code produces the following output::

params =

  struct with fields:

    level: [1x1 struct]


params2 =

  struct with fields:

        level: [1x1 struct]
    elevation: [1x1 struct]


params3 =

  struct with fields:

        level: [1x1 struct]
    elevation: [1x1 struct]
      azimuth: [1x1 struct]

Assign value(s):

new_params = frambi_parameters('assign', params, names, new_values) assignes new_values to parameters with the names names in params. The values will be checked for being withing the boundaries of the corresponding parameter:

params: Structure with parameters. It must contain fields defined in names.
names: Cell array with the names of the parameters to be have the values assigned.
new_values: Column vector with values to be assigned to each parameter defined by names. Each value in new_values must be within the boundary of the corresponding parameter.
new_params: Structure with updated parameters.

Examples:

% Create a new structure with parameters "level" and "elevation":
params = frambi_parameters('set', struct, {'level', 'elevation'}, [45, -90]);
vec = frambi_parameters('get', params)'
% Modify only the "azimuth" to be 25:
params = frambi_parameters('assign', params, {'elevation'}, 25);
vec = frambi_parameters('get', params)'
% Modify both "level" and "elevation" to be 50 and 70, respectively:
params = frambi_parameters('assign', params, {'level', 'elevation'}, [50 70]);
vec = frambi_parameters('get', params)'

This code produces the following output::

vec =

    45   -90

Get value(s):

values = frambi_parameters('get', params, names) reads out the values of parameters in params:

params: Structure with parameters. It must contain fields defined in names.
names: Optional cell array with the names of the parameters to be read out. Default: All parameters from params will be read out.
values: Vector with values of the requested parameters.

Examples:

% Create a new structure with parameters "level" and "elevation".
params = frambi_parameters('set', struct, {'level', 'elevation'}, [45, -90]);
% Read out all values
values = frambi_parameters('get', params)'
% Read out "elevation" only
ele = frambi_parameters('get', params, {'elevation'})

This code produces the following output::

values =

    45   -90


ele =

   -90

Transform value(s):

new_values = frambi_parameters('transform', params, names, values) transforms values to new_values according to the transformation defined by the parameters with the names names in params:

params: Structure with parameters. It must contain fields defined in names.
names: Cell array with the names of the parameters to be transformed.
values: Matrix with the values (in columns) to be transformed for each parameter (in rows). The number of rows must correspond with the the number of parameters defined in names.
new_values: Matrix with the size of values with the transformed values.

Examples:

% Create a new structure with linear parameters "elevation" and logarithmic "level".
params = frambi_parameters('init', struct, {'elevation'});
params = frambi_parameters('set', params, {'level'}, 100, true, {'log'}, [0, 1, 100, 200]);
% Transform the elevation for values from 1 to 15.
loglevels = frambi_parameters('transform', params, {'level'}, [1:5])
% Transform both parameters for a single value
all = frambi_parameters('transform', params, {'level', 'elevation'}, [5; 5])
% Transform both parameters for three values
mtx = frambi_parameters('transform', params, {'level', 'elevation'}, [1 2 3; 4 5 6])

This code produces the following output::

loglevels =

         0    0.6931    1.0986    1.3863    1.6094


all =

    1.6094
    5.0000


mtx =

         0    0.6931    1.0986
    4.0000    5.0000    6.0000

Inverse transform value(s):

new_values = frambi_parameters('itransform', params, names, values) transforms values to new_values according to the inverse transformation defined by the parameters with the names names in params:

params: Structure with parameters. It must contain fields defined in names.
names: Cell array with the names of the parameters to be transformed.
values: Matrix with the values (in columns) to be inversly transformed for each parameter (in rows). The number of rows must correspond with the the number of parameters defined in names.
new_values: Matrix with the size of values with the inversly transformed values.

Examples:

% Create a new structure with linear parameters "elevation" and logarithmic "level".
params = frambi_parameters('init', struct, {'elevation'});
params = frambi_parameters('set', params, {'level'}, 100, true, {'log'}, [0, 1, 100, 200]);
% Transform the elevation for values from 1 to 15.
loglevels = frambi_parameters('itransform', params, {'level'}, [1:5])
% Inverse that transformation
linlevels = frambi_parameters('itransform', params, {'level'}, loglevels)

This code produces the following output::

loglevels =

    2.7183    7.3891   20.0855   54.5982  148.4132


linlevels =

   1.0e+64 *

    0.0000    0.0000    0.0000    0.0000    2.8511

Test if outside plausible boundaries:

[num viol msg] = frambi_parameters('isimplausible', params, names, values) checks whether values are within the plausible boundaries as defined by the parameters with the names names in params. If values is not provided, the parameters' values stored in params are used:

params: Structure with parameters. It must contain fields defined in names.
names: Cell array with the names of the parameters to be tested.
values: Optional column vector with values to be tested for each parameter (in rows). The number of rows must correspond with the the number of parameters defined in names. Default: values stored in params.
num: Number of violations. If 0, all tested parameters are within the plausible boundaries.
viol: Row vector with details of violations per parameter in each row:
- -1: The value was below the plausible bound.
- 0: The value was within the plausible bounds.
- 1: The value was above the plausible bound.
msg: String with a human-readable text line for each violation.

Examples:

% Create a new structure with linear parameter "elevation" and logarithmic "level".
params = frambi_parameters('init', struct, {'elevation'}, 30, true, {'none'}, [-90, -45, 45, 90]);
params = frambi_parameters('set', params, {'level'}, 50, true, {'log'}, [0, 5, 100, 160]);
% Test whether the stored values are within the plausible boundaries
good = frambi_parameters('isimplausible', params, {'level','elevation'})
% Test whether the provided values are within the plausible boundaries. Returns violations.
[bad viol msg] = frambi_parameters('isimplausible', params, {'level','elevation'},[-20 120])

This code produces the following output::

good =

     0


bad =

     2


viol =

    -1
     1


msg =

    'level: Value of -20 is below the plausible lower bound of 5.
     elevation: Value of 120 is above the plausible upper bound of 45.'

Test if outside (strict) boundaries:

[num viol msg] = frambi_parameters('isoutofbounds', params, names, values) checks whether values are outside the boundaries as defined by the parameters with the names names in params. If values is not provided, the parameters' values stored in params are used:

params: Structure with parameters. It must contain fields defined in names.
names: Cell array with the names of the parameters to be tested.
values: Optional column vector with values to be tested for each parameter (in rows). The number of rows must correspond with the the number of parameters defined in names. Default: values stored in params.
num: Number of violations. If 0, all tested parameters are within the strict boundaries.
viol: Row vector with details of violations per parameter in each row:
- -1: The value was below the lower bound.
- 0: The value was within the strict bounds.
- 1: The value was above the upper bound.
msg: String with a human-readable text line for each violation.

Examples:

% Create a new structure with linear parameter "elevation" and logarithmic "level".
params = frambi_parameters('init', struct, {'elevation'}, 30, true, {'none'}, [-90, -45, 45, 90]);
params = frambi_parameters('set', params, {'level'}, 50, true, {'log'}, [0, 5, 100, 160]);
% Test whether the stored values are within the boundaries
good = frambi_parameters('isoutofbounds', params, {'level','elevation'})
% Test whether the provided values are within the boundaries. Returns violations.
[bad viol msg] = frambi_parameters('isoutofbounds', params, {'level','elevation'},[170 -100])

This code produces the following output::

good =

     0


bad =

     2


viol =

     1
    -1


msg =

    'level: Value of 170 is above the upper bound of 160.
     elevation: Value of -100 is below the lower bound of -90.'

References:

R. Barumerli and P. Majdak. FrAMBI: A Software Framework for Auditory Modeling Based on Bayesian Inference. under review at Neuroinformatics, 2024.

THE AUDITORY MODELING TOOLBOX

frambi_parameters Handles FrAMBI parameter configurations

Usage:

Input parameters:

Output parameters:

Description:

References:

frambi_parameters
Handles FrAMBI parameter configurations