Procedure {ao}

Procedure Object

Description

This object specifies alternating optimization procedure.

Active bindings

npar

(integer(1))
The length of the target argument.

partition

(character(1) or list())
Defines the parameter partition, and can be either

• "sequential" for treating each parameter separately,

• "random" for a random partition in each iteration,

• "none" for no partition (which is equivalent to joint optimization),

• or a list of vectors of parameter indices, specifying a custom partition for the alternating optimization process.

new_block_probability

(numeric(1))
Only relevant if partition = "random". The probability for a new parameter block when creating a random partitions. Values close to 0 result in larger parameter blocks, values close to 1 result in smaller parameter blocks.

minimum_block_number

(integer(1))
Only relevant if partition = "random". The minimum number of blocks in random partitions.

verbose

(logical(1))
Whether to print tracing details during the alternating optimization process.

minimize

(logical(1))
Whether to minimize during the alternating optimization process. If FALSE, maximization is performed.

iteration_limit

(integer(1) or Inf)
The maximum number of iterations through the parameter partition before the alternating optimization process is terminated. Can also be Inf for no iteration limit.

seconds_limit

(numeric(1))
The time limit in seconds before the alternating optimization process is terminated. Can also be Inf for no time limit. Note that this stopping criteria is only checked after a sub-problem is solved and not within solving a sub-problem, so the actual process time can exceed this limit.

tolerance_value

(numeric(1))
A non-negative tolerance value. The alternating optimization terminates if the absolute difference between the current function value and the one before tolerance_history iterations is smaller than tolerance_value.

Can be 0 for no value threshold.

tolerance_parameter

(numeric(1))
A non-negative tolerance value. The alternating optimization terminates if the distance between the current estimate and the before tolerance_history iterations is smaller than tolerance_parameter.

Can be 0 for no parameter threshold.

By default, the distance is measured using the euclidean norm, but another norm can be specified via the tolerance_parameter_norm field.

tolerance_parameter_norm

(function)
The norm that measures the distance between the current estimate and the one from the last iteration. If the distance is smaller than tolerance_parameter, the procedure is terminated.

It must be of the form function(x, y) for two vector inputs x and y, and return a single numeric value. By default, the euclidean norm function(x, y) sqrt(sum((x - y)^2)) is used.

tolerance_history

(integer(1))
The number of iterations to look back to determine whether tolerance_value or tolerance_parameter has been reached.

iteration

(integer(1))
The current iteration number.

block

(integer())
The currently active parameter block, represented as parameter indices.

output

(list(), read-only)
The output of the alternating optimization procedure, which is a list with the following elements:

• estimate is the parameter vector at termination.

• value is the function value at termination.

• details is a data.frame with full information about the procedure: For each iteration (column iteration) it contains the function value (column value), parameter values (columns starting with p followed by the parameter index), the active parameter block (columns starting with b followed by the parameter index, where 1 stands for a parameter contained in the active parameter block and 0 if not), and computation times in seconds (column seconds)

• seconds is the overall computation time in seconds.

• stopping_reason is a message why the procedure has terminated.

Methods

Public methods

• Procedure$new()

• Procedure$print_status()

• Procedure$initialize_details()

• Procedure$update_details()

• Procedure$get_partition()

• Procedure$get_details()

• Procedure$get_value()

• Procedure$get_value_latest()

• Procedure$get_value_best()

• Procedure$get_parameter()

• Procedure$get_parameter_latest()

• Procedure$get_parameter_best()

• Procedure$get_seconds()

• Procedure$get_seconds_total()

• Procedure$check_stopping()

Method new()

Creates a new object of this R6 class.

Usage

Procedure$new(
  npar = integer(),
  partition = "sequential",
  new_block_probability = 0.3,
  minimum_block_number = 2,
  verbose = FALSE,
  minimize = TRUE,
  iteration_limit = Inf,
  seconds_limit = Inf,
  tolerance_value = 1e-06,
  tolerance_parameter = 1e-06,
  tolerance_parameter_norm = function(x, y) sqrt(sum((x - y)^2)),
  tolerance_history = 1
)

Arguments

npar

(integer(1))
The (total) length of the target argument(s).

partition

(character(1) or list())
Defines the parameter partition, and can be either

• "sequential" for treating each parameter separately,

• "random" for a random partition in each iteration,

• "none" for no partition (which is equivalent to joint optimization),

• or a list of vectors of parameter indices, specifying a custom partition for the alternating optimization process.

new_block_probability

(numeric(1))
Only relevant if partition = "random". The probability for a new parameter block when creating a random partitions. Values close to 0 result in larger parameter blocks, values close to 1 result in smaller parameter blocks.

minimum_block_number

(integer(1))
Only relevant if partition = "random". The minimum number of blocks in random partitions.

verbose

(logical(1))
Whether to print tracing details during the alternating optimization process.

minimize

(logical(1))
Whether to minimize during the alternating optimization process. If FALSE, maximization is performed.

iteration_limit

(integer(1) or Inf)
The maximum number of iterations through the parameter partition before the alternating optimization process is terminated. Can also be Inf for no iteration limit.

seconds_limit

(numeric(1))
The time limit in seconds before the alternating optimization process is terminated. Can also be Inf for no time limit. Note that this stopping criteria is only checked after a sub-problem is solved and not within solving a sub-problem, so the actual process time can exceed this limit.

tolerance_value

(numeric(1))
A non-negative tolerance value. The alternating optimization terminates if the absolute difference between the current function value and the one before tolerance_history iterations is smaller than tolerance_value.

Can be 0 for no value threshold.

tolerance_parameter

(numeric(1))
A non-negative tolerance value. The alternating optimization terminates if the distance between the current estimate and the before tolerance_history iterations is smaller than tolerance_parameter.

Can be 0 for no parameter threshold.

By default, the distance is measured using the euclidean norm, but another norm can be specified via the tolerance_parameter_norm field.

tolerance_parameter_norm

(function)
The norm that measures the distance between the current estimate and the one from the last iteration. If the distance is smaller than tolerance_parameter, the procedure is terminated. It must be of the form function(x, y) for two vector inputs x and y, and return a single numeric value. By default, the euclidean norm function(x, y) sqrt(sum((x - y)^2)) is used.

tolerance_history

(integer(1))
The number of iterations to look back to determine whether tolerance_value or tolerance_parameter has been reached.

Method print_status()

Prints a status message.

Usage

Procedure$print_status(message, message_type = 8, verbose = self$verbose)

Arguments

message

(character(1))
The status message.

message_type

(integer(1))
The type of the message, one of the following:

• 1 for cli::cli_h1()

• 2 for cli::cli_h2()

• 3 for cli::cli_h3()

• 4 for cli::cli_alert_success()

• 5 for cli::cli_alert_info()

• 6 for cli::cli_alert_warning()

• 7 for cli::cli_alert_danger()

• 8 for cli::cat_line()

verbose

(logical(1))
Whether to print tracing details during the alternating optimization process.

Method initialize_details()

Initializes the details part of the output.

Usage

Procedure$initialize_details(initial_parameter, initial_value)

Arguments

initial_parameter

(numeric())
The starting parameter values for the procedure.

initial_value

(numeric(1))
The function value at the initial parameters.

Method update_details()

Updates the details part of the output.

Usage

Procedure$update_details(
  value,
  parameter_block,
  seconds,
  error,
  block = self$block
)

Arguments

value

(numeric(1))
The updated function value.

parameter_block

(numeric())
The updated parameter values for the active parameter block.

seconds

(numeric(1))
The time in seconds for solving the sub-problem.

error

(logical(1))
Whether solving the sub-problem resulted in an error.

block

(integer())
The currently active parameter block, represented as parameter indices.

Method get_partition()

Get a parameter partition.

Usage

Procedure$get_partition()

Method get_details()

Get the details part of the output.

Usage

Procedure$get_details(
  which_iteration = NULL,
  which_block = NULL,
  which_column = c("iteration", "value", "parameter", "block", "seconds")
)

Arguments

which_iteration

(integer())
Selects the iteration(s). Can also be NULL to select all iterations.

which_block

(character(1) or integer())
Selects the parameter block in the partition and can be one of

• "first" for the first parameter block,

• "last" for the last parameter block,

• an integer vector of parameter indices,

• or NULL for all parameter blocks.

which_column

(character())
Selects the columns in the details part of the output and can be one or more of "iteration", "value", "parameter", "block", and "seconds"

Method get_value()

Get the function value in different steps of the alternating optimization procedure.

Usage

Procedure$get_value(
  which_iteration = NULL,
  which_block = NULL,
  keep_iteration_column = FALSE,
  keep_block_columns = FALSE
)

Arguments

which_iteration

(integer())
Selects the iteration(s). Can also be NULL to select all iterations.

which_block

(character(1) or integer())
Selects the parameter block in the partition and can be one of

• "first" for the first parameter block,

• "last" for the last parameter block,

• an integer vector of parameter indices,

• or NULL for all parameter blocks.

keep_iteration_column

(logical())
Whether to keep the column containing the information about the iteration in the output.

keep_block_columns

(logical())
Whether to keep the column containing the information about the active parameter block in the output.

Method get_value_latest()

Get the function value in the latest step of the alternating optimization procedure.

Usage

Procedure$get_value_latest()

Method get_value_best()

Get the optimum function value in the alternating optimization procedure.

Usage

Procedure$get_value_best()

Method get_parameter()

Get the parameter values in different steps of the alternating optimization procedure.

Usage

Procedure$get_parameter(
  which_iteration = self$iteration,
  which_block = NULL,
  keep_iteration_column = FALSE,
  keep_block_columns = FALSE
)

Arguments

which_iteration

(integer())
Selects the iteration(s). Can also be NULL to select all iterations.

which_block

(character(1) or integer())
Selects the parameter block in the partition and can be one of

• "first" for the first parameter block,

• "last" for the last parameter block,

• an integer vector of parameter indices,

• or NULL for all parameter blocks.

keep_iteration_column

(logical())
Whether to keep the column containing the information about the iteration in the output.

keep_block_columns

(logical())
Whether to keep the column containing the information about the active parameter block in the output.

Method get_parameter_latest()

Get the parameter value in the latest step of the alternating optimization procedure.

Usage

Procedure$get_parameter_latest(parameter_type = "full")

Arguments

parameter_type

(character(1))
Can be one of

• "full" (default) to get the full parameter vector,

• "block" to get the parameter values for the current block, i.e., the parameters with the indices self$block

• "fixed" to get the parameter values which are currently fixed, i.e., all except for those with the indices self$block

Method get_parameter_best()

Get the optimum parameter value in the alternating optimization procedure.

Usage

Procedure$get_parameter_best(parameter_type = "full")

Arguments

parameter_type

(character(1))
Can be one of

• "full" (default) to get the full parameter vector,

• "block" to get the parameter values for the current block, i.e., the parameters with the indices self$block

• "fixed" to get the parameter values which are currently fixed, i.e., all except for those with the indices self$block

Method get_seconds()

Get the optimization time in seconds in different steps of the alternating optimization procedure.

Usage

Procedure$get_seconds(
  which_iteration = NULL,
  which_block = NULL,
  keep_iteration_column = FALSE,
  keep_block_columns = FALSE
)

Arguments

which_iteration

(integer())
Selects the iteration(s). Can also be NULL to select all iterations.

which_block

(character(1) or integer())
Selects the parameter block in the partition and can be one of

• "first" for the first parameter block,

• "last" for the last parameter block,

• an integer vector of parameter indices,

• or NULL for all parameter blocks.

keep_iteration_column

(logical())
Whether to keep the column containing the information about the iteration in the output.

keep_block_columns

(logical())
Whether to keep the column containing the information about the active parameter block in the output.

Method get_seconds_total()

Get the total optimization time in seconds of the alternating optimization procedure.

Usage

Procedure$get_seconds_total()

Method check_stopping()

Checks if the alternating optimization procedure can be terminated.

Usage

Procedure$check_stopping()