growth {dembase} | R Documentation

## Calculate average growth rates or increments.

### Description

Calculate average growth rates or increments for a `DemographicArray` object.

### Usage

    growth(
      object,
      along = NULL,
      within = NULL,
      weights,
      type = c("linear", "exponential"),
      method = c("endpoints", "lm")
    )

    ## S4 method for signature 'Counts'
    growth(
      object,
      along = NULL,
      within = NULL,
      weights,
      type = c("exponential", "linear"),
      method = c("endpoints", "lm")
    )

    ## S4 method for signature 'Values'
    growth(
      object,
      along = NULL,
      within = NULL,
      weights,
      type = c("exponential", "linear"),
      method = c("endpoints", "lm")
    )

### Arguments

`object` | Object of class `DemographicArray`.
`along` | Name or index of dimension along which growth is calculated. If `along` is omitted, `growth` looks for a dimension with `dimtype` `"time"`, `"age"`, or `"cohort"` (in that order).
`within` | Name or index of dimensions within which growth is calculated. Value `"."` can be used as shorthand for "all dimensions other than `along`". Origin-destination or parent-child pairs can be referred to using their base name. See below for examples.
`weights` | Object of class `Counts`, supplying weights to be used when aggregating dimensions not included in `along` or `within`.
`type` | One of `"exponential"` or `"linear"`. If `"exponential"`, growth rates are calculated; if `"linear"`, increments are calculated. Can be abbreviated. Defaults to `"exponential"`.
`method` | One of `"endpoints"` or `"lm"`. See below for details.

### Details

The `along` dimension must have `dimscale` `"Intervals"` or `"Points"`, which means that it must have `dimtype` `"age"`, `"cohort"`, or `"time"`. The intervals or points do not need to be evenly spaced.

If there is a dimension with `dimtype` `"iteration"` and that dimension is not explicitly included in `within`, then it is added to `within` automatically.

All dimensions of `object` not included in `along` or `within` are aggregated before growth rates or increments are calculated.

If a `weights` argument is supplied when `object` has class `Counts`, the argument is ignored. If a `weights` argument is not supplied when `object` has class `Values`, all elements are given equal weight.

If `method` is `"endpoints"`, then growth rates or increments are calculated from the first and last points only. If `method` is `"lm"`, then growth rates are calculated by fitting a linear model to the logged values, and increments are calculated by fitting a linear model to the values.

### Value

If `within` is `NULL`, a numeric value; otherwise an object with the same class as `object`.

### See Also

`extrapolate`

### Examples

    ## construct data
    spend <- USPersonalExpenditure
    names(dimnames(spend)) <- c("category", "year")
    spend <- Counts(spend)

    ## calculate average growth rate across all categories
    growth(spend, along = "year")
    growth(spend) ## defaults to using dimension with dimtype "time"

    ## growth within categories
    growth(spend, within = "category")
    growth(spend, within = ".")

    ## increments rather than rates
    growth(spend, within = "category", type = "linear")

    ## two different methods for calculating
    growth(spend, within = "category")
    growth(spend, within = "category", method = "lm")

    ## use base name to specific origin and destination dimensions
    a <- array(rpois(n = 45, lambda = 10),
               dim = c(3, 3, 5),
               dimnames = list(reg_orig = 1:3,
                   reg_dest = 1:3, time = 2000:2004))
    x <- Counts(a, dimscales = c(time = "Points"))
    growth(x, within = c("reg_orig", "reg_dest"))
    growth(x, within = "reg")

[Package dembase version 0.0.0.119 Index]