Skip to contents

Calculate model implied regressions for a sequence of time intervals (if ct) or steps (if dt) based on a ctStanFit object, for specified subjects. Wrap with print() when used inside for loops! ctStanDiscretePars is maintained as a backward-compatible alias.

Usage

ctDiscretePars(
  fit,
  subjects = "popmean",
  times = seq(from = 0, to = 10, by = 0.1),
  nsamples = 200,
  impulseType = "unit",
  standardise = FALSE,
  cov = FALSE,
  plot = FALSE,
  cores = getOption("mc.cores", 2L),
  state = NULL,
  method = "linearise",
  realid = TRUE,
  ...,
  ctstanfitobj,
  observational
)

Arguments

fit

model fit from ctFit

subjects

Either 'popmean', to use the population mean parameter, or the subjects to use, as ids in the data (see realid).

times

Numeric vector of positive values, discrete time parameters will be calculated for each. If the fit object is a discrete time model, these should be positive integers.

nsamples

Number of samples from the stanfit to use for plotting. Higher values will increase smoothness / accuracy, at cost of plotting speed. Values greater than the total number of samples will be set to total samples.

impulseType

What a "one unit change in process c" is taken to bring with it. Every variant is dtDRIFT(t) %*% C for a different companion matrix C, whose column c says what else moves.

'unit' (the default)

C = I. An impulse of one unit (one standard deviation when standardise=TRUE) is applied to process c alone and nothing else moves, because the change was imposed. This is the partial regression E[x(t+u)|x(t)], and the only variant that is a property of the dynamics alone.

'observed'

C = Sigma diag(Sigma)^-1 with Sigma = asymDIFFUSIONcov. Process c is observed one unit above expectation and the others are not held fixed, so they move by Sigma_rc/Sigma_cc. This is the simple regression – what regressing the observed data on x_c alone recovers.

'shock'

C = Q diag(Q)^-1 with Q = DIFFUSIONcov. One hypothetical system noise innovation arrives in c, with companion innovations Q_rc/Q_cc. An impulse response rather than a regression.

'orthogonal'

From the Cholesky factor of DIFFUSION, so shocks are uncorrelated. Depends on the order of the latent processes, which is a modelling assumption rather than a property of the fit.

The companion matrices are asymmetric, and must be: a one unit move in a wide-spread process implies more movement in a narrow one than the reverse. 'observed' and 'shock' use different covariance matrices because they ask different questions, and coincide only under isotropic decay with no cross effects.

standardise

Logical, FALSE by default. If TRUE, report the effect of a one standard deviation change in process c as a change in r's own standard deviations, taking both scales from the stationary within subject covariance asymDIFFUSIONcov. That makes effects between processes on different scales comparable, and is what ctNetwork reports by default. FALSE leaves the effects in the processes' own units, so impulseType='unit', standardise=FALSE is the bare expm(DRIFT*t). A system with no stationary variance has nothing to standardise by, and those draws are returned as NaN with a message. The plot title states which scale was used either way.

cov

Logical. If TRUE, covariances are returned instead of regression coefficients.

plot

Logical. If TRUE, ggplots output using ctDiscreteParsPlot instead of returning output.

cores

Number of cpu cores to use for computing subject matrices. If subject matrices were saved during fiting, not used.

state

Evaluation point for any matrix cell that depends on the latent state or a time dependent predictor – see ctContextDependence. NULL (the default) or 'T0MEANS' uses the population initial state, with time dependent predictors at zero, which for a model whose dynamics depend on the state can be far from where the data are; 'mean' the mean smoothed latent state, 'asymptotic' the system's own fixed point; or supply a numeric state vector. The initial state and the fixed point are each draw's own, so the intervals include where they are; 'mean' is the estimate's, used for every draw, so its intervals leave out where that state is. A process that does not change (a latent predictor) is held at its initial value in finding the fixed point. Requires backend='julia' and subjects='popmean'. For a linear model the argument makes no difference, since no cell depends on the state.

method

How the interval regressions are obtained. 'linearise' (the default) exponentiates the drift's Jacobian at the evaluation point, expm(J*t) with J the model's JAx: the DRIFT matrix itself for a linear model, where it is exact, and for a model whose dynamics depend on the state, the response of the model linearised at state. Where a cell is nonlinear in the state the two differ: a DRIFT cell a + b*Y in the column of process Y is a + b*Y there, and contributes a + 2*b*Y to the Jacobian. A stan fit carries no Jacobian, and exponentiates DRIFT as evaluated at T0MEANS. The linearisation holds J fixed over the interval, so it is a fair interval regression near a fixed point, or over intervals short beside the dynamics; away from a fixed point the state moves during the interval, the nonlinear system's response can differ from it, and 'simulate' is the check. 'simulate' integrates the nonlinear system from state, and from state plus a shock of one stationary standard deviation in each process in turn (with the companion movements impulseType gives), and differences the trajectories, divided back to one unit (one standard deviation when standardise=TRUE): the model implied regression for a shock of that size. It starts at 1 and decays to 0 for a stable process, and reduces exactly to 'linearise' when no cell depends on the state; for a strongly nonlinear system the curve depends on the shock's size, and near a fixed point the difference from 'linearise' is that size's effect. 'simulate' requires backend='julia' and is slower, so it uses nsamples posterior draws with a small default.

realid

If TRUE (the default), subjects are read as the ids in the data, and integers that are not ids there are read as ctsem's numbering of the subjects, 1 to N, with a message. If FALSE, they are read as that numbering.

...

additional plotting arguments to control ctDiscreteParsPlot

ctstanfitobj

Deprecated. Use fit.

observational

Deprecated. Use impulseType: FALSE is 'unit' and TRUE is 'observed'.

Value

With plot = FALSE, an array of the discrete time coefficients, by sample, subject, time interval, row and column, of class ctDiscretePars: summary() gives each curve's peak, the lag of the peak, the lag at which it has fallen to half the peak (a half-life), and the area under it, with their uncertainty (summary.ctDiscretePars). On an optimised fit, with subjects = 'popmean', the same coefficients at the fit's estimate are attr(x, 'estimate'), by subject, time interval, row and column: for 'linearise' computed from the matrices ctSummaryMatrices(fit, state = )$estimate reports, for 'simulate' simulated at the estimate. The draws' mean or median need not equal them. summary() reads their quantities into an estimate column, and ctDiscreteParsPlot draws them as its line. A sampled fit has no estimate, and gives none; nor do subjects other than 'popmean', whose matrices come from each subject's filter pass over the draws. With plot = TRUE, a ggplot object.

Details

Two of these combinations are quantities you may already know under other names. impulseType='unit' with standardise=FALSE is the discrete time autoregression and cross-lagged matrix, expm(DRIFT*t). impulseType='observed' with standardise=TRUE is the model implied cross-correlation function, Cor(x_r(t+u), x_c(t)) – the model's counterpart to the empirical autocorrelations ctACF computes from the data, and equal to the latent correlation matrix at t=0.

If plot=TRUE, the function will return a ggplot2 object (and hence needs to be printed if intended to display within a loop). This can be modified by the various ggplot2 functions, or displayed using print(x).

Examples

data.table::setDTthreads(1) #ignore this line
ctDiscretePars(ctstantestfit,times=seq(.5,4,.1),
 plot=TRUE,indices='CR')

#modify plot
require(ggplot2)
g=ctDiscretePars(ctstantestfit,times=seq(.5,4,.1),
 plot=TRUE,indices='CR')
g= g+ labs(title='Cross effects')
print(g)