tf_estimate_warps: Estimate warping functions for registration

In tf: S3 Classes and Methods for Tidy Functional Data

Estimate warping functions for registration

Description

tf_estimate_warps() is the low-level workhorse for functional data registration. It estimates warping functions that align a set of functions to a template, but does not apply them. For a one-shot interface that also aligns the data, see tf_register().

Usage

tf_estimate_warps(
  x,
  ...,
  template = NULL,
  method = c("srvf", "cc", "affine", "landmark"),
  max_iter = 3L,
  tol = 0.01
)

Arguments

x	a tf vector of functions to register.
...	additional method-specific arguments passed to backend routines (for example crit for method = "cc").
template	an optional tf vector of length 1 to use as the template. If NULL, a default template is computed (method-dependent). Not used for method = "landmark".
method	the registration method to use: "srvf": Square Root Velocity Framework (elastic registration). For details, see fdasrvf::time_warping(). Default template is the Karcher mean. "cc": continuous-criterion registration via a tf-native dense-grid optimizer with monotone spline warps. Default template is the arithmetic mean. "affine": affine (linear) registration with warps of the form h(t) = a \cdot t + b. Simpler than elastic registration, appropriate when phase variability consists only of shifts and/or uniform speed-up/slow-down. Default template is the arithmetic mean. "landmark": piecewise-linear warps that align user-specified landmark features. Requires landmarks argument.
max_iter	integer: maximum number of Procrustes-style template refinement iterations when template = NULL. The iteration cycle is: (1) estimate template as mean of (aligned) curves, (2) register all curves to current template, (3) update template as mean of newly aligned curves, (4) repeat until convergence or max_iter reached. Ignored when template is provided (no refinement needed) or for method = "landmark" (template not used). For method = "srvf" with template = NULL, the outer Procrustes loop is skipped regardless of max_iter because fdasrvf::time_warping() already computes the Karcher mean internally. Default is 3L.
tol	numeric: convergence tolerance for template refinement. For method = "cc", iteration stops when the relative improvement in the registration criterion becomes negligible; for the other iterative methods, iteration stops when the relative change in the template (L2 norm) falls below tol. Default is 1e-2.

Details

For method = "cc", tf uses a tf-native dense-grid optimizer with monotone spline warps. Each warp is represented as the normalized cumulative integral of exp(eta(t)), where eta(t) is a spline with nbasis coefficients. Registration is then carried out curve-by-curve by minimizing either an integrated squared-error criterion (crit = 1) or the first-eigenfunction variance criterion (crit = 2) plus an optional spline roughness penalty (lambda). The outer max_iter loop, when template = NULL, still performs the same Procrustes-style template refinement as the other methods.

Value

tfd vector of (forward) warping functions h_i(s) = t with the same length as x. Apply with tf_align() to obtain registered functions, or use tf_invert() to obtain inverse warps h_i^{-1}(t) = s. The returned warps carry an attr(, "template") with the template used (NULL for landmark registration, which has no template).

Important method-specific arguments (passed via ...)

For method = "srvf":

lambda

non-negative number: penalty controlling the flexibility of warpings (default is 0 for unrestricted warps).

penalty_method

cost function used to penalize warping functions. Defaults to "roughness" (norm of their second derivative), "geodesic" uses the geodesic distance to the identity and "norm" uses Euclidean distance to the identity.

For method = "cc":

nbasis

integer: number of B-spline basis functions for the monotone warp basis (default 6L, minimum 2).

lambda

non-negative number: roughness penalty for the warp basis (default 0 for unpenalized warping).

crit

registration criterion. Defaults to 2 for the first-eigenfunction variance criterion; alternative is 1 for integrated squared error.

conv

non-negative convergence tolerance for the inner optimizer. Default is 1e-4.

iterlim

maximum number of inner optimization iterations per curve. Default is 20L.

For method = "affine":

type

character: "shift" (translation only), "scale" (scaling only), or "shift_scale" (both). Default is "shift".

shift_range

numeric(2): bounds for shift parameter. Default is c(-range/2, range/2) where range is the domain width. Larger bounds allow greater shifts but may result in more NA values.

scale_range

numeric(2): bounds for scale parameter. Default is c(0.5, 2). Must have lower > 0.

For method = "landmark":

landmarks

(required) numeric matrix of landmark positions with one row per function and one column per landmark. Use tf_landmarks_extrema() to find peaks/valleys automatically.

template_landmarks

numeric vector of target landmark positions. Default is column-wise mean of landmarks.

Author(s)

Maximilian Muecke, Fabian Scheipl, Claude Opus 4.6

See Also

Other registration functions: tf_align(), tf_landmarks_extrema(), tf_register(), tf_registration, tf_warp()

Examples

# see tf_register() for full registration examples
set.seed(1)
f <- tf_rgp(5)
warps <- tf_estimate_warps(f, method = "srvf")
plot(warps)

tf documentation built on April 7, 2026, 5:07 p.m.