mbte_fit: Fit models to signals
In mkerschbaumer/mbte: Model-based trend estimation

Description Usage Arguments Details Value event-log event-logging See Also Examples

The presence of the 'signal'-column is required (see tbl_mbte). The idea is to fit the values of a signal via arbitrary models. Those models are used to make predictions for the signal-values.

1	mbte_fit(x, ...)

`x`	A `tbl_mbte`.
`...`	It is assumed, that the ellipsis only contains named elements. The elements are used as `quosures` via `tidy evaluation`. Caution: '.signal', '.time_sym' and '.value_sym' are masked (See details for more information). The ellipsis supports `tidy-dots`-semantics.

Fitting-quosures can make use of the following masked objects (see examples for clarification):

.signal: A tibble with the signal to fit ('time' and 'value'-columns are present).
.time_sym: The name of the time column as a symbol.
.value_sym: The name of the value-column stored as a symbol.
.row_nr: The number of the processed row of x. This masked object may be helpful if a fitting quosure has side-effects (e.g. a unique identifier is needed for storing parameters about the fit).

Currently, there are two ways, how a fitting-quosure may return the predicted signal-values for a signal:

by returning a numeric vector: if a quosure evaluates to a numeric vector, the values are used as is.
by returning an object compatible with predict: In this case, predict() will be called on the returned object with newdata = .signal (see above; the original signal-table, which has been used for fitting, gets passed). This option may come in handy, if the actual function used for fitting (e.g. lm) returns an object, for which a predict-method returning a numeric vector exists (in this case predict.lm).

In either case, the length of the vector containing the values of the predicted signal has to match the number of rows of .signal (the signal-table used for fitting).

The original table gets returned with the 'fits'-column added (list column consisting of tibbles). The column names are the names of the ellipsis (...). Each fit is a numeric column containing the predicted signal-values.

The tibble containing event-information contains the following columns:

error: The error, that occurred during processing. Errors which originate from the evaluation of a fitting quosure or prediction-related errors get wrapped.
row_nr: The row-number of the original table x, at which the error occurred.
signal: The signal-subtibble processed at the time the error occurred.
fit_name: The name of the fitting quosure (name in ...).
fit_quo: The fitting quosure being processed (element of ...).

This function logs unusual events. A warning gets raised at the end of an execution, if events have been logged. The event-log can be retrieved by passing the returned object to mbte_event_log. In this case, a tibble containing the logged events will be returned to the user.

filtered_signals (dataset used in examples) fitting-helpers

# load dataset (tbl_mbte with extracted subsignals)
data(filtered_signals)

# fit linear models to signals (by returning a predict()-compatible object
# and by returning a numeric vector of the correct length)
#
# NOTE: `.signal` is not defined in this scope. However, masking is used and
# to provide the signal-tibble as described above.
fits1 <- mbte_fit(filtered_signals,
  lm1 = lm(value ~ t, .signal), # rely on predict()
  lm2 = predict(lm(value ~ t, .signal)) # return numeric vector
)

# resuting table with `fits`-column added
fits1

# a tibble in the `fits`-list column; the columns `fit1` and `fit2` are
# equivalent (only different ways of returning the fittind signal-values have
# been used).
fits1$fits[[1]]

# use tidy-dots semantics of mbte_fit() - useful if fitting quosures are
# generated programmatically

# define fitting quosures
fitting_candidates <- rlang::quos(
  lm1 = lm(value ~ t, .signal), # rely on predict()
  lm2 = predict(lm(value ~ t, .signal)) # return numeric vector
)

# use tidy-dots splicing (equivalent to call producing `fits1` above)
fits2 <- mbte_fit(filtered_signals, !!!fitting_candidates)
fits2

fits2$fits[[1]]