Skip to contents

Specify objective function object

Source: R/objective.R
Objective.Rd

The Objective object specifies the framework for an objective function for numerical optimization.

Value

An Objective object.

Active bindings

objective_name

[character(1)]
The label for the objective function.

fixed_arguments

[character(), read-only]
The name(s) of the fixed argument(s) (if any).

seconds

[numeric(1)]
A time limit in seconds. Computations are interrupted prematurely if seconds is exceeded.

No time limit if seconds = Inf (the default).

Note the limitations documented in setTimeLimit.

hide_warnings

[logical(1)]
Hide warnings when evaluating the objective function?

verbose

[logical(1)]
Print status messages?

npar

[integer(), read-only]
The length of each target argument.

target

[character(), read-only]
The argument name(s) that get optimized.

gradient_specified

[logical(1), read-only]
Whether a gradient function has been specified via $set_gradient().

hessian_specified

[logical(1), read-only]
Whether a Hessian function has been specified via $set_hessian().

Methods

Public methods

Method new()

Creates a new Objective object.

Usage

Objective$new(f, target = NULL, npar, ...)

Arguments

f

[function]
A function to be optimized.

It is expected that f has at least one numeric argument.

Further, it is expected that the return value of f is of the structure numeric(1), i.e. a single numeric value.

target

[character()]
The argument name(s) that get optimized.

All target arguments must be numeric.

Can be NULL (default), then the first function argument is selected.

npar

[integer()]
The length of each target argument, i.e., the length(s) of the numeric vector argument(s) specified by target.

...

Optionally additional function arguments that are fixed during the optimization.

Method set_argument()

Set a function argument that remains fixed during optimization.

Usage

Objective$set_argument(..., .overwrite = TRUE, .verbose = self$verbose)

Arguments

...

Optionally additional function arguments that are fixed during the optimization.

.overwrite

[logical(1)]
Overwrite existing values?

.verbose

[logical(1)]
Print status messages?

Method get_argument()

Get a fixed function argument.

Usage

Objective$get_argument(argument_name, .verbose = self$verbose)

Arguments

argument_name

[character(1)]
A function argument name.

.verbose

[logical(1)]
Print status messages?

Method remove_argument()

Remove a fixed function argument.

Usage

Objective$remove_argument(argument_name, .verbose = self$verbose)

Arguments

argument_name

[character(1)]
A function argument name.

.verbose

[logical(1)]
Print status messages?

Method set_gradient()

Set a gradient function.

Usage

Objective$set_gradient(
  gradient,
  target = self$target,
  npar = self$npar,
  ...,
  .verbose = self$verbose
)

Arguments

gradient

[function]
A function that computes the gradient of the objective function f.

It is expected that gradient has the same call as f, and that gradient returns a numeric vector of length self$npar.

target

[character()]
The argument name(s) that get optimized.

All target arguments must be numeric.

Can be NULL (default), then the first function argument is selected.

npar

[integer()]
The length of each target argument, i.e., the length(s) of the numeric vector argument(s) specified by target.

...

Optionally additional function arguments that are fixed during the optimization.

.verbose

[logical(1)]
Print status messages?

Method set_hessian()

Set a Hessian function.

Usage

Objective$set_hessian(
  hessian,
  target = self$target,
  npar = self$npar,
  ...,
  .verbose = self$verbose
)

Arguments

hessian

[function]
A function that computes the Hessian of the objective function f.

It is expected that hessian has the same call as f, and that hessian returns a numeric matrix of dimension self$npar times self$npar.

target

[character()]
The argument name(s) that get optimized.

All target arguments must be numeric.

Can be NULL (default), then the first function argument is selected.

npar

[integer()]
The length of each target argument, i.e., the length(s) of the numeric vector argument(s) specified by target.

...

Optionally additional function arguments that are fixed during the optimization.

.verbose

[logical(1)]
Print status messages?

Method evaluate()

Evaluate the objective function.

Usage

Objective$evaluate(
  .at,
  .negate = FALSE,
  .gradient_as_attribute = FALSE,
  .gradient_attribute_name = "gradient",
  .hessian_as_attribute = FALSE,
  .hessian_attribute_name = "hessian",
  ...
)

Arguments

.at

[numeric()]
The values for the target argument(s), written in a single vector.

Must be of length sum(self$npar).

.negate

[logical(1)]
Negate the function return value?

.gradient_as_attribute

[`logical(1)]
Add the value of the gradient function as an attribute to the output?

The attribute name is defined via the .gradient_attribute_name argument.

Ignored if $gradient_specified is FALSE.

.gradient_attribute_name

[character(1)\]\cr Only relevant if .gradient_as_attribute = TRUE`.

In that case, the attribute name for the gradient (if available).

.hessian_as_attribute

[`logical(1)]
Add the value of the Hessian function as an attribute to the output?

The attribute name is defined via the .hessian_attribute_name argument.

Ignored if $hessian_specified is FALSE.

.hessian_attribute_name

[character(1)\]\cr Only relevant if .hessian_as_attribute = TRUE`.

In that case, the attribute name for the Hessian (if available).

...

Optionally additional function arguments that are fixed during the optimization.

Method evaluate_gradient()

Evaluate the gradient function.

Usage

Objective$evaluate_gradient(.at, .negate = FALSE, ...)

Arguments

.at

[numeric()]
The values for the target argument(s), written in a single vector.

Must be of length sum(self$npar).

.negate

[logical(1)]
Negate the function return value?

...

Optionally additional function arguments that are fixed during the optimization.

Method evaluate_hessian()

Evaluate the Hessian function.

Usage

Objective$evaluate_hessian(.at, .negate = FALSE, ...)

Arguments

.at

[numeric()]
The values for the target argument(s), written in a single vector.

Must be of length sum(self$npar).

.negate

[logical(1)]
Negate the function return value?

...

Optionally additional function arguments that are fixed during the optimization.

Method print()

Print details of the Objective object.

Usage

Objective$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

Objective$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

### define log-likelihood function of Gaussian mixture model
llk <- function(mu, sd, lambda, data) {
  sd <- exp(sd)
  lambda <- plogis(lambda)
  cluster_1 <- lambda * dnorm(data, mu[1], sd[1])
  cluster_2 <- (1 - lambda) * dnorm(data, mu[2], sd[2])
  sum(log(cluster_1 + cluster_2))
}

### optimize over the first three arguments, the 'data' argument is constant
objective <- Objective$new(
  f = llk, target = c("mu", "sd", "lambda"), npar = c(2, 2, 1),
  data = faithful$eruptions
)

### evaluate at 1:5 (1:2 is passed to mu, 3:4 to sd, and 5 to lambda)
objective$evaluate(1:5)
#> [1] -1069.623