pclm: Univariate Penalized Composite Link Model (PCLM)
In ungroup: Penalized Composite Link Model for Efficient Estimation of Smooth Distributions from Coarsely Binned Data

Description Usage Arguments Details Value References See Also Examples

Fit univariate penalized composite link model (PCLM) to ungroup binned count data, e.g. age-at-death distributions grouped in age classes.

pclm(
  x,
  y,
  nlast,
  offset = NULL,
  out.step = 1,
  ci.level = 95,
  verbose = FALSE,
  control = list()
)

`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. See \insertCiterizzi2015;textualungroup for further details.
`out.step`	Length of estimated intervals in output. Values between 0.1 and 1 are accepted. Default: 1.
`ci.level`	Level of significance for computing confidence intervals. Default: `95`.
`verbose`	Logical value. Indicates whether a progress bar should be shown or not. Default: `FALSE`.
`control`	List with additional parameters: `lambda` – Smoothing parameter to be used in pclm estimation. If `lambda = NA` an algorithm will find the optimal values. kr – Knot ratio. Number of internal intervals used for defining 1 knot in B-spline basis construction. See `MortSmooth_bbase`. `deg` – Degree of the splines needed to create equally-spaced B-splines basis over an abscissa of data. `int.lambda` – If `lambda` is optimized an interval to be searched needs to be specified. Format: vector containing the end-points. `diff` – An integer indicating the order of differences of the components of PCLM coefficients. `opt.method` – Selection criterion of the model. Possible values are `"AIC"` and `"BIC"`. `max.iter` – Maximal number of iterations used in fitting procedure. `tol` – Relative tolerance in PCLM fitting procedure.

The PCLM method is based on the composite link model, which extends standard generalized linear models. It implements the idea that the observed counts, interpreted as realizations from Poisson distributions, are indirect observations of a finer (ungrouped) but latent sequence. This latent sequence represents the distribution of expected means on a fine resolution and has to be estimated from the aggregated data. Estimates are obtained by maximizing a penalized likelihood. This maximization is performed efficiently by a version of the iteratively reweighted least-squares algorithm. Optimal values of the smoothing parameter are chosen by minimizing Bayesian or Akaike's Information Criterion.

The output is a list with the following components:

`input`	A list with arguments provided in input. Saved for convenience.
`fitted`	The fitted values of the PCLM model.
`ci`	Confidence intervals around fitted values.
`goodness.of.fit`	A list containing goodness of fit measures: standard errors, AIC and BIC.
`smoothPar`	Estimated smoothing parameters: `lambda, kr` and `deg`.
`bins.definition`	Additional values to identify the bins limits and location in input and output objects.
`deep`	A list of objects created in the fitting process. Useful in diagnosis of possible issues.
`call`	An unevaluated function call, that is, an unevaluated expression which consists of the named function applied to the given arguments.

\insertAllCited

control.pclm plot.pclm

# Data  
x <- c(0, 1, seq(5, 85, by = 5))
y <- c(294, 66, 32, 44, 170, 284, 287, 293, 361, 600, 998, 
       1572, 2529, 4637, 6161, 7369, 10481, 15293, 39016)
offset <- c(114, 440, 509, 492, 628, 618, 576, 580, 634, 657, 
            631, 584, 573, 619, 530, 384, 303, 245, 249) * 1000
nlast <- 26 # the size of the last interval

# Example 1 ----------------------
M1 <- pclm(x, y, nlast)
ls(M1)
summary(M1)
fitted(M1)
plot(M1)

# Example 2 ----------------------
# ungroup even in smaller intervals
M2 <- pclm(x, y, nlast, out.step = 0.5)
head(fitted(M1))
plot(M1, type = "s")
# Note, in example 1 we are estimating intervals of length 1. In example 2 
# we are estimating intervals of length 0.5 using the same aggregate data.

# Example 3 ----------------------
# Do not optimise smoothing parameters; choose your own. Faster.
M3 <- pclm(x, y, nlast, out.step = 0.5, 
           control = list(lambda = 100, kr = 10, deg = 10))
plot(M3)

summary(M2)
summary(M3) # not the smallest BIC here, but sometimes is not important.

# Example 4 -----------------------
# Grouped x & grouped offset (estimate death rates)
M4 <- pclm(x, y, nlast, offset)
plot(M4, type = "s")

# Example 5 -----------------------
# Grouped x & ungrouped offset (estimate death rates)

ungroupped_Ex <- pclm(x, y = offset, nlast, offset = NULL)$fitted # ungroupped offset data

M5 <- pclm(x, y, nlast, offset = ungroupped_Ex)

Warning messages:
1: In rgl.init(initValue, onlyNULL) : RGL: unable to open X11 display
2: 'rgl.init' failed, running with 'rgl.useNULL = TRUE'. 
[1] "bin.definition"  "call"            "ci"              "deep"           
[5] "fitted"          "goodness.of.fit" "input"           "smoothPar"      

Penalized Composite Link Model (PCLM)

Call:
pclm(x = x, y = y, nlast = nlast)

PCLM Type                    : Univariate
Number of input groups       : 19
Number of fitted values      : 111
Length of estimate bins      : 1
Smoothing parameter lambda   : 0
B-splines intervals/knot (kr): 2
B-splines degree (deg)       : 3
AIC                          : 39.97
BIC                          : 59.81
      [0,1)       [1,2)       [2,3)       [3,4)       [4,5)       [5,6) 
 292.254945   47.567040   12.031104    5.101512    3.653694    3.801854 
      [6,7)       [7,8)       [8,9)      [9,10)     [10,11)     [11,12) 
   4.815457    6.352663    7.702012    8.349355    8.188017    7.844892 
    [12,13)     [13,14)     [14,15)     [15,16)     [16,17)     [17,18) 
   7.985346    9.025702   11.568904   16.221280   23.582754   33.474380 
    [18,19)     [19,20)     [20,21)     [21,22)     [22,23)     [23,24) 
  43.922241   52.410476   56.932803   57.933128   57.243741   56.233473 
    [24,25)     [25,26)     [26,27)     [27,28)     [28,29)     [29,30) 
  55.838792   56.123535   56.825906   57.606178   58.115022   58.277037 
    [30,31)     [31,32)     [32,33)     [33,34)     [34,35)     [35,36) 
  58.166052   58.010385   58.102700   58.696747   60.036110   62.332101 
    [36,37)     [37,38)     [38,39)     [39,40)     [40,41)     [41,42) 
  65.807514   70.655621   77.070029   85.156572   94.920752  106.255362 
    [42,43)     [43,44)     [44,45)     [45,46)     [46,47)     [47,48) 
 118.899308  132.628986  147.270502  162.850021  179.626932  197.884008 
    [48,49)     [49,50)     [50,51)     [51,52)     [52,53)     [53,54) 
 217.908603  239.747591  263.142589  287.749013  313.174561  339.648841 
    [54,55)     [55,56)     [56,57)     [57,58)     [58,59)     [59,60) 
 368.253616  401.033766  441.270637  492.262928  557.117381  637.375129 
    [60,61)     [61,62)     [62,63)     [63,64)     [64,65)     [65,66) 
 731.255969  833.938220  936.476422 1029.409950 1105.860969 1163.069720 
    [66,67)     [67,68)     [68,69)     [69,70)     [70,71)     [71,72) 
1204.488941 1235.701765 1263.485202 1294.268889 1333.474545 1385.809083 
    [72,73)     [73,74)     [74,75)     [75,76)     [76,77)     [77,78) 
1454.810931 1543.184019 1651.740928 1780.116411 1925.536316 2084.766185 
    [78,79)     [79,80)     [80,81)     [81,82)     [82,83)     [83,84) 
2255.232116 2435.332561 2626.617487 2830.882343 3049.000300 3278.429175 
    [84,85)     [85,86)     [86,87)     [87,88)     [88,89)     [89,90) 
3508.095452 3720.392827 3888.451678 3983.178892 3979.668950 3861.687654 
    [90,91)     [91,92)     [92,93)     [93,94)     [94,95)     [95,96) 
3628.237713 3292.607167 2882.269884 2431.775913 1977.636196 1550.974452 
    [96,97)     [97,98)     [98,99)    [99,100)   [100,101)   [101,102) 
1174.299714  859.519261  609.244616  418.991695  280.160080  182.530429 
  [102,103)   [103,104)   [104,105)   [105,106)   [106,107)   [107,108) 
 116.138627   72.331820   44.198811   26.560956   15.734729    9.210650 
  [108,109)   [109,110)   [110,111) 
   5.340380    3.074238    1.761168 
     [0,1)      [1,2)      [2,3)      [3,4)      [4,5)      [5,6) 
292.254945  47.567040  12.031104   5.101512   3.653694   3.801854 

Penalized Composite Link Model (PCLM)

Call:
pclm(x = x, y = y, nlast = nlast, out.step = 0.5)

PCLM Type                    : Univariate
Number of input groups       : 19
Number of fitted values      : 222
Length of estimate bins      : 0.5
Smoothing parameter lambda   : 8
B-splines intervals/knot (kr): 2
B-splines degree (deg)       : 3
AIC                          : 39.96
BIC                          : 59.8

Penalized Composite Link Model (PCLM)

Call:
pclm(x = x, y = y, nlast = nlast, out.step = 0.5, control = list(lambda = 100, 
    kr = 10, deg = 10))

PCLM Type                    : Univariate
Number of input groups       : 19
Number of fitted values      : 222
Length of estimate bins      : 0.5
Smoothing parameter lambda   : 100
B-splines intervals/knot (kr): 10
B-splines degree (deg)       : 10
AIC                          : 255.87
BIC                          : 267.49