-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
89 lines (56 loc) · 3.47 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
# Alternating optimization <img src="man/figures/logo.png" align="right" height="139" />
<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/ao)](https://CRAN.R-project.org/package=ao)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/last-month/ao)](https://CRAN.R-project.org/package=ao)
[![R-CMD-check](https://github.com/loelschlaeger/ao/workflows/R-CMD-check/badge.svg)](https://github.com/loelschlaeger/ao/actions)
[![Codecov test coverage](https://codecov.io/gh/loelschlaeger/ao/branch/main/graph/badge.svg)](https://app.codecov.io/gh/loelschlaeger/ao?branch=main)
<!-- badges: end -->
The `{ao}` package implements a numerical optimization algorithm called alternating optimization in R.
Alternating optimization is an iterative procedure which optimizes a function jointly over all parameters by alternately performing restricted optimization over individual parameter subsets.
For additional details on the method, please refer to the [package vignette](https://loelschlaeger.de/ao/articles/ao.html).
## Installation
You can install the released version of `{ao}` from [CRAN](https://CRAN.R-project.org) with:
```{r install released, eval = FALSE}
install.packages("ao")
```
## Example
The following is a simple example to perform alternating optimization of the [Himmelblau's function](https://en.wikipedia.org/wiki/Himmelblau%27s_function), separately for $x_1$ and $x_2$, with the parameter restrictions $-5 \leq x_1, x_2 \leq 5$.
### Step 1: Load the package
```{r load ao package}
library("ao")
```
### Step 2: Define the function to be optimized
```{r define function}
himmelblau <- function(x, a, b) (x[1]^2 + x[2] + a)^2 + (x[1] + x[2]^2 + b)^2
```
The function is optimized over its first argument (`x`), which needs to be a `numeric` `vector`. Other function arguments (`a` and `b` in this case) remain fixed during the optimization. The function should return a single `numeric` value.
### Step 3: Define a base optimizer
Alternating optimization requires a base optimizer that numerically solves the optimization problems in the partitions of the parameter vector. Such an optimizer must be defined through the framework provided by the `{optimizeR}` package, please see [its documentation](https://loelschlaeger.de/optimizeR/) for details.
```{r define optimizer}
base_optimizer <- optimizeR::Optimizer$new(which = "stats::optim", lower = -5, upper = 5, method = "L-BFGS-B")
```
### Step 4: Call the `ao()` function
Despite `f` and `base_optimizer`, which have been defined above, the `ao()` function requires the following arguments:
- `p` defines the starting parameter values,
- `a` and `b` are fixed function arguments,
- `partition` defines the parameter subsets (here, the first entry of `x` and the second are optimized separately).
```{r optimize}
ao(f = himmelblau, p = c(0, 0), a = -11, b = -7, partition = list(1, 2), base_optimizer = base_optimizer)
```
The output contains:
- the function `value` at convergence,
- the parameter value `estimate` at convergence,
- `sequence` provides information about the updates in the single iterations and partitions,
- and the optimization time in `seconds`.
## Contact
Have a question, found a bug, request a feature, want to contribute? [Please file an issue](https://github.com/loelschlaeger/ao/issues/new/choose).