# tfa_inertia

##### Transfer function Analysis

Transfer function analysis of inertia of a population matrix projection model using a specified perturbation structure.

##### Usage

`tfa_inertia(A, d, e, vector = "n", bound = NULL, prange, digits = 1e-10)`

##### Arguments

- A
a square, primitive, nonnegative numeric matrix of any dimension

- d, e
numeric vectors that determine the perturbation structure (see details).

- vector
(optional) a numeric vector or one-column matrix describing the age/stage distribution ('demographic structure') used to calculate the transfer function of a 'case-specific' inertia

- bound
(optional) specifies whether the transfer funciton of an upper or lower bound on inertia should be calculated (see details).

- prange
a numeric vector giving the range of perturbation magnitude (see details)

- digits
specifies which values of lambda should be excluded from analysis to avoid a computationally singular system (see details).

##### Details

`tfa_inertia`

calculates the transfer function of inertia of a
population matrix projection model given a perturbation structure
(specified using `d`

and `e`

), and a range of desired perturbation
magnitude (`prange`

). Currently `tfa_inertia`

can only work with
rank-one, single-parameter perturbations (see Hodgson & Townley 2006).

If `vector="n"`

then either `bound="upper"`

or `bound="lower"`

must be specified, which calculate the transfer function of the upper or
lower bound on population inertia (i.e. the largest and smallest values that
inertia may take) respectively. Specifying `vector`

overrides
calculation of a bound, and will yield a transfer function of a 'case-specific'
inertia.

The perturbation structure is determined by `d%*%t(e)`

. Therefore,
the rows to be perturbed are determined by `d`

and the columns to be
perturbed are determined by `e`

. The specific values in d and e will
determine the relative perturbation magnitude. So for example, if only entry
[3,2] of a 3 by 3 matrix is to be perturbed, then `d = c(0,0,1)`

and
`e = c(0,1,0)`

. If entries [3,2] and [3,3] are to be perturbed with the
magnitude of perturbation to [3,2] half that of [3,3] then `d = c(0,0,1)`

and `e = c(0,0.5,1)`

. `d`

and `e`

may also be expressed as
numeric one-column matrices, e.g. `d = matrix(c(0,0,1), ncol=1)`

,
`e = matrix(c(0,0.5,1), ncol=1)`

. See Hodgson et al. (2006) for more
information on perturbation structures.

The perturbation magnitude is determined by `prange`

, a numeric vector
that gives the continuous range of perterbation magnitude to evaluate over.
This is usually a sequence (e.g. `prange=seq(-0.1,0.1,0.001)`

), but
single transfer functions can be calculated using a single perturbation
magnitude (e.g. `prange=-0.1`

). Because of the nature of the equation
used to calculate the transfer function, `prange`

is used to find a
range of lambda from which the perturbation magnitudes are back-calculated,
and matched to their orresponding inertia, so the output perturbation
magnitude `p`

will match `prange`

in length and range but not in
numerical value (see Stott et al. 2012 for more information).

`tfa_inertia`

uses the resolvent matrix in its calculation, which
cannot be computed if any lambda in the equation are equal to the dominant
eigenvalue of `A`

. `digits`

specifies the values of lambda that
should be excluded in order to avoid a computationally singular system.
Any values equal to the dominant eigenvalue of `A`

rounded to an
accuracy of `digits`

are excluded. `digits`

should only need to
be changed when the system is found to be computationally singular, in
which case increasing `digits`

should help to solve the problem.

`tfa_inertia`

will not work for reducible matrices.

There is an S3 plotting method available (see `plot.tfa`

and examples below)

##### Value

A list containing numerical vectors:

- p
perturbation magnitudes

- lambda
dominant eigenvalues of perturbed matrices

iteminertiainertias of perturbed matrices

(Note that `p`

will not be exactly the same as `prange`

when
`prange`

is specified, as the code calculates p for a given lambda
rather than the other way around, with `prange`

only used to determine
max, min and number of lambda values to evaluate.)

##### References

Stott et al. (2012) Methods Ecol. Evol., 3, 673-684.

Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

##### See Also

S3 plotting method: `plot.tfa`

Other TransferFunctionAnalyses: `tfa_lambda`

,
`tfam_inertia`

, `tfam_lambda`

,
`tfs_inertia`

, `tfs_lambda`

Other PerturbationAnalyses: `elas`

,
`sens`

, `tfa_lambda`

,
`tfam_inertia`

, `tfam_lambda`

,
`tfs_inertia`

, `tfs_lambda`

##### Examples

```
# NOT RUN {
# Create a 3x3 matrix
( A <- matrix(c(0,1,2,0.5,0.1,0,0,0.6,0.6), byrow=TRUE, ncol=3) )
# Create an initial stage structure
( initial <- c(1,3,2) )
# Calculate the transfer function of upper bound on inertia
# given a perturbation to A[3,2]
( transfer<-tfa_inertia(A, d=c(0,0,1), e=c(0,1,0), bound="upper",
prange=seq(-0.6,0.4,0.01)) )
# Plot the transfer function using the S3 method (defaults to p
# and inertia in this case)
plot(transfer)
# Plot inertia against lambda using the S3 method
plot(transfer, xvar="lambda", yvar="inertia")
# Calculate the transfer function of case-specific inertia
# given perturbation to A[3,2] and A[3,3] with perturbation
# to A[3,2] half that of A[3,3]
( transfer2<-tfa_inertia(A, d=c(0,0,1), e=c(0,0.5,1), vector=initial,
prange=seq(-0.6,0.4,0.01)) )
# Plot inertia against p using the S3 method
plot(transfer2)
# Plot inertia against lambda without using the S3 method
plot(transfer$inertia~transfer$lambda,type="l",
xlab=expression(lambda),ylab="inertia")
# }
```

*Documentation reproduced from package popdemo, version 1.3-0, License: GPL (>= 2)*