dpmeans_align: DP-Means Clustering and Alignment

View source: R/dpmeans.R

dpmeans_alignR Documentation

DP-Means Clustering and Alignment

Description

This function clusters functions and aligns them using the elastic square-root velocity function (SRVF) framework and the DP-means algorithm (Kulis and Jordan, 2012), the small-variance limit of a Dirichlet process mixture. A new cluster is opened whenever a function's elastic distance to every existing template exceeds lambda, so the number of clusters is learned from the data. Each pass assigns and aligns the functions, normalizes the warps within each cluster and updates the templates as in kmeans_align().

Usage

dpmeans_align(
  f,
  time,
  lambda = NA,
  lambda_align = 0,
  alignment = TRUE,
  smooth_data = FALSE,
  sparam = 25L,
  parallel = FALSE,
  omethod = c("DP", "RBFGS"),
  max_iter = 20L,
  thresh = 0.01,
  use_verbose = FALSE
)

Arguments

f

A numeric matrix of shape M \times N specifying a sample of N functions observed on a grid of size M.

time

A numeric vector of length M specifying the grid on which the functions are evaluated.

lambda

A numeric value specifying the cluster penalty, as an elastic distance. The objective minimized is the sum of squared distances to the templates plus lambda^2 times the number of clusters. Defaults to NA, in which case it is chosen as the largest distance of a function to its nearest center in a k-means++ seeding with 4 centers.

lambda_align

A numeric value specifying the alignment penalty passed to optimum.reparam(). Defaults to 0.0.

alignment

A Boolean specifying whether to perform alignment. Defaults to TRUE.

smooth_data

A Boolean specifying whether to smooth data using a box filter. Defaults to FALSE.

sparam

An integer value specifying the number of box filters applied. Defaults to 25L.

parallel

A Boolean specifying whether parallel mode (using foreach::foreach() and the doParallel package) should be activated. Defaults to FALSE.

omethod

A string specifying which method should be used to solve the optimization problem that provides estimated warping functions. Choices are "DP" or "RBFGS". Defaults to "DP".

max_iter

An integer value specifying the maximum number of iterations. Defaults to 20L.

thresh

A numeric value specifying the relative change of the objective below which convergence is assumed. Defaults to 0.01.

use_verbose

A Boolean specifying whether to display information about the calculations in the console. Defaults to FALSE.

Value

An object of class fdakma which is a list containing:

  • f0: the original functions;

  • q0: the original SRSFs;

  • time: the grid;

  • fn: the aligned functions of each cluster in a list;

  • qn: the aligned SRSFs of each cluster in a list;

  • gam: the warping functions of each cluster in a list;

  • gamI: the inverse Karcher mean warping function of each cluster in a list;

  • labels: the cluster memberships as an integer vector;

  • templates: the centroids in the original functional space, an array of shape 1 \times M \times K;

  • templates.q: the centroids in SRSF space, of the same shape;

  • distances_to_center: the elastic distance of each function to its template at the last assignment;

  • lambda: the cluster penalty used;

  • lambda_align: the alignment penalty;

  • omethod: the optimization method;

  • qun: the DP-means objective at each iteration.

References

Kulis, B., Jordan, M. I. (2012). "Revisiting k-means: new algorithms via Bayesian nonparametrics." Proceedings of the 29th International Conference on Machine Learning.

Srivastava, A., Wu, W., Kurtek, S., Klassen, E., Marron, J. S., May 2011. Registration of functional data using Fisher-Rao metric, arXiv:1103.3817v2.

Examples

## Not run: 
  out <- dpmeans_align(growth_vel$f, growth_vel$time)

## End(Not run)

fdasrvf documentation built on Nov. 21, 2026, 1:09 a.m.