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.
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) %*% Cfor a different companion matrixC, whose column c says what else moves.'unit'(the default)C = I. An impulse of one unit (one standard deviation whenstandardise=TRUE) is applied to process c alone and nothing else moves, because the change was imposed. This is the partial regressionE[x(t+u)|x(t)], and the only variant that is a property of the dynamics alone.'observed'C = Sigma diag(Sigma)^-1withSigma = asymDIFFUSIONcov. Process c is observed one unit above expectation and the others are not held fixed, so they move bySigma_rc/Sigma_cc. This is the simple regression – what regressing the observed data on x_c alone recovers.'shock'C = Q diag(Q)^-1withQ = DIFFUSIONcov. One hypothetical system noise innovation arrives in c, with companion innovationsQ_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,
FALSEby default. IfTRUE, 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 covarianceasymDIFFUSIONcov. That makes effects between processes on different scales comparable, and is whatctNetworkreports by default.FALSEleaves the effects in the processes' own units, soimpulseType='unit', standardise=FALSEis the bareexpm(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
ctDiscreteParsPlotinstead 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. Requiresbackend='julia'andsubjects='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)withJthe model'sJAx: 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 atstate. Where a cell is nonlinear in the state the two differ: a DRIFT cella + b*Yin the column of processYisa + b*Ythere, and contributesa + 2*b*Yto the Jacobian. A stan fit carries no Jacobian, and exponentiates DRIFT as evaluated atT0MEANS. The linearisation holdsJfixed 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 fromstate, and fromstateplus a shock of one stationary standard deviation in each process in turn (with the companion movementsimpulseTypegives), and differences the trajectories, divided back to one unit (one standard deviation whenstandardise=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'requiresbackend='julia'and is slower, so it usesnsamplesposterior 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:FALSEis'unit'andTRUEis'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).