Assemble model-fit-derived text or expressions and map them to
the `label`

aesthetic.

## Arguments

- ...
character Strings giving the names of the label components in the order they will be included in the combined label.

- labels
character A vector with the name of the label components. If provided, values passed through

`...`

are ignored.- other.mapping
An unevaluated expression constructed with function

`aes`

to be included in the returned value.- sep
character A string used as separator when pasting the label components together.

## Value

A mapping to the `label`

aesthetic and optionally additional
mappings as an unevaluated R expression, built using function
`aes`

, ready to be passed as argument to the
`mapping`

parameter of the supported statistics.

## Details

Statistics `stat_poly_eq`

, `stat_ma_eq`

,
`stat_quant_eq`

and `stat_correlation`

return
multiple text strings to be used individually or assembled into longer
character strings depending on the labels actually desired. Assembling and
mapping them requires verbose R code and familiarity with R expression
syntax. Function `use_label()`

automates these two tasks and accepts
abbreviated familiar names for the parameters in addition to the name of
the columns in the data object returned by the statistics. The default
separator is that for expressions.

The statistics return variables with names ending in `.label`

. This
ending can be omitted, as well as `.value`

for `f.value.label`

,
`t.value.label`

, `z.value.label`

, `S.value.label`

and
`p.value.label`

. `R2`

can be used in place of `rr`

.
Furthermore, case is ignored.

Function `use_label()`

calls `aes()`

to create a mapping for
the `label`

aesthetic, but it can in addition combine this mapping
with other mappings created with `aes()`

.

## Note

Function `use_label()`

can be only used to generate an argument
passed to formal parameter `mapping`

of the statistics
`stat_poly_eq`

, `stat_ma_eq`

,
`stat_quant_eq`

and `stat_correlation`

.

## Examples

```
# generate artificial data
set.seed(4321)
x <- 1:100
y <- (x + x^2 + x^3) + rnorm(length(x), mean = 0, sd = mean(x^3) / 4)
my.data <- data.frame(x = x,
y = y * 1e-5,
group = c("A", "B"),
y2 = y * 1e-5 + c(2, 0))
# give a name to a formula
formula <- y ~ poly(x, 3, raw = TRUE)
# default label constructed by use_label()
ggplot(data = my.data,
mapping = aes(x = x, y = y2, colour = group)) +
geom_point() +
stat_poly_line(formula = formula) +
stat_poly_eq(mapping = use_label(),
formula = formula)
# user specified label components
ggplot(data = my.data,
mapping = aes(x = x, y = y2, colour = group)) +
geom_point() +
stat_poly_line(formula = formula) +
stat_poly_eq(mapping = use_label("eq", "F"),
formula = formula)
# user specified label components and separator
ggplot(data = my.data,
mapping = aes(x = x, y = y2, colour = group)) +
geom_point() +
stat_poly_line(formula = formula) +
stat_poly_eq(mapping = use_label("R2", "F", sep = "*\" with \"*"),
formula = formula)
# combine the mapping to the label aesthetic with other mappings
ggplot(data = my.data,
mapping = aes(x = x, y = y2)) +
geom_point(mapping = aes(colour = group)) +
stat_poly_line(mapping = aes(colour = group), formula = formula) +
stat_poly_eq(mapping = use_label("grp", "eq", "F",
aes(grp.label = group)),
formula = formula)
# combine other mappings with default labels
ggplot(data = my.data,
mapping = aes(x = x, y = y2)) +
geom_point(mapping = aes(colour = group)) +
stat_poly_line(mapping = aes(colour = group), formula = formula) +
stat_poly_eq(mapping = use_label(aes(colour = group)),
formula = formula)
# example with other available components
ggplot(data = my.data,
mapping = aes(x = x, y = y2, colour = group)) +
geom_point() +
stat_poly_line(formula = formula) +
stat_poly_eq(mapping = use_label("eq", "adj.R2", "n"),
formula = formula)
# multiple labels
ggplot(data = my.data,
mapping = aes(x, y2, colour = group)) +
geom_point() +
stat_poly_line(formula = formula) +
stat_poly_eq(mapping = use_label("R2", "F", "P", "AIC", "BIC"),
formula = formula) +
stat_poly_eq(mapping = use_label(c("eq", "n")),
formula = formula,
label.y = "bottom",
label.x = "right")
# quantile regression
ggplot(data = my.data,
mapping = aes(x, y)) +
stat_quant_band(formula = formula) +
stat_quant_eq(mapping = use_label("eq", "n"),
formula = formula) +
geom_point()
# major axis regresion
ggplot(data = my.data, aes(x = x, y = y)) +
stat_ma_line() +
stat_ma_eq(mapping = use_label("eq", "n")) +
geom_point()
# correlation
ggplot(data = my.data,
mapping = aes(x = x, y = y)) +
stat_correlation(mapping = use_label("r", "t", "p")) +
geom_point()
```