pclm.fit: Fit PCLM Models

In ungroup: Penalized Composite Link Model for Efficient Estimation of Smooth Distributions from Coarsely Binned Data

Fit PCLM Models

Description

This is an internal function used to estimate PCLM model. It is used by pclm and pclm2D functions

Usage

pclm.fit(
  x,
  y,
  nlast,
  offset,
  out.step,
  verbose,
  lambda,
  kr,
  deg,
  diff,
  max.iter,
  tol,
  type
)

Arguments

x	Vector containing the starting values of the input intervals/bins. For example: if we have 3 bins [0,5), [5,10) and [10, 15), x will be defined by the vector: c(0, 5, 10).
y	Vector with counts to be ungrouped. It must have the same dimension as x.
nlast	Length of the last interval. In the example above nlast would be 5.
offset	Optional offset term to calculate smooth mortality rates. A vector of the same length as x and y, or one of the same length as the ungrouped output. See \insertCiterizzi2015;textualungroup for further details.
out.step	Length of estimated intervals in output. Values between 0.1 and 1 are accepted. Default: 1.
verbose	Logical value. Indicates whether a progress bar should be shown or not. Default: FALSE.
lambda	Smoothing parameter to be used in pclm estimation. If lambda = NA an algorithm will find the optimal values. pclm takes a single value. pclm2D takes two, one for the age axis and one for the year axis, and either may be NA to be found by optimisation while the other is held fixed.
kr	Knot ratio. Number of internal intervals used for defining 1 knot in B-spline basis construction. See MortSmooth_bbase. Default 2 in control.pclm and 7 in control.pclm2D. In the two-dimensional model kr applies to both axes, so it must not exceed the length of the shorter one: a panel of fewer than kr years has no internal knot and is rejected.
deg	Degree of the splines needed to create equally-spaced B-splines basis over an abscissa of data. Default: 3, a cubic spline. Must be an integer of at least 2.
diff	An integer indicating the order of differences of the components of PCLM coefficients. Default value: 2.
max.iter	Maximal number of iterations used in fitting procedure.
tol	Relative tolerance in PCLM fitting procedure. The iteration stops when the mean absolute relative error of the fitted bin totals falls below tol, or when that error stops changing by more than 0.1%, whichever comes first. Default: 1e-3. Note that it is a convergence tolerance on the fit, not an accuracy guarantee on the result. With a large lambda the penalty holds the fit away from the observed bins and the realized mean relative error can be several percent, because the second stopping rule fires long before tol is reached. Set tol = 1e-12 to see this: the fit does not move.
type	Type of PCLM model. Options: "1D", "2D" for univariate and two-dimensional model respectively.

ungroup documentation built on Oct. 3, 2026, 5:06 p.m.