diff --git a/DESCRIPTION b/DESCRIPTION index 59d9344..9ee7179 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: MARSS Type: Package Title: Multivariate Autoregressive State-Space Modeling -Version: 3.11.7 +Version: 3.11.8 Date: 2023-05-20 Depends: R (>= 3.5.0) Imports: diff --git a/NAMESPACE b/NAMESPACE index fcd2c25..95bf442 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -50,6 +50,7 @@ importFrom(generics,tidy) ## register S3 methods export(MARSSfit) # method +S3method(MARSSfit, default) S3method(MARSSfit, kem) S3method(MARSSfit, BFGS) diff --git a/NEWS.md b/NEWS.md index 6e648b1..fb292fc 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,11 @@ output: html_document --- -# MARSS 3.11.7 (GitHub) +# MARSS 3.11.8 (CRAN 2023-05-20) + +This combines the changes in GitHub releases 3.11.7 and 3.11.6. + +# MARSS 3.11.7 (GitHub 2023-05-19) This release is focused on moving the MARSS User Guide and derivation files into a `inst/userguide` and `inst/derivations` along with Makefiles to build. This will facilitate updating MARSS and converting the User Guide to an eBook. @@ -26,6 +30,10 @@ This release is focused on moving the MARSS User Guide and derivation files into * Added `inst/DEVELOPER_NOTES.md` * Minor change to make the v and w in `EMDerivation.Rnw` in slant font as they are random variables. +## OTHER + +* renamed `all.equal.vector` to `vector.all.equal()` so it is not interpreted as a method of `all.equal()`. + # MARSS 3.11.6 (GitHub) diff --git a/R/MARSS-methods.R b/R/MARSS-methods.R index 0cbd197..fbaa1b1 100644 --- a/R/MARSS-methods.R +++ b/R/MARSS-methods.R @@ -1,6 +1,10 @@ #' Generic for fitting MARSS models #' -#' Uses the method of a marssMLE class object. Will call a function such as [MARSSkem()], [MARSSoptim()] or `MARSStmb()` in the {marssTMB} package. +#' This is an internal function used by [MARSS()]. It is not +#' intended for use by users but needs to be exported so +#' {marssTMB} can use it. Uses the method of a marssMLE class object. +#' Will call a function such as [MARSSkem()], [MARSSoptim()] in the +#' MARSS package or `MARSStmb()` in the {marssTMB} package. #' @param x a [marssMLE] object. #' @param ... additional arguments for the fitting function MARSSfit <- function(x, ...) { @@ -8,7 +12,7 @@ MARSSfit <- function(x, ...) { } MARSSfit.default <- function(x, ...){ - stop("MARSS: Something is wrong. Did not find a method for the marssMLE object. Is method set incorrectly?\n There must be a MARSSfit.() function for each method.") + stop("MARSS: Something is wrong. Did not find a method for the marssMLE object. The first element of the call of the object should be the method. Did you call MARSSfit() with a marssMLE object? You need to add the method as the first element of the class.") } MARSSfit.kem <- function(x, ...) MARSSkem(x) diff --git a/R/toLatex_marssMODEL.R b/R/toLatex_marssMODEL.R index d9ba899..e60d127 100644 --- a/R/toLatex_marssMODEL.R +++ b/R/toLatex_marssMODEL.R @@ -369,7 +369,7 @@ build.eqn.tex <- function(eqn, eqn.special, x, greek, digits, simplify, headfoot # The following tests for that mat2D <- array(mat, dim = c(dim(mat)[1] * dim(mat)[2], dim(mat)[3])) # reform to be 2D # test equality within row; will return TRUE if dim 3 = 1 - if (all(apply(mat, 1, all.equal.vector))) { # not time-varying + if (all(apply(mat, 1, vector.all.equal))) { # not time-varying mat <- sub3D(mat, t = 1) # not time-varying so just use the mat at t=1 } else { # is time-varying if (!simplify) { # then there will be an equation for each parameter at time t @@ -378,7 +378,7 @@ build.eqn.tex <- function(eqn, eqn.special, x, greek, digits, simplify, headfoot } else { # do simplify # step 1: figure out which parameter elements are time-varying mat2D <- array(mat, dim = c(dim(mat)[1] * dim(mat)[2], dim(mat)[3])) # reform to be 2D, matrix(vec(mat),t) - tv.elem <- !apply(mat2D, 1, all.equal.vector) # which elements are time varying + tv.elem <- !apply(mat2D, 1, vector.all.equal) # which elements are time varying # step 2: replace that element with the name el2(i)_t tv.name <- paste(el2, "(", 1:dim(mat2D)[1], ")_", el2.time, sep = "") # step 3: set up a mat to be t=1; will replace time=varying ones @@ -443,9 +443,9 @@ parameters.time.varying <- function(eqn, eqn.special, x) { if (model.dims[[el2]][3] == 1) next # it is not time-varying # Even if 3D, it might not be time-varying if all elements are the same testtv <- FALSE - if (!all(apply(fixed[[el2]], 1, all.equal.vector))) testtv <- TRUE # time-varying + if (!all(apply(fixed[[el2]], 1, vector.all.equal))) testtv <- TRUE # time-varying mat2D <- array(free[[el2]], dim = c(dim(free[[el2]])[1] * dim(free[[el2]])[2], dim(free[[el2]])[3])) - if (!all(apply(mat2D, 1, all.equal.vector))) testtv <- TRUE # time-varying + if (!all(apply(mat2D, 1, vector.all.equal))) testtv <- TRUE # time-varying if (!testtv) { # not time-varying next } else { diff --git a/R/utility_functions.R b/R/utility_functions.R index 9c9441b..fda01c9 100644 --- a/R/utility_functions.R +++ b/R/utility_functions.R @@ -869,7 +869,7 @@ is.solvable <- function(A, y = NULL) { return("unique") } -all.equal.vector <- function(x) { +vector.all.equal <- function(x) { all(sapply(as.list(x[-1]), FUN = function(z) { identical(z, unlist(x[1])) })) diff --git a/cran-comments.md b/cran-comments.md index 976a08e..9a0ecc0 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,3 +1,9 @@ +## Tested on OS + +* `rhub::check_for_cran()` +* M1 MacBook +* R versions 4.3 and 4.2 + ## R CMD check results 0 errors | 0 warnings | 3 notes @@ -7,22 +13,13 @@ sub-directories of 1Mb or more: doc 4.6Mb -* checking DESCRIPTION meta-information ... NOTE - Maintainer field differs from that derived from Authors@R - Maintainer: ‘Elizabeth Holmes - NOAA Federal ’ - Authors@R: ‘Elizabeth Eli Holmes ’ - -For auto-check of the email that submission comes from, I use the form that my work email uses. - -* checking CRAN incoming feasibility ... NOTE - Maintainer: ‘Elizabeth Holmes - NOAA Federal ’ * Suggests or Enhances not in mainstream repositories: marssTMB Availability using Additional_repositories specification: marssTMB yes https://atsa-es.r-universe.dev - This is correct. +This is correct. ─ checking CRAN incoming feasibility ... [20s] NOTE Maintainer: 'Elizabeth Eli Holmes ' @@ -32,13 +29,9 @@ For auto-check of the email that submission comes from, I use the form that my w Old maintainer(s): Elizabeth Holmes - NOAA Federal - Correct. - - Possibly misspelled words in DESCRIPTION: - TMB (23:89) - marssTMB (24:16) - - +Correct. I changed to using Authors@R format + + ## revdepcheck results We checked 2 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package. diff --git a/inst/DEVELOPER_NOTES.md b/inst/DEVELOPER_NOTES.md index 90dfc66..7fa701a 100644 --- a/inst/DEVELOPER_NOTES.md +++ b/inst/DEVELOPER_NOTES.md @@ -154,6 +154,8 @@ These are the tests in `tests/testthat`. All should pass but some give warnings. cd inst make ``` +However I usually run it one target at a time. + Now using the final tar.gz file do the final tests. @@ -165,10 +167,6 @@ rm -r ~/Dropbox/MARSS.Rcheck R CMD check --timings --as-cran MARSS_3.11.7.tar.gz ``` - -However I usually run it one target at a time. - - ## Check on other OS * [ ] `devtools::check_win_devel()` diff --git a/inst/Makefile b/inst/Makefile index 8c63c36..27ef98d 100644 --- a/inst/Makefile +++ b/inst/Makefile @@ -1,5 +1,5 @@ RM = rm -f -version = 3.11.7 +version = 3.11.8 GitHubdir = ~/Documents/GitHub tmpdir = ~/Dropbox @@ -24,12 +24,14 @@ build: rm -r -f ${tmpdir}/MARSS rm -f ${tmpdir}/MARSS_${version}.tar.gz cp -p $(GitHubdir)/MARSS_${version}.tar.gz ${tmpdir}/MARSS_${version}.tar.gz + cd $(tmpdir) && tar -xvzf ${tmpdir}/MARSS_${version}.tar.gz movetodoc: - cd $(tmpdir) && tar -xvzf ${tmpdir}/MARSS_${version}.tar.gz rm -f ${tmpdir}/MARSS/inst/doc/*.pdf cp -a -p ${GitHubdir}/MARSS/inst/derivations/doc/*.pdf ${tmpdir}/MARSS/inst/doc cp -a -p ${GitHubdir}/MARSS/inst/userguide/doc/. $(tmpdir)/MARSS/inst/doc/ + cp -a -p ${GitHubdir}/MARSS/inst/derivations/doc/. ${GitHubdir}/MARSS/inst/doc/ + cp -a -p ${GitHubdir}/MARSS/inst/userguide/doc/. $(GitHubdir)/MARSS/inst/doc/ rebuild: cd $(tmpdir) && R CMD build --no-build-vignettes MARSS diff --git a/inst/derivations/Residuals-concordance.tex b/inst/derivations/Residuals-concordance.tex new file mode 100644 index 0000000..cf9a595 --- /dev/null +++ b/inst/derivations/Residuals-concordance.tex @@ -0,0 +1,2 @@ +\Sconcordance{concordance:Residuals.tex:Residuals.Rnw:% +1 175 1 1 0 628 1} diff --git a/inst/derivations/Residuals.bbl b/inst/derivations/Residuals.bbl new file mode 100644 index 0000000..799f1fd --- /dev/null +++ b/inst/derivations/Residuals.bbl @@ -0,0 +1,38 @@ +\begin{thebibliography}{} + +\bibitem[Commandeur and Koopman, 2007]{CommandeurKoopman2007} +Commandeur, J.~J. and Koopman, S.~J. (2007). +\newblock {\em An introduction to state space time series analysis}. +\newblock Practical Econometrics. Oxford University Press, Oxford. + +\bibitem[de~Jong, 1988]{deJong1988} +de~Jong, P. (1988). +\newblock A cross-validation filter for time series models. +\newblock {\em Biometrika}, 75(3):594--600. + +\bibitem[de~Jong and Penzer, 1998]{deJongPenzer1998} +de~Jong, P. and Penzer, J. (1998). +\newblock Diagnosing shocks in time series. +\newblock {\em Journal of the American Statistical Association}, 93(442):796--806. + +\bibitem[Harvey and Koopman, 1992]{HarveyKoopman1992} +Harvey, A. and Koopman, S.~J. (1992). +\newblock Diagnostic checking of unobserved-components time series models. +\newblock {\em Journal of Business and Economic Statistics,}, 10:377--389. + +\bibitem[Harvey et~al., 1998]{Harveyetal1998} +Harvey, A., Koopman, S.~J., and Penzer, J. (1998). +\newblock Messy time series: a unified approach. +\newblock {\em Advances in Econometrics}, 13:103--143. + +\bibitem[Holmes, 2012]{Holmes2010} +Holmes, E.~E. (2012). +\newblock Derivation of the {EM} algorithm for constrained and unconstrained {MARSS} models. +\newblock Technical report, arXiv:1302.3919 [stat.ME]. + +\bibitem[Shumway and Stoffer, 2006]{ShumwayStoffer2006} +Shumway, R. and Stoffer, D. (2006). +\newblock {\em Time series analysis and its applications}. +\newblock Springer-Science+Business Media, LLC, New York, New York, 2nd edition. + +\end{thebibliography} diff --git a/inst/derivations/Residuals.log b/inst/derivations/Residuals.log new file mode 100644 index 0000000..362a38f --- /dev/null +++ b/inst/derivations/Residuals.log @@ -0,0 +1,251 @@ +This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex 2023.5.14) 19 MAY 2023 20:46 +entering extended mode + restricted \write18 enabled. + %&-line parsing enabled. +**Residuals.tex +(./Residuals.tex +LaTeX2e <2022-11-01> patch level 1 +L3 programming layer <2023-05-11> (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/article.cls +Document Class: article 2022/07/02 v1.4n Standard LaTeX document class +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/size10.clo +File: size10.clo 2022/07/02 v1.4n Standard LaTeX file (size option) +) +\c@part=\count185 +\c@section=\count186 +\c@subsection=\count187 +\c@subsubsection=\count188 +\c@paragraph=\count189 +\c@subparagraph=\count190 +\c@figure=\count191 +\c@table=\count192 +\abovecaptionskip=\skip48 +\belowcaptionskip=\skip49 +\bibindent=\dimen140 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/multirow/multirow.sty +Package: multirow 2021/03/15 v2.8 Span multiple rows of a table +\multirow@colwidth=\skip50 +\multirow@cntb=\count193 +\multirow@dima=\skip51 +\bigstrutjot=\dimen141 +) (./footmisc.sty +Package: footmisc 2007/06/12 v5.4a a miscellany of footnote facilities +\FN@temptoken=\toks16 +\footnotemargin=\dimen142 + + +LaTeX Warning: Command \@footnotetext has changed. + Check if current package is valid. + +\c@pp@next@reset=\count194 +Package footmisc Info: Declaring symbol style bringhurst on input line 910. +Package footmisc Info: Declaring symbol style chicago on input line 918. +Package footmisc Info: Declaring symbol style wiley on input line 927. +Package footmisc Info: Declaring symbol style lamport-robust on input line 938. +Package footmisc Info: Declaring symbol style lamport* on input line 958. +Package footmisc Info: Declaring symbol style lamport*-robust on input line 979. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/natbib/natbib.sty +Package: natbib 2010/09/13 8.31b (PWD, AO) +\bibhang=\skip52 +\bibsep=\skip53 +LaTeX Info: Redefining \cite on input line 694. +\c@NAT@ctr=\count195 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsmath.sty +Package: amsmath 2022/04/08 v2.17n AMS math features +\@mathmargin=\skip54 + +For additional information on amsmath, use the `?' option. +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amstext.sty +Package: amstext 2021/08/26 v2.01 AMS text + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsgen.sty +File: amsgen.sty 1999/11/30 v2.0 generic functions +\@emptytoks=\toks17 +\ex@=\dimen143 +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsbsy.sty +Package: amsbsy 1999/11/29 v1.2d Bold Symbols +\pmbraise@=\dimen144 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsopn.sty +Package: amsopn 2022/04/08 v2.04 operator names +) +\inf@bad=\count196 +LaTeX Info: Redefining \frac on input line 234. +\uproot@=\count197 +\leftroot@=\count198 +LaTeX Info: Redefining \overline on input line 399. +LaTeX Info: Redefining \colon on input line 410. +\classnum@=\count199 +\DOTSCASE@=\count266 +LaTeX Info: Redefining \ldots on input line 496. +LaTeX Info: Redefining \dots on input line 499. +LaTeX Info: Redefining \cdots on input line 620. +\Mathstrutbox@=\box51 +\strutbox@=\box52 +LaTeX Info: Redefining \big on input line 722. +LaTeX Info: Redefining \Big on input line 723. +LaTeX Info: Redefining \bigg on input line 724. +LaTeX Info: Redefining \Bigg on input line 725. +\big@size=\dimen145 +LaTeX Font Info: Redeclaring font encoding OML on input line 743. +LaTeX Font Info: Redeclaring font encoding OMS on input line 744. +\macc@depth=\count267 +LaTeX Info: Redefining \bmod on input line 905. +LaTeX Info: Redefining \pmod on input line 910. +LaTeX Info: Redefining \smash on input line 940. +LaTeX Info: Redefining \relbar on input line 970. +LaTeX Info: Redefining \Relbar on input line 971. +\c@MaxMatrixCols=\count268 +\dotsspace@=\muskip16 +\c@parentequation=\count269 +\dspbrk@lvl=\count270 +\tag@help=\toks18 +\row@=\count271 +\column@=\count272 +\maxfields@=\count273 +\andhelp@=\toks19 +\eqnshift@=\dimen146 +\alignsep@=\dimen147 +\tagshift@=\dimen148 +\tagwidth@=\dimen149 +\totwidth@=\dimen150 +\lineht@=\dimen151 +\@envbody=\toks20 +\multlinegap=\skip55 +\multlinetaggap=\skip56 +\mathdisplay@stack=\toks21 +LaTeX Info: Redefining \[ on input line 2953. +LaTeX Info: Redefining \] on input line 2954. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/amsfonts.sty +Package: amsfonts 2013/01/14 v3.01 Basic AMSFonts support +\symAMSa=\mathgroup4 +\symAMSb=\mathgroup5 +LaTeX Font Info: Redeclaring math symbol \hbar on input line 98. +LaTeX Font Info: Overwriting math alphabet `\mathfrak' in version `bold' +(Font) U/euf/m/n --> U/euf/b/n on input line 106. +) (/Library/Frameworks/R.framework/Resources/share/texmf/tex/latex/Sweave.sty +Package: Sweave + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/ifthen.sty +Package: ifthen 2022/04/13 v1.1d Standard LaTeX ifthen package (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/iftex/iftex.sty +Package: iftex 2022/02/03 v1.0f TeX engine tests +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphicx.sty +Package: graphicx 2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/keyval.sty +Package: keyval 2022/05/29 v1.15 key=value parser (DPC) +\KV@toks@=\toks22 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphics.sty +Package: graphics 2022/03/10 v1.4e Standard LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/trig.sty +Package: trig 2021/08/11 v1.11 sin cos tan (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-cfg/graphics.cfg +File: graphics.cfg 2016/06/04 v1.11 sample graphics configuration +) +Package graphics Info: Driver file: pdftex.def on input line 107. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-def/pdftex.def +File: pdftex.def 2022/09/22 v1.2b Graphics/color driver for pdftex +)) +\Gin@req@height=\dimen152 +\Gin@req@width=\dimen153 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty +Package: fancyvrb 2023/01/19 4.5a verbatim text (tvz,hv) +\FV@CodeLineNo=\count274 +\FV@InFile=\read2 +\FV@TabBox=\box53 +\c@FancyVerbLine=\count275 +\FV@StepNumber=\count276 +\FV@OutFile=\write3 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/textcomp.sty +Package: textcomp 2020/02/02 v2.0n Standard LaTeX package +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/fontenc.sty +Package: fontenc 2021/04/29 v2.0v Standard LaTeX package +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/l3backend/l3backend-pdftex.def +File: l3backend-pdftex.def 2023-04-19 L3 backend support: PDF output (pdfTeX) +\l__color_backend_stack_int=\count277 +\l__pdf_internal_box=\box54 +) (./Residuals.aux) +\openout1 = `Residuals.aux'. + +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/epstopdf-pkg/epstopdf-base.sty +Package: epstopdf-base 2020-01-24 v2.11 Base part for package epstopdf + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/infwarerr/infwarerr.sty +Package: infwarerr 2019/12/03 v1.5 Providing info/warning/error messages (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/grfext/grfext.sty +Package: grfext 2019/12/03 v1.3 Manage graphics extensions (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/kvdefinekeys/kvdefinekeys.sty +Package: kvdefinekeys 2019-12-19 v1.6 Define keys (HO) +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvoptions/kvoptions.sty +Package: kvoptions 2022-06-15 v3.15 Key value format for package options (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/ltxcmds/ltxcmds.sty +Package: ltxcmds 2020-05-10 v1.25 LaTeX kernel commands for general use (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvsetkeys/kvsetkeys.sty +Package: kvsetkeys 2022-10-05 v1.19 Key value parser (HO) +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/pdftexcmds/pdftexcmds.sty +Package: pdftexcmds 2020-06-27 v0.33 Utility functions of pdfTeX for LuaTeX (HO) +Package pdftexcmds Info: \pdf@primitive is available. +Package pdftexcmds Info: \pdf@ifprimitive is available. +Package pdftexcmds Info: \pdfdraftmode found. +) +Package epstopdf-base Info: Redefining graphics rule for `.eps' on input line 485. +Package grfext Info: Graphics extension search list: +(grfext) [.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2,.eps] +(grfext) \AppendGraphicsExtensions on input line 504. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/latexconfig/epstopdf-sys.cfg +File: epstopdf-sys.cfg 2010/07/13 v1.3 Configuration of (r)epstopdf for TeX Live +)) (./Residuals-concordance.tex) +LaTeX Font Info: Trying to load font information for U+msa on input line 184. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsa.fd +File: umsa.fd 2013/01/14 v3.01 AMS symbols A +) +LaTeX Font Info: Trying to load font information for U+msb on input line 184. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsb.fd +File: umsb.fd 2013/01/14 v3.01 AMS symbols B +) +Underfull \hbox (badness 10000) in paragraph at lines 184--184 +[][]\T1/cmr/m/n/8 Northwest Fish-eries Sci-ence Cen-ter, NOAA Fish-eries, Seat-tle, WA 98112, eli.holmes@noaa.gov, + [] + +[1 + +{/Users/eli.holmes/Library/TinyTeX/texmf-var/fonts/map/pdftex/updmap/pdftex.map}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-t1.enc}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-ts1.enc}] [2] [3] +LaTeX Font Info: Trying to load font information for T1+cmtt on input line 326. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/t1cmtt.fd +File: t1cmtt.fd 2022/07/10 v2.5l Standard LaTeX font definitions +) [4] [5] [6] [7] [8] +Overfull \hbox (8.32883pt too wide) detected at line 562 +[][] \OML/cmm/m/it/10 : + [] + +[9] [10] [11] [12] +Overfull \hbox (3.60258pt too wide) in paragraph at lines 800--801 +[]\T1/cmr/m/n/10 Equation 85[] gives the equa-tion for the case where $[][]$ is par-tially ob-served. $[][]$ is out-put by the [][]\T1/cmtt/m/n/10 MARSShatyt() + [] + +(./Residuals.bbl [13]) [14] (./Residuals.aux) ) +Here is how much of TeX's memory you used: + 4104 strings out of 478007 + 65557 string characters out of 5838177 + 1912999 words of memory out of 5000000 + 24184 multiletter control sequences out of 15000+600000 + 536532 words of font info for 95 fonts, out of 8000000 for 9000 + 14 hyphenation exceptions out of 8191 + 72i,22n,76p,1268b,300s stack positions out of 10000i,1000n,20000p,200000b,200000s + +Output written on Residuals.pdf (14 pages, 593278 bytes). +PDF statistics: + 245 PDF objects out of 1000 (max. 8388607) + 150 compressed objects within 2 object streams + 0 named destinations out of 1000 (max. 500000) + 5 words of extra memory for PDF output out of 10000 (max. 10000000) + diff --git a/inst/derivations/Residuals.pdf b/inst/derivations/Residuals.pdf index a5fa880..be10449 100644 Binary files a/inst/derivations/Residuals.pdf and b/inst/derivations/Residuals.pdf differ diff --git a/inst/derivations/Residuals.synctex.gz b/inst/derivations/Residuals.synctex.gz new file mode 100644 index 0000000..b3f3adb Binary files /dev/null and b/inst/derivations/Residuals.synctex.gz differ diff --git a/inst/derivations/Residuals.tex b/inst/derivations/Residuals.tex new file mode 100644 index 0000000..7795954 --- /dev/null +++ b/inst/derivations/Residuals.tex @@ -0,0 +1,805 @@ +%\VignetteIndexEntry{Residuals} +%\VignettePackage{MARSS} +\documentclass[]{article} +%set margins to 1in without fullsty + \addtolength{\oddsidemargin}{-.875in} + \addtolength{\evensidemargin}{-.875in} + \addtolength{\textwidth}{1.75in} + + \addtolength{\topmargin}{-.875in} + \addtolength{\textheight}{1.75in} +%\usepackage{fullpage} %more standardized margins + +% choose options for [] as required from the list +% in the Reference Guide, Sect. 2.2 + +\usepackage{multirow} +\usepackage[bottom]{footmisc}% places footnotes at page bottom +\usepackage[round]{natbib} + +% Math stuff +\usepackage{amsmath} % the standard math package +\usepackage{amsfonts} % the standard math package +%%%% bold maths symbol system: +\def\uupsilon{\pmb{\upsilon}} +\def\llambda{\pmb{\lambda}} +\def\bbeta{\pmb{\beta}} +\def\aalpha{\pmb{\alpha}} +\def\zzeta{\pmb{\zeta}} +\def\etaeta{\mbox{\boldmath $\eta$}} +\def\xixi{\mbox{\boldmath $\xi$}} +\def\pipi{\pmb{\pi}} +\def\ep{\mbox{\boldmath $\epsilon$}} +\def\DEL{\mbox{\boldmath $\Delta$}} +\def\PHI{\mbox{\boldmath $\Phi$}} +\def\PI{\mbox{\boldmath $\Pi$}} +\def\LAM{\mbox{\boldmath $\Lambda$}} +\def\LAMm{\mathbb{L}} +\def\GAM{\mbox{\boldmath $\Gamma$}} +\def\OMG{\mbox{\boldmath $\Omega$}} +\def\SI{\mbox{\boldmath $\Sigma$}} +\def\TH{\mbox{\boldmath $\Theta$}} +\def\UPS{\mbox{\boldmath $\Upsilon$}} +\def\XI{\mbox{\boldmath $\Xi$}} +\def\AA{\mbox{$\mathbf A$}} \def\aa{\mbox{$\mathbf a$}} +\def\Ab{\mbox{$\mathbf D$}} \def\Aa{\mbox{$\mathbf d$}} \def\Am{\PI} +\def\BB{\mbox{$\mathbf B$}} \def\bb{\mbox{$\mathbf b$}} \def\Bb{\mbox{$\mathbf J$}} \def\Ba{\mbox{$\mathbf L$}} \def\Bm{\UPS} +\def\CC{\mbox{$\mathbf C$}} \def\cc{\mbox{$\mathbf c$}} +\def\Ca{\Delta} \def\Cb{\GAM} +\def\DD{\mbox{$\mathbf D$}} \def\dd{\mbox{$\mathbf d$}} +\def\EE{\mbox{$\mathbf E$}} \def\ee{\mbox{$\mathbf e$}} +\def\E{\,\textup{\textrm{E}}} +\def\EXy{\,\textup{\textrm{E}}_{\text{{\bf XY}}}} +\def\FF{\mbox{$\mathbf F$}} \def\ff{\mbox{$\mathbf f$}} +\def\GG{\mbox{$\mathbf G$}} \def\gg{\mbox{$\mathbf g$}} +\def\HH{\mbox{$\mathbf H$}} \def\hh{\mbox{$\mathbf h$}} +\def\II{\mbox{$\mathbf I$}} \def\ii{\mbox{$\mathbf i$}} +\def\IIm{\mbox{$\mathbf I$}} +\def\JJ{\mbox{$\mathbf J$}} +\def\KK{\mbox{$\mathbf K$}} +\def\LL{\mbox{$\mathbf L$}} \def\ll{\mbox{$\mathbf l$}} +\def\MM{\mbox{$\mathbf M$}} \def\mm{\mbox{$\mathbf m$}} +\def\N{\,\textup{\textrm{N}}} +\def\MVN{\,\textup{\textrm{MVN}}} +\def\OO{\mbox{$\mathbf O$}} +\def\PP{\mbox{$\mathbf P$}} \def\pp{\mbox{$\mathbf p$}} +\def\QQ{\mbox{$\mathbf Q$}} \def\qq{\mbox{$\mathbf q$}} \def\Qb{\mbox{$\mathbf G$}} \def\Qm{\mathbb{Q}} +\def\RR{\mbox{$\mathbf R$}} \def\rr{\mbox{$\mathbf r$}} \def\Rb{\mbox{$\mathbf H$}} \def\Rm{\mathbb{R}} +\def\Ss{\mbox{$\mathbf S$}} +\def\UU{\mbox{$\mathbf U$}} \def\uu{\mbox{$\mathbf u$}} +\def\Ub{\mbox{$\mathbf C$}} \def\Ua{\mbox{$\mathbf c$}} \def\Um{\UPS} +%\def\VV{\mbox{$\mathbf V$}} \def\vv{\mbox{$\mathbf v$}} +\def\VV{\mbox{$\pmb{V}$}} \def\vv{\mbox{$\pmb{v}$}} +%\def\WW{\mbox{$\mathbf W$}} \def\ww{\mbox{$\mathbf w$}} +\def\WW{\mbox{$\pmb{W}$}} \def\ww{\mbox{$\pmb{w}$}} +%\def\XX{\mbox{$\mathbf X$}} +\def\XX{\mbox{$\pmb{X}$}} \def\xx{\mbox{$\pmb{x}$}} +%\def\xx{\mbox{$\mathbf x$}} +%\def\YY{\mbox{$\mathbf Y$}} +\def\YY{\mbox{$\pmb{Y}$}} \def\yy{\mbox{$\pmb{y}$}} +%\def\yy{\mbox{$\mathbf y$}} +\def\ZZ{\mbox{$\mathbf Z$}} \def\zz{\mbox{$\mathbf z$}} \def\Zb{\mbox{$\mathbf M$}} \def\Za{\mbox{$\mathbf N$}} \def\Zm{\XI} +\def\zer{\mbox{\boldmath $0$}} +\def\chol{\,\textup{\textrm{chol}}} +\def\vec{\,\textup{\textrm{vec}}} +\def\var{\,\textup{\textrm{var}}} +\def\cov{\,\textup{\textrm{cov}}} +\def\diag{\,\textup{\textrm{diag}}} +\def\trace{\,\textup{\textrm{trace}}} +\def\dg{\,\textup{\textrm{dg}}} +\def\hatxtT{\widetilde{\xx}_t^T} +\def\hatxtpT{\widetilde{\xx}_{t+1}^T} +\def\hatxtt{\widetilde{\xx}_t^{t}} +\def\hatxttm{\widetilde{\xx}_t^{t-1}} +\def\hatxone{\widetilde{\xx}_1} +\def\hatxzero{\widetilde{\xx}_0} +\def\hatxtmT{\widetilde{\xx}_{t-1}^T} +\def\hatxtmt1{\widetilde{\xx}_{t-1}^{t-1}} +\def\hatxtpt1{\widetilde{\xx}_{t+1}^{t-1}} +\def\hatxQtm{\widetilde{\mathbb{x}}_{t-1}} +\def\hatyt{\widetilde{\yy}_t} +\def\hatyyt{\widetilde{\mbox{$\mathbf y$}\mbox{$\mathbf y$}^\top}_t} +\def\hatyone{\widetilde{\yy}_1} +\def\hatOt{\widetilde{\OO}_t} +\def\hatWt{\widehat{\WW}_t} +\def\hatWtp{\widehat{\WW}_{t+1}} +\def\hatwt{\widehat{\ww}_t} +\def\hatwtp{\widehat{\ww}_{t+1}} +\def\checkWt{\overline{\WW}_{t}} +\def\checkWtp{\overline{\WW}_{t+1}} +\def\checkwt{\overline{\ww}_t} +\def\checkwtp{\overline{\ww}_{t+1}} +\def\hatYXt{\widetilde{\mbox{$\yy\xx$}}_t} +\def\hatXYt{\widetilde{\mbox{$\xx\yy$}}_t} +\def\hatYXttm{\widetilde{\mbox{$\yy\xx$}}_{t,t-1}} +\def\hatPt{\widetilde{\PP}_t} +\def\hatPtm{\widetilde{\PP}_{t-1}} +\def\hatPQtm{\widetilde{\mathbb{P}}_{t-1}} +\def\hatPttm{\widetilde{\PP}_{t,t-1}} +\def\hatPQttm{\widetilde{\mathbb{P}}_{t,t-1}} +\def\hatPtmt{\widetilde{\PP}_{t-1,t}} +\def\hatVt{\widehat{\VV}_t} +\def\hatvt{\widehat{\vv}_t} +\def\checkvt{\overline{\vv}_t} +\def\checkvtp{\overline{\vv}_{t+1}} +\def\checkVtp{\overline{\VV}_{t+1}} +\def\checkVt{\overline{\VV}_t} +\def\dotvt{\dot{\vv}_t} +\def\dotvtp{\dot{\vv}_{t+1}} +\def\dotVtp{\dot{\VV}_{t+1}} +\def\dotVt{\dot{\VV}_t} +\def\hatVtT{\widetilde{\VV}_t^T} +\def\hatVttm{\widetilde{\VV}_t^{t-1}} +\def\hatVtt{\widetilde{\VV}_t^{t}} +\def\hatVtmT{\widetilde{\VV}_{t-1}^T} +\def\hatVtmt1{\widetilde{\VV}_{t-1}^{t-1}} +\def\hatVttmT{\widetilde{\VV}_{t,t-1}^T} +\def\hatVtmtT{\widetilde{\VV}_{t-1,t}^T} +\def\hatVttmt1{\widetilde{\VV}_{t,t-1}^{t-1}} +\def\hatVtpT{\widetilde{\VV}_{t+1}^T} +\def\hatVttpT{\widetilde{\VV}_{t,t+1}^T} +\def\hatVttpt1{\widetilde{\VV}_{t,t+1}^{t-1}} +\def\hatVtptT{\widetilde{\VV}_{t+1,t}^T} +\def\hatVtptt1{\widetilde{\VV}_{t+1,t}^{t-1}} +\def\hatUtT{\widetilde{\UU}_t^T} +\def\hatUtt1{\widetilde{\UU}_t^{t-1}} +\def\hatStT{\widetilde{\Ss}_t^T} +\def\hatSttm{\widetilde{\Ss}_t^{t-1}} +\def\hatStt{\widetilde{\Ss}_t^{t}} +\def\hatSttmT{\widetilde{\Ss}_{t,t-1}^T} +\def\hatSttmt1{\widetilde{\Ss}_{t,t-1}^{t-1}} +\def\hatSttpT{\widetilde{\Ss}_{t,t+1}^T} +\def\hatSttpt1{\widetilde{\Ss}_{t,t+1}^{t-1}} +\def\hatBmt{\widetilde{\Bm}_t} +\def\hatCat{\widetilde{\Ca}_t} +\def\hatCbt{\widetilde{\Cb}_t} +\def\hatZmt{\widetilde{\Zm}_t} +\def\YYr{\dot{\mbox{$\pmb{Y}$}}} +\def\yyr{\dot{\mbox{$\pmb{y}$}}} +\def\aar{\dot{\mbox{$\mathbf a$}}} +\def\ZZr{\dot{\mbox{$\mathbf Z$}}} +\def\RRr{\dot{\mbox{$\mathbf R$}}} +\def\IR{\nabla} +\usepackage[round]{natbib} % to get references that are like in ecology papers +% \citet{} for inline citation name (year); \citep for citation in parens (name year) + +%allow lines in matrix +\makeatletter +\renewcommand*\env@matrix[1][*\c@MaxMatrixCols c]{% + \hskip -\arraycolsep + \let\@ifnextchar\new@ifnextchar + \array{#1}} +\makeatother +\setcounter{tocdepth}{1} %no subsections in toc + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\usepackage{Sweave} +\begin{document} +\input{Residuals-concordance} +\author{E. E. Holmes\footnote{Northwest Fisheries Science Center, NOAA Fisheries, Seattle, WA 98112, + eli.holmes@noaa.gov, http://faculty.washington.edu/eeholmes}} +\title{Computation of Standardized Residuals for MARSS Models} +\date{original 31 Oct 2014 \\ +\small{\emph{added normalization calculations, 20 Oct 2020}}} +\maketitle +\begin{abstract} +This report walks through a derivation of the variance-covariance matrix for the joint conditional model and state residuals for multivariate autoregressive Gaussian state-space (MARSS) models. The bulk of the report focuses on `smoothations' residuals \citep{Harveyetal1998}, which are the residuals conditioned on all the data $t=1$ to $T$. The final part of the report covers `innovations' residuals, which are residuals conditioned on the data $t=1$ to $t-1$. + +The MARSS model can be written: $\xx_t=\BB\xx_{t-1}+\uu+\ww_t$, $\yy_t=\ZZ\xx_t+\zz+\vv_t$, where $\ww_t$ and $\vv_t$ are independent multivariate Gaussian error-terms with variance-covariance matrices $\QQ_t$ and $\RR_t$ respectively. The joint conditional residuals are the $\ww_t$ and $\vv_t$ conditioned on the observed data, which may be incomplete (missing values). Harvey, Koopman and Penzer (1998) show a recursive algorithm for the smoothation residuals (residuals conditioned on all the data). I show an alternate algorithm to compute these residuals using the conditional variances of the states and the conditional covariance between unobserved data and states. This allows one to compute the variance of un-observed smoothation residuals (residuals associated with missing or left-out data), which is needed for leave-one-out cross-validation tests using smoothation residuals. I show how to modify the Harvey et al. algorithm in the case of missing values and how to modify it to return the non-normalized conditional residuals. +\end{abstract} +Keywords: Time-series analysis, Kalman filter, residuals, maximum-likelihood, vector autoregressive model, dynamic linear model, parameter estimation, state-space +\vfill +{\noindent \small citation: Holmes, E. E. 2014. Computation of standardized residuals for (MARSS) models. Technical Report. arXiv:1411.0045 } + \newpage + +\section{Overview of MARSS residuals} + +This report discusses the computation of the variance of the conditional model and state residuals for MARSS models of the form: +\begin{equation}\label{eq:residsMARSS} +\begin{gathered} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \vv_t, \text{ where } \VV_t \sim \MVN(0,\RR_t)\\ +\XX_0 \sim \MVN(\xixi,\LAM) \text{ or } \xx_0 = \pipi . +\end{gathered} +\end{equation} +The state and model residuals are respectively +\begin{equation}\label{eq:resids} +\begin{gathered} +\ww_t = \xx_t - \BB_t\xx_{t-1} - \uu_t\\ +\vv_t = \yy_t - \ZZ_t\xx_t - \aa_t . +\end{gathered} +\end{equation} +The model (and state) residuals are a random variables since $\yy_t$ and $\xx_t$ are drawn from the joint multivariate distribution of $\YY_t$ and $\XX_t$ defined by the MARSS equations (Equation \ref{eq:residsMARSS}). +The unconditional\footnote{meaning not conditioning on any particular set of observed data but rather taking the expectation across all possible values of $\yy_t$ and $\xx_t$.} variance of the model residuals is +\begin{equation}\label{eq:unconditiondistofVt} +\var_{XY}[\VV_t] = \var_{XY}[\YY_t - (\ZZ_t \XX_t + \aa_t)] = \RR_t\\ +\end{equation} +based on the distribution of $\VV_t$ in Equation \ref{eq:residsMARSS}. $\var_{XY}$ indicates that the integration is over the joint unconditional distribution of $\XX$ and $\YY$. + +Once we have data, $\RR_t$ is not the variance-covariance matrix of our model residuals because our residuals are now conditioned\footnote{`conditioned' means that the probability distribution of the residual has changed. The distribution is now the distribution given that $\YY=\yy$, say. Expectations and variances $\var[ ]$ are integrals over the value that a random variable might take multiplied by the probability of that value. When presenting an `expectation', the probability distribution is normally implicit but for derivations involving conditional expectations, it is important to be explicit about the distribution that is being integrated over.} on a set of observed data. There are two types of conditional model residuals used in MARSS analyses: innovations and smoothations. Innovations are the model residuals at time $t$ using the expected value of $\XX_t$ conditioned on the data from 1 to $t-1$. Smoothations are the model residuals using the expected value of $\XX_t$ conditioned on all the data, $t=1$ to $T$. Smoothations are used in computing standardized residuals for outlier and structural break detection \citep{HarveyKoopman1992, Harveyetal1998, deJongPenzer1998, CommandeurKoopman2007}. + +It should be noted that all the calculations discussed here are conditioned on the MARSS parameters: $\BB$, $\QQ$, $\UU$, $\RR$, $\ZZ$ and $\AA$. These are treated as known. This is different than standard discussions of residual distributions for linear models where the uncertainty in the model parameters enters into the calculations (as it enters into the calculation of the influence of $\yy$ on the expected (or fitted) value of $\yy$). In the calculations in this report, $\yy$ does not affect the estimates of the parameters (which are fixed, perhaps at estimated values) but does affect the expected value of $\YY_t$ by affecting the estimate of the expected value and variance of $\XX_t$. + +\section{Distribution of MARSS smoothation residuals}\label{sec:smoothations} + +This section discusses computation of the variance of the model and state residuals conditioned on all the data from $t=1$ to $T$. These MARSS residuals are often used for outlier detection and shock detection, and in this case you only need the distribution of the model residuals for the observed values. However if you wanted to do a leave-one-out cross-validation, you would need to know the distribution of the residuals for data points you left out (treated as unobserved). The equations in this report give you the former and the latter, while the algorithm by \citet{Harveyetal1998} gives only the former. These equations for residuals for `left-out` data are different that other (typical) discussions of state-space cross-validation \citep{deJong1988} in that they are conditioned on all the data (smoothations residuals) rather than conditioned on data up to $t-1$ (innovations residuals). + +\subsection{Notation and relations} + +Throughout, I follow the convention that capital letters are random variables and small letters are a realization from the random variable. This only applies to random variables; parameters are not random variables\footnote{in a frequentist framework}. Parameters are shown in Roman font while while random variables are bold slanted font. Parameters written as capital letters are matrices, while parameters written in small letters are strictly column matrices. + +In this report, the distribution over which the integration is done in an expectation or variance is given by the subscript; e.g., $\E_A[f(A)]$ indicates an unconditional expectation over the distribution of $A$ without conditioning on another random variable while $\E_{A|b}[f(A)|b]$ would indicate an expectation over the distribution of $A$ conditioned on $B=b$; presumably $A$ and $B$ are not independent otherwise $B=b$ would have no effect on $A$. $\E_{A|b}[f(A)|b]$ is a fixed value, not random. It is the expected value when $B=b$. In contrast, $\E_{A|B}[f(A)|B]$ denotes the random variable over all the possible $\E_{A|b}[f(A)|b]$ given all the possible $b$ values that $B$ might take. The variance of $\E_{A|B}[f(A)|B]$ is the variance of this random variable. The variance of $\E_{A|b}[f(A)|b]$ in contrast is 0 since it is a fixed value. We will often be working with the random variables, $\E_{A|B}[f(A)|B]$ or $\var_{A|B}[f(A)|B]$, inside an expectation or variance: such as $\var_B[\E_{A|B}[f(A)|B]]$. + +\subsubsection{Law of total variance} + +The ``law of total variance'' can be written +\begin{equation}\label{eq:lawoftotvar} +\var_A[A] = \var_B[\E_{A|B}[A|B]] + \E_B[\var_{A|B}[A|B]] . +\end{equation} +The subscripts on the inner expectations make it explicit that the expectations are being taken over the conditional distributions. $\var_{A|B}[A|B]$ and $\E_{A|B}[A|B]$ are random variables because the $B$ in the conditional is a random variable. We take the expectation or variance with $B$ fixed at one value, $b$, but $B$ can take other values of $b$ also. + +Going forward, I will write the law or total variance more succinctly as +\begin{equation} +\var[A] = \var_B[\E[A|B]] + \E_B[\var[A|B]] . +\end{equation} +I leave off the subscript on the inner conditional expectation or variance. Just remember that when you see a conditional in an expectation or variance, the integration is over over the conditional distribution of $A$ conditioned on $B=b$. Even when you see $A|B$, the conditioning is on $B=b$ and the $B$ indicates that this is a random variable because $B$ can take different $b$ values. When computing $\var_B[\E_{A|B}[A|B]]$, we will typically compute $\E_{A|b}[A|b]$ and then compute (or infer) the variance or expectation of that over all possible values of $b$. + +The law of total variance will appear in this report in the following form: +\begin{equation} +\var_{XY}[f(\YY,\XX)] = \var_{Y^{(1)}}[\E_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] + \E_{Y^{(1)}}[\var_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] , +\end{equation} +where $f(\YY_t,\XX_t)$ is some function of $\XX_t$ and $\YY_t$ and $\YY^{(1)}$ is the observed data from $t=1$ to $T$ ($\YY^{(2)}$ is the unobserved data). + + +\subsection{Model residuals conditioned on all the data} + +Define the smoothations $\hatvt$ as: +\begin{equation}\label{eq:vtT} +\hatvt = \yy_t - \ZZ_t\hatxtT - \aa_t, +\end{equation} +where $\hatxtT$ is $\E[\XX_t|\yy^{(1)}]$. The smoothation is different from $\vv_t$ because it uses $\hatxtT$ not $\xx_t$; $\xx_t$ is not known, and $\hatxtT$ is its estimate. $\hatxtT$ is output by the Kalman smoother. $\yy^{(1)}$ means all the observed data from $t=1$ to $T$. $\yy^{(1)}$ is a sample from the random variable $\YY^{(1)}$. The unobserved $\yy$ will be termed $\yy^{(2)}$ and is a sample from the random variable $\YY^{(2)}$. When $\YY$ appears without a superscript, it means both $\YY^{(1)}$ and $\YY^{(2)}$ together. Similarly $\yy$ means both $\yy^{(1)}$ and $\yy^{(2)}$ together---the observed data that we use to estimate $\hatxtT$ and the unobserved data that we do not use and may or may not know. $\hatvt$ exists for both $\yy^{(1)}$ and $\yy^{(2)}$, though we might not know $\yy^{(2)}$ and thus might not know its corresponding $\hatvt$. In some cases, however, we do know $\yy^{(2)}$; they are data that we left out of our model fitting, in say a k-fold or leave-one-out cross-validation. + +$\hatvt$ is a sample from the random variable $\hatVt$. We want to compute the mean and variance of this random variable over all possibles values that $\XX_t$ and $\YY_t$ might take. The mean of $\hatVt$ is 0 and we are concerned only with computing the variance: +\begin{equation}\label{eq:var.vtT} +\var[\hatVt] = \var_{XY}[\YY_t - \ZZ_t\E[\XX_t|\YY^{(1)}] - \aa_t] . +\end{equation} +Notice we have an unconditional variance over ${\XX,\YY}$ on the outside and a conditional expectation over a specific value of $\YY^{(1)}$ on the inside (in the $\E[\;]$). + +From the law of total variance (Equation \ref{eq:lawoftotvar}), we can write the variance of the model residuals as +\begin{equation}\label{eq:varvvtgeneral} +\var[\hatVt] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] . +\end{equation} + +\subsubsection{First term on right hand side of Equation \ref{eq:varvvtgeneral}} + +The random variable inside the $\var[\;]$ in the first term is +\begin{equation}\label{eq:first.term.rhs.varvvtgeneral} +\E[\hatVt|\YY^{(1)}]= \E[(\YY_t + \ZZ_t \E[\XX_t|\YY^{(1)}] + \aa_t)|\YY^{(1)}] . +\end{equation} +Let's consider this for a specific value $\YY^{(1)}=\yy^{(1)}$. +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[(\YY_t + \ZZ_t \E[\XX_t|\yy^{(1)}] + \aa_t)|\yy^{(1)}] = +\E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +$\E[\XX_t|\yy^{(1)}]$ is a fixed value, and the expected value of a fixed value is itself. So $\E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=\E[\XX_t|\yy^{(1)}]$. +Thus, +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\XX_t|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +We can move the conditional out and write +\begin{equation} +\E[\hatVt|\yy^{(1)}]= \E[(\YY_t + \ZZ_t \XX_t + \aa_t)|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]. +\end{equation} +The right side is $\E[\VV_t|\yy^{(1)}]$, no `hat' on the $\VV_t$, and this applies for all $\yy^{(1)}$. This means that the first term in Equation \ref{eq:varvvtgeneral} can be written with no hat on $\VV$: +\begin{equation}\label{eq:no.hat.on.V} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] . +\end{equation} +If $\YY_t$ were completely observed (no missing values), this would be zero since $\E[\VV_t|\yy]$ would be a fixed value in that case. But $\YY_t$ is not assumed to be fully observed; it may have $\YY^{(2)}_t$ which is unobserved, or more precisely, not included in the estimation of $VV_t$ for whatever reason (`unknown" because it was unobserved being one reason). The derivation of $\E[\YY_t|\yy^{(1)}]$ is given in \citet{Holmes2010}\footnote{$\E[\YY^{(2)}_t|\yy^{(1)}]$ is not $\ZZ_t \hatxtT + \aa_t$ in general since $\YY^{(2)}_t$ and $\YY^{(1)}_t$ may be correlated through $\RR$ in addition to being correlated through $\hatxtT$}. + +Using the law of total variance, we can re-write $\var[\VV_t]$ as: +\begin{equation}\label{eq:varianceVt} +\var[\VV_t] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:varianceVt}, we can solve for $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]]$: +\begin{equation}\label{eq:var.E.vtT} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \var[\VV_t] - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:unconditiondistofVt}, we know that $\var[\VV_t]=\RR_t$ (this is the unconditional variance). Thus, +\begin{equation}\label{eq:var.E.vtT.R} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \RR_t - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} + +The second term in Equation \ref{eq:var.E.vtT.R} to the right of the equal sign and inside the expectation is $\var[\VV_t|\YY^{(1)}]$. This is the variance of $\VV_t$ with $\YY^{(1)}$ held at a specific fixed $\yy^{(1)}$. The variability in $\var[\VV_t|\yy^{(1)}]$ (notice $\yy^{(1)}$ not $\YY^{(1)}$ now) comes from $\XX_t$ and $\YY^{(2)}$ which are random variables. Let's compute this variance for a specific $\yy^{(1)}$ value. +\begin{equation}\label{eq:varvtcondy} +\var[\VV_t|\yy^{(1)}] = \var[ \YY_t - \ZZ_t\XX_t-\aa_t | \yy^{(1)} ]. +\end{equation} +Notice that there is no $\E$ (expectation) on the $\XX_t$; this is $\VV_t$ not $\hatVt$. $\aa_t$ is a fixed value and can be dropped. + +Equation \ref{eq:varvtcondy} can be written as\footnote{$\var(A+B)=\var(A)+\var(B)+\cov(A,B)+\cov(B,A)$}: +\begin{equation}\label{eq:var.Vt.yy} +\begin{split} +\var[\VV_t|\yy^{(1)}] &= \var[ \YY_t - \ZZ_t\XX_t | \yy^{(1)} ]\\ +&=\var[ - \ZZ_t\XX_t | \yy^{(1)} ] + \var[ \YY_t|\yy^{(1)}] + \cov[ \YY_t, - \ZZ_t\XX_t | \yy^{(1)} ] + \cov[ - \ZZ_t\XX_t, \YY_t | \yy^{(1)} ]\\ +&=\ZZ_t \hatVtT \ZZ_t^\top + \hatUtT - \hatStT\ZZ_t^\top - \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +$\hatVtT = \var[ \XX_t | \yy^{(1)} ]$ and is output by the Kalman smoother. $\hatUtT=\var[\YY_t|\yy^{(1)}]$ and $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$. The equations for these are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package\footnote{$\hatUtT$ is \texttt{OtT - tcrossprod(ytT)} in the \texttt{MARSShatyt()} output.}. If there were no missing data, i.e., if $\yy^{(1)}=\yy$, then $\hatUtT$ and $\hatStT$ would be zero because $\YY_t$ would be fixed at $\yy_t$. This would reduce Equation \ref{eq:var.Vt.yy} to $\ZZ_t \hatVtT \ZZ_t^\top$. But we are concerned with the case where there are missing values. Those missing values need not be for all $t$. That is, there may be some observed $y$ at time t and some missing $y$. $\yy_t$ is multivariate. + +From Equation \ref{eq:var.Vt.yy}, we know $\var[\VV_t|\yy^{(1)}]$ for a specific $\yy^{(1)}$. We want $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$ which is its expected value over all possible values of $\yy^{(1)}$. $\VV_t$ is a multivariate normal random variable with two random variables $\YY^{(1)}$ and $\YY^{(2)}$. The conditional variance of a multivariate Normal does not depend on the value that you are conditioning on. Let the $\AA$ be a N-dimensional multivariate Normal random variable partitioned into $\AA_1$ and $\AA_2$ with variance-covariance matrix $\Sigma = \begin{bmatrix} +\Sigma_1 & \Sigma_{12} \\ +\Sigma_21 & \Sigma_{2} +\end{bmatrix}$. The variance-covariance matrix of $\AA$ conditioned on $\AA_1=\aa$ is $\Sigma = \begin{bmatrix} +0 & 0 \\ +0 & \Sigma_2 - \Sigma_{12}\Sigma_{1}\Sigma_{21} +\end{bmatrix}$. Notice that $\aa$ does not appear in the conditional variance matrix. This means that $\var[\VV_t|\yy^{(1)}]$ does not depend on $\yy^{(1)}$. Its variance only depends on the MARSS model parameters\footnote{This also implies that $\hatVtT$, $\hatUtT$ and $\hatStT$ do not depend on $\yy^{(1)}$, which is rather counter-intuitive since $\yy^{(1)}$ is part of the algorithm (Kalman filter and smoother) used to compute these values. The value of $\yy^{(1)}$ affects the expected values of $\XX_t$ but only its presence\ (versus absence) affects $\XX_t$'s conditional variance.}. + +Because $\var[\VV_t|\yy^{(1)}]$ only depends on the MARSS parameters values, $\QQ$, $\BB$, $\RR$, etc., the second term in Equation \ref{eq:var.E.vtT}, $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$, is equal to $\var[\VV_t|\yy^{(1)}]$ (Equation \ref{eq:var.Vt.yy}). Putting this into Equation \ref{eq:var.E.vtT.R}, we have +\begin{equation}\label{eq:conditionalvtfinala} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \RR_t - \var[\VV_t|\yy^{(1)}] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} +Since $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]]$ (Equation \ref{eq:no.hat.on.V}), this means that the first term in Equation \ref{eq:varvvtgeneral} is +\begin{equation}\label{eq:conditionalvtfinal} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} + +\subsubsection{Second term on right hand side of Equation \ref{eq:varvvtgeneral}} + +Consider the second term in Equation \ref{eq:varvvtgeneral}. This term is +\begin{equation}\label{eq:second.term.rhs.9} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \E_{Y^{(1)}}[\var[(\YY_t-\ZZ_t\E[\XX_t|\YY^{(1)}]-\aa_t)|\YY^{(1)}]] . +\end{equation} +The middle term is: +\begin{equation} +\E_{Y^{(1)}}[\var[\E[\XX_t|\YY^{(1)}]|\YY^{(1)}]]. +\end{equation} +Let's solve the inner part for a specific $\YY^{(1)}=\yy^{(1)}$. $\E[\XX_t|\yy^{(1)}]$ is a fixed value. Thus $\var[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=0$ since the variance of a fixed value is 0. This is true for all $\yy^{(1)}$ so the middle term reduces to 0. $\aa_t$ is also fixed and its variance is also 0. The covariance between a random variable and a fixed value is 0\footnote{$\var[A+B] = \var[A]+\var[B]+\cov[A,B]$}. Thus for a specific $\YY^{(1)}=\yy^{(1)}$, the inside of the right hand side expectation reduces to $\var[\YY_t|\yy^{(1)}]$ which is $\hatUtT$. As noted in the previous section, $\hatUtT$ is only a function of the MARSS parameters; it is not a function of $\yy^{(1)}$ and $\var[\YY_t|\yy^{(1)}]=\hatUtT$ for all $\yy^{(1)}$. Thus the second term in Equation \ref{eq:varvvtgeneral} is simply $\hatUtT$: +\begin{equation}\label{eq:second.term.rhs.9final} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \var[\hatVt|\yy^{(1)}] = \hatUtT . +\end{equation} + +\subsubsection{Putting together the first and second terms} + +We can now put the first and second terms in Equation \ref{eq:varvvtgeneral} together (Equations \ref{eq:conditionalvtfinal} and \ref{eq:second.term.rhs.9final}) and write out the variance of the model residuals: +\begin{equation}\label{eq:first.and.secons.vvtgeneral} +\begin{split} +\var[\hatVt] &= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top + \hatUtT\\ +&= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t - \ZZ_t \hatVtT \ZZ_t^\top$ if $\yy_t$ has no missing values since $\hatStT = 0$ in this case. If $\yy_t$ is all missing values, $\hatStT = \ZZ_t \hatVtT$ because +\begin{equation}\label{eq:cov.Yt.Xt.no.missing.vals} +\cov[\YY_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t + \aa_t + \VV_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \cov[\XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \hatVtT . +\end{equation} +The reduction in Equation \ref{eq:cov.Yt.Xt.no.missing.vals} occurs because $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent in the form of MARSS model used in this report (Equation \ref{eq:residsMARSS})\footnote{This is not the case for the \citet{Harveyetal1998} form of the MARSS model where $\VV_t$ and $\WW_t$ are allowed to be correlated.}. Thus when $\yy_t$ is all missing values, Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t + \ZZ_t \hatVtT \ZZ_t^\top$ . The behavior if $\yy_t$ has some missing and some not missing values depends on whether $\RR_t$ is a diagonal matrix or not, i.e., if the $\yy_t^{(1)}$ and $\yy_t^{(2)}$ are correlated. + +\subsection{State residuals conditioned on the data} + +The state residuals are $\xx_t - (\BB_t \xx_{t-1} + \uu_t)=\ww_t$. The unconditional expected value of the state residuals is $\E[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \E[\WW_t] = 0$ and the unconditional variance of the state residuals is +\begin{equation} +\var[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \var[\WW_t] = \QQ_t +\end{equation} +based on the definition of $\WW_t$ in Equation \ref{eq:residsMARSS}. +The conditional state residuals (conditioned on the data from $t=1$ to $t=T$) are defined as +\begin{equation} +\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t. +\end{equation} +where $\hatxtT = E[\XX_t|\yy^{(1)}]$ and $\hatxtmT = E[\XX_{t-1}|\yy^{(1)}]$. $\hatwt$ is a sample from the random variable $\hatWt$; random over different possible data sets. The expected value of $\hatWt$ is 0, and we are concerned with computing its variance. + +We can write the variance of $\WW_t$ (no hat) using the law of total variance. +\begin{equation}\label{eq:Wlawoftotvar} +\var[\WW_t] = \var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Notice that +\begin{equation} +\E[\WW_t|\yy^{(1)}] = \E[(\XX_t - \BB_t \XX_{t-1} - \uu_t)|\yy^{(1)}] = \hatxtT - \BB_t \hatxtmT - \uu_t = \E[\hatWt|\yy^{(1)}] = \hatwt . +\end{equation} +This is true for all $\yy^{(1)}$, thus $\E[\WW_t|\YY^{(1)}]$ is $\hatWt$, and $\var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] = \var[\hatWt]$. Equation \ref{eq:Wlawoftotvar} can thus be written +\begin{equation} +\var[\WW_t] = \var[\hatWt] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Solve for $\var[\hatWt]$: +\begin{equation}\label{eq:varwwt} +\var[\hatWt] = \var[\WW_t] - \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]. +\end{equation} + +The variance in the expectation on the far right for a specific $\YY^{(1)}=\yy^{(1)}$ is +\begin{equation} +\var[\WW_t|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}-\uu_t) | \yy^{(1)} ] . +\end{equation} +$\uu_t$ is not a random variable and can be dropped. Thus\footnote{$\var[A-B]=\var[A]+\var[B]+\cov[A,-B]+\cov[-B,A]$. Be careful about the signs in this case as they are a little non-intuitive.}, +\begin{equation}\label{eq:var.W.cond.y1} +\begin{split} +\var[\WW_t&|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}) | \yy^{(1)} ] \\ +& = \var[ \XX_t | \yy^{(1)} ] + \var[\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[\XX_t, -\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[ -\BB_t\XX_{t-1}, \XX_t | \yy^{(1)} ]\\ +& = \hatVtT + \BB_t \hatVtmT \BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{split} +\end{equation} +Again this is conditional multivariate normal variance, and its value does not depend on the value, $\yy^{(1)}$ that we are conditioning on. It depends only on the parameters values, $\QQ$, $\BB$, $\RR$, etc., and is the same for all values of $\yy^{(1)}$. So $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \var[\WW_t|\yy^{(1)}]$, using any value of $\yy^{(1)}$. Thus +\begin{equation}\label{eq:E.var.Wt.yt} +\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \hatVtT + \BB_t\hatVtmT\BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{equation} + +Putting $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]$ from Equation \ref{eq:E.var.Wt.yt} and $\var[\WW_t]=\QQ_t$ into Equation \ref{eq:varwwt}, the variance of the conditional state residuals is +\begin{equation} +\var[\hatWt] = \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT . +\end{equation} + +\subsection{Covariance of the conditional model and state residuals} + +The unconditional model and state residuals, $\VV_t$ and $\WW_t$, are independent by definition\footnote{This independence is specific to the way the MARSS model for this report (Equation \ref{eq:residsMARSS}). It is possible for the model and state residuals to covary. In the MARSS model written in \citet{Harveyetal1998} form, they do covary.} (in Equation \ref{eq:residsMARSS}), i.e., $\cov[\VV_t,\WW_t]=0$. However the conditional model and state residuals, $\cov[\hatVt,\hatWt]$, are not independent since both depend on $\yy^{(1)}$. +Using the law of total covariance, we can write +\begin{equation}\label{eq:covhatVtWt1} +\cov[\hatVt,\hatWt] = +\cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]] + \E_{Y^{(1)}}[\cov[\hatVt, \hatWt|\YY^{(1)}]] . +\end{equation} + +For a specific value of $\YY^{(1)}=\yy^{(1)}$, the covariance in the second term on the right is $\cov[\hatVt, \hatWt|\yy^{(1)}]$. Conditioned on a specific value of $\YY^{(1)}$, $\hatWt$ is a fixed value, $\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t$, and conditioned on $\yy^{(1)}$, $\hatxtT$ and $\hatxtmT$ are fixed values. $\uu_t$ is also fixed; it is a parameter. $\hatVt$ is not a fixed value because it has $\YY_t^{(2)}$ and that is a random variable. Thus $\cov[\hatVt, \hatWt|\yy^{(1)}]$ is the covariance between a random variable and a fixed variable and thus the covariance is 0. This is true for all $\yy^{(1)}$. +Thus the second right-side term in Equation \ref{eq:covhatVtWt1} is zero, and the equation reduces to +\begin{equation}\label{eq:covhatVtWt3} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]]. +\end{equation} +Notice that $\E[\hatWt|\yy^{(1)}]=\E[\WW_t|\yy^{(1)}]$ and $\E[\hatVt|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]$ since +\begin{equation} +\E[\WW_t|\yy^{(1)}]= \E[\XX_t|\yy^{(1)}]-\BB_t\E[\XX_{t-1}|\yy^{(1)}] - \uu_t = \hatxtT-\BB_t\hatxtmT - \uu_t = \hatwt = \E[\hatWt|\yy^{(1)}] +\end{equation} +and +\begin{equation} +\E[\VV_t|\yy^{(1)}]= \E[\YY_t|\yy^{(1)}]-\ZZ_t\E[\XX_{t}|\yy^{(1)}] - \aa_t = \E[\YY_t|\yy^{(1)}]-\ZZ_t \hatxtT - \aa_t = \E[\hatVt|\yy^{(1)}] . +\end{equation} +Thus the right side of Equation \ref{eq:covhatVtWt3} can be written in terms of $\VV_t$ and $\WW_t$ instead of $\hatVt$ and $\hatWt$: +\begin{equation}\label{eq:covhatVtWt2} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]]. +\end{equation} + +Using the law of total covariance, we can write: +\begin{equation}\label{eq:covVtWt} +\cov[\VV_t, \WW_t] = \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] + \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] . +\end{equation} +The unconditional covariance of $\VV_t$ and $\WW_t$ is 0. Thus the left side of Equation \ref{eq:covVtWt} is 0 and we can rearrange the equation as +\begin{equation}\label{eq:covVtWt2} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] = - \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] . +\end{equation} +Combining Equation \ref{eq:covhatVtWt2} and \ref{eq:covVtWt2}, we get +\begin{equation}\label{eq:conditionalcovvtwt} +\cov[\hatVt,\hatWt] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ] , +\end{equation} +and our problem reduces to solving for the conditional covariance of the model and state residuals (right side of Equation \ref{eq:conditionalcovvtwt}). + +For a specific $\YY^{(1)}=\yy^{(1)}$, the conditional covariance $\cov[\VV_t, \WW_t|\yy^{(1)}]$ can be written out as +\begin{equation} +\cov[\VV_t, \WW_t|\yy^{(1)}] = \cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_t-\BB_t\XX_{t-1}-\uu_t|\yy^{(1)}] . +\end{equation} +$\aa_t$ and $\uu_t$ are fixed values and can be dropped. Thus\footnote{$\cov[\BB \mathbf{A},\CC \mathbf{D}]=\BB\cov[\mathbf{A},\mathbf{D}]\CC^\top$.} +\begin{equation} +\begin{split} +\cov&[\VV_t, \WW_t|\yy^{(1)}] =\cov[\YY_t-\ZZ_t\XX_t, \XX_t-\BB_t\XX_{t-1}|\yy^{(1)}] \\ +& =\cov[\YY_t,\XX_t|\yy^{(1)}] + \cov[\YY_t,-\BB_t\XX_{t-1}|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,\XX_t|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,-\BB_t\XX_{t-1}|\yy^{(1)}]\\ +& = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top , +\end{split} +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$ and $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$; the equations for $\hatStT$ and $\hatSttmT$ are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package. + +Both $\VV_t$ and $\WW_t$ are multivariate normal random variables that depend on $\YY^{(1)}$ and $\YY^{(2)}$ and the conditional covariance is not a function of the variable that we condition on (in this case $\yy^{(1)}$). The conditional covariance is only a function of the MARSS parameters\footnote{By extension, this is also the case for $\hatVtT$, $\hatVttmT$, $\hatStT$ and $\hatSttmT$ which may seem counter-intuitive, but you can show it is true by working through the Kalman filter and smoother equations starting at t=1. Or run a Kalman filter/smoother algorithm with different data and the same parameters and you will see that the variances do not change with different data.}. Thus +\begin{equation} +\E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ]= \cov[\VV_t, \WW_t|\yy^{(1)}] = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} +$\cov[\hatVt,\hatWt]$ is the negative of this (Equation \ref{eq:conditionalcovvtwt}), thus +\begin{equation} +\cov[\hatVt,\hatWt] = - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t \hatVtT - \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} + +The Harvey et al. algorithm (next section) gives the joint distribution of the model residuals at time $t$ and state residuals at time $t+1$. Using the law of total covariance as above, the covariance in this case is +\begin{equation} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] +\end{equation} +and +\begin{equation} +\begin{split} +\cov[\VV_t, \WW_{t+1}|\yy^{(1)}] & =\cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_{t+1}-\BB_{t+1}\XX_t-\uu_{t+1}|\yy^{(1)}] \\ +& =\cov[\YY_t-\ZZ_t\XX_t,\, \XX_{t+1}-\BB_{t+1}\XX_t|\yy^{(1)}] \\ +& = \hatSttpT - \hatStT\BB_{t+1}^\top - \ZZ_t\hatVttpT + \ZZ_t \hatVtT \BB_{t+1}^\top . +\end{split} +\end{equation} +Thus, +\begin{equation} +\begin{split} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] & = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] \\ +& = - \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top. +\end{split} +\end{equation} + + +\subsection{Joint distribution of the conditional residuals} + +We now can write the variance of the joint distribution of the conditional residuals. Define +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwt\end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtT - \BB_t\hatxtmT - \uu_t \end{bmatrix}. +\end{equation} +$\widehat{\varepsilon}_t$ is a sample drawn from the distribution of the random variable $\widehat{\mathcal{E}}_t$. The expected value of $\widehat{\mathcal{E}}_t$ over all possible $\yy$ is 0 and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} +\widehat{\Sigma}_t = \var[\widehat{\mathcal{E}}_t] = \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWt] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWt])^\top& + \var[\hatWt] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid1general} + \begin{bmatrix}[c|c] + \RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top+\ZZ_t(\hatStT)^\top& + - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top\\ + \rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ + (- \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top)^\top& + \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT \end{bmatrix}, +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$, $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$, $\hatVtT=\var[\XX_t|\yy^{(1)}]$, $\hatVttmT=\cov[\XX_t,\XX_{t-1}|\yy^{(1)}]$, and $\hatVtmtT=\cov[\XX_{t-1},\XX_t|\yy^{(1)}]$. This gives the variance of both `observed' model residuals (the ones associated with $\yy^{(1)}$) and the unobserved model residuals (the ones associated with $\yy^{(2)}$). +When there are no missing values in $\yy_t$, the $\hatStT$ and $\hatSttmT$ terms equal 0 and drop out. + +If the residuals are defined as in \citet{Harveyetal1998} with $\hatvt$ on top and $\hatwtp$ on the bottom instead of $\hatwt$, then +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtpT - \BB_{t+1}\hatxtT - \uu_{t+1} \end{bmatrix} +\end{equation} +and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} + \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWtp] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWtp])^\top& + \var[\hatWtp] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid2} +\begin{bmatrix}[c|c] +\RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top& +- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top \\ +\rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ +(- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top)^\top& +\QQ_{t+1} - \hatVtpT - \BB_{t+1}\hatVtT\BB_{t+1}^\top + \hatVtptT \BB_{t+1}^\top + \BB_{t+1}\hatVttpT \end{bmatrix} . +\end{equation} + + + +\section{Harvey et al. 1998 algorithm for the conditional residuals} +\citet[pgs 112-113]{Harveyetal1998} give a recursive algorithm for computing the variance of the conditional residuals when the time-varying MARSS equation is written as: +\begin{equation}\label{eq:residsMARSSHarvey} +\begin{gathered} +\xx_{t+1} = \BB_{t+1}\xx_t + \uu_{t+1} + \HH_{t+1}\epsilon_{t},\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \GG_t\epsilon_t,\\ +\mbox{ where } \epsilon_t \sim \MVN(0,\II_{m+n \times m+n}) \\ +\HH_t\HH_t^\top=\QQ_t, \GG_t\GG_t^\top=\RR_t, \text{ and } \HH_t\GG_t^\top = \cov[\WW_t, \VV_t] +\end{gathered} +\end{equation} +The $\HH_t$ and $\GG_t$ matrices specify the variance and covariance of $\WW_t$ and $\VV_t$. $\HH_t$ has $m$ rows and $m+n$ columns and $\GG_t$ has $n$ rows and $m+n$ columns. In the MARSS equation for this report (Equation \ref{eq:residsMARSS}), $\WW_t$ and $\VV_t$ are independent. To achieve this in the Harvey et al. form (Equation \ref{eq:residsMARSSHarvey}), the first $n$ columns of $\HH_t$ are all 0 and the last $m$ columns of $\GG_t$ are all zero. + +The algorithm in \citet{Harveyetal1998} gives the variance of the `normalized' residuals, the $\epsilon_t$. I have modified their algorithm so it returns the `non-normalized' residuals: +$$\varepsilon_t=\begin{bmatrix}\GG_t\epsilon_t\\ \HH_{t+1}\epsilon_t\end{bmatrix}=\begin{bmatrix}\vv_t\\ \ww_{t+1} \end{bmatrix}.$$ + +The Harvey et al. algorithm is a backwards recursion using the following output from the Kalman filter: the one-step ahead prediction covariance $\FF_t$, the Kalman gain $\KK_t$, $\hatxttm=\E[\XX_t|\yy^{(1),1:{t-1}}]$ and $\hatVttm=\var[\XX_t|\yy^{(1),1:{t-1}}]$. In the \{MARSS\} package, these are output from \texttt{MARSSkfss()} in \texttt{Sigma}, \texttt{Kt}, \texttt{xtt1} and \texttt{Vtt1}. + +\subsection{Algorithm for the non-normalized residuals} + +Start from $t=T$ and work backwards to $t=1$. At time $T$, $r_T=0_{1 \times m}$ and $N_T=0_{m \times m}$. $\BB_{t+1}$ and $\QQ_{t+1}$ can be set to NA or 0. They will not appear in the algorithm at time $T$ since $r_T=0$ and $N_T=0$. Note that the $\ww$ residual and its associated variance and covariance with $\vv$ at time $T$ is NA since this residual would be for $\xx_T$ to $\xx_{T+1}$. + +% algorithm with \GG_t and \HH_t +% \begin{equation}\label{eq:Harveyalgo} +% \begin{gathered} +% \FF_t = \ZZ_t\hatVt\ZZ_t^\top+\RR_t\\ +% G_t= \GG_t\QQ_t\GG_t^\top, \mbox{ }H_t = \HH_t\RR_t\HH_t^\top, \mbox{ } K_t = \BB_t\KK^{*}_t\\ +% L_t = \BB_t - K_t\ZZ_t, \mbox{ } J_t= H_t - K_t G_t, \mbox{ } u_t = \FF_t^{-1} - K_t^\top r_t\\ +% r_{t-1} = \ZZ_t^\top u_t + \BB_t^\top r_t, \mbox{ } N_{t-1} = K_t^\top N_t K_t + L_t^\top N_t L_t +% \end{gathered} +% \end{equation} + +\begin{equation}\label{eq:Harveyalgo} +\begin{gathered} +\QQ^\prime_{t+1}=\begin{bmatrix}0_{m \times n}&\QQ_{t+1}\end{bmatrix}, \mbox{ } \RR^\prime_t=\begin{bmatrix}\RR_t^* & 0_{n \times m}\end{bmatrix}\\ +\FF_t = \ZZ_t^*\hatVttm{\ZZ_t^*}^\top+\RR_t^* , \,\, n \times n \\ +K_t = \BB_{t+1}\KK_t = \BB_{t+1} \hatVttm{\ZZ_t^*}^\top \FF_t^{-1} , \,\, m \times n \\ +L_t = \BB_{t+1} - K_t\ZZ_t^* , \,\, m \times m \\ +J_t= \QQ^\prime_{t+1} - K_t \RR^\prime_t , \,\, m \times (n+m) \\ +v_t = \yy_t^* - \ZZ_t\hatxttm - \aa_t , \,\, n \times 1 \\ +u_t = \FF_t^{-1} v_t - K_t^\top r_t , \,\, n \times 1 \\ +r_{t-1} = {\ZZ_t^*}^\top u_t + \BB_{t+1}^\top r_t , \,\, m \times 1 \\ +N_{t-1} = {\ZZ_t^*}^\top \FF_t^{-1} \ZZ_t^* + L_t^\top N_t L_t , \,\, m \times m . +\end{gathered} +\end{equation} +$\yy_t^*$ is the observed data at time $t$ with the $i$-th rows set to 0 if the $i$-th $y$ is missing. +Bolded terms are the same as in Equation \ref{eq:residsMARSSHarvey} (and are output by \texttt{MARSSkfss()}). Unbolded terms are terms used in \citet{Harveyetal1998}. The * on $\ZZ_t$ and $\RR_t$, indicates that they are the missing value modified versions discussed in \citet[section 6.4]{ShumwayStoffer2006} and \citet{Holmes2010}: to construct $\ZZ_t^*$ and $\RR_t^*$, the rows of $\ZZ_t$ corresponding to missing rows of $\yy_t$ are set to zero and the $(i,j)$ and $(j,i)$ terms of $\RR_t$ corresponding the missing rows of $\yy_t$ are set to zero. For the latter, this means if the $i$-th row of $\yy_t$ is missing, then then the $i$-th row and column (including the value on the diagonal) in $\RR_t$ are set to 0. Notice that $\FF_t$ will have 0's on the diagonal if there are missing values. A modified inverse of $\FF_t$ is used: any 0's on the diagonal of $\FF_t$ are replaced with 1, the inverse is taken, and 1s on diagonals is replaced back with 0s. + +The residuals \citep[eqn 24]{Harveyetal1998} are +\begin{equation}\label{eq:Harveyresiduals} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} =({\RR^\prime_t})^\top u_t + ({\QQ^\prime_{t+1}})^\top r_t +\end{equation} +The expected value of $\widehat{\mathcal{E}}_t$ is 0 and its variance is +\begin{equation}\label{eq:Harveyvariance} +\widehat{\Sigma]}_t = \var[\widehat{\mathcal{E}}_t] ={\RR^\prime_t}^\top \FF_t^{-1} \RR^\prime_t + J_t^\top N_t J_t . +\end{equation} +These $\widehat{\varepsilon}_t$ and $\widehat{\Sigma]}_t$ are for both the non-missing and missing $\yy_t$. This is a modification to the \citet{Harveyetal1998} algorithm which does not give the variance for missing $\yy$. + +\subsection{Difference in notation} + +In Equation 20 in \citet{Harveyetal1998}, their $T_t$ is my $\BB_{t+1}$ and their $H_t H_t^\top$ is my $\QQ_{t+1}$. Notice the difference in the time indexing. My time indexing on $\BB$ and $\QQ$ matches the left $\xx$ while in theirs, $T$ and $H$ indexing matches the right $\xx$. Thus in my implementation of their algorithm \citep[eqns. 21-24]{Harveyetal1998}, $\BB_{t+1}$ appears in place of $T_t$ and $\QQ_{t+1}$ appears in place of $H_t$. See comments below on normalization and the difference between $\QQ$ and $H$. + +\citet[eqns. 19, 20]{Harveyetal1998} use $G_t$ to refer to the $\chol(\RR_t)^\top$ (non-zero part of the $n \times n+m$ matrix) and $H_t$ to refer to $\chol(\QQ_t)^\top$. I have replaced these with $\RR_t^\prime$ and $\QQ_t^\prime$ (Equation \ref{eq:Harveyalgo}) which causes my variant of their algorithm (Equation \ref{eq:Harveyalgo}) to give the `non-normalized' variance of the residuals. The residuals function in the \{MARSS\} package has an option to give either normalized or non-normalized residuals. + +$\KK_t$ is the Kalman gain output by the \{MARSS\} package \verb@MARSSkf()@ function. The Kalman gain as used in the \citet{Harveyetal1998} algorithm is $K_t=\BB_{t+1}\KK_t$. Notice that Equation 21 in \citet{Harveyetal1998} has $H_t G_t^\top$ in the equation for $K_t$. This is the covariance of the state and observation errors, which is allowed to be non-zero given the way Harvey et al. write the errors in their Equations 19 and 20. The way the \{MARSS\} package model is written, the state and observation errors are independent of each other. Thus $H_t G_t^\top = 0$ and this term drops out of the $K_t$ equation in Equation \ref{eq:Harveyalgo}. + +\subsection{Computing the normalized residuals} + +To compute the normalized residuals and residuals variance, a block diagonal matrix with the inverse of the $\RR$ and $\QQ$ matrices is used. The normalized residuals are: +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\varepsilon}_t +\end{equation} +The variance of the normalized residuals is +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\Sigma]}_t \begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} +\end{equation} + +\subsection{Computing the Cholesky standardized residuals} + +The Cholesky standardized residuals are computed by multiplying $\widehat{\varepsilon}_t$ by $(\widehat{\Sigma}_t)^{-1/2}$ (the inverse of the Cholesky decomposition of the variance-covariance matrix for $\widehat{\varepsilon}_t$): +\begin{equation}\label{eq:std.resid} +\widehat{\varepsilon}_{t, std} = (\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t . +\end{equation} +These residuals are uncorrelated (across the residuals at time $t$ in $\widehat{\varepsilon}_t$). See \citet{HarveyKoopman1992} and \citet[section V]{Harveyetal1998} for a discussion on how to use these residuals for outlier detection and structural break detection. + +It is also common to use the marginal standardized residuals, which would be $\widehat{\varepsilon}_t$ multiplied by the inverse of the square-root of $\dg(\widehat{\Sigma}_t)$, where $\dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. +\begin{equation} +\widehat{\varepsilon}_{t, mar} = \dg(\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t +\end{equation} +Marginal standardized residuals may be correlated at time $t$ (unlike the Cholesky standardized residuals) but are a bit easier to interpret when there is correlation across the model residuals. + +\section{Distribution of the MARSS innovation residuals} + +One-step-ahead predictions (innovations) are often shown for MARSS models and these are used for likelihood calculations. Innovations are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t-1$. This section gives the residual variance for the innovations and the analogous values for the states. Innovations residuals are the more common residuals discussed for state-space models; these are also known as the `one-step-ahead` prediction residuals. + +\subsection{One-step-ahead model residuals} + +Define the innovations $\checkvt$ as: +\begin{equation}\label{eq:vtt1} +\checkvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxttm - \aa_t, +\end{equation} +where $\hatxttm$ is $\E[\XX_t|\yy^{(1),t-1}]$ (expected value of $\XX_t$ conditioned on the data up to time $t-1$). The random variable, innovations over all possible $\yy_t$, is $\checkVt$. Its mean is 0 and we want to find its variance. + +This is conceptually different than the observed `innovations'. First, this is the random variable `innovation'. $\yy^{(1)}_t$ here is not the actual data that you observe (the one data set that you have). It's the data that you could observe. $\yy_t$ is a sample from the random variable $\YY_t$ and $\checkvt$ is a sample from the innovations you could observe. Second, $\checkvt$ includes both $\yy_t^{(1)}$ and $\yy_t^{(2)}$ (observed and unobserved $\yy$). Normally, the innovations for missing data would appear as 0s, e.g., from a call to \verb@MARSSfss()@. For missing data, $\checkvt$ is not necessarily 0. For example if $\yy$ is multivariate and correlated with each other through $\RR$ or a shared $\xx$ dependency. + +The derivation of the variance of $\checkVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t-1$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:innov.model} +\var[\checkVt] = \RR_t - \ZZ_t \hatVttm \ZZ_t^\top + \hatSttm\ZZ_t^\top + \ZZ_t(\hatSttm)^\top +\end{equation} +where the $\hatVttm$ and $\hatSttm$ are now conditioned on only the data from 1 to $t-1$. +$\hatSttm = \cov[\YY_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t-1}]$. +$\yy_t$ is not in the conditional since it only includes data up to $t-1$. Without $\yy_t$ in the conditional, $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent\footnote{This is only true given the way the MARSS equation is written in this report where $V_t$ and $W_t$ are independent. This is not the case for the more general Harvey et al. MARSS model which allows covariance between $V_t$ and $W_t$.} and $\cov[\ZZ_t \XX_t + \aa_t + \VV_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t,\XX_t|\yy^{(1), t-1}] = \ZZ_t \hatVttm$. Therefore, $\ZZ_t(\hatSttm)^\top = \ZZ_t \hatVttm \ZZ_t^\top = \hatSttm(\ZZ_t)^\top$. Thus Equation \ref{eq:innov.model} reduces to +\begin{equation}\label{eq:innov.model2} +\var[\checkVt] = \RR_t + \ZZ_t \hatVttm \ZZ_t^\top. +\end{equation} + +Note $\var[\checkVt]$ is a standard output from Kalman filter functions and is used to compute the likelihood of the data (conditioned on a set of parameters). In the Kalman filter in the \{MARSS\} package, it is output as \texttt{Sigma} from \texttt{MARSSkfss()}. + + +\subsection{One-step ahead state residuals} + +Define the state residuals conditioned on the data from 1 to $t-1$ as $\checkwt$. +\begin{equation}\label{eq:wtt1} +\checkwt = \hatxtt - \BB_t\hatxtmt1 - \uu_t, +\end{equation} +where $\hatxtmt1$ is $\E[\XX_{t-1}|\yy^{(1),t-1}]$ (expected value of $\XX_{t-1}$ conditioned on the data up to time $t-1$) and $\hatxtt$ is $\E[\XX_{t}|\yy^{(1),t}]$ (expected value of $\XX_{t}$ conditioned on the data up to time $t$). +From the Kalman filter equations: +\begin{equation}\label{eq:wtt1.2} +\hatxtt = \BB_t\hatxtmt1 + \uu_t + \KK_t \checkvt +\end{equation} +Thus, $\checkwt$ is a transformed $\checkvt$: +\begin{equation}\label{eq:wtt1.3} +\checkwt = \KK_t \checkvt, +\end{equation} +where $\KK_t$ is the Kalman gain. $\KK_t = \hatVttm \ZZ_t^\top[\ZZ_t \hatVttm \ZZ_t^\top + \RR_t]^{-1}$ and $\ZZ_t$ is the missing values modified $\ZZ_t$ where if the $i$-th $\yy_t$ is missing, the $i$-th row of $\ZZ_t$ is set to all 0s (Shumway and Stoffer 2006, equation 6.78). +Thus the variance of $\checkWt$ is +\begin{equation}\label{eq:var.Wt} +\var[\checkWt] = \KK_t \var[\checkVt] \KK_t^\top +\end{equation} + +\subsection{Joint distribution of the conditional one-step-ahead residuals} + +\subsubsection{with the state residuals defined from $t-1$ to $t$} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t = \begin{bmatrix}\checkvt\\ \checkwt \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWt$ is +\begin{equation}\label{eq:covhatVtWtp.onestep} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t}\checkVt] = \var[\checkVt]\KK_{t}^\top +\end{equation} + + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep} +\overline{\Sigma}_t = \var[\overline{\varepsilon}_t] = \begin{bmatrix}[c|c] + \var[\checkVt]& \var[\checkVt]\KK_{t}^\top\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +\KK_{t}\var[\checkVt]& \KK_{t}\var[\checkVt]\KK_{t}^\top \end{bmatrix}, +\end{equation} + +Since $\checkwt=\KK_t \checkvt$, the state one-step-ahead residuals are perfectly correlated with the model one-step-ahead residuals so the joint distribution is not useful (all the information is in the variance of $\checkVt$). + + +The Cholesky standardized residuals for $\overline{\varepsilon}_t$ are +\begin{equation} +\overline{\Sigma}_t^{-1/2} \overline{\varepsilon}_t +\end{equation} +However the Cholesky standardized joint residuals cannot be computed since $\overline{\Sigma}_t$ is not positive definite. Because $\checkwt$ equals $\KK_t \checkvt$, the state residuals are completely explained by the model residuals. However we can compute the Cholesky standardized model residuals using +\begin{equation} +\var[\checkVt]^{-1/2} \checkvt +\end{equation} +$\var[\checkVt]^{-1/2}$ is the inverse of the lower triangle of the Cholesky decomposition of $\var[\checkVt]$. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t$ (both model and state one-step ahead residuals) can be computed with the inverse of the square root of the diagonal of $\overline{\Sigma}_t$: +\begin{equation} +\dg(\overline{\Sigma}_t)^{-1/2} \overline{\varepsilon}_t +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\subsubsection{with the state residuals defined from $t$ to $t+1$} + +\emph{Note that the model residual is conditioned on data 1 to $t-1$ and the state residual on data 1 to $t$ in this case.} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t^* = \begin{bmatrix}\checkvt\\ \checkwtp \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWtp$ is +\begin{equation}\label{eq:covhatVtWtp.onestep.2} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t+1}\checkVtp] = \cov[\checkVt, \checkVtp]\KK_{t+1}^\top +\end{equation} +Innovations residuals are temporally uncorrelated, thus $\cov[\checkVt,\checkVtp]=0$ and thus $\cov[\checkVt,\checkWtp]=0$. + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep2} +\overline{\Sigma}_t^* = \var[\overline{\varepsilon}_t^*] = \begin{bmatrix}[c|c] + \var[\checkVt]& 0\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +0 & \KK_{t+1}\var[\checkVtp]\KK_{t+1}^\top \end{bmatrix}, +\end{equation} + +The Cholesky standardized residuals for $\overline{\varepsilon}_t^*$ are +\begin{equation} +(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} + $\overline{\Sigma}_t^*$ is positive definite so its Cholesky decomposition can be computed. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t^*$ are: +\begin{equation} +\dg(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\section{Distribution of the MARSS contemporaneous model residuals} + +Contemporaneous model residuals are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t$. This section gives the residual variance for these residuals. There are no state residuals for this case as that would require the expected value of $\XX_t$ conditioned on the data up to $t+1$. + +Define the contemporaneous model residuals $\dotvt$ as: +\begin{equation}\label{eq:vtt} +\dotvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxtt - \aa_t, +\end{equation} +where $\hatxtt$ is $\E[\XX_t|\yy^{(1),t}]$ (expected value of $\XX_t$ conditioned on the data up to time $t$). The random variable, contemporaneous model residuals over all possible $\yy_t$, is $\dotVt$. Its mean is 0 and we want to find its variance. + +The derivation of the variance of $\dotVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:contemp.model} +\var[\dotVt] = \RR_t - \ZZ_t \hatVtt \ZZ_t^\top + \hatStt\ZZ_t^\top + \ZZ_t(\hatStt)^\top +\end{equation} +where the $\hatVtt$ and $\hatStt$ are now conditioned on only the data from 1 to $t$. +$\hatStt = \cov[\YY_t,\XX_t|\yy^{(1), t}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t}]$. +If $\yy_t$ has no missing values, this reduces to $\RR_t - \ZZ_t \hatVtt \ZZ_t^\top$ while if $\yy_t$ is all missing values, this reduces to $\RR_t + \ZZ_t \hatVtt \ZZ_t^\top$. See discussion of this after Equation \ref{eq:first.and.secons.vvtgeneral}. + +Equation \ref{eq:contemp.model} gives the equation for the case where $\yy_t$ is partially observed. $\hatStt$ is output by the \verb@MARSShatyt()@ function in the \{MARSS\} package and $\hatVtt$ is output by the \verb@MARSSkfss()@ function. + +\bibliography{./EMDerivation} +\bibliographystyle{apalike} + +\end{document} diff --git a/inst/doc/Chapter_AnimalTracking.R b/inst/doc/Chapter_AnimalTracking.R new file mode 100644 index 0000000..e87bd84 --- /dev/null +++ b/inst/doc/Chapter_AnimalTracking.R @@ -0,0 +1,349 @@ +################################################### +### code chunk number 2: Cs00_required_libraries +################################################### +library(MARSS) +library(maps) + + +################################################### +### code chunk number 3: Cs01_data2 +################################################### +loggerheadNoisy[1:6, ] + + +################################################### +### code chunk number 4: Cs02_turtles2 +################################################### +turtles <- levels(loggerheadNoisy$turtle) +turtles + + +################################################### +### code chunk number 5: Cs03_data3 +################################################### +turtlename <- "BigMama" +theTurtle <- which(loggerheadNoisy$turtle == turtlename) +dat <- loggerheadNoisy[theTurtle, 5:6] +dat <- t(dat) # transpose + + +################################################### +### code chunk number 6: Cs04_fig-code +################################################### +# load the map package; you have to install it first +library(maps) +# Read in our noisy data (no missing values) +pdat <- loggerheadNoisy # for plotting +turtlename <- "BigMama" +theTurtle <- which(loggerheadNoisy$turtle == turtlename) +par(mai = c(0, 0, 0, 0), mfrow = c(1, 1)) +map("state", + region = c( + "florida", "georgia", "south carolina", + "north carolina", "virginia", "delaware", "new jersey", "maryland" + ), + xlim = c(-85, -70) +) +points(pdat$lon[theTurtle], pdat$lat[theTurtle], + col = "blue", pch = 21, cex = 0.7 +) + + +################################################### +### code chunk number 7: Cs05_badtagfig +################################################### +# load the map package; you have to install it first +library(maps) +# Read in our noisy data (no missing values) +pdat <- loggerheadNoisy # for plotting +turtlename <- "BigMama" +par(mai = c(0, 0, 0, 0), mfrow = c(1, 1)) +map("state", region = c( + "florida", "georgia", "south carolina", "north carolina", + "virginia", "delaware", "new jersey", "maryland" +), xlim = c(-85, -70)) +points(pdat$lon[which(pdat$turtle == turtlename)], pdat$lat[which(pdat$turtle == turtlename)], + col = "blue", pch = 21, cex = 0.7 +) + + +################################################### +### code chunk number 8: Cs06_setup2 +################################################### +Z.model <- "identity" +U.model <- "unequal" +Q.model <- "diagonal and unequal" +R.model <- "diagonal and unequal" + + +################################################### +### code chunk number 9: Cs07_fitmodel +################################################### +kem <- MARSS(dat, model = list( + Z = Z.model, + Q = Q.model, R = R.model, U = U.model +)) + + +################################################### +### code chunk number 10: Cs08_code-to-plot +################################################### +# Code to plot estimated turtle track against observations +# The estimates +pred.lon <- kem$states[1, ] +pred.lat <- kem$states[2, ] + +par(mai = c(0, 0, 0, 0), mfrow = c(1, 1)) +library(maps) +pdat <- loggerheadNoisy +turtlename <- "BigMama" +map("state", + region = c( + "florida", "georgia", "south carolina", + "north carolina", "virginia", "delaware", "new jersey", "maryland" + ), + xlim = c(-85, -70) +) +points(pdat$lon[theTurtle], pdat$lat[theTurtle], + col = "blue", pch = 21, cex = 0.7 +) +lines(pred.lon, pred.lat, col = "red", lwd = 2) + +goodturtles <- loggerhead +gooddat <- goodturtles[which(goodturtles$turtle == turtlename), 5:6] +points(gooddat[, 1], gooddat[, 2], col = "black", lwd = 2, pch = 3, cex = 1.1) +legend("bottomright", c( + "bad locations", "estimated true location", + "good location data" +), +pch = c(1, -1, 3), lty = c(-1, 1, -1), +col = c("blue", "red", "black"), bty = FALSE +) + + +################################################### +### code chunk number 11: Cs09_figbigmama +################################################### +# Code to plot estimated turtle track against observations +# The estimates +pred.lon <- kem$states[1, ] +pred.lat <- kem$states[2, ] + +par(mai = c(0, 0, 0, 0), mfrow = c(1, 1)) +library(maps) +pdat <- loggerheadNoisy +turtlename <- "BigMama" +map("state", region = c( + "florida", "georgia", "south carolina", "north carolina", + "virginia", "delaware", "new jersey", "maryland" +), xlim = c(-85, -70)) +points(pdat$lon[which(pdat$turtle == turtlename)], + pdat$lat[which(pdat$turtle == turtlename)], + col = "blue", pch = 21, cex = 0.7 +) +lines(pred.lon, pred.lat, col = "red", lwd = 2) + +goodturtles <- loggerhead +gooddat <- goodturtles[which(goodturtles$turtle == turtlename), 5:6] +points(gooddat[, 1], gooddat[, 2], + col = "black", lwd = 2, pch = 3, cex = 1.1 +) +legend("bottomright", c( + "bad locations", "estimated true location", + "good location data" +), +pch = c(1, -1, 3), lty = c(-1, 1, -1), +col = c("blue", "red", "black"), bty = FALSE +) + + +################################################### +### code chunk number 12: Cs09b_GCDF +################################################### +GCDF <- function(lon1, lon2, lat1, lat2, degrees = TRUE, units = "miles") { + temp <- ifelse(degrees == FALSE, + acos(sin(lat1) * sin(lat2) + cos(lat1) * cos(lat2) * cos(lon2 - lon1)), + acos(sin(lat1 / 57.2958) * sin(lat2 / 57.2958) + + cos(lat1 / 57.2958) * cos(lat2 / 57.2958) * + cos(lon2 / 57.2958 - lon1 / 57.2958)) + ) + r <- 3963.0 # (statute miles) , default + if ("units" == "nm") r <- 3437.74677 # (nautical miles) + if ("units" == "km") r <- 6378.7 # (kilometers) + return(r * temp) +} + + +################################################### +### code chunk number 13: Cs10_distance (eval = FALSE) +################################################### +## distance[i - 1] <- GCDF( +## pred.lon[i - 1], pred.lon[i], +## pred.lat[i - 1], pred.lat[i] +## ) + + +################################################### +### code chunk number 14: Cs11_distance2 +################################################### +distance <- array(NA, dim = c(dim(dat)[2] - 1, 1)) +for (i in 2:dim(dat)[2]) { + distance[i - 1] <- GCDF( + pred.lon[i - 1], pred.lon[i], + pred.lat[i - 1], pred.lat[i] + ) +} + + +################################################### +### code chunk number 15: Cs13_disfig +################################################### +par(mfrow = c(1, 1)) +hist(distance) # make a histogram of distance traveled per day + + +################################################### +### code chunk number 16: Cs14_disfig2 +################################################### +# Compare to the distance traveled per day if you used the raw data +distance.noerr <- array(NA, dim = c(dim(dat)[2] - 1, 1)) +for (i in 2:dim(dat)[2]) { + distance.noerr[i - 1] <- GCDF(dat[1, i - 1], dat[1, i], dat[2, i - 1], dat[2, i]) +} +hist(distance.noerr) # make a histogram of distance traveled per day + + +################################################### +### code chunk number 17: Cs15_mean.miles +################################################### +# accounting for observation error +mean(distance) +# assuming the data have no observation error +mean(distance.noerr) + + +################################################### +### code chunk number 18: Cs16_turt-names +################################################### +levels(loggerheadNoisy$turtle) + + +################################################### +### code chunk number 20: Cs18_code +################################################### +############################################################### +# GCDF FUNCTION +# This function converts units of degrees lat/lon to miles, +# nautical miles, or kilometers +############################################################### +GCDF <- function(lon1, lon2, lat1, lat2, degrees = TRUE, units = "miles") { + # This is the function for the Great Circle Distance Formula + # using decimal degrees or radians + # Calculations at: http://www.nhc.noaa.gov/gccalc.shtml + # This first component is only dependent on degrees or radians + temp <- ifelse(degrees == FALSE, acos(sin(lat1) * + sin(lat2) + cos(lat1) * cos(lat2) * cos(lon2 - lon1)), + acos(sin(lat1 / 57.2958) * sin(lat2 / 57.2958) + cos(lat1 / 57.2958) + * cos(lat2 / 57.2958) * cos(lon2 / 57.2958 - lon1 / 57.2958)) + ) + r <- 3963.0 # (statute miles) , default + if ("units" == "nm") r <- 3437.74677 # (nautical miles) + if ("units" == "km") r <- 6378.7 # (kilometers) + return(r * temp) +} + +library(maps) # must be installed from CRAN + +# our noisy data (with no missing values) +turtles <- levels(loggerheadNoisy$turtle) +levels(loggerheadNoisy$turtle) + +############## SPECIFY THE TURTLE NAME HERE +turtlename <- "BigMama" + +dat <- loggerheadNoisy[which(loggerheadNoisy$turtle == turtlename), 5:6] +dat <- t(dat) + +# Set up the MSSM model +# We are going to make a big approximation: +# We are going to pretend that 1 deg longitude +# change is equal to about the same distance (miles) +# over the range of latitudes that the turtles are moving +# That's not true. There is about a 10% difference across +# their range of latitude movement. +Q.model <- "diagonal and unequal" +R.model <- "diagonal and unequal" +U.model <- "unequal" +Z.model <- "identity" + +# Fit a random walk model for lon/lat to the lon/lat data +kem <- MARSS(dat, model = list( + Z = Z.model, + Q = Q.model, R = R.model, U = U.model +)) +pred.lon <- kem$states[1, ] +pred.lat <- kem$states[2, ] + +########################################## +# Plot the results +########################################## +op <- par(mai = c(0, 0, 0, 0)) +map("state", region = c( + "florida", "georgia", + "south carolina", "north carolina", "virginia", + "delaware", "new jersey", "maryland" +), xlim = c(-85, -65)) +points(loggerheadNoisy$lon[which(loggerheadNoisy$turtle == turtlename)], + loggerheadNoisy$lat[which(loggerheadNoisy$turtle == turtlename)], + col = "blue", pch = 21, cex = 0.7 +) +lines(pred.lon, pred.lat, col = "red", lwd = 2) + +# add the good location data +goodturtles <- loggerhead +gooddat <- goodturtles[which(goodturtles$turtle == turtlename), 5:6] +points(gooddat[, 1], gooddat[, 2], col = "black", lwd = 2, pch = 3, cex = 1.1) +legend("bottomright", c("bad locations", "estimated true location", "good location data"), pch = c(1, -1, 3), lty = c(-1, 1, -1), col = c("blue", "red", "black"), bty = F) + +# add the proposed fishery areas +lines(c(-77, -78, -78, -77, -77), c(33.5, 33.5, 32.5, 32.5, 33.5), + col = "red", lwd = 2 +) +lines(c(-75, -76, -76, -75, -75), c(38, 38, 37, 37, 38), + col = "red", lwd = 2 +) + +########################################### +# Calculate the average miles traveled each day using +# the function GCDF defined above +# You must select and run the GCDF code first +########################################### +distance <- array(NA, dim = c(dim(dat)[2] - 1, 1)) +for (i in 2:dim(dat)[2]) { + distance[i - 1] <- GCDF( + pred.lon[i - 1], pred.lon[i], + pred.lat[i - 1], pred.lat[i] + ) +} + +par(op) # reset plotting pars back to normal +par(mfrow = c(1, 2)) # make a 2 panel graph +hist(distance) # make a histogram of distance traveled per day +print(paste( + "KalmanEM estimate of ave. mile per day for ", + turtlename, " = ", mean(distance) +)) + +# Compare to the distance traveled per day if you used the raw data +distance <- array(NA, dim = c(dim(dat)[2] - 1, 1)) +for (i in 2:dim(dat)[2]) { + distance[i - 1] <- GCDF(dat[1, i - 1], dat[1, i], dat[2, i - 1], dat[2, i]) +} +hist(distance) # make a histogram of distance traveled per day +mean(distance) +print(paste( + "Raw estimate of ave. mile per day for ", + turtlename, " = ", mean(distance) +)) + + diff --git a/inst/doc/Chapter_CombiningTrendData.R b/inst/doc/Chapter_CombiningTrendData.R new file mode 100644 index 0000000..f67c64c --- /dev/null +++ b/inst/doc/Chapter_CombiningTrendData.R @@ -0,0 +1,159 @@ +################################################### +### code chunk number 2: Cs000_required_libraries +################################################### +library(MARSS) + + +################################################### +### code chunk number 3: Cs001_readinredddata +################################################### +head(okanaganRedds) +logRedds <- log(t(okanaganRedds)[c("aerial", "ground"), ]) + + +################################################### +### code chunk number 4: Cs002_fig1 +################################################### +# Code for plotting raw Okanagan redd counts +plot(okanaganRedds[, 1], okanaganRedds[, 2], + xlab = "", ylab = "Redd counts", main = "", col = "red", pch = 1 +) +points(okanaganRedds[, 1], okanaganRedds[, 3], col = "blue", pch = 2) +legend("topleft", + inset = 0.1, legend = c("Aerial survey", "Ground survey"), + col = c("red", "blue"), pch = c(1, 2) +) + + +################################################### +### code chunk number 5: Cs003_reddmodel1 +################################################### +model1 <- list() +model1$R <- "diagonal and equal" +model1$Z <- matrix(1, 2, 1) +model1$A <- "scaling" +kem1 <- MARSS(logRedds, model = model1) + + +################################################### +### code chunk number 6: Cs004_reddmodel2 +################################################### +model2 <- model1 # model2 is based on model1 +model2$R <- "diagonal and unequal" +kem2 <- MARSS(logRedds, model = model2) + + +################################################### +### code chunk number 7: Cs005_reddmodel3 +################################################### +model3 <- list() +model3$Q <- "diagonal and equal" +model3$R <- "diagonal and equal" +model3$U <- "equal" +model3$Z <- "identity" +model3$A <- "zero" +kem3 <- MARSS(logRedds, model = model3) + + +################################################### +### code chunk number 8: Cs005b_aic +################################################### +c(mod1 = kem1$AICc, mod2 = kem2$AICc, mod3 = kem3$AICc) + + +################################################### +### code chunk number 9: Cs006_fig2 +################################################### +# Code for plotting the fit from the best model +plot(okanaganRedds[, 1], logRedds[1, ], xlab = "", ylab = "Redd counts", + main = "", col = "red", ylim = c(0, 8) +) +points(okanaganRedds[, 1], logRedds[2, ], col = "blue", pch = 2) +lines(okanaganRedds[, 1], c(kem1$states), lty = 1, lwd = 2) +lines(okanaganRedds[, 1], c(kem1$states + 2 * kem1$states.se), lty = 1, lwd = 1, col = "grey40") +lines(okanaganRedds[, 1], c(kem1$states - 2 * kem1$states.se), lty = 1, lwd = 1, col = "grey40") + + +################################################### +### code chunk number 26: Cs007_birddata +################################################### +birddat <- t(kestrel[, c("British.Columbia", "Alberta", "Saskatchewan")]) +head(kestrel) + + +################################################### +### code chunk number 27: Cs008_plot-bird-data +################################################### +# Make a plot of the three time series +plot(kestrel[, 1], kestrel[, 2], xlab = "", ylab = "Index of kestrel abundance", main = "", col = "red", ylim = c(0, 2), pch = 21) +points(kestrel[, 1], kestrel[, 3], col = "blue", pch = 22) +points(kestrel[, 1], kestrel[, 4], col = "purple", pch = 25) +legend("topright", inset = 0.1, legend = c("British Columbia", "Alberta", "Saskatchewan"), col = c("red", "blue", "purple"), pch = c(21, 22, 25)) + + +################################################### +### code chunk number 28: Cs009_fit-bird-model-1 +################################################### +model.b1=list() +model.b1$R="diagonal and equal" +model.b1$Z=matrix(1,3,1) +kem.b1 = MARSS(birddat, model=model.b1, control=list(minit=100) ) + + +################################################### +### code chunk number 29: Cs011_fit-bird-model-2 +################################################### +model.b2 <- list() +model.b2$Q <- "diagonal and equal" +model.b2$R <- "diagonal and equal" +model.b2$Z <- "identity" +model.b2$A <- "zero" +model.b2$U <- "equal" +kem.b2 <- MARSS(birddat, model = model.b2) + + +################################################### +### code chunk number 30: Cs013_fit-bird-model-3 +################################################### +model.b3 <- model.b2 # is is based on model.b2 +# all we change is the structure of Q +model.b3$Q <- "diagonal and unequal" +model.b3$U <- "unequal" +kem.b3 <- MARSS(birddat, model = model.b3) + + +################################################### +### code chunk number 31: Cs015_fit-bird-model-4 +################################################### +model.b4 <- list() +model.b4$Q <- "diagonal and unequal" +model.b4$R <- "diagonal and equal" +model.b4$Z <- factor(c("BC", "AB-SK", "AB-SK")) +model.b4$A <- "scaling" +model.b4$U <- "unequal" +kem.b4 <- MARSS(birddat, model = model.b4) + + +################################################### +### code chunk number 32: Cs016_aics +################################################### +c(mod1 = kem.b1$AICc, mod2 = kem.b2$AICc, + mod3 = kem.b3$AICc, mod4 = kem.b4$AICc) + + +################################################### +### code chunk number 33: Cs017_plot-bird-model-4-fits +################################################### +# Make a plot of the predicted trajectory, confidence intervals, and the raw data in log-space +plot(kestrel[, 1], kestrel[, 2], xlab = "", ylab = "Index of kestrel abundance", + main = "", col = "red", ylim = c(0, 2), pch = 21) +points(kestrel[, 1], kestrel[, 3], col = "blue", pch = 22) +points(kestrel[, 1], kestrel[, 4], col = "purple", pch = 25) +lines(kestrel[, 1], c(kem.b4$states[1, ]), lty = 3, lwd = 2, col = "red") +lines(kestrel[, 1], c(kem.b4$states[2, ]), lty = 3, lwd = 2, col = "blue") +lines(kestrel[, 1], c(kem.b4$states[2, ] + coef(kem.b4, type = "matrix")$A[3, 1]), + lty = 3, lwd = 2, col = "purple") +legend("topright", inset = 0.1, legend = c("British Columbia", "Alberta", "Saskatchewan"), + col = c("red", "blue", "purple"), pch = c(21, 22, 25)) + + diff --git a/inst/doc/Chapter_Covariates.R b/inst/doc/Chapter_Covariates.R new file mode 100644 index 0000000..606d9bd --- /dev/null +++ b/inst/doc/Chapter_Covariates.R @@ -0,0 +1,368 @@ +################################################### +### code chunk number 2: Covar_sec0_required_libraries +################################################### +library(MARSS) + + +################################################### +### code chunk number 3: Covar_sec2_1_load-plankton-data +################################################### +fulldat <- lakeWAplanktonTrans +years <- fulldat[, "Year"] >= 1965 & fulldat[, "Year"] < 1975 +dat <- t(fulldat[years, c("Greens", "Bluegreens")]) +the.mean <- apply(dat, 1, mean, na.rm = TRUE) +the.sigma <- sqrt(apply(dat, 1, var, na.rm = TRUE)) +dat <- (dat - the.mean) * (1 / the.sigma) + + +################################################### +### code chunk number 4: Covar_sec2_2_z-score-covar-data +################################################### +covariates <- rbind( + Temp = fulldat[years, "Temp"], + TP = fulldat[years, "TP"] +) +# z.score the covariates +covariates <- zscore(covariates) + + +################################################### +### code chunk number 5: Covar_sec2_3_plot-dat +################################################### +LWA <- ts(cbind(Year = fulldat[years, "Year"], t(dat), t(covariates)), start = c(1965, 1), end = c(1974, 12), freq = 12) +plot.ts(LWA[, c("Greens", "Bluegreens", "Temp", "TP")], main = "", yax.flip = TRUE) + + +################################################### +### code chunk number 6: Covar_sec3_1_covar-model-0 +################################################### +Q <- U <- x0 <- "zero" +B <- Z <- "identity" +d <- covariates +A <- "zero" +D <- "unconstrained" +y <- dat # to show relationship between dat & the equation +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, + D = D, d = d, x0 = x0 +) +kem <- MARSS(y, model = model.list) + + +################################################### +### code chunk number 7: Covar_sec3_2_covar-model-0b +################################################### +Q <- "unconstrained" +B <- "diagonal and unequal" +A <- U <- x0 <- "zero" +R <- "diagonal and equal" +d <- covariates +D <- "unconstrained" +y <- dat +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, + R = R, D = D, d = d, x0 = x0 +) +control.list <- list(maxit = 1500) +kem <- MARSS(y, model = model.list, control = control.list) + + +################################################### +### code chunk number 8: Covar_sec4_1_covar-model-1 +################################################### +R <- A <- U <- "zero" +B <- Z <- "identity" +Q <- "equalvarcov" +C <- "unconstrained" +x <- dat # to show the relation between dat & the equations +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, + R = R, C = C, c = covariates +) +kem <- MARSS(x, model = model.list) + + +################################################### +### code chunk number 9: Covar_sec4_2_covar-model-1c +################################################### +model.list$B <- "diagonal and unequal" +kem <- MARSS(dat, model = model.list) + + +################################################### +### code chunk number 10: Covar_sec5_1_covar-model-5 +################################################### +model.list$R <- diag(0.16, 2) +kem <- MARSS(dat, model = model.list) + + +################################################### +### code chunk number 11: Covar_sec6_01_set-up-seasonal-dat +################################################### +years <- fulldat[, "Year"] >= 1965 & fulldat[, "Year"] < 1975 +phytos <- c( + "Diatoms", "Greens", "Bluegreens", + "Unicells", "Other.algae" +) +dat <- t(fulldat[years, phytos]) + +# z.score data again because we changed the mean when we subsampled +dat <- zscore(dat) +# number of time periods/samples +TT <- ncol(dat) + + +################################################### +### code chunk number 12: Covar_sec6_02_set-up-month-factors +################################################### +# number of "seasons" (e.g., 12 months per year) +period <- 12 +# first "season" (e.g., Jan = 1, July = 7) +per.1st <- 1 +# create factors for seasons +c.in <- diag(period) +for (i in 2:(ceiling(TT / period))) { + c.in <- cbind(c.in, diag(period)) +} +# trim c.in to correct start & length +c.in <- c.in[, (1:TT) + (per.1st - 1)] +# better row names +rownames(c.in) <- month.abb + + +################################################### +### code chunk number 13: Covar_sec6_03_C-constrained +################################################### +C <- matrix(month.abb, 5, 12, byrow = TRUE) +C + + +################################################### +### code chunk number 14: Covar_sec6_04_C-constrained2 +################################################### +C <- "unconstrained" + + +################################################### +### code chunk number 15: Covar_sec6_05_month-factor-marss-params +################################################### +# Each taxon has unique density-dependence +B <- "diagonal and unequal" +# Independent process errors +Q <- "diagonal and unequal" +# We have demeaned the data & are fitting a mean-reverting model +# by estimating a diagonal B, thus +U <- "zero" +# Each obs time series is associated with only one process +Z <- "identity" +# The data are demeaned & fluctuate around a mean +A <- "zero" +# Observation errors are independent, but they +# have similar variance due to similar collection methods +R <- "diagonal and equal" +# No covariate effects in the obs equation +D <- "zero" +d <- "zero" + + +################################################### +### code chunk number 16: Covar_sec6_06_fit-month-factor-with-MARSS +################################################### +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, R = R, + C = C, c = c.in, D = D, d = d +) +seas.mod.1 <- MARSS(dat, model = model.list, control = list(maxit = 1500)) + +# Get the estimated seasonal effects +# rows are taxa, cols are seasonal effects +seas.1 <- coef(seas.mod.1, type = "matrix")$C +rownames(seas.1) <- phytos +colnames(seas.1) <- month.abb + + +################################################### +### code chunk number 17: Covar_sec6_07_poly-month-factor +################################################### +# number of "seasons" (e.g., 12 months per year) +period <- 12 +# first "season" (e.g., Jan = 1, July = 7) +per.1st <- 1 +# order of polynomial +poly.order <- 3 +# create polynomials of months +month.cov <- matrix(1, 1, period) +for (i in 1:poly.order) { + month.cov <- rbind(month.cov, (1:12)^i) +} +# our c matrix is month.cov replicated once for each year +c.m.poly <- matrix(month.cov, poly.order + 1, TT + period, byrow = FALSE) +# trim c.in to correct start & length +c.m.poly <- c.m.poly[, (1:TT) + (per.1st - 1)] + +# Everything else remains the same as in the previous example +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, R = R, + C = C, c = c.m.poly, D = D, d = d +) +seas.mod.2 <- MARSS(dat, model = model.list, control = list(maxit = 1500)) + + +################################################### +### code chunk number 18: Covar_sec6_08_seasonal-effect-poly +################################################### +C.2 <- coef(seas.mod.2, type = "matrix")$C +seas.2 <- C.2 %*% month.cov +rownames(seas.2) <- phytos +colnames(seas.2) <- month.abb + + +################################################### +### code chunk number 19: Covar_sec6_09_seasonal-fourier +################################################### +cos.t <- cos(2 * pi * seq(TT) / period) +sin.t <- sin(2 * pi * seq(TT) / period) +c.Four <- rbind(cos.t, sin.t) + + +################################################### +### code chunk number 20: Covar_sec6_10_seasonal-fourier-fit +################################################### +model.list <- list( + B = B, U = U, Q = Q, Z = Z, A = A, R = R, + C = C, c = c.Four, D = D, d = d +) +seas.mod.3 <- MARSS(dat, model = model.list, control = list(maxit = 1500)) + + +################################################### +### code chunk number 21: Covar_sec6_11_seasonal-effects-fourier +################################################### +C.3 <- coef(seas.mod.3, type = "matrix")$C +# The time series of net seasonal effects +seas.3 <- C.3 %*% c.Four[, 1:period] +rownames(seas.3) <- phytos +colnames(seas.3) <- month.abb + + +################################################### +### code chunk number 22: Covar_sec6_12_plot-seas-effects +################################################### +par(mfrow = c(3, 1), mar = c(2, 4, 2, 2)) +graphics::matplot(t(seas.1), type = "l", bty = "n", xaxt = "n", ylab = "Fixed monthly", col = 1:5) +axis(1, labels = month.abb, at = 1:12, las = 2, cex.axis = 0.75) +legend("topright", lty = 1:5, legend = phytos, cex = 0.6, col = 1:5) + +graphics::matplot(t(seas.2), type = "l", bty = "n", xaxt = "n", ylab = "Cubic", col = 1:5) +axis(1, labels = month.abb, at = 1:12, las = 2, cex.axis = 0.75) +legend("topright", lty = 1:5, legend = phytos, cex = 0.6, col = 1:5) + +graphics::matplot(t(seas.3), type = "l", bty = "n", xaxt = "n", ylab = "Fourier", col = 1:5) +axis(1, labels = month.abb, at = 1:12, las = 2, cex.axis = 0.75) +legend("topright", lty = 1:5, legend = phytos, cex = 0.6, col = 1:5) + + +################################################### +### code chunk number 23: Covar_sec6_13_show-aics +################################################### +data.frame( + Model = c("Fixed", "Cubic", "Fourier"), + AICc = round(c( + seas.mod.1$AICc, + seas.mod.2$AICc, + seas.mod.3$AICc + ), 1), + stringsAsFactors = FALSE +) + + +################################################### +### code chunk number 24: Covar_sec7_01_diag-code (eval = FALSE) +################################################### +## for (i in 1:3) { +## dev.new() +## modn <- paste("seas.mod", i, sep = ".") +## for (j in 1:5) { +## plot.ts(MARSSresiduals(modn, type = "tt1")$model.residuals[j, ], +## ylab = "Residual", main = phytos[j] +## ) +## abline(h = 0, lty = "dashed") +## acf(MARSSresiduals(modn, type = "tt1")$model.residuals[j, ], +## na.action = na.pass +## ) +## } +## } + + +################################################### +### code chunk number 25: Covar_sec7_02_plot-acf-1 +################################################### +par(mfrow = c(5, 2), mai = c(0.1, 0.5, 0.2, 0.1), omi = c(0.5, 0, 0, 0)) +for (i in 1:5) { + plot.ts(MARSSresiduals(seas.mod.1, type = "tt1")$model.residuals[i, ], + ylab = "Residual", main = phytos[i], xlab = "", xaxt = "n" + ) + abline(h = 0, lty = "dashed") + if (i == 5) { + axis(1, + at = 1 + seq(0, TT - period, by = 12), + labels = seq(fulldat[years, "Year"][1], fulldat[years, "Year"][TT]) + ) + mtext(side = 1, line = 2.7, "Time") + } + acf(MARSSresiduals(seas.mod.1, type = "tt1")$model.residuals[i, ], lag.max = period, na.action = na.pass) + if (i == 5) { + axis(1, at = c(0, seq(period))) + mtext(side = 1, line = 2.7, "Time lag") + } +} + + +################################################### +### code chunk number 26: Covar_sec7_03_plot-acf-2 +################################################### +par(mfrow = c(5, 2), mai = c(0.1, 0.5, 0.2, 0.1), omi = c(0.5, 0, 0, 0)) +for (i in 1:5) { + plot.ts(MARSSresiduals(seas.mod.2, type = "tt1")$model.residuals[i, ], + ylab = "Residual", main = phytos[i], xlab = "", xaxt = "n" + ) + abline(h = 0, lty = "dashed") + if (i == 5) { + axis(1, + at = 1 + seq(0, TT - period, by = 12), + labels = seq(fulldat[years, "Year"][1], fulldat[years, "Year"][TT]) + ) + mtext(side = 1, line = 2.7, "Time") + } + acf(MARSSresiduals(seas.mod.2, type = "tt1")$model.residuals[i, ], lag.max = period, na.action = na.pass) + if (i == 5) { + axis(1, at = c(0, seq(period))) + mtext(side = 1, line = 2.7, "Time lag") + } +} + + +################################################### +### code chunk number 27: Covar_sec7_04_plot-acf-2 +################################################### +par(mfrow = c(5, 2), mai = c(0.1, 0.5, 0.2, 0.1), omi = c(0.5, 0, 0, 0)) +for (i in 1:5) { + plot.ts(MARSSresiduals(seas.mod.3, type = "tt1")$model.residuals[i, ], + ylab = "Residual", main = phytos[i], xlab = "", xaxt = "n" + ) + abline(h = 0, lty = "dashed") + if (i == 5) { + axis(1, + at = 1 + seq(0, TT - period, by = 12), + labels = seq(fulldat[years, "Year"][1], fulldat[years, "Year"][TT]) + ) + mtext(side = 1, line = 2.7, "Time") + } + acf(MARSSresiduals(seas.mod.3, type = "tt1")$model.residuals[i, ], lag.max = period, na.action = na.pass) + if (i == 5) { + axis(1, at = c(0, seq(period))) + mtext(side = 1, line = 2.7, "Time lag") + } +} + + diff --git a/inst/doc/Chapter_DFA.R b/inst/doc/Chapter_DFA.R new file mode 100644 index 0000000..05733aa --- /dev/null +++ b/inst/doc/Chapter_DFA.R @@ -0,0 +1,467 @@ +################################################### +### code chunk number 2: Cs00_required_libraries +################################################### +library(MARSS) +library(xtable) + + +################################################### +### code chunk number 3: Cs01_read_in_data +################################################### +data(lakeWAplankton) +# we want lakeWAplanktonTrans, which has been log-transformed +# and the 0s replaced with NAs +plankdat <- lakeWAplanktonTrans +years <- plankdat[, "Year"] >= 1980 & plankdat[, "Year"] < 1990 +phytos <- c( + "Cryptomonas", "Diatoms", "Greens", + "Unicells", "Other.algae" +) +dat.spp.1980 <- plankdat[years, phytos] + + +################################################### +### code chunk number 4: Cs02_transpose_data +################################################### +# transpose data so time goes across columns +dat.spp.1980 <- t(dat.spp.1980) +N.ts <- nrow(dat.spp.1980) +TT <- ncol(dat.spp.1980) + + +################################################### +### code chunk number 5: Cs03_zscore +################################################### +Sigma <- sqrt(apply(dat.spp.1980, 1, var, na.rm = TRUE)) +y.bar <- apply(dat.spp.1980, 1, mean, na.rm = TRUE) +dat.z <- (dat.spp.1980 - y.bar) * (1 / Sigma) +rownames(dat.z) <- rownames(dat.spp.1980) + + +################################################### +### code chunk number 6: Cs03b_zscore +################################################### +dat.z <- zscore(dat.spp.1980) + + +################################################### +### code chunk number 7: Cs04_plotdata +################################################### +spp <- rownames(dat.spp.1980) +par(mfcol = c(3, 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +for (i in spp) { + plot(dat.z[i, ], xlab = "", ylab = "Abundance index", bty = "L", xaxt = "n", pch = 16, col = "blue", type = "b") + axis(1, 12 * (0:dim(dat.spp.1980)[2]) + 1, 1980 + 0:dim(dat.spp.1980)[2]) + title(i) +} + + +################################################### +### code chunk number 8: Cs05_setupZ +################################################### +Z.vals <- list( + "z11", 0, 0, + "z21", "z22", 0, + "z31", "z32", "z33", + "z41", "z42", "z43", + "z51", "z52", "z53" +) +Z <- matrix(Z.vals, nrow = N.ts, ncol = 3, byrow = TRUE) + + +################################################### +### code chunk number 9: Cs06_printZ +################################################### +print(Z) + + +################################################### +### code chunk number 10: Cs07_setupQR +################################################### +Q <- B <- diag(1, 3) + + +################################################### +### code chunk number 11: Cs08_setupR +################################################### +R.vals <- list( + "r11", 0, 0, 0, 0, + 0, "r22", 0, 0, 0, + 0, 0, "r33", 0, 0, + 0, 0, 0, "r44", 0, + 0, 0, 0, 0, "r55" +) + +R <- matrix(R.vals, nrow = N.ts, ncol = N.ts, byrow = TRUE) + + +################################################### +### code chunk number 12: Cs09_printR +################################################### +print(R) + + +################################################### +### code chunk number 13: Cs10_setupR_short +################################################### +R <- "diagonal and unequal" + + +################################################### +### code chunk number 14: Cs11_setupU +################################################### +x0 <- U <- matrix(0, nrow = 3, ncol = 1) +A <- matrix(0, nrow = 6, ncol = 1) +x0 <- U <- A <- "zero" + + +################################################### +### code chunk number 15: Cs12_setupx0 +################################################### +V0 <- diag(5, 3) + + +################################################### +### code chunk number 16: Cs13_define_model_list +################################################### +dfa.model <- list( + Z = Z, A = "zero", R = R, B = B, U = U, + Q = Q, x0 = x0, V0 = V0 +) +cntl.list <- list(maxit = 50) + + +################################################### +### code chunk number 17: Cs14_fit_data +################################################### +kemz.3 <- MARSS(dat.z, model = dfa.model, control = cntl.list) + + +################################################### +### code chunk number 20: Cs15_plotfits +################################################### +fit <- kemz.3 +spp <- rownames(dat.z) +par(mfcol = c(3, 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +for (i in 1:length(spp)) { + plot(dat.z[i, ], xlab = "", ylab = "Abundance index", bty = "L", xaxt = "n", ylim = c(-4, 3), pch = 16, col = "blue") + axis(1, 12 * (0:dim(dat.z)[2]) + 1, 1980 + 0:dim(dat.z)[2]) + par.mat <- coef(fit, type = "matrix") + lines(as.vector(par.mat$Z[i, , drop = FALSE] %*% fit$states + par.mat$A[i, ]), lwd = 2) + title(spp[i]) +} + + +################################################### +### code chunk number 21: Cs16_set_up_two_trends_echo +################################################### +model.list <- list(m = 2, R = "diagonal and unequal") +kemz.2 <- MARSS(dat.spp.1980, + model = model.list, + z.score = TRUE, form = "dfa", control = cntl.list +) + + +################################################### +### code chunk number 23: Cs17_compare_mods_2n3 +################################################### +print(cbind( + model = c("3 trends", "2 trends"), + AICc = round(c(kemz.3$AICc, kemz.2$AICc)) +), +quote = FALSE +) + + +################################################### +### code chunk number 25: Cs18_setupmanytrends_echo (eval = FALSE) +################################################### +## # set new control params +## cntl.list <- list(minit = 200, maxit = 5000, allow.degen = FALSE) +## # set up forms of R matrices +## levels.R <- c( +## "diagonal and equal", +## "diagonal and unequal", +## "equalvarcov", +## "unconstrained" +## ) +## model.data <- data.frame(stringsAsFactors = FALSE) +## # fit lots of models & store results +## # NOTE: this will take a long time to run! +## for (R in levels.R) { +## for (m in 1:(N.ts - 1)) { +## dfa.model <- list(A = "zero", R = R, m = m) +## kemz <- MARSS(dat.z, +## model = dfa.model, control = cntl.list, +## form = "dfa", z.score = TRUE +## ) +## model.data <- rbind( +## model.data, +## data.frame( +## R = R, +## m = m, +## logLik = kemz$logLik, +## K = kemz$num.params, +## AICc = kemz$AICc, +## stringsAsFactors = FALSE +## ) +## ) +## assign(paste("kemz", m, R, sep = "."), kemz) +## } # end m loop +## } # end R loop + + +################################################### +### code chunk number 26: Cs19_makemodeltable +################################################### +# you must run the code to do all the models for this section +if (exists("model.data")) { + # calculate delta-AICc + model.data$delta.AICc <- model.data$AICc - min(model.data$AICc) + # calculate Akaike weights + wt <- exp(-0.5 * model.data$delta.AICc) + model.data$Ak.wt <- wt / sum(wt) + # sort results + model.tbl <- model.data[order(model.data$AICc), -4] + # drop AICc from table + # calculate cumulative wts + model.tbl$Ak.wt.cum <- cumsum(model.tbl$Ak.wt) + model.tbl <- model.tbl[, -4] +} + + +################################################### +### code chunk number 28: Cs20_kem3_R_unconstrained +################################################### +big.maxit.cntl.list <- list(minit = 200, maxit = 5000, allow.degen = FALSE) +model.list <- list(m = 2, R = "unconstrained") +the.fit <- MARSS(dat.z, model = model.list, form = "dfa", + control = big.maxit.cntl.list) + + +################################################### +### code chunk number 29: Cs21_varimax +################################################### +# get the inverse of the rotation matrix +Z.est <- coef(the.fit, type = "matrix")$Z +H.inv <- 1 +if (ncol(Z.est) > 1) + H.inv <- varimax(coef(the.fit, type = "matrix")$Z)$rotmat + + +################################################### +### code chunk number 30: Cs22_rotations +################################################### +# rotate factor loadings +Z.rot <- Z.est %*% H.inv +# rotate trends +trends.rot <- solve(H.inv) %*% the.fit$states + + +################################################### +### code chunk number 31: Cs22_rotations_cis +################################################### +# Add CIs to marssMLE object +the.fit <- MARSSparamCIs(the.fit) +# Use coef() to get the upper and lower CIs +Z.low <- coef(the.fit, type = "Z", what = "par.lowCI") +Z.up <- coef(the.fit, type = "Z", what = "par.upCI") +Z.rot.up <- Z.up %*% H.inv +Z.rot.low <- Z.low %*% H.inv +df <- data.frame( + est = as.vector(Z.rot), + conf.up = as.vector(Z.rot.up), + conf.low = as.vector(Z.rot.low) + ) + + +################################################### +### code chunk number 32: Cs23_plotfacloadings +################################################### +# plot the factor loadings +spp <- rownames(dat.z) +minZ <- 0.05 +m <- dim(trends.rot)[1] +ylims <- c(-1.1 * max(abs(Z.rot)), 1.1 * max(abs(Z.rot))) +par(mfrow = c(ceiling(m / 2), 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +for (i in 1:m) { + plot(c(1:N.ts)[abs(Z.rot[, i]) > minZ], as.vector(Z.rot[abs(Z.rot[, i]) > minZ, i]), + type = "h", lwd = 2, xlab = "", ylab = "", xaxt = "n", ylim = ylims, xlim = c(0, N.ts + 1) + ) + for (j in 1:N.ts) { + if (Z.rot[j, i] > minZ) { + text(j, -0.05, spp[j], srt = 90, adj = 1, cex = 0.9) + } + if (Z.rot[j, i] < -minZ) { + text(j, 0.05, spp[j], srt = 90, adj = 0, cex = 0.9) + } + abline(h = 0, lwd = 1, col = "gray") + } # end j loop + mtext(paste("Factor loadings on trend", i, sep = " "), side = 3, line = .5) +} # end i loop + + +################################################### +### code chunk number 33: Cs24_plottrends +################################################### +# get ts of trends +ts.trends <- t(trends.rot) +par(mfrow = c(ceiling(dim(ts.trends)[2] / 2), 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +# loop over each trend +for (i in 1:dim(ts.trends)[2]) { + # set up plot area + plot(ts.trends[, i], + ylim = c(-1.1, 1.1) * max(abs(ts.trends)), + type = "n", lwd = 2, bty = "L", + xlab = "", ylab = "", xaxt = "n", yaxt = "n" + ) + # draw zero-line + abline(h = 0, col = "gray") + # plot trend line + par(new = TRUE) + plot(ts.trends[, i], + ylim = c(-1.1, 1.1) * max(abs(ts.trends)), + type = "l", lwd = 2, bty = "L", + xlab = "", ylab = "", xaxt = "n" + ) + # add panel labels + mtext(paste("Trend", i, sep = " "), side = 3, line = 0.5) + axis(1, 12 * (0:dim(dat.spp.1980)[2]) + 1, 1980 + 0:dim(dat.spp.1980)[2]) +} # end i loop (trends) + + +################################################### +### code chunk number 34: Cs25_func_get_DFA_fits +################################################### +# If there were no missing values, this function will return the fits and CIs +getDFAfits <- function(MLEobj, alpha = 0.05, covariates = NULL) { + fits <- list() + Ey <- MARSShatyt(MLEobj) # for var() calcs + ZZ <- coef(MLEobj, type = "matrix")$Z # estimated Z + nn <- nrow(ZZ) # number of obs ts + mm <- ncol(ZZ) # number of factors/states + TT <- ncol(Ey$ytT) # number of time steps + ## check for covars + if (!is.null(covariates)) { + DD <- coef(MLEobj, type = "matrix")$D + cov_eff <- DD %*% covariates + } else { + cov_eff <- matrix(0, nn, TT) + } + ## model expectation + fits$ex <- ZZ %*% MLEobj$states + cov_eff + ## Var in model fits + VtT <- MARSSkfss(MLEobj)$VtT + VV <- NULL + for (tt in 1:TT) { + RZVZ <- coef(MLEobj, type = "matrix")$R - ZZ %*% VtT[, , tt] %*% t(ZZ) + SS <- Ey$yxtT[, , tt] - Ey$ytT[, tt, drop = FALSE] %*% t(MLEobj$states[, tt, drop = FALSE]) + VV <- cbind(VV, diag(RZVZ + SS %*% t(ZZ) + ZZ %*% t(SS))) + } + SE <- sqrt(VV) + ## upper & lower (1-alpha)% CI + fits$up <- qnorm(1 - alpha / 2) * SE + fits$ex + fits$lo <- qnorm(alpha / 2) * SE + fits$ex + return(fits) +} + + +################################################### +### code chunk number 35: Cs25b_get_DFA_fits +################################################### +fit.b <- getDFAfits(the.fit) + + +################################################### +### code chunk number 36: Cs25c_plotbestfits +################################################### +# plot the fits +ylbl <- rownames(dat.z) +w_ts <- seq(dim(dat.z)[2]) +par(mfcol = c(3, 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +for (i in 1:N.ts) { + up <- fit.b$up[i, ] + mn <- fit.b$ex[i, ] + lo <- fit.b$lo[i, ] + plot(w_ts, mn, + xlab = "", ylab = ylbl[i], xaxt = "n", type = "n", cex.lab = 1.2, + ylim = c(min(lo), max(up)) + ) + axis(1, 12 * (0:dim(dat.z)[2]) + 1, 1980 + 0:dim(dat.z)[2]) + points(w_ts, dat.z[i, ], pch = 16, col = "blue") + lines(w_ts, up, col = "darkgray") + lines(w_ts, mn, col = "black", lwd = 2) + lines(w_ts, lo, col = "darkgray") +} + + +################################################### +### code chunk number 36: Cs25d_plotwithaugment +################################################### +require(ggplot2) +alpha <- 0.05 +theme_set(theme_bw()) +d <- residuals(the.fit, type = "tT") +d$up <- qnorm(1 - alpha / 2) * d$.sigma + d$.fitted +d$lo <- qnorm(alpha / 2) * d$.sigma + d$.fitted +ggplot(data = subset(d, name=="model")) + + geom_point(aes(t, value)) + + geom_ribbon(aes(x = t, ymin = lo, ymax = up), linetype = 2, alpha = 0.2) + + geom_line(aes(t, .fitted), col="blue") + + facet_wrap(~.rownames) + + xlab("Time Step") + + ylab("Count") + + +################################################### +### code chunk number 37: Cs26_set-up-covar +################################################### +temp <- t(plankdat[years, "Temp", drop = FALSE]) +TP <- t(plankdat[years, "TP", drop = FALSE]) + + +################################################### +### code chunk number 38: Cs27_fit_covar_echo +################################################### +model.list <- list(m = 2, R = "unconstrained") +kemz.temp <- MARSS(dat.spp.1980, + model = model.list, z.score = TRUE, + form = "dfa", control = cntl.list, covariates = temp +) +kemz.TP <- MARSS(dat.spp.1980, + model = model.list, z.score = TRUE, + form = "dfa", control = cntl.list, covariates = TP +) +kemz.both <- MARSS(dat.spp.1980, + model = model.list, z.score = TRUE, + form = "dfa", control = cntl.list, covariates = rbind(temp, TP) +) + + +################################################### +### code chunk number 41: Cs28_covar_AICs +################################################### +print(cbind( + model = c("no covars", "Temp", "TP", "Temp & TP"), + AICc = round(c( + the.fit$AICc, kemz.temp$AICc, kemz.TP$AICc, + kemz.both$AICc + )) +), quote = FALSE) + + +################################################### +### code chunk number 42: Cs29_plotbestcovarfits +################################################### +par.mat <- coef(kemz.temp, type = "matrix") +fit.b <- par.mat$Z %*% kemz.temp$states + matrix(par.mat$A, nrow = N.ts, ncol = TT) +spp <- rownames(dat.z) +par(mfcol = c(3, 2), mar = c(3, 4, 1.5, 0.5), oma = c(0.4, 1, 1, 1)) +for (i in 1:length(spp)) { + plot(dat.z[i, ], xlab = "", ylab = "Abundance index", bty = "L", xaxt = "n", ylim = c(-4, 3), pch = 16, col = "blue") + axis(1, 12 * (0:dim(dat.z)[2]) + 1, 1980 + 0:dim(dat.z)[2]) + lines(fit.b[i, ], lwd = 2) + title(spp[i]) +} + + diff --git a/inst/doc/Chapter_KFAS.R b/inst/doc/Chapter_KFAS.R new file mode 100644 index 0000000..6b8b084 --- /dev/null +++ b/inst/doc/Chapter_KFAS.R @@ -0,0 +1,897 @@ +################################################### +### code chunk number 2: Cs00_required-libraries +################################################### +library(MARSS) +library(KFAS) +library(ggplot2) # plotting +library(tidyr) # data frame manipulation + + +################################################### +### code chunk number 3: Cs101_fitting-models +################################################### +model_Nile <- SSModel(Nile ~ SSMtrend( + degree = 1, + Q = list(matrix(NA)) +), +H = matrix(NA) +) +kinits <- c(log(var(Nile)), log(var(Nile))) +fit_kfas_default <- fitSSM(model_Nile, kinits, method = "BFGS") + + +################################################### +### code chunk number 4: Cs102_fitting-models +################################################### +model_Nile_stoch <- model_Nile +model_Nile_stoch$a1[1, 1] <- 0 +model_Nile_stoch$P1[1, 1] <- 1000 +model_Nile_stoch$P1inf[1, 1] <- 0 +kinits <- c(log(var(Nile)), log(var(Nile))) +fit_kfas_stoch <- fitSSM(model_Nile_stoch, kinits, method = "BFGS") +kfs_kfas_stoch <- KFS(fit_kfas_stoch$model) + + +################################################### +### code chunk number 5: Cs103_fitting-models +################################################### +mod.nile <- list( + Z = matrix(1), A = matrix(0), R = matrix("r"), + B = matrix(1), U = matrix(0), Q = matrix("q"), + tinitx = 1 +) + + +################################################### +### code chunk number 6: Cs104_fitting-models +################################################### +dat <- t(as.matrix(Nile)) +rownames(dat) <- "Nile" +fit_em_default <- MARSS(dat, model = mod.nile, silent = TRUE) +inits <- list(Q = matrix(var(Nile)), R = matrix(var(Nile))) +fit_bfgs_default <- MARSS(dat, + model = mod.nile, inits = inits, + method = "BFGS", silent = TRUE +) + + +################################################### +### code chunk number 7: Cs105_fitting-models +################################################### +mod.nile.stoch <- mod.nile +mod.nile.stoch$x0 <- fit_kfas_stoch$model$a1 +mod.nile.stoch$V0 <- fit_kfas_stoch$model$P1 +fit_em_stoch <- MARSS(dat, model = mod.nile.stoch, silent = TRUE) +fit_bfgs_stoch <- MARSS(dat, + model = mod.nile.stoch, inits = inits, + method = "BFGS", silent = TRUE +) + + +################################################### +### code chunk number 8: Cs106_fitting-models +################################################### +marss_kfas_model <- MARSSkfas(fit_em_stoch, + return.kfas.model = TRUE, + return.lag.one = FALSE +)$kfas.model +marss_kfas_model$Q[1, 1, 1] <- NA +marss_kfas_model$H[1, 1, 1] <- NA +kinits <- c(log(var(Nile)), log(var(Nile))) +fit_marss_kfas <- fitSSM(marss_kfas_model, kinits, method = "BFGS") + + +################################################### +### code chunk number 9: Cs107_fitting-models +################################################### +vals <- rbind( + c(fit_kfas_default$model$Q, fit_kfas_default$model$H, -1 * fit_kfas_default$optim.out$value), + c(coef(fit_em_default)$Q, coef(fit_em_default)$R, logLik(fit_em_default)), + c(coef(fit_bfgs_default)$Q, coef(fit_bfgs_default)$R, logLik(fit_bfgs_default)), + c(fit_kfas_stoch$model$Q, fit_kfas_stoch$model$H, -1 * fit_kfas_stoch$optim.out$value), + c(coef(fit_em_stoch)$Q, coef(fit_em_stoch)$R, logLik(fit_em_stoch)), + c(coef(fit_bfgs_stoch)$Q, coef(fit_bfgs_stoch)$R, logLik(fit_bfgs_stoch)), + c(fit_marss_kfas$model$Q, fit_marss_kfas$model$H, -1 * fit_marss_kfas$optim.out$value) +) +rownames(vals) <- c( + "KFAS default", "MARSS em default", "MARSS bfgs default", + "KFAS stoch", "MARSS em stoch", "MARSS bfgs stoch", "KFAS w marss kfas model" +) +colnames(vals) <- c("Q", "R", "logLik") +vals + + +################################################### +### code chunk number 10: Cs201_state-filtering +################################################### +fit_kfas <- fit_kfas_stoch +fit_marss <- fit_em_stoch +fit_marss$par$Q[1, 1] <- fit_kfas$model$Q +fit_marss$par$R[1, 1] <- fit_kfas$model$H + + +################################################### +### code chunk number 11: Cs202_state-filtering +################################################### +kf_kfas <- KFS(fit_kfas$model, + filtering = "state", + smoothing = "state", simplify = FALSE +) + + +################################################### +### code chunk number 12: Cs203_state-filtering +################################################### +kf_marss <- MARSSkfss(fit_marss) + + +################################################### +### code chunk number 13: Cs204_state-filtering +################################################### +names(kf_kfas) +names(kf_marss) + + +################################################### +### code chunk number 14: Cs205_state-filtering +################################################### +n <- 5 + + +################################################### +### code chunk number 15: Cs206_state-filtering +################################################### +cbind( + a = kf_kfas$a[1:n], xtt1 = kf_marss$xtt1[1:n], + att = kf_kfas$att[1:n], xtt = kf_marss$xtt[1:n] +) + + +################################################### +### code chunk number 16: Cs207_state-filtering +################################################### +cbind(kf_kfas$alphahat[1:n], kf_marss$xtT[1:n]) + + +################################################### +### code chunk number 17: Cs208_state-filtering +################################################### +cbind( + v = kf_kfas$v[1:n], Innov = kf_marss$Innov[1:n], + F = kf_kfas$F[1:n], Sigma = kf_marss$Sigma[1:n] +) + + +################################################### +### code chunk number 18: Cs209_state-filtering +################################################### +cbind( + P = kf_kfas$P[1:n], Vtt1 = kf_marss$Vtt1[1:n], + Ptt = kf_kfas$Ptt[1:n], Vtt = kf_marss$Vtt[1:n] +) + + +################################################### +### code chunk number 19: Cs301_obs-filtering +################################################### +kf_kfas <- KFS(fit_kfas$model, + filtering = "signal", + smoothing = "signal", simplify = FALSE +) + + +################################################### +### code chunk number 20: Cs302_obs-filtering +################################################### +kf_marss <- MARSSkf(fit_marss) + + +################################################### +### code chunk number 21: Cs304_obs-filtering +################################################### +n <- 10 + + +################################################### +### code chunk number 22: Cs305_obs-filtering +################################################### +ytt1_fit <- fitted(fit_marss, type = "ytt1")$.fitted +ytt1_hatyt <- MARSShatyt(fit_marss, only.kem = FALSE)$ytt1 +cbind(m = kf_kfas$m[1:n], + fitted = ytt1_fit[1:n], + MARSShatyt = ytt1_hatyt[1:n]) + + +################################################### +### code chunk number 23: Cs306_obs-filtering +################################################### +var.Eytt1_fit <- + fitted(fit_marss, type = "ytt1", interval = "confidence")$.se^2 +var.Eytt1_hatyt <- + MARSShatyt(fit_marss, only.kem = FALSE)$var.Eytt1 +cbind( + P_mu = kf_kfas$P_mu[1:n], fitted = var.Eytt1_fit[1:n], + MARSShatyt = var.Eytt1_hatyt[1:n] +) + + +################################################### +### code chunk number 24: Cs307_obs-filtering +################################################### +ytT_fit <- fitted(fit_marss, type = "ytT")$.fitted +ytT_hatyt <- MARSShatyt(fit_marss)$ytT +cbind( + a = kf_kfas$muhat[1:n], fitted = ytT_fit[1:n], + MARSShatyt = ytT_hatyt[1:n], Nile = Nile[1:n] +) + + +################################################### +### code chunk number 25: Cs308_obs-filtering +################################################### +var.EytT_fit <- + fitted(fit_marss, type = "ytT", interval = "confidence")$.se^2 +var.EytT_hatyt <- + MARSShatyt(fit_marss, only.kem = FALSE)$var.EytT +cbind( + V_mu = kf_kfas$V_mu[1:n], fitted = var.EytT_fit[1:n], + MARSShatyt = var.EytT_hatyt[1:n] +) + + +################################################### +### code chunk number 26: Cs401_conf-int +################################################### +conf_kfas <- predict(fit_kfas$model, + interval = "confidence", + se.fit = TRUE +) +head(conf_kfas) + + +################################################### +### code chunk number 27: Cs402_conf-int +################################################### +conf_marss1 <- fitted(fit_marss, type = "ytT", interval = "confidence") +head(conf_marss1) + + +################################################### +### code chunk number 28: Cs403_conf-int +################################################### +conf_marss2 <- predict(fit_marss, + type = "ytT", + interval = "confidence", level = 0.95 +) +head(conf_marss2$pred) + + +################################################### +### code chunk number 29: Cs404_conf-int +################################################### +pred_kfas <- predict(fit_kfas$model, + interval = "prediction", se.fit = TRUE +) +head(pred_kfas) + + +################################################### +### code chunk number 30: Cs405_conf-int +################################################### +pred_marss1 <- fitted(fit_marss, type = "ytT", interval = "prediction") +head(pred_marss1) + + +################################################### +### code chunk number 31: Cs406_conf-int +################################################### +pred_marss2 <- predict(fit_marss, + type = "ytT", + interval = "prediction", level = 0.95 +) + + +################################################### +### code chunk number 32: Cs407_conf-int +################################################### +conf_kfas_t1 <- predict(fit_kfas$model, + interval = "confidence", + se.fit = TRUE, filtered = TRUE +) +head(conf_kfas_t1) + + +################################################### +### code chunk number 33: Cs408_conf-int +################################################### +conf_marss1_t1 <- fitted(fit_marss, type = "ytt1", interval = "confidence") +head(conf_marss1_t1) + + +################################################### +### code chunk number 34: Cs409_conf-int +################################################### +conf_marss2_t1 <- predict(fit_marss, + type = "ytt1", + interval = "confidence", level = 0.95 +) +head(conf_marss2_t1$pred) + + +################################################### +### code chunk number 35: Cs410_conf-int +################################################### +pred_kfas_t1 <- predict(fit_kfas$model, + interval = "prediction", + se.fit = TRUE, filtered = TRUE +) +head(pred_kfas_t1) + + +################################################### +### code chunk number 36: Cs411_conf-int +################################################### +pred_marss1_t1 <- fitted(fit_marss, type = "ytt1", interval = "prediction") +head(pred_marss1_t1) + + +################################################### +### code chunk number 37: Cs412_conf-int +################################################### +pred_marss2_t1 <- predict(fit_marss, + type = "ytt1", + interval = "prediction", level = 0.95 +) + + +################################################### +### code chunk number 49: Cs501_plotting +################################################### +ts.plot(cbind(Nile, pred_kfas[, c("fit", "lwr", "upr")], conf_kfas[, c("lwr", "upr")]), + col = c(1:2, 3, 3, 4, 4), + ylab = "Predicted annual flow", main = "River Nile" +) + + +################################################### +### code chunk number 38: Cs501_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- residuals(kfs, type = "recursive") +resid_marss <- residuals(fit_marss, + type = "tt1", + standardization = "marginal" +) +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 50: Cs502_plotting +################################################### +plot.type <- ifelse(packageVersion("MARSS") < '3.11.4', "model.ytT", "fitted.ytT") +plot(fit_marss, plot.type = plot.type, pi.int = TRUE) + + +################################################### +### code chunk number 39: Cs502_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- rstandard(kfs, + type = "recursive", + standardization_type = "marginal" +) +resid_marss <- residuals(fit_marss, + type = "tt1", + standardization = "marginal" +) +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 51: Cs503_plotting +################################################### +require(ggplot2) +df <- cbind(conf_marss1, pred_marss1[, c(".lwr", ".upr")]) +ggplot(df, aes(x = t, y = .fitted)) + + geom_ribbon(aes(ymin = .lwr, ymax = .upr), fill = "grey") + + geom_ribbon(aes(ymin = .conf.low, ymax = .conf.up), fill = "blue", alpha = 0.25) + + geom_line(linetype = 2) + + ylab("Predicted Annual Flow") + + xlab("") + + ggtitle("River Nile") + + +################################################### +### code chunk number 40: Cs503_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- rstandard(kfs, + type = "recursive", + standardization_type = "cholesky" +) +resid_marss <- residuals(fit_marss, + type = "tt1", + standardization = "Cholesky" +) +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 41: Cs504_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- residuals(kfs, type = "pearson") +resid_marss <- residuals(fit_marss, type = "tT") +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 42: Cs505_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- rstandard(kfs, + type = "pearson", + standardization_type = "marginal" +) +resid_marss <- residuals(fit_marss, + type = "tT", + standardization = "marginal" +) +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 43: Cs506_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- rstandard(kfs, + type = "pearson", + standardization_type = "cholesky" +) +resid_marss <- residuals(fit_marss, + type = "tT", + standardization = "Cholesky" +) +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 44: Cs507_residuals +################################################### +kfs <- KFS(fit_kfas$model) +resid_kfas <- residuals(kfs, type = "response") +resid_marss <- residuals(fit_marss, type = "tT") +resid_marss <- subset(resid_marss, name == "model") +df <- cbind( + MARSS = resid_marss$.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 45: Cs508_residuals +################################################### +kfs <- KFS(fit_kfas$model, smoothing = "disturbance") +resid_kfas <- residuals(kfs, type = "state") +resid_marss <- residuals(fit_marss, type = "tT") +resid_marss <- subset(resid_marss, name == "state") +df <- cbind( + MARSS = resid_marss$.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 46: Cs509_residuals +################################################### +kfs <- KFS(fit_kfas$model, smoothing = "disturbance") +resid_kfas <- rstandard(kfs, + type = "state", + standardization_type = "marginal" +) +resid_marss <- residuals(fit_marss, + type = "tT", + standardization = "marginal" +) +resid_marss <- subset(resid_marss, name == "state") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 47: Cs509_residuals +################################################### +kfs <- KFS(fit_kfas$model, smoothing = "disturbance") +resid_kfas <- rstandard(kfs, + type = "state", + standardization_type = "cholesky" +) +resid_marss <- residuals(fit_marss, + type = "tT", + standardization = "Block.Cholesky" +) +resid_marss <- subset(resid_marss, name == "state") +df <- cbind( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas) +) +head(df) + + +################################################### +### code chunk number 48: Cs510_residuals +################################################### +kfs <- KFS(fit_kfas$model, smoothing = "disturbance") +test <- cbind( + b = fit_kfas$model$Q[1, 1, 1] - kfs$V_eta[1, 1, ], + a = MARSSresiduals(fit_marss, type = "tT")$var.residuals[2, 2, ] +) +test <- as.data.frame(test) +test$diff <- test$b - test$a +head(test) +tail(test) + + +################################################### +### code chunk number 52: Cs601_missing-values +################################################### +NileNA <- Nile +NileNA[c(21:40, 61:80)] <- NA +model_NileNA_stoch <- + SSModel(NileNA ~ SSMtrend( + degree = 1, + Q = list(matrix(NA)) + ), + H = matrix(NA) + ) +model_NileNA_stoch$a1[1, 1] <- 0 +model_NileNA_stoch$P1[1, 1] <- model_Nile_stoch$P1[1, 1] +model_NileNA_stoch$P1inf[1, 1] <- 0 +kinits <- c(log(var(Nile)), log(var(Nile))) +fit_kfas_NA <- fitSSM(model_NileNA_stoch, kinits, method = "BFGS") +fit_marss_NA <- MARSS(as.vector(NileNA), + model = mod.nile.stoch, + inits = inits, method = "BFGS", silent = TRUE +) + + +################################################### +### code chunk number 53: Cs602_missing-values +################################################### +rbind( + MARSS = c( + Q = coef(fit_marss_NA, type = "matrix")$Q, + R = coef(fit_marss_NA, type = "matrix")$R, + logLik = logLik(fit_marss_NA) + ), + KFAS = c( + Q = fit_kfas_NA$model$Q, + R = fit_kfas_NA$model$H, + logLik = -1 * fit_kfas_NA$optim.out$value + ) +) + + +################################################### +### code chunk number 55: Cs603_missing-values +################################################### +conf_kfas_NA <- + predict(fit_kfas_NA$model, interval = "confidence", filtered = FALSE) +conf_marss_NA <- + predict(fit_marss_NA, interval = "confidence", type = "ytT", level = 0.95)$pred + + +################################################### +### code chunk number 56: Cs604_marss-mult-fig-2 +################################################### +require(ggplot2) +df1 <- as.data.frame(conf_kfas_NA) +df1$name <- "KFAS" +df2 <- conf_marss_NA[, c("estimate", "Lo 95", "Hi 95")] +df2$name <- "MARSS" +colnames(df2) <- colnames(df1) +df <- rbind(df1, df2) +df$t <- as.vector(time(NileNA)) +df$y <- conf_marss_NA$y +ggplot(df, aes(x = t, y = fit)) + + geom_ribbon(aes(ymin = lwr, ymax = upr), fill = "grey") + + geom_line() + + ylab("Predicted Annual Flow") + + xlab("") + + ggtitle("River Nile with 95% CIs on estimate") + + facet_wrap(~name) + + +################################################### +### code chunk number 57: Cs605_missing-values +################################################### +fitted_kfas_NA <- data.frame( + smooth = as.vector(fitted(fit_kfas_NA$model)), + one.step.ahead = as.vector(fitted(fit_kfas_NA$model, filtered = TRUE)), + name = "KFAS" +) +fitted_marss_NA <- data.frame( + smooth = fitted(fit_marss_NA, type = "ytT")$.fitted, + one.step.ahead = fitted(fit_marss_NA, type = "ytt1")$.fitted, + name = "MARSS" +) + + +################################################### +### code chunk number 58: Cs606_missing-values +################################################### +require(ggplot2) +require(tidyr) +df <- rbind(fitted_kfas_NA, fitted_marss_NA) +df$t <- as.vector(time(NileNA)) +df$y <- conf_marss_NA$y +df <- tidyr::pivot_longer(df, c(smooth, one.step.ahead), names_to = "type", values_to = "value") +ggplot(df, aes(x = t, y = value, col = type)) + + geom_point(aes(x = t, y = y), col = "blue", size = 0.5, na.rm = TRUE) + + geom_line() + + ylab("Predicted Annual Flow") + + xlab("") + + ggtitle("River Nile - smoothed versus filtered") + + facet_wrap(~name, ncol = 1) + + +################################################### +### code chunk number 59: Cs701_globaltemp +################################################### +data("GlobalTemp") +ts.plot(GlobalTemp, col = 1:2, main = "Two ts for Global Temperature") + + +################################################### +### code chunk number 60: Cs702_globaltemp +################################################### +data("GlobalTemp") +model_temp <- SSModel(GlobalTemp ~ SSMtrend(1, Q = NA, type = "common"), + H = matrix(NA, 2, 2) +) +kinits <- chol(cov(GlobalTemp))[c(1, 4, 3)] +kinits <- c(0.5 * log(0.1), log(kinits[1:2]), kinits[3]) +kfas_temp_default <- fitSSM(model_temp, kinits, method = "BFGS") +model_temp_stoch <- model_temp +model_temp_stoch$a1[1, 1] <- 0 +model_temp_stoch$P1[1, 1] <- 1000 * max(diag(var(GlobalTemp))) +model_temp_stoch$P1inf[1, 1] <- 0 +kfas_temp_stoch <- fitSSM(model_temp_stoch, kinits, method = "BFGS") + + +################################################### +### code chunk number 61: Cs703_globaltemp +################################################### +mod.list <- list( + Z = matrix(1, 2, 1), + R = matrix(c("r1", "c", "c", "r2"), 2, 2), + U = matrix(0), + A = matrix(0, 2, 1), + tinitx = 1 +) +marss_temp_default <- MARSS(t(GlobalTemp), model = mod.list) +mod.list$x0 <- kfas_temp_stoch$model$a1 +mod.list$V0 <- kfas_temp_stoch$model$P1 +marss_temp_stoch_em <- MARSS(t(GlobalTemp), model = mod.list) +# use inits from a short run of EM algorithm +inits <- MARSS(t(GlobalTemp), + model = mod.list, control = list(maxit = 20), + silent = TRUE +) +marss_temp_stoch_bfgs <- MARSS(t(GlobalTemp), + model = mod.list, + inits = inits, method = "BFGS" +) + + +################################################### +### code chunk number 62: Cs704_globaltemp +################################################### +vals <- rbind( + c(kfas_temp_default$model$Q, kfas_temp_default$model$H[c(1, 2, 4)], -1 * kfas_temp_default$optim.out$value), + c(coef(marss_temp_default)$Q, coef(marss_temp_default)$R, logLik(marss_temp_default)), + c(kfas_temp_stoch$model$Q, kfas_temp_stoch$model$H[c(1, 2, 4)], -1 * kfas_temp_stoch$optim.out$value), + c(coef(marss_temp_stoch_em)$Q, coef(marss_temp_stoch_em)$R, logLik(marss_temp_stoch_em)), + c(coef(marss_temp_stoch_bfgs)$Q, coef(marss_temp_stoch_bfgs)$R, logLik(marss_temp_stoch_bfgs)) +) +rownames(vals) <- c( + "KFAS default", "MARSS em default", + "KFAS stoch", "MARSS em stoch", "MARSS bfgs stoch" +) +colnames(vals) <- c("Q", "R1", "Rcov", "R2", "logLik") +round(vals, digits = 5) + + +################################################### +### code chunk number 63: Cs705_globaltemp +################################################### +out_temp <- KFS(kfas_temp_stoch$model) +df <- data.frame( + t = as.vector(time(coef(out_temp))), + KFAS = coef(out_temp), + `MARSS BFGS` = tsSmooth(marss_temp_stoch_bfgs, type = "xtT")$.estimate, + `MARSS EM` = tsSmooth(marss_temp_stoch_bfgs, type = "xtT")$.estimate +) +df <- pivot_longer(df, c(KFAS, MARSS.BFGS, MARSS.EM), names_to = "model", values_to = "value") +ggplot(df, aes(x = t, y = value)) + + geom_line() + + facet_wrap(~model) + + +################################################### +### code chunk number 64: Cs706_globaltemp +################################################### +mod.list <- list( + Z = matrix(kfas_temp_stoch$model$Z, ncol = 1), + R = kfas_temp_stoch$model$H[, , 1], + U = matrix(0), + A = matrix(0, 2, 1), + Q = matrix(kfas_temp_stoch$model$Q[, , 1]), + x0 = kfas_temp_stoch$model$a1, + V0 = kfas_temp_stoch$model$P1, + tinitx = 1 +) +marss_test <- MARSS(t(GlobalTemp), model = mod.list) + + +################################################### +### code chunk number 65: Cs707_globaltemp +################################################### +kfs <- KFS(kfas_temp_stoch$model, smoothing = "disturbance") +resid_kfas <- rstandard(kfs, + type = "state", + standardization_type = "cholesky" +) +resid_marss <- residuals(marss_temp_stoch_bfgs, + type = "tT", + standardization = "Block.Cholesky" +) +resid_marss <- subset(resid_marss, name == "state") +resid_test <- residuals(marss_test, + type = "tT", + standardization = "Block.Cholesky" +) +resid_test <- subset(resid_test, name == "state") + +df <- data.frame( + MARSS = resid_marss$.std.resids, + KFAS = as.vector(resid_kfas), + MARSS.test = resid_test$.std.resids +) +df$diff.est <- df$MARSS - df$KFAS +df$diff.id <- df$MARSS.test - df$KFAS +df$t <- as.vector(time(kfas_temp_stoch$model$y)) +df$name <- "state" +df1 <- pivot_longer(df, c(MARSS, MARSS.test, KFAS, diff.est, diff.id), names_to = "model", values_to = "value") + +kfs <- KFS(kfas_temp_stoch$model) +resid_kfas <- residuals(kfs, type = "pearson") +resid_marss <- MARSSresiduals(marss_temp_stoch_bfgs, type = "tT") +resid_test <- MARSSresiduals(marss_test, type = "tT") +df <- rbind( + cbind(as.data.frame(t(resid_marss$model.residuals)), model = "MARSS") %>% pivot_longer(c("HL", "Folland")), + cbind(as.data.frame(t(resid_test$model.residuals)), model = "MARSS.test") %>% pivot_longer(c("HL", "Folland")), + cbind(as.data.frame(resid_kfas), model = "KFAS") %>% pivot_longer(c("HL", "Folland")), + cbind(as.data.frame(t(resid_marss$model.residuals) - resid_kfas), model = "diff.est") %>% pivot_longer(c("HL", "Folland")), + cbind(as.data.frame(t(resid_test$model.residuals) - resid_kfas), model = "diff.id") %>% pivot_longer(c("HL", "Folland")) +) +df$t <- rep(as.vector(time(kfas_temp_stoch$model$y)), 2 * 5) + +df <- rbind(df, df1[, colnames(df)]) + +ggplot(subset(df, model %in% c("diff.est", "diff.id")), aes(x = t, y = value, col = model)) + + geom_line(na.rm = TRUE) + + facet_wrap(~name) + + xlab("") + + ggtitle("Difference in residuals KFAS vs MARSS") + + +################################################### +### code chunk number 66: Cs708_globaltemp (eval = FALSE) +################################################### +## # test; these should be identical +## kfas_test <- kfas_temp_stoch +## mod.list <- list( +## Z = matrix(1, 2, 1), +## R = kfas_test$model$H[, , 1], +## U = matrix(0), +## A = matrix(0, 2, 1), +## Q = matrix(kfas_test$model$Q[, , 1]), +## tinitx = 1 +## ) +## mod.list$x0 <- matrix(0) +## mod.list$V0 <- kfas_test$model$P1 +## marss_test <- MARSS(t(GlobalTemp), model = mod.list) +## kfas_test_mod <- MARSSkfas(marss_test, +## return.kfas.model = TRUE, +## return.lag.one = FALSE +## )$kfas.model +## +## kfs <- KFS(kfas_test_mod, smoothing = "disturbance") +## test <- cbind(b = kfas_test_mod$Q[1, 1, 1] - kfs$V_eta[1, 1, ], a = MARSSresiduals(marss_test, type = "tT")$var.residuals[3, 3, ]) +## test <- as.data.frame(test) +## test$diff <- test$b - test$a +## head(test) +## tail(test) +## +## MARSSkfas(marss_test)$VtT[, , 1] +## MARSSkfss(marss_test)$VtT[, , 1] +## +## +## var.EytT_fit <- +## fitted(marss_test, type = "ytT", interval = "confidence")$.se^2 +## cbind(V_mu = KFS(kfas_test$model)$V_mu[1, 1, ], fitted = var.EytT_fit) +## +## kfs <- KFS(kfas_test_mod, smoothing = "disturbance") +## resid_kfas <- rstandard(kfs, +## type = "state", +## standardization_type = "marginal" +## ) +## resid_marss <- residuals(marss_test, +## type = "tT", +## standardization = "marginal" +## ) +## resid_marss <- subset(resid_marss, name == "state") +## df <- data.frame( +## MARSS = resid_marss$.std.resids, +## KFAS = as.vector(resid_kfas), +## diff = resid_marss$.std.resids - as.vector(resid_kfas) +## ) +## head(df) +## +## resid_kfas <- residuals(kfs, type = "state") +## resid_marss <- residuals(marss_test, type = "tT") +## resid_marss <- subset(resid_marss, name == "state") +## df <- cbind( +## MARSS = resid_marss$.resids, +## KFAS = as.vector(resid_kfas), +## diff = resid_marss$.resids - as.vector(resid_kfas) +## ) +## head(df) +## +## +## kfs <- KFS(kfas_temp_stoch$model) +## resid_kfas <- residuals(kfs, type = "pearson") +## resid_marss <- MARSSresiduals(marss_test, type = "tT") +## df <- cbind( +## as.data.frame(t(resid_marss$model.residuals)), +## as.data.frame(resid_kfas), +## as.data.frame(t(resid_marss$model.residuals) - resid_kfas) +## ) + + diff --git a/inst/doc/Chapter_MARp.R b/inst/doc/Chapter_MARp.R new file mode 100644 index 0000000..19eea54 --- /dev/null +++ b/inst/doc/Chapter_MARp.R @@ -0,0 +1,357 @@ +################################################### +### code chunk number 2: Cs_000_required_libraries +################################################### +library(MARSS) + + +################################################### +### code chunk number 4: Cs_101_ar2-sim +################################################### +TT <- 50 +true.2 <- c(r = 0, b1 = -1.5, b2 = -0.75, q = 1) +temp <- arima.sim(n = TT, list(ar = true.2[2:3]), sd = sqrt(true.2[4])) +sim.ar2 <- matrix(temp, nrow = 1) + + +################################################### +### code chunk number 5: Cs_102_ar2-model +################################################### +Z <- matrix(c(1, 0), 1, 2) +B <- matrix(list("b1", 1, "b2", 0), 2, 2) +U <- matrix(0, 2, 1) +Q <- matrix(list("q", 0, 0, 0), 2, 2) +A <- matrix(0, 1, 1) +R <- matrix(0, 1, 1) +mu <- matrix(sim.ar2[2:1], 2, 1) +V <- matrix(0, 2, 2) +model.list.2 <- list( + Z = Z, B = B, U = U, Q = Q, A = A, + R = R, x0 = mu, V0 = V, tinitx = 0 +) + + +################################################### +### code chunk number 6: Cs_103_ar2-fit +################################################### +ar2 <- MARSS(sim.ar2[3:TT], model = model.list.2) + + +################################################### +### code chunk number 7: Cs_104_ar2-fit +################################################### +print(cbind(true = true.2[2:4], estimates = coef(ar2, type = "vector"))) + + +################################################### +### code chunk number 8: Cs_105_ar2-gappy +################################################### +gappy.data <- sim.ar2[3:TT] +gappy.data[floor(runif(TT / 2, 2, TT))] <- NA +ar2.gappy <- MARSS(gappy.data, model = model.list.2, fun.kf="MARSSkfss") + + +################################################### +### code chunk number 9: Cs_106_ar2-gappy +################################################### +print(cbind( + true = true.2[2:4], + estimates.no.miss = coef(ar2, type = "vector"), + estimates.w.miss = coef(ar2.gappy, type = "vector") +)) + + +################################################### +### code chunk number 10: Cs_107_arima +################################################### +arima(gappy.data, order = c(2, 0, 0), include.mean = FALSE) + + +################################################### +### code chunk number 11: Cs_108_non-stationary +################################################### +TT <- 50 +true.2 <- c(r = 0, b1 = -1.5, b2 = -0.75, q = 1) +sim.ar2.ns <- rep(NA, TT) +sim.ar2.ns[1] <- -30 +sim.ar2.ns[2] <- -10 +for (i in 3:TT) { + sim.ar2.ns[i] <- true.2[2] * sim.ar2.ns[i - 1] + + true.2[3] * sim.ar2.ns[i - 2] + rnorm(1, 0, sqrt(true.2[4])) +} + +model.list.3 <- model.list.2 +model.list.3$x0 <- matrix(sim.ar2.ns[2:1], 2, 1) + +ar3.marss <- MARSS(sim.ar2.ns[3:TT], model = model.list.3, silent = TRUE) +ar3.arima <- arima(sim.ar2.ns[3:TT], order = c(2, 0, 0), include.mean = FALSE) + +print(cbind( + true = true.2[2:4], + estimates.marss = coef(ar3.marss, type = "vector"), + estimates.arima = c(coef(ar3.arima, type = "vector"), ar3.arima$sigma2) +)) + + +################################################### +### code chunk number 13: Cs_201_mar2-sim +################################################### +TT <- 50 +true.2 <- c(r = 0, b1 = -1.5, b2 = -0.75, q = 1) +temp1 <- arima.sim(n = TT, list(ar = true.2[c("b1", "b2")]), + sd = sqrt(true.2["q"])) + + +################################################### +### code chunk number 15: Cs_202_mar2-sim +################################################### +temp2 <- arima.sim(n = TT, list(ar = true.2[c("b1", "b2")]), + sd = sqrt(true.2["q"])) +sim.mar2 <- rbind(temp1, temp2) + + +################################################### +### code chunk number 16: Cs_203_mar2-model +################################################### +Z <- matrix(c(1, 0, 0, 1, 0, 0, 0, 0), 2, 4) +B1 <- matrix(list(0), 2, 2) +diag(B1) <- "b1" +B2 <- matrix(list(0), 2, 2) +diag(B2) <- "b2" +B <- matrix(list(0), 4, 4) +B[1:2, 1:2] <- B1 +B[1:2, 3:4] <- B2 +B[3:4, 1:2] <- diag(1, 2) +U <- matrix(0, 4, 1) +Q <- matrix(list(0), 4, 4) +Q[1, 1] <- "q" +Q[2, 2] <- "q" +A <- matrix(0, 2, 1) +R <- matrix(0, 2, 2) +pi <- matrix(c(sim.mar2[, 2], sim.mar2[, 1]), 4, 1) +V <- matrix(0, 4, 4) +model.list.2m <- list( + Z = Z, B = B, U = U, Q = Q, A = A, + R = R, x0 = pi, V0 = V, tinitx = 1 +) + + +################################################### +### code chunk number 19: Cs_204_mar2-fit +################################################### +mar2 <- MARSS(sim.mar2[, 2:TT], model = model.list.2m) + + +################################################### +### code chunk number 20: Cs_205_mar2-compare +################################################### +model.list.2$x0 <- matrix(sim.mar2[1, 2:1], 2, 1) +mar2a <- MARSS(sim.mar2[1, 2:TT], model = model.list.2) +model.list.2$x0 <- matrix(sim.mar2[2, 2:1], 2, 1) +mar2b <- MARSS(sim.mar2[2, 2:TT], model = model.list.2) + + +################################################### +### code chunk number 21: Cs_206_compare-mars +################################################### +print(cbind(true = true.2[2:4], est.mar2 = coef(mar2, type = "vector"), est.mar2a = coef(mar2a, type = "vector"), est.mar2b = coef(mar2b, type = "vector"))) + + +################################################### +### code chunk number 23: Cs_301_sim-ar3-data +################################################### +TT <- 100 +true.3 <- c(r = 0, b1 = -1.5, b2 = -0.75, b3 = .05, q = 1) +temp3 <- arima.sim( + n = TT, list(ar = true.3[c("b1", "b2", "b3")]), + sd = sqrt(true.3["q"]) +) +sim.ar3 <- matrix(temp3, nrow = 1) + + +################################################### +### code chunk number 24: Cs_302_set-up-ar3-model +################################################### +Z <- matrix(c(1, 0, 0), 1, 3) +B <- matrix(list("b1", 1, 0, "b2", 0, 1, "b3", 0, 0), 3, 3) +U <- matrix(0, 3, 1) +Q <- matrix(list(0), 3, 3) +Q[1, 1] <- "q" +A <- matrix(0, 1, 1) +R <- matrix(0, 1, 1) +pi <- matrix(sim.ar3[3:1], 3, 1) +V <- matrix(0, 3, 3) +model.list.3 <- list( + Z = Z, B = B, U = U, Q = Q, A = A, + R = R, x0 = pi, V0 = V, tinitx = 1 +) + + +################################################### +### code chunk number 25: Cs_303_fit-ar3 +################################################### +ar3 <- MARSS(sim.ar3[3:TT], model = model.list.3) + + +################################################### +### code chunk number 26: Cs_304_fit-ar3 +################################################### +print(cbind( + true = true.3[c("b1", "b2", "b3", "q")], + estimates.no.miss = coef(ar3, type = "vector") +)) + + +################################################### +### code chunk number 27: Cs_401_setseed5 +################################################### +set.seed(14) + + +################################################### +### code chunk number 28: Cs_402_fig-arss-model +################################################### +TT <- 1000 # set long +true.2ss <- c(r = .5, b1 = -1.5, b2 = -0.75, q = .1) +temp <- arima.sim( + n = TT, list(ar = true.2ss[c("b1", "b2")]), + sd = sqrt(true.2ss["q"]) +) +sim.ar <- matrix(temp, nrow = 1) +noise <- rnorm(TT - 1, 0, sqrt(true.2ss["r"])) +noisy.data <- sim.ar[2:TT] + noise + + +################################################### +### code chunk number 29: Cs_403_fig-arss-model +################################################### +Z <- matrix(c(1, 0), 1, 2) +B <- matrix(list("b1", 1, "b2", 0), 2, 2) +U <- matrix(0, 2, 1) +Q <- matrix(list("q", 0, 0, 0), 2, 2) +A <- matrix(0, 1, 1) +R <- matrix("r") +V <- matrix(0, 2, 2) +pi <- matrix(mean(noisy.data), 2, 1) +model.list.2ss <- list( + Z = Z, B = B, U = U, Q = Q, A = A, + R = R, x0 = pi, V0 = V, tinitx = 0 +) + + +################################################### +### code chunk number 30: Cs_404_fig-arss-model +################################################### +ar2ss <- MARSS(noisy.data, model = model.list.2ss) + + +################################################### +### code chunk number 31: Cs_405_fit-arss2-model +################################################### +model.list.2ss.bad <- model.list.2ss +# set R to zero in this model +model.list.2ss.bad$R <- matrix(0) + + +################################################### +### code chunk number 32: Cs_406_fit-arss2-model +################################################### +ar2ss2 <- MARSS(noisy.data, model = model.list.2ss.bad) + + +################################################### +### code chunk number 33: Cs_407_fit-arss2-model +################################################### +print(cbind( + true = true.2ss, + model.no.error = c(NA, coef(ar2ss2, type = "vector")), + model.w.error = coef(ar2ss, type = "vector") +)) + + +################################################### +### code chunk number 34: Cs_408_fit-arss2-with-arima +################################################### +arima(noisy.data, order = c(2, 0, 2), include.mean = FALSE) + + +################################################### +### code chunk number 36: Cs_409_code-to-compare-arss-estimation +################################################### +# This is the code used to make the figure comparing different ways to estimate +# AR parameters from AR with noise data +# sims.exist is just a flag. Set to FALSE to run the code +if (!exists("sims.exist")) { + sims.exist <- FALSE +} +if (!sims.exist) { + nsim <- 200 + TT <- 100 + file <- paste("AR2SS", TT, ".RData", sep = "") + params <- matrix(0, 8, nsim) + # sim 2 true.2ss=c(r=.5,b1=0.8,b2=-0.2,q=.1) + # sim 1 + true.2ss <- c(r = .5, b1 = -1.5, b2 = -0.75, q = .1) + + Z <- matrix(c(1, 0), 1, 2) + B <- matrix(list("b1", 1, "b2", 0), 2, 2) + U <- matrix(0, 2, 1) + Q <- matrix(list("q", 0, 0, 0), 2, 2) + A <- matrix(0, 1, 1) + V <- matrix(0, 2, 2) + R <- matrix("r") + pi <- matrix(0, 2, 1) # since demeaned + model.list.2ss <- list( + Z = Z, B = B, U = U, Q = Q, A = A, + R = R, x0 = pi, V0 = V, tinitx = 1 + ) + + for (i in 1:nsim) { + temp <- arima.sim(n = TT, list(ar = true.2ss[2:3]), sd = sqrt(true.2ss[4])) + sim.ar <- matrix(temp, nrow = 1) + noise <- rnorm(TT, 0, sqrt(true.2ss[1])) + noisy.data <- sim.ar + noise + noisy.data <- as.vector(noisy.data - mean(noisy.data)) # demean + test.it <- try(arima(noisy.data[2:TT], order = c(2, 0, 2), include.mean = FALSE), silent = TRUE) + test.it2 <- try(arima(noisy.data[2:TT], order = c(2, 0, 0), include.mean = FALSE), silent = TRUE) + while (inherits(test.it, "try-error") | inherits(test.it2, "try-error")) { + temp <- arima.sim(n = TT, list(ar = true.2ss[2:3]), sd = sqrt(true.2ss[4])) + sim.ar <- matrix(temp, nrow = 1) + noise <- rnorm(TT, 0, sqrt(true.2ss[1])) + noisy.data <- sim.ar + noise + noisy.data <- as.vector(noisy.data - mean(noisy.data)) # demean + test.it <- try(arima(noisy.data[2:TT], order = c(2, 0, 2), include.mean = FALSE), silent = TRUE) + test.it2 <- try(arima(noisy.data[2:TT], order = c(2, 0, 0), include.mean = FALSE), silent = TRUE) + } + init.list <- list(Q = matrix(.01, 1, 1), B = matrix(1, 2, 1)) + tmp.kem <- MARSS(noisy.data[2:TT], model = model.list.2ss, inits = init.list, silent = TRUE) + params[1:2, i] <- coef(tmp.kem)$B + tmp.bfgs <- MARSS(noisy.data[2:TT], model = model.list.2ss, inits = init.list, silent = TRUE, method = "BFGS") + # if(any(is.na(tmp.bfgs$states.se)) | any(is.na(tmp.kem$states.se))) print(i) + params[3:4, i] <- coef(tmp.bfgs)$B + params[5:6, i] <- test.it$coef[1:2] + params[7:8, i] <- test.it2$coef[1:2] + cat(i) + cat("\n") + if ((i %% 25) == 0) save(true.2ss, TT, params, file = file) + } + sims.exist <- TRUE + save(true.2ss, TT, params, file = file) +} + + +################################################### +### code chunk number 37: Cs_410_marssperffig +################################################### +if (sims.exist) { # flag to check that the code to creat the plot has been run + # This makes a plot of the comparisons + par(ylbias = -.2, tcl = -.2, cex = .75) + graphics::boxplot(t(params[c(7, 1, 3, 5, 8, 2, 4, 6), ]), names = c("AR(2)\n", "MARSS\nEM", "MARSS\nBFGS", "ARMA\n(2,2)", "AR(2)\n", "MARSS\nEM", "MARSS\nBFGS", "ARMA\n(2,2)"), ylab = "estimates of the ar coefficients", las = 2) + points(1:8, apply(params[c(7, 1, 3, 5, 8, 2, 4, 6), ], 1, mean), pch = "x", cex = 1.25) + par(cex = 1.5) + axis(side = 3, at = c(2, 6), labels = c(expression(b[1]), expression(b[2])), tick = FALSE, cex = 2) + lines(c(0, 4.5), c(true.2ss[2], true.2ss[2]), lty = 2) + lines(c(4.5, 9), c(true.2ss[3], true.2ss[3]), lty = 2) + abline(v = 4.5) +} + + diff --git a/inst/doc/Chapter_MLR.R b/inst/doc/Chapter_MLR.R new file mode 100644 index 0000000..d5fb902 --- /dev/null +++ b/inst/doc/Chapter_MLR.R @@ -0,0 +1,354 @@ +################################################### +### code chunk number 2: Cs_000_required_libraries +################################################### +library(MARSS) +library(xtable) +library(lattice) +library(nlme) +library(stringr) +library(lme4) + + +################################################### +### code chunk number 3: Cs_001_example1_plot +################################################### +data(longley) +plot(longley$Year, longley$Employed, type = "l", ylab = "Employed", xlab = "") + + +################################################### +### code chunk number 4: Cs_002_example1-data +################################################### +data(longley) +Employed <- matrix(longley$Employed, nrow = 1) + + +################################################### +### code chunk number 5: Cs_003_example1-params +################################################### +longley.model <- list() + + +################################################### +### code chunk number 6: Cs_004_example1-params1 +################################################### +longley.model$U <- longley.model$Q <- "zero" +longley.model$C <- "zero" +longley.model$B <- longley.model$Z <- "identity" +longley.model$x0 <- "zero" +longley.model$tinitx <- 0 + + +################################################### +### code chunk number 7: Cs_005_example1-paramsR +################################################### +longley.model$R <- matrix("r") + + +################################################### +### code chunk number 8: Cs_006_example1-paramsD +################################################### +longley.model$A <- matrix("intercept") +longley.model$D <- matrix(c("GNP", "Pop"), nrow = 1) + + +################################################### +### code chunk number 9: Cs_007_example1-eVar +################################################### +longley.model$d <- rbind(longley$GNP, longley$Population) + + +################################################### +### code chunk number 10: Cs_008_example1-marss +################################################### +mod1 <- MARSS(Employed, model = longley.model) + + +################################################### +### code chunk number 11: Cs_009_example1-marss +################################################### +coef(mod1, type = "vector") + + +################################################### +### code chunk number 12: Cs_010_example1-lm +################################################### +mod1.lm <- lm(Employed ~ GNP + Population, data = longley) +coef(mod1.lm) + + +################################################### +### code chunk number 13: Cs_011_example2-params +################################################### +longley.ar1 <- longley.model +longley.ar1$B <- matrix("b") +longley.ar1$Q <- matrix("q") + + +################################################### +### code chunk number 14: Cs_012_example2-marss +################################################### +mod2 <- MARSS(Employed, model = longley.ar1) + + +################################################### +### code chunk number 15: Cs_013_example2-marss-with-inits +################################################### +inits <- list(A = coef(mod1)$A, D = coef(mod1)$D) +mod2 <- MARSS(Employed, + model = longley.ar1, inits = inits, + control = list(maxit = 1000) +) +ests.marss <- c( + b = coef(mod2)$B, alpha = coef(mod2)$A, + GNP = coef(mod2)$D[1], Population = coef(mod2)$D[2], + logLik = logLik(mod2) +) + + +################################################### +### code chunk number 16: Cs_014_example2-gls +################################################### +library(nlme) +mod2.gls <- gls(Employed ~ GNP + Population, + correlation = corAR1(), data = longley, method = "ML" +) +mod2.gls.phi <- coef(mod2.gls$modelStruct[[1]], unconstrained = FALSE) +ests.gls <- c( + b = mod2.gls.phi, alpha = coef(mod2.gls)[1], + GNP = coef(mod2.gls)[2], Population = coef(mod2.gls)[3], + logLik = logLik(mod2.gls) +) + + +################################################### +### code chunk number 17: Cs_014b_compare_marss_gls +################################################### +rbind(MARSS = ests.marss, GLS = ests.gls) + + +################################################### +### code chunk number 18: Cs_015_example2-plot +################################################### +pairs(longley) + + +################################################### +### code chunk number 19: Cs_016_full-model-list +################################################### +eVar.names <- colnames(longley)[-7] +eVar <- t(longley[, eVar.names]) +longley.model <- list() +longley.model$U <- longley.model$Q <- "zero" +longley.model$C <- "zero" +longley.model$B <- longley.model$Z <- "identity" +longley.model$A <- matrix("intercept") +longley.model$R <- matrix("r") +longley.model$D <- matrix(eVar.names, nrow = 1) +longley.model$d <- eVar +longley.model$x0 <- "zero" +longley.model$tinitx <- 0 + + +################################################### +### code chunk number 20: Cs_017_full-model-fit +################################################### +mod3.em <- MARSS(Employed, model = longley.model) +mod3.bfgs <- MARSS(Employed, model = longley.model, method = "BFGS") + + +################################################### +### code chunk number 21: Cs_018_full-em-ests +################################################### +par.names <- c("A.intercept", paste("D", eVar.names, sep = ".")) +c(coef(mod3.em, type = "vector")[par.names], logLik = mod3.em$logLik) + + +################################################### +### code chunk number 22: Cs_019_full-bfgs-ests +################################################### +c(coef(mod3.bfgs, type = "vector")[par.names], logLik = mod3.bfgs$logLik) + + +################################################### +### code chunk number 23: Cs_020_full-lm-ests +################################################### +mod3.lm <- lm(Employed ~ 1 + GNP.deflator + GNP + Unemployed + + Armed.Forces + Population + Year, data = longley) +c(coef(mod3.lm), logLik = logLik(mod3.lm)) + + +################################################### +### code chunk number 24: Cs_021_full-model-correrr +################################################### +longley.correrr.model <- longley.model +longley.correrr.model$B <- matrix("b") +longley.correrr.model$Q <- matrix("q") + + +################################################### +### code chunk number 25: Cs_022_full-correrr-fit-hide +################################################### +inits <- list(A = coef(mod3.em)$A, D = coef(mod3.em)$D) +mod4.em <- MARSS(Employed, model = longley.correrr.model, inits = inits) +mod4.bfgs <- MARSS(Employed, + model = longley.correrr.model, + inits = inits, method = "BFGS" +) + + +################################################### +### code chunk number 26: Cs_023_full-correrr-em-ests +################################################### +c(coef(mod4.em, type = "vector")["B.b"], logLik = mod4.em$logLik) + + +################################################### +### code chunk number 27: Cs_024_full-correrr-bfgs-ests +################################################### +c(coef(mod4.bfgs, type = "vector")["B.b"], logLik = mod4.bfgs$logLik) + + +################################################### +### code chunk number 28: Cs_025_full-gls-ests +################################################### +mod4.gls <- gls(Employed ~ 1 + GNP.deflator + GNP + Unemployed + + Armed.Forces + Population + Year, +correlation = corAR1(), data = longley, method = "ML" +) +mod4.gls.phi <- coef(mod4.gls$modelStruct[[1]], unconstrained = FALSE) +c(mod4.gls.phi, logLik = logLik(mod4.gls)) + + +################################################### +### code chunk number 29: Cs_026_loadsleep +################################################### +data(sleepstudy, package = "lme4") + + +################################################### +### code chunk number 30: Cs_027_sleep-plot +################################################### +library(lattice) +xyplot(Reaction ~ Days | Subject, sleepstudy, + type = c("g", "p", "r"), + index = function(x, y) coef(lm(y ~ x))[1], + xlab = "Days of sleep deprivation", + ylab = "Average reaction time (ms)", aspect = "xy" +) + + +################################################### +### code chunk number 31: Cs_028_setupdata +################################################### +# number of subjects +nsub <- length(unique(sleepstudy$Subject)) +ndays <- length(sleepstudy$Days) / nsub +dat <- matrix(sleepstudy$Reaction, nsub, ndays, byrow = TRUE) +rownames(dat) <- paste("sub", unique(sleepstudy$Subject), sep = ".") +exp.var <- matrix(sleepstudy$Days, 1, ndays, byrow = TRUE) + + +################################################### +### code chunk number 32: Cs_029_sleepmod1 +################################################### +sleep.model <- list( + A = "unequal", B = "zero", x0 = "zero", U = "zero", + D = matrix("b1", nsub, 1), d = exp.var, tinitx = 0, Q = "zero" +) +sleep.mod1 <- MARSS(dat, model = sleep.model) + + +################################################### +### code chunk number 33: Cs_030_sleepmod1-lm +################################################### +sleep.lm1 <- lm(Reaction ~ -1 + Subject + Days, data = sleepstudy) + + +################################################### +### code chunk number 34: Cs_031_sleepmod2 +################################################### +sleep.model <- list( + A = "unequal", B = "zero", x0 = "zero", U = "zero", + D = "unequal", d = exp.var, tinitx = 0, Q = "zero" +) +sleep.mod2 <- MARSS(dat, model = sleep.model, silent = TRUE) + + +################################################### +### code chunk number 35: Cs_032_sleepmod2-lm +################################################### +sleep.lm2 <- lm(Reaction ~ 0 + Subject + Days:Subject, data = sleepstudy) + + +################################################### +### code chunk number 36: Cs_033_sleepmod3 +################################################### +sleep.model <- list( + A = "unequal", B = "zero", x0 = "zero", U = "zero", + D = "unequal", d = exp.var, tinitx = 0, Q = "zero", + R = "diagonal and unequal" +) +sleep.mod3 <- MARSS(dat, model = sleep.model, silent = TRUE) + + +################################################### +### code chunk number 37: Cs_034_sleepmod4 +################################################### +inits <- list(A = coef(sleep.mod3)$A, D = coef(sleep.mod3)$D) +# estimate a separate intercept for each but slope is the same +sleep.model <- list( + A = "unequal", B = "diagonal and unequal", x0 = "zero", U = "zero", + D = "unequal", d = exp.var, tinitx = 0, Q = "diagonal and unequal", + R = "diagonal and unequal" +) +sleep.mod4 <- MARSS(dat, model = sleep.model, inits = inits, silent = TRUE) + + +################################################### +### code chunk number 38: Cs_035_sleepmod5 +################################################### +inits <- list(A = coef(sleep.mod3)$A, D = coef(sleep.mod3)$D) +# estimate a separate intercept for each but slope is the same +sleep.model <- list( + A = "unequal", B = "diagonal and equal", x0 = "zero", U = "zero", + D = "unequal", d = exp.var, tinitx = 0, Q = "diagonal and equal", + R = "diagonal and equal" +) +sleep.mod5 <- MARSS(dat, model = sleep.model, inits = inits, silent = TRUE) + + +################################################### +### code chunk number 39: Cs_036_mod5-gls +################################################### +sleep.mod5.gls <- gls(Reaction ~ 0 + Subject + Days:Subject, + data = sleepstudy, + correlation = corAR1(form = ~ 1 | Subject), method = "ML" +) + + +################################################### +### code chunk number 40: Cs_037_makemodeltable +################################################### +if (!exists("tabledir")) tabledir <- "" +slope.names <- paste("D", rownames(dat), sep = ".") +phi.names <- names(coef(sleep.mod4, type = "vector"))[str_detect(names(coef(sleep.mod4, type = "vector")), "B.")] + +model.data <- cbind( + c(logLik(sleep.lm2), coef(sleep.lm2)[19:36], rep(NA, nsub)), + c(sleep.mod2$logLik, coef(sleep.mod2, type = "vector")[slope.names], rep(NA, nsub)), + c(sleep.mod3$logLik, coef(sleep.mod3, type = "vector")[slope.names], rep(NA, nsub)), + c(sleep.mod4$logLik, coef(sleep.mod4, type = "vector")[c(slope.names, phi.names)]), + c(sleep.mod5$logLik, coef(sleep.mod5, type = "vector")[c(slope.names, rep("B.diag", nsub))]), + c(logLik(sleep.mod5.gls), coef(sleep.mod5.gls)[19:36], rep(coef(sleep.mod5.gls$modelStruct[[1]], unconstrained = FALSE), nsub)) +) +rownames(model.data) <- c("logLik", paste("slope", unique(sleepstudy$Subject)), paste("phi", unique(sleepstudy$Subject))) +colnames(model.data) <- c("lm", "mod2 em", "mod3 em", "mod4 em", "mod5 em", "mod5 gls") +tmpaln <- "c" # figure out the number of cols automatically +for (i in 1:ncol(model.data)) tmpaln <- paste(tmpaln, "c", sep = "") +thetable <- xtable(model.data, caption = "Parameter estimates of different versions of the model where each subject has a separate intercept (response time on normal sleep) and different slope by day (increase in response time with each day of sleep deprivation). The model types are discussed in the text.", label = "ref:tablesleepstudy", align = tmpaln, digits = 2) +print(thetable, type = "latex", file = paste(tabledir, "tablesleepstudy.tex", sep = ""), include.rownames = TRUE, include.colnames = TRUE, caption.placement = "top", table.placement = "htp", sanitize.text.function = function(x) { + x +}, hline.after = c(-1, 0, nrow(model.data))) + + diff --git a/inst/doc/Chapter_PVA.R b/inst/doc/Chapter_PVA.R new file mode 100644 index 0000000..301c594 --- /dev/null +++ b/inst/doc/Chapter_PVA.R @@ -0,0 +1,167 @@ +################################################### +### code chunk number 7: Cs1_Exercise1 +################################################### +par(mfrow = c(3, 3)) +sim.u <- -0.05 +sim.Q <- 0.02 +sim.R <- 0.05 +nYr <- 50 +fracmiss <- 0.1 +init <- 7 +years <- seq(1:nYr) +for (i in 1:9) { + x <- rep(NA, nYr) # vector for ts w/o measurement error + y <- rep(NA, nYr) # vector for ts w/ measurement error + x[1] <- init + for (t in 2:nYr) { + x[t] <- x[t - 1] + sim.u + rnorm(1, mean = 0, sd = sqrt(sim.Q)) + } + for (t in 1:nYr) { + y[t] <- x[t] + rnorm(1, mean = 0, sd = sqrt(sim.R)) + } + missYears <- + sample(years[2:(nYr - 1)], floor(fracmiss * nYr), replace = FALSE) + y[missYears] <- NA + plot(years, y, + xlab = "", ylab = "Log abundance", lwd = 2, bty = "l" + ) + lines(years, x, type = "l", lwd = 2, lty = 2) + title(paste("simulation ", i)) +} +legend("topright", c("Observed", "True"), + lty = c(-1, 2), pch = c(1, -1) +) + + +################################################### +### code chunk number 17: Cs1_Exercise2 +################################################### +sim.u <- -0.05 # growth rate +sim.Q <- 0.02 # process error variance +sim.R <- 0.05 # non-process error variance +nYr <- 50 # number of years of data to generate +fracmiss <- 0.1 # fraction of years that are missing +init <- 7 # log of initial pop abundance (~1100 individuals) +nsim <- 9 +years <- seq(1:nYr) # col of years +params <- matrix(NA, + nrow = (nsim + 2), ncol = 5, + dimnames = list( + c(paste("sim", 1:nsim), "mean sim", "true"), + c("kem.U", "den91.U", "kem.Q", "kem.R", "den91.Q") + ) +) +x.ts <- matrix(NA, nrow = nsim, ncol = nYr) # ts w/o measurement error +y.ts <- matrix(NA, nrow = nsim, ncol = nYr) # ts w/ measurement error +for (i in 1:nsim) { + x.ts[i, 1] <- init + for (t in 2:nYr) { + x.ts[i, t] <- x.ts[i, t - 1] + sim.u + rnorm(1, mean = 0, sd = sqrt(sim.Q)) + } + for (t in 1:nYr) { + y.ts[i, t] <- x.ts[i, t] + rnorm(1, mean = 0, sd = sqrt(sim.R)) + } + missYears <- sample(years[2:(nYr - 1)], floor(fracmiss * nYr), + replace = FALSE + ) + y.ts[i, missYears] <- NA + + # MARSS estimates + kem <- MARSS(y.ts[i, ], silent = TRUE) + # type=vector outputs the estimates as a vector instead of a list + params[i, c(1, 3, 4)] <- coef(kem, type = "vector")[c(2, 3, 1)] + + # Dennis et al 1991 estimates + den.years <- years[!is.na(y.ts[i, ])] # the non missing years + den.yts <- y.ts[i, !is.na(y.ts[i, ])] # the non missing counts + den.n.yts <- length(den.years) + delta.pop <- rep(NA, den.n.yts - 1) # transitions + tau <- rep(NA, den.n.yts - 1) # time step lengths + for (t in 2:den.n.yts) { + delta.pop[t - 1] <- den.yts[t] - den.yts[t - 1] # transitions + tau[t - 1] <- den.years[t] - den.years[t - 1] # time step length + } # end i loop + den91 <- lm(delta.pop ~ -1 + tau) # -1 specifies no intercept + params[i, c(2, 5)] <- c(den91$coefficients, var(resid(den91))) +} +params[nsim + 1, ] <- apply(params[1:nsim, ], 2, mean) +params[nsim + 2, ] <- c(sim.u, sim.u, sim.Q, sim.R, sim.Q) + + +################################################### +### code chunk number 21: Cs1_Exercise3 +################################################### +# Needs Example 2 to be run first +par(mfrow = c(3, 3)) +pd <- 0.1; xd <- -log(pd) # decline threshold +te <- 100; tyrs <- 1:te # extinction time horizon +for (j in c(10, 1:8)) { + real.ex <- denn.ex <- kal.ex <- matrix(nrow = te) + + # MARSS parameter estimates + u <- params[j, 1]; Q <- params[j, 3] + if (Q == 0) Q <- 1e-4 # just so the extinction calc doesn't choke + p.ever <- ifelse(u <= 0, 1, exp(-2 * u * xd / Q)) + for (i in 1:100) { + if (is.finite(exp(2 * xd * abs(u) / Q))) { + sec.part <- exp(2 * xd * abs(u) / Q) * + pnorm((-xd - abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + } else { sec.part <- 0 } + kal.ex[i] <- p.ever * pnorm((-xd + abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + sec.part + } # end i loop + + # Dennis et al 1991 parameter estimates + u <- params[j, 2]; Q <- params[j, 5] + p.ever <- ifelse(u <= 0, 1, exp(-2 * u * xd / Q)) + for (i in 1:100) { + denn.ex[i] <- p.ever * pnorm((-xd + abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + + exp(2 * xd * abs(u) / Q) * + pnorm((-xd - abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + } # end i loop + + # True parameter values + u <- sim.u; Q <- sim.Q + p.ever <- ifelse(u <= 0, 1, exp(-2 * u * xd / Q)) + for (i in 1:100) { + real.ex[i] <- p.ever * pnorm((-xd + abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + + exp(2 * xd * abs(u) / Q) * + pnorm((-xd - abs(u) * tyrs[i]) / sqrt(Q * tyrs[i])) + } # end i loop + + plot(tyrs, real.ex, xlab = "Time steps into future", + ylab = "Probability of extinction", ylim = c(0, 1), bty = "l") + if (j <= 8) title(paste("simulation ", j)) + if (j == 10) title("average over sims") + lines(tyrs, denn.ex, type = "l", col = "red", lwd = 2, lty = 1) + lines(tyrs, kal.ex, type = "l", col = "green", lwd = 2, lty = 2) +} +legend("bottomright", c("True", "Dennis", "KalmanEM"), pch = c(1, -1, -1), + col = c(1, 2, 3), lty = c(-1, 1, 2), lwd = c(-1, 2, 2), bty = "n") + + +################################################### +### code chunk number 23: Cs1_Exercise4 +################################################### +par(mfrow = c(1, 1)) +CSEGtmufigure(N = 50, u = -0.05, s2p = 0.02) + + +################################################### +### code chunk number 27: Cs1_Exercise5 +################################################### +# If you have your data in a tab delimited file with a header +# This is how you would read it in using file.choose() +# to call up a directory browser. +# However, the package has the datasets for the examples +# dat=read.table(file.choose(), skip=1) +# dat=as.matrix(dat) +dat <- wilddogs +CSEGriskfigure(dat, CI.method = "hessian", silent = TRUE) + + +################################################### +### code chunk number 2: Cs1_a_required_libraries +################################################### +library(MARSS) + + diff --git a/inst/doc/Chapter_SealPopStructure.R b/inst/doc/Chapter_SealPopStructure.R new file mode 100644 index 0000000..3f85753 --- /dev/null +++ b/inst/doc/Chapter_SealPopStructure.R @@ -0,0 +1,300 @@ +################################################### +### code chunk number 2: Cs00_required_libraries +################################################### +library(MARSS) + + +################################################### +### code chunk number 9: Cs01_set.up.data +################################################### +years <- harborSeal[, 1] # first col is years +# leave off Hood Canal data for now +sealData <- t(harborSeal[, c(2:7, 9:13)]) + + +################################################### +### code chunk number 10: Cs02_fig1 +################################################### +par(mfrow = c(4, 3), mar = c(2, 2, 2, 2)) +for (i in 2:dim(harborSeal)[2]) { + plot(years, harborSeal[, i], xlab = "", ylab = "", + main = colnames(harborSeal)[i]) +} + + +################################################### +### code chunk number 11: Cs03_set.up.Z.models +################################################### +# H1 stock +Z1 <- factor(c("wa.or", "wa.or", rep("ps", 4), + "ca", "ca", "wa.or", "wa.or", "bc")) +# H2 coastal+PS +Z2 <- factor(c(rep("coast", 2), rep("ps", 4), rep("coast", 4), "ps")) +# H3 N and S +Z3 <- factor(c(rep("N", 6), "S", "S", "N", "S", "N")) +# H4 North Coast, Inland Strait, Puget Sound, South Coast +Z4 <- factor(c("nc", "nc", "is", "is", "ps", "ps", + "sc", "sc", "nc", "sc", "is")) +# H5 panmictic +Z5 <- factor(rep("pan", 11)) +# H6 Site +Z6 <- factor(1:11) # site +Z.models <- list(Z1, Z2, Z3, Z4, Z5, Z6) +names(Z.models) <- + c("stock", "coast+PS", "N-S", "NC+Strait+PS+SC", "panmictic", "site") + + +################################################### +### code chunk number 12: Cs04_Q.models +################################################### +Q.models <- c("diagonal and equal", "diagonal and unequal") + + +################################################### +### code chunk number 13: Cs04a_other.models +################################################### +U.model <- "unequal" +R.model <- "diagonal and equal" +A.model <- "scaling" +B.model <- "identity" +x0.model <- "unequal" +V0.model <- "zero" +model.constant <- list( + U = U.model, R = R.model, A = A.model, + x0 = x0.model, V0 = V0.model, tinitx = 0 +) + + +################################################### +### code chunk number 14: Cs05_run.the.models +################################################### +out.tab <- NULL +fits <- list() +for (i in 1:length(Z.models)) { + for (Q.model in Q.models) { + fit.model <- c(list(Z = Z.models[[i]], Q = Q.model), model.constant) + fit <- MARSS(sealData, + model = fit.model, + silent = TRUE, control = list(maxit = 1000) + ) + out <- data.frame( + H = names(Z.models)[i], Q = Q.model, U = U.model, + logLik = fit$logLik, AICc = fit$AICc, num.param = fit$num.params, + m = length(unique(Z.models[[i]])), + num.iter = fit$numIter, converged = !fit$convergence, + stringsAsFactors = FALSE + ) + out.tab <- rbind(out.tab, out) + fits <- c(fits, list(fit)) + if (i == 5) next # one m for panmictic so only run 1 Q + } +} + + +################################################### +### code chunk number 15: Cs06_sort.results +################################################### +min.AICc <- order(out.tab$AICc) +out.tab.1 <- out.tab[min.AICc, ] + + +################################################### +### code chunk number 16: Cs07_add.delta.aicc +################################################### +out.tab.1 <- cbind(out.tab.1, + delta.AICc = out.tab.1$AICc - out.tab.1$AICc[1] +) + + +################################################### +### code chunk number 17: Cs08_add.delta.aicc +################################################### +out.tab.1 <- cbind(out.tab.1, + rel.like = exp(-1 * out.tab.1$delta.AICc / 2) +) + + +################################################### +### code chunk number 18: Cs09_aic.weight +################################################### +out.tab.1 <- cbind(out.tab.1, + AIC.weight = out.tab.1$rel.like / sum(out.tab.1$rel.like) +) + + +################################################### +### code chunk number 19: Cs10_print.table +################################################### +out.tab.1$delta.AICc <- round(out.tab.1$delta.AICc, digits = 2) +out.tab.1$AIC.weight <- round(out.tab.1$AIC.weight, digits = 3) +print(out.tab.1[, c("H", "Q", "delta.AICc", "AIC.weight")], row.names = FALSE) + + +################################################### +### code chunk number 20: Cs11_fignorthsouth +################################################### +best.fit <- fits[min.AICc][[1]] +graphics::matplot(years, t(best.fit$states - best.fit$states[, 1]), + ylab = "Abundance index", xlab = "", + type = "l", lwd = 2, col = "black" +) +legend("topleft", c("North Coastal", "Inland Straits", "Puget Sound", "South Coastal"), lwd = 2, lty = c(1:4), bty = "n") + + +################################################### +### code chunk number 22: Cs12_new.Q.model +################################################### +for (i in 1:length(Z.models)) { + if (i == 5) next # don't rerun panmictic + for (Q.model in c("equalvarcov", "unconstrained")) { + fit.model <- c(list(Z = Z.models[[i]], Q = Q.model), model.constant) + fit <- MARSS(sealData, + model = fit.model, + silent = TRUE, control = list(maxit = 1000) + ) + out <- data.frame( + H = names(Z.models)[i], Q = Q.model, U = U.model, + logLik = fit$logLik, AICc = fit$AICc, num.param = fit$num.params, + m = length(unique(Z.models[[i]])), + num.iter = fit$numIter, converged = !fit$convergence, + stringsAsFactors = FALSE + ) + out.tab <- rbind(out.tab, out) + fits <- c(fits, list(fit)) + } +} + + +################################################### +### code chunk number 23: Cs13_out.tab.2 +################################################### +min.AICc <- order(out.tab$AICc) +out.tab.2 <- out.tab[min.AICc, ] +fits <- fits[min.AICc] +out.tab.2$delta.AICc <- out.tab.2$AICc - out.tab.2$AICc[1] +out.tab.2$rel.like <- exp(-1 * out.tab.2$delta.AICc / 2) +out.tab.2$AIC.weight <- out.tab.2$rel.like / sum(out.tab.2$rel.like) + + +################################################### +### code chunk number 24: Cs14_out.tab.2 +################################################### +out.tab.2$AIC.weight <- round(out.tab.2$AIC.weight, digits = 3) +out.tab.2$delta.AICc <- round(out.tab.2$delta.AICc, digits = 2) +print(out.tab.2[1:10, c("H", "Q", "delta.AICc", "AIC.weight")], row.names = FALSE) + + +################################################### +### code chunk number 25: Cs15_equalvarcov.weight +################################################### +c( + sum(out.tab.2$AIC.weight[out.tab.2$Q == "equalvarcov"]), + sum(out.tab.2$AIC.weight[out.tab.2$Q == "unconstrained"]), + sum(out.tab.2$AIC.weight[out.tab.2$Q == "diagonal and equal"]) +) + + +################################################### +### code chunk number 26: Cs16_Q.mat +################################################### +Q.unc <- coef(fits[[3]], type = "matrix")$Q + + +################################################### +### code chunk number 27: Cs17_Q.diag +################################################### +diag(Q.unc) + + +################################################### +### code chunk number 28: Cs18_Q.corr +################################################### +h <- diag(1 / sqrt(diag(Q.unc))) +Q.corr <- h %*% Q.unc %*% h +rownames(Q.corr) <- unique(Z4) +colnames(Q.corr) <- unique(Z4) + +Q.corr + + +################################################### +### code chunk number 29: Cs19_add.hood.canal +################################################### +sealData.hc <- rbind(sealData, harborSeal[, 8]) +rownames(sealData.hc)[12] <- "Hood.Canal" + + +################################################### +### code chunk number 30: Cs20_hood.z.models +################################################### +ZH1 <- factor(c("nc", "nc", "is", "is", "ps", + "ps", "sc", "sc", "nc", "sc", "is", "ps")) +ZH2 <- factor(c("nc", "nc", "is", "is", "ps", + "ps", "sc", "sc", "nc", "sc", "is", "hc")) +Z.models.hc <- list(ZH1, ZH2) +names(Z.models.hc) <- c("hood.in.ps", "hood.separate") + + +################################################### +### code chunk number 31: Cs21_hood.uqr.models +################################################### +Q3 <- matrix(list("offdiag"), 5, 5) +diag(Q3) <- "q" +Q3[, 5] <- 0 +Q3[5, ] <- 0 +Q3[5, 5] <- "q.hc" +Q.models <- list("equalvarcov", "unconstrained", Q3) +names(Q.models) <- c("equalvarcov", "unconstrained", "hood.independent") + + +################################################### +### code chunk number 32: Cs22_hood-q3 +################################################### +Q.models$hood.independent + + +################################################### +### code chunk number 33: Cs23_out.tab.hc +################################################### +out.tab.hc <- NULL +fits.hc <- list() +for (i in 1:length(Z.models.hc)) { + for (j in 1:length(Q.models)) { + if (i == 1 & j == 3) next # Q3 is only for Hood Separate model + Q.model <- Q.models[[j]] + fit.model <- c(list(Z = Z.models.hc[[i]], Q = Q.model), model.constant) + fit <- MARSS(sealData.hc, + model = fit.model, + silent = TRUE, control = list(maxit = 1000) + ) + out <- data.frame( + H = names(Z.models.hc)[i], Q = names(Q.models)[j], U = U.model, + logLik = fit$logLik, AICc = fit$AICc, num.param = fit$num.params, + m = length(unique(Z.models.hc[[i]])), + num.iter = fit$numIter, converged = !fit$convergence, + stringsAsFactors = FALSE + ) + out.tab.hc <- rbind(out.tab.hc, out) + fits.hc <- c(fits.hc, list(fit)) + } +} + + +################################################### +### code chunk number 34: Cs24_sort.aicc.hc +################################################### +min.AICc <- order(out.tab.hc$AICc) +out.tab.hc <- out.tab.hc[min.AICc, ] +out.tab.hc$delta.AICc <- out.tab.hc$AICc - out.tab.hc$AICc[1] +out.tab.hc$rel.like <- exp(-1 * out.tab.hc$delta.AICc / 2) +out.tab.hc$AIC.weight <- out.tab.hc$rel.like / sum(out.tab.hc$rel.like) + + +################################################### +### code chunk number 35: Cs25_out.tab.2 +################################################### +out.tab.hc$AIC.weight <- round(out.tab.hc$AIC.weight, digits = 3) +out.tab.hc$delta.AICc <- round(out.tab.hc$delta.AICc, digits = 2) +print(out.tab.hc[, c("H", "Q", "delta.AICc", "AIC.weight")], row.names = FALSE) + + diff --git a/inst/doc/Chapter_SealTrend.R b/inst/doc/Chapter_SealTrend.R new file mode 100644 index 0000000..6781555 --- /dev/null +++ b/inst/doc/Chapter_SealTrend.R @@ -0,0 +1,110 @@ +################################################### +### code chunk number 10: Cs2_Code1 +################################################### +# Code to fit the single population model with i.i.d. errors +# Read in data +dat <- t(harborSealWA) # MARSS needs time ACROSS columns +years <- dat[1, ] +n <- nrow(dat) - 1 +dat <- dat[2:nrow(dat), ] +legendnames <- (unlist(dimnames(dat)[1])) + +# estimate parameters +Z.model <- factor(c(1, 1, 1, 1, 1)) +R.model <- "diagonal and equal" +kem1 <- MARSS(dat, model = list(Z = Z.model, R = R.model)) + +# make figure +graphics::matplot(years, t(dat), + xlab = "", ylab = "Index of log abundance", + pch = c("1", "2", "3", "4", "5"), ylim = c(5, 9), bty = "L" +) +lines(years, kem1$states - 1.96 * kem1$states.se, + type = "l", + lwd = 1, lty = 2, col = "red" +) +lines(years, kem1$states + 1.96 * kem1$states.se, + type = "l", + lwd = 1, lty = 2, col = "red" +) +lines(years, kem1$states, type = "l", lwd = 2) +title("Observations and total population estimate", cex.main = .9) + +coef(kem1, type = "vector") # parameter estimates as a vector + +# show estimated elements for each parameter matrix as a list +coef(kem1) + +kem1$logLik # show the log-likelihood +kem1$AIC # show the AIC + + +################################################### +### code chunk number 17: Cs2_Code2 +################################################### +# Fit the single population model with independent and unequal errors +Z.model <- factor(c(1, 1, 1, 1, 1)) +R.model <- "diagonal and unequal" +kem2 <- MARSS(dat, model = list(Z = Z.model, R = R.model)) + +coef(kem2) # the estimated parameter elements +kem2$logLik # log likelihood +c(kem1$AIC, kem2$AIC) # AICs + +plot(kem2, plot.type="model.resids.ytT") + + +################################################### +### code chunk number 20: Cs2_Code3 +################################################### +# fit the north and south population model +Z.model <- factor(c(1, 1, 2, 2, 2)) +U.model <- "equal" +Q.model <- "diagonal and equal" +R.model <- "diagonal and unequal" +kem3 <- MARSS(dat, model = list( + Z = Z.model, + R = R.model, U = U.model, Q = Q.model +)) +# plot smoothation residuals +plot(kem3, plot.type="model.resids.ytT") + + +################################################### +### code chunk number 22: Cs2_Code4 +################################################### +Z.model <- factor(c(1, 2, 3, 4, 5)) +U.model <- "equal" +Q.model <- "diagonal and equal" +R.model <- "diagonal and unequal" +kem <- MARSS(dat, model = list( + Z = Z.model, + U = U.model, Q = Q.model, R = R.model +)) + + +################################################### +### code chunk number 29: Cs2_Code5_7 +################################################### +# Two subpopulations with different population parameters +Z.model <- factor(c(1, 1, 2, 2, 2)) +U.model <- "unequal" +Q.model <- "diagonal and unequal" +R.model <- "diagonal and unequal" +kem <- MARSS(dat, model = list(Z = Z.model, U = U.model, Q = Q.model, R = R.model)) + +# Hood Canal covaries with the other regions +Z.model <- factor(c(1, 1, 1, 1, 2)) +U.model <- "unequal" +Q.model <- "equalvarcov" +R.model <- "diagonal and unequal" +kem <- MARSS(dat, model = list(Z = Z.model, U = U.model, Q = Q.model, R = R.model)) + +# Three subpopulations with shared parameter values +Z.model <- factor(c(1, 1, 2, 2, 3)) +U.model <- "unequal" +Q.model <- "diagonal and unequal" +R.model <- "diagonal and unequal" +kem <- MARSS(dat, model = list(Z = Z.model, U = U.model, Q = Q.model, R = R.model)) + + diff --git a/inst/doc/Chapter_SpeciesInteractions.R b/inst/doc/Chapter_SpeciesInteractions.R new file mode 100644 index 0000000..f0333da --- /dev/null +++ b/inst/doc/Chapter_SpeciesInteractions.R @@ -0,0 +1,407 @@ +################################################### +### code chunk number 2: Cs01_load.wolf.data +################################################### +yr1960to2011 <- isleRoyal[, "Year"] >= 1960 & isleRoyal[, "Year"] <= 2011 +royale.dat <- log(t(isleRoyal[yr1960to2011, c("Wolf", "Moose")])) + + +################################################### +### code chunk number 3: Cs02_plotwolfmoosedata +################################################### +x <- isleRoyal[, "Year"] +y <- log(isleRoyal[, c("Wolf", "Moose")]) +graphics::matplot(x, y, + ylab = "Log count", xlab = "Year", type = "l", + lwd = 3, bty = "L", col = "black" +) +legend("topright", c("Wolf", "Moose"), lty = c(1, 2), bty = "n") + + +################################################### +### code chunk number 5: Cs03_z.score.wolf.data +################################################### +# if missing values are in the data, they should be NAs +z.royale.dat <- zscore(royale.dat) + + +################################################### +### code chunk number 6: Cs04_fit.model +################################################### +royale.model.1 <- list( + Z = "identity", B = "unconstrained", + Q = "diagonal and unequal", R = "diagonal and unequal", + U = "zero", tinitx = 1 +) +cntl.list <- list(allow.degen = FALSE, maxit = 200) +kem.1 <- MARSS(z.royale.dat, model = royale.model.1, control = cntl.list) + + +################################################### +### code chunk number 7: Cs05_fit.model.R0 +################################################### +royale.model.2 <- list( + Z = "identity", B = "unconstrained", + Q = "diagonal and unequal", R = "zero", U = "zero" +) +kem.2 <- MARSS(z.royale.dat, model = royale.model.2) + + +################################################### +### code chunk number 14: Cs05_fit.model.tinitx1 +################################################### +royale.model.4 <- list( + B = "unconstrained", U = "zero", Q = "diagonal and unequal", + Z = "identity", R = "zero", tinitx = 1 +) +kem.4 <- MARSS(z.royale.dat, model = royale.model.4) + + +################################################### +### code chunk number 8: Cs06_print-wolf.B +################################################### +wolf.B <- coef(kem.2, type = "matrix")$B +rownames(wolf.B) <- colnames(wolf.B) <- rownames(royale.dat) +print(wolf.B, digits = 2) + + +################################################### +### code chunk number 9: Cs07_prep-cov-wolf-moose +################################################### +clim.variables <- c( + "jan.feb.ave.temp", "jan.feb.ave.precip", + "july.sept.ave.temp" +) +yr1959to2010 <- isleRoyal[, "Year"] >= 1959 & isleRoyal[, "Year"] <= 2010 +clim.dat <- t(isleRoyal[yr1959to2010, clim.variables]) +z.score.clim.dat <- zscore(clim.dat) + + +################################################### +### code chunk number 10: Cs08_cov.wolf.moose.model +################################################### +royale.model.3 <- list( + Z = "identity", B = "unconstrained", + Q = "diagonal and unequal", R = "zero", U = "zero", + C = matrix(list( + 0, "Moose win temp", 0, "Moose win precip", + 0, "Moose sum temp" + ), 2, 3), + c = z.score.clim.dat +) + + +################################################### +### code chunk number 11: Cs09_fit-cov-wolf-moose-model +################################################### +kem.3 <- MARSS(z.royale.dat, model = royale.model.3) + + +################################################### +### code chunk number 12: Cs10_figwolfcov +################################################### +cor.fun <- function(x, y) { + text(0.5, 0.5, format(cor(x, y), digits = 2), cex = 2) +} +pairs(t(z.score.clim.dat), lower.panel = cor.fun) + + +################################################### +### code chunk number 13: Cs11_bad-data-2 (eval = FALSE) +################################################### +## bad.data <- z.royale.dat + matrix(rnorm(100, 0, sqrt(.2)), 2, 50) +## kem.bad <- MARSS(bad.data, model = model) + + +################################################### +### code chunk number 15: Cs12_load-plankton-data +################################################### +# only use the plankton, daphnia, & non-daphnia +plank.spp <- c("Large Phyto", "Small Phyto", "Daphnia", "Non-daphnia") +plank.dat <- ivesDataByWeek[, plank.spp] +# The data are not logged +plank.dat <- log(plank.dat) +# Transpose to get time going across the columns +plank.dat <- t(plank.dat) +# make a demeaned version +d.plank.dat <- (plank.dat - apply(plank.dat, 1, mean, na.rm = TRUE)) + + +################################################### +### code chunk number 16: Cs13_plot-plankton-data +################################################### +graphics::matplot((1:(52 * 6))[27:295], t(d.plank.dat), type = "l", lty = c(1, 1, 1, 1), lwd = c(1, 1, 3, 3), xlab = "week of study", ylab = "log biomass", xaxt = "n", xlim = c(11, 52 * 6 - 11), bty = "L") +# axis(1,at=(1:(52*6))[seq(27,295,2)]) +axis(1, at = seq(1, 52 * 6, 2)) +abline(v = c(52 * (1:6))) +abline(h = 0) + + +################################################### +### code chunk number 17: Cs14_set-up-plankton-model +################################################### +Q <- matrix(list(0), 4, 4) +diag(Q) <- c("Phyto", "Phyto", "Zoo", "Zoo") +R <- matrix(list(0), 4, 4) +diag(R) <- c("Phyto", "Phyto", "Zoo", "Zoo") +plank.model.0 <- list( + B = "unconstrained", U = "zero", Q = Q, + Z = "identity", A = "zero", R = R, + x0 = "unequal", tinitx = 1 +) + + +################################################### +### code chunk number 18: Cs15_fit-plank-model-0 +################################################### +kem.plank.0 <- MARSS(d.plank.dat, model = plank.model.0) + + +################################################### +### code chunk number 19: Cs16_print-B-0 +################################################### +# Cleaning up the B matrix for printing +B.0 <- coef(kem.plank.0, type = "matrix")$B[1:4, 1:4] +rownames(B.0) <- colnames(B.0) <- c("LP", "SP", "D", "ND") +print(B.0, digits = 2) + + +################################################### +### code chunk number 20: Cs17_print-B-Ives +################################################### +# Cleaning up the B matrix for printing +B.Ives.ML <- matrix(c(.5, NA, NA, NA, -.39, .076, NA, .1, NA, -.02, .77, NA, NA, -.1, NA, .55), 4, 4) +B.Ives.Obs <- matrix(c(.48, NA, NA, NA, -.39, .25, NA, .1, NA, -.17, .74, 0, NA, -.11, 0, .6), 4, 4) +B.Ives <- B.Ives.Obs +rownames(B.Ives) <- colnames(B.Ives) <- c("LP", "SP", "D", "ND") +print(B.Ives, digits = 2, na.print = "--") + + +################################################### +### code chunk number 21: Cs18_test-rm-NAs (eval = FALSE) +################################################### +## # Example code to see what would happen if we removed the NAs +## test.dat <- d.plank.dat[, !is.na(d.plank.dat[1, ])] +## test <- MARSS(test.dat, model = plank.model.0) + + +################################################### +### code chunk number 22: Cs19_fit-plank-model-1 +################################################### +plank.model.1 <- plank.model.0 +plank.model.1$Q <- "unconstrained" +kem.plank.1 <- MARSS(d.plank.dat, model = plank.model.1) + + +################################################### +### code chunk number 23: Cs20_print-B-1 +################################################### +# Cleaning up the B matrix for printing +B <- coef(kem.plank.1, type = "matrix")$B[1:4, 1:4] +rownames(B) <- colnames(B) <- c("LP", "SP", "D", "ND") +B[B == 0] <- NA +B.1 <- B +print(B, digits = 2, na.print = "--") + + +################################################### +### code chunk number 24: Cs21_B-2 +################################################### +B.2 <- matrix(list(0), 4, 4) # set up the list matrix +diag(B.2) <- c("B11", "B22", "B33", "B44") # give names to diagonals +# and names to the estimated non-diagonals +B.2[1, 2] <- "B12" +B.2[2, 3] <- "B23" +B.2[2, 4] <- "B24" +B.2[4, 2] <- "B42" +print(B.2) + + +################################################### +### code chunk number 25: Cs22_fit-plank-model-2 +################################################### +# model 2 +plank.model.2 <- plank.model.1 +plank.model.2$B <- B.2 +kem.plank.2 <- MARSS(d.plank.dat, model = plank.model.2) + + +################################################### +### code chunk number 26: Cs23_print-B-2 +################################################### +# Cleaning up the B matrix for printing +B <- coef(kem.plank.2, type = "matrix")$B[1:4, 1:4] +rownames(B) <- colnames(B) <- c("LP", "SP", "D", "ND") +B[B == 0] <- NA +B.2 <- B +print(B, digits = 2, na.print = "--") + + +################################################### +### code chunk number 27: Cs24_fit-plank-model-3 +################################################### +# model 3 +plank.model.3 <- plank.model.2 +plank.model.3$R <- diag(c(.04, .04, .16, .16)) +kem.plank.3 <- MARSS(d.plank.dat, model = plank.model.3) + + +################################################### +### code chunk number 28: Cs25_prep-covariates +################################################### +# transpose to make time go across columns +# drop=FALSE so that R doesn't change our matrix to a vector +phos <- t(log(ivesDataByWeek[, "Phosph", drop = FALSE])) +d.phos <- (phos - apply(phos, 1, mean, na.rm = TRUE)) + + +################################################### +### code chunk number 29: Cs26_add-covar-model-3 +################################################### +plank.model.4 <- plank.model.3 +plank.model.4$C <- matrix(list("C11", "C21", 0, 0), 4, 1) +plank.model.4$c <- d.phos + + +################################################### +### code chunk number 30: Cs27_plank-model-4 +################################################### +kem.plank.4 <- MARSS(d.plank.dat, model = plank.model.4) + + +################################################### +### code chunk number 31: Cs28_print-C +################################################### +# Cleaning up the C matrix for printing +Cmat <- coef(kem.plank.4, type = "matrix")$C[1:4, 1, drop = FALSE] +rownames(Cmat) <- c("LP", "SP", "D", "ND") +Cmat[Cmat == 0] <- NA +print(Cmat, digits = 2, na.print = "--") + + +################################################### +### code chunk number 32: Cs29_add-fish-to-data +################################################### +# transpose to make time go across columns +# drop=FALSE so that R doesn't change our matrix to a vector +fish <- t(log(ivesDataByWeek[, "Fish biomass", drop = FALSE])) +d.fish <- (fish - apply(fish, 1, mean, na.rm = TRUE)) +# plank.dat.w.fish = rbind(plank.dat,fish) +d.plank.dat.w.fish <- rbind(d.plank.dat, d.fish) + + +################################################### +### code chunk number 33: Cs30_B-covar +################################################### +B <- matrix(list(0), 5, 5) +diag(B) <- list("B11", "B22", "B33", "B44", "Bfish") +B[1, 2] <- "B12" +B[2, 3] <- "B23" +B[2, 4] <- "B24" +B[4, 2] <- "B42" +B[1:4, 5] <- list(0, 0, "C32", "C42") +print(B) + + +################################################### +### code chunk number 34: Cs31_C-covar +################################################### +C <- matrix(list("C11", "C21", 0, 0, 0), 5, 1) + + +################################################### +### code chunk number 35: Cs32_R.covar +################################################### +R <- matrix(list(0), 5, 5) +diag(R) <- list(0.04, 0.04, 0.16, 0.16, 0.36) + + +################################################### +### code chunk number 36: Cs33_Q-covar +################################################### +Q <- matrix(list(0), 5, 5) +Q[1:4, 1:4] <- paste(rep(1:4, times = 4), rep(1:4, each = 4), sep = "") +Q[5, 5] <- "fish" +Q[lower.tri(Q)] <- t(Q)[lower.tri(Q)] +print(Q) + + +################################################### +### code chunk number 37: Cs34_fit-covar-model +################################################### +plank.model.5 <- plank.model.4 +plank.model.5$B <- B +plank.model.5$C <- C +plank.model.5$Q <- Q +plank.model.5$R <- R +kem.plank.5 <- MARSS(d.plank.dat.w.fish, model = plank.model.5) + + +################################################### +### code chunk number 38: Cs35_print-B +################################################### +# Cleaning up the B matrix for printing +B.5 <- coef(kem.plank.5, type = "matrix")$B[1:4, 1:4] +rownames(B.5) <- colnames(B.5) <- c("LP", "SP", "D", "ND") +B.5[B.5 == 0] <- NA +print(B.5, digits = 2, na.print = "--") + + +################################################### +### code chunk number 40: Cs36_logLik-variates +################################################### +tmp <- kem.plank.5 +tmp$marss$data[5, ] <- NA +LL.variates <- MARSSkf(tmp)$logLik + + +################################################### +### code chunk number 41: Cs37_BQ.5 +################################################### +B <- coef(kem.plank.5, type = "matrix")$B[1:4, 1:4] +Q <- coef(kem.plank.5, type = "matrix")$Q[1:4, 1:4] + + +################################################### +### code chunk number 42: Cs38_max.eigen +################################################### +max(eigen(B)$values) + + +################################################### +### code chunk number 43: Cs39_max.eig.kron.b +################################################### +max(eigen(kronecker(B, B))$values) + + +################################################### +### code chunk number 44: Cs40_Vinfty +################################################### +m <- nrow(B) +vecV <- solve(diag(m * m) - kronecker(B, B)) %*% as.vector(Q) +V_inf <- matrix(vecV, nrow = m, ncol = m) + + +################################################### +### code chunk number 45: Cs41_det.b.squared +################################################### +abs(det(B))^2 + + +################################################### +### code chunk number 46: Cs42_det.b.scaled +################################################### +abs(det(B))^(2 / nrow(B)) + + +################################################### +### code chunk number 47: Cs43_covar.sigma.Vinf +################################################### +-sum(diag(Q)) / sum(diag(V_inf)) + + +################################################### +### code chunk number 48: Cs44_worse.case.reactivity +################################################### +max(eigen(t(B) %*% B)$values) - 1 + + diff --git a/inst/doc/Chapter_StructuralBreaks.R b/inst/doc/Chapter_StructuralBreaks.R new file mode 100644 index 0000000..58e6c0e --- /dev/null +++ b/inst/doc/Chapter_StructuralBreaks.R @@ -0,0 +1,166 @@ +################################################### +### code chunk number 2: Cs00_required_packages +################################################### +library(MARSS) +library(xtable) +library(survival) +library(Formula) +library(ggplot2) +library(Hmisc) +library(datasets) + + +################################################### +### code chunk number 3: Cs01_plotdata +################################################### +# load the datasets package +library(datasets) +data(Nile) # load the data +plot(Nile, ylab = "Flow volume", xlab = "") + + +################################################### +### code chunk number 4: Cs02_mod-nile-0 +################################################### +mod.nile.0 <- list( + Z = matrix(1), A = matrix(0), R = matrix("r"), + B = matrix(1), U = matrix(0), Q = matrix(0), + x0 = matrix("a") +) + + +################################################### +### code chunk number 5: Cs03_fit-data-0 +################################################### +# The data is in a ts format, and we need a matrix +dat <- t(as.matrix(Nile)) +rownames(dat) <- "Nile" + +kem.0 <- MARSS(dat, model = mod.nile.0, silent = TRUE) +summary(kem.0) + + +################################################### +### code chunk number 6: Cs04_mod-nile-1 +################################################### +mod.nile.1 <- list( + Z = matrix(1), A = matrix(0), R = matrix("r"), + B = matrix(1), U = matrix("u"), Q = matrix(0), + x0 = matrix("a") +) + + +################################################### +### code chunk number 7: Cs05_fit-data-1 +################################################### +kem.1 <- MARSS(dat, model = mod.nile.1, silent = TRUE) +summary(kem.1) + + +################################################### +### code chunk number 8: Cs06_mod-nile-2 +################################################### +mod.nile.2 <- list( + Z = matrix(1), A = matrix(0), R = matrix("r"), + B = matrix(1), U = matrix(0), Q = matrix("q"), + x0 = matrix("pi") +) + + +################################################### +### code chunk number 9: Cs07_fit-data-2 +################################################### +kem.2em <- MARSS(dat, model = mod.nile.2, silent = TRUE) +kem.2 <- MARSS(dat, + model = mod.nile.2, + inits = kem.2em$par, method = "BFGS", silent = TRUE +) +summary(kem.2) + + +################################################### +### code chunk number 11: Cs08_plotfit +################################################### +library(Hmisc) +par(mfrow = c(3, 1), mar = c(4, 4, 0.5, 0.5), oma = c(1, 1, 1, 1)) +x <- seq(tsp(Nile)[1], tsp(Nile)[2], tsp(Nile)[3]) +# model 0 +plot(Nile, ylab = "Flow volume", xlab = "", xaxp = c(1870, 1970, 10), bty = "L") +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +kem <- kem.0 # model 0 results +lines(x, kem$states[1, ], col = "red", lwd = 2) +legend("topright", paste("model 0, AICc=", format(kem.0$AICc, digits = 1)), bty = "n") + +# model 1 +plot(Nile, ylab = "Flow volume", xlab = "", xaxp = c(1870, 1970, 10), bty = "n") +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +kem <- kem.1 # model 1 results +lines(x, kem$states[1, ], col = "red", lwd = 2) +legend("topright", paste("model 1, AICc=", format(kem.1$AICc, digits = 1)), bty = "n") + +# model 2 +plot(Nile, ylab = "Flow volume", xlab = "", xaxp = c(1870, 1970, 10), bty = "L") +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +kem <- kem.2 # model 0 results +lines(x, kem$states[1, ], col = "red", lwd = 2) +lines(1871:1970, kem$states[1, ] - 2 * kem$states.se[1, ], col = "red", lty = 2) +lines(1871:1970, kem$states[1, ] + 2 * kem$states.se[1, ], col = "red", lty = 2) +legend("topright", paste("model 2, AICc=", format(kem$AICc, digits = 1)), bty = "n") + + +################################################### +### code chunk number 12: Cs09_compute-resids +################################################### +resids.0 <- MARSSresiduals(kem.0, type = "tT")$mar.residuals +resids.1 <- MARSSresiduals(kem.1, type = "tT")$mar.residuals +resids.2 <- MARSSresiduals(kem.2, type = "tT")$mar.residuals + + +################################################### +### code chunk number 13: Cs10_plotoutliertests +################################################### +library(Hmisc) +par(mfrow = c(3, 1), mar = c(3, 4, 1.5, 2)) +x <- seq(tsp(Nile)[1], tsp(Nile)[2], tsp(Nile)[3]) +plot(x, resids.0[1, ], + ylab = "Std. residuals", xlab = "", type = "l", + ylim = c(-4, 4), xaxp = c(1870, 1970, 10), bty = "L" +) +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +abline(h = c(1.97, -1.97, 0), lty = 2) +title("model 0--flat level") + +plot(x, resids.1[1, ], + ylab = "Std. residuals", xlab = "", type = "l", + ylim = c(-4, 4), xaxp = c(1870, 1970, 10), bty = "L" +) +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +abline(h = c(1.97, -1.97, 0), lty = 2) +title("model 1--linearly declining level") + +plot(x, resids.2[1, ], + ylab = "Std. residuals", xlab = "", type = "l", + ylim = c(-4, 4), xaxp = c(1870, 1970, 10), bty = "L" +) +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +abline(h = c(1.97, -1.97, 0), lty = 2) +title("model 2--stochastic level") + + +################################################### +### code chunk number 14: Cs11_plotresids +################################################### +par(mfrow = c(2, 1), mar = c(4, 3, 2, 1)) +x <- seq(tsp(Nile)[1], tsp(Nile)[2], tsp(Nile)[3]) +plot(x, resids.2[1, ], ylab = "", xlab = "", type = "l", ylim = c(-4, 4), xaxp = c(1870, 1970, 10)) +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +abline(h = c(1.97, -1.97), lty = 2) +title("test for outliers") + +plot(x, resids.2[2, ], ylab = "", xlab = "", type = "l", ylim = c(-4, 4), xaxp = c(1870, 1970, 10)) +minor.tick(nx = 10, ny = 0, tick.ratio = .3) +abline(h = c(1.97, -1.97), lty = 2) +title("test for level changes") +mtext("Standardized residuals", side = 2, outer = TRUE, line = -1) + + diff --git a/inst/doc/Chapter_Structural_TS.R b/inst/doc/Chapter_Structural_TS.R new file mode 100644 index 0000000..3dfefab --- /dev/null +++ b/inst/doc/Chapter_Structural_TS.R @@ -0,0 +1,629 @@ +################################################### +### code chunk number 2: Cs00_required-libraries +################################################### +library(MARSS) +library(tidyr) +library(ggplot2) +library(forecast) + + +################################################### +### code chunk number 3: Cs101_structTS-level +################################################### +y <- window(treering, start = 0, end = 20) + +fit1 <- StructTS(y, type = "level") + + +################################################### +### code chunk number 4: Cs102_structTS-level +################################################### +vy <- var(y, na.rm = TRUE) / 100 +mod.list <- list( + x0 = matrix(y[1]), U = "zero", tinitx = 0, + Q = matrix(fit1$coef[1]), R = matrix(fit1$coef[2]), + V0 = matrix(1e+06 * vy) +) +fit2 <- MARSS(as.vector(y), model = mod.list) +# Now estimate the parameters +mod.list <- list( + x0 = matrix(y[1]), U = "zero", tinitx = 0, V0 = matrix(1e+06 * vy), + Q = matrix("s2xi"), R = matrix("s2eps") +) +fit3 <- MARSS(as.vector(y), model = mod.list, method = "BFGS") +fit4 <- MARSS(as.vector(y), + model = mod.list, + control = list(allow.degen = FALSE) +) + + +################################################### +### code chunk number 5: Cs103_structTS-level +################################################### +fit2$kf <- MARSSkfss(fit2) +fit3$kf <- MARSSkfss(fit3) +fit4$kf <- MARSSkfss(fit4) +df <- data.frame( + StructTS = fit1$fitted, fit2 = fit2$kf$xtt[1, ], + fit.bfgs = fit3$kf$xtt[1, ], fit.em = fit4$kf$xtt[1, ] +) +head(df) + + +################################################### +### code chunk number 6: Cs104_structTS-level +################################################### +require(tidyr) +require(ggplot2) +df1 <- as.data.frame(fit1$fitted) +vars <- colnames(df1) +df2 <- as.data.frame(t(fit3$kf$xtt)) +colnames(df2) <- vars +df3 <- as.data.frame(t(fit4$kf$xtt)) +colnames(df3) <- vars +df1$model <- "StructTS" +df2$model <- "MARSS BFGS" +df3$model <- "MARSS EM" +df1$t <- as.vector(time(fit1$fitted)) +df2$t <- df1$t +df3$t <- df1$t +df <- rbind(df1, df2, df3) +df <- df %>% pivot_longer(all_of(vars)) +ggplot(df, aes(x = t, y = value)) + + geom_line() + + facet_wrap(~model) + + ggtitle("Level estimate from model fit with StructTS and MARSS") + + +################################################### +### code chunk number 7: Cs201_structTS-leveltrend +################################################### +y <- log10(forecast:::subset.ts(UKgas, quarter = 2)) +fit1 <- StructTS(y, type = "trend") + + +################################################### +### code chunk number 8: Cs202_structTS-leveltrend +################################################### +vy <- var(y, na.rm = TRUE) / 100 +B <- matrix(c(1, 0, 1, 1), 2, 2) +Z <- matrix(c(1, 0), 1, 2) +# fitx parameters at fit1 values +mod.list <- list( + x0 = matrix(c(y[1], 0), 2, 1), U = "zero", tinitx = 0, + Q = diag(fit1$coef[1:2]), R = matrix(fit1$coef[3]), + V0 = matrix(1e+06 * vy, 2, 2), Z = Z, B = B +) +fit2 <- MARSS(as.vector(y), + model = mod.list, fit = FALSE, + control = list(trace = -1) +) +fit2$par <- fit2$start # otherwise par is NULL since fit=FALSE + + +################################################### +### code chunk number 9: Cs203_structTS-leveltrend +################################################### +mod.list <- list( + x0 = matrix(c(y[1], 0), 2, 1), U = "zero", tinitx = 0, + Q = ldiag(c("s2xi", "s2zeta")), R = matrix("s2eps"), + V0 = matrix(1e+06 * vy, 2, 2) + diag(1e-10, 2), Z = Z, B = B +) +fit3 <- MARSS(as.vector(y), model = mod.list, method = "BFGS") +fit4 <- MARSS(as.vector(y), + model = mod.list, + control = list(allow.degen = FALSE) +) + + +################################################### +### code chunk number 10: Cs204_structTS-leveltrend +################################################### +fit2$kf <- MARSSkfss(fit2) +fit3$kf <- MARSSkfss(fit3) +fit4$kf <- MARSSkfss(fit4) +data.frame( + StructTS = fit1$fitted[, 2], fit2 = fit2$kf$xtt[2, ], + fit.bfgs = fit3$kf$xtt[2, ], fit.em = fit4$kf$xtt[2, ] +)[1:5, ] + + +################################################### +### code chunk number 11: Cs205_structTS-leveltrend +################################################### +require(tidyr) +require(ggplot2) +df1 <- as.data.frame(fit1$fitted) +vars <- colnames(df1) +df2 <- as.data.frame(t(fit3$kf$xtt)) +colnames(df2) <- vars +df3 <- as.data.frame(t(fit4$kf$xtt)) +colnames(df3) <- vars +df1$model <- "StructTS" +df2$model <- "MARSS BFGS" +df3$model <- "MARSS EM" +df1$t <- as.vector(time(fit1$fitted)) +df2$t <- df1$t +df3$t <- df1$t +df <- rbind(df1, df2, df3) +df <- df %>% pivot_longer(all_of(vars)) +ggplot(df, aes(x = t, y = value, color = model, linetype = model, shape = model)) + + geom_line() + + geom_point() + + facet_wrap(~name, scales = "free") + + scale_linetype_manual("model", values = c(1, 1, 0)) + + scale_shape_manual("model", values = c(NA, NA, 16)) + + +################################################### +### code chunk number 12: Cs301_structTS-bsm +################################################### +y <- log10(UKgas) +fit1 <- StructTS(y, type = "BSM") + + +################################################### +### code chunk number 13: Cs302_structTS-bsm +################################################### +makeB <- function(nf) { + B <- matrix(0, nf + 1L, nf + 1L) + B[1L:2L, 1L:2L] <- c(1, 0, 1, 1) + B[3L, ] <- c(0, 0, rep(-1, nf - 1L)) + if (nf >= 3L) { + ind <- 3:nf + B[cbind(ind + 1L, ind)] <- 1 + } + return(B) +} + + +################################################### +### code chunk number 14: Cs303_structTS-bsm +################################################### +nf <- frequency(y) +vy <- var(y) / 100 +B <- makeB(nf) +Z <- matrix(c(1, 0, 1, rep(0, nf - 2L)), 1, nf + 1) + +Q <- ldiag(list("s2xi", "s2zeta", "s2w", 0, 0)) +R <- matrix("s2eps") +V0 <- matrix(1e+06 * vy, nf + 1, nf + 1) + diag(1e-10, nf + 1) +mod.list <- list( + x0 = matrix(c(y[1], rep(0, nf)), ncol = 1), + U = "zero", A = "zero", tinitx = 0, + Q = Q, R = R, V0 = V0, Z = Z, B = B +) +fit3 <- MARSS(as.vector(y), model = mod.list, method = "BFGS") +fit4 <- MARSS(as.vector(y), + model = mod.list, + control = list(allow.degen = FALSE) +) +fit4$kf <- MARSSkfss(fit4) +fit3$kf <- MARSSkfss(fit3) + + +################################################### +### code chunk number 15: Cs304_structTS-bsm +################################################### +require(tidyr) +require(ggplot2) +df1 <- as.data.frame(fit1$fitted) +vars <- colnames(df1) +df2 <- as.data.frame(t(fit3$kf$xtt)[, 1:3]) +colnames(df2) <- vars +df3 <- as.data.frame(t(fit4$kf$xtt)[, 1:3]) +colnames(df3) <- vars +df1$model <- "StructTS" +df2$model <- "MARSS BFGS" +df3$model <- "MARSS EM" +df1$t <- as.vector(time(fit1$fitted)) +df1$Qtr <- as.vector(cycle(fit1$fitted)) +df2$t <- df1$t +df2$Qtr <- df1$Qtr +df3$t <- df1$t +df3$Qtr <- df1$Qtr +df <- rbind(df1, df2, df3) +df <- subset(df, Qtr == 1) %>% pivot_longer(all_of(vars)) +ggplot(df, aes(x = t, y = value, color = model, linetype = model, shape = model)) + + geom_line() + + geom_point() + + facet_wrap(~name, scales = "free") + + scale_linetype_manual("model", values = c(1, 1, 0)) + + scale_shape_manual("model", values = c(NA, NA, 15)) + + +################################################### +### code chunk number 16: Cs401_forecast +################################################### +y <- log10(UKgas) +fit1 <- StructTS(y, type = "BSM") + +nf <- frequency(y) +vy <- var(y) / 100 +B <- makeB(nf) # defined in the BSM section above +Z <- matrix(c(1, 0, 1, rep(0, nf - 2L)), 1, nf + 1) +V0 <- matrix(1e+06 * vy, nf + 1, nf + 1) + diag(1e-10, nf + 1) +mod.list <- list( + x0 = matrix(c(y[1], rep(0, nf)), ncol = 1), + U = "zero", A = "zero", tinitx = 0, + Q = diag(c(fit1$coef[1:3], 0, 0)), + R = matrix(fit1$coef[4]), + V0 = V0, Z = Z, B = B +) +fit2 <- MARSS(as.vector(y), model = mod.list) + + +################################################### +### code chunk number 17: Cs402_forecast +################################################### +fr1 <- predict(fit1, n.ahead = 5) +fr1 + + +################################################### +### code chunk number 18: Cs403_forecast +################################################### +fr2 <- predict(fit2, n.ahead = 5, interval = "prediction") +fr2 + + +################################################### +### code chunk number 19: Cs404_forecast +################################################### +rbind( + pred1 = fr1$pred, pred2 = fr2$pred$estimate[fr2$ft], + se1 = fr1$se, se2 = fr2$pred$se[fr2$ft] +) + + +################################################### +### code chunk number 20: Cs405_forecast +################################################### +fr1 <- forecast:::forecast.StructTS(fit1, h = 10) +fr2 <- forecast(fit2, h = 10) +p1 <- ggplot2::autoplot(fr1, include = 8) +p2 <- ggplot2::autoplot(fr2, include = 8) +gridExtra::grid.arrange(p1, p2, nrow = 1) + + +################################################### +### code chunk number 21: Cs501_fitted +################################################### +fitted1 <- fitted(fit1) +plot(fitted1) + + +################################################### +### code chunk number 22: Cs502_fitted +################################################### +fitted2 <- tsSmooth(fit2, type = "xtt") +fitted2 <- subset(fitted2, .rownames %in% c("X1", "X2", "X3")) + + +################################################### +### code chunk number 23: Cs503_fitted +################################################### +ggplot(fitted2, aes(x = t, y = .estimate)) + + geom_line() + + facet_wrap(~.rownames, ncol = 1, scale = "free_y") + + +################################################### +### code chunk number 24: Cs504_fitted +################################################### +fitted3 <- MARSSkfss(fit2)$xtt +fitted3 <- ts(t(fitted3[1:3, ])) +plot(fitted3) + + +################################################### +### code chunk number 25: Cs505_fitted +################################################### +fitted2 <- fitted(fit2, type = "ytt") +df2 <- data.frame(t = as.numeric(time(fitted1)), fitted = fitted2$.fitted, name = "MARSS") +df1 <- data.frame(t = df2$t, fitted = as.numeric(fitted1[, 1] + fitted1[, 3]), name = "StructTS") +df <- rbind(df1, df2) +df$y <- fitted2$y + +ggplot(df) + + geom_line(aes(x = t, y = fitted)) + + geom_point(aes(x = t, y = y), col = "blue") + + facet_wrap(~name, ncol = 1) + + +################################################### +### code chunk number 26: Cs601_residuals +################################################### +resids1 <- residuals(fit1) + + +################################################### +### code chunk number 27: Cs602_residuals +################################################### +resids2 <- residuals(fit2, type = "tt", standardization = "marginal") + + +################################################### +### code chunk number 28: Cs603_residuals +################################################### +df2 <- data.frame(t = as.numeric(time(resids1)), resids = resids2$.std.resids, name = "MARSS") +df1 <- data.frame(t = df2$t, resids = as.numeric(resids1), name = "StructTS") +df3 <- data.frame(t = df2$t, resids = df1$resids - df2$resids, name = "difference") +df <- rbind(df1, df2, df3) + +ggplot(df, aes(x = t, y = resids)) + + geom_line() + + facet_wrap(~name, ncol = 1, scale = "free_y") + + ggtitle("Marginal standardized model residuals") + + +################################################### +### code chunk number 29: Cs701_multivariate +################################################### +set.seed(100) +TT <- 60 +t <- 1:TT +q <- 0.01 +r <- 0.01 +trend <- 0.2 * sin((1:TT) / 4) +level <- cumsum(rnorm(TT, trend, sqrt(q))) + +# Simulated data +n <- 5 +miss.percent <- 0.5 +ym <- matrix(1, n, 1) %*% level + matrix(rnorm(TT * n, 0, sqrt(r * 100)), n, TT) +ym[sample(n * TT, miss.percent * n * TT)] <- NA + + +################################################### +### code chunk number 30: Cs702_multivariate +################################################### +par(mfrow = c(2, 1), mar = c(3, 3, 1, 1)) +ylims <- c(min(ym, na.rm = TRUE), max(ym, na.rm = TRUE)) +plot(t, trend, ylim = ylims, col = "red", type = "l") +lines(t, level, col = "black") +legend("topright", c("trend", "level"), lty = 1, col = c("red", "black")) +matplot(t, t(ym), pch = 1:n, ylab = "y", xlab = "", ylim = ylims, main = "bad data") +lines(t, level) + + +################################################### +### code chunk number 31: Cs703_multivariate +################################################### +vy <- var(y, na.rm = TRUE) / 100 +mod.list.x <- list( + x0 = matrix(list("x0", 0), nrow = 2), tinitx = 1, + V0 = matrix(1e+06 * vy, 2, 2) + diag(1e-10, 2), + Q = ldiag(list(q, "qt")), + B = matrix(c(1, 0, 1, 1), 2, 2), + U = "zero" +) + + +################################################### +### code chunk number 32: Cs704_multivariate +################################################### +mod.list.y <- list( + A = "zero", + R = "diagonal and equal" +) + + +################################################### +### code chunk number 33: Cs705_multivariate +################################################### +Z <- matrix(c(1, 0), 1, 2, byrow = TRUE) +mod.list <- c(mod.list.x, mod.list.y, list(Z = Z)) +fitu <- MARSS(ym[1, ], model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 34: Cs706_multivariate +################################################### +Z <- matrix(c(1, 0), n, 2, byrow = TRUE) +mod.list <- c(mod.list.x, mod.list.y, list(Z = Z)) +fitm <- MARSS(ym, model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 35: Cs707_multivariate +################################################### +true <- data.frame( + .rownames = rep(c("X1", "X2"), each = TT), t = t, + .estimate = c(level, trend), .se = NA, name = "true" +) +statesu <- tsSmooth(fitu) +statesu$name <- "one bad" +statesm <- tsSmooth(fitm) +statesm$name <- "multiple bad" +df <- rbind(true, statesu, statesm) + +ggplot(df, aes(x = t, y = .estimate, col = name)) + + geom_line() + + facet_wrap(~.rownames, scale = "free_y") + + +################################################### +### code chunk number 36: Cs708_multivariate +################################################### +par(mfrow = c(2, 1), mar = c(3, 3, 1, 1)) +covariate <- matrix(c(rep(0, TT - 10), rep(1, 10)), nrow = 1) +ymc <- ym +D <- matrix(c(-1, -1, 0, 1, 1), ncol = 1) +ymc <- ym + D %*% covariate +matplot(t, t(ymc), pch = 1:n, ylab = "y", xlab = "", main = "data") +lines(level) +plot(t, covariate[1, ], col = "blue", lty = 2, type = "l", main = "covariate") + + +################################################### +### code chunk number 37: Cs709_multivariate +################################################### +Z <- matrix(c(1, 0), n, 2, byrow = TRUE) +mod.list <- c(mod.list.x, mod.list.y, list(Z = Z, d = covariate)) +fitmc <- MARSS(ymc, model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 38: Cs710_multivariate +################################################### +dvals <- data.frame( + x = paste0("y", 1:n), + val = c(D, coef(fitmc, type = "matrix")$D), + name = rep(c("true", "estimate"), each = n) +) +ggplot(dvals, aes(x = x, y = val, col = name)) + + geom_point() + + xlab("observation series") + + ylab("D estimate") + + ggtitle("D true and estimated values") + + +################################################### +### code chunk number 39: Cs711_multivariate +################################################### +statesmc <- tsSmooth(fitmc) +statesmc$name <- "multiple w covariate" +df <- rbind(true, statesu, statesm, statesmc) + +ggplot(df, aes(x = t, y = .estimate, col = name)) + + geom_line() + + facet_wrap(~.rownames, scale = "free_y") + + +################################################### +### code chunk number 40: Cs712_multivariate +################################################### +r2 <- r * c(100, 10, 10, 200, 400) +a <- runif(n, -1, 1) +err <- rnorm(n * TT, mean = rep(a, each = TT), sd = rep(sqrt(r2), each = TT)) +ym2 <- matrix(1, nrow = n) %*% level + matrix(err, nrow = n, byrow = TRUE) +ym2[sample(n * TT, miss.percent * n * TT)] <- NA +matplot(t, t(ym2), pch = 1:n, ylab = "y", xlab = "", main = "data with different error and bias") +lines(level) + + +################################################### +### code chunk number 41: Cs713_multivariate +################################################### +Z <- matrix(c(1, 0), n, 2, byrow = TRUE) +mod.list <- c(mod.list.x, list(Z = Z, R = "diagonal and unequal", A = "scaling")) +fitm2 <- MARSS(ym2, model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 42: Cs714_multivariate +################################################### +rvals <- data.frame( + x = paste0("y", 1:n), + val = c(r2, coef(fitm2)$R), + name = rep(c("true", "estimate"), each = n) +) +ggplot(rvals, aes(x = x, y = val, col = name)) + + geom_point() + + xlab("observation series") + + ylab("R variance estimate") + + ggtitle("R true and estimated values") + + +################################################### +### code chunk number 43: Cs715_multivariate +################################################### +statesm2 <- tsSmooth(fitm2) +statesm2$name <- "multiple w different Rs" +df <- rbind(true, statesu, statesm, statesmc, statesm2) + +ggplot(df, aes(x = t, y = .estimate, col = name)) + + geom_line() + + facet_wrap(~.rownames, scale = "free_y") + + +################################################### +### code chunk number 44: Cs716_multivariate +################################################### +set.seed(100) +TT <- 60 +t <- 1:TT +q <- 0.5 +qt <- 0.01 +r <- 0.1 +b <- 0.5 +trend <- 0.2 * sin((1:TT) / 4) +level1 <- cumsum(rnorm(TT, trend, sqrt(q))) +level2 <- cumsum(rnorm(TT, trend, sqrt(q))) + +# Simulated data +ym <- rbind(level1, level2) + matrix(rnorm(TT * 2, 0, sqrt(r)), 2, TT) + + +################################################### +### code chunk number 45: Cs717_multivariate +################################################### +par(mfrow = c(2, 1), mar = c(3, 3, 1, 1)) +ylims <- c(min(ym, na.rm = TRUE), max(ym, na.rm = TRUE)) +plot(t, ym[1, ], ylim = ylims, type = "p") +lines(t, level1, col = "black") +plot(t, ym[2, ], ylim = ylims, type = "p") +lines(t, level2, col = "black") + + +################################################### +### code chunk number 46: Cs718_multivariate +################################################### +vy <- var(y, na.rm = TRUE) / 100 +Z <- matrix(c(1, 0), 1, 2) +mod.list.x <- list( + x0 = matrix(list("x0", 0), nrow = 2), tinitx = 1, + V0 = matrix(1e+06 * vy, 2, 2) + diag(1e-10, 2), + Q = ldiag(list(q, "qt")), + B = matrix(c(1, 0, 1, 1), 2, 2), + U = "zero" +) +mod.list <- c(mod.list.x, mod.list.y, list(Z = Z)) +fitm1 <- MARSS(ym[1, ], model = mod.list, method = "BFGS", inits = list(x0 = 0)) +fitm2 <- MARSS(ym[2, ], model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 47: Cs719_multivariate +################################################### +Z <- matrix(c(1, 0, 0, 0, 1, 0), 2, 3, byrow = TRUE) +m <- 3 +mod.list.x <- list( + x0 = matrix(list("x0.1", "x0.2", 0), nrow = m), tinitx = 1, + V0 = matrix(1e+06 * vy, m, m) + diag(1e-10, m), + Q = ldiag(list("q", "q", "qt")), + B = matrix(c(1, 0, 1, 0, 1, 1, 0, 0, 1), m, m, byrow = TRUE), + U = "zero" +) +mod.list <- c(mod.list.x, mod.list.y, list(Z = Z)) +fitm3 <- MARSS(ym, model = mod.list, method = "BFGS", inits = list(x0 = 0)) + + +################################################### +### code chunk number 48: Cs720_multivariate +################################################### +true <- data.frame( + .rownames = rep(c("level 1", "level 2", "trend"), each = TT), t = t, + .estimate = c(level1, level2, trend), .se = NA, name = "true" +) +statesm1 <- tsSmooth(fitm1) +statesm1$name <- "ts 1 alone" +statesm1$.rownames[statesm1$.rownames == "X2"] <- "trend" +statesm1$.rownames[statesm1$.rownames == "X1"] <- "level 1" +statesm2 <- tsSmooth(fitm2) +statesm2$name <- "ts 2 alone" +statesm2$.rownames[statesm2$.rownames == "X2"] <- "trend" +statesm2$.rownames[statesm2$.rownames == "X1"] <- "level 2" +statesm3 <- tsSmooth(fitm3) +statesm3$name <- "ts 1 & 2 together" +statesm3$.rownames[statesm3$.rownames == "X3"] <- "trend" +statesm3$.rownames[statesm3$.rownames == "X1"] <- "level 1" +statesm3$.rownames[statesm3$.rownames == "X2"] <- "level 2" +df <- rbind(true, statesm1, statesm2, statesm3) + +ggplot(df, aes(x = t, y = .estimate, col = name)) + + geom_line() + + facet_wrap(~.rownames, scale = "free_y", ncol = 1) + + diff --git a/inst/doc/Chapter_UnivariateDLM.R b/inst/doc/Chapter_UnivariateDLM.R new file mode 100644 index 0000000..2282eaa --- /dev/null +++ b/inst/doc/Chapter_UnivariateDLM.R @@ -0,0 +1,195 @@ +################################################### +### code chunk number 2: Cs_01_readindata +################################################### +data(SalmonSurvCUI) +years <- SalmonSurvCUI[, 1] +TT <- length(years) +# response data: logit(survival) +dat <- matrix(SalmonSurvCUI[, 2], nrow = 1) + + +################################################### +### code chunk number 3: Cs_02_zscore +################################################### +CUI <- SalmonSurvCUI[, "CUI.apr"] +CUI.z <- zscore(CUI) +# number of state = # of regression params (slope(s) + intercept) +m <- 1 + 1 + + +################################################### +### code chunk number 4: Cs_030_plotdata +################################################### +par(mfrow = c(m, 1), mar = c(4, 4, 0.1, 0), oma = c(0, 0, 2, 0.5)) +plot(years, dat, xlab = "", ylab = "Logit(s)", bty = "n", xaxt = "n", pch = 16, col = "darkgreen", type = "b") +plot(years, CUI.z, xlab = "", ylab = "CUI", bty = "n", xaxt = "n", pch = 16, col = "blue", type = "b") +axis(1, at = seq(1965, 2005, 5)) +mtext("Year of ocean entry", 1, line = 3) + + +################################################### +### code chunk number 5: Cs_031_univDLMproc +################################################### +# for process eqn +B <- diag(m) # 2x2; Identity +U <- matrix(0, nrow = m, ncol = 1) # 2x1; both elements = 0 +Q <- matrix(list(0), m, m) # 2x2; all 0 for now +diag(Q) <- c("q1", "q2") # 2x2; diag = (q1,q2) + + +################################################### +### code chunk number 6: Cs_04_univDLMobs +################################################### +# for observation eqn +Z <- array(NA, c(1, m, TT)) # NxMxT; empty for now +Z[1, 1, ] <- rep(1, TT) # Nx1; 1's for intercept +Z[1, 2, ] <- CUI.z # Nx1; regr variable +A <- matrix(0) # 1x1; scalar = 0 +R <- matrix("r") # 1x1; scalar = r + + +################################################### +### code chunk number 7: Cs_05_univDLM-list +################################################### +# only need starting values for regr parameters +inits.list <- list(x0 = matrix(c(0, 0), nrow = m)) +# list of model matrices & vectors +mod.list <- list(B = B, U = U, Q = Q, Z = Z, A = A, R = R) + + +################################################### +### code chunk number 8: Cs_06_univDLM-fit +################################################### +dlm1 <- MARSS(dat, inits = inits.list, model = mod.list) + + +################################################### +### code chunk number 9: Cs_07_plotdlm1 +################################################### +ylabs <- c(expression(alpha[t]), expression(beta[t])) +colr <- c("darkgreen", "blue") +par(mfrow = c(m, 1), mar = c(4, 4, 0.1, 0), oma = c(0, 0, 2, 0.5)) +for (i in 1:m) { + mn <- dlm1$states[i, ] + se <- dlm1$states.se[i, ] + plot(years, mn, + xlab = "", ylab = ylabs[i], bty = "n", xaxt = "n", type = "n", + ylim = c(min(mn - 2 * se), max(mn + 2 * se)) + ) + lines(years, rep(0, TT), lty = "dashed") + lines(years, mn, col = colr[i], lwd = 3) + lines(years, mn + 2 * se, col = colr[i]) + lines(years, mn - 2 * se, col = colr[i]) +} +axis(1, at = seq(1965, 2005, 5)) +mtext("Year of ocean entry", 1, line = 3) + + +################################################### +### code chunk number 10: Cs_08_univDLM-fore-mean +################################################### +# get list of Kalman filter output +kf.out <- MARSSkfss(dlm1) +# forecasts of regr parameters; 2xT matrix +eta <- kf.out$xtt1 +# ts of E(forecasts) +fore.mean <- vector() +for (t in 1:TT) { + fore.mean[t] <- Z[, , t] %*% eta[, t, drop = F] +} + + +################################################### +### code chunk number 11: Cs_09_univDLM-fore-Var +################################################### +# variance of regr parameters; 1x2xT array +Phi <- kf.out$Vtt1 +# obs variance; 1x1 matrix +R.est <- coef(dlm1, type = "matrix")$R +# ts of Var(forecasts) +fore.var <- vector() +for (t in 1:TT) { + tZ <- matrix(Z[, , t], m, 1) # transpose of Z + fore.var[t] <- Z[, , t] %*% Phi[, , t] %*% tZ + R.est +} + + +################################################### +### code chunk number 12: Cs_10_plot-dlm-Forecast-Logit +################################################### +par(mar = c(4, 4, 0.1, 0), oma = c(0, 0, 2, 0.5)) +ylims <- c(min(fore.mean - 2 * sqrt(fore.var)), max(fore.mean + 2 * sqrt(fore.var))) +plot(years, t(dat), + type = "p", pch = 16, ylim = ylims, + col = "blue", xlab = "", ylab = "Logit(s)", xaxt = "n" +) +lines(years, fore.mean, type = "l", xaxt = "n", ylab = "", lwd = 3) +lines(years, fore.mean + 2 * sqrt(fore.var)) +lines(years, fore.mean - 2 * sqrt(fore.var)) +axis(1, at = seq(1965, 2005, 5)) +mtext("Year of ocean entry", 1, line = 3) + + +################################################### +### code chunk number 13: Cs_11_plot-dlm-Forecast-Raw +################################################### +invLogit <- function(x) { + 1 / (1 + exp(-x)) +} +ff <- invLogit(fore.mean) +fup <- invLogit(fore.mean + 2 * sqrt(fore.var)) +flo <- invLogit(fore.mean - 2 * sqrt(fore.var)) +par(mar = c(4, 4, 0.1, 0), oma = c(0, 0, 2, 0.5)) +ylims <- c(min(flo), max(fup)) +plot(years, invLogit(t(dat)), + type = "p", pch = 16, ylim = ylims, + col = "blue", xlab = "", ylab = "Survival", xaxt = "n" +) +lines(years, ff, type = "l", xaxt = "n", ylab = "", lwd = 3) +lines(years, fup) +lines(years, flo) +axis(1, at = seq(1965, 2005, 5)) +mtext("Year of ocean entry", 1, line = 3) + + +################################################### +### code chunk number 14: Cs_12_dlm-forecast-errors +################################################### +# forecast errors +innov <- kf.out$Innov + + +################################################### +### code chunk number 16: Cs_13_plot-dlmQQ +################################################### +# use layout to get nicer plots +layout(matrix(c(0, 1, 1, 1, 0), 1, 5, byrow = TRUE)) +# set up L plotting space +par(mar = c(4, 4, 1, 0), oma = c(0, 0, 0, 0.5)) +# Q-Q plot of innovations +qqnorm(t(innov), main = "", pch = 16, col = "blue") +qqline(t(innov)) +# set up R plotting space +# par(mar=c(4,0,1,1)) #, oma=c(0,0,0,0.5)) +# boxplot of innovations +# boxplot(t(innov), axes=FALSE) + + +################################################### +### code chunk number 17: Cs_14_dlm-Innov-t-test +################################################### +# p-value for t-test of H0: E(innov) = 0 +t.test(t(innov), mu = 0)$p.value + + +################################################### +### code chunk number 19: Cs_15_plot-dlm-ACF +################################################### +# use layout to get nicer plots +layout(matrix(c(0, 1, 1, 1, 0), 1, 5, byrow = TRUE)) +# set up plotting space +par(mar = c(4, 4, 1, 0), oma = c(0, 0, 0, 0.5)) +# ACF of innovations +acf(t(innov), lwd = 2, lag.max = 10) + + diff --git a/inst/doc/Chapter_inits.R b/inst/doc/Chapter_inits.R new file mode 100644 index 0000000..de7a687 --- /dev/null +++ b/inst/doc/Chapter_inits.R @@ -0,0 +1,222 @@ +################################################### +### code chunk number 2: Cs_mci_001 +################################################### +fulldat <- lakeWAplanktonTrans +years <- fulldat[, "Year"] >= 1965 & fulldat[, "Year"] < 1975 +dat <- t(fulldat[years, c("Greens", "Bluegreens")]) +the.mean <- apply(dat, 1, mean, na.rm = TRUE) +the.sigma <- sqrt(apply(dat, 1, var, na.rm = TRUE)) +dat <- (dat - the.mean) * (1 / the.sigma) + + +################################################### +### code chunk number 3: Cs_mci_002 +################################################### +covariates <- rbind( + Temp = fulldat[years, "Temp"], + TP = fulldat[years, "TP"] +) +# demean the covariates +the.mean <- apply(covariates, 1, mean, na.rm = TRUE) +covariates <- covariates - the.mean + + +################################################### +### code chunk number 4: Cs_mci_003 +################################################### +U <- x0 <- "zero" +Q <- "unconstrained" +d <- covariates +A <- "zero" +D <- "unconstrained" +R <- "diagonal and equal" +model.list <- list( + U = U, Q = Q, A = A, R = R, + D = D, d = d, x0 = x0 +) +kem <- MARSS(dat, model = model.list) + + +################################################### +### code chunk number 5: Cs_mci_004 +################################################### +coef(kem, what = "par") + + +################################################### +### code chunk number 6: Cs_mci_005 +################################################### +out <- coef(kem, what = "par") +out$D +out$Q + + +################################################### +### code chunk number 7: Cs_mci_006 +################################################### +inits <- list(Q = 1) +kem <- MARSS(dat, model = model.list, inits = inits) +# or +inits <- list(Q = matrix(c(1, 0, 1), 3, 1)) +kem <- MARSS(dat, model = model.list, inits = inits) + + +################################################### +### code chunk number 8: Cs_mci_007 +################################################### +inits <- list(Q = matrix(c(1, 0.5, 0.7), 3, 1)) +kem <- MARSS(dat, model = model.list, inits = inits) + + +################################################### +### code chunk number 9: Cs_mci_008 +################################################### +inits <- list(Q = matrix(c(1, 0.5, 0.7), 3, 1), D = 1) +kem <- MARSS(dat, model = model.list, inits = inits) + + +################################################### +### code chunk number 10: Cs_mci_009 +################################################### +inits <- list(D = coef(kem, what = "par")$D) +kem <- MARSS(dat, model = model.list, inits = inits) + + +################################################### +### code chunk number 11: Cs_mci_010 +################################################### +# create the par list from the output +inits <- coef(kem, what = "par") +bfgs <- MARSS(dat, model = model.list, inits = inits, method = "BFGS") + + +################################################### +### code chunk number 12: Cs_mci_0101 +################################################### +# create the par list from the output +bfgs <- MARSS(dat, model = model.list, inits = kem, method = "BFGS") + + +################################################### +### code chunk number 13: Cs_mci_011 +################################################### +###################################################################################################### MARSSmcinit function +# Does a simple MonteCarlo initialization of the EM routine +# The function uses a number of MARSS utility functions accessed with MARSS::: +####################################################################################################### +MARSSmcinit <- function(MLEobj, + control = list( + numInits = 500, numInitSteps = 10, + MCbounds = list( + B = c(0, 1), U = c(-1, 1), Q = c(1, 1), + Z = c(0, 1), A = c(-1, 1), R = c(1, 1), x0 = c(-1, 1) + ) + ), + silent = FALSE) { + control.default <- list(numInits = 500, numInitSteps = 10, MCbounds = list(B = c(0, 1), U = c(-1, 1), Q = c(1, 1), Z = c(0, 1), A = c(-1, 1), R = c(1, 1), x0 = c(-1, 1))) + if (!is.null(control)) { + if (!is.list(control)) stop("MARSSmcinit: control must be a list") + if (any(!(names(control) %in% names(control.default)))) stop(paste("MARSSmcinit: allowed control list elements are", names(control.default))) + control.new <- control.default + for (i in names(control)) control.new[[i]] <- control[[i]] + control <- control.new + } + drawProgressBar <- FALSE + if (!silent) { # then we can draw a progress bar + cat("\n") + cat("> Starting Monte Carlo Initializations\n") + prev <- MARSS:::progressBar() # this is an internal function to MARSS + drawProgressBar <- TRUE + } + MODELobj <- MLEobj[["marss"]] + y <- MODELobj$data + par.dims <- attr(MODELobj, "model.dims") + m <- par.dims[["x"]][1] + n <- par.dims[["y"]][1] + TT <- par.dims[["data"]][2] + ## YM matrix for handling missing values + YM <- matrix(as.numeric(!is.na(y)), n, TT) + # Make sure the missing vals in y are zeroed out + y[YM == 0] <- 0 + + free.tmp <- MODELobj$free + dim.tmp <- list(Z = c(n, m), A = c(n, 1), R = c(n, n), B = c(m, m), U = c(m, 1), Q = c(m, m), x0 = c(m, 1)) + bounds.tmp <- control$MCbounds + init <- bestinits <- MLEobj$start + bestLL <- -1.0e10 + + # loop over numInits: # of random draws of initial values + for (loop in 1:control$numInits) { + init.loop <- init + + # Draw random values + en <- c("Z", "A", "R", "B", "U", "Q", "x0") + for (el in en) { + dim.param <- dim.tmp[[el]] + if (!MARSS:::is.fixed(free.tmp[[el]])) { # is.fixed is a utility func in MARSS + bounds.param <- bounds.tmp[[el]] + # use the first fixed and free in a temporally varying model; arbitrary + tmp <- list(f = MARSS:::sub3D(MODELobj$fixed[[el]], t = 1), D = MARSS:::sub3D(MODELobj$free[[el]], t = 1)) + if (el %in% c("Q", "R")) { # random starts drawn from a wishart dist + if (bounds.param[1] < dim.param[1]) { + df <- dim.param[1] + } else { + df <- bounds.param[1] + } + S <- diag(bounds.param[2], dim.param[1]) + # draw a random matrix from wishart + tmp.random <- MARSS:::rwishart(df, S) / df + # reapply the sharing and fixed constraints + par.random <- solve(t(tmp$D) %*% tmp$D) %*% t(tmp$D) %*% (MARSS:::vec(tmp.random) - tmp$f) + } else { + par.random <- matrix(runif(dim(tmp$D)[2], bounds.param[1], bounds.param[2]), dim(tmp$D)[2], 1) + if (el %in% c("B")) { + tmp.max <- max(abs(eigen(par.random, only.values = TRUE)$values)) + # rescale to bring the max abs eigenvalues to between 0 and 1 + par.random <- par.random / (tmp.max / runif(1, .01, .99)) + } + if (el %in% c("x0")) { + x0init <- init$x0 # where the original start is + x.lo <- ifelse(x0init > 0, exp(bounds.param[1]) * x0init, exp(bounds.param[2]) * x0init) + x.hi <- ifelse(x0init > 0, exp(bounds.param[2]) * x0init, exp(bounds.param[1]) * x0init) + par.random <- matrix(runif(dim(tmp$D)[2], x.lo, x.hi), dim(tmp$D)[2], 1) + } + } + } else { + par.random <- matrix(0, 0, 1) + } + init.loop[[el]] <- par.random + } + + ## Call MARSSkem() with these inits + MLEobj$start <- init.loop + MLEobj$control$maxit <- control$numInitSteps + MLEobj$control$minit <- 1 + MLEobj$control$silent <- TRUE # don't output + MLEobj <- MARSSkem(MLEobj) # get new fit using this init + + if (drawProgressBar == TRUE) prev <- MARSS:::progressBar(loop / control$numInits, prev) + + ## Check whether the likelihood is the best observed + ## Only use bootstrap param draws where loglike did not go down during numInitSteps + if (MLEobj$logLik > bestLL) { + # update the best initial parameter estimates + bestinits <- MLEobj$par + bestLL <- MLEobj$logLik + } + } # end numInits loop + + return(bestinits) +} + + +################################################### +### code chunk number 14: Cs_mci_012 +################################################### +dat <- t(harborSeal) +dat <- dat[c(2, nrow(dat)), ] +fit1 <- MARSS(dat) +MCinits <- MARSSmcinit(fit1, control = list(numInits = 10)) +fit2 <- MARSS(dat, inits = MCinits) + + diff --git a/inst/doc/EMDerivation.Rnw b/inst/doc/EMDerivation.Rnw new file mode 100644 index 0000000..1cd3114 --- /dev/null +++ b/inst/doc/EMDerivation.Rnw @@ -0,0 +1,3149 @@ +%\VignetteIndexEntry{EM_Derivation} +%\VignettePackage{MARSS} +\documentclass[]{article} +%set margins to 1in without fullsty + \addtolength{\oddsidemargin}{-.875in} + \addtolength{\evensidemargin}{-.875in} + \addtolength{\textwidth}{1.75in} + + \addtolength{\topmargin}{-.875in} + \addtolength{\textheight}{1.75in} + %\usepackage{fullpage} %more standardized margins + +% choose options for [] as required from the list +% in the Reference Guide, Sect. 2.2 + +\usepackage{Sweave} +\usepackage{multirow} +\usepackage[bottom]{footmisc}% places footnotes at page bottom +\usepackage[round]{natbib} +\usepackage[small]{caption} +%\setkeys{Gin}{width=\textwidth} +%\setkeys{Gin}{width=0.8\textwidth} %make the figs 50 perc textwidth +\setlength{\captionmargin}{0pt} +\setlength{\abovecaptionskip}{0pt} +\setlength{\belowcaptionskip}{15pt} + +% Math stuff +\usepackage{amsmath} % the standard math package +\usepackage{amsfonts} % the standard math package +%%%% bold maths symbol system: +\def\uupsilon{\pmb{\upsilon}} +\def\llambda{\pmb{\lambda}} +\def\bbeta{\pmb{\beta}} +\def\aalpha{\pmb{\alpha}} +\def\zzeta{\pmb{\zeta}} +\def\etaeta{\mbox{\boldmath $\eta$}} +\def\xixi{\mbox{\boldmath $\xi$}} +\def\ep{\mbox{\boldmath $\epsilon$}} +\def\DEL{\mbox{\boldmath $\Delta$}} +\def\PHI{\mbox{\boldmath $\Phi$}} +\def\PI{\mbox{\boldmath $\Pi$}} +\def\LAM{\mbox{\boldmath $\Lambda$}} +\def\LAMm{\mathbb{L}} +\def\GAM{\mbox{\boldmath $\Gamma$}} +\def\OMG{\mbox{\boldmath $\Omega$}} +\def\SI{\mbox{\boldmath $\Sigma$}} +\def\TH{\mbox{\boldmath $\Theta$}} +\def\UPS{\mbox{\boldmath $\Upsilon$}} +\def\XI{\mbox{\boldmath $\Xi$}} +%% Parameters are bold face +\def\ZZ{\mbox{$\mathbf Z$}} \def\zz{\mbox{$\mathbf z$}} +\def\AA{\mbox{$\mathbf A$}} \def\aa{\mbox{$\mathbf a$}} +\def\BB{\mbox{$\mathbf B$}} \def\bb{\mbox{$\mathbf b$}} +\def\CC{\mbox{$\mathbf C$}} \def\cc{\mbox{$\mathbf c$}} +\def\DD{\mbox{$\mathbf D$}} \def\dd{\mbox{$\mathbf d$}} +\def\EE{\mbox{$\mathbf E$}} \def\ee{\mbox{$\mathbf e$}} +\def\FF{\mbox{$\mathbf F$}} \def\ff{\mbox{$\mathbf f$}} +\def\GG{\mbox{$\mathbf G$}} \def\gg{\mbox{$\mathbf g$}} +\def\HH{\mbox{$\mathbf H$}} \def\hh{\mbox{$\mathbf h$}} +\def\II{\mbox{$\mathbf I$}} \def\ii{\mbox{$\mathbf i$}} +\def\IIm{\mbox{$\mathbf I$}} +\def\JJ{\mbox{$\mathbf J$}} +\def\KK{\mbox{$\mathbf K$}} +\def\MM{\mbox{$\mathbf M$}} \def\mm{\mbox{$\mathbf m$}} +\def\OO{\mbox{$\mathbf O$}} +\def\PP{\mbox{$\mathbf P$}} \def\pp{\mbox{$\mathbf p$}} +\def\QQ{\mbox{$\mathbf Q$}} \def\qq{\mbox{$\mathbf q$}} +\def\Qb{\mbox{$\mathbf G$}} \def\Qm{\mathbb{Q}} +\def\RR{\mbox{$\mathbf R$}} \def\rr{\mbox{$\mathbf r$}} +\def\Rb{\mbox{$\mathbf H$}} \def\Rm{\mathbb{R}} +\def\SS{\mbox{$\mathbf S$}} +\def\TT{\mbox{$\mathbf T$}} +\def\UU{\mbox{$\mathbf U$}} \def\uu{\mbox{$\mathbf u$}} +\def\Ub{\mbox{$\mathbf C$}} \def\Ua{\mbox{$\mathbf c$}} \def\Um{\UPS} +%% Random variables in slant +\def\VV{\mbox{$\pmb{V}$}} \def\vv{\mbox{$\pmb{v}$}} +\def\WW{\mbox{$\pmb{W}$}} \def\ww{\mbox{$\pmb{w}$}} +\def\XX{\mbox{$\pmb{X}$}} \def\xx{\mbox{$\pmb{x}$}} +\def\YY{\mbox{$\pmb{Y}$}} \def\yy{\mbox{$\pmb{y}$}} +\def\LL{\mbox{$\pmb{L}$}} \def\ll{\mbox{$\pmb{l}$}} +%% Other stuff +\def\Ab{\mbox{$\mathbf D$}} \def\Aa{\mbox{$\mathbf d$}} \def\Am{\PI} +\def\Ba{\mbox{$\mathbf L$}} \def\Bm{\UPS} \def\Bb{\mbox{$\mathbf J$}} +\def\Ca{\Delta} \def\Cb{\GAM} +\def\Za{\mbox{$\mathbf N$}} \def\Zm{\XI} +\def\Zb{\mbox{$\mathbf M$}} +\def\zer{\mbox{\boldmath $0$}} +\def\E{\,\textup{\textrm{E}}} +\def\vec{\,\textup{\textrm{vec}}} +\def\var{\,\textup{\textrm{var}}} +\def\cov{\,\textup{\textrm{cov}}} +\def\diag{\,\textup{\textrm{diag}}} +\def\trace{\,\textup{\textrm{trace}}} +\def\N{\,\textup{\textrm{N}}} +\def\MVN{\,\textup{\textrm{MVN}}} +\def\EXy{\,\textup{\textrm{E}}_{\text{{\bf XY}}}} +\def\hatxt{\widetilde{\mbox{$\mathbf x$}}_t} +\def\hatxone{\widetilde{\mbox{$\mathbf x$}}_1} +\def\hatxzero{\widetilde{\mbox{$\mathbf x$}}_0} +\def\hatxtm{\widetilde{\mbox{$\mathbf x$}}_{t-1}} +\def\hatxQtm{\widetilde{\mathbb{x}}_{t-1}} +\def\hatyt{\widetilde{\mbox{$\mathbf y$}}_t} +\def\hatyyt{\widetilde{\mbox{$\mathbf y$}\mbox{$\mathbf y$}^\top}_t} +\def\hatyone{\widetilde{\mbox{$\mathbf y$}}_1} +\def\hatwt{\widetilde{\mbox{$\mathbf w$}}_t} +\def\hatOt{\widetilde{\OO}_t} +\def\hatWt{\widetilde{\WW}_t} +\def\hatYXt{\widetilde{\mbox{$\mathbf{y}\mathbf{x}$}}_t} +\def\hatYXttm{\widetilde{\mbox{$\mathbf{y}\mathbf{x}$}}_{t,t-1}} +\def\hatPt{\widetilde{\PP}_t} +\def\hatPtm{\widetilde{\PP}_{t-1}} +\def\hatPQtm{\widetilde{\mathbb{P}}_{t-1}} +\def\hatPttm{\widetilde{\PP}_{t,t-1}} +\def\hatPQttm{\widetilde{\mathbb{P}}_{t,t-1}} +\def\hatPtmt{\widetilde{\PP}_{t-1,t}} +\def\hatVt{\widetilde{\VV}_t} +\def\hatVttm{\widetilde{\VV}_{t,t-1}} +\def\hatBmt{\widetilde{\Bm}_t} +\def\hatCat{\widetilde{\Ca}_t} +\def\hatCbt{\widetilde{\Cb}_t} +\def\hatZmt{\widetilde{\Zm}_t} +\def\YYr{\dot{\mbox{$\pmb{Y}$}}} +\def\yyr{\dot{\mbox{$\pmb{y}$}}} +\def\aar{\dot{\mbox{$\mathbf a$}}} +\def\ZZr{\dot{\mbox{$\mathbf Z$}}} +\def\RRr{\dot{\mbox{$\mathbf R$}}} +\def\IR{\nabla} +\usepackage[round]{natbib} % to get references that are like in ecology papers +% \citet{} for inline citation name (year); \citep for citation in parens (name year) + +%allow lines in matrix +\makeatletter +\renewcommand*\env@matrix[1][*\c@MaxMatrixCols c]{% + \hskip -\arraycolsep + \let\@ifnextchar\new@ifnextchar + \array{#1}} +\makeatother +\setcounter{tocdepth}{1} %no subsections in toc + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +\SweaveOpts{concordance=TRUE} +%\SweaveOpts{concordance=TRUE} +\author{Elizabeth Eli Holmes\footnote{Northwest Fisheries Science Center, NOAA Fisheries, Seattle, WA 98112, + eli.holmes@noaa.gov, http://faculty.washington.edu/eeholmes}} +\title{Derivation of an EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models} +\date{original 16 Feb 2013 \\ +{\small \emph{typo in Eqn 124}, 14 Apr 2018 \\ +\emph{added derivation of variance of Y conditioned on y and x}, 3 Feb 2020 \\ +\emph{typo in eqn 29-31}, 20 Oct 2020}} +\maketitle +\begin{abstract} +This report presents an Expectation-Maximization (EM) algorithm for estimation of the maximum-likelihood parameter values of constrained multivariate autoregressive Gaussian state-space (MARSS) models. The MARSS model can be written: x(t)=Bx(t-1)+u+w(t), y(t)=Zx(t)+a+v(t), where w(t) and v(t) are multivariate normal error-terms with variance-covariance matrices Q and R respectively. MARSS models are a class of dynamic linear model and vector autoregressive model state-space model. Shumway and Stoffer presented an unconstrained EM algorithm for this class of models in 1982, and a number of researchers have presented EM algorithms for specific types of constrained MARSS models since then. In this report, I present a general EM algorithm for constrained MARSS models, where the constraints are on the elements within the parameter matrices (B,u,Q,Z,a,R). The constraints take the form vec(M)=f+Dm, where M is the parameter matrix, f is a column vector of fixed values, D is a matrix of multipliers, and m is the column vector of estimated values. This allows a wide variety of constrained parameter matrix forms. The presentation is for a time-varying MARSS model, where time-variation enters through the fixed (meaning not estimated) f(t) and D(t) matrices for each parameter. The algorithm allows missing values in y and partially deterministic systems where 0s appear on the diagonals of Q or R. +\end{abstract} +Keywords: Time-series analysis, Kalman filter, EM algorithm, maximum-likelihood, vector autoregressive model, dynamic linear model, parameter estimation, state-space +\vfill +{\noindent \small citation: Holmes, E. E. 2013. Derivation of the EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models. Technical Report. arXiv:1302.3919 } + \newpage +\section{Overview} + +EM algorithms extend maximum-likelihood estimation to models with hidden states and are widely used in engineering and computer science applications. This report presents an EM algorithm for a general class of Gaussian constrained multivariate autoregressive state-space (MARSS) models, with a hidden multivariate autoregressive process (state) model and a multivariate observation model. This is an important class of time-series model used in many different scientific fields. The reader is referred to \citet{McLachlanKrishnan2008} for general background on EM algorithms and to \citet{Harvey1989} for a discussion of EM algorithms for time-series data. \citet{Borman2009} has a nice tutorial on the EM algorithm. + +Before showing the derivation for the constrained case, I first show a derivation of the EM algorithm for unconstrained\footnote{``unconstrained'' means that each element in the parameter matrix is estimated and no elements are fixed or shared.} MARSS model. This EM algorithm was published by \citet{ShumwayStoffer1982}, but my derivation is more similar to Ghahramani et al's \citep{GhahramaniHinton1996, RoweisGhahramani1999} slightly different presentation. One difference in my presentation and all these previous presentations, however, is that I treat the data as a random variable throughout; this means that there are no ``special" update equations for the missing values case. Another difference is that I present the update equations for both stochastic initial states and fixed initial states. I then extend the derivation to constrained MARSS models where there are fixed and shared elements in the parameter matrices and to the case of degenerate MARSS models where some processes in the model are deterministic rather than stochastic. See also \citet{Wuetal1996} and \citet{Zuuretal2003a} for other examples of the EM algorithm for different classes of constrained MARSS models. + +When working with MARSS models, one should be cognizant that misspecification of the prior on the initial hidden states can have catastrophic and difficult to detect effects on the parameter estimates. There is often no sign that something is amiss with the MLE estimates output by an EM algorithm. There has been much work on how to avoid these initial conditions effects; see especially literature on vector autoregressive state-space models in the economics literature. The trouble often occurs when the prior on the initial states is inconsistent with the distribution of the initial states that is implied by the maximum-likelihood model. This often happens when the model implies a specific covariance structure on the initial states, but since the maximum-likelihood parameters are unknown, this covariance structure is unknown. Using a diffuse prior does not help since your diffuse prior still has some covariance structure (often independence is being imposed). In some ways the EM algorithm is less sensitive to a misspecified prior because it uses the smoothed states conditioned on all the data. However, if the prior is inconsistent with the model, the EM algorithm will not (cannot) find the MLEs. It is very possible however that it will find parameter estimates that are closer to what you intend (estimates uninfluenced by the prior), but they will not be MLEs. The derivation presented here allows one to circumvent these problems by treating the initial states as fixed (and estimated) parameters. The problematic initial state variance-covariance matrix is removed from the model, albeit at the cost of additional estimated parameters. + +Finally, when working with MARSS models, one needs to ensure that the model is identifiable; i.e., a unique solution exists. For a given MARSS model, some of the parameter elements will need to be fixed (not estimated) in order to produce a model with one solution. How to do that depends on the MARSS model being fitted and is up to the user. + +\subsection{The MARSS model} + +The linear MARSS model with a stochastic initial state\footnote{`Stochastic' means the initial state has a distribution rather than a fixed value. Because the process must start somewhere, one needs to specify the initial state. In equation \ref{eq:MARSS}, I show the initial state specified as a distribution. However, the derivation will also discuss the case where the initial state is specified as an unknown fixed parameter.} is +\begin{subequations}\label{eq:MARSS} +\begin{gather} +\xx_t = \BB\xx_{t-1} + \uu + \ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ) \label{eq:MARSSx}\\ +\yy_t = \ZZ\xx_t + \aa + \vv_t, \text{ where } \VV_t \sim \MVN(0,\RR) \label{eq:MARSSy}\\ +\XX_0 \sim \MVN(\xixi,\LAM) \label{eq:MARSSx1} +\end{gather} +\end{subequations} +The $\yy$ equation is called the observation process, and $\yy_t$ is a $n \times 1$ vector. The $\xx$ equation is called the state or process equation, and $\xx_t$ is a $m \times 1$ vector. The equation for $\xx$ describes a multivariate autoregressive process (also called a random walk or Markov process). $\ww$ are the process errors and are specific realizations of the random variable $\WW$; $\vv$ is defined similarly. The initial state can either defined at $t=0$, as is done in equation \ref{eq:MARSS}, or at $t=1$. When presenting the MARSS model, I use $t=0$ but the derivations will show the EM algorithm for both cases. $\QQ$ and $\RR$ are variance-covariance matrices that specify the stochasticity in the observation and state equations. + +In the MARSS model, $\xx$ and $\yy$ equations describe two stochastic processes. By tradition, one conditions on observations of $\yy$, and $\xx$ is treated as completely hidden, hence the name `hidden Markov process' of which a MARSS model is a special type. However, you could condition on (partial) observations of $\xx$ and treat $\yy$ as a (partially) hidden process---with as usual proper constraints to ensure identifiability. Nonetheless in this report, I follow tradition and treat $\xx$ as hidden and $\yy$ as (partially) observed. If $\xx$ is partially observed then the update equations stay the same but the expectations shown in section \ref{sec:compexpectations} would be computed conditioned on the partially observed $\xx$. + +The first part of this report will review the derivation of an EM algorithm for the time-constant MARSS model (equation \ref{eq:MARSS}). However the main objective of this report is to show the derivation of an EM algorithm to solve a much more general MARSS model (section \ref{sec:tvMARSS}), which is a MARSS model with linear constraints on time-varying parameters: +\begin{equation}\label{eq:MARSS.ex} +\begin{gathered} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t, \text{ where } \WW_t \sim \mathrm{MVN}(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \HH_t\vv_t, \text{ where } \VV_t \sim \mathrm{MVN}(0,\RR_t)\\ +\xx_{0} = \xixi + \FF\ll, \text{ where } \ll \sim \mathrm{MVN}(0,\LAM) +\end{gathered} +\end{equation} +The initial state can either defined at $t=0$, as is done in equation \ref{eq:MARSS.ex}, or at $t=1$. + +The linear constraints appear as the vectorization of each parameter ($\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$, $\LAM$) is described by the relation $\ff_t+\DD_t\mm$. This relation specifies linear constraints of the form $\beta_i + \beta_{a,i} a + \beta_{b,i} b + \dots$ on the elements in each MARSS parameter matrix. Equation \ref{eq:MARSS.ex} is a much broader class of MARSS models that includes MARSS models with exogenous variable (covariates), AR-p models, moving average models, constrained MARSS models and models that are combinations of these. The derivation also includes partially deterministic systems where $\GG_t$, $\HH_t$ and $\FF$ may have all zero rows. + +\subsection{The joint log-likelihood function} +Equation \ref{eq:MARSS.ex} describes a multivariate stochastic process and $\YY_t$ and $\XX_t$ are random variables whose distributions are given by Equation \ref{eq:MARSS.ex}. Denote a specific realization of these random variables as $\yy$ and $\xx$ which denotes a set of all $y$'s and $x$'s from $t=1$ to $T$. The joint log-likelihood\footnote{This is not the log likelihood output by the Kalman filter. The log likelihood output by the Kalman filter is the $\log\LL(\yy;\Theta)$ (notice $\xx$ does not appear), which is known as the marginal log likelihood.} of $\yy$ and $\xx$ can then be written then as follows\footnote{The log-likelihood function is shown here for the MARSS with non-time varying parameters (equation \ref{eq:MARSS}).}, where $\XX_t$ denotes the random variable and $\xx_t$ is a realization from that random variable (and similarly for $\YY_t$):\footnote{To alleviate clutter, I have left off subscripts on the $f$'s. To emphasize that the $f$'s represent different density functions, one would often use a subscript showing what parameters are in the functions; i.e., $f(\xx_t|\XX_{t-1}=\xx_{t-1})$ becomes $f_{B,u,Q}(\xx_t|\XX_{t-1}=\xx_{t-1})$.} +\begin{equation} +f(\yy,\xx) = f(\yy|\XX=\xx)f(\xx), +\end{equation} +where +\begin{equation} +\begin{split} +f(\xx)&=f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_1^{t-1}=\xx_1^{t-1})\\ +f(\yy|\XX=\xx) &= \prod_{t=1}^T f(\yy_t|\XX=\xx) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:jointL} +\begin{split}f(\yy,\xx) &= \prod_{t=1}^T f(\yy_t|\XX=\xx) \times f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_1^{t-1}=\xx_1^{t-1}) \\ +&=\prod_{t=1}^T f(\yy_t|\XX_t=\xx_t) \times f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_{t-1}=\xx_{t-1}). +\end{split} +\end{equation} +Here $\xx_{t1}^{t2}$ denotes the set of $\xx_t$ from $t=t1$ to $t=t2$ (and thus $\xx$ is shorthand for $\xx_1^T$). The third line follows because conditioned on $\xx$, the $\yy_t$'s are independent of each other (because the $\vv_t$ are independent of each other). In the last line, $\xx_1^{t-1}$ becomes $\xx_{t-1}$ from the Markov property of the equation for $\xx_t$ (equation \ref{eq:MARSSx}), and $\xx$ becomes $\xx_t$ because $\yy_t$ depends only on $\xx_t$ (equation \ref{eq:MARSSy}). + +Since $(\XX_t|\XX_{t-1}=\xx_{t-1})$ is multivariate normal and $(\YY_t|\XX_t=\xx_t)$ is multivariate normal (equation \ref{eq:MARSS}), we can write down the joint log-likelihood function using the likelihood function for a multivariate normal distribution \citep[section 4.3]{JohnsonWichern2007}. +\begin{equation}\label{eq:logL} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_1^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ|\\ +&\quad -\frac{1}{2}(\xx_0 - \xixi)^\top \LAM^{-1}(\xx_0 - \xixi) - \frac{1}{2}\log |\LAM| - \frac{n}{2}\log 2\pi +\end{split} +\end{equation} +$n$ is the number of data points. This is the same as equation 6.64 in \citet{ShumwayStoffer2006}. The above equation is for the case where $\xx_0$ is stochastic (has a known distribution). However, if we instead treat $\xx_0$ as fixed but unknown (section 3.4.4 in Harvey, 1989), it is then a parameter and there is no $\LAM$. The likelihood then is slightly different. $\xx_0$ is defined as a parameter $\xixi$ and +\begin{equation}\label{eq:logL.V0.is.0} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_1^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ| +\end{split} +\end{equation} +$\xixi$ appears in the likelihood for $\xx_{t-1}$ when $t=1$ in the summation. Note that in this case, $\xx_0$ is no longer a realization of a random variable $\XX_0$; it is a fixed (but unknown) parameter. Equation \ref{eq:logL.V0.is.0} is written as if all the $\xx_0$ are fixed, however when the general derivation is presented, it is allowed that some $\xx_0$ are fixed ($\LAM$=0) and others are stochastic. + +If $\RR$ is constant through time, then $\sum_1^T\frac{1}{2} \log |\RR|$ in the likelihood equation reduces to $\frac{T}{2}\log |\RR|$, however $\RR$ might be time-varying or one may need to include a time-dependent weighting on $\RR$\footnote{If for example, one wanted to include a temporally dependent weighting on $\RR$ replace $|\RR|$ with $|\alpha_t\RR|=\alpha_t^n|\RR|$, where $\alpha_t$ is the weighting at time $t$ and is fixed not estimated.}. The same applies to $\sum_1^T\frac{1}{2}\log |\QQ|$. + +All bolded elements are column vectors (lower case) and matrices (upper case). $\AA^\top$ is the transpose of matrix $\AA$, $\AA^{-1}$ is the inverse of $\AA$, and $|\AA|$ is the determinant of $\AA$. Parameters are non-italic while elements that are slanted are realizations of a random variable ($\xx$ and $\yy$ are slated)\footnote{In matrix algebra, a capitol bolded letter indicates a matrix. Unfortunately in statistics, the capitol letter convention is used for random variables. Fortunately, this derivation does not need to reference random variables except indirectly when using expectations. Thus, I use capitols to refer to matrices not random variables. The one exception is the reference to $\XX$ and $\YY$. In this case a bolded {\it slanted} capitol is used.} + +\subsection{Missing values}\label{sec:missing} +In Shumway and Stoffer and other presentations of the EM algorithm for MARSS models \citep{ShumwayStoffer2006,Zuuretal2003a}, the missing values case is treated separately from the non-missing values case. In these derivations, a series of modifications are given for the EM update equations when there are missing values. In my derivation, I present the missing values treatment differently, and there is only one set of update equations and these equations apply in both the missing values and non-missing values cases. My derivation does this by keeping $\E[\YY_t|\text{data}]$ and $\E[\YY_t\XX_t^\top|\text{data}]$ in the update equations (much like $\E[\XX_t|\text{data}]$ is kept in the equations) while Shumway and Stoffer replace these expectations involving $\YY_t$ by their values, which depend on whether or not the data are a complete observation of $\YY_t$ with no missing values. Section \ref{sec:compexpectations} shows how to compute the expectations involving $\YY_t$ when the data are an incomplete observation of $\YY_t$. + +\section{The EM algorithm}\label{sec:EMalgorithm} +The EM algorithm cycles iteratively between an expectation step (the integration in the equation) followed by a maximization step (the arg max in the equation): +\begin{equation}\label{eq:EMalg} +\Theta_{j+1} = \arg \underset{\Theta}{\max} \int_{\xx}{\int_{\yy}{\log\LL(\xx,\yy;\Theta) f(\xx,\yy|\YY(1)=\yy(1),\Theta_j)d\xx d\yy}} +\end{equation} +$\YY(1)$ indicates those $\YY$ that have an observation and $\yy(1)$ are the actual observations. Note that $\Theta$ and $\Theta_j$ are different. If $\Theta$ consists of multiple parameters, we can also break this down into smaller steps. Let $\Theta=\{\alpha,\beta\}$, then +\begin{equation}\label{eq:EMalg.j} +\alpha_{j+1} = \arg \underset{\alpha}{\max} \int_{\xx}{\int_{\yy}{\log\LL(\xx,\yy,\beta_j;\alpha) f(\xx,\yy|\YY(1)=\yy(1),\alpha_j,\beta_j)d\xx d\yy}} +\end{equation} +Now the maximization is only over $\alpha$, the part that appears after the ``;'' in the log-likelihood. + +\textbf{Expectation step} The integral that appears in equation \ref{eq:EMalg} is an expectation. The first step in the EM algorithm is to compute this expectation. This will involve computing expectations like $\E[\XX_t\XX_t^\top|\YY_t(1)=\yy_t(1),\Theta_j]$ and $\E[\YY_t\XX_t^\top|\YY_t(1)=\yy_t(1),\Theta_j]$. The $j$ subscript on $\Theta$ denotes that these are the parameters at iteration $j$ of the algorithm. + +\textbf{Maximization step}: A new parameter set $\Theta_{j+1}$ is computed by finding the parameters that maximize the \textit{expected} log-likelihood function (the part in the integral) with respect to $\Theta$. The equations that give the parameters for the next iteration ($j+1$) are called the update equations and this report is devoted to the derivation of these update equations. + +After one iteration of the expectation and maximization steps, the cycle is then repeated. New expectations are computed using $\Theta_{j+1}$, and then a new set of parameters $\Theta_{j+2}$ is generated. This cycle is continued until the likelihood no longer increases more than a specified tolerance level. This algorithm is guaranteed to increase in likelihood at each iteration (if it does not, it means there is an error in one's update equations). The algorithm must be started from an initial set of parameter values $\Theta_1$. The algorithm is not particularly sensitive to the initial conditions but the surface could definitely be multi-modal and have local maxima. See section \ref{sec:implementation} on using Monte Carlo initialization to ensure that the global maximum is found. + +\textbf{Dividing the parameters into parts}: Above the parameter set is written as $\Theta$. However $\Theta$ is composed of multiple components: $\BB$, $\uu$, $\RR$, etc. The EM iteration $j$ is broken into subparts for each parameter matrix and both the maximization and expectation steps are done for each part. For example, the expectation step is run with parameters $\{\BB_j, \uu_j, \RR_j, \dots\}$ and then $\BB$ is updated to $\BB_{j+1}$ with the maximization step. The expectation step is run with parameters $\{\BB_{j+1}, \uu_j, \RR_j, \dots \}$ and the $\uu$is updated to $\uu_{j+1}$ with the maximization step. The expectation step is run with parameters $\{\BB_{j+1}, \uu_{j+1}, \RR_j, \dots \}$ and the $\RR$ is updated. This is continued until all parameters in $\Theta$ are updated and that completes the $j+1$ update. + +\subsection{The expected log-likelihood function}\label{sec:expLL} +The function that is maximized in the ``M'' step is the expected value of the log-likelihood function. This expectation is conditioned on two things: 1) the observed $\YY$'s which are denoted $\YY(1)$ and which are equal to the fixed values $\yy(1)$ and 2) the parameter set $\Theta_j$. Note that since there may be missing values in the data, $\YY(1)$ can be a subset of $\YY$, that is, only some $\YY$ have a corresponding $\yy$ value at time $t$. Mathematically what we are doing is $\EXy[g(\XX,\YY)|\YY(1)=\yy(1),\Theta_j]$. This is a multivariate conditional expectation because $\XX,\YY$ is multivariate (a $m \times n \times T$ vector). The function $g(\Theta)$ that we are taking the expectation of is $\log\LL(\YY,\XX ; \Theta)$. Note that $g(\Theta)$ is a random variable involving the random variables, $\XX$ and $\YY$, while $\log\LL(\yy,\xx ; \Theta)$ is not a random variable but rather a specific value since $\yy$ and $\xx$ are a set of specific values. + +We denote this expected log-likelihood by $\Psi$. The goal is to find the $\Theta$ that maximize $\Psi$ and this becomes the new $\Theta$ for the $j+1$ iteration of the EM algorithm. The equations to compute the new $\Theta$ are termed the update equations. Using the log likelihood equation \ref{eq:logL} and expanding out all the terms, we can write out $\Psi$ in verbose form as: +\begin{equation}\label{eq:expLL} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta);\YY(1)=\yy(1),\Theta_j] = \Psi = \\ +&\quad -\frac{1}{2}\sum_1^T\bigg( \E[\YY_t^\top \RR^{-1} \YY_t] - \E[\YY_t^\top \RR^{-1}\ZZ\XX_t] - \E[(\ZZ\XX_t)^\top\RR^{-1}\YY_t] - \E[\aa^\top\RR^{-1}\YY_t] - \E[\YY_t^\top\RR^{-1}\aa]\\ +&\quad + \E[(\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t] + \E[\aa^\top\RR^{-1}\ZZ\XX_t] + \E[(\ZZ\XX_t)^\top\RR^{-1}\aa] + \E[\aa^\top\RR^{-1}\aa]\bigg) + - \frac{T}{2}\log|\RR|\\ +&\quad - \frac{1}{2}\sum_1^T\bigg(\E[\XX_t^\top\QQ^{-1}\XX_t] - \E[\XX_t^\top\QQ^{-1}\BB\XX_{t-1}] - \E[(\BB\XX_{t-1})^\top\QQ^{-1}\XX_t]\\ +&\quad - \E[\uu^\top\QQ^{-1}\XX_t] - \E[\XX_t^\top\QQ^{-1}\uu] + \E[(\BB\XX_{t-1})^\top\QQ^{-1}\BB\XX_{t-1}]\\ +&\quad + \E[\uu^\top\QQ^{-1}\BB\XX_{t-1}] + \E[(\BB\XX_{t-1})^\top\QQ^{-1}\uu] + \uu^\top\QQ^{-1}\uu\bigg) - \frac{T}{2}\log|\QQ| \\ +&\quad - \frac{1}{2}\bigg(\E[\XX_0^\top\VV_0^{-1}\XX_0] - \E[\xixi^\top\LAM^{-1}\XX_0] - \E[\XX_0^\top\LAM^{-1}\xixi] + \xixi^\top\LAM^{-1}\xixi\bigg) - \frac{1}{2}\log|\LAM| +-\frac{n}{2}\log\pi +\end{split} +\end{equation} +All the $\E[\quad]$ appearing here denote $\EXy[g()|\YY(1)=\yy(1),\Theta_j]$. In the rest of the derivation, I drop the conditional and the $XY$ subscript on $\E$ to remove clutter, but it is important to remember that whenever $\E$ appears, it refers to a specific conditional multivariate expectation. If $\xx_0$ is treated as fixed, then $\XX_0=\xixi$ and the last line involving $\LAM$ is dropped but it will appear in place of $\XX_{t-1}$ when $t=1$ in the summation. + +Keep in mind that $\Theta$ and $\Theta_j$ are different. $\Theta$ is a parameter appearing in function $g(\XX,\YY,\Theta)$, i.e., the parameters in equation \ref{eq:logL}. $\XX$ and $\YY$ are random variables which means that $g(\XX,\YY,\Theta)$ is a random variable. We take the expectation of $g(\XX,\YY,\Theta)$, meaning we take integral over the joint distribution of $\XX$ and $\YY$. We need to specify what that distribution is and the conditioning on $\Theta_j$ (meaning the $\Theta_j$ appearing to the right of the $|$ in $\E[g()|\Theta_j]$) is specifying this distribution. This conditioning affects the value of the expectation of $g(\XX,\YY,\Theta)$, but it does not affect the value of $\Theta$, which are the $\RR$, $\QQ$, $\uu$, etc. values on the right side of equation \ref{eq:expLL}. We will first take the expectation of $g(\XX,\YY,\Theta)$ conditioned on $\Theta_j$ (using integration) and then take the differential of that expectation with respect to $\Theta$. + +\subsection{The expectations used in the derivation}\label{sec:expectations} +The following expectations appear frequently in the update equations and are given special names\footnote{This notation is different than what you see in Shumway and Stoffer (2006), section 6.2. What I call $\hatVt$, they refer to as $P_t^n$, and my $\hatPt$ would be $P_t^n + \hatxt \hatxt^\prime$ in their notation.}: +\begin{subequations}\label{eq:expectations} +\begin{align} +&\hatxt = \EXy[\XX_t | \YY(1)=\yy(1), \Theta_j]\\ +&\hatyt = \EXy[\YY_t | \YY(1)=\yy(1), \Theta_j]\\ +&\hatPt=\EXy[\XX_t\XX_t^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatPttm=\EXy[\XX_{t}\XX_{t-1}^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatVt = \var_{XY}[\XX_t|\YY(1)=\yy(1), \Theta_j] = \hatPt-\hatxt\hatxt^\top\label{eq:hatVt}\\ +&\hatOt=\EXy[\YY_t\YY_t^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatWt = \var_{XY}[\YY_t|\YY(1)=\yy(1), \Theta_j] = \hatOt-\hatyt\hatyt^\top\label{eq:hatWt}\\ +&\hatYXt = \EXy[\YY_t\XX_t^\top| \YY(1)=\yy(1), \Theta_j]\\ +&\hatYXttm = \EXy[\YY_t\XX_{t-1}^\top| \YY(1)=\yy(1), \Theta_j] +\end{align} +\end{subequations} +The subscript on the expectation, $\E$, denotes that this is a multivariate expectation taken over $\XX$ and $\YY$. The right sides of equations \ref{eq:hatVt} and \ref{eq:hatWt} arise from the computational formula for variance and covariance: +\begin{align}\label{eq:comp.formula.variance} +\var[X] &= \E[XX^\top] - \E[X]\E[X]^\top\\ +\cov[X,Y] &= \E[XY^\top] - \E[X]\E[Y]^\top. +\end{align} +Section \ref{sec:compexpectations} shows how to compute the expectations in equation \ref{eq:expectations}. + +\begin{table} + \caption{Notes on multivariate expectations. For the following examples, let $\XX$ be a vector of length three, $X_1,X_2,X_3$. $f()$ is the probability distribution function (pdf). $C$ is a constant (not a random variable).} + \label{tab:MultivariateExpectations} +\begin{center}\begin{tabular}{lr} +\hline\\ +$\E_X[g(\XX)]=\int{\int{\int{g(\xx)f(x_1,x_2,x_3) dx_1 dx_2 dx_3}}}$\\ +$\E_X[X_1]=\int{\int{\int{x_1 f(x_1,x_2,x_3) dx_1 dx_2 dx_3}}}=\int{x_1 f(x_1) dx_1}=\E[X_1]$ \\ +$\E_X[X_1+X_2]=\E_X[X_1]+\E_X[X_2]$\\ +$\E_X[X_1+C]=\E_X[X_1]+C$\\ +$\E_X[C X_1]=C\E_X[X_1]$\\ +$\E_X[\XX|\XX=\xx]=\xx$ \\ +\\ +\hline +\end{tabular} +\end{center} +\end{table} + +\section{The unconstrained update equations}\label{sec:generalupdate} +In this section, I show the derivation of the update equations when all elements of a parameter matrix are estimated and are all allowed to be different, i.e., the unconstrained case. These are similar to the update equations one will see in \citet{ShumwayStoffer2006}. Section \ref{sec:constrained} shows the update equations when there are unestimated (fixed) or estimated but shared values in the parameter matrices, i.e., the constrained update equations. + +To derive the update equations, one must find the $\Theta$, where $\Theta$ is comprised of the MARSS parameters $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$, and $\LAM$, that maximizes $\Psi$ (equation \ref{eq:expLL}) by partial differentiation of $\Psi$ with respect to $\Theta$. However, I will be using the EM equation where one maximizes each parameter matrix in $\Theta$ one-by-one (equation \ref{eq:EMalg.j}). In this case, the parameters that are not being maximized are fixed (and set at their current iteration value), and then one takes the derivative of $\Psi$ with respect to the parameter of interest. Then solve for the parameter value that sets the partial derivative to zero. The partial differentiation is with respect to each individual parameter element, for example each $u_{i,j}$ in matrix $\uu$. The idea is to single out those terms in equation \ref{eq:expLL} that involve $u_{i,j}$ (say), differentiate by $u_{i,j}$, set this to zero and solve for $u_{i,j}$. This gives the new $u_{i,j}$ that maximizes the partial derivative with respect to $u_{i,j}$ of the expected log-likelihood. Matrix calculus gives us a way to jointly maximize $\Psi$ with respect to all elements (not just element $i,j$) in a parameter matrix. + +Note, see the comments on the EM algorithm implementation (Section \ref{sec:EMalgorithm}) when the parameter set $\Theta$ is broken into parts (e.g., $\BB$, $\uu$, $\QQ$, etc.). In the implementation of the algorithm, one updates the $\Theta$ parts sequentially and the expectation step is re-run with the new $\Theta$ at each step (meaning the Kalman smoother is re-run with the updated parameters). Thus the algorithm is applied as follows (order that the parameters are updated is unimportant): E-step with $\{\BB_j, \uu_j, \QQ_j, etc.\}$, M-step updates $\BB_j$ to $\BB_{j+1}$, E-step with $\{\BB_{j+1}, \uu_j, \QQ_j, etc.\}$, M-step updates $\uu_j$ to $\uu_{j+1}$, E-step with $\{\BB_{j+1}, \uu_{j+1}, \QQ_j, etc.\}$, M-step updates $\QQ_j$ to $\QQ_{j+1}$, continuing until all parameters are updates which completes the $j+1$ update. + +\subsection{Matrix calculus need for the derivation}\label{sec:MatrixDerivatives} +A number of derivatives of a scalar with respect to vectors and matrices will be needed in the derivation and are shown in table \ref{tab:MatrixDerivatives}. The partial derivative of a scalar ($\Psi$ is a scalar) with respect to some column vector $\bb$ (which has elements $b_1$, $b_2$ . . .) is +\begin{equation*} +\frac{\partial\Psi}{\partial\bb}= +\begin{bmatrix} +\dfrac{\partial\Psi}{\partial b_1}& \dfrac{\partial\Psi}{\partial b_2}& \cdots& \dfrac{\partial\Psi}{\partial b_m} +\end{bmatrix} +\end{equation*} + Note that the derivative of scalar with respect to a column vector $\bb$ is a row vector. The partial derivatives of a scalar with respect to some $m \times m$ matrix $\BB$ is +\begin{equation*} +\frac{\partial\Psi}{\partial\BB}= +\begin{bmatrix} +\dfrac{\partial\Psi}{\partial b_{1,1}}& \dfrac{\partial\Psi}{\partial b_{2,1}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,1}}\\ +\\ +\dfrac{\partial\Psi}{\partial b_{1,2}}& \dfrac{\partial\Psi}{\partial b_{2,2}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,2}}\\ +\\ +\cdots& \cdots& \cdots& \cdots\\ +\\ +\dfrac{\partial\Psi}{\partial b_{1,m}}& \dfrac{\partial\Psi}{\partial b_{2,m}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,m}}\\ +\end{bmatrix} +\end{equation*} +Note that the indexing is interchanged; $\partial\Psi/\partial b_{i,j}=\big[\partial\Psi/\partial\BB\big]_{j,i}$. For $\QQ$ and $\RR$, this is unimportant because they are variance-covariance matrices and are symmetric. For $\BB$ and $\ZZ$, one must be careful because these may not be symmetric. The partial derivatives of a column vector $\aa$ with respect to a column vector $\bb$. +\begin{equation*} +\frac{\partial\Psi}{\partial\BB}= +\begin{bmatrix} +\dfrac{\partial a_1}{\partial b_1}& \dfrac{\partial a_1}{\partial b_2}& \cdots& \dfrac{\partial a_1}{\partial b_m}\\ +\\ +\dfrac{\partial a_2}{\partial b_1}& \dfrac{\partial\Psi}{\partial b_2}& \cdots& \dfrac{\partial a_2}{\partial b_m}\\ +\\ +\cdots& \cdots& \cdots& \cdots\\ +\\ +\dfrac{\partial a_n}{\partial b_1}& \dfrac{\partial a_n}{\partial b_2}& \cdots& \dfrac{\partial a_n}{\partial b_m}\\ +\end{bmatrix} +\end{equation*} + +In table \ref{tab:MatrixDerivatives}, both the vectorized and non-vectorized versions are shown. The vectorized version of a matrix $\DD$ with dimension $n \times m$ is +\begin{gather*} +\vec(\DD_{n,m})\equiv +\begin{bmatrix} +d_{1,1}\\ +\cdots\\ +d_{n,1}\\ +d_{1,2}\\ +\cdots\\ +d_{n,2}\\ +\cdots\\ +d_{1,m}\\ +\cdots\\ +d_{n,m} +\end{bmatrix}\\ +\end{gather*} + + +\begin{table} + \caption{Derivatives of a scalar with respect to vectors and matrices. In the following $a$ is a scalar (unrelated to $\aa$), $\aa$ and $\cc$ are $n \times 1$ column vectors, $\bb$ and $\dd$ are $m \times 1$ column vectors, $\DD$ is a $n \times m$ matrix, $\CC$ is a $n \times n$ matrix, and $\AA$ is a diagonal $n \times n$ matrix (0s on the off-diagonals). $\CC^{-1}$ is the inverse of $\CC$, $\CC^\top$ is the transpose of $\CC$, $\CC^{-\top} = \big(\CC^{-1}\big)^\top = \big(\CC^\top\big)^{-1}$, and $|\CC|$ is the determinant of $\CC$. Note, all the numerators in the differentials on the far left reduce to scalars. Although the matrix names may be the same as those of matrices referred to in the text, the matrices in this table are dummy matrices used to show the matrix derivative relations.} + \label{tab:MatrixDerivatives} +\begin{center}\begin{tabular}{lr} +\hline +\\ +\refstepcounter{equation}\label{eq:derivproductrule} +$\partial(\ff^\top\gg)/\partial\aa = \ff^\top\partial\gg/\partial\aa + \gg^\top\partial\ff/\partial\aa$ +& \multirow{2}{*}{(\theequation)} \\ +$\ff=f(\aa)$ and \gg=$g(\aa)$ are $m \times 1$ column vectors and functions of $\aa$. & \\ +$\partial a /\partial\aa = \frac{1}{m} \partial a /\partial \gg \, \partial\gg/\partial\aa$ +&\\ +$\partial \ff /\partial\aa = \frac{1}{m} \partial \ff /\partial \gg \, \partial\gg/\partial\aa$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivaTc} +$\partial(\aa^\top\cc)/\partial\aa = \partial(\cc^\top\aa)/\partial\aa = \cc^\top$ & \multirow{2}{*}{(\theequation)} \\ +$\partial \aa/\partial \aa = \partial(\aa^\top)/\partial \aa = \II_n$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivaTDb} +$\partial(\aa^\top\DD\bb)/\partial\DD = \partial(\bb^\top\DD^\top\aa)/\partial\DD = \bb\aa^\top$ +& \multirow{2}{*}{(\theequation)} \\ +$\partial(\aa^\top\DD\bb)/\partial\vec(\DD) = \partial(\bb^\top\DD^\top\aa)/\partial\vec(\DD) = \big(\vec(\bb\aa^\top)\big)^\top$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivlogDet} +$\CC$ is invertible.& \multirow{6}{*}{(\theequation)} \\ +$\partial(\log |\CC|)/\partial\CC = -\partial(\log |\CC^{-1}|)/\partial\CC=(\CC^\top)^{-1} = \CC^{-\top}$\\ +$\partial(\log |\CC|)/\partial\vec(\CC) = \big(\vec(\CC^{-\top})\big)^\top$& \\ +If $\CC$ is also symmetric and $\BB$ is not a function of $\CC$.& \\ +$\partial(\log |\CC^\top\BB\CC|)/\partial\CC = 2\CC^{-1}$\\ +$\partial(\log |\CC^\top\BB\CC|)/\partial\vec(\CC) = 2\big(\vec(\CC^{-1})\big)^\top$\\ +\\ +\refstepcounter{equation}\label{eq:derivbDTCDd} +$\partial(\bb^\top\DD^\top\CC\DD\dd)/\partial\DD = \dd\bb^\top\DD^\top\CC + \bb\dd^\top\DD^\top\CC^\top$ +& \multirow{3}{*}{(\theequation)} \\ +$\partial(\bb^\top\DD^\top\CC\DD\dd)/\partial\vec(\DD) = +\big(\vec(\dd\bb^\top\DD^\top\CC + \bb\dd^\top\DD^\top\CC^\top)\big)^\top $ &\\ +If $\bb=\dd$ and $\CC$ is symmetric then the sum reduces to $2\bb\bb^\top\DD^\top\CC$ & \\ +\\ +\refstepcounter{equation}\label{eq:derivaTCa} +$\partial(\aa^\top\CC\aa)/\partial\aa = \partial(\aa\CC^\top\aa^\top)/\partial\aa = 2\aa^\top\CC$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:derivInv} +$\partial(\aa^\top\CC^{-1}\cc)/\partial\CC = -\CC^{-1}\aa\cc^\top\CC^{-1} $ +& \multirow{2}{*}{(\theequation)} \\ +$\partial(\aa^\top\CC^{-1}\cc)/\partial\vec(\CC) = -\big(\vec(\CC^{-1}\aa\cc^\top\CC^{-1})\big)^\top$ & \\ +\\ +\hline +\end{tabular}\end{center} +\end{table} + +\subsection{The update equation for $\uu$ (unconstrained)} +Take the partial derivative of $\Psi$ with respect to $\uu$, which is a $m \times 1$ matrix. All parameters other than $\uu$ are fixed to constant values (because partial derivation is being done). Since the derivative of a constant is 0, terms not involving $\uu$ will equal 0 and drop out. Taking the derivative to equation \ref{eq:expLL} with respect to $\uu$: +\begin{equation}\label{eq:u.unconstrained1} +\begin{split} +&\partial\Psi/\partial\uu = - \frac{1}{2}\sum_{t=1}^T \bigg(- \partial(\E[\XX_t^\top\QQ^{-1}\uu])/\partial\uu +- \partial(\E[\uu^\top\QQ^{-1}\XX_t])/\partial\uu \\ +&\quad + \partial(\E[(\BB\XX_{t-1})^\top\QQ^{-1}\uu])/\partial\uu ++ \partial(\E[\uu^\top\QQ^{-1}\BB\XX_{t-1}])/\partial\uu + \partial(\uu^\top\QQ^{-1}\uu)/\partial\uu \bigg) +\end{split} +\end{equation} +The parameters can be moved out of the expectations and then the matrix derivative relations (table \ref{tab:MatrixDerivatives}) are used to take the derivative. +\begin{equation}\label{eq:u.unconstrained2} +\begin{split} +\partial\Psi/\partial\uu = - \frac{1}{2}\sum_{t=1}^T\bigg(- \E[\XX_t]^\top\QQ^{-1} +- \E[\XX_t]^\top\QQ^{-1} + (\BB\E[\XX_{t-1}])^\top\QQ^{-1} + (\BB\E[\XX_{t-1}])^\top\QQ^{-1} + 2\uu^\top\QQ^{-1} \bigg) +\end{split} +\end{equation} +This also uses $\QQ^{-1} = (\QQ^{-1})^\top$. This can then be reduced to +\begin{equation}\label{eq:u.unconstrained3} +\begin{split} +&\partial\Psi/\partial\uu = \sum_{t=1}^T\big(\E[\XX_t]^\top\QQ^{-1} + - \E[\XX_{t-1}]^\top\BB^\top\QQ^{-1} - \uu^\top\QQ^{-1} \big) +\end{split} +\end{equation} +Set the left side to zero (a $p \times m$ matrix of zeros) and transpose the whole equation. $\QQ^{-1}$ cancels out\footnote{$\QQ$ is a variance-covariance matrix and is invertible. $\QQ^{-1}\QQ=\II$, the identity matrix.} by multiplying on the left by $\QQ$ (left since the whole equation was just transposed), giving +\begin{equation}\label{eq:u.unconstrained4} +\mathbf{0} = \sum_{t=1}^T\big(\E[\XX_t] - \BB\E[\XX_{t-1}] - \uu \big) += \sum_{t=1}^T\big(\E[\XX_t] - \BB\E[\XX_{t-1}] \big) - \uu +\end{equation} +Solving for $\uu$ and replacing the expectations with their names from equation \ref{eq:expectations}, gives us the new $\uu$ that maximizes $\Psi$, +\begin{equation}\label{eq:uupdate.unconstrained} +\uu_{j+1} = \frac{1}{T} \sum_{t=1}^T\big(\hatxt - \BB\hatxtm \big) +\end{equation} + +\subsection{The update equation for $\BB$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\BB$. Terms not involving $\BB$, equal 0 and drop out. I have put the $\E$ outside the partials by noting that $\partial(\E[h(\XX_t,\BB)])/\partial\BB=\E[\partial(h(\XX_t,\BB))/\partial\BB]$ since the expectation is conditioned on $\BB_j$ not $\BB$. +\begin{equation}\label{eq:B.unconstrained1} +\begin{split} +&\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB] \\ +&\quad - \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\XX_t)/\partial\BB] + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}(\BB\XX_{t-1}))/\partial\BB] \\ +&\quad + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\uu)/\partial\BB] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB]\bigg)\\ +&= -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1}])/\partial\BB] \\ +&\quad - \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}\XX_t)/\partial\BB] ++ \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}(\BB\XX_{t-1}))/\partial\BB] \\ +&\quad + \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}\uu)/\partial\BB] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB\bigg)]\\ +\end{split} +\end{equation} +After pulling the constants out of the expectations, we use relations \ref{eq:derivaTDb} and \ref{eq:derivbDTCDd} to take the derivative and note that $\QQ^{-1} = (\QQ^{-1})^\top$: +\begin{equation}\label{eq:B.unconstrained2} +\begin{split} +&\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\XX_{t-1}\XX_t^\top]\QQ^{-1} - \E[ \XX_{t-1}\XX_t^\top]\QQ^{-1} \\ +&\quad + 2 \E[\XX_{t-1}\XX_{t-1}^\top]\BB^\top\QQ^{-1} + \E[\XX_{t-1}]\uu^\top\QQ^{-1} + \E[\XX_{t-1}]\uu^\top\QQ^{-1} \bigg) \\ +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{eq:B.unconstrained3} +\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-2\E[\XX_{t-1}\XX_t^\top]\QQ^{-1} + 2 \E[\XX_{t-1}\XX_{t-1}^\top ]\BB^\top\QQ^{-1} ++ 2\E[\XX_{t-1}]\uu^\top\QQ^{-1} \bigg) +\end{equation} +Set the left side to zero (an $m \times m$ matrix of zeros), cancel out $\QQ^{-1}$ by multiplying by $\QQ$ on the right, get rid of the -1/2, and transpose the whole equation to give +\begin{equation}\label{eq:B.unconstrained4} +\begin{split} +&\mathbf{0} = \sum_{t=1}^T\big(\E[\XX_t\XX_{t-1}^\top] - \BB \E[\XX_{t-1}\XX_{t-1}^\top] - \uu \E[\XX_{t-1}^\top]\big)\\ +&\quad = \sum_{t=1}^T \big( \hatPttm - \BB \hatPtm - \uu \hatxtm^\top \big) +\end{split} +\end{equation} +The last line replaced the expectations with their names shown in equation \ref{eq:expectations}. +Solving for $\BB$ and noting that $\hatPtm$ is like a variance-covariance matrix and is invertible, gives us the new $\BB$ that maximizes $\Psi$, +\begin{equation}\label{eq:B.update.unconstrained} +\BB_{j+1}= \bigg( \sum_{t=1}^T \big( \hatPttm - \uu \hatxtm^\top \big)\bigg) \bigg(\sum_{t=1}^T \hatPtm\bigg)^{-1} +\end{equation} + +Because all the equations above also apply to block-diagonal matrices, the derivation immediately generalizes to the case where $\BB$ is an unconstrained block diagonal matrix: +\begin{equation*} +\BB = +\begin{bmatrix} +b_{1,1}&b_{1,2}&b_{1,3}&0&0&0&0&0\\ +b_{2,1}&b_{2,2}&b_{2,3}&0&0&0&0&0\\ +b_{3,1}&b_{3,2}&b_{3,3}&0&0&0&0&0\\ +0&0&0&b_{4,4}&b_{4,5}&0&0&0\\ +0&0&0&b_{5,4}&b_{5,5}&0&0&0\\ +0&0&0&0&0&b_{6,6}&b_{6,7}&b_{6,8}\\ +0&0&0&0&0&b_{7,6}&b_{7,7}&b_{7,8}\\ +0&0&0&0&0&b_{8,6}&b_{8,7}&b_{8,8} +\end{bmatrix} += +\begin{bmatrix} +\BB_1&0&0\\ +0&\BB_2&0\\ +0&0&\BB_3\\ +\end{bmatrix} +\end{equation*} + +For the block diagonal $\BB$, +\begin{equation}\label{eq:B.update.blockdiag} +\BB_{i,j+1}= \bigg( \sum_{t=1}^T \big( \hatPttm - \uu \hatxtm^\top \big) \bigg)_i \bigg(\sum_{t=1}^T \hatPtm \bigg)_i^{-1} +\end{equation} +where the subscript $i$ means to take the parts of the matrices that are analogous to $\BB_i$; take the whole part within the parentheses not the individual matrices inside the parentheses. If $\BB_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\BB$, then take rows $a$ to $b$ and columns $c$ to $d$ of the matrices subscripted by $i$ in equation \ref{eq:B.update.blockdiag}. + +\subsection{The update equation for $\QQ$ (unconstrained)} +\label{subsec:Qunconstrained} +The usual way to do this derivation is to use what is known as the ``trace trick'' which will pull the $\QQ^{-1}$ out to the left of the $\cc^\top\QQ^{-1}\bb$ terms which appear in the likelihood (equation \ref{eq:expLL}). Here I'm showing a less elegant derivation that plods step by step through each of the likelihood terms. Take the derivative of $\Psi$ with respect to $\QQ$. Terms not involving $\QQ$ equal 0 and drop out. Again the expectations are placed outside the partials by noting that $\partial(\E[h(\XX_t,\QQ)])/\partial\QQ=\E[\partial(h(\XX_t,\QQ))/\partial\QQ]$. +\begin{equation}\label{eq:Q.unconstrained1} +\begin{split} +&\partial\Psi/\partial\QQ = -\frac{1}{2} \sum_{t=1}^T\bigg( +\E[\partial(\XX_t^\top\QQ^{-1}\XX_t)/\partial\QQ] +-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ] \\ +&\quad -\E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\XX_t)/\partial\QQ ] + - \E[\partial(\XX_t^\top\QQ^{-1}\uu)/\partial\QQ] \\ +&\quad - \E[\partial(\uu^\top\QQ^{-1}\XX_t)/\partial\QQ] ++ \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ] \\ +&\quad + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\uu)/\partial\QQ] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ]\\ +&\quad +\partial(\uu^\top\QQ^{-1}\uu)/\partial\QQ +\bigg) - \partial\bigg(\frac{T}{2}\log |\QQ| \bigg)/\partial\QQ \\ +\end{split} +\end{equation} +The relations \eqref{eq:derivInv} and \eqref{eq:derivlogDet} are used to do the differentiation. Notice that all the terms in the summation are of the form $\cc^\top\QQ^{-1}\bb$, and thus after differentiation, all the $\cc^\top\bb$ terms can be grouped inside one set of parentheses. Also there is a minus that comes from equation \ref{eq:derivInv} and it cancels out the minus in front of the initial $-1/2$. +\begin{equation}\label{eq:Q.unconstrained2} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \E[\XX_t\XX_t^\top] -\E[\XX_t(\BB\XX_{t-1})^\top ] - \E[\BB\XX_{t-1}\XX_t^\top ] - \E[ \XX_t\uu^\top ] - \E[ \uu\XX_t^\top ] \\ +&\quad + \E[ \BB\XX_{t-1}(\BB\XX_{t-1})^\top ] + \E[\BB\XX_{t-1}\uu^\top] + \E[ \uu(\BB\XX_{t-1})^\top ] + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +Pulling the parameters out of the expectations and using $(\BB\XX_t)^\top = \XX_t^\top\BB^\top$, we have +\begin{equation}\label{eq:Q.unconstrained3} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \E[\XX_t\XX_t^\top] -\E[\XX_t\XX_{t-1}^\top ]\BB^\top - \BB\E[\XX_{t-1}\XX_t^\top ] - \E[ \XX_t ]\uu^\top - \uu \E[ \XX_t^\top ]\\ +&\quad + \BB\E[ \XX_{t-1}\XX_{t-1}^\top ]\BB^\top + \BB\E[\XX_{t-1}]\uu^\top + \uu\E[\XX_{t-1}^\top ]\BB^\top + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +The partial derivative is then rewritten in terms of the Kalman smoother output: +\begin{equation}\label{eq:Q.unconstrained4} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt +- \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +Setting this to zero (a $m \times m$ matrix of zeros), $\QQ^{-1}$ is canceled out by multiplying by $\QQ$ twice, once on the left and once on the right and the $1/2$ is removed: +\begin{equation}\label{eq:Q.unconstrained5} +\begin{split} +T\QQ = \sum_{t=1}^T \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top + + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg) +\end{split} +\end{equation} +This gives us the new $\QQ$ that maximizes $\Psi$, +\begin{equation}\label{eq:Q.update.unconstrained} +\begin{split} +&\QQ_{j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( +\hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg) +\end{split} +\end{equation} + +This derivation immediately generalizes to the case where $\QQ$ is a block diagonal matrix: +\begin{equation*} +\QQ = +\begin{bmatrix} +q_{1,1}&q_{1,2}&q_{1,3}&0&0&0&0&0\\ +q_{1,2}&q_{2,2}&q_{2,3}&0&0&0&0&0\\ +q_{1,3}&q_{2,3}&q_{3,3}&0&0&0&0&0\\ +0&0&0&q_{4,4}&q_{4,5}&0&0&0\\ +0&0&0&q_{4,5}&q_{5,5}&0&0&0\\ +0&0&0&0&0&q_{6,6}&q_{6,7}&q_{6,8}\\ +0&0&0&0&0&q_{6,7}&q_{7,7}&q_{7,8}\\ +0&0&0&0&0&q_{6,8}&q_{7,8}&q_{8,8} +\end{bmatrix} += +\begin{bmatrix} +\QQ_1&0&0\\ +0&\QQ_2&0\\ +0&0&\QQ_3\\ +\end{bmatrix} +\end{equation*} +In this case, +\begin{equation}\label{eq:Q.update.blockdiag} +\begin{split} +&\QQ_{i,j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg)_i +\end{split} +\end{equation} +where the subscript $i$ means take the elements of the matrix (in the big parentheses) that are analogous to $\QQ_i$; take the whole part within the parentheses not the individual matrices inside the parentheses). If $\QQ_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\QQ$, then take rows $a$ to $b$ and columns $c$ to $d$ of matrices subscripted by $i$ in equation \ref{eq:Q.update.blockdiag}. + +By the way, $\QQ$ is never really unconstrained since it is a variance-covariance matrix and the upper and lower triangles are shared. However, because the shared values are only the symmetric values in the matrix, the derivation still works even though it's technically incorrect \citep{HendersonSearle1979}. The constrained update equation for $\QQ$ shown in section \ref{sec:constrained.Q} explicitly deals with the shared lower and upper triangles. + +\subsection{Update equation for $\aa$ (unconstrained)}\label{sec:unconstA} +Take the derivative of $\Psi$ with respect to $\aa$, where $\aa$ is a $n \times 1$ matrix. Terms not involving $\aa$, equal 0 and drop out. +\begin{equation}\label{eq:a.unconstrained1} +\begin{split} +&\partial\Psi/\partial\aa = - \frac{1}{2}\sum_{t=1}^T \bigg(- \partial(\E[\YY_t^\top\RR^{-1}\aa])/\partial\aa +- \partial(\E[\aa^\top\RR^{-1}\YY_t])/\partial\aa \\ +&\quad + \partial(\E[(\ZZ\XX_t)^\top\RR^{-1}\aa])/\partial\aa ++ \partial(\E[\aa^\top\RR^{-1}\ZZ\XX_t])/\partial\aa ++ \partial(\E[\aa^\top\RR^{-1}\aa])/\partial\aa \bigg) +\end{split} +\end{equation} +The expectations around constants can be dropped\footnote{ +because $\EXy(C)=C$, where $C$ is a constant.}. Using relations \eqref{eq:derivaTc} and \eqref{eq:derivaTCa} and using $\RR^{-1} = (\RR^{-1})^\top$, we have then +\begin{equation}\label{eq:a.unconstrained2} +\begin{split} +&\partial\Psi/\partial\aa = - \frac{1}{2}\sum_{t=1}^T\bigg(-\E[\YY_t^\top\RR^{-1}] +-\E[\YY_t^\top\RR^{-1}] + \E[(\ZZ\XX_t)^\top\RR^{-1}] + + \E[(\ZZ\XX_t)^\top\RR^{-1}] + 2\aa^\top\RR^{-1} \bigg) +\end{split} +\end{equation} +Pull the parameters out of the expectations, use $(\aa\bb)^\top = \bb^\top\aa^\top$ and $\RR^{-1} = (\RR^{-1})^\top$ where needed, and remove the $-1/2$ to get +\begin{equation}\label{eq:a.unconstrained3} +\begin{split} +&\partial\Psi/\partial\aa = \sum_{t=1}^T\bigg(\E[\YY_t]^\top\RR^{-1} + - \E[\XX_t]^\top\ZZ^\top\RR^{-1} - \aa^\top\RR^{-1} \bigg) +\end{split} +\end{equation} +Set the left side to zero (a $1 \times n$ matrix of zeros), take the transpose, and cancel out $\RR^{-1}$ by multiplying by $\RR$, giving +\begin{equation}\label{eq:a.unconstrained4} +\mathbf{0} = \sum_{t=1}^{T}\big(\E[\YY_t] - \ZZ\E[\XX_t] - \aa \big) +=\sum_{t=1}^{T}\big(\hatyt - \ZZ\hatxt - \aa\big) +\end{equation} + +Solving for $\aa$ gives us the update equation for $\aa$: +\begin{equation}\label{eq:a.update.unconstrained} +\aa_{j+1} = \frac{1}{T}\sum_{t=1}^{T}\big(\hatyt - \ZZ\hatxt \big) +\end{equation} + +\subsection{The update equation for $\ZZ$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\ZZ$. Terms not involving $\ZZ$, equal 0 and drop out. The expectations around terms involving only constants have been dropped. +\begin{equation}\label{eq:Z.unconstrained1} +\begin{split} +&\partial\Psi/\partial\ZZ = \text{(note $\partial\ZZ$ is $m \times n$ while $\ZZ$ is $n \times m$)}\\ +&\quad -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] + - \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\YY_t)/\partial\ZZ] + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] \\ +&\quad + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\aa)/\partial\ZZ] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ]\bigg)\\ +&= -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] + -\E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\YY_t)/\partial\ZZ] ++ \E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] \\ +&\quad + \E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\aa)/\partial\ZZ] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ]\bigg)\\ +\end{split} +\end{equation} +Using the matrix derivative relations (table \ref{tab:MatrixDerivatives}) and using $\RR^{-1} = (\RR^{-1})^\top$, we get +\begin{equation}\label{eq:Z.unconstrained2} +\begin{split} +\partial\Psi/\partial\ZZ = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[ \XX_t\YY_t^\top\RR^{-1} ] - &\E[ \XX_t\YY_t^\top\RR^{-1} ] \\ +&+ 2 \E[\XX_t\XX_t^\top\ZZ^\top\RR^{-1}] + \E[ \XX_{t-1}\aa^\top\RR^{-1} ] + \E[ \XX_t\aa^\top\RR^{-1} ] \bigg) +\end{split} +\end{equation} +Pulling the parameters out of the expectations and getting rid of the $-1/2$, we have +\begin{equation}\label{eq:Z.unconstrained3} +\begin{split} +&\partial\Psi/\partial\ZZ = \sum_{t=1}^T\bigg(\E[ \XX_t \YY_t^\top]\RR^{-1} +- \E[ \XX_t\XX_t^\top ]\ZZ^\top\RR^{-1} -\E[ \XX_t ]\aa^\top\RR^{-1} \bigg) \\ +\end{split} +\end{equation} +Set the left side to zero (a $m \times n$ matrix of zeros), transpose it all, and cancel out $\RR^{-1}$ by multiplying by $\RR$ on the left, to give +\begin{equation}\label{eq:Z.unconstrained4} +\begin{split} +\mathbf{0} = \sum_{t=1}^T\big(\E[\YY_t\XX_t^\top] - \ZZ \E[\XX_t\XX_t^\top] - \aa\E[\XX_t^\top]\big) + = \sum_{t=1}^T \big( \hatYXt - \ZZ \hatPt - \aa\hatxt^\top \big) +\end{split} +\end{equation} +Solving for $\ZZ$ and noting that $\hatPt$ is invertible, gives us the new $\ZZ$: +\begin{equation}\label{eq:Z.update.unconstrained} +\ZZ_{j+1}= \bigg( \sum_{t=1}^T \big(\hatYXt - \aa\hatxt^\top\big)\bigg) \bigg(\sum_{t=1}^T \hatPt\bigg)^{-1} +\end{equation} + +\subsection{The update equation for $\RR$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\RR$. Terms not involving $\RR$, equal 0 and drop out. The expectations around terms involving constants have been removed. +\begin{equation}\label{eq:R.unconstrained1} +\begin{split} +&\partial\Psi/\partial\RR = -\frac{1}{2} \sum_{t=1}^T\bigg( +\E[\partial(\YY_t^\top\RR^{-1}\YY_t)/\partial\RR] +-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] -\E[\partial((\ZZ\XX_t)^\top\RR^{-1}\YY_t)/\partial\RR]\\ +&\quad - \E[\partial(\YY_t^\top\RR^{-1}\aa)/\partial\RR] + - \E[\partial(\aa^\top\RR^{-1}\YY_t)/\partial\RR] ++ \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] \\ +&\quad + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\aa)/\partial\RR] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] + + \partial(\aa^\top\RR^{-1}\aa)/\partial\RR +\bigg) - \partial\big(\frac{T}{2}\log |\RR| \big)/\partial\RR +\end{split} +\end{equation} +We use relations \eqref{eq:derivInv} and \eqref{eq:derivlogDet} to do the differentiation. Notice that all the terms in the summation are of the form $\cc^\top\RR^{-1}\bb$, and thus after differentiation, we group all the $\cc^\top\bb$ inside one set of parentheses. Also there is a minus that comes from equation \ref{eq:derivInv} and cancels out the minus in front of $-1/2$. +\begin{equation}\label{eq:R.unconstrained2} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( + \E[\YY_t\YY_t^\top] -\E[\YY_t(\ZZ\XX_t)^\top] - \E[\ZZ\XX_t\YY_t^\top ] - \E[\YY_t\aa^\top] - \E[\aa\YY_t^\top]\\ +&\quad + \E[ \ZZ\XX_t(\ZZ\XX_t)^\top ] + \E[\ZZ\XX_t\aa^\top] + \E[ \aa(\ZZ\XX_t)^\top ] + + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +Pulling the parameters out of the expectations and using $(\ZZ\YY_t)^\top = \YY_t^\top\ZZ^\top$, we have +\begin{equation}\label{eq:R.unconstrained3} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( + \E[\YY_t\YY_t^\top] -\E[\YY_t\XX_t^\top ]\ZZ^\top - \ZZ\E[\XX_t\YY_t^\top] + - \E[\YY_t]\aa^\top - \aa\E[\YY_t^\top] \\ +&\quad + \ZZ\E[ \XX_t\XX_t^\top ]\ZZ^\top + \ZZ\E[\XX_t]\aa^\top + \aa\E[\XX_t^\top ]\ZZ^\top + + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +We rewrite the partial derivative in terms of expectations: +\begin{equation}\label{eq:R.unconstrained4} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( +\hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top \\ +&\quad + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +Setting this to zero (a $n \times n$ matrix of zeros), we cancel out $\RR^{-1}$ by multiplying by $\RR$ twice, once on the left and once on the right, and get rid of the $1/2$. +\begin{equation}\label{eq:R.unconstrained5} +\begin{split} +T\RR = \sum_{t=1}^T \bigg( +\hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top ++ \aa\aa^\top \bigg) +\end{split} +\end{equation} + +We can then solve for $\RR$, giving us the new $\RR$ that maximizes $\Psi$, +\begin{equation}\label{eq:R.update.unconstrained} +\begin{split} +\RR_{j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + + \aa\aa^\top \bigg) +\end{split} +\end{equation} +As with $\QQ$, this derivation immediately generalizes to a block diagonal matrix: +\begin{equation*} +\RR = +\begin{bmatrix} +\RR_1&0&0\\ +0&\RR_2&0\\ +0&0&\RR_3\\ +\end{bmatrix} +\end{equation*} +In this case, +\begin{equation}\label{eq:R.update.blockdiag} +\begin{split} +\RR_{i,j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + + \aa\aa^\top \bigg)_i +\end{split} +\end{equation} +where the subscript $i$ means we take the elements in the matrix in the big parentheses that are analogous to $\RR_i$. If $\RR_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\RR$, then we take rows $a$ to $b$ and columns $c$ to $d$ of matrix subscripted by $i$ in equation \ref{eq:R.update.blockdiag}. + +\subsection{Update equation for $\xixi$ and $\LAM$ (unconstrained), stochastic initial state} +\citet{ShumwayStoffer2006} and \citet{GhahramaniHinton1996} imply in their discussion of the EM algorithm that both $\xixi$ and $\LAM$ can be estimated (though not simultaneously). Harvey (1989), however, discusses that there are only two allowable cases: $\xx_0$ is treated as fixed ($\LAM=0$) and equal to the unknown parameter $\xixi$ or $\xx_0$ is treated as stochastic with a known mean $\xixi$ and variance $\LAM$. For completeness, we show here the update equation in the case of $\xx_0$ stochastic with unknown mean $\xixi$ and variance $\LAM$ (a case that Harvey (1989) says is not consistent). + +We proceed as before and solve for the new $\xixi$ by minimizing $\Psi$. +Take the derivative of $\Psi$ with respect to $\xixi$ . Terms not involving $\xixi$, equal 0 and drop out. +\begin{equation}\label{eq:pi.unconstrained1} +\begin{split} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- \partial(\E[\xixi^\top\LAM^{-1}\XX_0])/\partial\xixi +- \partial(\E[\XX_0^\top\LAM^{-1}\xixi])/\partial\xixi + + \partial(\xixi^\top\LAM^{-1}\xixi)/\partial\xixi \big) +\end{split} +\end{equation} +Using relations \eqref{eq:derivaTc} and \eqref{eq:derivaTCa} and using $\LAM^{-1} = (\LAM^{-1})^\top$, we have +\begin{equation}\label{eq:pi.unconstrained2} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- \E[ \XX_0^\top\LAM^{-1} ] +- \E[ \XX_0^\top\LAM^{-1} ] + 2\xixi^\top\LAM^{-1} \big) +\end{equation} +Pulling the parameters out of the expectations, we get +\begin{equation}\label{eq:pi.unconstrained3} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- 2\E[ \XX_0^\top ]\LAM^{-1} + 2\xixi^\top\LAM^{-1} \big) +\end{equation} +We then set the left side to zero, take the transpose, and cancel out $-1/2$ and $\LAM^{-1}$ (by noting that it is a variance-covariance matrix and is invertible). +\begin{equation}\label{eq:pi.unconstrained4} +\mathbf{0} = \big(\LAM^{-1}\E[ \XX_0 ] + \LAM^{-1}\xixi \big)=(\widetilde{\mbox{$\mathbf x$}}_0 - \xixi) +\end{equation} + +Thus, +\begin{equation}\label{eq:pi.update.unconstrained} +\xixi_{j+1} = \widetilde{\mbox{$\mathbf x$}}_0 +\end{equation} +$\widetilde{\mbox{$\mathbf x$}}_0$ is the expected value of $\XX_0$ conditioned on the data from $t=1$ to $T$, which comes from the Kalman smoother recursions with initial conditions defined as $\E[\XX_0|\YY_0=\yy_0] \equiv \xixi_j$ and $\var(\XX_0 \XX_0^\top|\YY_0=\yy_0)\equiv \LAM_j$ (meaning the filter recursions start with $t=1$ with $\tilde{x}_{t-1}^{t-1} = \tilde{x}_0^0 = \xixi_j$). +A similar set of steps gets us to the update equation for $\LAM$, +\begin{equation}\label{eq:V0.update.unconstrained} +\LAM_{j+1} = \widetilde{\VV}_0 +\end{equation} +$\widetilde{\VV}_0$ is the variance of $\XX_0$ conditioned on the data from $t=1$ to $T$ and is an output from the Kalman smoother recursions. + +If the initial state is defined as at $t=1$ instead of $t=0$, the update equation is derived in an identical fashion and the update equation is similar: +\begin{equation}\label{eq:pix1.update.unconstrained} +\xixi_{j+1} = \widetilde{\mbox{$\mathbf x$}}_1 +\end{equation} +\begin{equation} +\LAM_{j+1} = \widetilde{\VV}_1 +\end{equation} +These are output from the Kalman smoother recursions with initial conditions defined as $\E[\XX_1|\YY_0=\yy_0] \equiv \xixi_j$ and $\var(\XX_1 \XX_1^\top|\YY_0=\yy_0)\equiv \LAM_j$ (meaning the filter recursions start with $t=1$ with $\tilde{x}_{t}^{t-1} = \tilde{x}_1^0 = \xixi_j$). Notice that the recursions are initialized slightly differently. In the literature, you will see the Kalman filter and smoother equations presented with both types of initializations depending on whether the author defines the initial state at $t=0$ or $t=1$. + +\subsection{Update equation for $\xixi$ (unconstrained), fixed $\xx_0$} +For the case where $\xx_0$ is treated as fixed, i.e., as another parameter, then there is no $\LAM$, and we need to maximize $\partial\Psi/\partial\xixi$ using the slightly different $\Psi$ shown in equation \ref{eq:logL.V0.is.0}. Now $\xixi$ appears in the state equation part of the likelihood. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\partial(\XX_1^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial((\BB\xixi)^\top\QQ^{-1}\XX_1)/\partial\xixi] + \E[\partial((\BB\xixi)^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\BB\xixi)^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg)\\ +&= -\frac{1}{2} \bigg(-\E[\partial(\XX_1^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial(\xixi^\top\BB^\top\QQ^{-1}\XX_1)/\partial\xixi] ++ \E[\partial(\xixi^\top\BB^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial(\xixi^\top\BB^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg) +\end{split} +\end{equation} +After pulling the constants out of the expectations, we use relations \eqref{eq:derivaTDb} and \eqref{eq:derivbDTCDd} to take the derivative: +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.2} +\begin{split} +\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\XX_1]^\top\QQ^{-1}\BB - \E[ \XX_1]^\top\QQ^{-1}\BB + + 2 \xixi^\top\BB^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB \bigg) \\ +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.3} +\begin{split} +\partial\Psi/\partial\xixi = \E[\XX_1]^\top\QQ^{-1}\BB - \xixi^\top\BB^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB +\end{split} +\end{equation} +To solve for $\xixi$, set the left side to zero (an $m \times 1$ matrix of zeros), transpose the whole equation, and then cancel out $\BB^\top\QQ^{-1}\BB$ by multiplying by its inverse on the left, and solve for $\xixi$. This step requires that this inverse exists. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.4} +\begin{split} +\xixi = (\BB^\top\QQ^{-1}\BB)^{-1}\BB^\top\QQ^{-1}(\E[\XX_1] - \uu) +\end{split} +\end{equation} +Thus, in terms of the Kalman filter/smoother output the new $\xixi$ for EM iteration $j+1$ is +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.5} +\begin{split} +\xixi_{j+1} = (\BB^\top\QQ^{-1}\BB)^{-1}\BB^\top\QQ^{-1}(\widetilde{\mbox{$\mathbf x$}}_1 - \uu) +\end{split} +\end{equation} +Note that using, $\widetilde{\mbox{$\mathbf x$}}_0$ output from the Kalman smoother would not work since $\LAM=0$. As a result, $\xixi_{j+1} \equiv \xixi_j$ in the EM algorithm, and it is impossible to move away from your starting condition for $\xixi$. + +This is conceptually similar to using a generalized least squares estimate of $\xixi$ to concentrate it out of the likelihood as discussed in Harvey (1989), section 3.4.4. However, in the context of the EM algorithm, dealing with the fixed $\xx_0$ case requires nothing special; one simply takes care to use the likelihood for the case where $\xx_0$ is treated as an unknown parameter (equation \ref{eq:logL.V0.is.0}). For the other parameters, the update equations are the same whether one uses the log-likelihood equation with $\xx_0$ treated as stochastic (equation \ref{eq:logL}) or fixed (equation \ref{eq:logL.V0.is.0}). + +If your MARSS model is stationary\footnote{meaning the $\XX$'s have a stationary distribution} and your data appear stationary, however, equation \ref{eq:pi.unconstrained.V0.is.0.4} probably is not what you want to use. The estimate of $\xixi$ will be the maximum-likelihood value, but it will not be drawn from the stationary distribution; instead it could be some wildly different value that happens to give the maximum-likelihood. If you are modeling the data as stationary, then you should probably assume that $\xixi$ is drawn from the stationary distribution of the $\XX$'s, which is some function of your model parameters. This would mean that the model parameters would enter the part of the likelihood that involves $\xixi$ and $\LAM$. Since you probably don't want to do that (if might start to get circular), you might try an iterative process to get decent $\xixi$ and $\LAM$ or try fixing $\xixi$ and estimating $\LAM$ (above). You can fix $\xixi$ at, say, zero, by making sure the model you fit has a stationary distribution with mean zero. You might also need to demean your data (or estimate the $\aa$ term to account for non-zero mean data). A second approach is to estimate $\xx_1$ as the initial state instead of $\xx_0$. + +\subsection{Update equation for $\xixi$ (unconstrained), fixed $\xx_1$}\label{sec:xi.unconstrained.x1} +In some cases, the estimate of $\xx_0$ from $\xx_1$ using equation \ref{eq:pi.unconstrained.V0.is.0.5} will be highly sensitive to small changes in the parameters. This is particularly the case for certain $\BB$ matrices, even if they are stationary. The result is that your $\xixi$ estimate is wildly different from the data at $t=1$. The estimates are correct given how you defined the model, just not realistic given the data. In this case, you can specify $\xixi$ as being the value of $\xx$ at $t=1$ instead of $t=0$. That way, the data at $t=1$ will constrain the estimated $\xixi$. In this case, we treat $\xx_1$ as fixed but unknown parameter $\xixi$. The likelihood is then: +\begin{equation} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_2^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ| +\end{split} +\end{equation} + +\begin{equation}\label{} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\partial(\YY_1^\top\RR^{-1}\ZZ\xixi)/\partial\xixi] + - \E[\partial((\ZZ\xixi)^\top\RR^{-1}\YY_1)/\partial\xixi] + \E[\partial((\ZZ\xixi)^\top\RR^{-1}(\ZZ\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\ZZ\xixi)^\top\RR^{-1}\aa)/\partial\xixi] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\xixi)/\partial\xixi]\bigg)\\ +&\quad -\frac{1}{2} \bigg(-\E[\partial(\XX_2^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial((\BB\xixi)^\top\QQ^{-1}\XX_2)/\partial\xixi] + \E[\partial((\BB\xixi)^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\BB\xixi)^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg) +\end{split} +\end{equation} +Note that the second summation starts at $t=2$ and $\xixi$ is $\xx_1$ instead of $\xx_0$. + +After pulling the constants out of the expectations, we use relations \eqref{eq:derivaTDb} and \eqref{eq:derivbDTCDd} to take the derivative: +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.1} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\YY_1]^\top\RR^{-1}\ZZ - \E[ \YY_1]^\top\RR^{-1}\ZZ + + 2 \xixi^\top\ZZ^\top\RR^{-1}\ZZ + \aa^\top\RR^{-1}\ZZ + \aa^\top\RR^{-1}\ZZ \bigg) \\ +&\quad-\frac{1}{2} \bigg(-\E[\XX_2]^\top\QQ^{-1}\BB - \E[ \XX_2]^\top\QQ^{-1}\BB + + 2 \xixi^\top\BB^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB \bigg) +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{} +\begin{split} +&\partial\Psi/\partial\xixi = \E[\YY_1]^\top\RR^{-1}\ZZ - \xixi^\top\ZZ^\top\RR^{-1}\ZZ - \aa^\top\RR^{-1}\ZZ + + \E[\XX_2]^\top\QQ^{-1}\BB - \xixi^\top\BB^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB \\ +&\quad = - \xixi^\top(\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB) + \E[\YY_1]^\top\RR^{-1}\ZZ - \aa^\top\RR^{-1}\ZZ ++ \E[\XX_2]^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB +\end{split} +\end{equation} +To solve for $\xixi$, set the left side to zero (an $m \times 1$ matrix of zeros), transpose the whole equation, and solve for $\xixi$. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.2} +\begin{split} +\xixi = (\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB)^{-1}(\ZZ^\top\RR^{-1}(\E[\YY_1]-\aa) +\BB^\top\QQ^{-1}(\E[\XX_2] - \uu)) \\ +\end{split} +\end{equation} +Thus, when $\xixi \equiv \xx_1$, the new $\xixi$ for EM iteration $j+1$ is +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.3} +\begin{split} +\xixi_{j+1} = (\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB)^{-1}(\ZZ^\top\RR^{-1}(\widetilde{\mbox{$\mathbf y$}}_1-\aa) +\BB^\top\QQ^{-1}(\widetilde{\mbox{$\mathbf x$}}_2 - \uu)) +\end{split} +\end{equation} + +\section{The time-varying MARSS model with linear constraints}\label{sec:tvMARSS} +The first part of this report dealt with the case of a MARSS model (equation \ref{eq:MARSS}) where the parameters are time-constant and where all the elements in a parameter matrix are estimated with no constraints. I will now describe the derivation of an EM algorithm to solve a much more general MARSS model (equation \ref{eq:MARSS.ex2}), which is a time-varying MARSS model where the MARSS parameter matrices are written as a linear equation $\ff+\DD\mm$. This is a very general form of a MARSS model, of which many (most) multivariate autoregressive Gaussian models are a special case. This general MARSS model includes as special cases, MARSS models with covariates (many VARSS models with exogeneous variables), multivariate AR lag-p models and multivariate moving average models, and MARSS models with linear constraints placed on the elements within the model parameters. The objective is to derive one EM algorithm for the whole class, thus a uniform approach to fitting these models. + +The time-varying MARSS model is written: +\begin{subequations}\label{eq:MARSS.ex2} +\begin{gather} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \HH_t\vv_t, \text{ where } \VV_t \sim \MVN(0,\RR_t)\\ +\xx_{t_0} = \xixi+\FF\ll, \text{ where } t_0=0 \text{ or } t_0=1\\ +\LL \sim \MVN(0,\LAM)\\ +\begin{bmatrix}\ww_t\\ \vv_t\end{bmatrix} \sim \MVN(0,\Sigma), \quad \Sigma=\begin{bmatrix}\QQ_t&0\\ 0&\RR_t\end{bmatrix} +\end{gather} +\end{subequations} +This looks quite similar to the previous non-time varying MARSS model, but now the model parameters, $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$ and $\RR$, have a $t$ subscript and we have a multiplier matrix on the error terms $\vv_t$, $\ww_t$, $\ll$. The $\GG_t$ multiplier is $m \times s$, so we now have $s$ state errors instead of $m$. The $\HH_t$ multiplier is $n \times k$, so we now have $k$ observation errors instead of $n$. The $\FF$ multiplier is $m \times j$, so now we can have some initial states ($j$ of them) be stochastic and others be fixed. I assume that appropriate constraints are put on $\GG$ and $\HH$ so that the resulting MARSS model is not under- or over-constrained\footnote{For example, if both $\GG$ and $\HH$ are column vectors, then the system is over-constrained and has no solution.}. +The notation/presentation here was influenced by SJ Koopman's work, esp. \citet{KoopmanOoms2011} and \citet{Koopman1993}, but in these works, $\QQ_t$ and $\RR_t$ equal $\II$ and the variance-covariance structures are instead specified only by $\HH_t$ and $\GG_t$. I keep $\QQ_t$ and $\RR_t$ in my formulation as it seems more intuitive (to me) in the context of the EM algorithm and the required joint-likelihood function. + +We can rewrite this MARSS model using vec relationships (table \ref{tab:VecRelations}): +\begin{equation}\label{eq:MARSS.ex.vec} +\begin{gathered} +\xx_t = (\xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \vec(\uu_t) + \GG_t\ww_t, \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = (\xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \vec(\aa_t) + \HH_t\vv_t, \VV_t \sim \MVN(0,\RR_t)\\ +\xx_{t_0} = \xixi+\FF\ll, \LL \sim \MVN(0,\LAM) +\end{gathered} +\end{equation} +Each model parameter, $\BB_t$, $\uu_t$, $\QQ_t$, $\ZZ_t$, $\aa_t$, and $\RR_t$, is written as a time-varying linear model, $\ff_t+\DD_t\mm$, where $\ff$ and $\DD$ are fully-known (not estimated and no missing values) and $\mm$ is a column vector of the estimates elements of the parameter matrix: +\begin{equation}\label{eq:MARSS.ex.vec.2} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq\\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr\\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda \\ +\vec(\xixi)&= \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} + +The estimated parameters are now the column vectors, $\bbeta$, $\uupsilon$, $\qq$, $\zzeta$, $\aalpha$, $\rr$, $\pp$ and $\llambda$. The time-varying aspect comes from the time-varying $\ff$ and $\DD$. Note that variance-covariance matrices must be positive-definite and we cannot specify a form that cannot be estimated. Fixing the diagonal terms and estimating the off-diagonals would not be allowed. Thus the $\ff$ and $\DD$ terms for $\QQ$, $\RR$ and $\LAM$ are limited. For the other parameters, the forms are fairly unrestricted, except that the $\DD$s need to be full rank so that we are not specifying an under-constrained model. 'Full rank' will imply that we are not trying to estimate confounded matrix elements; for example, trying to estimate $a_1$ and $a_2$ but only $a_1+a_2$ appear in the model. + +The temporally variable MARSS model, equation \ref{eq:MARSS.ex.vec} together with equation \ref{eq:MARSS.ex.vec.2}, looks rather different than other temporally variable MARSS models, such as a VARSSX or MARSS with covariates model, in the literature. But those models are special cases of this equation. By deriving an EM algorithm for this more general (if unfamiliar) form, I then have an algorithm for many different types of time-varying MARSS models with linear constraints on the parameter elements. Below I show some examples. + +\subsection{MARSS model with linear constraints} +We can use equation \ref{eq:MARSS.ex.vec} to put linear constraints on the elements of the parameters, $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$ and $\LAM$. Here is an example of a simple MARSS model with linear constraints: +\begin{gather*} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t += \begin{bmatrix}a&0\\0&2a\end{bmatrix} +\begin{bmatrix}x_1\\x_2\end{bmatrix}_{t-1} ++ \begin{bmatrix}w_1\\ w_2\end{bmatrix}_t,\quad +\begin{bmatrix}w_1\\ w_2\end{bmatrix}_t \sim \MVN\begin{pmatrix}\begin{bmatrix}0.1\\u+0.1\end{bmatrix},\begin{bmatrix}q_{11}&q_{12}\\q_{21}&q_{22}\end{bmatrix} \end{pmatrix} \\ +\\ +\begin{bmatrix}y_1\\ y_2\\ y_3\end{bmatrix}_t += \begin{bmatrix}c&3c+2d+1\\ c& d\\ c+e+2 &e\end{bmatrix} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t ++ \begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t,\\ +\begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t \sim \MVN\begin{pmatrix}\begin{bmatrix}a_1\\ a_2\\ 0\end{bmatrix}, + \begin{bmatrix}r&0&0\\0&2r&0\\0&0&4r\end{bmatrix} \end{pmatrix} \\ +\\ +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_0 \sim \MVN\begin{pmatrix}\begin{bmatrix}\pi\\ \pi\end{bmatrix},\begin{bmatrix}1&0\\ 0&1\end{bmatrix} \end{pmatrix} +\end{gather*} +Linear constraints mean that elements of a matrix may be fixed to a specific numerical value or specified as a linear combination of values (which can be shared within a matrix but not shared between matrices). + +Let's say we have some parameter matrix $\MM$ (here $\MM$ could be any of the parameters in the MARSS model) where each matrix element is written as a linear model of some potentially shared values: +\begin{equation*} +\MM= +\begin{bmatrix} +a+2c+2&0.9&c\\ +-1.2&a&0\\ +0&3c+1&b +\end{bmatrix} +\end{equation*} +Thus each $i$-th element in $\MM$ can be written as $\beta_i+\beta_{a,i} a + \beta_{b,i} b + \beta_{c,i} c$, which is a linear combination of three estimated values $a$, $b$ and $c$. The matrix $\MM$ can be rewritten in terms of a $\beta_i$ part and the part involving the $\beta_{-,j}$'s: +\begin{equation*} +\MM= +\begin{bmatrix} +2&0.9&0\\ +-1.2&0&0\\ +0&1&0 +\end{bmatrix} ++ +\begin{bmatrix} +a+2c&0&c\\ +0&a&0\\ +0&3c&b +\end{bmatrix} +=\MM_\text{fixed}+\MM_\text{free} +\end{equation*} +The vec function turns any matrix into a column vector by stacking the columns on top of each other. Thus, +\begin{equation*} +\vec(\MM)= +\begin{bmatrix} +a+2c+2\\ +-1.2\\ +0\\ +0.9\\ +a\\ +3c+1\\ +c\\ +0\\ +b +\end{bmatrix} +\end{equation*} +We can now write $\vec(\MM)$ as a linear combination of $\ff = \vec(\MM_\text{fixed})$ and $\DD\mm = \vec(\MM_\text{free})$. $\mm$ is a $p \times 1$ column vector of the $p$ free values, in this case $p=3$ and the free values are $a, b, c$. $\DD$ is a design matrix that translates $\mm$ into $\vec(\MM_\text{free})$. For example, +\begin{equation*} +\vec(\MM)= +\begin{bmatrix} +a+2c+2\\ +-1.2\\ +0\\ +0.9\\ +a\\ +3c+1\\ +c\\ +0\\ +b +\end{bmatrix} += +\begin{bmatrix} +0\\ +-1.2\\ +2\\ +0.9\\ +0\\ +1\\ +0\\ +0\\ +0 +\end{bmatrix} ++ +\begin{bmatrix} +1&2&0\\ +0&0&0\\ +0&0&0\\ +0&0&0\\ +1&0&0\\ +0&0&3\\ +0&0&1\\ +0&0&0\\ +0&1&0 +\end{bmatrix} +\begin{bmatrix} +a\\ +b\\ +c +\end{bmatrix} += \ff + \DD\mm +\end{equation*} +There are constraints on $\DD$. Your $\DD$ matrix needs to describe a solvable linear set of equations. Basically it needs to be full rank (rank $p$ where $p$ is the number of columns in $\DD$ or free values you are trying to estimate), so that you can estimate each of the $p$ free values. For example, if $a+b$ always appeared together, then $a+b$ can be estimated but not $a$ and $b$ separately. Note, if $\MM$ is fixed, then $\DD$ is undefined but that is fine because in this case, there will be no update equation needed; you just use the fixed value of $\MM$ in the algorithm. + + +\begin{table} + \caption{Kronecker and vec relations. Here $\AA$ is $n \times m$, $\BB$ is $m \times p$, $\CC$ is $p \times q$, and $\EE$ and $\DD$ are $p \times p$. $\aa$ is a $m \times 1$ column vector and $\bb$ is a $p \times 1$ column vector. The symbol $\otimes$ stands for the Kronecker product: $\AA \otimes \CC$ is a $np \times mq$ matrix. The identity matrix, $\II_n$, is a $n \times n$ diagonal matrix with ones on the diagonal.} + \label{tab:VecRelations} + \begin{center} + \begin{tabular}{lr} +\hline +\\ +\refstepcounter{equation}\label{eq:vec.a} +$\vec(\aa) = \vec(\aa^\top) = \aa$ +&\multirow{3}{*}{(\theequation)} \\ +The vec of a column vector (or its transpose) is itself. & \\ +$\aa=(\aa^\top \otimes \II_1)$ & \\ +\\ +\refstepcounter{equation}\label{eq:vec.Aa} +$\vec(\AA\aa) = (\aa^\top \otimes \II_n)\vec(\AA) = \AA\aa$ +&\multirow{2}{*}{(\theequation)} \\ +$\vec(\AA\aa) = \AA\aa$ since $\AA\aa$ is itself an $m \times 1$ column vector. & \\ +\\ +\refstepcounter{equation}\label{eq:vec.AB} +$\vec(\AA\BB) = (\II_p \otimes \AA)\vec(\BB) = (\BB^\top \otimes \II_n)\vec(\AA)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:vec.ABC} +$\vec(\AA\BB\CC) = (\CC^\top \otimes \AA)\vec(\BB)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:vec.aTBa} +$\vec(\aa^\top\BB\aa) = \aa^\top\BB\aa = (\aa^\top \otimes \aa)\vec(\BB)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:kron.prod} +$(\AA \otimes \BB)(\CC \otimes \DD) = (\AA\CC \otimes \BB\DD)$ +&\multirow{2}{*}{(\theequation)} \\ +$(\AA \otimes \BB)+(\AA \otimes \CC) = (\AA \otimes (\BB+\CC))$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.column.vec} +$(\aa \otimes \II_p)\CC = (\aa \otimes \CC)$ &\multirow{3}{*}{(\theequation)} \\ +$\CC(\aa^\top \otimes \II_q) = (\aa^\top \otimes \CC)$ &\\ +$\EE(\aa^\top \otimes \DD)=\EE\DD(\aa^\top \otimes \II_p)=(\aa^\top \otimes \EE\DD)$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.column.quad.vec} +$(\aa \otimes \II_p)\CC(\bb^\top \otimes \II_q) = (\aa\bb^\top \otimes \CC)$ & +(\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:kron.column.column.vec} +$(\aa \otimes \bb)=\vec(\bb\aa^\top)$ +&\multirow{2}{*}{(\theequation)} \\ +$(\aa^\top \otimes \bb^\top)=(\aa \otimes \bb)^\top=(\vec(\bb\aa^\top))^\top$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.trans} +$(\AA^\top \otimes \BB^\top)=(\AA \otimes \BB)^\top$ & +(\theequation) \\ +\\\hline +\end{tabular} +\end{center} +\end{table} + +\subsection{A MARSS model with exogenous variables} +The following is a commonly seen MARSS model with covariates $\cc_t$ and $\dd_t$ appearing as additive elements: +\begin{equation*} +\begin{split} +\xx_t &= \BB\xx_{t-1} + \CC\cc_t + \ww_t\\ +\yy_t &= \ZZ\xx_t + \DD\dd_t + \vv_t +\end{split} +\end{equation*} +Here, $\DD$ is the effect of $\dd_t$ on $\yy_t$ not a design matrix (which would have a subscript). We would typically want to estimate $\CC$ or $\DD$ which are the influence of our covariates on our responses, $\xx$ or $\yy$. Let's say there are $p$ covariates in $\cc_t$ and $q$ covariates in $\dd_t$. Then we can write the above in vec form: +\begin{equation}\label{eq:MARSS.simple.ex} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)\vec(\BB) + (\cc_t^\top \otimes \II_p)\vec(\CC) + \ww_t\\ +\yy_t &= (\xx_t^\top \otimes \II_n)\vec(\ZZ) + (\dd_t^\top \otimes \II_q)\vec(\DD) + \vv_t +\end{split} +\end{equation} +Let's say we put no constraints $\BB$, $\ZZ$, $\QQ$, $\RR$, $\xixi$, or $\LAM$. Then in the form of equation \ref{eq:MARSS.ex.vec}, +\begin{equation*} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \vec(\uu_t) + \ww_t\\ +\yy_t &= (\xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \vec(\aa_t) + \vv_t, +\end{split} +\end{equation*} +with the parameters defined as follows: +\begin{equation*} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta; +\, \ff_{t,b} = 0;\, \DD_{t,b}=1;\, \bbeta=\vec(\BB)\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon; +\, \ff_{t,u} = 0;\, \DD_{t,u}=(\cc_t^\top \otimes \II_p);\, \uupsilon=\vec(\CC)\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq; +\, \ff_{t,q}= 0;\, \DD_{t,q}= \DD_q \\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta; +\, \ff_{t,z} = 0;\, \DD_{t,z}=1;\, \zzeta=\vec(\ZZ)\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha; +\, \ff_{t,a} = 0;\, \DD_{t,a}=(\dd_t^\top \otimes \II_q);\, \aalpha=\vec(\DD)\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr; +\, \ff_{t,r}= 0;\, \DD_{t,r}= \DD_r \\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda; +\, \ff_\lambda= 0 \\ +\vec(\xixi)&= \xixi=\ff_\xi+\DD_\xi\pp; +\, \ff_\xi = 0; \, \DD_\xi = 1 +\end{split} +\end{equation*} +Note that variance-covariance matrices are never unconstrained really so we use $\DD_q$, $\DD_r$ and $\DD_\lambda$ to specify the symmetry within the matrix. + +The transformation of the simple MARSS with covariates (equation \ref{eq:MARSS.simple.ex}) into the form of equation \ref{eq:MARSS.ex.vec} may seem a little painful, but the advantage is that a single EM algorithm can be used for a large class of models. Presumably, the transformation of the equation will be hidden from users by a wrapper function that does the reformulation before passing the model to the general EM algorithm. In the MARSS R package, this reformulation is done in the \verb@MARSS.marxss@ function. + +\subsection{A general MARSS model with exogenous variables} +Let's imagine now a very general MARSS model with various `inputs'. ` +input' here just means that it is some fully known matrix rather than something we are estimating. It could be a sequence of 0s and 1s if for example we were fitting a before/after sort of model. Below the letters with a $t$ subscript are the inputs (and $\Ab_t$ is an input not a design matrix), except $\xx$, $\yy$, $\ww$ and $\vv$. +\begin{equation}\label{eq:MARSS.general.ex} +\begin{split} +\xx_t &= \Bb_t\BB\Ba_t\xx_{t-1} + \Ub_t\UU\Ua_t + \Qb_t\ww_t\\ +\yy_t &= \Zb_t\ZZ\Za_t\xx_t + \Ab_t\AA\Aa_t + \Rb_t\vv_t +\end{split} +\end{equation} +In vec form, this is: +\begin{equation}\label{eq:MARSS.ex3} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)(\Ba_t^\top \otimes \Bb_t)\vec(\BB) + (\Ua_t^\top \otimes \Ub_t)\vec(\UU) ++ \Qb_t\ww_t\\ +&= (\xx_{t-1}^\top \otimes \II_m)(\Ba_t^\top \otimes \Bb_t)(\ff_b+\DD_b\bbeta) + (\Ua_t^\top \otimes \Ub_t)(\ff_u + \DD_u\uupsilon) + \Qb_t\ww_t\\ +\WW_t & \sim \MVN(0,\Qb_t\QQ\Qb_t^\top)\\ +\\ +\yy_t &= (\xx_t^\top \otimes \II_n)(\Za_t^\top \otimes \Zb_t)\vec(\ZZ) + (\Aa_t^\top \otimes \Ab_t)\vec(\AA) + \Rb_t\vv_t \\ +&= (\xx_t^\top \otimes \II_n)\mathbb{Z}_t(\ff_z+\DD_z\zzeta) + \mathbb{A}_t(\ff_a+\DD_a\aalpha) + \Rb_t\vv_t \\ +\VV_t &\sim \MVN(0,\Rb_t\RR\Rb_t^\top)\\ +\\ +\XX_{t_0} &\sim \MVN(\ff_\xi+\DD_\xi\pp,\FF\LAM\FF^\top), \text{ where } \vec(\LAM)=\ff_\lambda+\DD_\lambda\llambda +\end{split} +\end{equation} +We could write down a likelihood function for this model but written this way, the model presumes that $\Rb_t\RR\Rb_t^\top$, $\Qb_t\QQ\Qb_t^\top$, and $\FF\LAM\FF^\top$ are valid variance-covariance matrices. I will actually write this model differently below because I don't want to make that assumption. + +We define the $\ff$ and $\DD$ parameters as follows. +\begin{equation*} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta = (\Ba_t^\top \otimes \Bb_t)\ff_b + (\Ba_t^\top \otimes \Bb_t)\DD_b\bbeta\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon = (\Ua_t^\top \otimes \Ub_t)\ff_u + (\Ua_t^\top \otimes \Ub_t)\DD_u\uupsilon\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq = (\Qb_t \otimes \Qb_t)\ff_q + (\Qb_t \otimes \Qb_t)\DD_q\qq \\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta = (\Za_t^\top \otimes \Zb_t)\ff_z + (\Za_t^\top \otimes \Zb_t)\DD_z\zzeta\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha = (\Aa_t^\top \otimes \Ab_t)\ff_a + (\Aa_t^\top \otimes \Ab_t)\DD_a\aalpha\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr = (\Rb_t \otimes \Rb_t)\ff_q + (\Rb_t \otimes \Rb_t)\DD_r\rr\\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda = 0 + \DD_\lambda\llambda\\ +\vec(\xixi)&= \xixi=\ff_\xi+\DD_\xi\pp = 0+1\pp +\end{split} +\end{equation*} +Here, for example $\ff_b$ and $\DD_b$ indicate the linear constraints on $\BB$ and $\ff_{t,b}$ is $(\Ba_t^\top \otimes \Bb_t)\ff_b$ and $\DD_{t,b}$ is $(\Ba_t^\top \otimes \Bb_t)\DD_b$. The elements of $\BB$ that are being estimated are $\bbeta$ arranged as a column vector. + +As usual, this reformulation looks cumbersome, but would be hidden from the user presumably. + +\subsection{The expected log-likelihood function} +As mentioned above, we do not necessarily want to assume that $\HH_t\RR_t\HH_t^\top$, $\GG_t\QQ_t\GG_t^\top$, and $\FF\LAM\FF^\top$ are valid variance-covariance matrices. This would rule out many MARSS models that we would like to fit. For example, if $\QQ=\sigma^2$ and $\GG=\begin{bmatrix}1\\ 1\\ 1\end{bmatrix}$, $\GG\QQ\GG^\top$ would be an invalid variance-variance matrix. However, this is a valid MARSS model. We do need to be careful that $\HH_t$ and $\GG_t$ are specified such that the model has a solution. For example, a model where both $\GG$ and $\HH$ are $\begin{bmatrix}1\\ 1\\ 1\end{bmatrix}$ would not be solvable for all $\yy$. + +Instead I will define $\Phi_t=(\GG_t^\top\GG_t)^{-1}\GG_t^\top$, $\Xi_t=(\HH_t^\top\HH_t)^{-1}\HH_t^\top$, and $\Pi = (\FF^\top\FF)^{-1}\FF^\top$. I then require that the inverses of $\GG_t^\top\GG_t$, $\HH_t^\top\HH_t$, and $\FF^\top\FF$ exist and that $\ff_{t,q}+\DD_{t,q}\qq$, $\ff_{t,r}+\DD_{t,r}\rr$, and $\ff_\lambda+\DD_\lambda\llambda$ specify valid variance-covariance matrices. These are much less stringent restrictions. + +For the purpose of writing down the expected log-likelihood, our MARSS model is now written +\begin{equation}\label{eq:MARSS.ex.reformed} +\begin{gathered} +\Phi_t\xx_t = \Phi_t( \xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \Phi_t\vec(\uu_t) + \ww_t, \quad +\text{ where } \WW_t \sim \mathrm{MVN}(0,\QQ_t)\\ +\Xi_t\yy_t = \Xi_t( \xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \Xi_t\vec(\aa_t) + \vv_t,\quad \text{ where } \VV_t \sim \mathrm{MVN}(0,\RR_t)\\ +\Pi\xx_{t_0}=\Pi\xixi+\ll, \quad \text{ where } \LL \sim \MVN(0,\LAM) +\end{gathered} +\end{equation} +As mentioned before, this relies on $\GG$ and $\HH$ having forms that do not lead to over- or under-constrained linear systems. + +To derive the EM update equations, we need the expected log-likelihood function for the time-varying MARSS model. Using equation \ref{eq:MARSS.ex.reformed}, we get +\begin{equation}\label{eq:logL.vec.general} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - ( \XX_t^\top \otimes \II_m)\vec(\ZZ_t) - \vec(\aa_t) )^\top\Xi_t^\top \RR_t^{-1}\Xi_t\\ +&\quad (\YY_t-(\XX_t^\top \otimes \II_m)\vec(\ZZ_t) - \vec(\aa_t))+\sum_1^T \log |\RR_t|\\ +&\quad +\sum_{t_0+1}^T(\XX_t-(\XX_{t-1}^\top \otimes \II_m)\vec(\BB_t) - \vec(\uu_t) )^\top \Phi_t^\top\QQ_t^{-1}\Phi_t \\ +&\quad ( \XX_t-(\XX_{t-1}^\top \otimes \II_m)\vec(\BB_t) - \vec(\uu_t) )+\sum_{t_0+1}^T\log |\QQ_t|\\ +&\quad +(\XX_{t_0}-\vec(\xixi))^\top \Pi^\top\LAM^{-1}\Pi (\XX_{t_0}-\vec(\xixi)) + \log |\LAM| + \log 2\pi \bigg) +\end{split} +\end{equation} +If any $\GG_t$, $\HH_t$ or $\FF$ is all zero, then the line in the likelihood with $\RR_t$, $\QQ_t$ or $\LAM$, respectively, does not appear. If any $\xx_{t_0}$ are fixed, meaning all zero row in $\FF$, that $\XX_{t_0}\equiv\xixi$ anywhere it appears in the likelihood. The way I have written the general equation, some $\xx_{t_0}$ might be fixed and others stochastic. + +The vec of the model parameters are defined as follows: +\begin{equation*} +\begin{split} +\vec(\BB_t)&=\ff_{t,b}+\DD_{t,b}\bbeta\\ +\vec(\uu_t) &= \ff_{t,u}+\DD_{t,u}\uupsilon\\ +\vec(\ZZ_t)&=\ff_{t,z}+\DD_{t,z}\zzeta\\ +\vec(\aa_t) &= \ff_{t,a}+\DD_{t,a}\aalpha\\ +\vec(\QQ_t)&=\ff_{t,q}+\DD_{t,q}\qq\\ +\vec(\RR_t)&=\ff_{t,r}+\DD_{t,r}\rr\\ +\vec(\xixi)&=\ff_\xi+\DD_\xi\pp\\ +\vec(\LAM)&=\ff_\lambda+\DD_\lambda\llambda\\ +\Phi_t&=(\GG_t^\top\GG_t)^{-1}\GG_t^\top\\ +\Xi_t&=(\HH_t^\top\HH_t)^{-1}\HH_t^\top\\ +\Pi&=(\FF^\top\FF)^{-1}\FF^\top +\end{split} +\end{equation*} + +\section{The constrained update equations}\label{sec:constrained} +The derivation proceeds by taking the partial derivative of equation \ref{eq:logL.vec.general} with respect to the estimated terms, the $\zzeta$, $\aalpha$, etc, setting the derivative to zero, and solving for those estimated terms. Conceptually, the algebraic steps in the derivation are similar to those in the unconstrained derivation. See the notes in Sections \ref{sec:generalupdate} and \ref{sec:EMalgorithm} regarding implementation of the EM algorithm when $\Theta$ is broken into parts (e.g., $\BB$, $\uu$, $\QQ$, etc.). + +\subsection{The general $\uu$ update equations} +We take the derivative of $\Psi$ (equation \ref{eq:logL.vec.general}) with respect to $\uupsilon$. +\begin{equation}\label{eq:u.general1} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} + &= - \frac{1}{2}\sum_{t=1}^T \bigg(-\partial(\E[\XX_t^\top\Qm_t\DD_{t,u}\uupsilon])/\partial\pmb{\upsilon} + - \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t\XX_t])/\partial\pmb{\upsilon} \\ +&+ \partial(\E[(( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t))^\top\Qm_t\DD_{t,u}\uupsilon] )/\partial\pmb{\upsilon} + + \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t)])/\partial\pmb{\upsilon}\\ +&+ \partial(\uupsilon^\top\DD_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon)/\partial\pmb{\upsilon} ++ \partial(\E[\ff_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon])/\partial\pmb{\upsilon} + + \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t\ff_{t,u}])/\partial\pmb{\upsilon} +\bigg) +\end{split} +\end{equation} +where $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t$. + +Since $\uupsilon$ is to the far left or right in each term, the derivative is simple using the derivative terms in table \ref{sec:MatrixDerivatives}. +$\partial\Psi/\partial\pmb{\upsilon}$ becomes: +\begin{equation}\label{eq:u.general1b} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} +&= - \frac{1}{2}\sum_{t=1}^T \bigg( +-2\E[\XX_t^\top\Qm_t\DD_{t,u}] + 2\E[(( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t))^\top \Qm_t\DD_{t,u}] \\ +&\quad + 2(\uupsilon^\top\DD_{t,u}^\top\Qm_t\DD_{t,u}) + 2\E[ \ff_{t,u}^\top\Qm_t\DD_{t,u} ] \bigg) +\end{split}\end{equation} +Set the left side to zero and transpose the whole equation. +\begin{equation}\label{eq:u.general4} +\begin{split} +\mathbf{0}= \sum_{t=1}^T \bigg( \DD_{t,u}^\top\Qm_t\E[\XX_t] - \DD_{t,u}^\top\Qm_t(\E[\XX_{t-1}]^\top \otimes \II_m)\vec(\BB_t) +- \DD_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon + - \DD_{t,u}^\top\Qm_t\ff_{t,u} \bigg) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:u.general5} +\big(\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u} \big)\uupsilon + = \sum_{t=1}^T \DD_{t,u}^\top\Qm_t\big(\E[ \XX_t ]- (\E[\XX_{t-1}]^\top \otimes \II_m)\vec(\BB_t) - \ff_{t,u} \big) +\end{equation} +We solve for $\uupsilon$, and the new $\uupsilon$ for the $j+1$ iteration of the EM algorithm is +\begin{equation}\label{eq:u.general.update1} +\begin{split} +\uupsilon_{j+1} &= \bigg(\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u} \bigg)^{-1} + \sum_{t=1}^T \DD_{t,u}^\top\Qm_t\big(\hatxt- (\hatxtm^\top \otimes \II_m)\vec(\BB_t) - \ff_{t,u} \big) +\end{split} +\end{equation} +where $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t = \GG_t(\GG_t^\top\GG_t)^{-1}\QQ_t^{-1}(\GG_t^\top\GG_t)^{-1}\GG_t^\top$. + +The update equation requires that $\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u}$ is invertible. It generally will be if $\Phi_t\QQ_t\Phi_t^\top$ is a proper variance-covariance matrix (positive semi-definite) and $\DD_{t,u}$ is full rank. If $\GG_t$ has all-zero rows then $\Phi_t\QQ_t\Phi_t^\top$ has zeros on the diagonal and we have a partially deterministic model. In this case, $\Qm_t$ will have all-zero row/columns and $\DD_{t,u}^\top\Qm_t\DD_{t,u}$ will not be invertible unless the corresponding row of $\DD_{t,u}$ is zero. This means that if one of the $\xx$ rows is fully deterministic then the corresponding row of $\uu$ would need to be fixed. We can get around this, however. See section \ref{sec:degenerate} on the modifications to the update equation when some of the $\xx$'s are fully deterministic. + +\subsection{The general $\aa$ update equation}\label{sec:constA} +The derivation of the update equation for $\aalpha$ with fixed and shared values is completely analogous to the derivation for $\uupsilon$. We take the derivative of $\Psi$ with respect to $\aalpha$ and arrive at the analogous: +\begin{equation}\label{eq:general.a.update} +\begin{split} +\aalpha_{j+1} &= \big(\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a} \big)^{-1} + \sum_{t=1}^T \DD_{t,a}^\top\Rm_t\big(\hatyt- (\hatxt^\top \otimes \II_n)\vec(\ZZ_t) - \ff_{t,a} \big) \\ + &= \big(\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a} \big)^{-1} + \sum_{t=1}^T \DD_{t,a}^\top\Rm_t\big(\hatyt- \ZZ_t\hatxt - \ff_{t,a} \big) +\end{split} +\end{equation} +$\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a}$ must be invertible. + +\subsection{The general $\xixi$ update equation, stochastic initial state} +When $\xx_0$ is treated as stochastic with an unknown mean and known variance, the derivation of the update equation for $\xixi$ with fixed and shared values is as follows. Take the derivative of $\Psi$ (using equation \ref{eq:logL.vec.general}) with respect to $\pp$: +\begin{equation}\label{eq:pi.general1} +\partial\Psi/\partial\pp = +\big(\widetilde{\mbox{$\mathbf x$}}_0^\top \LAMm - \xixi^\top\LAMm \big) +\end{equation} +Replace $\xixi$ with $\ff_\xi + \DD_\xi\pp$, set the left side to zero and transpose: +\begin{equation}\label{eq:pi.general2} +\mathbf{0} = +\DD_\xi^\top\big(\LAMm\widetilde{\mbox{$\mathbf x$}}_0 - \LAMm\ff_\xi + \LAMm\DD_\xi\pp \big) +\end{equation} +Thus, +\begin{equation}\label{eq:pi.update.general1} +\pp_{j+1} = \big(\DD_\xi^\top\LAMm\DD_\xi \big)^{-1} +\DD_\xi^\top\LAMm(\widetilde{\mbox{$\mathbf x$}}_0 - \ff_\xi) +\end{equation} +and the new $\xixi$ is then, +\begin{equation}\label{eq:pi.update.general2} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} +When the initial state is defined as at $t=1$, replace $\widetilde{\mbox{$\mathbf x$}}_0$ with $\widetilde{\mbox{$\mathbf x$}}_1$ in equation \ref{eq:pi.update.general1}. + +\subsection{The general $\xixi$ update equation, fixed $\xx_0$}\label{sec:xi.constrained.x0} +For this case, $\xx_0$ is treated as fixed, i.e., as another parameter, and $\LAM$ does not appear in the equation. It will be easier to work with $\Psi$ written as follows: +\begin{equation}\label{eq:logL.vec.general.V0.is.0b} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - \ZZ_t\XX_t - \aa_t)^\top \Rm_t(\YY_t - \ZZ_t\XX_t - \aa_t) + +\sum_1^T \log |\RR_t|\\ +&\quad +\sum_1^T(\XX_t - \BB_t\XX_{t-1} - \uu_t)^\top \Qm_t (\XX_t - \BB_t\XX_{t-1} - \uu_t) + +\sum_1^T\log |\QQ_t| + \log 2\pi\bigg)\\ +&\quad \xx_0 \equiv \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} +This is the same as equation \ref{eq:logL.vec.general} except not written in vec form and $\LAM$ does not appear. Take the derivative of $\Psi$ using equation \ref{eq:logL.vec.general.V0.is.0b}. Terms not involving $\pp$ will drop out: +\begin{equation}\label{eq:pi.constrained.V0.is.0} +\begin{split} +&\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( -\E[\partial(\mathbb{P}_1^\top\Qm_1\BB_1\DD_\xi\pp)/\partial\pp] -\E[\partial(\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\mathbb{P}_1)/\partial\pp] \\ +&\quad +\E[\partial(\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\BB_1\DD_\xi\pp)/\partial\pp] +\bigg) +\end{split} +\end{equation} +where +\begin{equation} +\mathbb{P}_1=\XX_1 - \BB_1\ff_\xi - \uu_1 +\end{equation} + +After pulling the constants out of the expectations and taking the derivative, we arrive at: +\begin{equation} +\begin{split} +\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( - 2\E[\mathbb{P}_1]^\top\Qm_1\BB_1\DD_\xi ++ 2\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\BB_1\DD_\xi +\bigg) +\end{split} +\end{equation} +Set the left side to zero, and solve for $\pp$. +\begin{equation}\label{eq:pi.constrained.V0.is.0.4} +\pp = (\DD_\xi^\top\BB_1^\top\Qm_1\BB_1\DD_\xi)^{-1}\DD_\xi^\top\BB_1^\top\Qm_1(\hatxone - \BB_1\ff_\xi - \uu_1) +\end{equation} + +This equation requires that the inverse right of the $=$ exists and it might not if $\BB_t$ or $\Qm_1$ has any all zero rows/columns. In that case, defining $\xixi \equiv \xx_1$ might work (section \ref{sec:general.x1.update}) or the problematic rows of $\xixi$ could be fixed. +The new $\xixi$ is then, +\begin{equation} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} + +\subsection{The general $\xixi$ update equation, fixed $\xx_1$}\label{sec:general.x1.update} +When $\xx_1$ is treated as fixed, i.e., as an estimated parameter, and $\LAM$ does not appear, the expected log likelihood, $\Psi$, is written as follows: +\begin{equation}\label{eq:logL.vec.general.V0.is.0.x1} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - \ZZ_t\XX_t - \aa_t)^\top \Rm_t (\YY_t - \ZZ_t\XX_t - \aa_t) +\sum_1^T \log |\RR_t|\\ +&\quad +\sum_2^T(\XX_t - \BB_t\XX_{t-1} - \uu_t)^\top \Qm_t (\XX_t - \BB_t\XX_{t-1} - \uu_t) + +\sum_2^T\log |\QQ_t| + \log 2\pi\bigg)\\ +&\quad \xx_1 \equiv \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} +Take the derivative of $\Psi$ using equation \ref{eq:logL.vec.general.V0.is.0.x1}: +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( +-\E[\partial(\mathbb{O}_1^\top\Rm_1\ZZ_1\DD_\xi\pp)/\partial\pp] -\E[\partial((\ZZ_1\DD_\xi\pp)^\top\Rm_1\mathbb{O}_1)/\partial\pp] \\ +&\quad +\E[\partial((\ZZ_1\DD_\xi\pp)^\top\Rm_1\ZZ_1\DD_\xi\pp)/\partial\pp] + -\E[\partial(\mathbb{P}_2^\top\Qm_2\BB_2\DD_\xi\pp)/\partial\pp] -\E[\partial((\BB_2\DD_\xi\pp)^\top\Qm_2\mathbb{P}_2)/\partial\pp] \\ +&\quad +\E[\partial((\BB_2\DD_\xi\pp)^\top\Qm_2\BB_2\DD_\xi\pp)/\partial\pp] +\bigg) +\end{split} +\end{equation} +where +\begin{equation} +\begin{split} +\mathbb{P}_2&=\XX_2 - \BB_2\ff_\xi - \uu_2\\ +\mathbb{O}_1&=\YY_1 - \ZZ_1\ff_\xi - \aa_1\\ +\end{split} +\end{equation} + +In terms of the Kalman smoother output the new $\xixi$ for EM iteration $j+1$ when $\xixi \equiv \xx_1$ is +\begin{equation}\label{eq:pix1.unconstrained.V0.is.0.t.1.3} +\begin{split} +\pp_{j+1} &= ((\ZZ_1\DD_\xi)^\top\Rm_1\ZZ_1\DD_\xi + +(\BB_2\DD_\xi)^\top\Qm_2\BB_2\DD_\xi)^{-1} +( (\ZZ_1\DD_\xi)^\top\Rm_1\widetilde{\mathbb{O}}_1 + (\BB_2\DD_\xi)^\top\Qm_2\widetilde{\mathbb{P}}_2) +\end{split} +\end{equation} +where +\begin{equation} +\begin{split} +\widetilde{\mathbb{P}}_2 &=\widetilde{\mbox{$\mathbf x$}}_2 - \BB_2\ff_\xi - \uu_2\\ +\widetilde{\mathbb{O}}_1 &=\widetilde{\mbox{$\mathbf y$}}_1 - \ZZ_1\ff_\xi - \aa_1 +\end{split} +\end{equation} +The new $\xixi$ is +\begin{equation} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} + +\subsection{The general $\BB$ update equation} +Take the derivative of $\Psi$ with respect to $\bbeta$; terms in $\Psi$ do not involve $\bbeta$ will equal 0 and drop out. +\begin{equation}\label{eq:B.general1} +\begin{split} +\partial\Psi/\partial\bbeta + &= - \frac{1}{2}\sum_{t=1}^T \bigg( -\partial(\E[\XX_t^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + - \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\XX_t])/\partial\bbeta \\ +&+ \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + + \partial(\E[\uu_t^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta ++ \partial((\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\uu_t)/\partial\bbeta \\ +&+ \partial(\E[(\Bm_t\ff_{t,b})^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + + \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\Bm_t\ff_{t,b}])/\partial\bbeta +\bigg)\end{split} +\end{equation} +where +\begin{equation} +\Bm_t = (\XX_{t-1}^\top \otimes \II_m) +\end{equation}Since $\bbeta$ is to the far left or right in each term, the derivative is simple using the derivative terms in table \ref{sec:MatrixDerivatives}. +$\partial\Psi/\partial\bbeta$ becomes: +\begin{equation}\label{eq:B.general1b} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} +&= - \frac{1}{2}\sum_{t=1}^T \bigg( +-2\E[\XX_t^\top\Qm_t\Bm_t\DD_{t,b}] + 2(\beta^\top\DD_{t,b}^\top\Bm_t^\top\Qm_t\Bm_t\DD_{t,b}) \\ +&+ 2\E[\uu_t^\top\Qm_t\Bm_t\DD_{t,b}] + 2\E[(\Bm_t\ff_{t,b})^\top\Qm_t\Bm_t\DD_{t,b}] \bigg) +\end{split}\end{equation} +Note that $\XX$ appears in $\Bm_t$ but not in other terms. We need to keep track of where $\XX$ appears so the we keep the expectation brackets around any terms involving $\XX$. +\begin{equation} +\begin{split} +\partial\Psi/\partial\bbeta += \sum_{t=1}^T \bigg( +\E[\XX_t^\top\Qm_t\Bm_t]\DD_{t,b} - \uu_t^\top\Qm_t\E[\Bm_t]\DD_{t,b} +- \bbeta^\top\DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} - \ff_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} \bigg) +\end{split} +\end{equation} +Set the left side to zero and transpose the whole equation. +\begin{equation} +\mathbf{0} + = \sum_{t=1}^T \bigg( +\DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\XX_t]- \DD_{t,b}^\top\E[\Bm_t]^\top\Qm_t\uu_t + - \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\ff_{t,b} + - \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b}\bbeta \bigg) +\end{equation} +Thus, +\begin{equation} +\big(\sum_{t=1}^T \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} \big)\bbeta + = \sum_{t=1}^T \DD_{t,b}^\top\big( + \E[\Bm_t^\top\Qm_t\XX_t] + - \E[\Bm_t]^\top\Qm_t\uu_t + - \E[\Bm_t^\top\Qm_t\Bm_t]\ff_{t,b} \big) +\end{equation} +Now we need to deal with the expectations. +\begin{equation}\label{eq:B.expect1} +\begin{split} +\E[\Bm_t^\top\Qm_t\Bm_t] +&=\E[(\XX_{t-1}^\top \otimes \II_m)^\top\Qm_t(\XX_{t-1}^\top \otimes \II_m)]\\ +&=\E[(\XX_{t-1} \otimes \II_m)\Qm_t(\XX_{t-1}^\top \otimes \II_m)]\\ +&=\E[\XX_{t-1}\XX_{t-1}^\top \otimes \Qm_t]\\ +&=\E[\XX_{t-1}\XX_{t-1}^\top] \otimes \Qm_t\\ +&=\hatPtm \otimes \Qm_t +\end{split} +\end{equation} + +\begin{equation}\label{eq:B.expect2} +\begin{split} +\E[\Bm_t^\top\Qm_t\XX_t] +&=\E[(\XX_{t-1}^\top \otimes \II_m)^\top\Qm_t\XX_t]\\ +&=\E[(\XX_{t-1} \otimes \II_m)\Qm_t\XX_t]\\ +&=\E[(\XX_{t-1} \otimes \Qm_t)\XX_t]\\ +&=\E[\vec(\Qm_t\XX_t\XX_{t-1}^\top)]\\ +&=\vec(\Qm_t\hatPttm) +\end{split} +\end{equation} + +\begin{equation}\label{eq:B.expect3} +\begin{split} +\E[\Bm_t]^\top\Qm_t\uu_t&=(\E[\XX_{t-1}] \otimes \II_m)\Qm_t\uu_t \\ +&= (\hatxtm \otimes \Qm_t)\uu_t \\ +&= \vec(\Qm_t\uu_t\hatxtm^\top) +\end{split} +\end{equation} + +Thus, +\begin{equation} +\begin{split} +\big(\sum_{t=1}^T &\DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b} \big)\bbeta + = \sum_{t=1}^T \DD_{t,b}^\top \big(\vec(\Qm_t\hatPttm) - (\hatPtm \otimes \Qm_t)\ff_{t,b} - \vec(\Qm_t\uu_t\hatxtm^\top) \big) +\end{split} +\end{equation} +Then $\bbeta$ for the $j+1$ iteration of the EM algorithm is then: +\begin{equation}\label{eq:B.general4} +\begin{split} +\bbeta = \bigg(\sum_{t=1}^T \DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b} \bigg)^{-1} +\times \sum_{t=1}^T \DD_{t,b}^\top \big(\vec(\Qm_t\hatPttm) - (\hatPtm \otimes \Qm_t)\ff_{t,b} - \vec(\Qm_t\uu_t\hatxtm^\top) \big) +\end{split} +\end{equation} + +This requires that $\DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b}$ is invertible, and as usual we will run into trouble if $\Phi_t\QQ_t\Phi_t^\top$ has zeros on the diagonal. See section \ref{sec:degenerate}. + +\subsection{The general $\ZZ$ update equation}\label{sec:constZ} +The derivation of the update equation for $\zzeta$ with fixed and shared values is analogous to the derivation for $\bbeta$. The update equation for $\zzeta$ is +\begin{equation}\label{eq:general.Z.update} +\begin{split} +\zzeta_{j+1} = +\bigg(\sum_{t=1}^T \DD_{t,z}^\top(\hatPt \otimes \Rm_t)\DD_{t,z} \bigg)^{-1} +\times \sum_{t=1}^T \DD_{t,z}^\top \big(\vec(\Rm_t\hatYXt) - (\hatPt \otimes \Rm_t)\ff_{t,z} - \vec(\Rm_t\aa_t\hatxt^\top) \big) +\end{split} +\end{equation} + +This requires that $\DD_{t,z}^\top(\hatPt \otimes \Rm_t)\DD_{t,z}$ is invertible. If $\Xi_t\RR_t\Xi_t^\top$ has zeros on the diagonal, this will not be the case. See section \ref{sec:degenerate}. + +\subsection{The general $\QQ$ update equation}\label{sec:constrained.Q} +A general analytical solution for $\QQ$ is problematic because the inverse of $\QQ_t$ appears in the likelihood and $\QQ_t^{-1}$ cannot always be rewritten as a function of $\vec(\QQ_t)$. However, in a few important special---yet quite broad--- cases, an analytical solution can be derived. The most general of these special cases is a block-symmetric matrix with optional independent fixed blocks (subsection \ref{sec:Q.general}). Indeed, all other cases (diagonal, block-diagonal, unconstrained, equal variance-covariance) except one (a replicated block-diagonal) are special cases of the blocked matrix with optional independent fixed blocks. + +Unlike the other parameters, I need to put constraints on $\ff$ and $\DD$. I constrain $\DD$ to be a design matrix. It has only 1s and 0s, and the rows sums are either 1 or 0. Thus terms like $q_1+q_2$ are not allowed. A non-zero value in $\ff$ is only allowed if the corresponding row in $\DD$ is all zero. Thus elements like $f_1+q_1$ are not allowed in $\QQ$. These constraints, especially the constraint that $\DD$ only has 0s and 1s, might be loosened, but with the addition of $\GG_t$, we still have a very wide class of $\QQ$ matrices. + +The general update equation for $\QQ$ with these constraints is +\begin{equation}\label{eq:Q.general} +\begin{split} +\qq_{j+1} &= \big(\sum_{t=1}^T(\DD_{t,q}^\top\DD_{t,q})\big)^{-1} \sum_{t=1}^T\DD_{t,q}^\top\vec(\SS_t)\\ +\text{where }\SS_t&=\Phi_t\big(\hatPt - \hatPttm \BB_t^\top - \BB_t\hatPtmt +- \hatxt\uu_t^\top - \uu_t\hatxt^\top + \\ +&\quad \BB_t\hatPtm\BB_t^\top + \BB_t\hatxtm\uu_t^\top + \uu_t\hatxtm^\top\BB_t^\top + \uu_t\uu_t^\top \big)\Phi_t^\top\\ +\vec(\QQ_t)_{j+1}&=\ff_{t,q}+\DD_{t,q}\qq_{j+1} \\ +\text{where}\\ +\Phi_t = (\GG_t^\top\GG_t)^{-1}\GG_t^\top +\end{split} +\end{equation} + +The vec of $\QQ_t$ is written in the form of $\vec(\QQ_t) = \ff_{t,q} + \DD_{t,q} \pmb{q}$, where $\ff_{t,q}$ is a $p^2 \times 1$ column vector of the fixed values including zero, $\DD_{t,q}$ is the $p^2 \times s$ design matrix, and $\pmb{q}$ is a column vector of the $s$ free values in $\QQ_t$. This requires that $(\DD_{t,q}^\top\DD_{t,q})$ be invertible, which in a valid model must be true; if is not true you have specified an invalid variance-covariance structure since the implied variance-covariance matrix will not be full-rank and not invertible and thus an invalid variance-covariance matrix. + +Below I show how the $\QQ$ update equation arises by working through a few of the special cases. In these derivations the $q$ subscript is left off the $\DD$ and $\ff$ matrices. + +\subsubsection{Special case: diagonal $\QQ$ matrix (with shared or unique parameters)} +Let $\QQ$ be a non-time varying diagonal matrix with fixed and shared values such that it takes a form like so: +\begin{equation*} +\QQ= +\begin{bmatrix} +q_1&0&0&0&0\\ +0&f_1&0&0&0\\ +0&0&q_2&0&0\\ +0&0&0&f_2&0\\ +0&0&0&0&q_2 +\end{bmatrix} +\end{equation*} +Here, $f$'s are fixed values (constants) and $q$'s are free parameters elements. The $f$ and $q$ do not occur together; i.e., there are no terms like $f_1+q_1$. + + +The vec of $\QQ^{-1}$ can be written then as $\vec(\QQ^{-1}) = \ff^{*}_q + \DD_q \pmb{q^{*}}$, where $\ff^{*}$ is like $\ff_q$ but with the corresponding $i$-th non-zero fixed values replaced by $1/f_i$ and $\pmb{q^{*}}$ is a column vector of 1 over the $q_i$ values. For the example above, +\begin{equation*} +\pmb{q^{*}} = +\begin{bmatrix} +1/q_1 \\ 1/q_2 +\end{bmatrix} +\end{equation*} + +Take the partial derivative of $\Psi$ with respect to $\pmb{q^{*}}$. We can do this because $\QQ^{-1}$ is diagonal and thus each element of $\pmb{q^{*}}$ is independent of the other elements; otherwise we would not necessarily be able to vary one element of $\pmb{q^{*}}$ while holding the other elements constant. +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\partial\bigg( +\E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] +-\E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] \\ +&\quad -\E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] + - \E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t] \\ +&\quad - \E[\uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] ++ \E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] \\ +&\quad + \E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t] ++ \E[\uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] + \uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t \bigg)/\partial\pmb{q^{*}}\\ +& - \partial\big(\frac{T}{2}\log |\QQ| \big)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +Use vec operation Equation \ref{eq:vec.aTBa} to pull $\QQ^{-1}$ out from the middle\footnote{Another, more common, way to do this is to use a ``trace trick'', $\trace(\aa^\top\AA\bb)=\trace(\AA\bb\aa^\top)$, to pull $\QQ^{-1}$ out.}, using +$$\aa^\top \Phi^\top \QQ^{-1} \Phi \bb = (\bb^\top\Phi^\top \otimes \aa^\top \Phi^\top)\vec(\QQ^{-1}) = (\bb^\top \otimes \aa^\top)(\Phi^\top \otimes \Phi^\top)\vec(\QQ^{-1})$$. +Then replace the expectations with the Kalman smoother output, +\begin{equation}\label{eq:Q.gendiag2} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\partial\bigg( +\E[\XX_t^\top \otimes \XX_t^\top ] +-\E[\XX_t^\top \otimes (\BB_t\XX_{t-1})^\top] -\E[(\BB_t\XX_{t-1})^\top \otimes \XX_t^\top] \\ +&\quad - \E[\XX_t^\top \otimes \uu_t^\top] - \E[\uu_t^\top \otimes \XX_t^\top] ++ \E[(\BB_t\XX_{t-1})^\top \otimes (\BB_t\XX_{t-1})^\top] \\ +&\quad + \E[(\BB_t\XX_{t-1})^\top \otimes \uu_t^\top] ++ \E[\uu_t^\top \otimes (\BB\XX_{t-1})^\top] + (\uu_t^\top \otimes \uu_t^\top) \bigg)(\Phi_t \otimes \Phi_t)^\top\vec(\QQ^{-1})/\partial\pmb{q^{*}}\\ +& - \partial\bigg(\frac{T}{2}\log |\QQ| \bigg)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +This can be further reduced using +$$(\bb^\top \otimes \aa^\top)(\Phi^\top \otimes \Phi^\top)=(\vec(\aa\bb^\top))^\top (\Phi \otimes \Phi)^\top = \vec(\Phi \aa\bb^\top \Phi^\top)^\top$$ +With this reduction and replacing $\log|\QQ|$ with $-\log|\QQ^{-1}|$, we get +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\vec(\SS_t)^\top\partial\big(\vec(\QQ^{-1})\big)/\partial\pmb{q^{*}} ++ \partial\big(\frac{T}{2}\log|\QQ^{-1}| \big)/\partial\pmb{q^{*}} \\ +&\text{where }\\ +&\SS_t=\Phi_t\big(\hatPt - \hatPttm \BB_t^\top - \BB\hatPtmt +- \hatxt\uu_t^\top - \uu_t \hatxt^\top + \\ +&\quad \BB_t\hatPtm\BB_t^\top + \BB_t\hatxtm\uu_t^\top + \uu_t\hatxtm^\top\BB_t^\top + \uu_t\uu_t^\top \big)\Phi_t^\top +\end{split} +\end{equation} +The determinant of a diagonal matrix is the product of its diagonal elements. Thus, +\begin{equation}\label{eq:Q.gendiag3} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}}= + -\bigg(\frac{1}{2} \sum_{t=1}^T \vec(\SS_t)^\top (\ff^{*} + \DD_q\pmb{q^{*}}) \\ +&\quad - \frac{1}{2}\sum_{t=1}^T(\log(f^{*}_1) + \log(f^{*}_2) ... k\log(q^{*}_1) + l\log(q^{*}_2)...)\bigg)/\partial\pmb{q^{*}}\\ +\end{split} +\end{equation} +where $k$ is the number of times $q_1$ appears on the diagonal of $\QQ$ and $l$ is the number of times $q_2$ appears, etc. + +Taking the derivatives and transposing the whole equation we get, +\begin{equation}\label{eq:Q.gendiag4} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = += \frac{1}{2} \sum_{t=1}^T\DD_q^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T(\log(f^{*}_1) + ... k\log(q^{*}_1) + l\log(q^{*}_2)...)/\partial\pmb{q^{*}}\\ +&\quad = \frac{1}{2} \sum_{t=1}^T\DD_q^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T\DD_q^\top\DD_q\pmb{q} +\end{split} +\end{equation} +$\DD_q^\top\DD_q$ is a $s \times s$ matrix with $k$, $l$, etc. along the diagonal and thus is invertible; as usual, $s$ is the number of free elements in $\QQ$. Set the left side to zero (a $1 \times s$ matrix of zeros) and solve for $\pmb{q}$. This gives us the update equation for $\qq$ and $\QQ$: +\begin{equation}\label{eq:Q.diag.update} +\begin{split} +\qq_{j+1} &= \big(\sum_{t=1}^T\DD_q^\top\DD_q\big)^{-1}\sum_{t=1}^T\DD_q^\top\vec(\SS_t)\\ +\vec(\QQ)_{j+1} &= \ff + \DD_q\pmb{q}_{j+1} +\end{split} +\end{equation} +Since in this example, $\DD_q$ is time-constant, this reduces to +\begin{equation*} +\pmb{q}_{j+1} = \frac{1}{T}(\DD_q^\top\DD_q)^{-1}\DD_q^\top\sum_{t=1}^T\vec(\SS_t) +\end{equation*} +$\SS_t$ is defined in equation \ref{eq:Q.gendiag2}. + +\subsubsection{Special case: $\QQ$ with one variance and one covariance} +\begin{equation*} +\QQ= +\begin{bmatrix} +\alpha&\beta&\beta&\beta\\ +\beta&\alpha&\beta&\beta\\ +\beta&\beta&\alpha&\beta\\ +\beta&\beta&\beta&\alpha +\end{bmatrix}\quad\quad +\QQ^{-1}= +\begin{bmatrix} +f(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&f(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&g(\alpha,\beta)&f(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)&f(\alpha,\beta) +\end{bmatrix} +\end{equation*} +This is a matrix with a single shared variance parameter on the diagonal and a single shared covariance on the off-diagonals. The derivation is the same as for the diagonal case, until the step involving the differentiation of $\log|\QQ^{-1}|$: +\begin{equation}\label{eq:Q.eqvarcov1} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = + \partial\bigg(-\frac{1}{2} \sum_{t=1}^T\big(\vec(\SS_t)^\top\big)\vec(\QQ^{-1}) ++ \frac{T}{2}\log |\QQ^{-1}|\bigg)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +It does not make sense to take the partial derivative of $\log |\QQ^{-1}|$ with respect to $\vec(\QQ^{-1})$ because many elements of $\QQ^{-1}$ are shared so it is not possible to fix one element while varying another. Instead, we can take the partial derivative of $\log |\QQ^{-1}|$ with respect to $g(\alpha,\beta)$ which is $\sum_{\{i,j\}\in \text{set}_g}\partial\log|\QQ^{-1}|/\partial\pmb{q^{*}}_{i,j}$. Set $g$ is those $i,j$ values where $\pmb{q^{*}}=g(\alpha,\beta)$. Because $g()$ and $f()$ are different functions of both $\alpha$ and $\beta$, we can hold one constant while taking the partial derivative with respect to the other (well, presuming there exists some combination of $\alpha$ and $\beta$ that would allow that). But if we have fixed values on the off-diagonal, this would not be possible. In this case (see below), we cannot hold $g()$ constant while varying $f()$ because both are only functions of $\alpha$: +\begin{equation*} +\QQ= +\begin{bmatrix} +\alpha&f&f&f\\ +f&\alpha&f&f\\ +f&f&\alpha&f\\ +f&f&f&\alpha +\end{bmatrix}\quad\quad +\QQ^{-1}= +\begin{bmatrix} +f(\alpha)&g(\alpha)&g(\alpha)&g(\alpha)\\ +g(\alpha)&f(\alpha)&g(\alpha)&g(\alpha)\\ +g(\alpha)&g(\alpha)&f(\alpha)&g(\alpha)\\ +g(\alpha)&g(\alpha)&g(\alpha)&f(\alpha) +\end{bmatrix} +\end{equation*} + +Taking the partial derivative of $\log |\QQ^{-1}|$ with respect to $\pmb{q^{*}}=\big[\begin{smallmatrix}f(\alpha,\beta)\\g(\alpha,\beta)\end{smallmatrix}\big]$, we arrive at the same equation as for the diagonal matrix: +\begin{equation}\label{eq:Q.eqvarcov2} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = +\frac{1}{2} \sum_{t=1}^T\DD^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T(\DD^\top\DD)\pmb{q} +\end{split} +\end{equation} +where here $\DD^\top\DD$ is a $2 \times 2$ diagonal matrix with the number of times $f(\alpha,\beta)$ appears in element $(1,1)$ and the number of times $g(\alpha,\beta)$ appears in element $(2,2)$ of $\DD$; $s=2$ here since there are only 2 free parameters in $\QQ$. + +Setting to zero and solving for $\pmb{q^{*}}$ leads to the exact same update equation as for the diagonal $\QQ$, namely equation \ref{eq:Q.diag.update} in which $\ff_q = 0$ since there are no fixed values. + +\subsubsection{Special case: a block-diagonal matrices with replicated blocks} +\label{sec:Q.block.diagonal} +Because these operations extend directly to block-diagonal matrices, all results for individual matrix types can be extended to a block-diagonal matrix with those types: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{B}_1&0&0\\ +0&\mathbb{B}_2&0\\ +0&0&\mathbb{B}_3\\ +\end{bmatrix} +\end{equation*} +where $\mathbb{B}_i$ is a matrix from any of the allowed matrix types, such as unconstrained, diagonal (with fixed or shared elements), or equal variance-covariance. Blocks can also be shared: +\begin{equation*}\QQ= +\begin{bmatrix} +\mathbb{B}_1&0&0\\ +0&\mathbb{B}_2&0\\ +0&0&\mathbb{B}_2\\ +\end{bmatrix} +\end{equation*} +but the entire block must be identical $(\mathbb{B}_2 \equiv \mathbb{B}_3)$; one cannot simply share individual elements in different blocks. Either all the elements in two (or 3, or 4...) blocks are shared or none are shared. + +This is ok: +\begin{equation*} +\begin{bmatrix} +c&d&d&0&0&0\\ +d&c&d&0&0&0\\ +d&d&c&0&0&0\\ +0&0&0&c&d&d\\ +0&0&0&d&c&d\\ +0&0&0&d&d&c\\ +\end{bmatrix} +\end{equation*} +This is not ok: +\begin{equation*} +\begin{bmatrix} +c&d&d&0&0\\ +d&c&d&0&0\\ +d&d&c&0&0\\ +0&0&0&c&d\\ +0&0&0&d&c +\end{bmatrix} +\text{ nor } +\begin{bmatrix} +c&d&d&0&0&0\\ +d&c&d&0&0&0\\ +d&d&c&0&0&0\\ +0&0&0&c&e&e\\ +0&0&0&e&c&e\\ +0&0&0&e&e&c\\ +\end{bmatrix}\end{equation*} +The first is bad because the blocks are not identical; they need the same dimensions as well as the same values. The second is bad because again the blocks are not identical; all values must be the same. + +\subsubsection{Special case: a symmetric blocked matrix} +\label{sec:Q.symmetric blocked} +The same derivation translates immediately to blocked symmetric $\QQ$ matrices with the following form: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\\ +\end{bmatrix} +\end{equation*} +where the $\mathbb{E}$ are as above matrices with one value on the diagonal and another on the off-diagonals (no zeros!). The $\mathbb{C}$ matrices have only one free value or are all zero. Some $\mathbb{C}$ matrices can be zero while are others are non-zero, but a individual $\mathbb{C}$ matrix cannot have a combination of free values and zero values; they have to be one or the other. Also the whole matrix must stay block symmetric. Additionally, there can be shared $\mathbb{E}$ or $\mathbb{C}$ matrices but the whole matrix needs to stay block-symmetric. Here are the forms that $\mathbb{E}$ and $\mathbb{C}$ can take: +\begin{equation*} +\mathbb{E}_i= +\begin{bmatrix} +\alpha&\beta&\beta&\beta\\ +\beta&\alpha&\beta&\beta\\ +\beta&\beta&\alpha&\beta\\ +\beta&\beta&\beta&\alpha +\end{bmatrix} +\quad\quad +\mathbb{C}_i= +\begin{bmatrix} +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi +\end{bmatrix} +\text{ or } +\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation*} +The following are block-symmetric: +\begin{equation*} +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\\ +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}&\mathbb{C}&\mathbb{C}\\ +\mathbb{C}&\mathbb{E}&\mathbb{C}\\ +\mathbb{C}&\mathbb{C}&\mathbb{E}\\ +\end{bmatrix} +\end{equation*} +\begin{equation*} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_1&\mathbb{E}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_{1,2}&\mathbb{C}_{1,2}&\mathbb{E}_2\\ +\end{bmatrix} +\end{equation*} +The following are NOT legal block-symmetric matrices: +\begin{equation*} +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&0\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +0&\mathbb{C}_{2,3}&\mathbb{E}_3 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&0&\mathbb{C}_1\\ +0&\mathbb{E}_1&\mathbb{C}_2\\ +\mathbb{C}_1&\mathbb{C}_2&\mathbb{E}_2 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&0&\mathbb{C}_{1,2}\\ +0&\mathbb{E}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_{1,2}&\mathbb{C}_{1,2}&\mathbb{E}_2\\ +\end{bmatrix} +\end{equation*} +\begin{equation*} +\text{ and } +\begin{bmatrix} +\mathbb{U}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{D}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\end{bmatrix} +\end{equation*} +In the first row, the matrices have fixed values (zeros) and free values (covariances) on the same off-diagonal row and column. That is not allowed. If there is a zero on a row or column, all other terms on the off-diagonal row and column must be also zero. In the second row, the matrix is not block-symmetric since the upper corner is an unconstrained block ($\mathbb{U}_1$) in the left matrix and diagonal block ($\mathbb{D}_1$) in the right matrix instead of a equal variance-covariance matrix ($\mathbb{E}$). + +\subsubsection{The general case: a block-diagonal matrix with general blocks} +\label{sec:Q.general} +In it's most general form, $\QQ$ is allowed to have a block-diagonal form where the blocks, here called $\mathbb{G}$ are any of the previous allowed cases. No shared values across $\mathbb{G}$'s; shared values are allowed within $\mathbb{G}$'s. +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{G}_1&0&0\\ +0&\mathbb{G}_2&0\\ +0&0&\mathbb{G}_3\\ +\end{bmatrix} +\end{equation*} +The $\mathbb{G}$'s must be one of the special cases listed above: unconstrained, diagonal (with fixed or shared values), equal variance-covariance, block diagonal (with shared or unshared blocks), and block-symmetric (with shared or unshared blocks). Fixed blocks are allowed, but then the covariances with the free blocks must be zero: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{F}&0&0&0\\ +0&\mathbb{G}_1&0&0\\ +0&0&\mathbb{G}_2&0\\ +0&0&0&\mathbb{G}_3 +\end{bmatrix} +\end{equation*} +Fixed blocks must have only fixed values (zero is a fixed value) but the fixed values can be different from each other. The free blocks must have only free values (zero is not a free value). + +\subsection{The general $\RR$ update equation} +The $\RR$ update equation for blocked symmetric matrices with optional independent fixed blocks is completely analogous to the $\QQ$ equation. Thus if $\RR$ has the form +\begin{equation*} +\RR= +\begin{bmatrix} +\mathbb{F}&0&0&0\\ +0&\mathbb{G}_1&0&0\\ +0&0&\mathbb{G}_2&0\\ +0&0&0&\mathbb{G}_3 +\end{bmatrix} +\end{equation*} +Again the $\mathbb{G}$'s must be one of the special cases listed above: unconstrained, diagonal (with fixed or shared values), equal variance-covariance, block diagonal (with shared or unshared blocks), and block-symmetric (with shared or unshared blocks). Fixed blocks are allowed, but then the covariances with the free blocks must be zero. Elements like $f_i+r_j$ and $r_i+r_j$ are not allowed in $\RR$. Only elements of the form $f_i$ and $r_i$ are allowed. If an element has a fixed component, it must be completely fixed. Each element in $\RR$ can have only one of the elements in $\rr$, but multiple elements in $\RR$ can have the same $\rr$ element. + +The update equation is +\begin{equation}\label{eq:R.general} +\begin{split} +&\rr_{j+1} = +\bigg(\sum_{t=1}^T\DD_{t,r}^\top \DD_{t,r}\bigg)^{-1} \sum_{t=1}^T \DD_{t,r}^\top\vec\bigg(\TT_{t,{j+1}} + \bigg)\\ +&\quad\quad\quad\quad\vec(\RR_t)_{j+1} = \ff_{t,r} + \DD_{t,r} \rr_{j+1} +\end{split} +\end{equation} +The $\TT_{t,j+1}$ used at time step $t$ in equation \ref{eq:R.general} is the term that appears in the summation in the unconstrained update equation with no missing values (equation \ref{eq:R.update.unconstrained}): +\begin{equation} +\begin{split} +\TT_{t,j+1}=\Xi_t\bigg( + \hatOt - \hatYXt\ZZ_t^\top - \ZZ_t\hatYXt^\top + - \hatyt\aa_t^\top - \aa_t\hatyt^\top + + \ZZ_t\hatPt\ZZ_t^\top + \ZZ_t\hatxt\aa_t^\top + \aa_t\hatxt^\top\ZZ_t^\top + + \aa_t\aa_t^\top \bigg)\Xi_t^\top +\end{split} +\end{equation} +where $\Xi_t = (\HH_t^\top\HH_t)^{-1}\HH_t^\top$. + + +\section{Computing the expectations in the update equations}\label{sec:compexpectations} +For the update equations, we need to compute the expectations of $\XX_t$ and $\YY_t$ and their products conditioned on 1) the observed data $\YY(1)=\yy(1)$ and 2) the parameters at time $t$, $\Theta_j$. This section shows how to compute these expectations. Throughout the section, I will normally leave off the conditional $\YY(1)=\yy(1),\Theta_j$ when specifying an expectation. Thus any $\E[ ]$ appearing without its conditional is conditioned on $\YY(1)=\yy(1),\Theta_j$. However if there are additional or different conditions those will be shown. Also all expectations are over the joint distribution of $XY$ unless explicitly specified otherwise. + +Before commencing, we need some notation for the observed and unobserved elements of the data. +The $n \times 1$ vector $\yy_t$ denotes the potential observations at time $t$. If some elements of $\yy_t$ are missing, that means some elements are equal to NA (or some other missing values marker): +\begin{equation} +\yy_t=\begin{bmatrix} +y_1\\ +NA\\ +y_3\\ +y_4\\ +NA\\ +y_6 +\end{bmatrix} +\end{equation} +We denote the non-missing observations as $\yy_t(1)$ and the missing observations as $\yy_t(2)$. Similar to $\yy_t$, $\YY_t$ denotes all the $\YY$ random variables at time $t$. The $\YY_t$'s with an observation are $\YY_t(1)$ and those without an observation are denoted $\YY_t(2)$. + +Let $\OMG_t^{(1)}$ be the matrix that extracts only $\YY_t(1)$ from $\YY_t$ and $\OMG_t(2)$ be the matrix that extracts only $\YY_t(2)$. For the example above, +\begin{equation} +\begin{split} +&\YY_t(1)=\OMG_t^{(1)} \YY_t,\quad \OMG_t^{(1)} = +\begin{bmatrix} +1&0&0&0&0&0\\ +0&0&1&0&0&0\\ +0&0&0&1&0&0\\ +0&0&0&0&0&1\\ +\end{bmatrix}\\ +&\YY_t(2)=\OMG_t^{(2)} \YY_t,\quad \OMG_t^{(2)} = +\begin{bmatrix} +0&1&0&0&0&0\\ +0&0&0&0&1&0 +\end{bmatrix} +\end{split} +\end{equation} + +We will define another set of matrices that zeros out the missing or non-missing values. Let $\IIm_t^{(1)}$ denote a diagonal matrix that zeros out the $\YY_t(2)$ in $\YY_t$ and $\IIm_t^{(2)}$ denote a matrix that zeros out the $\YY_t(1)$ in $\YY_t$. For the example above, +\begin{equation} +\begin{split} +\IIm_t^{(1)} &= (\OMG_t^{(1)})^\top\OMG_t^{(1)} = +\begin{bmatrix} +1&0&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&1&0&0&0\\ +0&0&0&1&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&0&1\\ +\end{bmatrix}\quad\text{and}\\ +\IIm_t^{(2)} &= (\OMG_t^{(2)})^\top\OMG_t^{(2)} = +\begin{bmatrix} +0&0&0&0&0&0\\ +0&1&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&1&0\\ +0&0&0&0&0&0\\ +\end{bmatrix}. +\end{split} +\end{equation} + +\subsection{Expectations involving only $\XX_t$}\label{sec:kalman.smoother} +The Kalman smoother provides the expectations involving only $\XX_t$ conditioned on all the data from time 1 to $T$. The Kalman filter provides the expectations involving only $\XX_t$ conditioned on all the data from time 1 to $t-1$ and from time 1 to $t$. For the EM algorithm, we only need the smoother output and the expected values conditioned on the data from time 1 to $T$ and these are denoted with special symbol of a tilde over a variable. + +To present the algorithm for the Kalman smoother and filter, the expectations conditioned on time 1 to $t$ are needed. The notation for this general case will be $\xx_t^t$ to denote $\E[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]$ where $\yy(1)_1^t$ means the observed data (the $(1)$ part) from time 1 to $t$ (the superscript). This is fairly common notation for the conditional expectations in a Kalman filter and smoother and it is important to note that the superscript is not a power notation but the upper time extent. The the expectations used in the previous sections on the EM algorithm are the following: + +\begin{subequations}\label{eq:kfsoutput} +\begin{align} +&\hatxt \equiv \xx_t^T = \E[\XX_t|\YY(1)_1^T=\yy(1)_1^T,\Theta]\label{eq:xt}\\ +&\widetilde{\VV}_t \equiv \VV_t^T = \var[\XX_t|\YY(1)_1^T=\yy(1)_1^T,\Theta]\\ +&\widetilde{\VV}_{t,t-1} \equiv \VV_{t,t-1}^T = \cov[\XX_t,\XX_{t-1}|\YY(1)_1^T=\yy(1)_1^T,\Theta]\\ +&\text{From $\hatxt$, $\widetilde{\VV}_t$, and $\widetilde{\VV}_{t,t-1}$, we compute}\nonumber\\ +&\hatPt \equiv \PP_t^T =\E[\XX_t\XX_t^\top|\YY(1)_1^T=\yy(1)_1^T,\Theta]= \widetilde{\VV}_t + \hatxt\hatxt^\top\label{eq:Pt}\\ +&\hatPttm \equiv \PP_{t,t-1}^T =\E[\XX_{t}\XX_{t-1}^\top|\YY(1)_1^T=\yy(1)_1^T,\Theta]=\widetilde{\VV}_{t,t-1} +\hatxt\hatxtm^\top\label{eq:Ptt1} +\end{align} +\end{subequations} +The $\hatPt$ and $\hatPttm$ equations arise from the computational formula for variance (equation \ref{eq:comp.formula.variance}). When comparing the Kalman filter and smoother algorithms here to Shumway and Stoffer, keep in mind the difference in notation: $P_t^n$ in Shumway and Stoffer is $\VV_t^T$ here not $\PP_t^T$. + +In the presentation of the EM algorithm, $\YY(1)_1^T=\yy(1)_1^T,\Theta$ was dropped from the expectations to remove clutter; thus $E[\dots]$ always denoted the conditional expectation $\E[\dots|\YY(1)_1^T=\yy(1)_1^T,\Theta]$. To present the smoother algorithm, I present the other conditional expectations. +\begin{subequations}\label{eq:kffilteroutput} +\begin{align} +&\xx_t^{t-1} = \E[\XX_t|\YY(1)_1^{t-1}=\yy(1)_1^{t-1},\Theta]\\ +&\xx_t^t = \E[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]\\ +&\VV_t^{t-1} = \var[\XX_t|\YY(1)_1^{t-1}=\yy(1)_1^{t-1},\Theta]\\ +&\VV_t^t = \var[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]\\ +\end{align} +\end{subequations} + +The first part of the Kalman smoother algorithm is the Kalman filter which gives the expectation at time $t$ conditioned on the data up to time $t$. The following the filter as shown in \citep[section 6.2, p. 331]{ShumwayStoffer2006}, although the notation is a little different. The recursion starts at time $t=1$ and repeats until $t=T$. +\begin{subequations}\label{eq:kffilter} +\begin{align} +&\xx_t^{t-1}=\BB_t\xx_{t-1}^{t-1}+\uu_t\label{eq:xtt1}\\ +&\VV_t^{t-1}=\BB_t\VV_{t-1}^{t-1}\BB_t^\top + \GG_t\QQ_t\GG_t^\top\label{eq:Vtt1}\\ +&\xx_t^t=\xx_t^{t-1}+\KK_t(\yy_t-\ZZ_t\xx_t^{t-1}-\aa_t)\label{eq:xtt}\\ +&\VV_t^t=(\II_m-\KK_t\ZZ_t)\VV_t^{t-1}\label{eq:Vtt}\\ +&\KK_t=\VV_t^{t-1}\ZZ_t^\top(\ZZ_t\VV_t^{t-1}\ZZ_t^\top+\HH_t\RR_t\HH_t^\top)^{-1}\label{eq:Kt} +\end{align} +\end{subequations} +If the initial value is defined at $t=0$, then the filter starts at $t=1$ with the first two equations with $\xx_{0}^{0} \equiv \xixi$ and $\VV_{0}^{}\equiv\LAM$. If the initial value is defined at $t=1$, then the filter starts at $t=1$ with the third and fourth equations with $\xx_{1}^{0}\equiv\xixi$ and $\VV_{1}^{0}\equiv\LAM$. + + +The Kalman smoother and lag-1 covariance smoother compute the expectations conditioned on all the data, 1 to $T$: +\begin{subequations}\label{eq:kfsmoother} +\begin{align} +&\xx_{t-1}^T=\xx_{t-1}^{t-1}+\JJ_{t-1}(\xx_t^T-\xx_t^{t-1})\label{eq:xt1T}\\ +&\VV_{t-1}^T=\VV_{t-1}^{t-1}+\JJ_{t-1}(\VV_t^T-\VV_t^{t-1})\JJ_{t-1}^\top\label{eq:Vt1T}\\ +&\JJ_{t-1}=\VV_{t-1}^{t-1}\BB_t^\top(\VV_t^{t-1})^{-1}\label{eq:Jt}\\ +\\ +&\VV_{T,T-1}^T=(\II-\KK_T\ZZ_T)\BB_T\VV_{T-1}^{T-1}\label{eq:VTT1T}\\ +&\VV_{t-1,t-2}^T=\VV_{t-1}^{t-1}\JJ_{t-2}^\top + \JJ_{t-1}((\VV_{t,t-1}^T-\BB_t\VV_{t-1}^{t-1}))\JJ_{t-2}^\top\label{eq:Vtt1T} +\end{align} +\end{subequations} + +The classic Kalman smoother is an algorithm to compute these expectations conditioned on no missing values in $\yy$. However, the algorithm can be easily modified to give the expected values of $\XX$ conditioned on the incomplete data, $\YY(1)=\yy(1)$ \citep[section 6.4, eqn 6.78, p. 348]{ShumwayStoffer2006}. +In this case, the usual filter and smoother equations are used with the following modifications to the parameters and data used in the equations. If the $i$-th element of $\yy_t$ is missing, zero out the $i$-th rows in $\yy_t$, $\aa$ and $\ZZ$. Thus if the 2nd and 5th elements of $\yy_t$ are missing, +\begin{equation}\label{eq:yaZ.miss} +\yy_t^*=\begin{bmatrix} +y_1\\ +0\\ +y_3\\ +y_4\\ +0\\ +y_6\\ +\end{bmatrix}, \quad +\aa_t^*=\begin{bmatrix} +a_1\\ +0\\ +a_3\\ +a_4\\ +0\\ +a_6\\ +\end{bmatrix}, \quad +\ZZ_t^*=\begin{bmatrix} +z_{1,1}&z_{1,2}&...\\ +0&0&...\\ +z_{3,1}&z_{3,2}&...\\ +z_{4,1}&z_{4,2}&...\\ +0&0&...\\ +z_{6,1}&z_{6,2}&...\\ +\end{bmatrix} +\end{equation} + +The $\RR_t$ parameter used in the filter equations is also modified. We need to zero out the covariances between the non-missing, $\yy_t(1)$, and missing, $\yy_t(2)$, data. For the example above, if +\begin{equation} +\RR_t = \Rb_t\RR\Rb_t^\top = \begin{bmatrix} +r_{1,1}&r_{1,2}&r_{1,3}&r_{1,4}&r_{1,5}&r_{1,6}\\ +r_{2,1}&r_{2,2}&r_{2,3}&r_{2,4}&r_{2,5}&r_{2,6}\\ +r_{3,1}&r_{3,2}&r_{3,3}&r_{3,4}&r_{3,5}&r_{3,6}\\ +r_{4,1}&r_{4,2}&r_{4,3}&r_{4,4}&r_{4,5}&r_{4,6}\\ +r_{5,1}&r_{5,2}&r_{5,3}&r_{5,4}&r_{5,5}&r_{5,6}\\ +r_{6,1}&r_{6,2}&r_{6,3}&r_{6,4}&r_{6,5}&r_{6,6}\\ +\end{bmatrix} +\end{equation} +then the $\RR_t$ we use at time $t$, will have zero covariances between the non-missing elements 1,3,4,6 and the missing elements 2,5: +\begin{equation} +\RR_t^* + = \begin{bmatrix} +r_{1,1}&0&r_{1,3}&r_{1,4}&0&r_{1,6}\\ +0&r_{2,2}&0&0&r_{2,5}&0\\ +r_{3,1}&0&r_{3,3}&r_{3,4}&0&r_{3,6}\\ +r_{4,1}&0&r_{4,3}&r_{4,4}&0&r_{4,6}\\ +0&r_{5,2}&0&0&r_{5,5}&0\\ +r_{6,1}&0&r_{6,3}&r_{6,4}&0&r_{6,6}\\ +\end{bmatrix} +\end{equation} + +Thus, the data and parameters used in the filter and smoother equations are +\begin{equation} +\begin{split} +\yy_t^*&=\IIm_t^{(1)}\yy_t\\ +\aa_t^*&=\IIm_t^{(1)}\aa_t\\ +\ZZ_t^*&=\IIm_t^{(1)}\ZZ_t\\ +\RR_t^* &= \IIm_t^{(1)}\RR_t\IIm_t^{(1)} + \IIm_t^{(2)}\RR_t\II_t^{(2)} +\end{split} +\end{equation} +$\aa_t^*$, $\ZZ_t^*$ and $\RR_t^*$ only are used in the Kalman filter and smoother. They are not used in the EM update equations. However when coding the algorithm, it is convenient to replace the NAs (or whatever the missing values placeholder is) in $\yy_t$ with zero so that there is not a problem with NAs appearing in the computations. + +\subsection{Expectations involving $\YY_t$}\label{sec:exp.Y} +First, replace the missing values in $\yy_t$ with zeros\footnote{The only reason is so that in your computer code, if you use NA or NaN as the missing value marker, NA-NA=0 and 0*NA=0 rather than NA.} and then the expectations are given by the following equations. The derivations for these equations are given in the subsections to follow. +\begin{subequations}\label{eq:Yt.exp} +\begin{align} +\hatyt &= \E[\YY_t]=\yy_t-\IR_t(\yy_t-\ZZ_t\hatxt-\aa_t)\label{eq:hatyt}\\ +\hatOt &= \E[\YY_t\YY_t^\top]=\IIm_t^{(2)}(\IR_t\HH_t\RR_t\HH_t^\top + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} + \hatyt\hatyt^\top \label{eq:hatOt}\\ +\hatYXt&= \E[\YY_t\XX_t^\top] = \IR_t\ZZ_t\hatVt + \hatyt\hatxt^\top \label{eq:hatyxttm}\\ +\hatYXttm&= \E[\YY_t\XX_{t-1}^\top] = \IR_t\ZZ_t\hatVttm + \hatyt\hatxtm^\top \label{eq:hatyxt}\\ +\text{where }\IR_t &= \II-\HH_t\RR_t\HH_t^\top(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\HH_t\RR_t\HH_t^\top(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}\label{eq.IRt}\\ +\text{and }\IIm_t^{(2)}&=(\OMG_t^{(2)})^\top\OMG_t^{(2)} +\label{eq:IRt} +\end{align} +\end{subequations} +If $\yy_t$ is all missing, $\OMG_t^{(1)}$ is a $0 \times n$ matrix, and we define $(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\RR(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}$ to be a $n \times n$ matrix of zeros. If $\RR_t$ is diagonal, then $\RR_t(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\RR_t(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}=\IIm_t^{(1)}$ and $\IR_t=\IIm_t^{(2)}$. This will mean that in $\hatyt$ the $\yy_t(2)$ are given by $\ZZ_t\hatxt+\aa_t$, as expected when $\yy_t(1)$ and $\yy_t(2)$ are independent. + +If there are zeros on the diagonal of $\RR_t$ (section \ref{sec:degenerate}), the definition of $\IR_t$ is changed slightly from that shown in equation \ref{eq:Yt.exp}. Let $\mho_t^{(r)}$ be the matrix that extracts the elements of $\yy_t$ where $\yy_t(i)$ is not missing AND $\HH_t\RR_t(i,i)\HH_t^\top$ is not zero. Then +\begin{equation} +\IR_t = \II-\HH_t\RR_t\HH_t^\top(\mho_t^{(r)})^\top +(\mho_t^{(r)}\HH_t\RR_t\HH_t^\top(\mho_t^{(r)})^\top)^{-1}\mho_t^{(r)} +\label{eq:IRt.degen} +\end{equation} + +\subsection{Derivation of the expected value of $\YY_t$} +In the MARSS equation, the observation errors are denoted $\HH_t\vv_t$. $\vv_t$ is a specific realization from a random variable $\VV_t$ that is distributed multivariate normal with mean 0 and variance $\RR_t$. $\VV_t$ is not to be confused with $\widetilde{\VV}_t$ in equation \ref{eq:kfsoutput}, which is unrelated\footnote{I apologize for the confusing notation, but $\widetilde{\VV}_t$ and $\vv_t$ are somewhat standard in the MARSS literature and it is standard to use a capital letter to refer to a random variable. Thus $\VV_t$ would be the standard way to refer to the random variable associated with $\vv_t$.} to $\VV_t$. If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t|\YY(1)=\yy(1)] = \E[\YY_t|\YY_t=\yy_t] = \yy_t\\ +\end{split} +\end{equation} +If there are no observed values, then +\begin{equation} +\begin{split} +\E[\YY_t|\YY(1)=\yy(1)]=\E[\YY_t] = \E[\ZZ_t\XX_t+\aa_t+\VV_t] = \ZZ_t\hatxt+\aa_t +\end{split} +\end{equation} +If only some of the $\YY_t$ are observed, then we use the conditional probability for a multivariate normal distribution (here shown for a bivariate case): +\begin{equation}\label{eq:cond.multi.normal} +\text{If, }\begin{bmatrix} +Y_1\\ +Y_2\end{bmatrix} +\sim +\MVN\biggl( \begin{bmatrix} +\mu_1\\ +\mu_2 +\end{bmatrix}, \begin{bmatrix} +\Sigma_{11}&\Sigma_{12}\\ +\Sigma_{21}&\Sigma_{22}\end{bmatrix}\biggr) +\end{equation} +Then, +\begin{equation} +\begin{split} +(Y_1|Y_1=y_1) &=y_1,\quad\text{and}\\ +(Y_2|Y_1=y_1) &\sim \MVN(\bar{\mu},\bar{\Sigma}),\quad\text{where}\\ +\bar{\mu}&= \mu_2+\Sigma_{21}\Sigma_{11}^{-1}(y_1-\mu_1)\\ +\bar{\Sigma} &= \Sigma_{22}-\Sigma_{21}\Sigma_{11}^{-1}\Sigma_{12} +\end{split} +\end{equation} + +From this property, we can write down the distribution of $\YY_t$ conditioned on $\YY_t(1)=\yy_t(1)$ and $\XX_t=\xx_t$: +\begin{equation} +\begin{split} +\begin{bmatrix} +\YY_t(1)|\XX_t=\xx_t\\ +\YY_t(2)|\XX_t=\xx_t +\end{bmatrix} +&\sim \\ +&\MVN\biggl( \begin{bmatrix} +\OMG_t^{(1)}(\ZZ_t\xx_t+\aa_t)\\ +\OMG_t^{(2)}(\ZZ_t\xx_t+\aa_t) +\end{bmatrix}, \begin{bmatrix} +(\HH_t\RR_t\HH_t^\top)_{11}&(\HH_t\RR_t\HH_t^\top)_{12}\\ +(\HH_t\RR_t\HH_t^\top)_{21}&(\HH_t\RR_t\HH_t^\top)_{22} +\end{bmatrix}\biggr) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:varY} +\begin{split} +(\YY_t(1)&|\YY_t(1)=\yy_t(1),\XX_t=\xx_t) = \OMG_t^{(1)}\yy_t\quad\text{and}\\ +(\YY_t(2)&|\YY_t(1)=\yy_t(1),\XX_t=\xx_t) \sim \MVN(\ddot{\mu},\ddot{\Sigma})\quad\text{where}\\ +\ddot{\mu}&= \OMG_t^{(2)}(\ZZ_t\xx_t+\aa_t)+\ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}(\yy_t-\ZZ_t\xx_t-\aa_t)\\ +\ddot{\Sigma}&= \ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12} \\ +\ddot{\RR}_t&= \HH_t\RR_t\HH_t^\top +\end{split} +\end{equation} + +Note that since we are conditioning on $\XX_t=\xx_t$, we can replace $\YY$ (all data from time 1 to $T$) by $\YY_t$ (data at time $t$) in the conditional: +$$\E[\YY_t|\YY(1)=\yy(1),\XX_t=\xx_t]=\E[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t].$$ +From this and the distributions in equation \ref{eq:varY}, we can write down $\hatyt=\E[\YY_t|\YY(1)=\yy(1),\Theta_j]$: +\begin{equation} +\begin{split} +\hatyt&=\E_{XY}[\YY_t|\YY(1)=\yy(1)]\\ +&=\int_{\xx_t}\int_{\yy_t}\yy_t f(\yy_t|\yy_t(1),\xx_t)d\yy_t f(\xx_t)d\xx_t \\ +&=\E_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]]\\ +&=\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]\\ +&=\yy_t-\IR_t(\yy_t-\ZZ_t\hatxt-\aa_t)\\ +\text{where }\IR_t &= \II-\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)} +\end{split} +\end{equation} +$(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}$ is a $n \times n$ matrix with 0s in the non-(11) positions. If the $k$-th element of $\yy_t$ is observed, then $k$-th row and column of $\IR_t$ will be zero. +Thus if there are no missing values at time $t$, $\IR_t=\II-\II=0$. If there are no observed values at time $t$, $\IR_t$ will reduce to $\II$. + +\subsection{Derivation of the expected value of $\YY_t\YY_t^\top$} +The following outlines a\footnote{The following derivations are painfully ugly. There are surely more elegant ways to do this; at least, there must be more elegant notations.} derivation. If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t &\YY_t^\top|\YY(1)=\yy(1)] = \E[\YY_t \YY_t^\top|\YY_t=\yy_t] = \yy_t\yy_t^\top. +\end{split} +\end{equation} +If there are no observed values at time $t$, then +\begin{equation} +\begin{split} +\E[\YY_t &\YY_t^\top]\\ +&=\var[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]+\E[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]\E[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]^\top\\ +&=\var[\VV_t]+\var[\ZZ_t\XX_t]+(\E[\ZZ_t\XX_t+\aa_t]+\E[\HH_t\VV_t])(\E[\ZZ_t\XX_t+\aa_t]+\E[\HH_t\VV_t])^\top\\ +&=\ddot{\RR}_t+\ZZ_t\hatVt\ZZ_t^\top + (\ZZ_t\hatxt+\aa_t)(\ZZ_t\hatxt+\aa_t)^\top +\end{split} +\end{equation} + +When only some of the $\YY_t$ are observed, we use again the conditional probability of a multivariate normal (equation \ref{eq:cond.multi.normal}). From this property, we know that +\begin{equation}\label{eq:var.Y.cond.x} +\begin{split} +&\var_{Y|x}[\YY_t(2)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12},\\ +&\var_{Y|x}[\YY_t(1)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=0\\ +\text{and }&\cov_{Y|x}[\YY_t(1),\YY_t(2)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=0\\ +\\ +\text{Thus }&\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]\\ +&=(\OMG_t^{(2)})^\top(\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12})\OMG_t^{(2)}\\ +&=(\OMG_t^{(2)})^\top(\OMG_t^{(2)}\ddot{\RR}_t(\OMG_t^{(2)})^\top - \OMG_t^{(2)}\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}\ddot{\RR}_t(\OMG_t^{(2)})^\top)\OMG_t^{(2)}\\ +&=\IIm_t^{(2)}(\ddot{\RR}_t-\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}\ddot{\RR}_t)\IIm_t^{(2)}\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} +\end{split} +\end{equation} +The $\IIm_t^{(2)}$ bracketing both sides is zero-ing out the rows and columns corresponding to the $\yy_t(1)$ values. + +Now we can compute the $\E_{XY}[\YY_t\YY_t^\top|\YY(1)=\yy(1)]$. The subscripts are added to the $\E$ to emphasize that we are breaking the multivariate expectation into an inner and outer expectation. +\begin{equation} +\begin{split} +\hatOt&=\E_{XY}[\YY_t\YY_t^\top|\YY(1)=\yy(1)]=\E_X[\E_{Y|x}[\YY_t\YY_t^\top|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]]\\ +&=\E_X\bigl[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t] \\ +&\quad + \E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t] +\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]^\top\bigr]\\ +&=\E_X[\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)}] +\E_X[(\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t))(\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t))^\top]\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} + \var_X\bigl[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)\bigr]\\ &\quad +\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]^\top\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} + \IIm_t^{(2)}\IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top\IIm_t^{(2)} + \hatyt\hatyt^\top \\ +\end{split} +\end{equation} +Thus, +\begin{equation} +\hatOt=\IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} + \hatyt\hatyt^\top \\ +\end{equation} +and +\begin{equation}\label{eq:cond.var.Y} +\var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] = \IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} +\end{equation} + +The variance can be decomposed into two parts via the law of total variance: +\begin{equation}\label{eq:law.total.var.Y} +\var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] = \E_X[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] + +\var_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] +\end{equation} +Using equations \ref{eq:law.total.var.Y}, \ref{eq:var.Y.cond.x}, and \ref{eq:cond.var.Y}, we can solve for the variance (over $\xx_t$) of the expected value of $\YY_t|\YY_t(1)=\yy_t(1)$ conditioned on $\XX_t=\xx_t$: +\begin{equation} +\begin{split} +\var_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] & \\ +&= \var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] - \E_X[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] \\ +&= \IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} - \IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} \\ +&= \IIm_t^{(2)}\IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top\IIm_t^{(2)} +\end{split} +\end{equation} +Though this variance is not used in the EM algoritm, it gives us the confidence intervals for the expected value of missing data while the variance of $\YY_t|\YY_t(1)=\yy_t(1)$ gives us the prediction intervals for missing data. + +\subsection{Derivation of the expected value of $\YY_t\XX_t^\top$} +If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t \XX_t^\top|\YY(1)=\yy(1)] = \yy_t\E[\XX_t^\top]=\yy_t\hatxt^\top +\end{split} +\end{equation} +If there are no observed values at time $t$, then +\begin{equation} +\begin{split} +\E[\YY_t &\XX_t^\top|\YY(1)=\yy(1)]\\ +&=\E[(\ZZ_t\XX_t+\aa_t+\VV_t)\XX_t^\top]\\ +&=\E[\ZZ_t\XX_t\XX_t^\top+\aa_t\XX_t^\top+\VV_t\XX_t^\top]\\ +&=\ZZ_t\hatPt+\aa_t\hatxt^\top+\cov[\VV_t,\XX_t]+\E[\VV_t]\E[\XX_t]^\top\\ +&=\ZZ_t\hatPt+\aa_t\hatxt^\top +\end{split} +\end{equation} +Note that $\VV_t$ and $\XX_t$ are independent (equation \ref{eq:MARSS}). $\E[\VV_t]=0$ and $\cov[\VV_t,\XX_t]=0$. + +Now we can compute the $\E_{XY}[\YY_t\XX_t^\top|\YY_(1)=\yy(1)]$. +\begin{equation} +\begin{split} +\hatYXt&=\E_{XY}[\YY_t\XX_t^\top|\YY(1)=\yy(1)]\\ +&=\cov[\YY_t,\XX_t|\YY_t(1)=\yy_t(1)]+\E_{XY}[\YY_t|\YY(1)=\yy(1)]\E_{XY}[\XX_t^\top|\YY(1)=\yy(1)]^\top\\ +&=\cov[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)+\VV^*_t,\XX_t]+\hatyt\hatxt^\top \\ +&=\cov[\yy_t,\XX_t]-\cov[\IR_t\yy_t,\XX_t]+\cov[\IR_t\ZZ_t\XX_t,\XX_t] +\cov[\IR_t\aa_t,\XX_t]\\ +&\quad + \cov[\VV^*_t,\XX_t]+\hatyt\hatxt^\top \\ +&=0 - 0 + \IR_t\ZZ_t\hatVt + 0 + 0 + \hatyt\hatxt^\top \\ +&= \IR_t\ZZ_t\hatVt + \hatyt\hatxt^\top +\end{split} +\end{equation} +This uses the computational formula for covariance: $\E[\YY\XX^\top]=\cov[\YY,\XX]+\E[\YY]\E[\XX]^\top$. $\VV^*_t$ is a random variable with mean 0 and variance $\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12}$ from equation \ref{eq:varY}. $\VV^*_t$ and $\XX_t$ are independent of each other, thus $\cov[\VV^*_t,\XX_t^\top]=0$. + +\subsection{Derivation of the expected value of $\YY_t\XX_{t-1}^\top$} +The derivation of $\E[\YY_t\XX_{t-1}^\top]$ is similar to the derivation of $\E[\YY_t\XX_{t-1}^\top]$: +\begin{equation} +\begin{split} +\hatYXt&=\E_{XY}[\YY_t\XX_{t-1}^\top|\YY(1)=\yy(1)]\\ +&=\cov[\YY_t,\XX_{t-1}|\YY_t(1)=\yy_t(1)] + \E_{XY}[\YY_t|\YY(1)=\yy(1)]\E_{XY}[\XX_{t-1}^\top|\YY(1)=\yy(1)]^\top\\ +&=\cov[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)+\VV^*_t,\XX_{t-1}]+\hatyt\hatxtm^\top \\ +&=\cov[\yy_t,\XX_{t-1}]-\cov[\IR_t\yy_t,\XX_{t-1}]+\cov[\IR_t\ZZ_t\XX_t,\XX_{t-1}] \\ +&\quad +\cov[\IR_t\aa_t,\XX_{t-1}] + \cov[\VV^*_t,\XX_{t-1}]+\hatyt\hatxtm^\top \\ +&=0 - 0 + \IR_t\ZZ_t\hatVttm + 0 + 0 + \hatyt\hatxtm^\top \\ +&= \IR_t\ZZ_t\hatVttm + \hatyt\hatxtm^\top +\end{split} +\end{equation} + +\section{Degenerate variance models}\label{sec:degenerate} +It is possible that the model has deterministic and stochastic elements; mathematically this means that either $\GG_t$, $\HH_t$ or $\FF$ have all zero rows, and this means that some of the observation or state processes are deterministic\footnote{Deterministic means that given the parameters, the states or observation processes have known values and are not random variables.} Such models often arise when a MAR-p is put into MARSS-1 form. Assuming the model is solvable (one solution and not over-determined), we can modify the Kalman smoother and EM algorithm to handle models with deterministic elements. + +The motivation behind the degenerate variance modification is that we want to use one set of EM update equations for all models in the MARSS class---regardless of whether they are partially or fully degenerate\footnote{Degenerate means zeros on the diagonal of the variance-covariance matrix, which appears as a zero row in $\GG_t$, $\HH_t$ or $\FF$.}. The difficulties arise in getting the $\uu$ and $\xixi$ update equations. If we were to fix these or make $\xixi$ stochastic (a fixed mean and fixed variance), most of the trouble in this section could be avoided. However, fixing $\xixi$ or making it stochastic is putting a prior on it and placing a prior on the variance-covariance structure of $\xixi$ that conflicts logically with the model is often both unavoidable (since the correct variance-covariance structure depends on the parameters you are trying to estimate) and disastrous to one's estimation although the problem is often difficult to detect especially with long time series. Many papers have commented on this subtle problem. So, we want to be able to estimate $\xixi$ so we do not have to specify $\LAM$ (because we remove it from the model altogether). Note that in a univariate $\xx$ model (one state), $\LAM$ is just a variance so we do not run into this trouble. The problems arise when $\xx$ is multivariate (>1 state) and then we have to deal with the variance-covariance structure of the initial states. + +\subsection{Rewriting the state and observation models for degenerate variance systems} +Let's start with an example where $y_{2,t}$ (2nd $y$) has no added observation error. +\begin{equation} +\RR_t=\begin{bmatrix} +1&0.2\\ +0.2&1 +\end{bmatrix}\\ +\text{ and } +\HH_t=\begin{bmatrix} +1&0\\ +0&0\\ +0&1 +\end{bmatrix} +\end{equation} +Let $\OMG_{t,r}^+$ be a $p \times n$ matrix that extracts the $p$ non-zero rows from $\HH_t$. The diagonal matrix $(\OMG_{t,r}^+)^\top\OMG_{t,r}^+ \equiv \II_{t,r}^+$ is a diagonal matrix that can zero out the $\HH_t$ zero rows in any $n$ row matrix. + +\begin{equation} +\begin{split} +\OMG_{t,r}^+ &= +\begin{bmatrix} +1&0&0\\ +0&0&1 +\end{bmatrix}\quad\quad +\II_{t,r}^+ = (\OMG_{t,r}^+)^\top\OMG_{t,r}^+ = +\begin{bmatrix} +1&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\\ +\yy_t^+&=\OMG_{t,r}^+ \yy_t = +\begin{bmatrix} +y_1\\ +y_3 +\end{bmatrix}_t\quad\quad +\yy_t^+=\II_{t,r}^+ \yy_t = \begin{bmatrix} +y_1\\ +0\\ +y_3 +\end{bmatrix}_t +\end{split} +\end{equation} + +Let $\OMG_{t,r}^{(0)}$ be a $(n-p) \times n$ matrix that extracts the $n-p$ zero rows from $\HH_t$. For the example above, +\begin{equation} +\begin{split} +\OMG_{t,r}^{(0)} &= +\begin{bmatrix} +0&1&0\\ +\end{bmatrix}\quad\quad +\II_{t,r}^{(0)} = (\OMG_{t,r}^{(0)})^\top\OMG_{t,r}^{(0)} = +\begin{bmatrix} +0&0&0\\ +0&1&0\\ +0&0&0 +\end{bmatrix} +\\ +\yy_t^{(0)}&=\OMG_{t,r}^{(0)} \yy_t = \begin{bmatrix} +y_3 +\end{bmatrix}_t\quad\quad +\yy_t^{(0)}=\II_{t,r}^{(0)} \yy_t = \begin{bmatrix} +0\\ +y_2\\ +0 +\end{bmatrix}_t +\end{split} +\end{equation} +Similarly, $\OMG_{t,q}^+$ extracts the states associated with the non-zero rows in $\GG_t$ and $\OMG_{t,q}^{(0)}$ extracts the zero rows. $\II_{t,q}^+$ and $\II_{t,q}^{(0)}$ are defined similarly. + +Using these definitions, we can rewrite the state process part of the MARSS model by separating out the deterministic parts. $\xx_t^{(0)}$ is the rows of $\xx_t$ that are associated with all-zero rows of $\GG_t$, that means there is no $w_t$ in the $x_t$ equation for those rows\footnote{$x_{t,i}=\BB_{t,i}\xx_{t-1} + \uu_{t,i}$ where the $i$ subscript means $i$-th row.} +\begin{equation}\label{eq:degen.model.x1} +\begin{split} +\xx_t^{(0)}&=\OMG_{t,q}^{(0)}\xx_t=\OMG_{t,q}^{(0)}(\BB_t\xx_{t-1} + \uu_t)\\ +\xx_t^+&=\OMG_{t,q}^+\xx_t=\OMG_{t,q}^+(\BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t)\\ +\ww_t^+ &\sim \MVN(0,\QQ_t) +\end{split} +\end{equation} +Similarly, we can rewrite the observation process part of the MARSS model by separating out the parts with no observation error: +\begin{equation}\label{eq:degen.model.y1} +\begin{split} +\yy_t^{(0)}&=\OMG_{t,r}^{(0)}\yy_t=\OMG_{t,r}^{(0)}(\ZZ_t\xx_t + \aa_t) \\ +&=\OMG_{t,r}^{(0)}(\ZZ_t\II_{t,q}^+\xx_t + \ZZ_t\II_{t,q}^{(0)}\xx_t + \aa_t)\\ +\yy_t^+&=\OMG_{t,r}^+\yy_t=\OMG_{t,r}^+(\ZZ_t\xx_t + \aa_t + \HH_t\vv_t)\\ +&=\OMG_{t,r}^+(\ZZ_t\II_{t,q}^+\xx_t + \ZZ_t\II_{t,q}^{(0)}\xx_t + \aa_t+\HH_t\vv_t)\\ +\vv_t^+ &\sim \MVN(0,\RR_t) +\end{split} +\end{equation} + +In order for this to be solvable using an EM algorithm with the Kalman filter, we require that no estimated $\BB$ or $\uu$ elements appear in the equation for $\yy_t^{(0)}$ (via $x_t$ in that equation). Since the $\yy_t^{(0)}$ do not appear in the likelihood function (since $\HH_t^{(0)}=0$), $\yy_t^{(0)}$ would not affect the estimate for the parameters appearing in the $\yy_t^{(0)}$ equation. This translates to the following constraints, $(1_{1 \times m} \otimes \OMG_{t,r}^{(0)}\ZZ_t\II_{t,q}^{(0)})\DD_{t,b}$ is all zeros and $\OMG_{t,r}^{(0)}\ZZ_t\II_{t,q}^{(0)}\DD_u$ is all zeros. +Also notice that $\OMG_{t,r}^{(0)}\ZZ_t$ and $\OMG_{t,r}^{(0)}\aa_t$ appear in the $\yy^{(0)}$ equation and not in the $\yy^+$ equation. This means that $\OMG_{t,r}^{(0)}\ZZ_t$ and $\OMG_{t,r}^{(0)}\aa_t$ must be only fixed terms. + +In summary, the degenerate model can be reduced to the following (with $\xx_0$ not specified yet). +\begin{equation}\label{eq:degen.model2} +\begin{split} +\xx_t^{(0)}&=\BB_t^{(0)}\xx_{t-1} + \uu_t^{(0)}\\ +\xx_t^+&=\BB_t^+\xx_{t-1} + \uu_t^+ + \GG_t^+\ww_t\\ +\ww_t &\sim \MVN(0,\QQ_t) +\\ +\yy_t^{(0)}&=\ZZ^{(0)}\II_q^+\xx_t + \ZZ^{(0)}\II_q^{(0)}\xx_t + \aa^{(0)}_t\\ +\yy_t^+&=\ZZ_t^+\xx_t + \aa_t^+ \HH_t^+\vv_t\\ +&=\ZZ_t^+\II_q^+\xx_t + \ZZ_t^+\II_q^{(0)}\xx_t + \aa_t^+ + \HH_t^+\vv_t\\ +\vv_t &\sim \MVN(0,\RR) +\end{split} +\end{equation} +where $\BB_t^{(0)}=\OMG_{t,q}^{(0)}\BB_t$ and $\BB_t^+=\OMG_{t,q}^+\BB_t$ so that $\BB_t^{(0)}$ are the rows of $\BB_t$ corresponding to the zero rows of $\GG_t$ and $\BB_t^+$ are the rows of $\BB_t$ corresponding to non-zero rows of $\GG_t$. The other parameters are similarly defined: $\uu_t^{(0)}=\OMG_{t,q}^{(0)}\uu_t$ and $\uu_t^+=\OMG_{t,q}^+\uu_t$, $\ZZ_t^{(0)}=\OMG_{t,r}^{(0)}\ZZ_t$ and $\ZZ_t^+=\OMG_{t,r}^+\ZZ_t$, and $\aa_t^{(0)}=\OMG_{t,r}^{(0)}\aa_t$ and $\aa_t^+=\OMG_{t,r}^+\aa_t$. + +\subsection{Identifying the fully deterministic $\xx$ rows}\label{sec:ident.xds} +To derive EM update equations, we need to take the derivative of the expected log-likelihood holding everything but the parameter of interest constant. If there are deterministic $\xx_t$ rows, then we cannot hold these constant and do this partial differentiation with respect to the state parameters. We need to identify these $\xx_t$ rows and remove them from the likelihood function by rewriting them in terms of only the state parameters\footnote{Then we can do the partial differentiation with respect to the parameters.}. For this derivation, I am going to make the simplifying assumption that the locations of the all-zero rows in $\GG_t$ and $\HH_t$ are time-invariant. This is not strictly necessary, but simplifies the algebra greatly. + +For the deterministic $\xx_t$ rows, denoted $\xx_t^d$, the process equation is $\xx_t = \BB_t\xx_{t-1}+\uu_t$, with no $\ww_t$ term. When we do the partial differentiation step in deriving the EM update equation for $\uu$, $\BB$ or $\xixi$, we will need to take a partial derivative while holding $\xx_t$ and $\xx_{t-1}$ constant. We cannot hold the deterministic rows of $\xx_t$ and $\xx_{t-1}$ constant while changing the corresponding rows of $\uu_t$ and $\BB_t$ (or $\xixi$ if $t=0$ or $t=1$). If a row of $\xx_t$ is fully deterministic, then that $x_{i,t}$ must change when row $i$ of $\uu_t$ or $\BB_t$ is changed. Thus we cannot do the partial differentiation step required in the EM update equation derivation. + +So we need to identify the fully deterministic $\xx_t$ and treat them differently in our likelihood so we can derive the update equation. First I will define some terminology regarding the $\xx_t$. +\begin{itemize} + \item $(0)$ rows of any $\xx$, $\BB$, $\uu$ or $\II$ matrix that are associated with all-zero rows of $\GG_t$, e.g. $\xx_t^{(0)}$. + \item $(+)$ rows of any $\xx$, $\BB$, $\uu$ or $\II$ matrix that are associated with non-zero rows of $\GG_t$, e.g. $\xx_t^{(+)}$. + \item 'directly stochastic' $\xx_t$ are denoted $\xx_t^{ds}$. These are the same as $\xx_t^{+}$. These $\xx_t$ have a $w_t$ from their row of $\GG_t$. + \item 'deterministic' $\xx_t$ are denoted $\xx_t^d$. These are those $\xx_t^{(0)}$ which have no $w_t$ terms either from their own row or picked up through $\BB$ from a non-zero row of $\GG_t$. + \item 'indirectly stochastic' $\xx_t$ are denoted $\xx_t^{is}$. Indirectly stochastic $\xx_t^{is}$ have a corresponding row of $\GG_t$ that is all zero, but pick up a $w_t$ from a non-zero row of $\GG_t$ through $\BB$ in one of the prior $\BB_t\xx_t$ steps. +\end{itemize} +The stochastic $\xx_t$ are denoted $\xx_t^s$ whether they are indirectly or directly stochastic. + +How do you determine the $d$, or deterministic, set of $\xx_t$ rows? These are the rows of $\xx_t$ with no $w$ terms, from time $t$ or from prior $t$. Note that the location of the $d$ rows is time-dependent, a row may be deterministic at time $t$ but pick up a $w$ at time $t+1$ and thus be indirectly stochastic thereafter. I am requiring that once a row becomes indirectly stochastic, it remains stochastic; rows are not allowed to flip back and forth between deterministic (no $w$ terms in them) and stochastic (containing a $w$ term). + +I will work through an example and then show a general algorithm to keep track of the deterministic rows at time $t$. + +\subsubsection*{Example} + +Let $\xx_0=\xixi$ (so $\FF$ is all zero and $\xx_0$ is not stochastic). Define $\II_t^{ds}$, $\II_t^{is}$, and $\II_t^d$ as diagonal indicator matrices with a 1 at $\II(i,i)$ if row $i$ is directly stochastic, indirectly stochastic, or deterministic respectively. $\II_t^{ds}+\II_t^{is}+\II_t^d=\II_m$. Let our state equation be $\xx_t=\BB\xx_{t-1}+\GG w_t$. +Let +\begin{equation} +\BB=\begin{bmatrix} +1&1&0&0\\ +1&0&0&0\\ +0&1&0&0\\ +0&0&0&1 +\end{bmatrix}\quad\quad +\GG=\begin{bmatrix} +1\\ +0\\ +0\\ +0 +\end{bmatrix} +\end{equation} +At $t=0$, $\xx_0$ is fixed, aka deterministic. +\begin{equation} +\xx_0=\begin{bmatrix} +\pi_1\\ +\pi_2\\ +\pi_3\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_0^d=\begin{bmatrix} +1&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_0^s=\II_0^{is}=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +At $t=1$, the $\xx_t$ begin picking up $w_t$ starting with $x_{1,t}$. +\begin{equation} +\xx_1=\begin{bmatrix} +\pi_1+\pi_2+w_1\\ +\pi_1\\ +\pi_2\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_1^d=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_1^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_1^{is}=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +At $t=2$, $x_{2,2}$ picks up $w_1$ through $\BB$. +\begin{equation} +\xx_2=\begin{bmatrix} +\dots+w_2\\ +\pi_1+\pi_2+w_1\\ +\pi_1\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_2^d=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_2^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_0^{is}=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +By $t=3$, the $\II^{d}$ and $\II^{is}$ stabilize. +\begin{equation} +\xx_3=\begin{bmatrix} +\dots+w_1+w_2+w_3\\ +\dots+w_1+w_2\\ +\pi_1+\pi_2+w_1\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_3^d=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_3^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_3^{is}=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +After time $t=3$ the location of the deterministic and indirectly stochastic rows is stabilized and no longer changes. + +\subsubsection*{Finding the indirectly stochastic rows} + +In general, it can take up to $m$ time steps for the location of the deterministic rows to stabilize. This is because $\BB_t$ is like an adjacency matrix, and I require that the location of the 0 elements in $\BB_1\BB_2\dots\BB_t$ is time invariant. If we replace all non-zero elements in $\BB_t$ with 1, then we have an adjacency matrix, let's call it $\MM$. If there is a path in $\MM$ from $x_{j,t}$, where $j$ is a $(0)$ row of $\xx$, to an $x_{i,t}$, where $i$ is a $(+)$ row, then row $j$ of $\xx$ will eventually be indirectly stochastic. Graph theory tells us that it takes at most $m$ steps for a $m \times m$ adjacency matrix to show full connectivity. This means that if element $(j,i)$ is 0 in $M^m$ then row $j$ is not connected to row $i$ by any path and thus will remain unconnected for $M^{t>m}$; note element $i,j$ can be 0 while $j,i$ is not. + +This means that to determine if $x_{j,t}$, in the $(0)$ rows, is indirectly stochastic, we raise $\MM$, to the $t$ power and look if there is a non-zero value in the $j$-th row and any $(+)$ columns of $\MM^t$. In words, we looking for a path from $x_{j,t}$ to any $x_{+}$ in the past. We do not need to do this past $t=m$ since the location of the indirectly stochastic and deterministic rows stabilize by then. + +Since my $\BB_t$ matrices are small, I use an inefficient strategy in the MARSS code to construct the indicator matrices $\II_d^t$. I define $\MM$ as $\BB_t$ with the non-zero $\BB$ replaced with 1; I require that the location of the non-zero elements in $\BB_t$ are time-invariant so there is only one $\MM$. Within the product $\MM^t$, those rows where only 0s appear in the 'stochastic' columns (non-zero $\GG_t$ rows) are the fully deterministic $\xx_{t+1}$ rows. Note, $t+1$ so one time step ahead. There are much faster algorithms for finding paths, but my $\MM$ tend to be small. Also, unfortunately, using $\BB^t$ in place of $\MM^t$ is not robust. Let's say $\BB=\bigl[ \begin{smallmatrix}-1&-2\\ 1&1\end{smallmatrix} \bigr]$, $\GG=\bigl[ \begin{smallmatrix}1\\ 0\end{smallmatrix} \bigr]$ and $\xx_0$ is fixed (not stochastic). +$\BB^2$ is a diagonal matrix suggesting that no connection between $x_2$ and $x_1$ at time $t=2$. That is incorrect. $x_{2,t}$ is indirectly stochastic. + +\subsubsection{Redefining the $\xx_t^d$ elements in the likelihood} +Because the deterministic rows of $\xx_t$ do not appear in the $\xx$ part of the likelihood (no error term = no likelihood), we have to move them into the $\yy$ part of the likelihood. To do that we need to re-write them in terms of only model parameters and remove all $\xx_{t-1}$ terms. This section walks through how to do that. + +By definition, all the $\BB_t$ elements in the $ds$ and $is$ columns of the $d$ rows of $\BB_t$ are 0. If they weren't, then $\xx_t^d$ wouldn't be a deterministic row because it would pick up a $w$ from a directly or indirectly stochastic $x$ from a prior $t-1$. This is due to the constraint that I have imposed that locations of 0s in $\BB_t$ are time-invariant and the location of the zero rows in $\GG_t$ also time-invariant: $\II_q^{+}$ and $\II_q^{(0)}$ are time-constant. + +\subsubsection*{Example} + +Consider this $\BB$ and $\GG$, which would arise in a MARSS version of an AR-3 model: +\begin{equation} +\BB=\begin{bmatrix} +b_1&b_2&b_3\\ +1&0&0\\ +0&1&0\end{bmatrix} +\quad +\GG=\begin{bmatrix} +1\\ +0\\ +0\end{bmatrix} +\end{equation} +Using $\xx_0=\xixi$ (so fixed and not stochastic): +\begin{equation} +\xx_0=\begin{bmatrix} +\pi_1\\ +\pi_2\\ +\pi_3 +\end{bmatrix} +\quad +\xx_1=\begin{bmatrix} +\dots+w_1\\ +\pi_1\\ +\pi_2 +\end{bmatrix} +\quad +\xx_2=\begin{bmatrix} +\dots+w_2\\ +\dots+w_1\\ +\pi_1\end{bmatrix} +\quad +\xx_3=\begin{bmatrix} +\dots+w_3\\ +\dots+w_2\\ +\dots+w_1 +\end{bmatrix} +\end{equation} +The $\dots$ just represent 'some values'. The key part is the $w$ appearing which is the stochasticity. At $t=1$, rows 2 and 3 are deterministic. At $t=2$, row 3 is deterministic, and at $t=3$, no rows are deterministic. + +The $\II^d$ are: +\begin{equation} +\II_{q,1}^d=\begin{bmatrix} +0&0&0\\ +0&1&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,2}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,3}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&0 +\end{bmatrix} +\end{equation} +The $\MM$ are: +\begin{equation} +\MM=\begin{bmatrix} +1&1&1\\ +1&0&0\\ +0&1&0 +\end{bmatrix} +\quad +\MM^2=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,3}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&0 +\end{bmatrix} +\end{equation} + +We can rewrite the equation for the deterministic rows in $\xx_t$ as follows. $\xx_t^d$ is $\xx_t$ with the $d$ rows zeroed out, so $\xx_t^d = \II_{q,t}^d\xx_t$. +\begin{equation} \label{eq:xt.det.sum} +\begin{split} +\xx_1^{d}&=\II_{q,1}^d\xx_1\\ + &=\II_{q,1}^d(\BB_1 \xx_0 + \ff_{u,1} + \DD_{u,1}\uupsilon) \\ +\xx_2^{d}&=\II_{q,2}^d\xx_2\\ + &=\II_{q,2}^d(\BB_2 \xx_1 + \uu_2) \\ + &=\II_{q,2}\BB_2((\BB_1 \xx_0 + \ff_{u,1} + \DD_{u,1}\uupsilon) + \ff_{u,2} + \DD_{u,2}\uupsilon) \\ + &=\II_2^d(\BB_2\BB_1 \xx_0 + \BB_2\ff_{1,u} + \ff_{2,u} + (\BB_2\DD_{u,1} +\DD_{u,2})\uupsilon) \\ + \dots \\ +\end{split} +\end{equation} +The messy part is keeping track of which rows are deterministic because this will potentially change up to time $t=m$. + +We can rewrite the function for $\xx_t^d$, where $t_0$ is the $t$ at which the initial state is defined. It is either $t=0$ or $t=1$. +\begin{equation} \label{eq:xt.det.sum2} +\begin{split} +\xx_t^d &= \II_t^d(\BB^*_t\xx_{t_0} + \ff^*_t +\DD^*_t\uupsilon) \\ +\text{where}&\\ +\BB^*_{t_0} &= \II_m \\ +\BB^*_{t} &=\BB_t\BB^*_{t-1}\quad t > t_0 \\ +\\ +\ff^*_{t_0} &= 0 \\ +\ff^*_t &=\BB_t\ff^*_{t-1} + \ff_{t,u}\quad t > t_0\\ +\\ +\DD^*_{t_0} &= 0 \\ +\DD^*_t &= \BB_t\DD^*_{t-1} + \DD_{t,u}\quad t > t_0\\ +\\ +\II_{q,t_0}^d&=\II_\lambda^d\\ +\text{diag}(\II_{t_0+\tau}^d)&=\text{apply}(\OMG_q^{(0)}\MM^\tau\OMG_q^+ == 0, 1, \text{all}) +\end{split} +\end{equation} +The bottom line is written in R: $\II_{t_0+\tau}^d$ is a diagonal matrix with a 1 at $(i,i)$ where row $i$ of $\GG$ is all 0 and all $ds$ and $is$ columns in row $i$ of $\MM^t$ are equal to zero. + +In the expected log-likelihood, the term $\E[\XX_t^d]=\E[\XX_t^d|\YY=\yy]$, meaning the expected value of $\XX_t^d$ conditioned on the data, appears. Thus in the expected log-likelihood the function will be written: +\begin{equation} +\begin{split} +\XX_t^d &= \II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) \\ +\E[\XX_t^d] &= \II_t^d(\BB^*_t\E[\XX_{t_0}] + \ff^*_t +\DD^*_t\uupsilon) +\end{split} +\end{equation} + +When the $j$-th row of $\FF$ is all zero, meaning the $j$-th row of $\xx_0$ is fixed to be $\xi_j$, then $\E[X_{t_0,j}]\equiv\xi_j$. This is the case where we treat $x_{t_0,j}$ as fixed and we either estimate or specify its value. If $\xx_{t_0}$ is wholly treated as fixed, then $\E[\XX_{t_0}]\equiv\xixi$ and $\LAM$ does not appear in the model at all. In the general case, where some $x_{t_0,j}$ are treated as fixed and some as stochastic, we can write $\E[\XX_t^d]$ appearing in the expected log-likelihood as: +\begin{equation}\label{eq:EXtd} +\begin{split} +\E[\XX_{t_0}]=(\II_m-\II_\lambda^{(0)})\E[\XX_{t_0}]+\II_\lambda^{(0)}\xixi +\end{split} +\end{equation} +$\II_\lambda^{(0)}$ is a diagonal indicator matrix with 1 at $(j,j)$ if row $j$ of $\FF$ is all zero. + +If $\BB^{d,d}$ and $\uu^d$ are time-constant, we could use the matrix geometric series: +\begin{equation}\label{eq:xt.geo} +\begin{split} +\xx_t^{d}=&(\BB^{d,d})^t \xx_0^{d} + \sum_{i=0}^{t-1}(\BB^{d,d})^i \uu^{d} = +(\BB^{d,d})^t \xx_0^{d} + (\II - \BB^{d,d})^{-1}(\II-(\BB^{d,d})^t)\uu^{d}, \quad\text{if }\BB^{d,d} \neq \II\\ +&\xx_0^d + \uu^d,\quad\text{if }\BB^{d,d} = \II +\end{split} +\end{equation} +where $\BB^{d,d}$ is the block of $d$'s associated with the deterministic $\xx_t$. + +\subsubsection{Dealing with the $\xx_t^{is}$ elements in the likelihood and associated parameter rows} +Although $\ww_t^{is}=0$, these terms are connected to the stochastic $\xx$'s in earlier time steps though $\BB$, thus all $\xx_t^{is}$ are possible for a given $\uu_t$, $\BB_t$ or $\xixi$. However, all $\xx_t^{is}$ are not possible conditioned on $\xx_{t-1}$, so we are back in the position that we cannot both change $\xx_t$ and change $\uu_t$. + +Recall that for the partial differentiation step in the EM algorithm, we need to be able to hold the $E[\XX_t]$ appearing in the likelihood constant. We can deal with the deterministic $\xx_t$ because they are not stochastic and do not have 'expected values'. They can be removed from the likelihood by rewriting $\xx_t^d$ in terms of the model parameters. We cannot do that for $\xx_t^{is}$ because these $x$ are stochastic. There is no equation for them; all $\xx^{is}$ are possible but some are more likely than others. We also cannot replace $\xx_t^{is}$ with $\BB_t^{is}E[\XX_{t-1}]+\uu_t^{is}$ to force $\BB_t^{is}$ and $\uu^{is}$ to appear in the $\yy$ part of the likelihood. The reason is that $\E[\XX_t]$ and $\E[\XX_{t-1}]$ both appear in the likelihood and we cannot hold both constant (as we must for the partial differentiation) and at the same time change $\BB_t^{is}$ or $\uu_t^{is}$ as we are doing when we differentiate with respect to $\BB_t^{is}$ or $\uu)_t^{is}$. We cannot do that because $\xx_t^{is}$ is constrained to equal $\BB_t^{is}\xx_{t-1}+\uu_t^{is}$. + +This effectively means that we cannot estimate $\BB_t^{is}$ and $\uu_t^{is}$ because we cannot rewrite $\xx_t^{is}$ in terms of only the model parameters. This is specific to the EM algorithm because it is an iterative algorithm where the expected $\XX_t$ are computed with fixed parameters and then the $\E[\XX_t]$ are held fixed at their expected values while the parameters are updated. In my $\BB$ update equation, I assume that $\BB_t^{(0)}$ is fixed for all $t$. Thus I circumvent the problem altogether for $\BB$. For $\uu$, I assume that only the $\uu^{is}$ elements are fixed. + +\subsection{Expected log-likelihood for degenerate models} + +The basic idea is to replace $\II_q^d\E[\XX_t]$ with a deterministic function involving only the state parameters (and $\E[\XX_{t_0}]$ if $\XX_{t_0}$ is stochastic) . These appear in the $\yy$ part of the likelihood in $\ZZ_t\XX_t$ when the $d$ columns of $\ZZ_t$ have non-zero values. They appear in the $\xx$ part of the likelihood in $\BB_t\XX_{t-1}$ when the $d$ columns of $\BB_t$ have non-zero values. They do not appear in $\XX_t$ in the $\xx$ part of the likelihood because $\Qm_t$ has all the non-$s$ columns and rows zeroed out (non-$s$ includes both $d$ and $is$) and the element to the left of $\Qm_t$ is a row vector and to the right, it is a column vector. Thus any $\xx_t^d$ in $\XX_t$ are being zeroed out by $\Qm_t$. + +The first step is to pull out the $\II_t^{d}\XX_t$: +\begin{equation} +\begin{split} +\Psi^+ &= \E[\log\LL(\YY^+,\XX^+ ; \Theta)] = \E[-\frac{1}{2}\sum_1^T \\ +& (\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d\XX_t - \aa_t)^\top \Rm_t\\ +&(\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d\XX_t - \aa_t) -\frac{1}{2}\sum_1^T\log |\RR_t|\\ +& -\frac{1}{2}\sum_{t_0+1}^T (\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d\XX_{t-1}) - \uu_t)^\top \Qm_t \\ +&(\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d\XX_{t-1}) - \uu_t) - \frac{1}{2}\sum_{t_0+1}^T\log |\QQ_t| \\ +& - \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| -\frac{n}{2}\log 2\pi +\end{split} +\end{equation} +See section \ref{sec:ident.xds} for the definition of $\II_t^d$. + +Next we replace $\II_q^d\XX_t$ with equation \ref{eq:xt.det.sum2}. $\XX_{t_0}$ will appear in this function instead of $\xx_{t_0}$. I rewrite $\uu_t$ as $\ff_{u,t}+\DD_{u,t}\uupsilon$. This gives us the expected log-likelihood: +\begin{equation}\label{eq:degen.logL.x0} +\begin{split} +\Psi^+ &= \E[\log\LL(\YY^+,\XX^+ ; \Theta)] = \E[-\frac{1}{2}\sum_1^T \\ +& (\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) - \aa_t)^\top \Rm_t\\ +&(\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) - \aa_t) -\frac{1}{2}\sum_1^T\log |\RR_t|\\ +& -\frac{1}{2}\sum_{t_0+1}^T (\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d(\BB^*_{t-1}\XX_{t_0} + \ff^*_{t-1} +\DD^*_{t-1}\uupsilon)) - \ff_{u,t} - \DD_{u,t}\uupsilon)^\top \Qm_t \\ +&(\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d(\BB^*_{t-1}\XX_{t_0} + \ff^*_{t-1} +\DD^*_{t-1}+\uupsilon)) - \ff_{u,t} - \DD_{u,t}\uupsilon) \\ +&- \frac{1}{2}\sum_{t_0}^T\log |\QQ_t| - \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| -\frac{n}{2}\log 2\pi +\end{split} +\end{equation} +where $\BB^*$, $\ff^*$ and $\DD^*$ are defined in equation \ref{eq:xt.det.sum2}. $\Rm_t = \Xi_t^\top\RR_t^{-1}\Xi_t$ and $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t$, $\LAMm = \Pi^\top\LAM^{-1}\Pi$. When $\xx_{t_0}$ is treated as fixed, $\LAMm=0$ and the last line will drop out altogether, however in general some rows of $\xx_{t_0}$ could be fixed and others stochastic. + +We can see directly in equation \ref{eq:degen.logL.x0} where $\uupsilon$ appears in the expected log-likelihood. Where $\pp$ appears is less obvious because it depends on $\FF$, which specifies which rows of $\xx_{t_0}$ are fixed. From equation \ref{eq:EXtd}, $$\E[\XX_{t_0}]=(\II_m-\II_l^{(0)})\E[\XX_{t_0}]+\II_l^{(0)}\xixi$$ +and $\xixi=\ff_\xi+\DD_\xi\pp$. Thus where $\pp$ appears in the expected log-likelihood depends on the location of zero rows in $\FF$ (and thus the zero rows in the indicator matrix $\II_l^{(0)}$). Recall that $\E[\XX_{t_0}]$ appearing in the expected log-likelihood function is conditioned on the data so $\E[\XX_{t_0}]$ in $\Psi$ is not equal to $\xixi$ if $\xx_{t_0}$ is stochastic. + +The case where $\xx_{t_0}$ is stochastic is a little odd because conditioned on $\XX_{t_0}=\xx_{t_0}$, $\xx_t^d$ is deterministic even though $\XX_0$ is a random variable in the model. Thus in the model, $\xx_t^d$ is a random variable through $\XX_{t_0}$. But when we do the partial differentiation step for the EM algorithm, we hold $\XX$ at its expected value thus we are holding $\XX_{t_0}$ at a specific value. We cannot do that and change $\uu$ at the same time because once we fix $\XX_{t_0}$ the $\xx_t^d$ are deterministic functions of $\uu$. + +\subsection{Logical constraints to ensure a consistent system of equations} +We need to ensure that the model remains internally consistent when $\RR$ or $\QQ$ goes to zero and that we do not have an over- or under-constrained system. + +As an example of a solvable versus unsolvable model, consider the following. +\begin{equation} +\HH_t\RR_t=\begin{bmatrix} +0&0\\ +1&0\\ +0&1\\ +0&0 +\end{bmatrix} +\begin{bmatrix} +a&0\\ +0&b\\ +\end{bmatrix} = \begin{bmatrix} +0&0&0&0\\ +0&a&0&0\\ +0&0&b&0\\ +0&0&0&0\\\end{bmatrix}, +\end{equation} +then following are bad versus ok $\ZZ$ matrices. +\begin{equation} +\ZZ_{\text{bad}}=\begin{bmatrix} +c&d&0\\ +z(2,1)&z(2,2)&z(2,3)\\ +z(3,1)&z(3,1)&z(3,1)\\ +c&d&0 +\end{bmatrix},\quad +\ZZ_{\text{ok}}=\begin{bmatrix} +c&0&0\\ +z(2,1)&z(2,2)&z(2,3)\\ +z(3,1)&z(3,1)&z(3,1)\\ +c&d\neq0&0 +\end{bmatrix} +\end{equation} +Because $y_t(1)$ and $y_t(4)$ have zero observation variance, the first $\ZZ$ reduces to this for $x_t(1)$ and $x_t(2)$: +\begin{equation} +\begin{bmatrix} +y_t(1)\\ +y_t(4) +\end{bmatrix}= +\begin{bmatrix} +c x_t(1) + d x_t(2)\\ +c x_t(1) + d x_t(2) +\end{bmatrix} +\end{equation} +and since $y_t(1)\neq y_t(4)$, potentially, that is not solvable. The second $\ZZ$ reduces to +\begin{equation} +\begin{bmatrix} +y_t(1)\\ +y_t(4) +\end{bmatrix}= +\begin{bmatrix} +c x_t(1)\\ +c x_t(1) + d x_t(4) +\end{bmatrix} +\end{equation}and that is solvable for any $y_t(1)$ and $y_t(4)$ combination. Notice that in the latter case, $x_t(1)$ and $x_t(2)$ are fully specified by $y_t(1)$ and $y_t(4)$. + +\subsubsection{Constraint 1: $\ZZ$ does not lead to an over-determined observation process} +We need to ensure that a $\xx_t$ exists for all $\yy^{(0)}_t$ such that: +$$\E[\YY^{(0)}_t]=\ZZ^{(0)}\E[\XX_t]+\aa^{(0)}.$$ If $\ZZ^{(0)}$ is invertible, such a $\xx_t$ certainly exists. But we do not require that only one $\xx_t$ exists, simply that at least one exists. Thus the system can be under-constrained but not over-constrained. One way to test for this is to use the singular value decomposition (SVD) of $\ZZ^{(0)}$ ($\ZZ^{(0)}$ square). If the number of singular values of $\ZZ^{(0)}$ is less than the number of columns in $\ZZ$, which is the number of $\xx$ rows, then $\ZZ^{(0)}$ specifies an over-constrained system ($y=Zx$\footnote{This is the classic problem of solving the system of linear equations, which is standardly written $Ax=b$.}) Using the R language, you would test if the length of \verb@svd(Z)$d@ is less than than \verb@dim(Z)[2]@. If $\ZZ^{(0)}$ specifies and under-determined system, some of the singular values would be equal to 0 (within machine tolerance). It is possible that $\ZZ^{(0)}$ could specify both an over- and under-determined system at the same time. That is, the number of singular values could be less than the number of columns in $\ZZ^{(0)}$ and some of the singular values could be 0. + +Doesn't a $\ZZ$ with more rows than columns automatically specify a over-determined system? No. Considered this $\ZZ$ +\begin{equation} +\begin{bmatrix} +1&0\\ +0&1\\ +0&0 +\end{bmatrix} +\end{equation} +This $\ZZ$ is fine, although obviously the last row of $\yy$ will not hold any information about the $\xx$. But it could have information about $\RR$ and $\aa$, which might be shared with the other $\yy$, so we don't want to prevent the user from specifying a $\ZZ$ like this. + + +\subsubsection{Constraint 2: the state processes are not over-constrained. } +We also need to be concerned with the state process being over-constrained when both $\QQ=0$ and $\RR=0$ because we can have a situation where the constraint imposed by the observation process is at odds with the constraint imposed by the state process. Here is an example: + +\begin{equation} +\begin{split} +\yy_t=\begin{bmatrix} +1&0\\ +0&1 +\end{bmatrix} +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_t\\ +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_t= +\begin{bmatrix} +1&0\\ +0&0 +\end{bmatrix} +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_{t-1} ++ +\begin{bmatrix} +w_1\\0 +\end{bmatrix}_{t-1} +\end{split} +\end{equation} + +In this case, some of the $x$'s are deterministic, $\QQ=0$ and not linked through $\BB$ to a stochastic $x$, and the corresponding $y$ are also deterministic. These cases will show up as errors in the Kalman filter/smoother because in the Kalman gain equation (equation \ref{eq:Kt}), the term $\ZZ_t\VV_t^{t-1}\ZZ_t^\top$ will appear when $\RR=0$. We need to make sure that 0 rows in $\BB_t$, $\ZZ_t$ and $\QQ_t$ do not line up in such a way that 0 rows/cols do not appear in $\ZZ_t\VV_t^{t-1}\ZZ_t^\top$ at the same place as 0 rows/cols in $\RR$. In MARSS, this is checked by doing a pre-run of the Kalman smoother to see if it throws an error in the Kalman gain step. + +\section{EM algorithm modifications for degenerate models} + +The $\RR$, $\QQ$, $\ZZ$, and $\aa$ update equations are largely unchanged. The real difficulties arise for the $\uu$ and $\xixi$ update equations when $\uu^{(0)}$ or $\xixi^{(0)}$ are estimated. For $\BB$, I do not have a degenerate update equation, so I need to assume that $\BB^{(0)}$ elements are fixed (not estimated). + +\subsection{$\RR$ and $\QQ$ update equations} +The constrained update equations for $\QQ$ and $\RR$ work fine because their update equations do not involve any inverses of non-invertible matrices. However if $\HH_t\RR_t\HH_t^\top$ is non-diagonal and there are missing values, then the $\RR$ update equation involves $\hatyt$. That will involve the inverse of $\HH_t\RR_{11}\HH_t^\top$ (section \ref{sec:exp.Y}), which might have zeros on the diagonal. In that case, use the $\IR_t$ modification that deals with such zeros (equation \ref{eq:IRt.degen}). + + +\subsection{$\ZZ$ and $\aa$ update equations} +We need to deal with $\ZZ$ and $\aa$ elements that appear in rows where the diagonal of $\RR=0$. These values will not appear in the likelihood function unless they also happen to also appear on the rows where the diagonal of $\RR$ is not 0 (because they are constrained to be equal for example). However, in this case the $\ZZ^{(0)}$ and $\aa^{(0)}$ are logically constrained by the equation +$$\yy_t^{(0)}=\ZZ_t^{(0)}\E[\xx_t]+\aa_t^{(0)}.$$ +Notice there is no $\ww_t$ since $\RR=0$ for these rows. The $\E[\xx_t]$ is ML estimate of $\xx_t$ computed in the Kalman smoother from the parameter values at iteration $i$ of the EM algorithm, so there is no information in this equation for $\ZZ$ and $\aa$ at iteration $i+1$. The nature of the smoother is that it will find the $\xx_t$ that is most consistent with the data. For example if our $y=Zx+a$ equation looks like so +\begin{equation} +\begin{bmatrix} +0\\ +2\\ +\end{bmatrix} += +\begin{bmatrix} +1\\ +1\\ +\end{bmatrix} +x, +\end{equation} +there is no $x$ that will solve this. However $x=1$ is the closest (lowest squared error) and so this is the information in the data about $x$. The Kalman filter will use this and the relative value of $\QQ$ and $\RR$ to come up with the estimated $x$. In this case, $\RR=0$, so the information in the data will completely determine $x$ and the smoother would return $x=1$ regardless of the process equation. + +The $\aa$ and $\ZZ$ update equations require that $\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a}$ and $\sum_{t=1}^T \DD_{t,z}^\top\Rm_t\DD_{t,z}$ are invertible. If $\ZZ_t^{(0)}$ and $\aa_t^{(0)}$ are fixed, this will be satisfied, however the restriction is a little less restrictive than that since it is possible that $\Rm_t$ does not have zeros on the diagonal in the same places so that the sum over $t$ could be invertible while the individual values at $t$ are not. The section on the summary of constraints has the test for this constraint. + +The update equations also +involve $\hatyt$, and the modified algorithm for $\hatyt$ when $\HH_t$ has all zero rows will be needed. Other than that, the constrained update equations work (sections \ref{sec:constA} and \ref{sec:constZ}). + +\subsection{$\uu$ update equation} + +Here I discuss the update for $\uu$, or more specifically $\uupsilon$ which appears in $\uu$, when $\GG_t$ or $\HH_t$ have zero rows. I require that $\uu^{is}_t$ is not estimated. All the $\uu^{is}_t$ are fixed values. The $\uu_t^d$ may be estimated or more specifically there may be $\uupsilon$ in $\uu_t^d$ that are estimated; $\uu_t^d = \ff_{u,t}^d+\DD_{u,t}^d\uupsilon$. + + +For the constrained $\uu$ update equation with deterministic $\xx$'s takes the following form. It is similar to the unconstrained update equation except that that a part from the $\yy$ part of the likelihood now appears: +\begin{equation} +\begin{split}\label{eq:u.update.degen.2} +\pmb{\upsilon}_{j+1} = \bigg(\sum_{t=1}^T(\Delta_{t,2}^\top\Rm_t\Delta_{t,2} + \Delta_{t,4}^\top\Qm_t\Delta_{t,4})\bigg)^{-1} \times + \bigg( \sum_{t=1}^T \big( \Delta_{t,2}^\top\Rm_t\Delta_{t,1} + \Delta_{t,4}^\top\Qm_t\Delta_{t,3} \big) \bigg)\\ +\end{split} +\end{equation} + +Conceptually, I think the approach described here is the similar to the approach presented in section 4.2.5 of \citep{Harvey1989}, but it is more general because it deals with the case where some $\uu$ elements are shared (linear functions of some set of shared values), possibly across deterministic and stochastic elements. Also, I present it here within the context of the EM algorithm, so solving for the maximum-likelihood $\uu$ appears in the context of maximizing $\Psi^+$ with respect to $\uu$ for the update equation at iteration $j+1$. + +\subsubsection{$\uu^{(0)}$ is not estimated} +When $\uu^{(0)}$ is not estimated (since it is at some user defined value via $\DD_u$ and $\ff_u$), the part we are estimating, $\uu^+$, only appears in the $\xx$ part of the likelihood. The update equation for $\uu$ remains equation \ref{eq:u.general.update1}. + +\subsubsection{$\uu^d$ is estimated} +The derivation of the update equation proceeds as usual. We need to take the partial derivative of $\Psi^+$ (equation \ref{eq:degen.logL.x0}) holding everything constant except $\uupsilon$, elements of which might appear in both $\uu_t^d$ and $\uu_t^s$ (but not $\uu_t^{is}$ since I require that $\uu_t^{is}$ has no estimated elements). + +The expected log-likelihood takes the following form, where $t_0$ is the time where the initial state is defined ($t=0$ or $t=1$): +\begin{equation}\label{eq:degen.logL.u} +\begin{split} +\Psi^+ = +-\frac{1}{2}\sum_1^T (\Delta_{t,1} - \Delta_{t,2}\pmb{\upsilon})^\top\Rm_t(\Delta_{t,1} - \Delta_{t,2}\pmb{\upsilon}) - \frac{1}{2}\sum_1^T\log |\RR_t| \\ +-\frac{1}{2}\sum_{t_0+1}^T (\Delta_{t,3} - \Delta_{t,4}\pmb{\upsilon})^\top\Qm_t(\Delta_{t,3} - \Delta_{t,4}\pmb{\upsilon}) - \frac{1}{2}\sum_{t_0+1}^T\log |\QQ_t| \\ +- \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| - \frac{n}{2}\log 2\pi \\ +\end{split} +\end{equation} +$\LAMm=\FF^\top\LAM^{-1}\FF$. If $\xx_{t_0}$ is treated as fixed, $\FF$ is all zero and the line with $\LAMm$ drops out. If some but not all $\xx_{t_0}$ are treated as fixed, then only the stochastic rows appear in the last line. In any case, the last line does not contain $\uupsilon$, thus when we do the partial differentiation with respect to $\uupsilon$, this line drops out. + +The $\Delta$ terms are defined as: +\begin{equation}\label{eq:degen.u.update.Deltas} +\begin{split} +\Delta_{t,1}&=\hatyt - \ZZ_t(\II_m - \II_t^d)\hatxt - \ZZ_t\II_t^{d}(\BB^*_t\E[\XX_{t_0}] + \ff^*_t) - \aa_t \\ +\Delta_{t,2}&= \ZZ_t\II_t^{d}\DD^*_t \\ +\Delta_{t_0,3}&=0_{m\times 1} \\ +\Delta_{t,3}&=\hatxt - \BB_t(\II_m - \II_{t-1}^d)\hatxtm - \BB_t\II_{t-1}^{d}(\BB^*_{t-1} \E[\XX_{t_0}] + \ff^*_{t-1}) - \ff_{t,u} \\ +\Delta_{t_0,4}&=0_{m\times m} \DD_{1,u} \\ +\Delta_{t,4}&=\DD_{t,u}+\BB_t\II_{t-1}^{d}\DD^*_{t-1} \\ +\E[\XX_{t_0}]&=((\II_m-\II_\lambda^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \xixi) +\end{split} +\end{equation} +$\II^d_t$, $\BB_t^*$, $\ff_t*$, and $\DD_t^*$ are defined in equation \ref{eq:xt.det.sum2}. The values of these at $t_0$ is special so that the math works out. The expectation ($\E$) has been subsumed into the $\Delta$s since $\Delta_2$ and $\Delta_4$ do not involve $\XX$ or $\YY$, so terms like $\XX^\top\XX$ never appear. + +Take the derivative of this with respect to $\uupsilon$ and arrive at: +\begin{equation} +\begin{split} +\label{eq:p.degen.update.u} +\uupsilon_{j+1} = \big(\sum_{t=1}^T\Delta_{t,4}^\top\Qm_t\Delta_{t,4} + \sum_{t=1}^T\Delta_{t,2}^\top\Rm_t\Delta_{t,2}\big)^{-1} \times + \bigg(\sum_{t=1}^T\Delta_{1,4}^\top\Qm_t\Delta_{1,3} + \sum_{t=1}^T \Delta_{t,2}^\top\Rm_t\Delta_{t,1})\bigg) +\end{split} +\end{equation} + +\subsection{$\xixi$ update equation} + +\subsubsection{$\xixi$ is stochastic} +This means that none of the rows of $\FF$ (in $\FF\lambda$) are zero, so $\II_\lambda^{(0)}$ is all zero and the update equation reduces to a constrained version of the classic $\xixi$ update equation: +\begin{equation} +\label{eq:p.degen.update.x0.0.a} +\pp_{j+1} = \big(\DD_\xi^\top\LAM^{-1}\DD_\xi\big)^{-1}\DD_\xi^\top\LAM^{-1}(\E[\XX_{t_0}] - \ff_\xi) +\end{equation} +\subsubsection{$\xixi^{(0)}$ is not estimated} +When $\xixi^{(0)}$ is not estimated (because you fixed it as some value), we do not need to take the partial derivative with respect to $\xixi^{(0)}$ since we will not be estimating it. Thus the update equation is unchanged from the constrained update equation. + +\subsubsection{$\xixi^{(0)}$ is estimated} +Using the same approach as for $\uu$ update equation, we take the derivative of \ref{eq:degen.logL.x0} with respect to $\pp$ where $\xixi=\ff_\xi+\DD_\xi\pp$. $\Psi^+$ will take the following form: +\begin{equation}\label{eq:degen.logL.x0.0} +\begin{split} +\Psi^+ &= \\ +&-\frac{1}{2}\sum_{t=1}^T (\Delta_{t,5} - \Delta_{t,6}\pp)^\top\Rm_t(\Delta_{t,5} - \Delta_{t,6}\pp) - \frac{1}{2}\sum_1^T\log |\RR_t| \\ +& -\frac{1}{2}\sum_{t=1}^T (\Delta_{t,7} - \Delta_{t,8}\pp)^\top\Qm_t(\Delta_{t,7} - \Delta_{t,8}\pp) - \frac{1}{2}\sum_1^T\log |\QQ_t| \\ +& -\frac{1}{2} (\E[\XX_{t_0}] - \ff_\xi - \DD_\xi\pp)^\top\LAMm(\E[\XX_{t_0}] - \ff_\xi - \DD_\xi\pp) - \frac{1}{2}\log |\LAM| \\ +& - \frac{n}{2}\log 2\pi \\ +\end{split} +\end{equation} + +The $\Delta$'s are defined as follows using $ \E[\XX_{t_0}]=(\II_m-\II_l^{(0)})\widetilde{\xx}_{t_0}+\II_l^{(0)}\xixi$ where it appears in $\II_t^d\E[\XX_t]$. +\begin{equation}\label{eq:degen.x0.update.Deltas} +\begin{split} +\Delta_{t,5}&=\hatyt - \ZZ_t(\II_m - \II_t^d)\hatxt - \ZZ_t\II_t^{d}(\BB^*_t((\II_m-\II_\lambda^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \ff_\xi) + \uu^*_t) - \aa_t \\ +\Delta_{t,6}&= \ZZ_t\II_t^{d}\BB^*_t\II_\lambda^{(0)}\DD_\xi \\ +\Delta_{t_0,7}&=0_{m\times 1} \\ +\Delta_{t,7}&=\hatxt - \BB_t(\II_m - \II_{t-1}^d)\hatxtm - \BB_t\II_{t-1}^{d}(\BB^*_{t-1} ((\II_m-\II_l^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \ff_\xi) + \uu^*_{t-1}) - \uu_t \\ +\Delta_{t_0,8}&=0_{m\times m} \DD_\xi\\ +\Delta_{t,8}&=\BB_t\II_{t-1}^{d}\BB^*_{t-1}\II_\lambda^{(0)}\DD_\xi\\ +\uu^*_t=\ff^*_t+\DD^*_t\uupsilon +\end{split} +\end{equation} +The expectation can be pulled inside the $\Delta$s since the $\Delta$s in front of $\pp$ do not involve $\XX$ or $\YY$. + +Take the derivative of this with respect to $\pp$ and arrive at: +\begin{equation} +\begin{split} +\label{eq:p.degen.update.x0.0.a.fixed} +\pp_{j+1} &= \big(\sum_{t=1}^T\Delta_{t,8}^\top\Qm_t\Delta_{t,8} + \sum_{t=1}^T\Delta_{t,6}^\top\Rm_t\Delta_{t,6} + \DD_\xi^\top\LAMm\DD_\xi\big)^{-1} \times\\ +&\quad \bigg(\sum_{t=1}^T\Delta_{1,8}^\top\Qm_t\Delta_{1,7} + \sum_{t=1}^T \Delta_{t,6}^\top\Rm_t\Delta_{t,5} + \DD_\xi^\top\LAMm(\E[\XX_{t_0}] - \ff_\xi)\bigg) +\end{split} +\end{equation} + +\subsubsection{When $\HH_t$ has 0 rows in addition to $\GG_t$} +When $\HH_t$ has all zero rows, some of the $\pp$ or $\uupsilon$ may constrained by the model, but these constraints do not appear in $\Psi^+$ since $\Rm_t$ zeros out those constraints. For example, if $H_t$ is all zeros and $\xx_1 \equiv \xixi$, then $\xixi$ is constrained to equal $\ZZ^{-1}(\hatyone-\aa_1)$. + +The model needs to be internally consistent and we need to be able to estimate all the $\pp$ and the $\uupsilon$. Rather than try to estimate the correct $\pp$ and $\uupsilon$ to ensure internal consistency of the model with the data when some of the $\HH_t$ have 0 rows, I test by running the Kalman filter with the degenerate variance modification (in particular the modification for $\FF$ with zero rows is critical) before starting the EM algorithm. Then I test that $\hatyt-\ZZ_t\hatxt-\aa_t$ is all zeros. If it is not, within machine accuracy, then there is a problem. This is reported and the algorithm stopped\footnote{In some cases, it is easy to determine the correct $\xixi$. For example, when $\HH_t$ is all zero rows, $t_0=1$ and there is no missing data at time $t=1$, $\xixi=\ZZ^*(\yy_1-\aa_1)$, where $\ZZ^*$ is the pseudoinverse. One would want to use the SVD pseudoinverse calculation in case $\ZZ$ leads to an under-constrained system (some of the singular values of $\ZZ$ are 0). } + +I also test that $\big(\sum_{t=1}^T\Delta_{t,8}^\top\Qm_t\Delta_{t,8} + \sum_{t=1}^T\Delta_{t,6}^\top\Rm_t\Delta_{t,6} + \DD_\xi^\top\LAMm\DD_\xi\big)$ is invertible to ensure that all the $\pp$ can be solved for, and I test that $\big(\sum_{t=1}^T\Delta_{t,4}^\top\Qm_t\Delta_{t,4} + \sum_{t=1}^T\Delta_{t,2}^\top\Rm_t\Delta_{t,2}\big)$ is invertible so that all the $\uupsilon$ can be solved for. If errors are present, they should be apparent in iteration 1, are reported and the EM algorithm stopped. + +\subsection{$\BB^{(0)}$ update equation for degenerate models} +I do not have an update equation for $\BB^{(0)}$ and for now, I side-step this problem by requiring that any $\BB^{(0)}$ terms are fixed. + +\section{Kalman filter and smoother modifications for degenerate models} + +\subsection{Modifications due to degenerate $\RR$ and $\QQ$} +[1/1/2012 note. These modifications mainly have to do with inverses that appear in the Shumway and Stoffer's presentation of the Kalman filter. The MARSS package uses Koopman's smoother algorithm which avoids these inverses altogether however these appear in the MARSSkfss() function (the Shumway and Stoffer implementation).] + +In principle, when either $\GG_t\QQ_t$ or $\HH_t\RR_t$ has zero rows, the standard Kalman filter/smoother equations would still work and provide the correct state outputs and likelihood. In practice however errors will be generated because under certain situations, one of the matrix inverses in the Kalman filter/smoother equations will involve a matrix with a zero on the diagonal and this will lead to the computer code throwing an error. + +When $\HH_t\RR_t$ has zero rows, problems arise in the Kalman update part of the Kalman filter. +The Kalman gain is +\begin{equation}\label{eq:KKt.2} +\KK_t = \VV_t^{t-1}(\ZZ_t^*)^\top(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)^{-1} +\end{equation} +Here, $\ZZ_t^*$ is the missing values modified $\ZZ_t$ matrix with the $i$-th rows zero-ed out if the $i$-th element of $\yy_t$ is missing (section \ref{sec:kalman.smoother}, equation \ref{eq:yaZ.miss}). Thus if the $i$-th element of $\yy_t$ is missing and the $i$-th row of $\HH_t$ is zero, the $(i,i)$ element of $(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)$ will be zero also and one cannot take its inverse. In addition, if the initial value $\xx_1$ is treated as fixed but unknown then $\VV_1^0$ will be a $m \times m$ matrix of zeros. Again in this situation $(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)$ will have zeros at any $(i,i)$ elements where the $i$-th row of $\HH_t$ is also zero. + +The first case, where zeros on the diagonal arise due to missing values in the data, can be solved using the matrix which pulls out the rows and columns corresponding to the non-missing values ($\OMG_t^{(1)}$). Replace $\big(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top\big)^{-1}$ in equation \ref{eq:KKt.2} with +\begin{equation} +(\OMG_t^{(1)})^\top\big(\OMG_t^{(1)}(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)(\OMG_t^{(1)})^\top\big)^{-1}\OMG_t^{(1)} +\end{equation} +Wrapping in $\OMG_t^{(1)}(\OMG_t^{(1)})^\top$ gets rid of all the zero rows/columns in $\ZZ_t^\prime\VV_t^{t-1}(\ZZ_t^\prime)^\top + \HH_t\RR_t^\prime\HH_t^\top$, and the matrix is reassembled with the zero rows/columns reinserted by wrapping in $(\OMG_t^{(1)})^\top\OMG_t^{(1)}$. This works because $\RR_t^\prime$ is the missing values modified $\RR$ (section \ref{sec:missing}) and is block diagonal across the $i$ and non-$i$ rows/columns, and $\ZZ_t^\prime$ has the $i$-columns zero-ed out. Thus removing the $i$ columns and rows before taking the inverse has no effect on the product $\ZZ_t(...)^{-1}$. When $\VV_1^0=\mathbf{0}$, set $\KK_1=\mathbf{0}$ without computing the inverse (see equation \ref{eq:KKt.2} where $\VV_1^0$ appears on the left). + +There is also a numerical issue to deal with. When the $i$-th row of $\HH_t$ is zero, some of the elements of $\xx_t$ may be completely specified (fully known) given $\yy_t$. Let's call these fully known elements of $\xx_t$, the $k$-th elements. In this case, the $k$-th row and column of $\VV_t^t$ must be zero because given $y_t(i)$, $x_t(k)$ is known (is fixed) and its variance, $\VV_t^t(k,k)$, is zero. Because $\KK_t$ is computed using a numerical estimate of the inverse, the standard $\VV_t^t$ update equation (which uses $\KK_t$) will cause these elements to be close to zero but not precisely zero, and they may even be slightly negative on the diagonal. This will cause serious problems when the Kalman filter output is passed on to the EM algorithm. Thus after $\VV_t^t$ is computed using the normal Kalman update equation, we will want to explicitly zero out the $k$ rows and columns in the filter. + +When $\GG_t$ has zero rows, then we might also have similar numerical errors in $\JJ$ in the Kalman smoother. The $\JJ$ equation is +\begin{equation}\label{eq:Jt.2} +\begin{split} +\JJ_t &= \VV_{t-1}^{t-1}\BB_t^\top(\VV_t^{t-1})^{-1}\\ +&\text{where }\VV_t^{t-1} = \BB_t \VV_{t-1}^{t-1} \BB_t^\top + \GG_t\QQ_t\GG_t^\top +\end{split} +\end{equation} +If there are zeros on the diagonals of ($\LAM$ and/or $\BB_t$) and zero rows in $\GG_t$ and these zeros line up, then if the $\BB_t^{(0)}$ and $\BB_T^{(1)}$ elements in $\BB_t$ are blocks\footnote{This means the following. Let the rows where the diagonal elements in $\QQ$ equal zero be denoted $i$ and the the rows where there are non-zero diagonals be denoted $j$. The $\BB_t^{(0)}$ elements are the $\BB_t$ elements where both row and column are in $i$. The $\BB_t^{(1)}$ elements are the $\BB$ elements where both row and column are in $j$. If the $\BB_t^{(0)}$ and $\BB_t^{(1)}$ elements in $\BB$ are blocks, this means all the $\BB_t(i,j)$ are 0; no deterministic components interact with the stochastic components.}, there will be zeros on the diagonal of $\VV_t^t$. Thus there will be zeros on the diagonal of $\VV_t^{t-1}$ and it cannot be inverted. In this case, the corresponding elements of $\VV_t^T$ need to be zero since what's happening is that those elements are deterministic and thus have 0 variance. + +We want to catch these zero variances in $\VV_t^{t-1}$ so that we can take the inverse. Note that this can only happen when there are zeros on the diagonal of $\GG_t\QQ_t\GG_t^\top$ since $\BB_t\VV_{t-1}^{t-1} \BB_t^\top$ can never be negative on the diagonal since $\BB_t\BB_t^\top$ must be positive-definite and so is $\VV_{t-1}^{t-1}$. The basic idea is the same as above. We replace $(\VV_t^{t-1})^{-1}$ with: +\begin{equation} +(\OMG_{Vt}^+)^\top\big(\OMG_{Vt}^+(\VV_t^{t-1})(\OMG_{Vt}^+)^\top\big)^{-1}\OMG_{Vt}^+ +\end{equation} +where $\OMG_{Vt}^+$ is a matrix that removes all the positive $\VV_t^{t-1}$ rows analogous to $\OMG_t^{(1)}$. + +\subsection{Modifications due to fixed initial states} +When the initial state of $\xx$ is fixed, then it is a bit like $\LAM=0$ although actually $\LAM$ does not appear in the model and $\xixi$ has a different interpretation. + +When the initial state of $\xx$ is treated as stochastic, then if $t_0=0$, $\xixi$ is the expected value of $\xx_0$ conditioned on no data. In the Kalman filter this means $\xx_0^0=\xixi$ and $\VV_0^0=\LAM$; in words, the expected value of $\xx_0$ conditioned on $\yy_0$ is $\xixi$ and the variance of $\xx_0^0$ conditioned on $\yy_0$ is $\LAM$. When $t_0=1$, then $\xixi$ is the expected value of $\xx_1$ conditioned on no data. In the Kalman filter this means $\xx_1^0=\xixi$ and $\VV_1^0=\LAM$. Thus where $\xixi$ and $\LAM$ appear in the Kalman filter equations is different depending on $t_0$; the $\xx_t^t$ and $\VV_t^{t}$ initial condition versus the $\xx_t^{t-1}$ and $\VV_t^{t-1}$ initial condition. + +When some or all of the $\xx_{t_0}$ are fixed, denoted the $\II_\lambda^{(0)}\xx_{t_0}$, the fixed values are not a random variables. While technically speaking, the expected value of a fixed value does not exist, we can think of it as a random variable with a probability density function with all the weight on the fixed value. Thus $\II_\lambda^{(0)}\E[\xx_{t_0}]=\xixi$ regardless of the data. The data have no information for $\II_\lambda^{(0)}\xx_{t_0}$ since we fix $\II_\lambda^{(0)}\xx_{t_0}$ at $\II_\lambda^{(0)}\xixi$. If $t_0=0$, we initialize the Kalman filter as usual with $\xx_0^0=\xixi$ and $\VV_0^0=\FF\LAM\FF^\top$, where the fixed $\xx_{t_0}$ rows correspond to the zero row/columns in $\FF\LAM\FF^\top$. The Kalman filter will return the correct expectations even when some of the diagonals of $\HH\RR\HH^\top$ or $\GG\QQ\GG^\top$ are 0---with the constraint that we have no purely deterministic elements in the model (meaning there are no errors terms from either $\RR$ or $\QQ$). + +When $t_0=1$, $\II_\lambda^{(0)}\xx_1^0$ and $\II_l^{(0)}\xx_1^1=\xixi$ regardless of the data and $\VV_1^0=\FF\LAM\FF^\top$ and $\VV_1^1=\FF\LAM\FF^\top$, where the fixed rows of $\xx_1$ correspond with the 0 row/columns in $\FF\LAM\FF^\top$. We also set $\II_\lambda^{(0)}\KK_1$, meaning the rows of $\xx_1$ that are fixed, to all zero because $\KK_1$ is the information in $\yy_1$ regarding $\xx_1$ and there is no information in the data regarding the values of $\xx_1$ that are fixed to equal $\II_\lambda^{(0)}\xixi$. + +With $\VV_1^1$, $\xx_1^1$ and $\KK_1$ set to their correct initial values, the normal Kalman filter equations will work fine. However it is possible for the data at $t=1$ to be inconsistent with the model if the rows of $\yy_1$ corresponding to any zero row/columns in $\ZZ_1\FF\LAM\FF^\top\ZZ_1^\top+\HH_1\RR_1\HH_1^\top$ are not equal to $\ZZ_1\xixi + \aa_1$. Here is a trivial example, let the model be $x_t=x_{t-1}+w_t$, $y_t=x_t$, $x_1=1$. Then if $y_1$ is anything except 1, the model is impossible. Technically, the likelihood of $x_1$ conditioned on $Y_1=y_1$ does not exist since neither $x_1$ nor $y_1$ are realizations of a random variable (since they are fixed), so when the likelihood is computed using the innovations form of the likelihood, the $t=1$ does not appear, at least for those $\yy_1$ corresponding to any zero row/columns in $\ZZ_1\FF\LAM\FF^\top\ZZ_1^\top+\HH_1\RR_1\HH_1^\top$. Thus these internal inconsistencies would neither provoke an error nor cause Inf to be returned for the likelihood. In the MARSS package, the Kalman filter has been modified to return LL=Inf and an error. + +\section{Summary of requirements for degenerate models} +Below are discussed the update equations for the different parameters. Here I summarize the constraints that are scattered throughout these subsections. These requirements are coded into the function MARSSkemcheck() in the MARSS package but some tests must be repeated in the function degen.test(), which tests if any of the $\RR$ or $\QQ$ diagonals can be set to zero if it appears they are going to zero. A model that is allowed when $\RR$ and $\QQ$ are non-zero, might be disallowed if $\RR$ or $\QQ$ diagonals were to be set to zero. degen.test() does this check. + +\begin{itemize} +\item $(\II_m \otimes \II_r^{(0)}\ZZ_t\II_q^{(0)})\DD_{t,b}$, is all zeros. If there is a all zero row in $\HH_t$ and it is linked (through $\ZZ$) to a all zero row in $\GG_t$, then the corresponding $\BB_t$ elements are fixed instead of estimated. Corresponding $\BB$ rows means those rows in $\BB$ where there is a non-zero column in $\ZZ$. We need $\II_r^{(0)}\ZZ_t\II_q^{(0)}\BB_t$ to only specify fixed $\BB_t$ elements, which means $\vec(\II_r^{(0)}\ZZ_t\II_q^{(0)}\BB_t\II_m)$ only specifies fixed values. This in turn leads to the condition above. MARSSkemcheck() +\item $(\II_1 \otimes \II_r^{(0)}\ZZ_t\II_q^{(0)})\DD_{t,u}$ is all zeros; if there is a all zero row in $\HH_t$ and it is linked (through $\ZZ_t$) to a all zero row in $\GG_t$, then the corresponding $\uu_t$ elements are fixed instead of estimated. MARSSkemcheck() +\item $(\II_m \otimes \II_r^{(0)})\DD_{t,z}$, where is all zeros; if $y$ has no observation error, then the corresponding $\ZZ_t$ rows are fixed values. $(\II_m \otimes \II_r^{(0)})$ is a diagonal matrix with 1s for the rows of $\DD_{t,z}$ that correspond to elements of $\ZZ_t$ on the $R=0$ rows. MARSSkemcheck() +\item $(\II_1 \otimes \II_r^{(0)})\DD_{t,a}$ is all zeros; if $y$ has no observation error, then the corresponding $\aa_t$ rows are fixed values. MARSSkemcheck() +\item $(\II_m \otimes \II_q^{(0)})\DD_{t,b}$ is all zeros. This means $\BB^{(0)}$ (the whole row) is fixed. While $\BB^d$ could potentially be estimated potentially, my derivation assumes it is not. MARSSkemcheck() +\item $(\II_1 \otimes \II_{q,t>m}^{is})\DD_{t,u}$ is all zeros. This means $\uu^{is}$ is fixed. Here $is$ is defined as those rows that are indirectly stochastic at time $m$, where $m$ is the dimension of $\BB$; it can take up to $m$ steps for the $is$ rows to be connected to the $s$ rows through $\BB$. MARSSkemcheck() +\item If $\uu^{(0)}$ or $\xixi^{(0)}$ are being estimated, then the adjacency matrices defined by $\BB_t \neq 0$ are not time-varying. This means that the locations of the 0s in $\BB_t$ are not changing over time. $\BB_t$ however may be time-varying. MARSSkemcheck() +\item $\II_q^{(0)}$ and $\II_r^{(0)}$ are time invariant (an imposed assumption). This means that the location of the 0 rows in $\GG_t$ and $\HH_t$ (and thus in $\ww_t$ and $\vv_t$) are not changing through time. It would be easy enough to allow $\II_r^{(0)}$ to be time varying, but to make my derivation easier, I assume it is time constant. +\item $\ZZ_t^{(0)}$ in $\E[\YY_t^{(0)}]=\ZZ_t^{(0)}\E[\XX_t]+\aa_t^{(0)}$ does not imply an over-determined system of equations. Because the $\vv_t$ rows are zero for the ${(0)}$ rows of $\yy$, it must be possible for this equality to hold. This means that $\ZZ_t^{(0)}$ cannot specify an over-determined system although an underdetermined system is ok. The check is in MARSSkfss() since the fully-specified $x$ need to be known for the MARSSkfss() filter. If $\ZZ_t^{(0)}$ is square, its inverse is attempted and if that throws and error an error is reported (re over-constrained model). The function to find the fully determined $\xx$ is fully.det.x() in the utility functions. +\item The state process cannot be over-determined via constraints imposed from the deterministic observation process ($\RR=0$) and the deterministic state process ($\QQ=0$). If this is the case the Kalman gain equation (in the Kalman filter) will throw an error. Checked in MARSS() via call to MARSSkf() before fitting call; degen.test(), in MARSSkem() will also test via MARSSkf call if some R or Q are attempted to be set to 0. If B or Z changes during kem or optim iterations such that this constraint does not hold, then algorithm will exit with an error message. +\item The location of the 0s in $\BB$ are time-invariant. The $\BB$ can be time-varying but not the location of 0s. Also, I want $\BB$ to be such that once a row becomes indirectly stochastic is stays that way. For example, if $\BB=\bigl[ \begin{smallmatrix} +0&1\\ 1&0 \end{smallmatrix} \bigr]$, then row 2 flips back and forth from being indirectly stochastic to deterministic. +\end{itemize} +The dimension of the identity matrices in the above constraints is given by the subscript on $\II$ except when it is implicit. + +\section{Implementation comments}\label{sec:implementation} +The EM algorithm is a hill-climbing algorithm and like all hill-climbing algorithms it can get stuck on local maxima. There are a number approaches to doing a pre-search of the initial conditions space, but a brute force random Monte Carol search appears to work well \citep{Biernackietal2003}. It is slow, but normally sufficient. However an initial conditions search should be done before reporting final estimates for an analysis. In our papers on the distributional properties of MARSS parameter estimates, we rarely found that an initial conditions search changed the estimates---except in cases where $\ZZ$ and $\BB$ are estimated as unconstrained and as the fraction of missing data in the data set became large. + +The EM algorithm will quickly home in on parameter estimates that are close to the maximum, but once the values are close, the EM algorithm can slow to a crawl. Some researchers start with an EM algorithm to get close to the maximum-likelihood parameters and then switch to a quasi-Newton method for the final search. In many ecological applications, parameter estimates that differ by less than 3 decimal places are for all practical purposes the same. Thus we have not used the quasi-Newton final search. + +Shumway and Stoffer (2006; chapter 6) imply in their discussion of the EM algorithm that both $\xixi$ and $\LAM$ can be estimated, though not simultaneously. Harvey (1989), in contrast, discusses that there are only two allowable cases for the initial conditions: 1) fixed but unknown and 2) a initial condition set as a prior. In case 1, $\xixi$ is $\xx_0$ (or $\xx_1$) and is then estimated as a parameter; $\LAM$ is held fixed at 0. In case 2, $\xixi$ and $\LAM$ specify the mean and variance of $\XX_0$ (or $\XX_1$) respectively. Neither are estimated; instead, they are specified as part of the model. + +As mentioned in the introduction, misspecification of the prior on $\xx_0$ can have catastrophic and undetectable effects on your parameter estimates. For many MARSS models, you will never see this problem. However, if you are fitting models that imply a correlation structure between the hidden states, i.e., the variance-covariance matrix of the $\XX$'s is not diagonal, then your prior can definitely create problems if it does not have the same correlation structure as that implied by your MLE model. A common default is to use a prior with a diagonal variance-covariance matrix. This can lead to serious problems if the implied variance-covariance of the $\XX$'s is not diagonal. A diffuse prior does not get around this since it has a correlation structure also even if it has infinite variance. + +One way you can detect that you have a problem is to start the EM algorithm at the outputs from a Newton-esque algorithm. If the EM estimates diverge and the likelihood drops, you have a problem. Here are a few suggestions for getting around the problem: +\begin{itemize} + \item Treat $\xx_0$ as an estimated parameter and set $\VV_0$=0. If the model is not stable going backwards in time, then treat $\xx_1$ as the estimated parameter; this will allow the data to constrain the $\xx_1$ estimate (since there is no data at $t=0$, $\xx_0$ has no data to constrain it). + \item Try a diffuse prior, but first read the info in the KFAS R package about diffuse priors since MARSS uses the KFAS implementation. In particular, note that you will still be imposing an information on the correlation structure using a diffuse prior; whatever $\VV_0$ you use is telling the algorithm what correlation structure to use. If there is a mismatch between the correlation structure in the prior and the correlation structure implied by the MLE model, you will not be escaping the prior problem. But sometimes you will know your implied correlation structure. For example, you may know that the $\xx$'s are independent or you may be able to solve for the stationary distribution a priori if your stationary distribution is not a function of the parameters you are trying to estimate. Other times you are estimating a parameter that determines the correlation structure (like $\BB$) and you will not know a priori what the correlation structure is. +\end{itemize} + +In some cases, the update equation for one parameter needs other parameters. Technically, the Kalman filter/smoother should be run between each parameter update, however following \citet{GhahramaniHinton1996} the default MARSS algorithm skips this step (unless the user sets \verb@control$safe=TRUE@) and each updated parameter is used for subsequent update equations. If you see warnings that the log-likelihood drops, then try setting \verb@control$safe=TRUE@. This will increase computation time greatly. + +\section{MARSS R package} +R code for the Kalman filter, Kalman smoother, and EM algorithm is provided as a separate R package, MARSS, available on CRAN (https://CRAN.R-project.org/package=MARSS). MARSS was developed by Elizabeth Holmes, Eric Ward and Kellie Wills and provides maximum-likelihood estimation and model-selection for both unconstrained and constrained MARSS models. The package contains a detailed user guide which shows various applications. In addition to model fitting via the EM algorithm, the package provides algorithms for bootstrapping, confidence intervals, auxiliary residuals, and model selection criteria. + +\bibliography{./EMDerivation} +\bibliographystyle{apalike} + +\end{document} diff --git a/inst/doc/EMDerivation.pdf b/inst/doc/EMDerivation.pdf new file mode 100644 index 0000000..799d544 Binary files /dev/null and b/inst/doc/EMDerivation.pdf differ diff --git a/inst/doc/Quick_Examples.R b/inst/doc/Quick_Examples.R new file mode 100644 index 0000000..befdf2d --- /dev/null +++ b/inst/doc/Quick_Examples.R @@ -0,0 +1,307 @@ +################################################### +### code chunk number 2: Cs00_load_library +################################################### +library(MARSS) + + +################################################### +### code chunk number 3: Cs01_model-gen-spec +################################################### +Z <- matrix(list("z1", "z2", 0, 0, "z2", 3), 3, 2) +A <- matrix(0, 3, 1) +R <- matrix(list(0), 3, 3) +diag(R) <- c("r", "r", 1) +B <- matrix(list("b1", 0.1, "b2", 2), 2, 2) +U <- matrix(c("u", "u"), 2, 1) +Q <- matrix(c("q1", "q3", "q3", "q2"), 2, 2) +x0 <- matrix(c("pi1", "pi2"), 2, 1) +V0 <- diag(1, 2) +model.gen <- list(Z = Z, A = A, R = R, B = B, U = U, + Q = Q, x0 = x0, V0 = V0, tinitx = 0) + + +################################################### +### code chunk number 4: Cs02_model-general (eval = FALSE) +################################################### +## kem <- MARSS(dat, model = model.gen) + + +################################################### +### code chunk number 5: Cs03_enterdata +################################################### +dat <- t(harborSealWA) +dat <- dat[2:nrow(dat), ] # remove the year row + + +################################################### +### code chunk number 6: Cs04_model-default +################################################### +kem <- MARSS(dat) + + +################################################### +### code chunk number 7: Cs05_B-setup (eval = FALSE) +################################################### +## B <- Z <- diag(1, 5) +## U <- matrix(c("u1", "u2", "u3", "u4", "u5"), 5, 1) +## x0 <- A <- matrix(0, 5, 1) +## R <- Q <- matrix(list(0), 5, 5) +## diag(R) <- "r" +## diag(Q) <- c("q1", "q2", "q3", "q4", "q5") + + +################################################### +### code chunk number 8: Cs06_model-default-time +################################################### +kem.time <- system.time(MARSS(dat, silent = TRUE)) + + +################################################### +### code chunk number 9: Cs07_model-bfgs +################################################### +bfgs <- MARSS(dat, method = "BFGS") + + +################################################### +### code chunk number 10: Cs08_model-bfgs-time +################################################### +bfgs.time <- system.time(MARSS(dat, silent = TRUE, method = "BFGS")) + + +################################################### +### code chunk number 11: Cs09_model-bfgs2 +################################################### +bfgs2 <- MARSS(dat, method = "BFGS", inits = kem$par) + + +################################################### +### code chunk number 12: Cs10_model-default (eval = FALSE) +################################################### +## kem.strange <- MARSS(dat, model = list(tinitx = 1)) + + +################################################### +### code chunk number 13: Cs11_model-corr1 +################################################### +kem <- MARSS(dat, model = list(Q = "unconstrained")) + + +################################################### +### code chunk number 14: Cs12_model-corr2 +################################################### +kem <- MARSS(dat, model = list(Q = "equalvarcov")) + + +################################################### +### code chunk number 15: Cs13_model-u-NS +################################################### +regions <- list("N", "N", "N", "S", "S") +U <- matrix(regions, 5, 1) +Q <- matrix(list(0), 5, 5) +diag(Q) <- regions +kem <- MARSS(dat, model = list(U = U, Q = Q)) + + +################################################### +### code chunk number 16: Cs14_model-u-NS-fixR +################################################### +regions <- list("N", "N", "N", "S", "S") +U <- matrix(regions, 5, 1) +Q <- matrix(list(0), 5, 5) +diag(Q) <- regions +R <- diag(0.01, 5) +kem <- MARSS(dat, model = list(U = U, Q = Q, R = R)) + + +################################################### +### code chunk number 17: Cs15_model-pan1 +################################################### +Z <- factor(c(1, 1, 1, 1, 1)) +kem <- MARSS(dat, model = list(Z = Z)) + + +################################################### +### code chunk number 18: Cs16_model-pan2 +################################################### +Z <- factor(c(1, 1, 1, 1, 1)) +R <- "diagonal and unequal" +kem <- MARSS(dat, model = list(Z = Z, R = R)) + + +################################################### +### code chunk number 19: Cs17_model-two1 +################################################### +Z <- factor(c("N", "N", "N", "S", "S")) +Q <- "diagonal and equal" +U <- "equal" +kem <- MARSS(dat, model = list(Z = Z, Q = Q, U = U)) + + +################################################### +### code chunk number 21: Cs17_model-two2 +################################################### +kem <- MARSS(dat, model = list(Z = Z, Q = Q, U = U, A="zero")) + + +################################################### +### code chunk number 22: Cs18_model-time-varying +################################################### +U1 <- matrix("t1", 5, 1) +U2 <- matrix("t2", 5, 1) +Ut <- array(U2, dim = c(dim(U1), dim(dat)[2])) +TT <- dim(dat)[2] +Ut[, , 1:floor(TT / 2)] <- U1 +Qde <- "diagonal and equal" +kem.tv <- MARSS(dat, model = list(U = Ut, Q = Qde)) + + +################################################### +### code chunk number 24: Cs19_model-print +################################################### +print(kem) +print(kem$model) + + +################################################### +### code chunk number 23: Cs19b_model-time-varying2 +################################################### +U1 <- matrix(c(rep("t1", 4), "hc"), 5, 1) +U2 <- matrix(c(rep("t2", 4), "hc"), 5, 1) +Ut <- array(U2, dim = c(dim(U1), dim(dat)[2])) +Ut[, , 1:floor(TT / 2)] <- U1 +kem.tv <- MARSS(dat, model = list(U = Ut, Q = Qde)) + + +################################################### +### code chunk number 25: Cs20_model-summary +################################################### +summary(kem$model) + + +################################################### +### code chunk number 26: Cs23_model-print-R +################################################### +x <- print(kem, what = "states", silent = TRUE) + + +################################################### +### code chunk number 27: Cs24_model-tidy-R +################################################### +tidy(kem) +glance(kem) + + +################################################### +### code chunk number 28: Cs25_CIs-hessian +################################################### +kem.with.hess.CIs <- MARSSparamCIs(kem) + + +################################################### +### code chunk number 29: Cs26_print-CIs +################################################### +print(kem.with.hess.CIs) + + +################################################### +### code chunk number 30: Cs27_CIs-pboot +################################################### +kem.w.boot.CIs <- MARSSparamCIs(kem, method = "parametric", nboot = 10) +print(kem.w.boot.CIs) + + +################################################### +### code chunk number 31: Cs28_parvec +################################################### +parvec <- coef(kem, type = "vector") +parvec + + +################################################### +### code chunk number 32: Cs29_tsSmooth +################################################### +df <- tsSmooth(kem) +head(df) + + +################################################### +### code chunk number 33: Cs30_marsskf +################################################### +kf <- MARSSkf(kem) +names(kf) +# if you only need the logLik, +MARSSkf(kem, only.logLik = TRUE) +# or +logLik(kem) + + +################################################### +### code chunk number 34: Cs31_like.kem.degen +################################################### +dat.short <- dat[1:4, 1:10] +kem.degen <- MARSS(dat.short, control = list(allow.degen = FALSE)) + + +################################################### +### code chunk number 35: Cs32_like.kem200 (eval = FALSE) +################################################### +## kem.degen2 <- MARSS(dat.short, control = list( +## maxit = 1000, +## allow.degen = FALSE +## ), silent = 2) + + +################################################### +### code chunk number 36: Cs33_like.kem.allow.degen +################################################### +kem.short <- MARSS(dat.short) + + +################################################### +### code chunk number 37: Cs34_like.kem200 +################################################### +kem.small <- MARSS(dat.short, model = list( + Q = "diagonal and equal", + U = "equal" +)) + + +################################################### +### code chunk number 38: Cs35_boot +################################################### +boot.params <- MARSSboot(kem, + nboot = 20, output = "parameters", sim = "parametric" +)$boot.params + + +################################################### +### code chunk number 39: Cs36_sim +################################################### +sim.data <- MARSSsimulate(kem, nsim = 2, tSteps = 100)$sim.data + + +################################################### +### code chunk number 40: Cs37_sim-fit +################################################### +kem.sim.1 <- MARSS(sim.data[, , 1]) + + +################################################### +### code chunk number 41: Cs38_sim-like +################################################### +kem.sim.2 <- kem.sim.1 +kem.sim.2$model$data <- sim.data[, , 2] +MARSSkf(kem.sim.2)$logLik + + +################################################### +### code chunk number 42: Cs39_AICb +################################################### +kem.with.AICb <- MARSSaic(kem, + output = "AICbp", + Options = list(nboot = 10, silent = TRUE) +) + +print(kem.with.AICb) + + diff --git a/inst/doc/Residuals.Rnw b/inst/doc/Residuals.Rnw new file mode 100644 index 0000000..6676564 --- /dev/null +++ b/inst/doc/Residuals.Rnw @@ -0,0 +1,804 @@ +%\VignetteIndexEntry{Residuals} +%\VignettePackage{MARSS} +\documentclass[]{article} +%set margins to 1in without fullsty + \addtolength{\oddsidemargin}{-.875in} + \addtolength{\evensidemargin}{-.875in} + \addtolength{\textwidth}{1.75in} + + \addtolength{\topmargin}{-.875in} + \addtolength{\textheight}{1.75in} +%\usepackage{fullpage} %more standardized margins + +% choose options for [] as required from the list +% in the Reference Guide, Sect. 2.2 + +\usepackage{multirow} +\usepackage[bottom]{footmisc}% places footnotes at page bottom +\usepackage[round]{natbib} + +% Math stuff +\usepackage{amsmath} % the standard math package +\usepackage{amsfonts} % the standard math package +%%%% bold maths symbol system: +\def\uupsilon{\pmb{\upsilon}} +\def\llambda{\pmb{\lambda}} +\def\bbeta{\pmb{\beta}} +\def\aalpha{\pmb{\alpha}} +\def\zzeta{\pmb{\zeta}} +\def\etaeta{\mbox{\boldmath $\eta$}} +\def\xixi{\mbox{\boldmath $\xi$}} +\def\pipi{\pmb{\pi}} +\def\ep{\mbox{\boldmath $\epsilon$}} +\def\DEL{\mbox{\boldmath $\Delta$}} +\def\PHI{\mbox{\boldmath $\Phi$}} +\def\PI{\mbox{\boldmath $\Pi$}} +\def\LAM{\mbox{\boldmath $\Lambda$}} +\def\LAMm{\mathbb{L}} +\def\GAM{\mbox{\boldmath $\Gamma$}} +\def\OMG{\mbox{\boldmath $\Omega$}} +\def\SI{\mbox{\boldmath $\Sigma$}} +\def\TH{\mbox{\boldmath $\Theta$}} +\def\UPS{\mbox{\boldmath $\Upsilon$}} +\def\XI{\mbox{\boldmath $\Xi$}} +\def\AA{\mbox{$\mathbf A$}} \def\aa{\mbox{$\mathbf a$}} +\def\Ab{\mbox{$\mathbf D$}} \def\Aa{\mbox{$\mathbf d$}} \def\Am{\PI} +\def\BB{\mbox{$\mathbf B$}} \def\bb{\mbox{$\mathbf b$}} \def\Bb{\mbox{$\mathbf J$}} \def\Ba{\mbox{$\mathbf L$}} \def\Bm{\UPS} +\def\CC{\mbox{$\mathbf C$}} \def\cc{\mbox{$\mathbf c$}} +\def\Ca{\Delta} \def\Cb{\GAM} +\def\DD{\mbox{$\mathbf D$}} \def\dd{\mbox{$\mathbf d$}} +\def\EE{\mbox{$\mathbf E$}} \def\ee{\mbox{$\mathbf e$}} +\def\E{\,\textup{\textrm{E}}} +\def\EXy{\,\textup{\textrm{E}}_{\text{{\bf XY}}}} +\def\FF{\mbox{$\mathbf F$}} \def\ff{\mbox{$\mathbf f$}} +\def\GG{\mbox{$\mathbf G$}} \def\gg{\mbox{$\mathbf g$}} +\def\HH{\mbox{$\mathbf H$}} \def\hh{\mbox{$\mathbf h$}} +\def\II{\mbox{$\mathbf I$}} \def\ii{\mbox{$\mathbf i$}} +\def\IIm{\mbox{$\mathbf I$}} +\def\JJ{\mbox{$\mathbf J$}} +\def\KK{\mbox{$\mathbf K$}} +\def\LL{\mbox{$\mathbf L$}} \def\ll{\mbox{$\mathbf l$}} +\def\MM{\mbox{$\mathbf M$}} \def\mm{\mbox{$\mathbf m$}} +\def\N{\,\textup{\textrm{N}}} +\def\MVN{\,\textup{\textrm{MVN}}} +\def\OO{\mbox{$\mathbf O$}} +\def\PP{\mbox{$\mathbf P$}} \def\pp{\mbox{$\mathbf p$}} +\def\QQ{\mbox{$\mathbf Q$}} \def\qq{\mbox{$\mathbf q$}} \def\Qb{\mbox{$\mathbf G$}} \def\Qm{\mathbb{Q}} +\def\RR{\mbox{$\mathbf R$}} \def\rr{\mbox{$\mathbf r$}} \def\Rb{\mbox{$\mathbf H$}} \def\Rm{\mathbb{R}} +\def\Ss{\mbox{$\mathbf S$}} +\def\UU{\mbox{$\mathbf U$}} \def\uu{\mbox{$\mathbf u$}} +\def\Ub{\mbox{$\mathbf C$}} \def\Ua{\mbox{$\mathbf c$}} \def\Um{\UPS} +%\def\VV{\mbox{$\mathbf V$}} \def\vv{\mbox{$\mathbf v$}} +\def\VV{\mbox{$\pmb{V}$}} \def\vv{\mbox{$\pmb{v}$}} +%\def\WW{\mbox{$\mathbf W$}} \def\ww{\mbox{$\mathbf w$}} +\def\WW{\mbox{$\pmb{W}$}} \def\ww{\mbox{$\pmb{w}$}} +%\def\XX{\mbox{$\mathbf X$}} +\def\XX{\mbox{$\pmb{X}$}} \def\xx{\mbox{$\pmb{x}$}} +%\def\xx{\mbox{$\mathbf x$}} +%\def\YY{\mbox{$\mathbf Y$}} +\def\YY{\mbox{$\pmb{Y}$}} \def\yy{\mbox{$\pmb{y}$}} +%\def\yy{\mbox{$\mathbf y$}} +\def\ZZ{\mbox{$\mathbf Z$}} \def\zz{\mbox{$\mathbf z$}} \def\Zb{\mbox{$\mathbf M$}} \def\Za{\mbox{$\mathbf N$}} \def\Zm{\XI} +\def\zer{\mbox{\boldmath $0$}} +\def\chol{\,\textup{\textrm{chol}}} +\def\vec{\,\textup{\textrm{vec}}} +\def\var{\,\textup{\textrm{var}}} +\def\cov{\,\textup{\textrm{cov}}} +\def\diag{\,\textup{\textrm{diag}}} +\def\trace{\,\textup{\textrm{trace}}} +\def\dg{\,\textup{\textrm{dg}}} +\def\hatxtT{\widetilde{\xx}_t^T} +\def\hatxtpT{\widetilde{\xx}_{t+1}^T} +\def\hatxtt{\widetilde{\xx}_t^{t}} +\def\hatxttm{\widetilde{\xx}_t^{t-1}} +\def\hatxone{\widetilde{\xx}_1} +\def\hatxzero{\widetilde{\xx}_0} +\def\hatxtmT{\widetilde{\xx}_{t-1}^T} +\def\hatxtmt1{\widetilde{\xx}_{t-1}^{t-1}} +\def\hatxtpt1{\widetilde{\xx}_{t+1}^{t-1}} +\def\hatxQtm{\widetilde{\mathbb{x}}_{t-1}} +\def\hatyt{\widetilde{\yy}_t} +\def\hatyyt{\widetilde{\mbox{$\mathbf y$}\mbox{$\mathbf y$}^\top}_t} +\def\hatyone{\widetilde{\yy}_1} +\def\hatOt{\widetilde{\OO}_t} +\def\hatWt{\widehat{\WW}_t} +\def\hatWtp{\widehat{\WW}_{t+1}} +\def\hatwt{\widehat{\ww}_t} +\def\hatwtp{\widehat{\ww}_{t+1}} +\def\checkWt{\overline{\WW}_{t}} +\def\checkWtp{\overline{\WW}_{t+1}} +\def\checkwt{\overline{\ww}_t} +\def\checkwtp{\overline{\ww}_{t+1}} +\def\hatYXt{\widetilde{\mbox{$\yy\xx$}}_t} +\def\hatXYt{\widetilde{\mbox{$\xx\yy$}}_t} +\def\hatYXttm{\widetilde{\mbox{$\yy\xx$}}_{t,t-1}} +\def\hatPt{\widetilde{\PP}_t} +\def\hatPtm{\widetilde{\PP}_{t-1}} +\def\hatPQtm{\widetilde{\mathbb{P}}_{t-1}} +\def\hatPttm{\widetilde{\PP}_{t,t-1}} +\def\hatPQttm{\widetilde{\mathbb{P}}_{t,t-1}} +\def\hatPtmt{\widetilde{\PP}_{t-1,t}} +\def\hatVt{\widehat{\VV}_t} +\def\hatvt{\widehat{\vv}_t} +\def\checkvt{\overline{\vv}_t} +\def\checkvtp{\overline{\vv}_{t+1}} +\def\checkVtp{\overline{\VV}_{t+1}} +\def\checkVt{\overline{\VV}_t} +\def\dotvt{\dot{\vv}_t} +\def\dotvtp{\dot{\vv}_{t+1}} +\def\dotVtp{\dot{\VV}_{t+1}} +\def\dotVt{\dot{\VV}_t} +\def\hatVtT{\widetilde{\VV}_t^T} +\def\hatVttm{\widetilde{\VV}_t^{t-1}} +\def\hatVtt{\widetilde{\VV}_t^{t}} +\def\hatVtmT{\widetilde{\VV}_{t-1}^T} +\def\hatVtmt1{\widetilde{\VV}_{t-1}^{t-1}} +\def\hatVttmT{\widetilde{\VV}_{t,t-1}^T} +\def\hatVtmtT{\widetilde{\VV}_{t-1,t}^T} +\def\hatVttmt1{\widetilde{\VV}_{t,t-1}^{t-1}} +\def\hatVtpT{\widetilde{\VV}_{t+1}^T} +\def\hatVttpT{\widetilde{\VV}_{t,t+1}^T} +\def\hatVttpt1{\widetilde{\VV}_{t,t+1}^{t-1}} +\def\hatVtptT{\widetilde{\VV}_{t+1,t}^T} +\def\hatVtptt1{\widetilde{\VV}_{t+1,t}^{t-1}} +\def\hatUtT{\widetilde{\UU}_t^T} +\def\hatUtt1{\widetilde{\UU}_t^{t-1}} +\def\hatStT{\widetilde{\Ss}_t^T} +\def\hatSttm{\widetilde{\Ss}_t^{t-1}} +\def\hatStt{\widetilde{\Ss}_t^{t}} +\def\hatSttmT{\widetilde{\Ss}_{t,t-1}^T} +\def\hatSttmt1{\widetilde{\Ss}_{t,t-1}^{t-1}} +\def\hatSttpT{\widetilde{\Ss}_{t,t+1}^T} +\def\hatSttpt1{\widetilde{\Ss}_{t,t+1}^{t-1}} +\def\hatBmt{\widetilde{\Bm}_t} +\def\hatCat{\widetilde{\Ca}_t} +\def\hatCbt{\widetilde{\Cb}_t} +\def\hatZmt{\widetilde{\Zm}_t} +\def\YYr{\dot{\mbox{$\pmb{Y}$}}} +\def\yyr{\dot{\mbox{$\pmb{y}$}}} +\def\aar{\dot{\mbox{$\mathbf a$}}} +\def\ZZr{\dot{\mbox{$\mathbf Z$}}} +\def\RRr{\dot{\mbox{$\mathbf R$}}} +\def\IR{\nabla} +\usepackage[round]{natbib} % to get references that are like in ecology papers +% \citet{} for inline citation name (year); \citep for citation in parens (name year) + +%allow lines in matrix +\makeatletter +\renewcommand*\env@matrix[1][*\c@MaxMatrixCols c]{% + \hskip -\arraycolsep + \let\@ifnextchar\new@ifnextchar + \array{#1}} +\makeatother +\setcounter{tocdepth}{1} %no subsections in toc + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +\SweaveOpts{concordance=TRUE} +\author{E. E. Holmes\footnote{Northwest Fisheries Science Center, NOAA Fisheries, Seattle, WA 98112, + eli.holmes@noaa.gov, http://faculty.washington.edu/eeholmes}} +\title{Computation of Standardized Residuals for MARSS Models} +\date{original 31 Oct 2014 \\ +\small{\emph{added normalization calculations, 20 Oct 2020}}} +\maketitle +\begin{abstract} +This report walks through a derivation of the variance-covariance matrix for the joint conditional model and state residuals for multivariate autoregressive Gaussian state-space (MARSS) models. The bulk of the report focuses on `smoothations' residuals \citep{Harveyetal1998}, which are the residuals conditioned on all the data $t=1$ to $T$. The final part of the report covers `innovations' residuals, which are residuals conditioned on the data $t=1$ to $t-1$. + +The MARSS model can be written: $\xx_t=\BB\xx_{t-1}+\uu+\ww_t$, $\yy_t=\ZZ\xx_t+\zz+\vv_t$, where $\ww_t$ and $\vv_t$ are independent multivariate Gaussian error-terms with variance-covariance matrices $\QQ_t$ and $\RR_t$ respectively. The joint conditional residuals are the $\ww_t$ and $\vv_t$ conditioned on the observed data, which may be incomplete (missing values). Harvey, Koopman and Penzer (1998) show a recursive algorithm for the smoothation residuals (residuals conditioned on all the data). I show an alternate algorithm to compute these residuals using the conditional variances of the states and the conditional covariance between unobserved data and states. This allows one to compute the variance of un-observed smoothation residuals (residuals associated with missing or left-out data), which is needed for leave-one-out cross-validation tests using smoothation residuals. I show how to modify the Harvey et al. algorithm in the case of missing values and how to modify it to return the non-normalized conditional residuals. +\end{abstract} +Keywords: Time-series analysis, Kalman filter, residuals, maximum-likelihood, vector autoregressive model, dynamic linear model, parameter estimation, state-space +\vfill +{\noindent \small citation: Holmes, E. E. 2014. Computation of standardized residuals for (MARSS) models. Technical Report. arXiv:1411.0045 } + \newpage + +\section{Overview of MARSS residuals} + +This report discusses the computation of the variance of the conditional model and state residuals for MARSS models of the form: +\begin{equation}\label{eq:residsMARSS} +\begin{gathered} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \vv_t, \text{ where } \VV_t \sim \MVN(0,\RR_t)\\ +\XX_0 \sim \MVN(\xixi,\LAM) \text{ or } \xx_0 = \pipi . +\end{gathered} +\end{equation} +The state and model residuals are respectively +\begin{equation}\label{eq:resids} +\begin{gathered} +\ww_t = \xx_t - \BB_t\xx_{t-1} - \uu_t\\ +\vv_t = \yy_t - \ZZ_t\xx_t - \aa_t . +\end{gathered} +\end{equation} +The model (and state) residuals are a random variables since $\yy_t$ and $\xx_t$ are drawn from the joint multivariate distribution of $\YY_t$ and $\XX_t$ defined by the MARSS equations (Equation \ref{eq:residsMARSS}). +The unconditional\footnote{meaning not conditioning on any particular set of observed data but rather taking the expectation across all possible values of $\yy_t$ and $\xx_t$.} variance of the model residuals is +\begin{equation}\label{eq:unconditiondistofVt} +\var_{XY}[\VV_t] = \var_{XY}[\YY_t - (\ZZ_t \XX_t + \aa_t)] = \RR_t\\ +\end{equation} +based on the distribution of $\VV_t$ in Equation \ref{eq:residsMARSS}. $\var_{XY}$ indicates that the integration is over the joint unconditional distribution of $\XX$ and $\YY$. + +Once we have data, $\RR_t$ is not the variance-covariance matrix of our model residuals because our residuals are now conditioned\footnote{`conditioned' means that the probability distribution of the residual has changed. The distribution is now the distribution given that $\YY=\yy$, say. Expectations and variances $\var[ ]$ are integrals over the value that a random variable might take multiplied by the probability of that value. When presenting an `expectation', the probability distribution is normally implicit but for derivations involving conditional expectations, it is important to be explicit about the distribution that is being integrated over.} on a set of observed data. There are two types of conditional model residuals used in MARSS analyses: innovations and smoothations. Innovations are the model residuals at time $t$ using the expected value of $\XX_t$ conditioned on the data from 1 to $t-1$. Smoothations are the model residuals using the expected value of $\XX_t$ conditioned on all the data, $t=1$ to $T$. Smoothations are used in computing standardized residuals for outlier and structural break detection \citep{HarveyKoopman1992, Harveyetal1998, deJongPenzer1998, CommandeurKoopman2007}. + +It should be noted that all the calculations discussed here are conditioned on the MARSS parameters: $\BB$, $\QQ$, $\UU$, $\RR$, $\ZZ$ and $\AA$. These are treated as known. This is different than standard discussions of residual distributions for linear models where the uncertainty in the model parameters enters into the calculations (as it enters into the calculation of the influence of $\yy$ on the expected (or fitted) value of $\yy$). In the calculations in this report, $\yy$ does not affect the estimates of the parameters (which are fixed, perhaps at estimated values) but does affect the expected value of $\YY_t$ by affecting the estimate of the expected value and variance of $\XX_t$. + +\section{Distribution of MARSS smoothation residuals}\label{sec:smoothations} + +This section discusses computation of the variance of the model and state residuals conditioned on all the data from $t=1$ to $T$. These MARSS residuals are often used for outlier detection and shock detection, and in this case you only need the distribution of the model residuals for the observed values. However if you wanted to do a leave-one-out cross-validation, you would need to know the distribution of the residuals for data points you left out (treated as unobserved). The equations in this report give you the former and the latter, while the algorithm by \citet{Harveyetal1998} gives only the former. These equations for residuals for `left-out` data are different that other (typical) discussions of state-space cross-validation \citep{deJong1988} in that they are conditioned on all the data (smoothations residuals) rather than conditioned on data up to $t-1$ (innovations residuals). + +\subsection{Notation and relations} + +Throughout, I follow the convention that capital letters are random variables and small letters are a realization from the random variable. This only applies to random variables; parameters are not random variables\footnote{in a frequentist framework}. Parameters are shown in Roman font while while random variables are bold slanted font. Parameters written as capital letters are matrices, while parameters written in small letters are strictly column matrices. + +In this report, the distribution over which the integration is done in an expectation or variance is given by the subscript; e.g., $\E_A[f(A)]$ indicates an unconditional expectation over the distribution of $A$ without conditioning on another random variable while $\E_{A|b}[f(A)|b]$ would indicate an expectation over the distribution of $A$ conditioned on $B=b$; presumably $A$ and $B$ are not independent otherwise $B=b$ would have no effect on $A$. $\E_{A|b}[f(A)|b]$ is a fixed value, not random. It is the expected value when $B=b$. In contrast, $\E_{A|B}[f(A)|B]$ denotes the random variable over all the possible $\E_{A|b}[f(A)|b]$ given all the possible $b$ values that $B$ might take. The variance of $\E_{A|B}[f(A)|B]$ is the variance of this random variable. The variance of $\E_{A|b}[f(A)|b]$ in contrast is 0 since it is a fixed value. We will often be working with the random variables, $\E_{A|B}[f(A)|B]$ or $\var_{A|B}[f(A)|B]$, inside an expectation or variance: such as $\var_B[\E_{A|B}[f(A)|B]]$. + +\subsubsection{Law of total variance} + +The ``law of total variance'' can be written +\begin{equation}\label{eq:lawoftotvar} +\var_A[A] = \var_B[\E_{A|B}[A|B]] + \E_B[\var_{A|B}[A|B]] . +\end{equation} +The subscripts on the inner expectations make it explicit that the expectations are being taken over the conditional distributions. $\var_{A|B}[A|B]$ and $\E_{A|B}[A|B]$ are random variables because the $B$ in the conditional is a random variable. We take the expectation or variance with $B$ fixed at one value, $b$, but $B$ can take other values of $b$ also. + +Going forward, I will write the law or total variance more succinctly as +\begin{equation} +\var[A] = \var_B[\E[A|B]] + \E_B[\var[A|B]] . +\end{equation} +I leave off the subscript on the inner conditional expectation or variance. Just remember that when you see a conditional in an expectation or variance, the integration is over over the conditional distribution of $A$ conditioned on $B=b$. Even when you see $A|B$, the conditioning is on $B=b$ and the $B$ indicates that this is a random variable because $B$ can take different $b$ values. When computing $\var_B[\E_{A|B}[A|B]]$, we will typically compute $\E_{A|b}[A|b]$ and then compute (or infer) the variance or expectation of that over all possible values of $b$. + +The law of total variance will appear in this report in the following form: +\begin{equation} +\var_{XY}[f(\YY,\XX)] = \var_{Y^{(1)}}[\E_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] + \E_{Y^{(1)}}[\var_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] , +\end{equation} +where $f(\YY_t,\XX_t)$ is some function of $\XX_t$ and $\YY_t$ and $\YY^{(1)}$ is the observed data from $t=1$ to $T$ ($\YY^{(2)}$ is the unobserved data). + + +\subsection{Model residuals conditioned on all the data} + +Define the smoothations $\hatvt$ as: +\begin{equation}\label{eq:vtT} +\hatvt = \yy_t - \ZZ_t\hatxtT - \aa_t, +\end{equation} +where $\hatxtT$ is $\E[\XX_t|\yy^{(1)}]$. The smoothation is different from $\vv_t$ because it uses $\hatxtT$ not $\xx_t$; $\xx_t$ is not known, and $\hatxtT$ is its estimate. $\hatxtT$ is output by the Kalman smoother. $\yy^{(1)}$ means all the observed data from $t=1$ to $T$. $\yy^{(1)}$ is a sample from the random variable $\YY^{(1)}$. The unobserved $\yy$ will be termed $\yy^{(2)}$ and is a sample from the random variable $\YY^{(2)}$. When $\YY$ appears without a superscript, it means both $\YY^{(1)}$ and $\YY^{(2)}$ together. Similarly $\yy$ means both $\yy^{(1)}$ and $\yy^{(2)}$ together---the observed data that we use to estimate $\hatxtT$ and the unobserved data that we do not use and may or may not know. $\hatvt$ exists for both $\yy^{(1)}$ and $\yy^{(2)}$, though we might not know $\yy^{(2)}$ and thus might not know its corresponding $\hatvt$. In some cases, however, we do know $\yy^{(2)}$; they are data that we left out of our model fitting, in say a k-fold or leave-one-out cross-validation. + +$\hatvt$ is a sample from the random variable $\hatVt$. We want to compute the mean and variance of this random variable over all possibles values that $\XX_t$ and $\YY_t$ might take. The mean of $\hatVt$ is 0 and we are concerned only with computing the variance: +\begin{equation}\label{eq:var.vtT} +\var[\hatVt] = \var_{XY}[\YY_t - \ZZ_t\E[\XX_t|\YY^{(1)}] - \aa_t] . +\end{equation} +Notice we have an unconditional variance over ${\XX,\YY}$ on the outside and a conditional expectation over a specific value of $\YY^{(1)}$ on the inside (in the $\E[\;]$). + +From the law of total variance (Equation \ref{eq:lawoftotvar}), we can write the variance of the model residuals as +\begin{equation}\label{eq:varvvtgeneral} +\var[\hatVt] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] . +\end{equation} + +\subsubsection{First term on right hand side of Equation \ref{eq:varvvtgeneral}} + +The random variable inside the $\var[\;]$ in the first term is +\begin{equation}\label{eq:first.term.rhs.varvvtgeneral} +\E[\hatVt|\YY^{(1)}]= \E[(\YY_t + \ZZ_t \E[\XX_t|\YY^{(1)}] + \aa_t)|\YY^{(1)}] . +\end{equation} +Let's consider this for a specific value $\YY^{(1)}=\yy^{(1)}$. +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[(\YY_t + \ZZ_t \E[\XX_t|\yy^{(1)}] + \aa_t)|\yy^{(1)}] = +\E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +$\E[\XX_t|\yy^{(1)}]$ is a fixed value, and the expected value of a fixed value is itself. So $\E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=\E[\XX_t|\yy^{(1)}]$. +Thus, +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\XX_t|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +We can move the conditional out and write +\begin{equation} +\E[\hatVt|\yy^{(1)}]= \E[(\YY_t + \ZZ_t \XX_t + \aa_t)|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]. +\end{equation} +The right side is $\E[\VV_t|\yy^{(1)}]$, no `hat' on the $\VV_t$, and this applies for all $\yy^{(1)}$. This means that the first term in Equation \ref{eq:varvvtgeneral} can be written with no hat on $\VV$: +\begin{equation}\label{eq:no.hat.on.V} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] . +\end{equation} +If $\YY_t$ were completely observed (no missing values), this would be zero since $\E[\VV_t|\yy]$ would be a fixed value in that case. But $\YY_t$ is not assumed to be fully observed; it may have $\YY^{(2)}_t$ which is unobserved, or more precisely, not included in the estimation of $VV_t$ for whatever reason (`unknown" because it was unobserved being one reason). The derivation of $\E[\YY_t|\yy^{(1)}]$ is given in \citet{Holmes2010}\footnote{$\E[\YY^{(2)}_t|\yy^{(1)}]$ is not $\ZZ_t \hatxtT + \aa_t$ in general since $\YY^{(2)}_t$ and $\YY^{(1)}_t$ may be correlated through $\RR$ in addition to being correlated through $\hatxtT$}. + +Using the law of total variance, we can re-write $\var[\VV_t]$ as: +\begin{equation}\label{eq:varianceVt} +\var[\VV_t] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:varianceVt}, we can solve for $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]]$: +\begin{equation}\label{eq:var.E.vtT} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \var[\VV_t] - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:unconditiondistofVt}, we know that $\var[\VV_t]=\RR_t$ (this is the unconditional variance). Thus, +\begin{equation}\label{eq:var.E.vtT.R} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \RR_t - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} + +The second term in Equation \ref{eq:var.E.vtT.R} to the right of the equal sign and inside the expectation is $\var[\VV_t|\YY^{(1)}]$. This is the variance of $\VV_t$ with $\YY^{(1)}$ held at a specific fixed $\yy^{(1)}$. The variability in $\var[\VV_t|\yy^{(1)}]$ (notice $\yy^{(1)}$ not $\YY^{(1)}$ now) comes from $\XX_t$ and $\YY^{(2)}$ which are random variables. Let's compute this variance for a specific $\yy^{(1)}$ value. +\begin{equation}\label{eq:varvtcondy} +\var[\VV_t|\yy^{(1)}] = \var[ \YY_t - \ZZ_t\XX_t-\aa_t | \yy^{(1)} ]. +\end{equation} +Notice that there is no $\E$ (expectation) on the $\XX_t$; this is $\VV_t$ not $\hatVt$. $\aa_t$ is a fixed value and can be dropped. + +Equation \ref{eq:varvtcondy} can be written as\footnote{$\var(A+B)=\var(A)+\var(B)+\cov(A,B)+\cov(B,A)$}: +\begin{equation}\label{eq:var.Vt.yy} +\begin{split} +\var[\VV_t|\yy^{(1)}] &= \var[ \YY_t - \ZZ_t\XX_t | \yy^{(1)} ]\\ +&=\var[ - \ZZ_t\XX_t | \yy^{(1)} ] + \var[ \YY_t|\yy^{(1)}] + \cov[ \YY_t, - \ZZ_t\XX_t | \yy^{(1)} ] + \cov[ - \ZZ_t\XX_t, \YY_t | \yy^{(1)} ]\\ +&=\ZZ_t \hatVtT \ZZ_t^\top + \hatUtT - \hatStT\ZZ_t^\top - \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +$\hatVtT = \var[ \XX_t | \yy^{(1)} ]$ and is output by the Kalman smoother. $\hatUtT=\var[\YY_t|\yy^{(1)}]$ and $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$. The equations for these are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package\footnote{$\hatUtT$ is \texttt{OtT - tcrossprod(ytT)} in the \texttt{MARSShatyt()} output.}. If there were no missing data, i.e., if $\yy^{(1)}=\yy$, then $\hatUtT$ and $\hatStT$ would be zero because $\YY_t$ would be fixed at $\yy_t$. This would reduce Equation \ref{eq:var.Vt.yy} to $\ZZ_t \hatVtT \ZZ_t^\top$. But we are concerned with the case where there are missing values. Those missing values need not be for all $t$. That is, there may be some observed $y$ at time t and some missing $y$. $\yy_t$ is multivariate. + +From Equation \ref{eq:var.Vt.yy}, we know $\var[\VV_t|\yy^{(1)}]$ for a specific $\yy^{(1)}$. We want $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$ which is its expected value over all possible values of $\yy^{(1)}$. $\VV_t$ is a multivariate normal random variable with two random variables $\YY^{(1)}$ and $\YY^{(2)}$. The conditional variance of a multivariate Normal does not depend on the value that you are conditioning on. Let the $\AA$ be a N-dimensional multivariate Normal random variable partitioned into $\AA_1$ and $\AA_2$ with variance-covariance matrix $\Sigma = \begin{bmatrix} +\Sigma_1 & \Sigma_{12} \\ +\Sigma_21 & \Sigma_{2} +\end{bmatrix}$. The variance-covariance matrix of $\AA$ conditioned on $\AA_1=\aa$ is $\Sigma = \begin{bmatrix} +0 & 0 \\ +0 & \Sigma_2 - \Sigma_{12}\Sigma_{1}\Sigma_{21} +\end{bmatrix}$. Notice that $\aa$ does not appear in the conditional variance matrix. This means that $\var[\VV_t|\yy^{(1)}]$ does not depend on $\yy^{(1)}$. Its variance only depends on the MARSS model parameters\footnote{This also implies that $\hatVtT$, $\hatUtT$ and $\hatStT$ do not depend on $\yy^{(1)}$, which is rather counter-intuitive since $\yy^{(1)}$ is part of the algorithm (Kalman filter and smoother) used to compute these values. The value of $\yy^{(1)}$ affects the expected values of $\XX_t$ but only its presence\ (versus absence) affects $\XX_t$'s conditional variance.}. + +Because $\var[\VV_t|\yy^{(1)}]$ only depends on the MARSS parameters values, $\QQ$, $\BB$, $\RR$, etc., the second term in Equation \ref{eq:var.E.vtT}, $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$, is equal to $\var[\VV_t|\yy^{(1)}]$ (Equation \ref{eq:var.Vt.yy}). Putting this into Equation \ref{eq:var.E.vtT.R}, we have +\begin{equation}\label{eq:conditionalvtfinala} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \RR_t - \var[\VV_t|\yy^{(1)}] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} +Since $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]]$ (Equation \ref{eq:no.hat.on.V}), this means that the first term in Equation \ref{eq:varvvtgeneral} is +\begin{equation}\label{eq:conditionalvtfinal} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} + +\subsubsection{Second term on right hand side of Equation \ref{eq:varvvtgeneral}} + +Consider the second term in Equation \ref{eq:varvvtgeneral}. This term is +\begin{equation}\label{eq:second.term.rhs.9} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \E_{Y^{(1)}}[\var[(\YY_t-\ZZ_t\E[\XX_t|\YY^{(1)}]-\aa_t)|\YY^{(1)}]] . +\end{equation} +The middle term is: +\begin{equation} +\E_{Y^{(1)}}[\var[\E[\XX_t|\YY^{(1)}]|\YY^{(1)}]]. +\end{equation} +Let's solve the inner part for a specific $\YY^{(1)}=\yy^{(1)}$. $\E[\XX_t|\yy^{(1)}]$ is a fixed value. Thus $\var[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=0$ since the variance of a fixed value is 0. This is true for all $\yy^{(1)}$ so the middle term reduces to 0. $\aa_t$ is also fixed and its variance is also 0. The covariance between a random variable and a fixed value is 0\footnote{$\var[A+B] = \var[A]+\var[B]+\cov[A,B]$}. Thus for a specific $\YY^{(1)}=\yy^{(1)}$, the inside of the right hand side expectation reduces to $\var[\YY_t|\yy^{(1)}]$ which is $\hatUtT$. As noted in the previous section, $\hatUtT$ is only a function of the MARSS parameters; it is not a function of $\yy^{(1)}$ and $\var[\YY_t|\yy^{(1)}]=\hatUtT$ for all $\yy^{(1)}$. Thus the second term in Equation \ref{eq:varvvtgeneral} is simply $\hatUtT$: +\begin{equation}\label{eq:second.term.rhs.9final} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \var[\hatVt|\yy^{(1)}] = \hatUtT . +\end{equation} + +\subsubsection{Putting together the first and second terms} + +We can now put the first and second terms in Equation \ref{eq:varvvtgeneral} together (Equations \ref{eq:conditionalvtfinal} and \ref{eq:second.term.rhs.9final}) and write out the variance of the model residuals: +\begin{equation}\label{eq:first.and.secons.vvtgeneral} +\begin{split} +\var[\hatVt] &= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top + \hatUtT\\ +&= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t - \ZZ_t \hatVtT \ZZ_t^\top$ if $\yy_t$ has no missing values since $\hatStT = 0$ in this case. If $\yy_t$ is all missing values, $\hatStT = \ZZ_t \hatVtT$ because +\begin{equation}\label{eq:cov.Yt.Xt.no.missing.vals} +\cov[\YY_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t + \aa_t + \VV_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \cov[\XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \hatVtT . +\end{equation} +The reduction in Equation \ref{eq:cov.Yt.Xt.no.missing.vals} occurs because $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent in the form of MARSS model used in this report (Equation \ref{eq:residsMARSS})\footnote{This is not the case for the \citet{Harveyetal1998} form of the MARSS model where $\VV_t$ and $\WW_t$ are allowed to be correlated.}. Thus when $\yy_t$ is all missing values, Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t + \ZZ_t \hatVtT \ZZ_t^\top$ . The behavior if $\yy_t$ has some missing and some not missing values depends on whether $\RR_t$ is a diagonal matrix or not, i.e., if the $\yy_t^{(1)}$ and $\yy_t^{(2)}$ are correlated. + +\subsection{State residuals conditioned on the data} + +The state residuals are $\xx_t - (\BB_t \xx_{t-1} + \uu_t)=\ww_t$. The unconditional expected value of the state residuals is $\E[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \E[\WW_t] = 0$ and the unconditional variance of the state residuals is +\begin{equation} +\var[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \var[\WW_t] = \QQ_t +\end{equation} +based on the definition of $\WW_t$ in Equation \ref{eq:residsMARSS}. +The conditional state residuals (conditioned on the data from $t=1$ to $t=T$) are defined as +\begin{equation} +\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t. +\end{equation} +where $\hatxtT = E[\XX_t|\yy^{(1)}]$ and $\hatxtmT = E[\XX_{t-1}|\yy^{(1)}]$. $\hatwt$ is a sample from the random variable $\hatWt$; random over different possible data sets. The expected value of $\hatWt$ is 0, and we are concerned with computing its variance. + +We can write the variance of $\WW_t$ (no hat) using the law of total variance. +\begin{equation}\label{eq:Wlawoftotvar} +\var[\WW_t] = \var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Notice that +\begin{equation} +\E[\WW_t|\yy^{(1)}] = \E[(\XX_t - \BB_t \XX_{t-1} - \uu_t)|\yy^{(1)}] = \hatxtT - \BB_t \hatxtmT - \uu_t = \E[\hatWt|\yy^{(1)}] = \hatwt . +\end{equation} +This is true for all $\yy^{(1)}$, thus $\E[\WW_t|\YY^{(1)}]$ is $\hatWt$, and $\var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] = \var[\hatWt]$. Equation \ref{eq:Wlawoftotvar} can thus be written +\begin{equation} +\var[\WW_t] = \var[\hatWt] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Solve for $\var[\hatWt]$: +\begin{equation}\label{eq:varwwt} +\var[\hatWt] = \var[\WW_t] - \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]. +\end{equation} + +The variance in the expectation on the far right for a specific $\YY^{(1)}=\yy^{(1)}$ is +\begin{equation} +\var[\WW_t|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}-\uu_t) | \yy^{(1)} ] . +\end{equation} +$\uu_t$ is not a random variable and can be dropped. Thus\footnote{$\var[A-B]=\var[A]+\var[B]+\cov[A,-B]+\cov[-B,A]$. Be careful about the signs in this case as they are a little non-intuitive.}, +\begin{equation}\label{eq:var.W.cond.y1} +\begin{split} +\var[\WW_t&|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}) | \yy^{(1)} ] \\ +& = \var[ \XX_t | \yy^{(1)} ] + \var[\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[\XX_t, -\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[ -\BB_t\XX_{t-1}, \XX_t | \yy^{(1)} ]\\ +& = \hatVtT + \BB_t \hatVtmT \BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{split} +\end{equation} +Again this is conditional multivariate normal variance, and its value does not depend on the value, $\yy^{(1)}$ that we are conditioning on. It depends only on the parameters values, $\QQ$, $\BB$, $\RR$, etc., and is the same for all values of $\yy^{(1)}$. So $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \var[\WW_t|\yy^{(1)}]$, using any value of $\yy^{(1)}$. Thus +\begin{equation}\label{eq:E.var.Wt.yt} +\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \hatVtT + \BB_t\hatVtmT\BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{equation} + +Putting $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]$ from Equation \ref{eq:E.var.Wt.yt} and $\var[\WW_t]=\QQ_t$ into Equation \ref{eq:varwwt}, the variance of the conditional state residuals is +\begin{equation} +\var[\hatWt] = \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT . +\end{equation} + +\subsection{Covariance of the conditional model and state residuals} + +The unconditional model and state residuals, $\VV_t$ and $\WW_t$, are independent by definition\footnote{This independence is specific to the way the MARSS model for this report (Equation \ref{eq:residsMARSS}). It is possible for the model and state residuals to covary. In the MARSS model written in \citet{Harveyetal1998} form, they do covary.} (in Equation \ref{eq:residsMARSS}), i.e., $\cov[\VV_t,\WW_t]=0$. However the conditional model and state residuals, $\cov[\hatVt,\hatWt]$, are not independent since both depend on $\yy^{(1)}$. +Using the law of total covariance, we can write +\begin{equation}\label{eq:covhatVtWt1} +\cov[\hatVt,\hatWt] = +\cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]] + \E_{Y^{(1)}}[\cov[\hatVt, \hatWt|\YY^{(1)}]] . +\end{equation} + +For a specific value of $\YY^{(1)}=\yy^{(1)}$, the covariance in the second term on the right is $\cov[\hatVt, \hatWt|\yy^{(1)}]$. Conditioned on a specific value of $\YY^{(1)}$, $\hatWt$ is a fixed value, $\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t$, and conditioned on $\yy^{(1)}$, $\hatxtT$ and $\hatxtmT$ are fixed values. $\uu_t$ is also fixed; it is a parameter. $\hatVt$ is not a fixed value because it has $\YY_t^{(2)}$ and that is a random variable. Thus $\cov[\hatVt, \hatWt|\yy^{(1)}]$ is the covariance between a random variable and a fixed variable and thus the covariance is 0. This is true for all $\yy^{(1)}$. +Thus the second right-side term in Equation \ref{eq:covhatVtWt1} is zero, and the equation reduces to +\begin{equation}\label{eq:covhatVtWt3} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]]. +\end{equation} +Notice that $\E[\hatWt|\yy^{(1)}]=\E[\WW_t|\yy^{(1)}]$ and $\E[\hatVt|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]$ since +\begin{equation} +\E[\WW_t|\yy^{(1)}]= \E[\XX_t|\yy^{(1)}]-\BB_t\E[\XX_{t-1}|\yy^{(1)}] - \uu_t = \hatxtT-\BB_t\hatxtmT - \uu_t = \hatwt = \E[\hatWt|\yy^{(1)}] +\end{equation} +and +\begin{equation} +\E[\VV_t|\yy^{(1)}]= \E[\YY_t|\yy^{(1)}]-\ZZ_t\E[\XX_{t}|\yy^{(1)}] - \aa_t = \E[\YY_t|\yy^{(1)}]-\ZZ_t \hatxtT - \aa_t = \E[\hatVt|\yy^{(1)}] . +\end{equation} +Thus the right side of Equation \ref{eq:covhatVtWt3} can be written in terms of $\VV_t$ and $\WW_t$ instead of $\hatVt$ and $\hatWt$: +\begin{equation}\label{eq:covhatVtWt2} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]]. +\end{equation} + +Using the law of total covariance, we can write: +\begin{equation}\label{eq:covVtWt} +\cov[\VV_t, \WW_t] = \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] + \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] . +\end{equation} +The unconditional covariance of $\VV_t$ and $\WW_t$ is 0. Thus the left side of Equation \ref{eq:covVtWt} is 0 and we can rearrange the equation as +\begin{equation}\label{eq:covVtWt2} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] = - \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] . +\end{equation} +Combining Equation \ref{eq:covhatVtWt2} and \ref{eq:covVtWt2}, we get +\begin{equation}\label{eq:conditionalcovvtwt} +\cov[\hatVt,\hatWt] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ] , +\end{equation} +and our problem reduces to solving for the conditional covariance of the model and state residuals (right side of Equation \ref{eq:conditionalcovvtwt}). + +For a specific $\YY^{(1)}=\yy^{(1)}$, the conditional covariance $\cov[\VV_t, \WW_t|\yy^{(1)}]$ can be written out as +\begin{equation} +\cov[\VV_t, \WW_t|\yy^{(1)}] = \cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_t-\BB_t\XX_{t-1}-\uu_t|\yy^{(1)}] . +\end{equation} +$\aa_t$ and $\uu_t$ are fixed values and can be dropped. Thus\footnote{$\cov[\BB \mathbf{A},\CC \mathbf{D}]=\BB\cov[\mathbf{A},\mathbf{D}]\CC^\top$.} +\begin{equation} +\begin{split} +\cov&[\VV_t, \WW_t|\yy^{(1)}] =\cov[\YY_t-\ZZ_t\XX_t, \XX_t-\BB_t\XX_{t-1}|\yy^{(1)}] \\ +& =\cov[\YY_t,\XX_t|\yy^{(1)}] + \cov[\YY_t,-\BB_t\XX_{t-1}|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,\XX_t|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,-\BB_t\XX_{t-1}|\yy^{(1)}]\\ +& = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top , +\end{split} +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$ and $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$; the equations for $\hatStT$ and $\hatSttmT$ are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package. + +Both $\VV_t$ and $\WW_t$ are multivariate normal random variables that depend on $\YY^{(1)}$ and $\YY^{(2)}$ and the conditional covariance is not a function of the variable that we condition on (in this case $\yy^{(1)}$). The conditional covariance is only a function of the MARSS parameters\footnote{By extension, this is also the case for $\hatVtT$, $\hatVttmT$, $\hatStT$ and $\hatSttmT$ which may seem counter-intuitive, but you can show it is true by working through the Kalman filter and smoother equations starting at t=1. Or run a Kalman filter/smoother algorithm with different data and the same parameters and you will see that the variances do not change with different data.}. Thus +\begin{equation} +\E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ]= \cov[\VV_t, \WW_t|\yy^{(1)}] = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} +$\cov[\hatVt,\hatWt]$ is the negative of this (Equation \ref{eq:conditionalcovvtwt}), thus +\begin{equation} +\cov[\hatVt,\hatWt] = - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t \hatVtT - \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} + +The Harvey et al. algorithm (next section) gives the joint distribution of the model residuals at time $t$ and state residuals at time $t+1$. Using the law of total covariance as above, the covariance in this case is +\begin{equation} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] +\end{equation} +and +\begin{equation} +\begin{split} +\cov[\VV_t, \WW_{t+1}|\yy^{(1)}] & =\cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_{t+1}-\BB_{t+1}\XX_t-\uu_{t+1}|\yy^{(1)}] \\ +& =\cov[\YY_t-\ZZ_t\XX_t,\, \XX_{t+1}-\BB_{t+1}\XX_t|\yy^{(1)}] \\ +& = \hatSttpT - \hatStT\BB_{t+1}^\top - \ZZ_t\hatVttpT + \ZZ_t \hatVtT \BB_{t+1}^\top . +\end{split} +\end{equation} +Thus, +\begin{equation} +\begin{split} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] & = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] \\ +& = - \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top. +\end{split} +\end{equation} + + +\subsection{Joint distribution of the conditional residuals} + +We now can write the variance of the joint distribution of the conditional residuals. Define +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwt\end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtT - \BB_t\hatxtmT - \uu_t \end{bmatrix}. +\end{equation} +$\widehat{\varepsilon}_t$ is a sample drawn from the distribution of the random variable $\widehat{\mathcal{E}}_t$. The expected value of $\widehat{\mathcal{E}}_t$ over all possible $\yy$ is 0 and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} +\widehat{\Sigma}_t = \var[\widehat{\mathcal{E}}_t] = \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWt] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWt])^\top& + \var[\hatWt] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid1general} + \begin{bmatrix}[c|c] + \RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top+\ZZ_t(\hatStT)^\top& + - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top\\ + \rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ + (- \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top)^\top& + \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT \end{bmatrix}, +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$, $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$, $\hatVtT=\var[\XX_t|\yy^{(1)}]$, $\hatVttmT=\cov[\XX_t,\XX_{t-1}|\yy^{(1)}]$, and $\hatVtmtT=\cov[\XX_{t-1},\XX_t|\yy^{(1)}]$. This gives the variance of both `observed' model residuals (the ones associated with $\yy^{(1)}$) and the unobserved model residuals (the ones associated with $\yy^{(2)}$). +When there are no missing values in $\yy_t$, the $\hatStT$ and $\hatSttmT$ terms equal 0 and drop out. + +If the residuals are defined as in \citet{Harveyetal1998} with $\hatvt$ on top and $\hatwtp$ on the bottom instead of $\hatwt$, then +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtpT - \BB_{t+1}\hatxtT - \uu_{t+1} \end{bmatrix} +\end{equation} +and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} + \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWtp] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWtp])^\top& + \var[\hatWtp] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid2} +\begin{bmatrix}[c|c] +\RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top& +- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top \\ +\rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ +(- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top)^\top& +\QQ_{t+1} - \hatVtpT - \BB_{t+1}\hatVtT\BB_{t+1}^\top + \hatVtptT \BB_{t+1}^\top + \BB_{t+1}\hatVttpT \end{bmatrix} . +\end{equation} + + + +\section{Harvey et al. 1998 algorithm for the conditional residuals} +\citet[pgs 112-113]{Harveyetal1998} give a recursive algorithm for computing the variance of the conditional residuals when the time-varying MARSS equation is written as: +\begin{equation}\label{eq:residsMARSSHarvey} +\begin{gathered} +\xx_{t+1} = \BB_{t+1}\xx_t + \uu_{t+1} + \HH_{t+1}\epsilon_{t},\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \GG_t\epsilon_t,\\ +\mbox{ where } \epsilon_t \sim \MVN(0,\II_{m+n \times m+n}) \\ +\HH_t\HH_t^\top=\QQ_t, \GG_t\GG_t^\top=\RR_t, \text{ and } \HH_t\GG_t^\top = \cov[\WW_t, \VV_t] +\end{gathered} +\end{equation} +The $\HH_t$ and $\GG_t$ matrices specify the variance and covariance of $\WW_t$ and $\VV_t$. $\HH_t$ has $m$ rows and $m+n$ columns and $\GG_t$ has $n$ rows and $m+n$ columns. In the MARSS equation for this report (Equation \ref{eq:residsMARSS}), $\WW_t$ and $\VV_t$ are independent. To achieve this in the Harvey et al. form (Equation \ref{eq:residsMARSSHarvey}), the first $n$ columns of $\HH_t$ are all 0 and the last $m$ columns of $\GG_t$ are all zero. + +The algorithm in \citet{Harveyetal1998} gives the variance of the `normalized' residuals, the $\epsilon_t$. I have modified their algorithm so it returns the `non-normalized' residuals: +$$\varepsilon_t=\begin{bmatrix}\GG_t\epsilon_t\\ \HH_{t+1}\epsilon_t\end{bmatrix}=\begin{bmatrix}\vv_t\\ \ww_{t+1} \end{bmatrix}.$$ + +The Harvey et al. algorithm is a backwards recursion using the following output from the Kalman filter: the one-step ahead prediction covariance $\FF_t$, the Kalman gain $\KK_t$, $\hatxttm=\E[\XX_t|\yy^{(1),1:{t-1}}]$ and $\hatVttm=\var[\XX_t|\yy^{(1),1:{t-1}}]$. In the \{MARSS\} package, these are output from \texttt{MARSSkfss()} in \texttt{Sigma}, \texttt{Kt}, \texttt{xtt1} and \texttt{Vtt1}. + +\subsection{Algorithm for the non-normalized residuals} + +Start from $t=T$ and work backwards to $t=1$. At time $T$, $r_T=0_{1 \times m}$ and $N_T=0_{m \times m}$. $\BB_{t+1}$ and $\QQ_{t+1}$ can be set to NA or 0. They will not appear in the algorithm at time $T$ since $r_T=0$ and $N_T=0$. Note that the $\ww$ residual and its associated variance and covariance with $\vv$ at time $T$ is NA since this residual would be for $\xx_T$ to $\xx_{T+1}$. + +% algorithm with \GG_t and \HH_t +% \begin{equation}\label{eq:Harveyalgo} +% \begin{gathered} +% \FF_t = \ZZ_t\hatVt\ZZ_t^\top+\RR_t\\ +% G_t= \GG_t\QQ_t\GG_t^\top, \mbox{ }H_t = \HH_t\RR_t\HH_t^\top, \mbox{ } K_t = \BB_t\KK^{*}_t\\ +% L_t = \BB_t - K_t\ZZ_t, \mbox{ } J_t= H_t - K_t G_t, \mbox{ } u_t = \FF_t^{-1} - K_t^\top r_t\\ +% r_{t-1} = \ZZ_t^\top u_t + \BB_t^\top r_t, \mbox{ } N_{t-1} = K_t^\top N_t K_t + L_t^\top N_t L_t +% \end{gathered} +% \end{equation} + +\begin{equation}\label{eq:Harveyalgo} +\begin{gathered} +\QQ^\prime_{t+1}=\begin{bmatrix}0_{m \times n}&\QQ_{t+1}\end{bmatrix}, \mbox{ } \RR^\prime_t=\begin{bmatrix}\RR_t^* & 0_{n \times m}\end{bmatrix}\\ +\FF_t = \ZZ_t^*\hatVttm{\ZZ_t^*}^\top+\RR_t^* , \,\, n \times n \\ +K_t = \BB_{t+1}\KK_t = \BB_{t+1} \hatVttm{\ZZ_t^*}^\top \FF_t^{-1} , \,\, m \times n \\ +L_t = \BB_{t+1} - K_t\ZZ_t^* , \,\, m \times m \\ +J_t= \QQ^\prime_{t+1} - K_t \RR^\prime_t , \,\, m \times (n+m) \\ +v_t = \yy_t^* - \ZZ_t\hatxttm - \aa_t , \,\, n \times 1 \\ +u_t = \FF_t^{-1} v_t - K_t^\top r_t , \,\, n \times 1 \\ +r_{t-1} = {\ZZ_t^*}^\top u_t + \BB_{t+1}^\top r_t , \,\, m \times 1 \\ +N_{t-1} = {\ZZ_t^*}^\top \FF_t^{-1} \ZZ_t^* + L_t^\top N_t L_t , \,\, m \times m . +\end{gathered} +\end{equation} +$\yy_t^*$ is the observed data at time $t$ with the $i$-th rows set to 0 if the $i$-th $y$ is missing. +Bolded terms are the same as in Equation \ref{eq:residsMARSSHarvey} (and are output by \texttt{MARSSkfss()}). Unbolded terms are terms used in \citet{Harveyetal1998}. The * on $\ZZ_t$ and $\RR_t$, indicates that they are the missing value modified versions discussed in \citet[section 6.4]{ShumwayStoffer2006} and \citet{Holmes2010}: to construct $\ZZ_t^*$ and $\RR_t^*$, the rows of $\ZZ_t$ corresponding to missing rows of $\yy_t$ are set to zero and the $(i,j)$ and $(j,i)$ terms of $\RR_t$ corresponding the missing rows of $\yy_t$ are set to zero. For the latter, this means if the $i$-th row of $\yy_t$ is missing, then then the $i$-th row and column (including the value on the diagonal) in $\RR_t$ are set to 0. Notice that $\FF_t$ will have 0's on the diagonal if there are missing values. A modified inverse of $\FF_t$ is used: any 0's on the diagonal of $\FF_t$ are replaced with 1, the inverse is taken, and 1s on diagonals is replaced back with 0s. + +The residuals \citep[eqn 24]{Harveyetal1998} are +\begin{equation}\label{eq:Harveyresiduals} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} =({\RR^\prime_t})^\top u_t + ({\QQ^\prime_{t+1}})^\top r_t +\end{equation} +The expected value of $\widehat{\mathcal{E}}_t$ is 0 and its variance is +\begin{equation}\label{eq:Harveyvariance} +\widehat{\Sigma]}_t = \var[\widehat{\mathcal{E}}_t] ={\RR^\prime_t}^\top \FF_t^{-1} \RR^\prime_t + J_t^\top N_t J_t . +\end{equation} +These $\widehat{\varepsilon}_t$ and $\widehat{\Sigma]}_t$ are for both the non-missing and missing $\yy_t$. This is a modification to the \citet{Harveyetal1998} algorithm which does not give the variance for missing $\yy$. + +\subsection{Difference in notation} + +In Equation 20 in \citet{Harveyetal1998}, their $T_t$ is my $\BB_{t+1}$ and their $H_t H_t^\top$ is my $\QQ_{t+1}$. Notice the difference in the time indexing. My time indexing on $\BB$ and $\QQ$ matches the left $\xx$ while in theirs, $T$ and $H$ indexing matches the right $\xx$. Thus in my implementation of their algorithm \citep[eqns. 21-24]{Harveyetal1998}, $\BB_{t+1}$ appears in place of $T_t$ and $\QQ_{t+1}$ appears in place of $H_t$. See comments below on normalization and the difference between $\QQ$ and $H$. + +\citet[eqns. 19, 20]{Harveyetal1998} use $G_t$ to refer to the $\chol(\RR_t)^\top$ (non-zero part of the $n \times n+m$ matrix) and $H_t$ to refer to $\chol(\QQ_t)^\top$. I have replaced these with $\RR_t^\prime$ and $\QQ_t^\prime$ (Equation \ref{eq:Harveyalgo}) which causes my variant of their algorithm (Equation \ref{eq:Harveyalgo}) to give the `non-normalized' variance of the residuals. The residuals function in the \{MARSS\} package has an option to give either normalized or non-normalized residuals. + +$\KK_t$ is the Kalman gain output by the \{MARSS\} package \verb@MARSSkf()@ function. The Kalman gain as used in the \citet{Harveyetal1998} algorithm is $K_t=\BB_{t+1}\KK_t$. Notice that Equation 21 in \citet{Harveyetal1998} has $H_t G_t^\top$ in the equation for $K_t$. This is the covariance of the state and observation errors, which is allowed to be non-zero given the way Harvey et al. write the errors in their Equations 19 and 20. The way the \{MARSS\} package model is written, the state and observation errors are independent of each other. Thus $H_t G_t^\top = 0$ and this term drops out of the $K_t$ equation in Equation \ref{eq:Harveyalgo}. + +\subsection{Computing the normalized residuals} + +To compute the normalized residuals and residuals variance, a block diagonal matrix with the inverse of the $\RR$ and $\QQ$ matrices is used. The normalized residuals are: +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\varepsilon}_t +\end{equation} +The variance of the normalized residuals is +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\Sigma]}_t \begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} +\end{equation} + +\subsection{Computing the Cholesky standardized residuals} + +The Cholesky standardized residuals are computed by multiplying $\widehat{\varepsilon}_t$ by $(\widehat{\Sigma}_t)^{-1/2}$ (the inverse of the Cholesky decomposition of the variance-covariance matrix for $\widehat{\varepsilon}_t$): +\begin{equation}\label{eq:std.resid} +\widehat{\varepsilon}_{t, std} = (\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t . +\end{equation} +These residuals are uncorrelated (across the residuals at time $t$ in $\widehat{\varepsilon}_t$). See \citet{HarveyKoopman1992} and \citet[section V]{Harveyetal1998} for a discussion on how to use these residuals for outlier detection and structural break detection. + +It is also common to use the marginal standardized residuals, which would be $\widehat{\varepsilon}_t$ multiplied by the inverse of the square-root of $\dg(\widehat{\Sigma}_t)$, where $\dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. +\begin{equation} +\widehat{\varepsilon}_{t, mar} = \dg(\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t +\end{equation} +Marginal standardized residuals may be correlated at time $t$ (unlike the Cholesky standardized residuals) but are a bit easier to interpret when there is correlation across the model residuals. + +\section{Distribution of the MARSS innovation residuals} + +One-step-ahead predictions (innovations) are often shown for MARSS models and these are used for likelihood calculations. Innovations are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t-1$. This section gives the residual variance for the innovations and the analogous values for the states. Innovations residuals are the more common residuals discussed for state-space models; these are also known as the `one-step-ahead` prediction residuals. + +\subsection{One-step-ahead model residuals} + +Define the innovations $\checkvt$ as: +\begin{equation}\label{eq:vtt1} +\checkvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxttm - \aa_t, +\end{equation} +where $\hatxttm$ is $\E[\XX_t|\yy^{(1),t-1}]$ (expected value of $\XX_t$ conditioned on the data up to time $t-1$). The random variable, innovations over all possible $\yy_t$, is $\checkVt$. Its mean is 0 and we want to find its variance. + +This is conceptually different than the observed `innovations'. First, this is the random variable `innovation'. $\yy^{(1)}_t$ here is not the actual data that you observe (the one data set that you have). It's the data that you could observe. $\yy_t$ is a sample from the random variable $\YY_t$ and $\checkvt$ is a sample from the innovations you could observe. Second, $\checkvt$ includes both $\yy_t^{(1)}$ and $\yy_t^{(2)}$ (observed and unobserved $\yy$). Normally, the innovations for missing data would appear as 0s, e.g., from a call to \verb@MARSSfss()@. For missing data, $\checkvt$ is not necessarily 0. For example if $\yy$ is multivariate and correlated with each other through $\RR$ or a shared $\xx$ dependency. + +The derivation of the variance of $\checkVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t-1$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:innov.model} +\var[\checkVt] = \RR_t - \ZZ_t \hatVttm \ZZ_t^\top + \hatSttm\ZZ_t^\top + \ZZ_t(\hatSttm)^\top +\end{equation} +where the $\hatVttm$ and $\hatSttm$ are now conditioned on only the data from 1 to $t-1$. +$\hatSttm = \cov[\YY_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t-1}]$. +$\yy_t$ is not in the conditional since it only includes data up to $t-1$. Without $\yy_t$ in the conditional, $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent\footnote{This is only true given the way the MARSS equation is written in this report where $V_t$ and $W_t$ are independent. This is not the case for the more general Harvey et al. MARSS model which allows covariance between $V_t$ and $W_t$.} and $\cov[\ZZ_t \XX_t + \aa_t + \VV_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t,\XX_t|\yy^{(1), t-1}] = \ZZ_t \hatVttm$. Therefore, $\ZZ_t(\hatSttm)^\top = \ZZ_t \hatVttm \ZZ_t^\top = \hatSttm(\ZZ_t)^\top$. Thus Equation \ref{eq:innov.model} reduces to +\begin{equation}\label{eq:innov.model2} +\var[\checkVt] = \RR_t + \ZZ_t \hatVttm \ZZ_t^\top. +\end{equation} + +Note $\var[\checkVt]$ is a standard output from Kalman filter functions and is used to compute the likelihood of the data (conditioned on a set of parameters). In the Kalman filter in the \{MARSS\} package, it is output as \texttt{Sigma} from \texttt{MARSSkfss()}. + + +\subsection{One-step ahead state residuals} + +Define the state residuals conditioned on the data from 1 to $t-1$ as $\checkwt$. +\begin{equation}\label{eq:wtt1} +\checkwt = \hatxtt - \BB_t\hatxtmt1 - \uu_t, +\end{equation} +where $\hatxtmt1$ is $\E[\XX_{t-1}|\yy^{(1),t-1}]$ (expected value of $\XX_{t-1}$ conditioned on the data up to time $t-1$) and $\hatxtt$ is $\E[\XX_{t}|\yy^{(1),t}]$ (expected value of $\XX_{t}$ conditioned on the data up to time $t$). +From the Kalman filter equations: +\begin{equation}\label{eq:wtt1.2} +\hatxtt = \BB_t\hatxtmt1 + \uu_t + \KK_t \checkvt +\end{equation} +Thus, $\checkwt$ is a transformed $\checkvt$: +\begin{equation}\label{eq:wtt1.3} +\checkwt = \KK_t \checkvt, +\end{equation} +where $\KK_t$ is the Kalman gain. $\KK_t = \hatVttm \ZZ_t^\top[\ZZ_t \hatVttm \ZZ_t^\top + \RR_t]^{-1}$ and $\ZZ_t$ is the missing values modified $\ZZ_t$ where if the $i$-th $\yy_t$ is missing, the $i$-th row of $\ZZ_t$ is set to all 0s (Shumway and Stoffer 2006, equation 6.78). +Thus the variance of $\checkWt$ is +\begin{equation}\label{eq:var.Wt} +\var[\checkWt] = \KK_t \var[\checkVt] \KK_t^\top +\end{equation} + +\subsection{Joint distribution of the conditional one-step-ahead residuals} + +\subsubsection{with the state residuals defined from $t-1$ to $t$} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t = \begin{bmatrix}\checkvt\\ \checkwt \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWt$ is +\begin{equation}\label{eq:covhatVtWtp.onestep} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t}\checkVt] = \var[\checkVt]\KK_{t}^\top +\end{equation} + + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep} +\overline{\Sigma}_t = \var[\overline{\varepsilon}_t] = \begin{bmatrix}[c|c] + \var[\checkVt]& \var[\checkVt]\KK_{t}^\top\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +\KK_{t}\var[\checkVt]& \KK_{t}\var[\checkVt]\KK_{t}^\top \end{bmatrix}, +\end{equation} + +Since $\checkwt=\KK_t \checkvt$, the state one-step-ahead residuals are perfectly correlated with the model one-step-ahead residuals so the joint distribution is not useful (all the information is in the variance of $\checkVt$). + + +The Cholesky standardized residuals for $\overline{\varepsilon}_t$ are +\begin{equation} +\overline{\Sigma}_t^{-1/2} \overline{\varepsilon}_t +\end{equation} +However the Cholesky standardized joint residuals cannot be computed since $\overline{\Sigma}_t$ is not positive definite. Because $\checkwt$ equals $\KK_t \checkvt$, the state residuals are completely explained by the model residuals. However we can compute the Cholesky standardized model residuals using +\begin{equation} +\var[\checkVt]^{-1/2} \checkvt +\end{equation} +$\var[\checkVt]^{-1/2}$ is the inverse of the lower triangle of the Cholesky decomposition of $\var[\checkVt]$. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t$ (both model and state one-step ahead residuals) can be computed with the inverse of the square root of the diagonal of $\overline{\Sigma}_t$: +\begin{equation} +\dg(\overline{\Sigma}_t)^{-1/2} \overline{\varepsilon}_t +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\subsubsection{with the state residuals defined from $t$ to $t+1$} + +\emph{Note that the model residual is conditioned on data 1 to $t-1$ and the state residual on data 1 to $t$ in this case.} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t^* = \begin{bmatrix}\checkvt\\ \checkwtp \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWtp$ is +\begin{equation}\label{eq:covhatVtWtp.onestep.2} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t+1}\checkVtp] = \cov[\checkVt, \checkVtp]\KK_{t+1}^\top +\end{equation} +Innovations residuals are temporally uncorrelated, thus $\cov[\checkVt,\checkVtp]=0$ and thus $\cov[\checkVt,\checkWtp]=0$. + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep2} +\overline{\Sigma}_t^* = \var[\overline{\varepsilon}_t^*] = \begin{bmatrix}[c|c] + \var[\checkVt]& 0\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +0 & \KK_{t+1}\var[\checkVtp]\KK_{t+1}^\top \end{bmatrix}, +\end{equation} + +The Cholesky standardized residuals for $\overline{\varepsilon}_t^*$ are +\begin{equation} +(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} + $\overline{\Sigma}_t^*$ is positive definite so its Cholesky decomposition can be computed. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t^*$ are: +\begin{equation} +\dg(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\section{Distribution of the MARSS contemporaneous model residuals} + +Contemporaneous model residuals are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t$. This section gives the residual variance for these residuals. There are no state residuals for this case as that would require the expected value of $\XX_t$ conditioned on the data up to $t+1$. + +Define the contemporaneous model residuals $\dotvt$ as: +\begin{equation}\label{eq:vtt} +\dotvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxtt - \aa_t, +\end{equation} +where $\hatxtt$ is $\E[\XX_t|\yy^{(1),t}]$ (expected value of $\XX_t$ conditioned on the data up to time $t$). The random variable, contemporaneous model residuals over all possible $\yy_t$, is $\dotVt$. Its mean is 0 and we want to find its variance. + +The derivation of the variance of $\dotVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:contemp.model} +\var[\dotVt] = \RR_t - \ZZ_t \hatVtt \ZZ_t^\top + \hatStt\ZZ_t^\top + \ZZ_t(\hatStt)^\top +\end{equation} +where the $\hatVtt$ and $\hatStt$ are now conditioned on only the data from 1 to $t$. +$\hatStt = \cov[\YY_t,\XX_t|\yy^{(1), t}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t}]$. +If $\yy_t$ has no missing values, this reduces to $\RR_t - \ZZ_t \hatVtt \ZZ_t^\top$ while if $\yy_t$ is all missing values, this reduces to $\RR_t + \ZZ_t \hatVtt \ZZ_t^\top$. See discussion of this after Equation \ref{eq:first.and.secons.vvtgeneral}. + +Equation \ref{eq:contemp.model} gives the equation for the case where $\yy_t$ is partially observed. $\hatStt$ is output by the \verb@MARSShatyt()@ function in the \{MARSS\} package and $\hatVtt$ is output by the \verb@MARSSkfss()@ function. + +\bibliography{./EMDerivation} +\bibliographystyle{apalike} + +\end{document} \ No newline at end of file diff --git a/inst/doc/Residuals.pdf b/inst/doc/Residuals.pdf new file mode 100644 index 0000000..a5fa880 Binary files /dev/null and b/inst/doc/Residuals.pdf differ diff --git a/man/MARSSfit.Rd b/man/MARSSfit.Rd index 3223851..8b034b4 100644 --- a/man/MARSSfit.Rd +++ b/man/MARSSfit.Rd @@ -12,5 +12,9 @@ MARSSfit(x, ...) \item{...}{additional arguments for the fitting function} } \description{ -Uses the method of a marssMLE class object. Will call a function such as \code{\link[=MARSSkem]{MARSSkem()}}, \code{\link[=MARSSoptim]{MARSSoptim()}} or \code{MARSStmb()} in the {marssTMB} package. +This is an internal function used by \code{\link[=MARSS]{MARSS()}}. It is not +intended for use by users but needs to be exported so +{marssTMB} can use it. Uses the method of a marssMLE class object. +Will call a function such as \code{\link[=MARSSkem]{MARSSkem()}}, \code{\link[=MARSSoptim]{MARSSoptim()}} in the +MARSS package or \code{MARSStmb()} in the {marssTMB} package. } diff --git a/man/MARSSkf.Rd b/man/MARSSkf.Rd index 019bffa..c5a03de 100644 --- a/man/MARSSkf.Rd +++ b/man/MARSSkf.Rd @@ -67,7 +67,7 @@ Ghahramani, Z. and Hinton, G.E. (1996) Parameter estimation for linear dynamical Holmes, E. E. (2012). Derivation of the EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models. Technical Report. arXiv:1302.3919 [stat.ME] \code{RShowDoc("EMDerivation",package="MARSS")} to open a copy. -Jouni Helske (2012). KFAS: Kalman filter and smoother for exponential family state space models. \href{https://CRAN.R-project.org/package=KFAS} +Jouni Helske (2012). KFAS: Kalman filter and smoother for exponential family state space models. \href{https://CRAN.R-project.org/package=KFAS}{https://CRAN.R-project.org/package=KFAS} Koopman, S.J. and Durbin J. (2000). Fast filtering and smoothing for non-stationary time series models, Journal of American Statistical Association, 92, 1630-38. diff --git a/man/accuracy_marssMLE.Rd b/man/accuracy_marssMLE.Rd index a29eaac..4e5b3b4 100644 --- a/man/accuracy_marssMLE.Rd +++ b/man/accuracy_marssMLE.Rd @@ -50,5 +50,5 @@ accuracy(fr, x=test.dat) \references{ Hyndman, R.J. and Koehler, A.B. (2006) "Another look at measures of forecast accuracy". International Journal of Forecasting, 22(4), 679-688. -Hyndman, R.J. and Athanasopoulos, G. (2018) "Forecasting: principles and practice", 2nd ed., OTexts, Melbourne, Australia. Section 3.4 "Evaluating forecast accuracy". \href{https://otexts.org/fpp2/accuracy.html}. +Hyndman, R.J. and Athanasopoulos, G. (2018) "Forecasting: principles and practice", 2nd ed., OTexts, Melbourne, Australia. Section 3.4 "Evaluating forecast accuracy". \href{https://otexts.com/fpp2/accuracy.html}{https://otexts.com/fpp2/accuracy.html}. } \ No newline at end of file diff --git a/man/residuals_marssMLE.Rd b/man/residuals_marssMLE.Rd index 41f5fc8..ead59c4 100644 --- a/man/residuals_marssMLE.Rd +++ b/man/residuals_marssMLE.Rd @@ -87,13 +87,16 @@ fit <- MARSS(dat, model = list(Z = factor(c("WA", "OR", "OR")))) library(ggplot2) theme_set(theme_bw()) -# Show the standard residuals diagnostic plots for state-space models -# silent used for examples to not be in interactive mode +\dontrun{ +# Show a series of standard residuals diagnostic plots for state-space models autoplot(fit, plot.type="residuals") +} -# Plot the residuals object; show both for y and x d <- residuals(fit, type="tt1") +\dontrun{ +# Make a series of diagnostic plots from a residuals object autoplot(d) +} # Manually make a plot of the model residuals (innovations) with intervals d$.conf.low <- d$.fitted+qnorm(0.05/2)*d$.sigma diff --git a/man/utility_functions.Rd b/man/utility_functions.Rd index 63a4d26..8392f4a 100644 --- a/man/utility_functions.Rd +++ b/man/utility_functions.Rd @@ -27,7 +27,7 @@ \alias{ pinv } \alias{ pcholinv } \alias{ pchol } -\alias{ all.equal.vector } +\alias{ vector.all.equal } \keyword{internal} \title{ Utility Functions } @@ -35,7 +35,7 @@ Utility functions for MARSS functions in the \code{\link{MARSS-package}}. These are not exported but can be accessed using the \code{MARSS:::} prefix. } \usage{ -\method{all.equal}{vector}(x) +vector.all.equal(x) convert.model.mat(param.matrix) fixed.free.to.formula(fixed,free,dim) fully.spec.x(Z, R) @@ -108,7 +108,7 @@ vec(x) \item \code{ pcholinv } is the inverse based on the Cholesky decomposition but modified to allow 0s on the diagonal of x (with corresponding 0 row/column). These appear as 0 row/columns in the returned inverse. \item \code{ pchol } returns the Cholesky decomposition but modified to allow 0s on the diagonal of x (with corresponding 0 row/column). \item \code{ is.solvable } returns information on the solvability of the linear system y=Ax using the SVD decomposition. - \item \code{ all.equal.vector } tests if the all the elements in a vector, matrix, or array are all equal. Works on list matrices too. + \item \code{ vector.all.equal } tests if the all the elements in a vector, matrix, or array are all equal. Works on list matrices too. \item \code{ parmat } constructs the parameter matrix with both the fixed and free values from the vectorized form in a \code{\link{marssMLE}} object. Users should use \code{\link[=coef.marssMLE]{coef}}. \item \code{ fully.spec.x } returns a list with 0 and 1 showing which x are fully specified by data when \code{R} has zeros on the diagonal. Used by \code{\link{MARSSkfss}()}. diff --git a/vignettes/EMDerivation-concordance.tex b/vignettes/EMDerivation-concordance.tex new file mode 100644 index 0000000..6aa2315 --- /dev/null +++ b/vignettes/EMDerivation-concordance.tex @@ -0,0 +1,2 @@ +\Sconcordance{concordance:EMDerivation.tex:/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/EMDerivation.Rnw:% +1 3148 1} diff --git a/vignettes/EMDerivation.aux b/vignettes/EMDerivation.aux new file mode 100644 index 0000000..dc45461 --- /dev/null +++ b/vignettes/EMDerivation.aux @@ -0,0 +1,312 @@ +\relax +\citation{McLachlanKrishnan2008} +\citation{Harvey1989} +\citation{Borman2009} +\citation{ShumwayStoffer1982} +\citation{GhahramaniHinton1996,RoweisGhahramani1999} +\citation{Wuetal1996} +\citation{Zuuretal2003a} +\@writefile{toc}{\contentsline {section}{\numberline {1}Overview}{2}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {1.1}The MARSS model}{2}{}\protected@file@percent } +\newlabel{eq:MARSS}{{1}{2}} +\newlabel{eq:MARSSx}{{1a}{2}} +\newlabel{eq:MARSSy}{{1b}{2}} +\newlabel{eq:MARSSx1}{{1c}{2}} +\newlabel{eq:MARSS.ex}{{2}{3}} +\@writefile{toc}{\contentsline {subsection}{\numberline {1.2}The joint log-likelihood function}{3}{}\protected@file@percent } +\newlabel{eq:jointL}{{5}{3}} +\citation{JohnsonWichern2007} +\citation{ShumwayStoffer2006} +\citation{ShumwayStoffer2006,Zuuretal2003a} +\newlabel{eq:logL}{{6}{4}} +\newlabel{eq:logL.V0.is.0}{{7}{4}} +\@writefile{toc}{\contentsline {subsection}{\numberline {1.3}Missing values}{4}{}\protected@file@percent } +\newlabel{sec:missing}{{1.3}{4}} +\@writefile{toc}{\contentsline {section}{\numberline {2}The EM algorithm}{5}{}\protected@file@percent } +\newlabel{sec:EMalgorithm}{{2}{5}} +\newlabel{eq:EMalg}{{8}{5}} +\newlabel{eq:EMalg.j}{{9}{5}} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.1}The expected log-likelihood function}{5}{}\protected@file@percent } +\newlabel{sec:expLL}{{2.1}{5}} +\citation{ShumwayStoffer2006} +\newlabel{eq:expLL}{{10}{6}} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.2}The expectations used in the derivation}{6}{}\protected@file@percent } +\newlabel{sec:expectations}{{2.2}{6}} +\newlabel{eq:expectations}{{11}{6}} +\newlabel{eq:hatVt}{{11e}{6}} +\newlabel{eq:hatWt}{{11g}{6}} +\newlabel{eq:comp.formula.variance}{{12}{6}} +\@writefile{lot}{\contentsline {table}{\numberline {1}{\ignorespaces Notes on multivariate expectations. For the following examples, let $\mbox {$\pmb {X}$}$ be a vector of length three, $X_1,X_2,X_3$. $f()$ is the probability distribution function (pdf). $C$ is a constant (not a random variable).\relax }}{7}{}\protected@file@percent } +\providecommand*\caption@xref[2]{\@setref\relax\@undefined{#1}} +\newlabel{tab:MultivariateExpectations}{{1}{7}} +\@writefile{toc}{\contentsline {section}{\numberline {3}The unconstrained update equations}{7}{}\protected@file@percent } +\newlabel{sec:generalupdate}{{3}{7}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Matrix calculus need for the derivation}{7}{}\protected@file@percent } +\newlabel{sec:MatrixDerivatives}{{3.1}{7}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}The update equation for $\mbox {$\mathbf u$}$ (unconstrained)}{8}{}\protected@file@percent } +\newlabel{eq:u.unconstrained1}{{21}{8}} +\@writefile{lot}{\contentsline {table}{\numberline {2}{\ignorespaces Derivatives of a scalar with respect to vectors and matrices. In the following $a$ is a scalar (unrelated to $\mbox {$\mathbf a$}$), $\mbox {$\mathbf a$}$ and $\mbox {$\mathbf c$}$ are $n \times 1$ column vectors, $\mbox {$\mathbf b$}$ and $\mbox {$\mathbf d$}$ are $m \times 1$ column vectors, $\mbox {$\mathbf D$}$ is a $n \times m$ matrix, $\mbox {$\mathbf C$}$ is a $n \times n$ matrix, and $\mbox {$\mathbf A$}$ is a diagonal $n \times n$ matrix (0s on the off-diagonals). $\mbox {$\mathbf C$}^{-1}$ is the inverse of $\mbox {$\mathbf C$}$, $\mbox {$\mathbf C$}^\top $ is the transpose of $\mbox {$\mathbf C$}$, $\mbox {$\mathbf C$}^{-\top } = \big (\mbox {$\mathbf C$}^{-1}\big )^\top = \big (\mbox {$\mathbf C$}^\top \big )^{-1}$, and $|\mbox {$\mathbf C$}|$ is the determinant of $\mbox {$\mathbf C$}$. Note, all the numerators in the differentials on the far left reduce to scalars. Although the matrix names may be the same as those of matrices referred to in the text, the matrices in this table are dummy matrices used to show the matrix derivative relations.\relax }}{9}{}\protected@file@percent } +\newlabel{tab:MatrixDerivatives}{{2}{9}} +\newlabel{eq:derivproductrule}{{14}{9}} +\newlabel{eq:derivaTc}{{15}{9}} +\newlabel{eq:derivaTDb}{{16}{9}} +\newlabel{eq:derivlogDet}{{17}{9}} +\newlabel{eq:derivbDTCDd}{{18}{9}} +\newlabel{eq:derivaTCa}{{19}{9}} +\newlabel{eq:derivInv}{{20}{9}} +\newlabel{eq:u.unconstrained2}{{22}{10}} +\newlabel{eq:u.unconstrained3}{{23}{10}} +\newlabel{eq:u.unconstrained4}{{24}{10}} +\newlabel{eq:uupdate.unconstrained}{{25}{10}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}The update equation for $\mbox {$\mathbf B$}$ (unconstrained)}{10}{}\protected@file@percent } +\newlabel{eq:B.unconstrained1}{{26}{10}} +\newlabel{eq:B.unconstrained2}{{27}{10}} +\newlabel{eq:B.unconstrained3}{{28}{10}} +\newlabel{eq:B.unconstrained4}{{29}{11}} +\newlabel{eq:B.update.unconstrained}{{30}{11}} +\newlabel{eq:B.update.blockdiag}{{31}{11}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.4}The update equation for $\mbox {$\mathbf Q$}$ (unconstrained)}{11}{}\protected@file@percent } +\newlabel{subsec:Qunconstrained}{{3.4}{11}} +\newlabel{eq:Q.unconstrained1}{{32}{11}} +\citation{HendersonSearle1979} +\newlabel{eq:Q.unconstrained2}{{33}{12}} +\newlabel{eq:Q.unconstrained3}{{34}{12}} +\newlabel{eq:Q.unconstrained4}{{35}{12}} +\newlabel{eq:Q.unconstrained5}{{36}{12}} +\newlabel{eq:Q.update.unconstrained}{{37}{12}} +\newlabel{eq:Q.update.blockdiag}{{38}{12}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.5}Update equation for $\mbox {$\mathbf a$}$ (unconstrained)}{13}{}\protected@file@percent } +\newlabel{sec:unconstA}{{3.5}{13}} +\newlabel{eq:a.unconstrained1}{{39}{13}} +\newlabel{eq:a.unconstrained2}{{40}{13}} +\newlabel{eq:a.unconstrained3}{{41}{13}} +\newlabel{eq:a.unconstrained4}{{42}{13}} +\newlabel{eq:a.update.unconstrained}{{43}{13}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.6}The update equation for $\mbox {$\mathbf Z$}$ (unconstrained)}{13}{}\protected@file@percent } +\newlabel{eq:Z.unconstrained1}{{44}{13}} +\newlabel{eq:Z.unconstrained2}{{45}{14}} +\newlabel{eq:Z.unconstrained3}{{46}{14}} +\newlabel{eq:Z.unconstrained4}{{47}{14}} +\newlabel{eq:Z.update.unconstrained}{{48}{14}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.7}The update equation for $\mbox {$\mathbf R$}$ (unconstrained)}{14}{}\protected@file@percent } +\newlabel{eq:R.unconstrained1}{{49}{14}} +\newlabel{eq:R.unconstrained2}{{50}{14}} +\newlabel{eq:R.unconstrained3}{{51}{14}} +\newlabel{eq:R.unconstrained4}{{52}{14}} +\citation{ShumwayStoffer2006} +\citation{GhahramaniHinton1996} +\newlabel{eq:R.unconstrained5}{{53}{15}} +\newlabel{eq:R.update.unconstrained}{{54}{15}} +\newlabel{eq:R.update.blockdiag}{{55}{15}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.8}Update equation for $\mbox {\boldmath $\xi $}$ and $\mbox {\boldmath $\Lambda $}$ (unconstrained), stochastic initial state}{15}{}\protected@file@percent } +\newlabel{eq:pi.unconstrained1}{{56}{15}} +\newlabel{eq:pi.unconstrained2}{{57}{15}} +\newlabel{eq:pi.unconstrained3}{{58}{15}} +\newlabel{eq:pi.unconstrained4}{{59}{15}} +\newlabel{eq:pi.update.unconstrained}{{60}{15}} +\newlabel{eq:V0.update.unconstrained}{{61}{16}} +\newlabel{eq:pix1.update.unconstrained}{{62}{16}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.9}Update equation for $\mbox {\boldmath $\xi $}$ (unconstrained), fixed $\mbox {$\pmb {x}$}_0$}{16}{}\protected@file@percent } +\newlabel{eq:pi.unconstrained.V0.is.0}{{64}{16}} +\newlabel{eq:pi.unconstrained.V0.is.0.2}{{65}{16}} +\newlabel{eq:pi.unconstrained.V0.is.0.3}{{66}{16}} +\newlabel{eq:pi.unconstrained.V0.is.0.4}{{67}{16}} +\newlabel{eq:pi.unconstrained.V0.is.0.5}{{68}{16}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.10}Update equation for $\mbox {\boldmath $\xi $}$ (unconstrained), fixed $\mbox {$\pmb {x}$}_1$}{17}{}\protected@file@percent } +\newlabel{sec:xi.unconstrained.x1}{{3.10}{17}} +\newlabel{eq:pi.unconstrained.V0.is.0.t.1.1}{{71}{17}} +\newlabel{eq:pi.unconstrained.V0.is.0.t.1.2}{{73}{17}} +\citation{KoopmanOoms2011} +\citation{Koopman1993} +\newlabel{eq:pi.unconstrained.V0.is.0.t.1.3}{{74}{18}} +\@writefile{toc}{\contentsline {section}{\numberline {4}The time-varying MARSS model with linear constraints}{18}{}\protected@file@percent } +\newlabel{sec:tvMARSS}{{4}{18}} +\newlabel{eq:MARSS.ex2}{{75}{18}} +\newlabel{eq:MARSS.ex.vec}{{76}{18}} +\newlabel{eq:MARSS.ex.vec.2}{{77}{18}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.1}MARSS model with linear constraints}{19}{}\protected@file@percent } +\@writefile{lot}{\contentsline {table}{\numberline {3}{\ignorespaces Kronecker and vec relations. Here $\mbox {$\mathbf A$}$ is $n \times m$, $\mbox {$\mathbf B$}$ is $m \times p$, $\mbox {$\mathbf C$}$ is $p \times q$, and $\mbox {$\mathbf E$}$ and $\mbox {$\mathbf D$}$ are $p \times p$. $\mbox {$\mathbf a$}$ is a $m \times 1$ column vector and $\mbox {$\mathbf b$}$ is a $p \times 1$ column vector. The symbol $\otimes $ stands for the Kronecker product: $\mbox {$\mathbf A$}\otimes \mbox {$\mathbf C$}$ is a $np \times mq$ matrix. The identity matrix, $\mbox {$\mathbf I$}_n$, is a $n \times n$ diagonal matrix with ones on the diagonal.\relax }}{20}{}\protected@file@percent } +\newlabel{tab:VecRelations}{{3}{20}} +\newlabel{eq:vec.a}{{78}{20}} +\newlabel{eq:vec.Aa}{{79}{20}} +\newlabel{eq:vec.AB}{{80}{20}} +\newlabel{eq:vec.ABC}{{81}{20}} +\newlabel{eq:vec.aTBa}{{82}{20}} +\newlabel{eq:kron.prod}{{83}{20}} +\newlabel{eq:kron.column.vec}{{84}{20}} +\newlabel{eq:kron.column.quad.vec}{{85}{20}} +\newlabel{eq:kron.column.column.vec}{{86}{20}} +\newlabel{eq:kron.trans}{{87}{20}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.2}A MARSS model with exogenous variables}{21}{}\protected@file@percent } +\newlabel{eq:MARSS.simple.ex}{{88}{21}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.3}A general MARSS model with exogenous variables}{21}{}\protected@file@percent } +\newlabel{eq:MARSS.general.ex}{{89}{21}} +\newlabel{eq:MARSS.ex3}{{90}{22}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.4}The expected log-likelihood function}{22}{}\protected@file@percent } +\newlabel{eq:MARSS.ex.reformed}{{91}{22}} +\newlabel{eq:logL.vec.general}{{92}{23}} +\@writefile{toc}{\contentsline {section}{\numberline {5}The constrained update equations}{23}{}\protected@file@percent } +\newlabel{sec:constrained}{{5}{23}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.1}The general $\mbox {$\mathbf u$}$ update equations}{23}{}\protected@file@percent } +\newlabel{eq:u.general1}{{93}{23}} +\newlabel{eq:u.general1b}{{94}{24}} +\newlabel{eq:u.general4}{{95}{24}} +\newlabel{eq:u.general5}{{96}{24}} +\newlabel{eq:u.general.update1}{{97}{24}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.2}The general $\mbox {$\mathbf a$}$ update equation}{24}{}\protected@file@percent } +\newlabel{sec:constA}{{5.2}{24}} +\newlabel{eq:general.a.update}{{98}{24}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.3}The general $\mbox {\boldmath $\xi $}$ update equation, stochastic initial state}{24}{}\protected@file@percent } +\newlabel{eq:pi.general1}{{99}{24}} +\newlabel{eq:pi.general2}{{100}{24}} +\newlabel{eq:pi.update.general1}{{101}{24}} +\newlabel{eq:pi.update.general2}{{102}{24}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.4}The general $\mbox {\boldmath $\xi $}$ update equation, fixed $\mbox {$\pmb {x}$}_0$}{25}{}\protected@file@percent } +\newlabel{sec:xi.constrained.x0}{{5.4}{25}} +\newlabel{eq:logL.vec.general.V0.is.0b}{{103}{25}} +\newlabel{eq:pi.constrained.V0.is.0}{{104}{25}} +\newlabel{eq:pi.constrained.V0.is.0.4}{{107}{25}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.5}The general $\mbox {\boldmath $\xi $}$ update equation, fixed $\mbox {$\pmb {x}$}_1$}{25}{}\protected@file@percent } +\newlabel{sec:general.x1.update}{{5.5}{25}} +\newlabel{eq:logL.vec.general.V0.is.0.x1}{{109}{25}} +\newlabel{eq:pix1.unconstrained.V0.is.0.t.1.3}{{112}{26}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.6}The general $\mbox {$\mathbf B$}$ update equation}{26}{}\protected@file@percent } +\newlabel{eq:B.general1}{{115}{26}} +\newlabel{eq:B.general1b}{{117}{26}} +\newlabel{eq:B.expect1}{{121}{27}} +\newlabel{eq:B.expect2}{{122}{27}} +\newlabel{eq:B.expect3}{{123}{27}} +\newlabel{eq:B.general4}{{125}{27}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.7}The general $\mbox {$\mathbf Z$}$ update equation}{27}{}\protected@file@percent } +\newlabel{sec:constZ}{{5.7}{27}} +\newlabel{eq:general.Z.update}{{126}{27}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.8}The general $\mbox {$\mathbf Q$}$ update equation}{27}{}\protected@file@percent } +\newlabel{sec:constrained.Q}{{5.8}{27}} +\newlabel{eq:Q.general}{{127}{28}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {5.8.1}Special case: diagonal $\mbox {$\mathbf Q$}$ matrix (with shared or unique parameters)}{28}{}\protected@file@percent } +\newlabel{eq:Q.gendiag2}{{129}{29}} +\newlabel{eq:Q.gendiag3}{{131}{29}} +\newlabel{eq:Q.gendiag4}{{132}{29}} +\newlabel{eq:Q.diag.update}{{133}{29}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {5.8.2}Special case: $\mbox {$\mathbf Q$}$ with one variance and one covariance}{30}{}\protected@file@percent } +\newlabel{eq:Q.eqvarcov1}{{134}{30}} +\newlabel{eq:Q.eqvarcov2}{{135}{30}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {5.8.3}Special case: a block-diagonal matrices with replicated blocks}{30}{}\protected@file@percent } +\newlabel{sec:Q.block.diagonal}{{5.8.3}{30}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {5.8.4}Special case: a symmetric blocked matrix}{31}{}\protected@file@percent } +\newlabel{sec:Q.symmetric blocked}{{5.8.4}{31}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {5.8.5}The general case: a block-diagonal matrix with general blocks}{32}{}\protected@file@percent } +\newlabel{sec:Q.general}{{5.8.5}{32}} +\@writefile{toc}{\contentsline {subsection}{\numberline {5.9}The general $\mbox {$\mathbf R$}$ update equation}{32}{}\protected@file@percent } +\newlabel{eq:R.general}{{136}{32}} +\@writefile{toc}{\contentsline {section}{\numberline {6}Computing the expectations in the update equations}{32}{}\protected@file@percent } +\newlabel{sec:compexpectations}{{6}{32}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.1}Expectations involving only $\mbox {$\pmb {X}$}_t$}{33}{}\protected@file@percent } +\newlabel{sec:kalman.smoother}{{6.1}{33}} +\newlabel{eq:kfsoutput}{{141}{33}} +\citation{ShumwayStoffer2006} +\citation{ShumwayStoffer2006} +\newlabel{eq:xt}{{141a}{34}} +\newlabel{eq:Pt}{{141d}{34}} +\newlabel{eq:Ptt1}{{141e}{34}} +\newlabel{eq:kffilteroutput}{{142}{34}} +\newlabel{eq:kffilter}{{143}{34}} +\newlabel{eq:xtt1}{{143a}{34}} +\newlabel{eq:Vtt1}{{143b}{34}} +\newlabel{eq:xtt}{{143c}{34}} +\newlabel{eq:Vtt}{{143d}{34}} +\newlabel{eq:Kt}{{143e}{34}} +\newlabel{eq:kfsmoother}{{144}{34}} +\newlabel{eq:xt1T}{{144a}{34}} +\newlabel{eq:Vt1T}{{144b}{34}} +\newlabel{eq:Jt}{{144c}{34}} +\newlabel{eq:VTT1T}{{144e}{34}} +\newlabel{eq:Vtt1T}{{144f}{34}} +\newlabel{eq:yaZ.miss}{{145}{35}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.2}Expectations involving $\mbox {$\pmb {Y}$}_t$}{35}{}\protected@file@percent } +\newlabel{sec:exp.Y}{{6.2}{35}} +\newlabel{eq:Yt.exp}{{149}{35}} +\newlabel{eq:hatyt}{{149a}{35}} +\newlabel{eq:hatOt}{{149b}{35}} +\newlabel{eq:hatyxttm}{{149c}{35}} +\newlabel{eq:hatyxt}{{149d}{35}} +\newlabel{eq.IRt}{{149e}{35}} +\newlabel{eq:IRt}{{149f}{35}} +\newlabel{eq:IRt.degen}{{150}{36}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.3}Derivation of the expected value of $\mbox {$\pmb {Y}$}_t$}{36}{}\protected@file@percent } +\newlabel{eq:cond.multi.normal}{{153}{36}} +\newlabel{eq:varY}{{156}{36}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.4}Derivation of the expected value of $\mbox {$\pmb {Y}$}_t\mbox {$\pmb {Y}$}_t^\top $}{37}{}\protected@file@percent } +\newlabel{eq:var.Y.cond.x}{{160}{37}} +\newlabel{eq:cond.var.Y}{{163}{38}} +\newlabel{eq:law.total.var.Y}{{164}{38}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.5}Derivation of the expected value of $\mbox {$\pmb {Y}$}_t\mbox {$\pmb {X}$}_t^\top $}{38}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {6.6}Derivation of the expected value of $\mbox {$\pmb {Y}$}_t\mbox {$\pmb {X}$}_{t-1}^\top $}{39}{}\protected@file@percent } +\@writefile{toc}{\contentsline {section}{\numberline {7}Degenerate variance models}{39}{}\protected@file@percent } +\newlabel{sec:degenerate}{{7}{39}} +\@writefile{toc}{\contentsline {subsection}{\numberline {7.1}Rewriting the state and observation models for degenerate variance systems}{39}{}\protected@file@percent } +\newlabel{eq:degen.model.x1}{{173}{40}} +\newlabel{eq:degen.model.y1}{{174}{40}} +\newlabel{eq:degen.model2}{{175}{40}} +\@writefile{toc}{\contentsline {subsection}{\numberline {7.2}Identifying the fully deterministic $\mbox {$\pmb {x}$}$ rows}{41}{}\protected@file@percent } +\newlabel{sec:ident.xds}{{7.2}{41}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {7.2.1}Redefining the $\mbox {$\pmb {x}$}_t^d$ elements in the likelihood}{43}{}\protected@file@percent } +\newlabel{eq:xt.det.sum}{{189}{43}} +\newlabel{eq:xt.det.sum2}{{190}{44}} +\newlabel{eq:EXtd}{{192}{44}} +\newlabel{eq:xt.geo}{{193}{44}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {7.2.2}Dealing with the $\mbox {$\pmb {x}$}_t^{is}$ elements in the likelihood and associated parameter rows}{44}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {7.3}Expected log-likelihood for degenerate models}{45}{}\protected@file@percent } +\newlabel{eq:degen.logL.x0}{{195}{45}} +\@writefile{toc}{\contentsline {subsection}{\numberline {7.4}Logical constraints to ensure a consistent system of equations}{46}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {7.4.1}Constraint 1: $\mbox {$\mathbf Z$}$ does not lead to an over-determined observation process}{46}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {7.4.2}Constraint 2: the state processes are not over-constrained. }{47}{}\protected@file@percent } +\@writefile{toc}{\contentsline {section}{\numberline {8}EM algorithm modifications for degenerate models}{47}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {8.1}$\mbox {$\mathbf R$}$ and $\mbox {$\mathbf Q$}$ update equations}{47}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {8.2}$\mbox {$\mathbf Z$}$ and $\mbox {$\mathbf a$}$ update equations}{47}{}\protected@file@percent } +\citation{Harvey1989} +\@writefile{toc}{\contentsline {subsection}{\numberline {8.3}$\mbox {$\mathbf u$}$ update equation}{48}{}\protected@file@percent } +\newlabel{eq:u.update.degen.2}{{203}{48}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.3.1}$\mbox {$\mathbf u$}^{(0)}$ is not estimated}{48}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.3.2}$\mbox {$\mathbf u$}^d$ is estimated}{48}{}\protected@file@percent } +\newlabel{eq:degen.logL.u}{{204}{48}} +\newlabel{eq:degen.u.update.Deltas}{{205}{49}} +\newlabel{eq:p.degen.update.u}{{206}{49}} +\@writefile{toc}{\contentsline {subsection}{\numberline {8.4}$\mbox {\boldmath $\xi $}$ update equation}{49}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.4.1}$\mbox {\boldmath $\xi $}$ is stochastic}{49}{}\protected@file@percent } +\newlabel{eq:p.degen.update.x0.0.a}{{207}{49}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.4.2}$\mbox {\boldmath $\xi $}^{(0)}$ is not estimated}{49}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.4.3}$\mbox {\boldmath $\xi $}^{(0)}$ is estimated}{49}{}\protected@file@percent } +\newlabel{eq:degen.logL.x0.0}{{208}{49}} +\newlabel{eq:degen.x0.update.Deltas}{{209}{50}} +\newlabel{eq:p.degen.update.x0.0.a.fixed}{{210}{50}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {8.4.4}When $\mbox {$\mathbf H$}_t$ has 0 rows in addition to $\mbox {$\mathbf G$}_t$}{50}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {8.5}$\mbox {$\mathbf B$}^{(0)}$ update equation for degenerate models}{50}{}\protected@file@percent } +\@writefile{toc}{\contentsline {section}{\numberline {9}Kalman filter and smoother modifications for degenerate models}{50}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {9.1}Modifications due to degenerate $\mbox {$\mathbf R$}$ and $\mbox {$\mathbf Q$}$}{50}{}\protected@file@percent } +\newlabel{eq:KKt.2}{{211}{51}} +\newlabel{eq:Jt.2}{{213}{51}} +\@writefile{toc}{\contentsline {subsection}{\numberline {9.2}Modifications due to fixed initial states}{52}{}\protected@file@percent } +\@writefile{toc}{\contentsline {section}{\numberline {10}Summary of requirements for degenerate models}{52}{}\protected@file@percent } +\citation{Biernackietal2003} +\@writefile{toc}{\contentsline {section}{\numberline {11}Implementation comments}{53}{}\protected@file@percent } +\newlabel{sec:implementation}{{11}{53}} +\citation{GhahramaniHinton1996} +\bibdata{./EMDerivation} +\bibcite{Biernackietal2003}{{1}{2003}{{Biernacki et~al.}}{{}}} +\bibcite{Borman2009}{{2}{2009}{{Borman}}{{}}} +\bibcite{GhahramaniHinton1996}{{3}{1996}{{Ghahramani and Hinton}}{{}}} +\bibcite{Harvey1989}{{4}{1989}{{Harvey}}{{}}} +\bibcite{HendersonSearle1979}{{5}{1979}{{Henderson and Searle}}{{}}} +\@writefile{toc}{\contentsline {section}{\numberline {12}MARSS R package}{54}{}\protected@file@percent } +\bibcite{JohnsonWichern2007}{{6}{2007}{{Johnson and Wichern}}{{}}} +\bibcite{KoopmanOoms2011}{{7}{2011}{{Koopman and Ooms}}{{}}} +\bibcite{Koopman1993}{{8}{1993}{{Koopman}}{{}}} +\bibcite{McLachlanKrishnan2008}{{9}{2008}{{McLachlan and Krishnan}}{{}}} +\bibcite{RoweisGhahramani1999}{{10}{1999}{{Roweis and Ghahramani}}{{}}} +\bibcite{ShumwayStoffer2006}{{11}{2006}{{Shumway and Stoffer}}{{}}} +\bibcite{ShumwayStoffer1982}{{12}{1982}{{Shumway and Stoffer}}{{}}} +\bibcite{Wuetal1996}{{13}{1996}{{Wu et~al.}}{{}}} +\bibcite{Zuuretal2003a}{{14}{2003}{{Zuur et~al.}}{{}}} +\bibstyle{apalike} +\gdef \@abspage@last{55} diff --git a/vignettes/EMDerivation.bbl b/vignettes/EMDerivation.bbl new file mode 100644 index 0000000..715bdfa --- /dev/null +++ b/vignettes/EMDerivation.bbl @@ -0,0 +1,72 @@ +\begin{thebibliography}{} + +\bibitem[Biernacki et~al., 2003]{Biernackietal2003} +Biernacki, C., Celeux, G., and Govaert, G. (2003). +\newblock Choosing starting values for the {EM} algorithm for getting the highest likelihood in multivariate gaussian mixture models. +\newblock {\em Computational Statistics and Data Analysis}, 41(3-4):561--575. + +\bibitem[Borman, 2009]{Borman2009} +Borman, S. (2009). +\newblock The expectation maximization algorithm - a short tutorial. + +\bibitem[Ghahramani and Hinton, 1996]{GhahramaniHinton1996} +Ghahramani, Z. and Hinton, G.~E. (1996). +\newblock Parameter estimation for linear dynamical systems. +\newblock Technical Report CRG-TR-96-2, University of Totronto, Dept. of Computer Science. + +\bibitem[Harvey, 1989]{Harvey1989} +Harvey, A.~C. (1989). +\newblock {\em Forecasting, structural time series models and the Kalman filter}. +\newblock Cambridge University Press, Cambridge, UK. + +\bibitem[Henderson and Searle, 1979]{HendersonSearle1979} +Henderson, H.~V. and Searle, S.~R. (1979). +\newblock Vec and vech operators for matrices, with some uses in jacobians and multivariate statistics. +\newblock {\em The Canadian Journal of Statistics}, 7(1):65--81. + +\bibitem[Johnson and Wichern, 2007]{JohnsonWichern2007} +Johnson, R.~A. and Wichern, D.~W. (2007). +\newblock {\em Applied multivariate statistical analysis}. +\newblock Prentice Hall, Upper Saddle River, NJ. + +\bibitem[Koopman and Ooms, 2011]{KoopmanOoms2011} +Koopman, S. and Ooms, M. (2011). +\newblock {\em Forecasting economic time series using unobserved components time series models}, pages 129--162. +\newblock Oxford University Press, Oxford. + +\bibitem[Koopman, 1993]{Koopman1993} +Koopman, S.~J. (1993). +\newblock Disturbance smoother for state space models. +\newblock {\em Biometrika}, 80(1):117--126. + +\bibitem[McLachlan and Krishnan, 2008]{McLachlanKrishnan2008} +McLachlan, G.~J. and Krishnan, T. (2008). +\newblock {\em The {EM} algorithm and extensions}. +\newblock John Wiley and Sons, Inc., Hoboken, NJ, 2nd edition. + +\bibitem[Roweis and Ghahramani, 1999]{RoweisGhahramani1999} +Roweis, S. and Ghahramani, Z. (1999). +\newblock A unifying review of linear gaussian models. +\newblock {\em Neural Computation}, 11:305--345. + +\bibitem[Shumway and Stoffer, 2006]{ShumwayStoffer2006} +Shumway, R. and Stoffer, D. (2006). +\newblock {\em Time series analysis and its applications}. +\newblock Springer-Science+Business Media, LLC, New York, New York, 2nd edition. + +\bibitem[Shumway and Stoffer, 1982]{ShumwayStoffer1982} +Shumway, R.~H. and Stoffer, D.~S. (1982). +\newblock An approach to time series smoothing and forecasting using the {EM} algorithm. +\newblock {\em Journal of Time Series Analysis}, 3(4):253--264. + +\bibitem[Wu et~al., 1996]{Wuetal1996} +Wu, L. S.-Y., Pai, J.~S., and Hosking, J. R.~M. (1996). +\newblock An algorithm for estimating parameters of state-space models. +\newblock {\em Statistics and Probability Letters}, 28:99--106. + +\bibitem[Zuur et~al., 2003]{Zuuretal2003a} +Zuur, A.~F., Fryer, R.~J., Jolliffe, I.~T., Dekker, R., and Beukema, J.~J. (2003). +\newblock Estimating common trends in multivariate time series using dynamic factor analysis. +\newblock {\em Environmetrics}, 14(7):665--685. + +\end{thebibliography} diff --git a/vignettes/EMDerivation.blg b/vignettes/EMDerivation.blg new file mode 100644 index 0000000..3173552 --- /dev/null +++ b/vignettes/EMDerivation.blg @@ -0,0 +1,48 @@ +This is BibTeX, Version 0.99d (TeX Live 2023) +Capacity: max_strings=200000, hash_size=200000, hash_prime=170003 +The top-level auxiliary file: EMDerivation.aux +The style file: apalike.bst +Database file #1: ./EMDerivation.bib +Warning--can't use both author and editor fields in KoopmanOoms2011 +You've used 14 entries, + 1935 wiz_defined-function locations, + 576 strings with 6144 characters, +and the built_in function-call counts, 5157 in all, are: += -- 499 +> -- 189 +< -- 13 ++ -- 70 +- -- 60 +* -- 427 +:= -- 905 +add.period$ -- 41 +call.type$ -- 14 +change.case$ -- 97 +chr.to.int$ -- 14 +cite$ -- 15 +duplicate$ -- 200 +empty$ -- 370 +format.name$ -- 90 +if$ -- 1019 +int.to.chr$ -- 1 +int.to.str$ -- 0 +missing$ -- 17 +newline$ -- 72 +num.names$ -- 42 +pop$ -- 82 +preamble$ -- 1 +purify$ -- 100 +quote$ -- 0 +skip$ -- 154 +stack$ -- 0 +substring$ -- 344 +swap$ -- 23 +text.length$ -- 2 +text.prefix$ -- 0 +top$ -- 0 +type$ -- 74 +warning$ -- 1 +while$ -- 37 +width$ -- 0 +write$ -- 184 +(There was 1 warning) diff --git a/vignettes/EMDerivation.log b/vignettes/EMDerivation.log new file mode 100644 index 0000000..fadf3cb --- /dev/null +++ b/vignettes/EMDerivation.log @@ -0,0 +1,232 @@ +This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex 2023.5.14) 19 MAY 2023 23:06 +entering extended mode + restricted \write18 enabled. + %&-line parsing enabled. +**\input ./EMDerivation.tex \input ./EMDerivation.tex \input ./EMDerivation.tex + (./EMDerivation.tex (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/article.cls +Document Class: article 2022/07/02 v1.4n Standard LaTeX document class +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/size10.clo +File: size10.clo 2022/07/02 v1.4n Standard LaTeX file (size option) +) +\c@part=\count185 +\c@section=\count186 +\c@subsection=\count187 +\c@subsubsection=\count188 +\c@paragraph=\count189 +\c@subparagraph=\count190 +\c@figure=\count191 +\c@table=\count192 +\abovecaptionskip=\skip48 +\belowcaptionskip=\skip49 +\bibindent=\dimen140 +) (/Library/Frameworks/R.framework/Resources/share/texmf/tex/latex/Sweave.sty +Package: Sweave + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/ifthen.sty +Package: ifthen 2022/04/13 v1.1d Standard LaTeX ifthen package (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/iftex/iftex.sty +Package: iftex 2022/02/03 v1.0f TeX engine tests +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphicx.sty +Package: graphicx 2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/keyval.sty +Package: keyval 2022/05/29 v1.15 key=value parser (DPC) +\KV@toks@=\toks16 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphics.sty +Package: graphics 2022/03/10 v1.4e Standard LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/trig.sty +Package: trig 2021/08/11 v1.11 sin cos tan (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-cfg/graphics.cfg +File: graphics.cfg 2016/06/04 v1.11 sample graphics configuration +) +Package graphics Info: Driver file: pdftex.def on input line 107. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-def/pdftex.def +File: pdftex.def 2022/09/22 v1.2b Graphics/color driver for pdftex +)) +\Gin@req@height=\dimen141 +\Gin@req@width=\dimen142 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty +Package: fancyvrb 2023/01/19 4.5a verbatim text (tvz,hv) +\FV@CodeLineNo=\count193 +\FV@InFile=\read2 +\FV@TabBox=\box51 +\c@FancyVerbLine=\count194 +\FV@StepNumber=\count195 +\FV@OutFile=\write3 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/textcomp.sty +Package: textcomp 2020/02/02 v2.0n Standard LaTeX package +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/fontenc.sty +Package: fontenc 2021/04/29 v2.0v Standard LaTeX package +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/multirow/multirow.sty +Package: multirow 2021/03/15 v2.8 Span multiple rows of a table +\multirow@colwidth=\skip50 +\multirow@cntb=\count196 +\multirow@dima=\skip51 +\bigstrutjot=\dimen143 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/footmisc/footmisc.sty +Package: footmisc 2022/03/08 v6.0d a miscellany of footnote facilities +\FN@temptoken=\toks17 +\footnotemargin=\dimen144 +\@outputbox@depth=\dimen145 +Package footmisc Info: Declaring symbol style bringhurst on input line 695. +Package footmisc Info: Declaring symbol style chicago on input line 703. +Package footmisc Info: Declaring symbol style wiley on input line 712. +Package footmisc Info: Declaring symbol style lamport-robust on input line 723. +Package footmisc Info: Declaring symbol style lamport* on input line 743. +Package footmisc Info: Declaring symbol style lamport*-robust on input line 764. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/natbib/natbib.sty +Package: natbib 2010/09/13 8.31b (PWD, AO) +\bibhang=\skip52 +\bibsep=\skip53 +LaTeX Info: Redefining \cite on input line 694. +\c@NAT@ctr=\count197 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/caption/caption.sty +Package: caption 2023/03/12 v3.6j Customizing captions (AR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/caption/caption3.sty +Package: caption3 2023/03/12 v2.4 caption3 kernel (AR) +\caption@tempdima=\dimen146 +\captionmargin=\dimen147 +\caption@leftmargin=\dimen148 +\caption@rightmargin=\dimen149 +\caption@width=\dimen150 +\caption@indent=\dimen151 +\caption@parindent=\dimen152 +\caption@hangindent=\dimen153 +Package caption Info: Standard document class detected. +) +\c@caption@flags=\count198 +\c@continuedfloat=\count199 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsmath.sty +Package: amsmath 2022/04/08 v2.17n AMS math features +\@mathmargin=\skip54 + +For additional information on amsmath, use the `?' option. +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amstext.sty +Package: amstext 2021/08/26 v2.01 AMS text + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsgen.sty +File: amsgen.sty 1999/11/30 v2.0 generic functions +\@emptytoks=\toks18 +\ex@=\dimen154 +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsbsy.sty +Package: amsbsy 1999/11/29 v1.2d Bold Symbols +\pmbraise@=\dimen155 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsopn.sty +Package: amsopn 2022/04/08 v2.04 operator names +) +\inf@bad=\count266 +LaTeX Info: Redefining \frac on input line 234. +\uproot@=\count267 +\leftroot@=\count268 +LaTeX Info: Redefining \overline on input line 399. +LaTeX Info: Redefining \colon on input line 410. +\classnum@=\count269 +\DOTSCASE@=\count270 +LaTeX Info: Redefining \ldots on input line 496. +LaTeX Info: Redefining \dots on input line 499. +LaTeX Info: Redefining \cdots on input line 620. +\Mathstrutbox@=\box52 +\strutbox@=\box53 +LaTeX Info: Redefining \big on input line 722. +LaTeX Info: Redefining \Big on input line 723. +LaTeX Info: Redefining \bigg on input line 724. +LaTeX Info: Redefining \Bigg on input line 725. +\big@size=\dimen156 +LaTeX Font Info: Redeclaring font encoding OML on input line 743. +LaTeX Font Info: Redeclaring font encoding OMS on input line 744. +\macc@depth=\count271 +LaTeX Info: Redefining \bmod on input line 905. +LaTeX Info: Redefining \pmod on input line 910. +LaTeX Info: Redefining \smash on input line 940. +LaTeX Info: Redefining \relbar on input line 970. +LaTeX Info: Redefining \Relbar on input line 971. +\c@MaxMatrixCols=\count272 +\dotsspace@=\muskip16 +\c@parentequation=\count273 +\dspbrk@lvl=\count274 +\tag@help=\toks19 +\row@=\count275 +\column@=\count276 +\maxfields@=\count277 +\andhelp@=\toks20 +\eqnshift@=\dimen157 +\alignsep@=\dimen158 +\tagshift@=\dimen159 +\tagwidth@=\dimen160 +\totwidth@=\dimen161 +\lineht@=\dimen162 +\@envbody=\toks21 +\multlinegap=\skip55 +\multlinetaggap=\skip56 +\mathdisplay@stack=\toks22 +LaTeX Info: Redefining \[ on input line 2953. +LaTeX Info: Redefining \] on input line 2954. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/amsfonts.sty +Package: amsfonts 2013/01/14 v3.01 Basic AMSFonts support +\symAMSa=\mathgroup4 +\symAMSb=\mathgroup5 +LaTeX Font Info: Redeclaring math symbol \hbar on input line 98. +LaTeX Font Info: Overwriting math alphabet `\mathfrak' in version `bold' +(Font) U/euf/m/n --> U/euf/b/n on input line 106. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/l3backend/l3backend-pdftex.def +File: l3backend-pdftex.def 2023-04-19 L3 backend support: PDF output (pdfTeX) +\l__color_backend_stack_int=\count278 +\l__pdf_internal_box=\box54 +) (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/EMDerivation.aux) +\openout1 = `EMDerivation.aux'. + +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 141. +LaTeX Font Info: ... okay on input line 141. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/epstopdf-pkg/epstopdf-base.sty +Package: epstopdf-base 2020-01-24 v2.11 Base part for package epstopdf +Package epstopdf-base Info: Redefining graphics rule for `.eps' on input line 485. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/latexconfig/epstopdf-sys.cfg +File: epstopdf-sys.cfg 2010/07/13 v1.3 Configuration of (r)epstopdf for TeX Live +)) +Package caption Info: Begin \AtBeginDocument code. +Package caption Info: End \AtBeginDocument code. + (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/EMDerivation-concordance.tex) +LaTeX Font Info: Trying to load font information for U+msa on input line 151. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsa.fd +File: umsa.fd 2013/01/14 v3.01 AMS symbols A +) +LaTeX Font Info: Trying to load font information for U+msb on input line 151. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsb.fd +File: umsb.fd 2013/01/14 v3.01 AMS symbols B +) +Underfull \hbox (badness 10000) in paragraph at lines 151--151 +[][]\T1/cmr/m/n/8 Northwest Fish-eries Sci-ence Cen-ter, NOAA Fish-eries, Seat-tle, WA 98112, eli.holmes@noaa.gov, + [] + +[1 + +{/Users/eli.holmes/Library/TinyTeX/texmf-var/fonts/map/pdftex/updmap/pdftex.map}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-t1.enc}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-ts1.enc}] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] +LaTeX Font Info: Trying to load font information for T1+cmtt on input line 1195. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/t1cmtt.fd +File: t1cmtt.fd 2022/07/10 v2.5l Standard LaTeX font definitions +) [21] [22] [23] [24] [25] [26] [27] [28] [29] [30] [31] [32] [33] [34] [35] [36] [37] [38] [39] [40] [41] [42] [43] [44] [45] [46] [47] [48] [49] [50] [51] [52] [53] (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/EMDerivation.bbl [54]) [55] (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/EMDerivation.aux) ) +Here is how much of TeX's memory you used: + 5094 strings out of 478007 + 84933 string characters out of 5838177 + 1917999 words of memory out of 5000000 + 25184 multiletter control sequences out of 15000+600000 + 542505 words of font info for 107 fonts, out of 8000000 for 9000 + 14 hyphenation exceptions out of 8191 + 72i,26n,76p,1765b,377s stack positions out of 10000i,1000n,20000p,200000b,200000s + +Output written on EMDerivation.pdf (55 pages, 869206 bytes). +PDF statistics: + 421 PDF objects out of 1000 (max. 8388607) + 267 compressed objects within 3 object streams + 0 named destinations out of 1000 (max. 500000) + 5 words of extra memory for PDF output out of 10000 (max. 10000000) + diff --git a/vignettes/EMDerivation.pdf b/vignettes/EMDerivation.pdf new file mode 100644 index 0000000..5d5cc56 Binary files /dev/null and b/vignettes/EMDerivation.pdf differ diff --git a/vignettes/EMDerivation.tex b/vignettes/EMDerivation.tex new file mode 100644 index 0000000..47b35a6 --- /dev/null +++ b/vignettes/EMDerivation.tex @@ -0,0 +1,3149 @@ +%\VignetteIndexEntry{EM_Derivation} +%\VignettePackage{MARSS} +\documentclass[]{article} +%set margins to 1in without fullsty + \addtolength{\oddsidemargin}{-.875in} + \addtolength{\evensidemargin}{-.875in} + \addtolength{\textwidth}{1.75in} + + \addtolength{\topmargin}{-.875in} + \addtolength{\textheight}{1.75in} + %\usepackage{fullpage} %more standardized margins + +% choose options for [] as required from the list +% in the Reference Guide, Sect. 2.2 + +\usepackage{Sweave} +\usepackage{multirow} +\usepackage[bottom]{footmisc}% places footnotes at page bottom +\usepackage[round]{natbib} +\usepackage[small]{caption} +%\setkeys{Gin}{width=\textwidth} +%\setkeys{Gin}{width=0.8\textwidth} %make the figs 50 perc textwidth +\setlength{\captionmargin}{0pt} +\setlength{\abovecaptionskip}{0pt} +\setlength{\belowcaptionskip}{15pt} + +% Math stuff +\usepackage{amsmath} % the standard math package +\usepackage{amsfonts} % the standard math package +%%%% bold maths symbol system: +\def\uupsilon{\pmb{\upsilon}} +\def\llambda{\pmb{\lambda}} +\def\bbeta{\pmb{\beta}} +\def\aalpha{\pmb{\alpha}} +\def\zzeta{\pmb{\zeta}} +\def\etaeta{\mbox{\boldmath $\eta$}} +\def\xixi{\mbox{\boldmath $\xi$}} +\def\ep{\mbox{\boldmath $\epsilon$}} +\def\DEL{\mbox{\boldmath $\Delta$}} +\def\PHI{\mbox{\boldmath $\Phi$}} +\def\PI{\mbox{\boldmath $\Pi$}} +\def\LAM{\mbox{\boldmath $\Lambda$}} +\def\LAMm{\mathbb{L}} +\def\GAM{\mbox{\boldmath $\Gamma$}} +\def\OMG{\mbox{\boldmath $\Omega$}} +\def\SI{\mbox{\boldmath $\Sigma$}} +\def\TH{\mbox{\boldmath $\Theta$}} +\def\UPS{\mbox{\boldmath $\Upsilon$}} +\def\XI{\mbox{\boldmath $\Xi$}} +%% Parameters are bold face +\def\ZZ{\mbox{$\mathbf Z$}} \def\zz{\mbox{$\mathbf z$}} +\def\AA{\mbox{$\mathbf A$}} \def\aa{\mbox{$\mathbf a$}} +\def\BB{\mbox{$\mathbf B$}} \def\bb{\mbox{$\mathbf b$}} +\def\CC{\mbox{$\mathbf C$}} \def\cc{\mbox{$\mathbf c$}} +\def\DD{\mbox{$\mathbf D$}} \def\dd{\mbox{$\mathbf d$}} +\def\EE{\mbox{$\mathbf E$}} \def\ee{\mbox{$\mathbf e$}} +\def\FF{\mbox{$\mathbf F$}} \def\ff{\mbox{$\mathbf f$}} +\def\GG{\mbox{$\mathbf G$}} \def\gg{\mbox{$\mathbf g$}} +\def\HH{\mbox{$\mathbf H$}} \def\hh{\mbox{$\mathbf h$}} +\def\II{\mbox{$\mathbf I$}} \def\ii{\mbox{$\mathbf i$}} +\def\IIm{\mbox{$\mathbf I$}} +\def\JJ{\mbox{$\mathbf J$}} +\def\KK{\mbox{$\mathbf K$}} +\def\MM{\mbox{$\mathbf M$}} \def\mm{\mbox{$\mathbf m$}} +\def\OO{\mbox{$\mathbf O$}} +\def\PP{\mbox{$\mathbf P$}} \def\pp{\mbox{$\mathbf p$}} +\def\QQ{\mbox{$\mathbf Q$}} \def\qq{\mbox{$\mathbf q$}} +\def\Qb{\mbox{$\mathbf G$}} \def\Qm{\mathbb{Q}} +\def\RR{\mbox{$\mathbf R$}} \def\rr{\mbox{$\mathbf r$}} +\def\Rb{\mbox{$\mathbf H$}} \def\Rm{\mathbb{R}} +\def\SS{\mbox{$\mathbf S$}} +\def\TT{\mbox{$\mathbf T$}} +\def\UU{\mbox{$\mathbf U$}} \def\uu{\mbox{$\mathbf u$}} +\def\Ub{\mbox{$\mathbf C$}} \def\Ua{\mbox{$\mathbf c$}} \def\Um{\UPS} +%% Random variables in slant +\def\VV{\mbox{$\pmb{V}$}} \def\vv{\mbox{$\pmb{v}$}} +\def\WW{\mbox{$\pmb{W}$}} \def\ww{\mbox{$\pmb{w}$}} +\def\XX{\mbox{$\pmb{X}$}} \def\xx{\mbox{$\pmb{x}$}} +\def\YY{\mbox{$\pmb{Y}$}} \def\yy{\mbox{$\pmb{y}$}} +\def\LL{\mbox{$\pmb{L}$}} \def\ll{\mbox{$\pmb{l}$}} +%% Other stuff +\def\Ab{\mbox{$\mathbf D$}} \def\Aa{\mbox{$\mathbf d$}} \def\Am{\PI} +\def\Ba{\mbox{$\mathbf L$}} \def\Bm{\UPS} \def\Bb{\mbox{$\mathbf J$}} +\def\Ca{\Delta} \def\Cb{\GAM} +\def\Za{\mbox{$\mathbf N$}} \def\Zm{\XI} +\def\Zb{\mbox{$\mathbf M$}} +\def\zer{\mbox{\boldmath $0$}} +\def\E{\,\textup{\textrm{E}}} +\def\vec{\,\textup{\textrm{vec}}} +\def\var{\,\textup{\textrm{var}}} +\def\cov{\,\textup{\textrm{cov}}} +\def\diag{\,\textup{\textrm{diag}}} +\def\trace{\,\textup{\textrm{trace}}} +\def\N{\,\textup{\textrm{N}}} +\def\MVN{\,\textup{\textrm{MVN}}} +\def\EXy{\,\textup{\textrm{E}}_{\text{{\bf XY}}}} +\def\hatxt{\widetilde{\mbox{$\mathbf x$}}_t} +\def\hatxone{\widetilde{\mbox{$\mathbf x$}}_1} +\def\hatxzero{\widetilde{\mbox{$\mathbf x$}}_0} +\def\hatxtm{\widetilde{\mbox{$\mathbf x$}}_{t-1}} +\def\hatxQtm{\widetilde{\mathbb{x}}_{t-1}} +\def\hatyt{\widetilde{\mbox{$\mathbf y$}}_t} +\def\hatyyt{\widetilde{\mbox{$\mathbf y$}\mbox{$\mathbf y$}^\top}_t} +\def\hatyone{\widetilde{\mbox{$\mathbf y$}}_1} +\def\hatwt{\widetilde{\mbox{$\mathbf w$}}_t} +\def\hatOt{\widetilde{\OO}_t} +\def\hatWt{\widetilde{\WW}_t} +\def\hatYXt{\widetilde{\mbox{$\mathbf{y}\mathbf{x}$}}_t} +\def\hatYXttm{\widetilde{\mbox{$\mathbf{y}\mathbf{x}$}}_{t,t-1}} +\def\hatPt{\widetilde{\PP}_t} +\def\hatPtm{\widetilde{\PP}_{t-1}} +\def\hatPQtm{\widetilde{\mathbb{P}}_{t-1}} +\def\hatPttm{\widetilde{\PP}_{t,t-1}} +\def\hatPQttm{\widetilde{\mathbb{P}}_{t,t-1}} +\def\hatPtmt{\widetilde{\PP}_{t-1,t}} +\def\hatVt{\widetilde{\VV}_t} +\def\hatVttm{\widetilde{\VV}_{t,t-1}} +\def\hatBmt{\widetilde{\Bm}_t} +\def\hatCat{\widetilde{\Ca}_t} +\def\hatCbt{\widetilde{\Cb}_t} +\def\hatZmt{\widetilde{\Zm}_t} +\def\YYr{\dot{\mbox{$\pmb{Y}$}}} +\def\yyr{\dot{\mbox{$\pmb{y}$}}} +\def\aar{\dot{\mbox{$\mathbf a$}}} +\def\ZZr{\dot{\mbox{$\mathbf Z$}}} +\def\RRr{\dot{\mbox{$\mathbf R$}}} +\def\IR{\nabla} +\usepackage[round]{natbib} % to get references that are like in ecology papers +% \citet{} for inline citation name (year); \citep for citation in parens (name year) + +%allow lines in matrix +\makeatletter +\renewcommand*\env@matrix[1][*\c@MaxMatrixCols c]{% + \hskip -\arraycolsep + \let\@ifnextchar\new@ifnextchar + \array{#1}} +\makeatother +\setcounter{tocdepth}{1} %no subsections in toc + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +\input{EMDerivation-concordance} +%\SweaveOpts{concordance=TRUE} +\author{Elizabeth Eli Holmes\footnote{Northwest Fisheries Science Center, NOAA Fisheries, Seattle, WA 98112, + eli.holmes@noaa.gov, http://faculty.washington.edu/eeholmes}} +\title{Derivation of an EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models} +\date{original 16 Feb 2013 \\ +{\small \emph{typo in Eqn 124}, 14 Apr 2018 \\ +\emph{added derivation of variance of Y conditioned on y and x}, 3 Feb 2020 \\ +\emph{typo in eqn 29-31}, 20 Oct 2020}} +\maketitle +\begin{abstract} +This report presents an Expectation-Maximization (EM) algorithm for estimation of the maximum-likelihood parameter values of constrained multivariate autoregressive Gaussian state-space (MARSS) models. The MARSS model can be written: x(t)=Bx(t-1)+u+w(t), y(t)=Zx(t)+a+v(t), where w(t) and v(t) are multivariate normal error-terms with variance-covariance matrices Q and R respectively. MARSS models are a class of dynamic linear model and vector autoregressive model state-space model. Shumway and Stoffer presented an unconstrained EM algorithm for this class of models in 1982, and a number of researchers have presented EM algorithms for specific types of constrained MARSS models since then. In this report, I present a general EM algorithm for constrained MARSS models, where the constraints are on the elements within the parameter matrices (B,u,Q,Z,a,R). The constraints take the form vec(M)=f+Dm, where M is the parameter matrix, f is a column vector of fixed values, D is a matrix of multipliers, and m is the column vector of estimated values. This allows a wide variety of constrained parameter matrix forms. The presentation is for a time-varying MARSS model, where time-variation enters through the fixed (meaning not estimated) f(t) and D(t) matrices for each parameter. The algorithm allows missing values in y and partially deterministic systems where 0s appear on the diagonals of Q or R. +\end{abstract} +Keywords: Time-series analysis, Kalman filter, EM algorithm, maximum-likelihood, vector autoregressive model, dynamic linear model, parameter estimation, state-space +\vfill +{\noindent \small citation: Holmes, E. E. 2013. Derivation of the EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models. Technical Report. arXiv:1302.3919 } + \newpage +\section{Overview} + +EM algorithms extend maximum-likelihood estimation to models with hidden states and are widely used in engineering and computer science applications. This report presents an EM algorithm for a general class of Gaussian constrained multivariate autoregressive state-space (MARSS) models, with a hidden multivariate autoregressive process (state) model and a multivariate observation model. This is an important class of time-series model used in many different scientific fields. The reader is referred to \citet{McLachlanKrishnan2008} for general background on EM algorithms and to \citet{Harvey1989} for a discussion of EM algorithms for time-series data. \citet{Borman2009} has a nice tutorial on the EM algorithm. + +Before showing the derivation for the constrained case, I first show a derivation of the EM algorithm for unconstrained\footnote{``unconstrained'' means that each element in the parameter matrix is estimated and no elements are fixed or shared.} MARSS model. This EM algorithm was published by \citet{ShumwayStoffer1982}, but my derivation is more similar to Ghahramani et al's \citep{GhahramaniHinton1996, RoweisGhahramani1999} slightly different presentation. One difference in my presentation and all these previous presentations, however, is that I treat the data as a random variable throughout; this means that there are no ``special" update equations for the missing values case. Another difference is that I present the update equations for both stochastic initial states and fixed initial states. I then extend the derivation to constrained MARSS models where there are fixed and shared elements in the parameter matrices and to the case of degenerate MARSS models where some processes in the model are deterministic rather than stochastic. See also \citet{Wuetal1996} and \citet{Zuuretal2003a} for other examples of the EM algorithm for different classes of constrained MARSS models. + +When working with MARSS models, one should be cognizant that misspecification of the prior on the initial hidden states can have catastrophic and difficult to detect effects on the parameter estimates. There is often no sign that something is amiss with the MLE estimates output by an EM algorithm. There has been much work on how to avoid these initial conditions effects; see especially literature on vector autoregressive state-space models in the economics literature. The trouble often occurs when the prior on the initial states is inconsistent with the distribution of the initial states that is implied by the maximum-likelihood model. This often happens when the model implies a specific covariance structure on the initial states, but since the maximum-likelihood parameters are unknown, this covariance structure is unknown. Using a diffuse prior does not help since your diffuse prior still has some covariance structure (often independence is being imposed). In some ways the EM algorithm is less sensitive to a misspecified prior because it uses the smoothed states conditioned on all the data. However, if the prior is inconsistent with the model, the EM algorithm will not (cannot) find the MLEs. It is very possible however that it will find parameter estimates that are closer to what you intend (estimates uninfluenced by the prior), but they will not be MLEs. The derivation presented here allows one to circumvent these problems by treating the initial states as fixed (and estimated) parameters. The problematic initial state variance-covariance matrix is removed from the model, albeit at the cost of additional estimated parameters. + +Finally, when working with MARSS models, one needs to ensure that the model is identifiable; i.e., a unique solution exists. For a given MARSS model, some of the parameter elements will need to be fixed (not estimated) in order to produce a model with one solution. How to do that depends on the MARSS model being fitted and is up to the user. + +\subsection{The MARSS model} + +The linear MARSS model with a stochastic initial state\footnote{`Stochastic' means the initial state has a distribution rather than a fixed value. Because the process must start somewhere, one needs to specify the initial state. In equation \ref{eq:MARSS}, I show the initial state specified as a distribution. However, the derivation will also discuss the case where the initial state is specified as an unknown fixed parameter.} is +\begin{subequations}\label{eq:MARSS} +\begin{gather} +\xx_t = \BB\xx_{t-1} + \uu + \ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ) \label{eq:MARSSx}\\ +\yy_t = \ZZ\xx_t + \aa + \vv_t, \text{ where } \VV_t \sim \MVN(0,\RR) \label{eq:MARSSy}\\ +\XX_0 \sim \MVN(\xixi,\LAM) \label{eq:MARSSx1} +\end{gather} +\end{subequations} +The $\yy$ equation is called the observation process, and $\yy_t$ is a $n \times 1$ vector. The $\xx$ equation is called the state or process equation, and $\xx_t$ is a $m \times 1$ vector. The equation for $\xx$ describes a multivariate autoregressive process (also called a random walk or Markov process). $\ww$ are the process errors and are specific realizations of the random variable $\WW$; $\vv$ is defined similarly. The initial state can either defined at $t=0$, as is done in equation \ref{eq:MARSS}, or at $t=1$. When presenting the MARSS model, I use $t=0$ but the derivations will show the EM algorithm for both cases. $\QQ$ and $\RR$ are variance-covariance matrices that specify the stochasticity in the observation and state equations. + +In the MARSS model, $\xx$ and $\yy$ equations describe two stochastic processes. By tradition, one conditions on observations of $\yy$, and $\xx$ is treated as completely hidden, hence the name `hidden Markov process' of which a MARSS model is a special type. However, you could condition on (partial) observations of $\xx$ and treat $\yy$ as a (partially) hidden process---with as usual proper constraints to ensure identifiability. Nonetheless in this report, I follow tradition and treat $\xx$ as hidden and $\yy$ as (partially) observed. If $\xx$ is partially observed then the update equations stay the same but the expectations shown in section \ref{sec:compexpectations} would be computed conditioned on the partially observed $\xx$. + +The first part of this report will review the derivation of an EM algorithm for the time-constant MARSS model (equation \ref{eq:MARSS}). However the main objective of this report is to show the derivation of an EM algorithm to solve a much more general MARSS model (section \ref{sec:tvMARSS}), which is a MARSS model with linear constraints on time-varying parameters: +\begin{equation}\label{eq:MARSS.ex} +\begin{gathered} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t, \text{ where } \WW_t \sim \mathrm{MVN}(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \HH_t\vv_t, \text{ where } \VV_t \sim \mathrm{MVN}(0,\RR_t)\\ +\xx_{0} = \xixi + \FF\ll, \text{ where } \ll \sim \mathrm{MVN}(0,\LAM) +\end{gathered} +\end{equation} +The initial state can either defined at $t=0$, as is done in equation \ref{eq:MARSS.ex}, or at $t=1$. + +The linear constraints appear as the vectorization of each parameter ($\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$, $\LAM$) is described by the relation $\ff_t+\DD_t\mm$. This relation specifies linear constraints of the form $\beta_i + \beta_{a,i} a + \beta_{b,i} b + \dots$ on the elements in each MARSS parameter matrix. Equation \ref{eq:MARSS.ex} is a much broader class of MARSS models that includes MARSS models with exogenous variable (covariates), AR-p models, moving average models, constrained MARSS models and models that are combinations of these. The derivation also includes partially deterministic systems where $\GG_t$, $\HH_t$ and $\FF$ may have all zero rows. + +\subsection{The joint log-likelihood function} +Equation \ref{eq:MARSS.ex} describes a multivariate stochastic process and $\YY_t$ and $\XX_t$ are random variables whose distributions are given by Equation \ref{eq:MARSS.ex}. Denote a specific realization of these random variables as $\yy$ and $\xx$ which denotes a set of all $y$'s and $x$'s from $t=1$ to $T$. The joint log-likelihood\footnote{This is not the log likelihood output by the Kalman filter. The log likelihood output by the Kalman filter is the $\log\LL(\yy;\Theta)$ (notice $\xx$ does not appear), which is known as the marginal log likelihood.} of $\yy$ and $\xx$ can then be written then as follows\footnote{The log-likelihood function is shown here for the MARSS with non-time varying parameters (equation \ref{eq:MARSS}).}, where $\XX_t$ denotes the random variable and $\xx_t$ is a realization from that random variable (and similarly for $\YY_t$):\footnote{To alleviate clutter, I have left off subscripts on the $f$'s. To emphasize that the $f$'s represent different density functions, one would often use a subscript showing what parameters are in the functions; i.e., $f(\xx_t|\XX_{t-1}=\xx_{t-1})$ becomes $f_{B,u,Q}(\xx_t|\XX_{t-1}=\xx_{t-1})$.} +\begin{equation} +f(\yy,\xx) = f(\yy|\XX=\xx)f(\xx), +\end{equation} +where +\begin{equation} +\begin{split} +f(\xx)&=f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_1^{t-1}=\xx_1^{t-1})\\ +f(\yy|\XX=\xx) &= \prod_{t=1}^T f(\yy_t|\XX=\xx) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:jointL} +\begin{split}f(\yy,\xx) &= \prod_{t=1}^T f(\yy_t|\XX=\xx) \times f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_1^{t-1}=\xx_1^{t-1}) \\ +&=\prod_{t=1}^T f(\yy_t|\XX_t=\xx_t) \times f(\xx_0)\prod_{t=1}^T f(\xx_t|\XX_{t-1}=\xx_{t-1}). +\end{split} +\end{equation} +Here $\xx_{t1}^{t2}$ denotes the set of $\xx_t$ from $t=t1$ to $t=t2$ (and thus $\xx$ is shorthand for $\xx_1^T$). The third line follows because conditioned on $\xx$, the $\yy_t$'s are independent of each other (because the $\vv_t$ are independent of each other). In the last line, $\xx_1^{t-1}$ becomes $\xx_{t-1}$ from the Markov property of the equation for $\xx_t$ (equation \ref{eq:MARSSx}), and $\xx$ becomes $\xx_t$ because $\yy_t$ depends only on $\xx_t$ (equation \ref{eq:MARSSy}). + +Since $(\XX_t|\XX_{t-1}=\xx_{t-1})$ is multivariate normal and $(\YY_t|\XX_t=\xx_t)$ is multivariate normal (equation \ref{eq:MARSS}), we can write down the joint log-likelihood function using the likelihood function for a multivariate normal distribution \citep[section 4.3]{JohnsonWichern2007}. +\begin{equation}\label{eq:logL} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_1^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ|\\ +&\quad -\frac{1}{2}(\xx_0 - \xixi)^\top \LAM^{-1}(\xx_0 - \xixi) - \frac{1}{2}\log |\LAM| - \frac{n}{2}\log 2\pi +\end{split} +\end{equation} +$n$ is the number of data points. This is the same as equation 6.64 in \citet{ShumwayStoffer2006}. The above equation is for the case where $\xx_0$ is stochastic (has a known distribution). However, if we instead treat $\xx_0$ as fixed but unknown (section 3.4.4 in Harvey, 1989), it is then a parameter and there is no $\LAM$. The likelihood then is slightly different. $\xx_0$ is defined as a parameter $\xixi$ and +\begin{equation}\label{eq:logL.V0.is.0} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_1^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ| +\end{split} +\end{equation} +$\xixi$ appears in the likelihood for $\xx_{t-1}$ when $t=1$ in the summation. Note that in this case, $\xx_0$ is no longer a realization of a random variable $\XX_0$; it is a fixed (but unknown) parameter. Equation \ref{eq:logL.V0.is.0} is written as if all the $\xx_0$ are fixed, however when the general derivation is presented, it is allowed that some $\xx_0$ are fixed ($\LAM$=0) and others are stochastic. + +If $\RR$ is constant through time, then $\sum_1^T\frac{1}{2} \log |\RR|$ in the likelihood equation reduces to $\frac{T}{2}\log |\RR|$, however $\RR$ might be time-varying or one may need to include a time-dependent weighting on $\RR$\footnote{If for example, one wanted to include a temporally dependent weighting on $\RR$ replace $|\RR|$ with $|\alpha_t\RR|=\alpha_t^n|\RR|$, where $\alpha_t$ is the weighting at time $t$ and is fixed not estimated.}. The same applies to $\sum_1^T\frac{1}{2}\log |\QQ|$. + +All bolded elements are column vectors (lower case) and matrices (upper case). $\AA^\top$ is the transpose of matrix $\AA$, $\AA^{-1}$ is the inverse of $\AA$, and $|\AA|$ is the determinant of $\AA$. Parameters are non-italic while elements that are slanted are realizations of a random variable ($\xx$ and $\yy$ are slated)\footnote{In matrix algebra, a capitol bolded letter indicates a matrix. Unfortunately in statistics, the capitol letter convention is used for random variables. Fortunately, this derivation does not need to reference random variables except indirectly when using expectations. Thus, I use capitols to refer to matrices not random variables. The one exception is the reference to $\XX$ and $\YY$. In this case a bolded {\it slanted} capitol is used.} + +\subsection{Missing values}\label{sec:missing} +In Shumway and Stoffer and other presentations of the EM algorithm for MARSS models \citep{ShumwayStoffer2006,Zuuretal2003a}, the missing values case is treated separately from the non-missing values case. In these derivations, a series of modifications are given for the EM update equations when there are missing values. In my derivation, I present the missing values treatment differently, and there is only one set of update equations and these equations apply in both the missing values and non-missing values cases. My derivation does this by keeping $\E[\YY_t|\text{data}]$ and $\E[\YY_t\XX_t^\top|\text{data}]$ in the update equations (much like $\E[\XX_t|\text{data}]$ is kept in the equations) while Shumway and Stoffer replace these expectations involving $\YY_t$ by their values, which depend on whether or not the data are a complete observation of $\YY_t$ with no missing values. Section \ref{sec:compexpectations} shows how to compute the expectations involving $\YY_t$ when the data are an incomplete observation of $\YY_t$. + +\section{The EM algorithm}\label{sec:EMalgorithm} +The EM algorithm cycles iteratively between an expectation step (the integration in the equation) followed by a maximization step (the arg max in the equation): +\begin{equation}\label{eq:EMalg} +\Theta_{j+1} = \arg \underset{\Theta}{\max} \int_{\xx}{\int_{\yy}{\log\LL(\xx,\yy;\Theta) f(\xx,\yy|\YY(1)=\yy(1),\Theta_j)d\xx d\yy}} +\end{equation} +$\YY(1)$ indicates those $\YY$ that have an observation and $\yy(1)$ are the actual observations. Note that $\Theta$ and $\Theta_j$ are different. If $\Theta$ consists of multiple parameters, we can also break this down into smaller steps. Let $\Theta=\{\alpha,\beta\}$, then +\begin{equation}\label{eq:EMalg.j} +\alpha_{j+1} = \arg \underset{\alpha}{\max} \int_{\xx}{\int_{\yy}{\log\LL(\xx,\yy,\beta_j;\alpha) f(\xx,\yy|\YY(1)=\yy(1),\alpha_j,\beta_j)d\xx d\yy}} +\end{equation} +Now the maximization is only over $\alpha$, the part that appears after the ``;'' in the log-likelihood. + +\textbf{Expectation step} The integral that appears in equation \ref{eq:EMalg} is an expectation. The first step in the EM algorithm is to compute this expectation. This will involve computing expectations like $\E[\XX_t\XX_t^\top|\YY_t(1)=\yy_t(1),\Theta_j]$ and $\E[\YY_t\XX_t^\top|\YY_t(1)=\yy_t(1),\Theta_j]$. The $j$ subscript on $\Theta$ denotes that these are the parameters at iteration $j$ of the algorithm. + +\textbf{Maximization step}: A new parameter set $\Theta_{j+1}$ is computed by finding the parameters that maximize the \textit{expected} log-likelihood function (the part in the integral) with respect to $\Theta$. The equations that give the parameters for the next iteration ($j+1$) are called the update equations and this report is devoted to the derivation of these update equations. + +After one iteration of the expectation and maximization steps, the cycle is then repeated. New expectations are computed using $\Theta_{j+1}$, and then a new set of parameters $\Theta_{j+2}$ is generated. This cycle is continued until the likelihood no longer increases more than a specified tolerance level. This algorithm is guaranteed to increase in likelihood at each iteration (if it does not, it means there is an error in one's update equations). The algorithm must be started from an initial set of parameter values $\Theta_1$. The algorithm is not particularly sensitive to the initial conditions but the surface could definitely be multi-modal and have local maxima. See section \ref{sec:implementation} on using Monte Carlo initialization to ensure that the global maximum is found. + +\textbf{Dividing the parameters into parts}: Above the parameter set is written as $\Theta$. However $\Theta$ is composed of multiple components: $\BB$, $\uu$, $\RR$, etc. The EM iteration $j$ is broken into subparts for each parameter matrix and both the maximization and expectation steps are done for each part. For example, the expectation step is run with parameters $\{\BB_j, \uu_j, \RR_j, \dots\}$ and then $\BB$ is updated to $\BB_{j+1}$ with the maximization step. The expectation step is run with parameters $\{\BB_{j+1}, \uu_j, \RR_j, \dots \}$ and the $\uu$is updated to $\uu_{j+1}$ with the maximization step. The expectation step is run with parameters $\{\BB_{j+1}, \uu_{j+1}, \RR_j, \dots \}$ and the $\RR$ is updated. This is continued until all parameters in $\Theta$ are updated and that completes the $j+1$ update. + +\subsection{The expected log-likelihood function}\label{sec:expLL} +The function that is maximized in the ``M'' step is the expected value of the log-likelihood function. This expectation is conditioned on two things: 1) the observed $\YY$'s which are denoted $\YY(1)$ and which are equal to the fixed values $\yy(1)$ and 2) the parameter set $\Theta_j$. Note that since there may be missing values in the data, $\YY(1)$ can be a subset of $\YY$, that is, only some $\YY$ have a corresponding $\yy$ value at time $t$. Mathematically what we are doing is $\EXy[g(\XX,\YY)|\YY(1)=\yy(1),\Theta_j]$. This is a multivariate conditional expectation because $\XX,\YY$ is multivariate (a $m \times n \times T$ vector). The function $g(\Theta)$ that we are taking the expectation of is $\log\LL(\YY,\XX ; \Theta)$. Note that $g(\Theta)$ is a random variable involving the random variables, $\XX$ and $\YY$, while $\log\LL(\yy,\xx ; \Theta)$ is not a random variable but rather a specific value since $\yy$ and $\xx$ are a set of specific values. + +We denote this expected log-likelihood by $\Psi$. The goal is to find the $\Theta$ that maximize $\Psi$ and this becomes the new $\Theta$ for the $j+1$ iteration of the EM algorithm. The equations to compute the new $\Theta$ are termed the update equations. Using the log likelihood equation \ref{eq:logL} and expanding out all the terms, we can write out $\Psi$ in verbose form as: +\begin{equation}\label{eq:expLL} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta);\YY(1)=\yy(1),\Theta_j] = \Psi = \\ +&\quad -\frac{1}{2}\sum_1^T\bigg( \E[\YY_t^\top \RR^{-1} \YY_t] - \E[\YY_t^\top \RR^{-1}\ZZ\XX_t] - \E[(\ZZ\XX_t)^\top\RR^{-1}\YY_t] - \E[\aa^\top\RR^{-1}\YY_t] - \E[\YY_t^\top\RR^{-1}\aa]\\ +&\quad + \E[(\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t] + \E[\aa^\top\RR^{-1}\ZZ\XX_t] + \E[(\ZZ\XX_t)^\top\RR^{-1}\aa] + \E[\aa^\top\RR^{-1}\aa]\bigg) + - \frac{T}{2}\log|\RR|\\ +&\quad - \frac{1}{2}\sum_1^T\bigg(\E[\XX_t^\top\QQ^{-1}\XX_t] - \E[\XX_t^\top\QQ^{-1}\BB\XX_{t-1}] - \E[(\BB\XX_{t-1})^\top\QQ^{-1}\XX_t]\\ +&\quad - \E[\uu^\top\QQ^{-1}\XX_t] - \E[\XX_t^\top\QQ^{-1}\uu] + \E[(\BB\XX_{t-1})^\top\QQ^{-1}\BB\XX_{t-1}]\\ +&\quad + \E[\uu^\top\QQ^{-1}\BB\XX_{t-1}] + \E[(\BB\XX_{t-1})^\top\QQ^{-1}\uu] + \uu^\top\QQ^{-1}\uu\bigg) - \frac{T}{2}\log|\QQ| \\ +&\quad - \frac{1}{2}\bigg(\E[\XX_0^\top\VV_0^{-1}\XX_0] - \E[\xixi^\top\LAM^{-1}\XX_0] - \E[\XX_0^\top\LAM^{-1}\xixi] + \xixi^\top\LAM^{-1}\xixi\bigg) - \frac{1}{2}\log|\LAM| +-\frac{n}{2}\log\pi +\end{split} +\end{equation} +All the $\E[\quad]$ appearing here denote $\EXy[g()|\YY(1)=\yy(1),\Theta_j]$. In the rest of the derivation, I drop the conditional and the $XY$ subscript on $\E$ to remove clutter, but it is important to remember that whenever $\E$ appears, it refers to a specific conditional multivariate expectation. If $\xx_0$ is treated as fixed, then $\XX_0=\xixi$ and the last line involving $\LAM$ is dropped but it will appear in place of $\XX_{t-1}$ when $t=1$ in the summation. + +Keep in mind that $\Theta$ and $\Theta_j$ are different. $\Theta$ is a parameter appearing in function $g(\XX,\YY,\Theta)$, i.e., the parameters in equation \ref{eq:logL}. $\XX$ and $\YY$ are random variables which means that $g(\XX,\YY,\Theta)$ is a random variable. We take the expectation of $g(\XX,\YY,\Theta)$, meaning we take integral over the joint distribution of $\XX$ and $\YY$. We need to specify what that distribution is and the conditioning on $\Theta_j$ (meaning the $\Theta_j$ appearing to the right of the $|$ in $\E[g()|\Theta_j]$) is specifying this distribution. This conditioning affects the value of the expectation of $g(\XX,\YY,\Theta)$, but it does not affect the value of $\Theta$, which are the $\RR$, $\QQ$, $\uu$, etc. values on the right side of equation \ref{eq:expLL}. We will first take the expectation of $g(\XX,\YY,\Theta)$ conditioned on $\Theta_j$ (using integration) and then take the differential of that expectation with respect to $\Theta$. + +\subsection{The expectations used in the derivation}\label{sec:expectations} +The following expectations appear frequently in the update equations and are given special names\footnote{This notation is different than what you see in Shumway and Stoffer (2006), section 6.2. What I call $\hatVt$, they refer to as $P_t^n$, and my $\hatPt$ would be $P_t^n + \hatxt \hatxt^\prime$ in their notation.}: +\begin{subequations}\label{eq:expectations} +\begin{align} +&\hatxt = \EXy[\XX_t | \YY(1)=\yy(1), \Theta_j]\\ +&\hatyt = \EXy[\YY_t | \YY(1)=\yy(1), \Theta_j]\\ +&\hatPt=\EXy[\XX_t\XX_t^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatPttm=\EXy[\XX_{t}\XX_{t-1}^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatVt = \var_{XY}[\XX_t|\YY(1)=\yy(1), \Theta_j] = \hatPt-\hatxt\hatxt^\top\label{eq:hatVt}\\ +&\hatOt=\EXy[\YY_t\YY_t^\top | \YY(1)=\yy(1), \Theta_j]\\ +&\hatWt = \var_{XY}[\YY_t|\YY(1)=\yy(1), \Theta_j] = \hatOt-\hatyt\hatyt^\top\label{eq:hatWt}\\ +&\hatYXt = \EXy[\YY_t\XX_t^\top| \YY(1)=\yy(1), \Theta_j]\\ +&\hatYXttm = \EXy[\YY_t\XX_{t-1}^\top| \YY(1)=\yy(1), \Theta_j] +\end{align} +\end{subequations} +The subscript on the expectation, $\E$, denotes that this is a multivariate expectation taken over $\XX$ and $\YY$. The right sides of equations \ref{eq:hatVt} and \ref{eq:hatWt} arise from the computational formula for variance and covariance: +\begin{align}\label{eq:comp.formula.variance} +\var[X] &= \E[XX^\top] - \E[X]\E[X]^\top\\ +\cov[X,Y] &= \E[XY^\top] - \E[X]\E[Y]^\top. +\end{align} +Section \ref{sec:compexpectations} shows how to compute the expectations in equation \ref{eq:expectations}. + +\begin{table} + \caption{Notes on multivariate expectations. For the following examples, let $\XX$ be a vector of length three, $X_1,X_2,X_3$. $f()$ is the probability distribution function (pdf). $C$ is a constant (not a random variable).} + \label{tab:MultivariateExpectations} +\begin{center}\begin{tabular}{lr} +\hline\\ +$\E_X[g(\XX)]=\int{\int{\int{g(\xx)f(x_1,x_2,x_3) dx_1 dx_2 dx_3}}}$\\ +$\E_X[X_1]=\int{\int{\int{x_1 f(x_1,x_2,x_3) dx_1 dx_2 dx_3}}}=\int{x_1 f(x_1) dx_1}=\E[X_1]$ \\ +$\E_X[X_1+X_2]=\E_X[X_1]+\E_X[X_2]$\\ +$\E_X[X_1+C]=\E_X[X_1]+C$\\ +$\E_X[C X_1]=C\E_X[X_1]$\\ +$\E_X[\XX|\XX=\xx]=\xx$ \\ +\\ +\hline +\end{tabular} +\end{center} +\end{table} + +\section{The unconstrained update equations}\label{sec:generalupdate} +In this section, I show the derivation of the update equations when all elements of a parameter matrix are estimated and are all allowed to be different, i.e., the unconstrained case. These are similar to the update equations one will see in \citet{ShumwayStoffer2006}. Section \ref{sec:constrained} shows the update equations when there are unestimated (fixed) or estimated but shared values in the parameter matrices, i.e., the constrained update equations. + +To derive the update equations, one must find the $\Theta$, where $\Theta$ is comprised of the MARSS parameters $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$, and $\LAM$, that maximizes $\Psi$ (equation \ref{eq:expLL}) by partial differentiation of $\Psi$ with respect to $\Theta$. However, I will be using the EM equation where one maximizes each parameter matrix in $\Theta$ one-by-one (equation \ref{eq:EMalg.j}). In this case, the parameters that are not being maximized are fixed (and set at their current iteration value), and then one takes the derivative of $\Psi$ with respect to the parameter of interest. Then solve for the parameter value that sets the partial derivative to zero. The partial differentiation is with respect to each individual parameter element, for example each $u_{i,j}$ in matrix $\uu$. The idea is to single out those terms in equation \ref{eq:expLL} that involve $u_{i,j}$ (say), differentiate by $u_{i,j}$, set this to zero and solve for $u_{i,j}$. This gives the new $u_{i,j}$ that maximizes the partial derivative with respect to $u_{i,j}$ of the expected log-likelihood. Matrix calculus gives us a way to jointly maximize $\Psi$ with respect to all elements (not just element $i,j$) in a parameter matrix. + +Note, see the comments on the EM algorithm implementation (Section \ref{sec:EMalgorithm}) when the parameter set $\Theta$ is broken into parts (e.g., $\BB$, $\uu$, $\QQ$, etc.). In the implementation of the algorithm, one updates the $\Theta$ parts sequentially and the expectation step is re-run with the new $\Theta$ at each step (meaning the Kalman smoother is re-run with the updated parameters). Thus the algorithm is applied as follows (order that the parameters are updated is unimportant): E-step with $\{\BB_j, \uu_j, \QQ_j, etc.\}$, M-step updates $\BB_j$ to $\BB_{j+1}$, E-step with $\{\BB_{j+1}, \uu_j, \QQ_j, etc.\}$, M-step updates $\uu_j$ to $\uu_{j+1}$, E-step with $\{\BB_{j+1}, \uu_{j+1}, \QQ_j, etc.\}$, M-step updates $\QQ_j$ to $\QQ_{j+1}$, continuing until all parameters are updates which completes the $j+1$ update. + +\subsection{Matrix calculus need for the derivation}\label{sec:MatrixDerivatives} +A number of derivatives of a scalar with respect to vectors and matrices will be needed in the derivation and are shown in table \ref{tab:MatrixDerivatives}. The partial derivative of a scalar ($\Psi$ is a scalar) with respect to some column vector $\bb$ (which has elements $b_1$, $b_2$ . . .) is +\begin{equation*} +\frac{\partial\Psi}{\partial\bb}= +\begin{bmatrix} +\dfrac{\partial\Psi}{\partial b_1}& \dfrac{\partial\Psi}{\partial b_2}& \cdots& \dfrac{\partial\Psi}{\partial b_m} +\end{bmatrix} +\end{equation*} + Note that the derivative of scalar with respect to a column vector $\bb$ is a row vector. The partial derivatives of a scalar with respect to some $m \times m$ matrix $\BB$ is +\begin{equation*} +\frac{\partial\Psi}{\partial\BB}= +\begin{bmatrix} +\dfrac{\partial\Psi}{\partial b_{1,1}}& \dfrac{\partial\Psi}{\partial b_{2,1}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,1}}\\ +\\ +\dfrac{\partial\Psi}{\partial b_{1,2}}& \dfrac{\partial\Psi}{\partial b_{2,2}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,2}}\\ +\\ +\cdots& \cdots& \cdots& \cdots\\ +\\ +\dfrac{\partial\Psi}{\partial b_{1,m}}& \dfrac{\partial\Psi}{\partial b_{2,m}}& \cdots& \dfrac{\partial\Psi}{\partial b_{m,m}}\\ +\end{bmatrix} +\end{equation*} +Note that the indexing is interchanged; $\partial\Psi/\partial b_{i,j}=\big[\partial\Psi/\partial\BB\big]_{j,i}$. For $\QQ$ and $\RR$, this is unimportant because they are variance-covariance matrices and are symmetric. For $\BB$ and $\ZZ$, one must be careful because these may not be symmetric. The partial derivatives of a column vector $\aa$ with respect to a column vector $\bb$. +\begin{equation*} +\frac{\partial\Psi}{\partial\BB}= +\begin{bmatrix} +\dfrac{\partial a_1}{\partial b_1}& \dfrac{\partial a_1}{\partial b_2}& \cdots& \dfrac{\partial a_1}{\partial b_m}\\ +\\ +\dfrac{\partial a_2}{\partial b_1}& \dfrac{\partial\Psi}{\partial b_2}& \cdots& \dfrac{\partial a_2}{\partial b_m}\\ +\\ +\cdots& \cdots& \cdots& \cdots\\ +\\ +\dfrac{\partial a_n}{\partial b_1}& \dfrac{\partial a_n}{\partial b_2}& \cdots& \dfrac{\partial a_n}{\partial b_m}\\ +\end{bmatrix} +\end{equation*} + +In table \ref{tab:MatrixDerivatives}, both the vectorized and non-vectorized versions are shown. The vectorized version of a matrix $\DD$ with dimension $n \times m$ is +\begin{gather*} +\vec(\DD_{n,m})\equiv +\begin{bmatrix} +d_{1,1}\\ +\cdots\\ +d_{n,1}\\ +d_{1,2}\\ +\cdots\\ +d_{n,2}\\ +\cdots\\ +d_{1,m}\\ +\cdots\\ +d_{n,m} +\end{bmatrix}\\ +\end{gather*} + + +\begin{table} + \caption{Derivatives of a scalar with respect to vectors and matrices. In the following $a$ is a scalar (unrelated to $\aa$), $\aa$ and $\cc$ are $n \times 1$ column vectors, $\bb$ and $\dd$ are $m \times 1$ column vectors, $\DD$ is a $n \times m$ matrix, $\CC$ is a $n \times n$ matrix, and $\AA$ is a diagonal $n \times n$ matrix (0s on the off-diagonals). $\CC^{-1}$ is the inverse of $\CC$, $\CC^\top$ is the transpose of $\CC$, $\CC^{-\top} = \big(\CC^{-1}\big)^\top = \big(\CC^\top\big)^{-1}$, and $|\CC|$ is the determinant of $\CC$. Note, all the numerators in the differentials on the far left reduce to scalars. Although the matrix names may be the same as those of matrices referred to in the text, the matrices in this table are dummy matrices used to show the matrix derivative relations.} + \label{tab:MatrixDerivatives} +\begin{center}\begin{tabular}{lr} +\hline +\\ +\refstepcounter{equation}\label{eq:derivproductrule} +$\partial(\ff^\top\gg)/\partial\aa = \ff^\top\partial\gg/\partial\aa + \gg^\top\partial\ff/\partial\aa$ +& \multirow{2}{*}{(\theequation)} \\ +$\ff=f(\aa)$ and \gg=$g(\aa)$ are $m \times 1$ column vectors and functions of $\aa$. & \\ +$\partial a /\partial\aa = \frac{1}{m} \partial a /\partial \gg \, \partial\gg/\partial\aa$ +&\\ +$\partial \ff /\partial\aa = \frac{1}{m} \partial \ff /\partial \gg \, \partial\gg/\partial\aa$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivaTc} +$\partial(\aa^\top\cc)/\partial\aa = \partial(\cc^\top\aa)/\partial\aa = \cc^\top$ & \multirow{2}{*}{(\theequation)} \\ +$\partial \aa/\partial \aa = \partial(\aa^\top)/\partial \aa = \II_n$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivaTDb} +$\partial(\aa^\top\DD\bb)/\partial\DD = \partial(\bb^\top\DD^\top\aa)/\partial\DD = \bb\aa^\top$ +& \multirow{2}{*}{(\theequation)} \\ +$\partial(\aa^\top\DD\bb)/\partial\vec(\DD) = \partial(\bb^\top\DD^\top\aa)/\partial\vec(\DD) = \big(\vec(\bb\aa^\top)\big)^\top$ +&\\ +\\ +\refstepcounter{equation}\label{eq:derivlogDet} +$\CC$ is invertible.& \multirow{6}{*}{(\theequation)} \\ +$\partial(\log |\CC|)/\partial\CC = -\partial(\log |\CC^{-1}|)/\partial\CC=(\CC^\top)^{-1} = \CC^{-\top}$\\ +$\partial(\log |\CC|)/\partial\vec(\CC) = \big(\vec(\CC^{-\top})\big)^\top$& \\ +If $\CC$ is also symmetric and $\BB$ is not a function of $\CC$.& \\ +$\partial(\log |\CC^\top\BB\CC|)/\partial\CC = 2\CC^{-1}$\\ +$\partial(\log |\CC^\top\BB\CC|)/\partial\vec(\CC) = 2\big(\vec(\CC^{-1})\big)^\top$\\ +\\ +\refstepcounter{equation}\label{eq:derivbDTCDd} +$\partial(\bb^\top\DD^\top\CC\DD\dd)/\partial\DD = \dd\bb^\top\DD^\top\CC + \bb\dd^\top\DD^\top\CC^\top$ +& \multirow{3}{*}{(\theequation)} \\ +$\partial(\bb^\top\DD^\top\CC\DD\dd)/\partial\vec(\DD) = +\big(\vec(\dd\bb^\top\DD^\top\CC + \bb\dd^\top\DD^\top\CC^\top)\big)^\top $ &\\ +If $\bb=\dd$ and $\CC$ is symmetric then the sum reduces to $2\bb\bb^\top\DD^\top\CC$ & \\ +\\ +\refstepcounter{equation}\label{eq:derivaTCa} +$\partial(\aa^\top\CC\aa)/\partial\aa = \partial(\aa\CC^\top\aa^\top)/\partial\aa = 2\aa^\top\CC$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:derivInv} +$\partial(\aa^\top\CC^{-1}\cc)/\partial\CC = -\CC^{-1}\aa\cc^\top\CC^{-1} $ +& \multirow{2}{*}{(\theequation)} \\ +$\partial(\aa^\top\CC^{-1}\cc)/\partial\vec(\CC) = -\big(\vec(\CC^{-1}\aa\cc^\top\CC^{-1})\big)^\top$ & \\ +\\ +\hline +\end{tabular}\end{center} +\end{table} + +\subsection{The update equation for $\uu$ (unconstrained)} +Take the partial derivative of $\Psi$ with respect to $\uu$, which is a $m \times 1$ matrix. All parameters other than $\uu$ are fixed to constant values (because partial derivation is being done). Since the derivative of a constant is 0, terms not involving $\uu$ will equal 0 and drop out. Taking the derivative to equation \ref{eq:expLL} with respect to $\uu$: +\begin{equation}\label{eq:u.unconstrained1} +\begin{split} +&\partial\Psi/\partial\uu = - \frac{1}{2}\sum_{t=1}^T \bigg(- \partial(\E[\XX_t^\top\QQ^{-1}\uu])/\partial\uu +- \partial(\E[\uu^\top\QQ^{-1}\XX_t])/\partial\uu \\ +&\quad + \partial(\E[(\BB\XX_{t-1})^\top\QQ^{-1}\uu])/\partial\uu ++ \partial(\E[\uu^\top\QQ^{-1}\BB\XX_{t-1}])/\partial\uu + \partial(\uu^\top\QQ^{-1}\uu)/\partial\uu \bigg) +\end{split} +\end{equation} +The parameters can be moved out of the expectations and then the matrix derivative relations (table \ref{tab:MatrixDerivatives}) are used to take the derivative. +\begin{equation}\label{eq:u.unconstrained2} +\begin{split} +\partial\Psi/\partial\uu = - \frac{1}{2}\sum_{t=1}^T\bigg(- \E[\XX_t]^\top\QQ^{-1} +- \E[\XX_t]^\top\QQ^{-1} + (\BB\E[\XX_{t-1}])^\top\QQ^{-1} + (\BB\E[\XX_{t-1}])^\top\QQ^{-1} + 2\uu^\top\QQ^{-1} \bigg) +\end{split} +\end{equation} +This also uses $\QQ^{-1} = (\QQ^{-1})^\top$. This can then be reduced to +\begin{equation}\label{eq:u.unconstrained3} +\begin{split} +&\partial\Psi/\partial\uu = \sum_{t=1}^T\big(\E[\XX_t]^\top\QQ^{-1} + - \E[\XX_{t-1}]^\top\BB^\top\QQ^{-1} - \uu^\top\QQ^{-1} \big) +\end{split} +\end{equation} +Set the left side to zero (a $p \times m$ matrix of zeros) and transpose the whole equation. $\QQ^{-1}$ cancels out\footnote{$\QQ$ is a variance-covariance matrix and is invertible. $\QQ^{-1}\QQ=\II$, the identity matrix.} by multiplying on the left by $\QQ$ (left since the whole equation was just transposed), giving +\begin{equation}\label{eq:u.unconstrained4} +\mathbf{0} = \sum_{t=1}^T\big(\E[\XX_t] - \BB\E[\XX_{t-1}] - \uu \big) += \sum_{t=1}^T\big(\E[\XX_t] - \BB\E[\XX_{t-1}] \big) - \uu +\end{equation} +Solving for $\uu$ and replacing the expectations with their names from equation \ref{eq:expectations}, gives us the new $\uu$ that maximizes $\Psi$, +\begin{equation}\label{eq:uupdate.unconstrained} +\uu_{j+1} = \frac{1}{T} \sum_{t=1}^T\big(\hatxt - \BB\hatxtm \big) +\end{equation} + +\subsection{The update equation for $\BB$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\BB$. Terms not involving $\BB$, equal 0 and drop out. I have put the $\E$ outside the partials by noting that $\partial(\E[h(\XX_t,\BB)])/\partial\BB=\E[\partial(h(\XX_t,\BB))/\partial\BB]$ since the expectation is conditioned on $\BB_j$ not $\BB$. +\begin{equation}\label{eq:B.unconstrained1} +\begin{split} +&\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB] \\ +&\quad - \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\XX_t)/\partial\BB] + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}(\BB\XX_{t-1}))/\partial\BB] \\ +&\quad + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\uu)/\partial\BB] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB]\bigg)\\ +&= -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1}])/\partial\BB] \\ +&\quad - \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}\XX_t)/\partial\BB] ++ \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}(\BB\XX_{t-1}))/\partial\BB] \\ +&\quad + \E[\partial(\XX_{t-1}^\top\BB^\top\QQ^{-1}\uu)/\partial\BB] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\BB\bigg)]\\ +\end{split} +\end{equation} +After pulling the constants out of the expectations, we use relations \ref{eq:derivaTDb} and \ref{eq:derivbDTCDd} to take the derivative and note that $\QQ^{-1} = (\QQ^{-1})^\top$: +\begin{equation}\label{eq:B.unconstrained2} +\begin{split} +&\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\XX_{t-1}\XX_t^\top]\QQ^{-1} - \E[ \XX_{t-1}\XX_t^\top]\QQ^{-1} \\ +&\quad + 2 \E[\XX_{t-1}\XX_{t-1}^\top]\BB^\top\QQ^{-1} + \E[\XX_{t-1}]\uu^\top\QQ^{-1} + \E[\XX_{t-1}]\uu^\top\QQ^{-1} \bigg) \\ +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{eq:B.unconstrained3} +\partial\Psi/\partial\BB = -\frac{1}{2} \sum_{t=1}^T\bigg(-2\E[\XX_{t-1}\XX_t^\top]\QQ^{-1} + 2 \E[\XX_{t-1}\XX_{t-1}^\top ]\BB^\top\QQ^{-1} ++ 2\E[\XX_{t-1}]\uu^\top\QQ^{-1} \bigg) +\end{equation} +Set the left side to zero (an $m \times m$ matrix of zeros), cancel out $\QQ^{-1}$ by multiplying by $\QQ$ on the right, get rid of the -1/2, and transpose the whole equation to give +\begin{equation}\label{eq:B.unconstrained4} +\begin{split} +&\mathbf{0} = \sum_{t=1}^T\big(\E[\XX_t\XX_{t-1}^\top] - \BB \E[\XX_{t-1}\XX_{t-1}^\top] - \uu \E[\XX_{t-1}^\top]\big)\\ +&\quad = \sum_{t=1}^T \big( \hatPttm - \BB \hatPtm - \uu \hatxtm^\top \big) +\end{split} +\end{equation} +The last line replaced the expectations with their names shown in equation \ref{eq:expectations}. +Solving for $\BB$ and noting that $\hatPtm$ is like a variance-covariance matrix and is invertible, gives us the new $\BB$ that maximizes $\Psi$, +\begin{equation}\label{eq:B.update.unconstrained} +\BB_{j+1}= \bigg( \sum_{t=1}^T \big( \hatPttm - \uu \hatxtm^\top \big)\bigg) \bigg(\sum_{t=1}^T \hatPtm\bigg)^{-1} +\end{equation} + +Because all the equations above also apply to block-diagonal matrices, the derivation immediately generalizes to the case where $\BB$ is an unconstrained block diagonal matrix: +\begin{equation*} +\BB = +\begin{bmatrix} +b_{1,1}&b_{1,2}&b_{1,3}&0&0&0&0&0\\ +b_{2,1}&b_{2,2}&b_{2,3}&0&0&0&0&0\\ +b_{3,1}&b_{3,2}&b_{3,3}&0&0&0&0&0\\ +0&0&0&b_{4,4}&b_{4,5}&0&0&0\\ +0&0&0&b_{5,4}&b_{5,5}&0&0&0\\ +0&0&0&0&0&b_{6,6}&b_{6,7}&b_{6,8}\\ +0&0&0&0&0&b_{7,6}&b_{7,7}&b_{7,8}\\ +0&0&0&0&0&b_{8,6}&b_{8,7}&b_{8,8} +\end{bmatrix} += +\begin{bmatrix} +\BB_1&0&0\\ +0&\BB_2&0\\ +0&0&\BB_3\\ +\end{bmatrix} +\end{equation*} + +For the block diagonal $\BB$, +\begin{equation}\label{eq:B.update.blockdiag} +\BB_{i,j+1}= \bigg( \sum_{t=1}^T \big( \hatPttm - \uu \hatxtm^\top \big) \bigg)_i \bigg(\sum_{t=1}^T \hatPtm \bigg)_i^{-1} +\end{equation} +where the subscript $i$ means to take the parts of the matrices that are analogous to $\BB_i$; take the whole part within the parentheses not the individual matrices inside the parentheses. If $\BB_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\BB$, then take rows $a$ to $b$ and columns $c$ to $d$ of the matrices subscripted by $i$ in equation \ref{eq:B.update.blockdiag}. + +\subsection{The update equation for $\QQ$ (unconstrained)} +\label{subsec:Qunconstrained} +The usual way to do this derivation is to use what is known as the ``trace trick'' which will pull the $\QQ^{-1}$ out to the left of the $\cc^\top\QQ^{-1}\bb$ terms which appear in the likelihood (equation \ref{eq:expLL}). Here I'm showing a less elegant derivation that plods step by step through each of the likelihood terms. Take the derivative of $\Psi$ with respect to $\QQ$. Terms not involving $\QQ$ equal 0 and drop out. Again the expectations are placed outside the partials by noting that $\partial(\E[h(\XX_t,\QQ)])/\partial\QQ=\E[\partial(h(\XX_t,\QQ))/\partial\QQ]$. +\begin{equation}\label{eq:Q.unconstrained1} +\begin{split} +&\partial\Psi/\partial\QQ = -\frac{1}{2} \sum_{t=1}^T\bigg( +\E[\partial(\XX_t^\top\QQ^{-1}\XX_t)/\partial\QQ] +-\E[\partial(\XX_t^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ] \\ +&\quad -\E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\XX_t)/\partial\QQ ] + - \E[\partial(\XX_t^\top\QQ^{-1}\uu)/\partial\QQ] \\ +&\quad - \E[\partial(\uu^\top\QQ^{-1}\XX_t)/\partial\QQ] ++ \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ] \\ +&\quad + \E[\partial((\BB\XX_{t-1})^\top\QQ^{-1}\uu)/\partial\QQ] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\XX_{t-1})/\partial\QQ]\\ +&\quad +\partial(\uu^\top\QQ^{-1}\uu)/\partial\QQ +\bigg) - \partial\bigg(\frac{T}{2}\log |\QQ| \bigg)/\partial\QQ \\ +\end{split} +\end{equation} +The relations \eqref{eq:derivInv} and \eqref{eq:derivlogDet} are used to do the differentiation. Notice that all the terms in the summation are of the form $\cc^\top\QQ^{-1}\bb$, and thus after differentiation, all the $\cc^\top\bb$ terms can be grouped inside one set of parentheses. Also there is a minus that comes from equation \ref{eq:derivInv} and it cancels out the minus in front of the initial $-1/2$. +\begin{equation}\label{eq:Q.unconstrained2} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \E[\XX_t\XX_t^\top] -\E[\XX_t(\BB\XX_{t-1})^\top ] - \E[\BB\XX_{t-1}\XX_t^\top ] - \E[ \XX_t\uu^\top ] - \E[ \uu\XX_t^\top ] \\ +&\quad + \E[ \BB\XX_{t-1}(\BB\XX_{t-1})^\top ] + \E[\BB\XX_{t-1}\uu^\top] + \E[ \uu(\BB\XX_{t-1})^\top ] + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +Pulling the parameters out of the expectations and using $(\BB\XX_t)^\top = \XX_t^\top\BB^\top$, we have +\begin{equation}\label{eq:Q.unconstrained3} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \E[\XX_t\XX_t^\top] -\E[\XX_t\XX_{t-1}^\top ]\BB^\top - \BB\E[\XX_{t-1}\XX_t^\top ] - \E[ \XX_t ]\uu^\top - \uu \E[ \XX_t^\top ]\\ +&\quad + \BB\E[ \XX_{t-1}\XX_{t-1}^\top ]\BB^\top + \BB\E[\XX_{t-1}]\uu^\top + \uu\E[\XX_{t-1}^\top ]\BB^\top + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +The partial derivative is then rewritten in terms of the Kalman smoother output: +\begin{equation}\label{eq:Q.unconstrained4} +\begin{split} +&\partial\Psi/\partial\QQ = \frac{1}{2} \sum_{t=1}^T \QQ^{-1} \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt +- \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + \uu\uu^\top \bigg)\QQ^{-1} - \frac{T}{2}\QQ^{-1} +\end{split} +\end{equation} +Setting this to zero (a $m \times m$ matrix of zeros), $\QQ^{-1}$ is canceled out by multiplying by $\QQ$ twice, once on the left and once on the right and the $1/2$ is removed: +\begin{equation}\label{eq:Q.unconstrained5} +\begin{split} +T\QQ = \sum_{t=1}^T \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top + + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg) +\end{split} +\end{equation} +This gives us the new $\QQ$ that maximizes $\Psi$, +\begin{equation}\label{eq:Q.update.unconstrained} +\begin{split} +&\QQ_{j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( +\hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg) +\end{split} +\end{equation} + +This derivation immediately generalizes to the case where $\QQ$ is a block diagonal matrix: +\begin{equation*} +\QQ = +\begin{bmatrix} +q_{1,1}&q_{1,2}&q_{1,3}&0&0&0&0&0\\ +q_{1,2}&q_{2,2}&q_{2,3}&0&0&0&0&0\\ +q_{1,3}&q_{2,3}&q_{3,3}&0&0&0&0&0\\ +0&0&0&q_{4,4}&q_{4,5}&0&0&0\\ +0&0&0&q_{4,5}&q_{5,5}&0&0&0\\ +0&0&0&0&0&q_{6,6}&q_{6,7}&q_{6,8}\\ +0&0&0&0&0&q_{6,7}&q_{7,7}&q_{7,8}\\ +0&0&0&0&0&q_{6,8}&q_{7,8}&q_{8,8} +\end{bmatrix} += +\begin{bmatrix} +\QQ_1&0&0\\ +0&\QQ_2&0\\ +0&0&\QQ_3\\ +\end{bmatrix} +\end{equation*} +In this case, +\begin{equation}\label{eq:Q.update.blockdiag} +\begin{split} +&\QQ_{i,j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatPt - \hatPttm \BB^\top - \BB\hatPtmt + - \hatxt\uu^\top - \uu \hatxt^\top \\ +&\quad + \BB\hatPtm\BB^\top + \BB\hatxtm\uu^\top + \uu\hatxtm^\top\BB^\top + + \uu\uu^\top \bigg)_i +\end{split} +\end{equation} +where the subscript $i$ means take the elements of the matrix (in the big parentheses) that are analogous to $\QQ_i$; take the whole part within the parentheses not the individual matrices inside the parentheses). If $\QQ_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\QQ$, then take rows $a$ to $b$ and columns $c$ to $d$ of matrices subscripted by $i$ in equation \ref{eq:Q.update.blockdiag}. + +By the way, $\QQ$ is never really unconstrained since it is a variance-covariance matrix and the upper and lower triangles are shared. However, because the shared values are only the symmetric values in the matrix, the derivation still works even though it's technically incorrect \citep{HendersonSearle1979}. The constrained update equation for $\QQ$ shown in section \ref{sec:constrained.Q} explicitly deals with the shared lower and upper triangles. + +\subsection{Update equation for $\aa$ (unconstrained)}\label{sec:unconstA} +Take the derivative of $\Psi$ with respect to $\aa$, where $\aa$ is a $n \times 1$ matrix. Terms not involving $\aa$, equal 0 and drop out. +\begin{equation}\label{eq:a.unconstrained1} +\begin{split} +&\partial\Psi/\partial\aa = - \frac{1}{2}\sum_{t=1}^T \bigg(- \partial(\E[\YY_t^\top\RR^{-1}\aa])/\partial\aa +- \partial(\E[\aa^\top\RR^{-1}\YY_t])/\partial\aa \\ +&\quad + \partial(\E[(\ZZ\XX_t)^\top\RR^{-1}\aa])/\partial\aa ++ \partial(\E[\aa^\top\RR^{-1}\ZZ\XX_t])/\partial\aa ++ \partial(\E[\aa^\top\RR^{-1}\aa])/\partial\aa \bigg) +\end{split} +\end{equation} +The expectations around constants can be dropped\footnote{ +because $\EXy(C)=C$, where $C$ is a constant.}. Using relations \eqref{eq:derivaTc} and \eqref{eq:derivaTCa} and using $\RR^{-1} = (\RR^{-1})^\top$, we have then +\begin{equation}\label{eq:a.unconstrained2} +\begin{split} +&\partial\Psi/\partial\aa = - \frac{1}{2}\sum_{t=1}^T\bigg(-\E[\YY_t^\top\RR^{-1}] +-\E[\YY_t^\top\RR^{-1}] + \E[(\ZZ\XX_t)^\top\RR^{-1}] + + \E[(\ZZ\XX_t)^\top\RR^{-1}] + 2\aa^\top\RR^{-1} \bigg) +\end{split} +\end{equation} +Pull the parameters out of the expectations, use $(\aa\bb)^\top = \bb^\top\aa^\top$ and $\RR^{-1} = (\RR^{-1})^\top$ where needed, and remove the $-1/2$ to get +\begin{equation}\label{eq:a.unconstrained3} +\begin{split} +&\partial\Psi/\partial\aa = \sum_{t=1}^T\bigg(\E[\YY_t]^\top\RR^{-1} + - \E[\XX_t]^\top\ZZ^\top\RR^{-1} - \aa^\top\RR^{-1} \bigg) +\end{split} +\end{equation} +Set the left side to zero (a $1 \times n$ matrix of zeros), take the transpose, and cancel out $\RR^{-1}$ by multiplying by $\RR$, giving +\begin{equation}\label{eq:a.unconstrained4} +\mathbf{0} = \sum_{t=1}^{T}\big(\E[\YY_t] - \ZZ\E[\XX_t] - \aa \big) +=\sum_{t=1}^{T}\big(\hatyt - \ZZ\hatxt - \aa\big) +\end{equation} + +Solving for $\aa$ gives us the update equation for $\aa$: +\begin{equation}\label{eq:a.update.unconstrained} +\aa_{j+1} = \frac{1}{T}\sum_{t=1}^{T}\big(\hatyt - \ZZ\hatxt \big) +\end{equation} + +\subsection{The update equation for $\ZZ$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\ZZ$. Terms not involving $\ZZ$, equal 0 and drop out. The expectations around terms involving only constants have been dropped. +\begin{equation}\label{eq:Z.unconstrained1} +\begin{split} +&\partial\Psi/\partial\ZZ = \text{(note $\partial\ZZ$ is $m \times n$ while $\ZZ$ is $n \times m$)}\\ +&\quad -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] + - \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\YY_t)/\partial\ZZ] + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] \\ +&\quad + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\aa)/\partial\ZZ] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ]\bigg)\\ +&= -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] + -\E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\YY_t)/\partial\ZZ] ++ \E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ] \\ +&\quad + \E[\partial(\XX_t^\top\ZZ^\top\RR^{-1}\aa)/\partial\ZZ] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\ZZ]\bigg)\\ +\end{split} +\end{equation} +Using the matrix derivative relations (table \ref{tab:MatrixDerivatives}) and using $\RR^{-1} = (\RR^{-1})^\top$, we get +\begin{equation}\label{eq:Z.unconstrained2} +\begin{split} +\partial\Psi/\partial\ZZ = -\frac{1}{2} \sum_{t=1}^T\bigg(-\E[ \XX_t\YY_t^\top\RR^{-1} ] - &\E[ \XX_t\YY_t^\top\RR^{-1} ] \\ +&+ 2 \E[\XX_t\XX_t^\top\ZZ^\top\RR^{-1}] + \E[ \XX_{t-1}\aa^\top\RR^{-1} ] + \E[ \XX_t\aa^\top\RR^{-1} ] \bigg) +\end{split} +\end{equation} +Pulling the parameters out of the expectations and getting rid of the $-1/2$, we have +\begin{equation}\label{eq:Z.unconstrained3} +\begin{split} +&\partial\Psi/\partial\ZZ = \sum_{t=1}^T\bigg(\E[ \XX_t \YY_t^\top]\RR^{-1} +- \E[ \XX_t\XX_t^\top ]\ZZ^\top\RR^{-1} -\E[ \XX_t ]\aa^\top\RR^{-1} \bigg) \\ +\end{split} +\end{equation} +Set the left side to zero (a $m \times n$ matrix of zeros), transpose it all, and cancel out $\RR^{-1}$ by multiplying by $\RR$ on the left, to give +\begin{equation}\label{eq:Z.unconstrained4} +\begin{split} +\mathbf{0} = \sum_{t=1}^T\big(\E[\YY_t\XX_t^\top] - \ZZ \E[\XX_t\XX_t^\top] - \aa\E[\XX_t^\top]\big) + = \sum_{t=1}^T \big( \hatYXt - \ZZ \hatPt - \aa\hatxt^\top \big) +\end{split} +\end{equation} +Solving for $\ZZ$ and noting that $\hatPt$ is invertible, gives us the new $\ZZ$: +\begin{equation}\label{eq:Z.update.unconstrained} +\ZZ_{j+1}= \bigg( \sum_{t=1}^T \big(\hatYXt - \aa\hatxt^\top\big)\bigg) \bigg(\sum_{t=1}^T \hatPt\bigg)^{-1} +\end{equation} + +\subsection{The update equation for $\RR$ (unconstrained)} +Take the derivative of $\Psi$ with respect to $\RR$. Terms not involving $\RR$, equal 0 and drop out. The expectations around terms involving constants have been removed. +\begin{equation}\label{eq:R.unconstrained1} +\begin{split} +&\partial\Psi/\partial\RR = -\frac{1}{2} \sum_{t=1}^T\bigg( +\E[\partial(\YY_t^\top\RR^{-1}\YY_t)/\partial\RR] +-\E[\partial(\YY_t^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] -\E[\partial((\ZZ\XX_t)^\top\RR^{-1}\YY_t)/\partial\RR]\\ +&\quad - \E[\partial(\YY_t^\top\RR^{-1}\aa)/\partial\RR] + - \E[\partial(\aa^\top\RR^{-1}\YY_t)/\partial\RR] ++ \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] \\ +&\quad + \E[\partial((\ZZ\XX_t)^\top\RR^{-1}\aa)/\partial\RR] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\XX_t)/\partial\RR] + + \partial(\aa^\top\RR^{-1}\aa)/\partial\RR +\bigg) - \partial\big(\frac{T}{2}\log |\RR| \big)/\partial\RR +\end{split} +\end{equation} +We use relations \eqref{eq:derivInv} and \eqref{eq:derivlogDet} to do the differentiation. Notice that all the terms in the summation are of the form $\cc^\top\RR^{-1}\bb$, and thus after differentiation, we group all the $\cc^\top\bb$ inside one set of parentheses. Also there is a minus that comes from equation \ref{eq:derivInv} and cancels out the minus in front of $-1/2$. +\begin{equation}\label{eq:R.unconstrained2} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( + \E[\YY_t\YY_t^\top] -\E[\YY_t(\ZZ\XX_t)^\top] - \E[\ZZ\XX_t\YY_t^\top ] - \E[\YY_t\aa^\top] - \E[\aa\YY_t^\top]\\ +&\quad + \E[ \ZZ\XX_t(\ZZ\XX_t)^\top ] + \E[\ZZ\XX_t\aa^\top] + \E[ \aa(\ZZ\XX_t)^\top ] + + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +Pulling the parameters out of the expectations and using $(\ZZ\YY_t)^\top = \YY_t^\top\ZZ^\top$, we have +\begin{equation}\label{eq:R.unconstrained3} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( + \E[\YY_t\YY_t^\top] -\E[\YY_t\XX_t^\top ]\ZZ^\top - \ZZ\E[\XX_t\YY_t^\top] + - \E[\YY_t]\aa^\top - \aa\E[\YY_t^\top] \\ +&\quad + \ZZ\E[ \XX_t\XX_t^\top ]\ZZ^\top + \ZZ\E[\XX_t]\aa^\top + \aa\E[\XX_t^\top ]\ZZ^\top + + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +We rewrite the partial derivative in terms of expectations: +\begin{equation}\label{eq:R.unconstrained4} +\begin{split} +&\partial\Psi/\partial\RR = \frac{1}{2} \sum_{t=1}^T \RR^{-1} \bigg( +\hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top \\ +&\quad + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + \aa\aa^\top \bigg)\RR^{-1} - \frac{T}{2}\RR^{-1} +\end{split} +\end{equation} +Setting this to zero (a $n \times n$ matrix of zeros), we cancel out $\RR^{-1}$ by multiplying by $\RR$ twice, once on the left and once on the right, and get rid of the $1/2$. +\begin{equation}\label{eq:R.unconstrained5} +\begin{split} +T\RR = \sum_{t=1}^T \bigg( +\hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top ++ \aa\aa^\top \bigg) +\end{split} +\end{equation} + +We can then solve for $\RR$, giving us the new $\RR$ that maximizes $\Psi$, +\begin{equation}\label{eq:R.update.unconstrained} +\begin{split} +\RR_{j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + + \aa\aa^\top \bigg) +\end{split} +\end{equation} +As with $\QQ$, this derivation immediately generalizes to a block diagonal matrix: +\begin{equation*} +\RR = +\begin{bmatrix} +\RR_1&0&0\\ +0&\RR_2&0\\ +0&0&\RR_3\\ +\end{bmatrix} +\end{equation*} +In this case, +\begin{equation}\label{eq:R.update.blockdiag} +\begin{split} +\RR_{i,j+1} = \frac{1}{T}\sum_{t=1}^T \bigg( + \hatOt - \hatYXt\ZZ^\top - \ZZ\hatYXt^\top + - \hatyt\aa^\top - \aa\hatyt^\top + + \ZZ\hatPt\ZZ^\top + \ZZ\hatxt\aa^\top + \aa\hatxt^\top\ZZ^\top + + \aa\aa^\top \bigg)_i +\end{split} +\end{equation} +where the subscript $i$ means we take the elements in the matrix in the big parentheses that are analogous to $\RR_i$. If $\RR_i$ is comprised of rows $a$ to $b$ and columns $c$ to $d$ of matrix $\RR$, then we take rows $a$ to $b$ and columns $c$ to $d$ of matrix subscripted by $i$ in equation \ref{eq:R.update.blockdiag}. + +\subsection{Update equation for $\xixi$ and $\LAM$ (unconstrained), stochastic initial state} +\citet{ShumwayStoffer2006} and \citet{GhahramaniHinton1996} imply in their discussion of the EM algorithm that both $\xixi$ and $\LAM$ can be estimated (though not simultaneously). Harvey (1989), however, discusses that there are only two allowable cases: $\xx_0$ is treated as fixed ($\LAM=0$) and equal to the unknown parameter $\xixi$ or $\xx_0$ is treated as stochastic with a known mean $\xixi$ and variance $\LAM$. For completeness, we show here the update equation in the case of $\xx_0$ stochastic with unknown mean $\xixi$ and variance $\LAM$ (a case that Harvey (1989) says is not consistent). + +We proceed as before and solve for the new $\xixi$ by minimizing $\Psi$. +Take the derivative of $\Psi$ with respect to $\xixi$ . Terms not involving $\xixi$, equal 0 and drop out. +\begin{equation}\label{eq:pi.unconstrained1} +\begin{split} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- \partial(\E[\xixi^\top\LAM^{-1}\XX_0])/\partial\xixi +- \partial(\E[\XX_0^\top\LAM^{-1}\xixi])/\partial\xixi + + \partial(\xixi^\top\LAM^{-1}\xixi)/\partial\xixi \big) +\end{split} +\end{equation} +Using relations \eqref{eq:derivaTc} and \eqref{eq:derivaTCa} and using $\LAM^{-1} = (\LAM^{-1})^\top$, we have +\begin{equation}\label{eq:pi.unconstrained2} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- \E[ \XX_0^\top\LAM^{-1} ] +- \E[ \XX_0^\top\LAM^{-1} ] + 2\xixi^\top\LAM^{-1} \big) +\end{equation} +Pulling the parameters out of the expectations, we get +\begin{equation}\label{eq:pi.unconstrained3} +\partial\Psi/\partial\xixi = - \frac{1}{2} \big(- 2\E[ \XX_0^\top ]\LAM^{-1} + 2\xixi^\top\LAM^{-1} \big) +\end{equation} +We then set the left side to zero, take the transpose, and cancel out $-1/2$ and $\LAM^{-1}$ (by noting that it is a variance-covariance matrix and is invertible). +\begin{equation}\label{eq:pi.unconstrained4} +\mathbf{0} = \big(\LAM^{-1}\E[ \XX_0 ] + \LAM^{-1}\xixi \big)=(\widetilde{\mbox{$\mathbf x$}}_0 - \xixi) +\end{equation} + +Thus, +\begin{equation}\label{eq:pi.update.unconstrained} +\xixi_{j+1} = \widetilde{\mbox{$\mathbf x$}}_0 +\end{equation} +$\widetilde{\mbox{$\mathbf x$}}_0$ is the expected value of $\XX_0$ conditioned on the data from $t=1$ to $T$, which comes from the Kalman smoother recursions with initial conditions defined as $\E[\XX_0|\YY_0=\yy_0] \equiv \xixi_j$ and $\var(\XX_0 \XX_0^\top|\YY_0=\yy_0)\equiv \LAM_j$ (meaning the filter recursions start with $t=1$ with $\tilde{x}_{t-1}^{t-1} = \tilde{x}_0^0 = \xixi_j$). +A similar set of steps gets us to the update equation for $\LAM$, +\begin{equation}\label{eq:V0.update.unconstrained} +\LAM_{j+1} = \widetilde{\VV}_0 +\end{equation} +$\widetilde{\VV}_0$ is the variance of $\XX_0$ conditioned on the data from $t=1$ to $T$ and is an output from the Kalman smoother recursions. + +If the initial state is defined as at $t=1$ instead of $t=0$, the update equation is derived in an identical fashion and the update equation is similar: +\begin{equation}\label{eq:pix1.update.unconstrained} +\xixi_{j+1} = \widetilde{\mbox{$\mathbf x$}}_1 +\end{equation} +\begin{equation} +\LAM_{j+1} = \widetilde{\VV}_1 +\end{equation} +These are output from the Kalman smoother recursions with initial conditions defined as $\E[\XX_1|\YY_0=\yy_0] \equiv \xixi_j$ and $\var(\XX_1 \XX_1^\top|\YY_0=\yy_0)\equiv \LAM_j$ (meaning the filter recursions start with $t=1$ with $\tilde{x}_{t}^{t-1} = \tilde{x}_1^0 = \xixi_j$). Notice that the recursions are initialized slightly differently. In the literature, you will see the Kalman filter and smoother equations presented with both types of initializations depending on whether the author defines the initial state at $t=0$ or $t=1$. + +\subsection{Update equation for $\xixi$ (unconstrained), fixed $\xx_0$} +For the case where $\xx_0$ is treated as fixed, i.e., as another parameter, then there is no $\LAM$, and we need to maximize $\partial\Psi/\partial\xixi$ using the slightly different $\Psi$ shown in equation \ref{eq:logL.V0.is.0}. Now $\xixi$ appears in the state equation part of the likelihood. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\partial(\XX_1^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial((\BB\xixi)^\top\QQ^{-1}\XX_1)/\partial\xixi] + \E[\partial((\BB\xixi)^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\BB\xixi)^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg)\\ +&= -\frac{1}{2} \bigg(-\E[\partial(\XX_1^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial(\xixi^\top\BB^\top\QQ^{-1}\XX_1)/\partial\xixi] ++ \E[\partial(\xixi^\top\BB^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial(\xixi^\top\BB^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg) +\end{split} +\end{equation} +After pulling the constants out of the expectations, we use relations \eqref{eq:derivaTDb} and \eqref{eq:derivbDTCDd} to take the derivative: +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.2} +\begin{split} +\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\XX_1]^\top\QQ^{-1}\BB - \E[ \XX_1]^\top\QQ^{-1}\BB + + 2 \xixi^\top\BB^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB \bigg) \\ +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.3} +\begin{split} +\partial\Psi/\partial\xixi = \E[\XX_1]^\top\QQ^{-1}\BB - \xixi^\top\BB^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB +\end{split} +\end{equation} +To solve for $\xixi$, set the left side to zero (an $m \times 1$ matrix of zeros), transpose the whole equation, and then cancel out $\BB^\top\QQ^{-1}\BB$ by multiplying by its inverse on the left, and solve for $\xixi$. This step requires that this inverse exists. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.4} +\begin{split} +\xixi = (\BB^\top\QQ^{-1}\BB)^{-1}\BB^\top\QQ^{-1}(\E[\XX_1] - \uu) +\end{split} +\end{equation} +Thus, in terms of the Kalman filter/smoother output the new $\xixi$ for EM iteration $j+1$ is +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.5} +\begin{split} +\xixi_{j+1} = (\BB^\top\QQ^{-1}\BB)^{-1}\BB^\top\QQ^{-1}(\widetilde{\mbox{$\mathbf x$}}_1 - \uu) +\end{split} +\end{equation} +Note that using, $\widetilde{\mbox{$\mathbf x$}}_0$ output from the Kalman smoother would not work since $\LAM=0$. As a result, $\xixi_{j+1} \equiv \xixi_j$ in the EM algorithm, and it is impossible to move away from your starting condition for $\xixi$. + +This is conceptually similar to using a generalized least squares estimate of $\xixi$ to concentrate it out of the likelihood as discussed in Harvey (1989), section 3.4.4. However, in the context of the EM algorithm, dealing with the fixed $\xx_0$ case requires nothing special; one simply takes care to use the likelihood for the case where $\xx_0$ is treated as an unknown parameter (equation \ref{eq:logL.V0.is.0}). For the other parameters, the update equations are the same whether one uses the log-likelihood equation with $\xx_0$ treated as stochastic (equation \ref{eq:logL}) or fixed (equation \ref{eq:logL.V0.is.0}). + +If your MARSS model is stationary\footnote{meaning the $\XX$'s have a stationary distribution} and your data appear stationary, however, equation \ref{eq:pi.unconstrained.V0.is.0.4} probably is not what you want to use. The estimate of $\xixi$ will be the maximum-likelihood value, but it will not be drawn from the stationary distribution; instead it could be some wildly different value that happens to give the maximum-likelihood. If you are modeling the data as stationary, then you should probably assume that $\xixi$ is drawn from the stationary distribution of the $\XX$'s, which is some function of your model parameters. This would mean that the model parameters would enter the part of the likelihood that involves $\xixi$ and $\LAM$. Since you probably don't want to do that (if might start to get circular), you might try an iterative process to get decent $\xixi$ and $\LAM$ or try fixing $\xixi$ and estimating $\LAM$ (above). You can fix $\xixi$ at, say, zero, by making sure the model you fit has a stationary distribution with mean zero. You might also need to demean your data (or estimate the $\aa$ term to account for non-zero mean data). A second approach is to estimate $\xx_1$ as the initial state instead of $\xx_0$. + +\subsection{Update equation for $\xixi$ (unconstrained), fixed $\xx_1$}\label{sec:xi.unconstrained.x1} +In some cases, the estimate of $\xx_0$ from $\xx_1$ using equation \ref{eq:pi.unconstrained.V0.is.0.5} will be highly sensitive to small changes in the parameters. This is particularly the case for certain $\BB$ matrices, even if they are stationary. The result is that your $\xixi$ estimate is wildly different from the data at $t=1$. The estimates are correct given how you defined the model, just not realistic given the data. In this case, you can specify $\xixi$ as being the value of $\xx$ at $t=1$ instead of $t=0$. That way, the data at $t=1$ will constrain the estimated $\xixi$. In this case, we treat $\xx_1$ as fixed but unknown parameter $\xixi$. The likelihood is then: +\begin{equation} +\begin{split} +&\log\LL(\yy,\xx ; \Theta) = -\sum_1^T \frac{1}{2}(\yy_t - \ZZ \xx_t - \aa)^\top \RR^{-1} (\yy_t - \ZZ \xx_t - \aa) -\sum_1^T\frac{1}{2} \log |\RR|\\ +&\quad -\sum_2^T \frac{1}{2} (\xx_t - \BB \xx_{t-1} - \uu)^\top \QQ^{-1} (\xx_t - \BB \xx_{t-1} - \uu) - \sum_1^T\frac{1}{2}\log |\QQ| +\end{split} +\end{equation} + +\begin{equation}\label{} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\partial(\YY_1^\top\RR^{-1}\ZZ\xixi)/\partial\xixi] + - \E[\partial((\ZZ\xixi)^\top\RR^{-1}\YY_1)/\partial\xixi] + \E[\partial((\ZZ\xixi)^\top\RR^{-1}(\ZZ\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\ZZ\xixi)^\top\RR^{-1}\aa)/\partial\xixi] ++ \E[\partial(\aa^\top\RR^{-1}\ZZ\xixi)/\partial\xixi]\bigg)\\ +&\quad -\frac{1}{2} \bigg(-\E[\partial(\XX_2^\top\QQ^{-1}\BB\xixi)/\partial\xixi] + - \E[\partial((\BB\xixi)^\top\QQ^{-1}\XX_2)/\partial\xixi] + \E[\partial((\BB\xixi)^\top\QQ^{-1}(\BB\xixi))/\partial\xixi] \\ +&\quad + \E[\partial((\BB\xixi)^\top\QQ^{-1}\uu)/\partial\xixi] ++ \E[\partial(\uu^\top\QQ^{-1}\BB\xixi)/\partial\xixi]\bigg) +\end{split} +\end{equation} +Note that the second summation starts at $t=2$ and $\xixi$ is $\xx_1$ instead of $\xx_0$. + +After pulling the constants out of the expectations, we use relations \eqref{eq:derivaTDb} and \eqref{eq:derivbDTCDd} to take the derivative: +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.1} +\begin{split} +&\partial\Psi/\partial\xixi = -\frac{1}{2} \bigg(-\E[\YY_1]^\top\RR^{-1}\ZZ - \E[ \YY_1]^\top\RR^{-1}\ZZ + + 2 \xixi^\top\ZZ^\top\RR^{-1}\ZZ + \aa^\top\RR^{-1}\ZZ + \aa^\top\RR^{-1}\ZZ \bigg) \\ +&\quad-\frac{1}{2} \bigg(-\E[\XX_2]^\top\QQ^{-1}\BB - \E[ \XX_2]^\top\QQ^{-1}\BB + + 2 \xixi^\top\BB^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB + \uu^\top\QQ^{-1}\BB \bigg) +\end{split} +\end{equation} +This can be reduced to +\begin{equation}\label{} +\begin{split} +&\partial\Psi/\partial\xixi = \E[\YY_1]^\top\RR^{-1}\ZZ - \xixi^\top\ZZ^\top\RR^{-1}\ZZ - \aa^\top\RR^{-1}\ZZ + + \E[\XX_2]^\top\QQ^{-1}\BB - \xixi^\top\BB^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB \\ +&\quad = - \xixi^\top(\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB) + \E[\YY_1]^\top\RR^{-1}\ZZ - \aa^\top\RR^{-1}\ZZ ++ \E[\XX_2]^\top\QQ^{-1}\BB - \uu^\top\QQ^{-1}\BB +\end{split} +\end{equation} +To solve for $\xixi$, set the left side to zero (an $m \times 1$ matrix of zeros), transpose the whole equation, and solve for $\xixi$. +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.2} +\begin{split} +\xixi = (\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB)^{-1}(\ZZ^\top\RR^{-1}(\E[\YY_1]-\aa) +\BB^\top\QQ^{-1}(\E[\XX_2] - \uu)) \\ +\end{split} +\end{equation} +Thus, when $\xixi \equiv \xx_1$, the new $\xixi$ for EM iteration $j+1$ is +\begin{equation}\label{eq:pi.unconstrained.V0.is.0.t.1.3} +\begin{split} +\xixi_{j+1} = (\ZZ^\top\RR^{-1}\ZZ + \BB^\top\QQ^{-1}\BB)^{-1}(\ZZ^\top\RR^{-1}(\widetilde{\mbox{$\mathbf y$}}_1-\aa) +\BB^\top\QQ^{-1}(\widetilde{\mbox{$\mathbf x$}}_2 - \uu)) +\end{split} +\end{equation} + +\section{The time-varying MARSS model with linear constraints}\label{sec:tvMARSS} +The first part of this report dealt with the case of a MARSS model (equation \ref{eq:MARSS}) where the parameters are time-constant and where all the elements in a parameter matrix are estimated with no constraints. I will now describe the derivation of an EM algorithm to solve a much more general MARSS model (equation \ref{eq:MARSS.ex2}), which is a time-varying MARSS model where the MARSS parameter matrices are written as a linear equation $\ff+\DD\mm$. This is a very general form of a MARSS model, of which many (most) multivariate autoregressive Gaussian models are a special case. This general MARSS model includes as special cases, MARSS models with covariates (many VARSS models with exogeneous variables), multivariate AR lag-p models and multivariate moving average models, and MARSS models with linear constraints placed on the elements within the model parameters. The objective is to derive one EM algorithm for the whole class, thus a uniform approach to fitting these models. + +The time-varying MARSS model is written: +\begin{subequations}\label{eq:MARSS.ex2} +\begin{gather} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \HH_t\vv_t, \text{ where } \VV_t \sim \MVN(0,\RR_t)\\ +\xx_{t_0} = \xixi+\FF\ll, \text{ where } t_0=0 \text{ or } t_0=1\\ +\LL \sim \MVN(0,\LAM)\\ +\begin{bmatrix}\ww_t\\ \vv_t\end{bmatrix} \sim \MVN(0,\Sigma), \quad \Sigma=\begin{bmatrix}\QQ_t&0\\ 0&\RR_t\end{bmatrix} +\end{gather} +\end{subequations} +This looks quite similar to the previous non-time varying MARSS model, but now the model parameters, $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$ and $\RR$, have a $t$ subscript and we have a multiplier matrix on the error terms $\vv_t$, $\ww_t$, $\ll$. The $\GG_t$ multiplier is $m \times s$, so we now have $s$ state errors instead of $m$. The $\HH_t$ multiplier is $n \times k$, so we now have $k$ observation errors instead of $n$. The $\FF$ multiplier is $m \times j$, so now we can have some initial states ($j$ of them) be stochastic and others be fixed. I assume that appropriate constraints are put on $\GG$ and $\HH$ so that the resulting MARSS model is not under- or over-constrained\footnote{For example, if both $\GG$ and $\HH$ are column vectors, then the system is over-constrained and has no solution.}. +The notation/presentation here was influenced by SJ Koopman's work, esp. \citet{KoopmanOoms2011} and \citet{Koopman1993}, but in these works, $\QQ_t$ and $\RR_t$ equal $\II$ and the variance-covariance structures are instead specified only by $\HH_t$ and $\GG_t$. I keep $\QQ_t$ and $\RR_t$ in my formulation as it seems more intuitive (to me) in the context of the EM algorithm and the required joint-likelihood function. + +We can rewrite this MARSS model using vec relationships (table \ref{tab:VecRelations}): +\begin{equation}\label{eq:MARSS.ex.vec} +\begin{gathered} +\xx_t = (\xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \vec(\uu_t) + \GG_t\ww_t, \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = (\xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \vec(\aa_t) + \HH_t\vv_t, \VV_t \sim \MVN(0,\RR_t)\\ +\xx_{t_0} = \xixi+\FF\ll, \LL \sim \MVN(0,\LAM) +\end{gathered} +\end{equation} +Each model parameter, $\BB_t$, $\uu_t$, $\QQ_t$, $\ZZ_t$, $\aa_t$, and $\RR_t$, is written as a time-varying linear model, $\ff_t+\DD_t\mm$, where $\ff$ and $\DD$ are fully-known (not estimated and no missing values) and $\mm$ is a column vector of the estimates elements of the parameter matrix: +\begin{equation}\label{eq:MARSS.ex.vec.2} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq\\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr\\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda \\ +\vec(\xixi)&= \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} + +The estimated parameters are now the column vectors, $\bbeta$, $\uupsilon$, $\qq$, $\zzeta$, $\aalpha$, $\rr$, $\pp$ and $\llambda$. The time-varying aspect comes from the time-varying $\ff$ and $\DD$. Note that variance-covariance matrices must be positive-definite and we cannot specify a form that cannot be estimated. Fixing the diagonal terms and estimating the off-diagonals would not be allowed. Thus the $\ff$ and $\DD$ terms for $\QQ$, $\RR$ and $\LAM$ are limited. For the other parameters, the forms are fairly unrestricted, except that the $\DD$s need to be full rank so that we are not specifying an under-constrained model. 'Full rank' will imply that we are not trying to estimate confounded matrix elements; for example, trying to estimate $a_1$ and $a_2$ but only $a_1+a_2$ appear in the model. + +The temporally variable MARSS model, equation \ref{eq:MARSS.ex.vec} together with equation \ref{eq:MARSS.ex.vec.2}, looks rather different than other temporally variable MARSS models, such as a VARSSX or MARSS with covariates model, in the literature. But those models are special cases of this equation. By deriving an EM algorithm for this more general (if unfamiliar) form, I then have an algorithm for many different types of time-varying MARSS models with linear constraints on the parameter elements. Below I show some examples. + +\subsection{MARSS model with linear constraints} +We can use equation \ref{eq:MARSS.ex.vec} to put linear constraints on the elements of the parameters, $\BB$, $\uu$, $\QQ$, $\ZZ$, $\aa$, $\RR$, $\xixi$ and $\LAM$. Here is an example of a simple MARSS model with linear constraints: +\begin{gather*} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t += \begin{bmatrix}a&0\\0&2a\end{bmatrix} +\begin{bmatrix}x_1\\x_2\end{bmatrix}_{t-1} ++ \begin{bmatrix}w_1\\ w_2\end{bmatrix}_t,\quad +\begin{bmatrix}w_1\\ w_2\end{bmatrix}_t \sim \MVN\begin{pmatrix}\begin{bmatrix}0.1\\u+0.1\end{bmatrix},\begin{bmatrix}q_{11}&q_{12}\\q_{21}&q_{22}\end{bmatrix} \end{pmatrix} \\ +\\ +\begin{bmatrix}y_1\\ y_2\\ y_3\end{bmatrix}_t += \begin{bmatrix}c&3c+2d+1\\ c& d\\ c+e+2 &e\end{bmatrix} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t ++ \begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t,\\ +\begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t \sim \MVN\begin{pmatrix}\begin{bmatrix}a_1\\ a_2\\ 0\end{bmatrix}, + \begin{bmatrix}r&0&0\\0&2r&0\\0&0&4r\end{bmatrix} \end{pmatrix} \\ +\\ +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_0 \sim \MVN\begin{pmatrix}\begin{bmatrix}\pi\\ \pi\end{bmatrix},\begin{bmatrix}1&0\\ 0&1\end{bmatrix} \end{pmatrix} +\end{gather*} +Linear constraints mean that elements of a matrix may be fixed to a specific numerical value or specified as a linear combination of values (which can be shared within a matrix but not shared between matrices). + +Let's say we have some parameter matrix $\MM$ (here $\MM$ could be any of the parameters in the MARSS model) where each matrix element is written as a linear model of some potentially shared values: +\begin{equation*} +\MM= +\begin{bmatrix} +a+2c+2&0.9&c\\ +-1.2&a&0\\ +0&3c+1&b +\end{bmatrix} +\end{equation*} +Thus each $i$-th element in $\MM$ can be written as $\beta_i+\beta_{a,i} a + \beta_{b,i} b + \beta_{c,i} c$, which is a linear combination of three estimated values $a$, $b$ and $c$. The matrix $\MM$ can be rewritten in terms of a $\beta_i$ part and the part involving the $\beta_{-,j}$'s: +\begin{equation*} +\MM= +\begin{bmatrix} +2&0.9&0\\ +-1.2&0&0\\ +0&1&0 +\end{bmatrix} ++ +\begin{bmatrix} +a+2c&0&c\\ +0&a&0\\ +0&3c&b +\end{bmatrix} +=\MM_\text{fixed}+\MM_\text{free} +\end{equation*} +The vec function turns any matrix into a column vector by stacking the columns on top of each other. Thus, +\begin{equation*} +\vec(\MM)= +\begin{bmatrix} +a+2c+2\\ +-1.2\\ +0\\ +0.9\\ +a\\ +3c+1\\ +c\\ +0\\ +b +\end{bmatrix} +\end{equation*} +We can now write $\vec(\MM)$ as a linear combination of $\ff = \vec(\MM_\text{fixed})$ and $\DD\mm = \vec(\MM_\text{free})$. $\mm$ is a $p \times 1$ column vector of the $p$ free values, in this case $p=3$ and the free values are $a, b, c$. $\DD$ is a design matrix that translates $\mm$ into $\vec(\MM_\text{free})$. For example, +\begin{equation*} +\vec(\MM)= +\begin{bmatrix} +a+2c+2\\ +-1.2\\ +0\\ +0.9\\ +a\\ +3c+1\\ +c\\ +0\\ +b +\end{bmatrix} += +\begin{bmatrix} +0\\ +-1.2\\ +2\\ +0.9\\ +0\\ +1\\ +0\\ +0\\ +0 +\end{bmatrix} ++ +\begin{bmatrix} +1&2&0\\ +0&0&0\\ +0&0&0\\ +0&0&0\\ +1&0&0\\ +0&0&3\\ +0&0&1\\ +0&0&0\\ +0&1&0 +\end{bmatrix} +\begin{bmatrix} +a\\ +b\\ +c +\end{bmatrix} += \ff + \DD\mm +\end{equation*} +There are constraints on $\DD$. Your $\DD$ matrix needs to describe a solvable linear set of equations. Basically it needs to be full rank (rank $p$ where $p$ is the number of columns in $\DD$ or free values you are trying to estimate), so that you can estimate each of the $p$ free values. For example, if $a+b$ always appeared together, then $a+b$ can be estimated but not $a$ and $b$ separately. Note, if $\MM$ is fixed, then $\DD$ is undefined but that is fine because in this case, there will be no update equation needed; you just use the fixed value of $\MM$ in the algorithm. + + +\begin{table} + \caption{Kronecker and vec relations. Here $\AA$ is $n \times m$, $\BB$ is $m \times p$, $\CC$ is $p \times q$, and $\EE$ and $\DD$ are $p \times p$. $\aa$ is a $m \times 1$ column vector and $\bb$ is a $p \times 1$ column vector. The symbol $\otimes$ stands for the Kronecker product: $\AA \otimes \CC$ is a $np \times mq$ matrix. The identity matrix, $\II_n$, is a $n \times n$ diagonal matrix with ones on the diagonal.} + \label{tab:VecRelations} + \begin{center} + \begin{tabular}{lr} +\hline +\\ +\refstepcounter{equation}\label{eq:vec.a} +$\vec(\aa) = \vec(\aa^\top) = \aa$ +&\multirow{3}{*}{(\theequation)} \\ +The vec of a column vector (or its transpose) is itself. & \\ +$\aa=(\aa^\top \otimes \II_1)$ & \\ +\\ +\refstepcounter{equation}\label{eq:vec.Aa} +$\vec(\AA\aa) = (\aa^\top \otimes \II_n)\vec(\AA) = \AA\aa$ +&\multirow{2}{*}{(\theequation)} \\ +$\vec(\AA\aa) = \AA\aa$ since $\AA\aa$ is itself an $m \times 1$ column vector. & \\ +\\ +\refstepcounter{equation}\label{eq:vec.AB} +$\vec(\AA\BB) = (\II_p \otimes \AA)\vec(\BB) = (\BB^\top \otimes \II_n)\vec(\AA)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:vec.ABC} +$\vec(\AA\BB\CC) = (\CC^\top \otimes \AA)\vec(\BB)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:vec.aTBa} +$\vec(\aa^\top\BB\aa) = \aa^\top\BB\aa = (\aa^\top \otimes \aa)\vec(\BB)$ +& (\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:kron.prod} +$(\AA \otimes \BB)(\CC \otimes \DD) = (\AA\CC \otimes \BB\DD)$ +&\multirow{2}{*}{(\theequation)} \\ +$(\AA \otimes \BB)+(\AA \otimes \CC) = (\AA \otimes (\BB+\CC))$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.column.vec} +$(\aa \otimes \II_p)\CC = (\aa \otimes \CC)$ &\multirow{3}{*}{(\theequation)} \\ +$\CC(\aa^\top \otimes \II_q) = (\aa^\top \otimes \CC)$ &\\ +$\EE(\aa^\top \otimes \DD)=\EE\DD(\aa^\top \otimes \II_p)=(\aa^\top \otimes \EE\DD)$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.column.quad.vec} +$(\aa \otimes \II_p)\CC(\bb^\top \otimes \II_q) = (\aa\bb^\top \otimes \CC)$ & +(\theequation) \\ +\\ +\refstepcounter{equation}\label{eq:kron.column.column.vec} +$(\aa \otimes \bb)=\vec(\bb\aa^\top)$ +&\multirow{2}{*}{(\theequation)} \\ +$(\aa^\top \otimes \bb^\top)=(\aa \otimes \bb)^\top=(\vec(\bb\aa^\top))^\top$ &\\ +\\ +\refstepcounter{equation}\label{eq:kron.trans} +$(\AA^\top \otimes \BB^\top)=(\AA \otimes \BB)^\top$ & +(\theequation) \\ +\\\hline +\end{tabular} +\end{center} +\end{table} + +\subsection{A MARSS model with exogenous variables} +The following is a commonly seen MARSS model with covariates $\cc_t$ and $\dd_t$ appearing as additive elements: +\begin{equation*} +\begin{split} +\xx_t &= \BB\xx_{t-1} + \CC\cc_t + \ww_t\\ +\yy_t &= \ZZ\xx_t + \DD\dd_t + \vv_t +\end{split} +\end{equation*} +Here, $\DD$ is the effect of $\dd_t$ on $\yy_t$ not a design matrix (which would have a subscript). We would typically want to estimate $\CC$ or $\DD$ which are the influence of our covariates on our responses, $\xx$ or $\yy$. Let's say there are $p$ covariates in $\cc_t$ and $q$ covariates in $\dd_t$. Then we can write the above in vec form: +\begin{equation}\label{eq:MARSS.simple.ex} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)\vec(\BB) + (\cc_t^\top \otimes \II_p)\vec(\CC) + \ww_t\\ +\yy_t &= (\xx_t^\top \otimes \II_n)\vec(\ZZ) + (\dd_t^\top \otimes \II_q)\vec(\DD) + \vv_t +\end{split} +\end{equation} +Let's say we put no constraints $\BB$, $\ZZ$, $\QQ$, $\RR$, $\xixi$, or $\LAM$. Then in the form of equation \ref{eq:MARSS.ex.vec}, +\begin{equation*} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \vec(\uu_t) + \ww_t\\ +\yy_t &= (\xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \vec(\aa_t) + \vv_t, +\end{split} +\end{equation*} +with the parameters defined as follows: +\begin{equation*} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta; +\, \ff_{t,b} = 0;\, \DD_{t,b}=1;\, \bbeta=\vec(\BB)\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon; +\, \ff_{t,u} = 0;\, \DD_{t,u}=(\cc_t^\top \otimes \II_p);\, \uupsilon=\vec(\CC)\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq; +\, \ff_{t,q}= 0;\, \DD_{t,q}= \DD_q \\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta; +\, \ff_{t,z} = 0;\, \DD_{t,z}=1;\, \zzeta=\vec(\ZZ)\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha; +\, \ff_{t,a} = 0;\, \DD_{t,a}=(\dd_t^\top \otimes \II_q);\, \aalpha=\vec(\DD)\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr; +\, \ff_{t,r}= 0;\, \DD_{t,r}= \DD_r \\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda; +\, \ff_\lambda= 0 \\ +\vec(\xixi)&= \xixi=\ff_\xi+\DD_\xi\pp; +\, \ff_\xi = 0; \, \DD_\xi = 1 +\end{split} +\end{equation*} +Note that variance-covariance matrices are never unconstrained really so we use $\DD_q$, $\DD_r$ and $\DD_\lambda$ to specify the symmetry within the matrix. + +The transformation of the simple MARSS with covariates (equation \ref{eq:MARSS.simple.ex}) into the form of equation \ref{eq:MARSS.ex.vec} may seem a little painful, but the advantage is that a single EM algorithm can be used for a large class of models. Presumably, the transformation of the equation will be hidden from users by a wrapper function that does the reformulation before passing the model to the general EM algorithm. In the MARSS R package, this reformulation is done in the \verb@MARSS.marxss@ function. + +\subsection{A general MARSS model with exogenous variables} +Let's imagine now a very general MARSS model with various `inputs'. ` +input' here just means that it is some fully known matrix rather than something we are estimating. It could be a sequence of 0s and 1s if for example we were fitting a before/after sort of model. Below the letters with a $t$ subscript are the inputs (and $\Ab_t$ is an input not a design matrix), except $\xx$, $\yy$, $\ww$ and $\vv$. +\begin{equation}\label{eq:MARSS.general.ex} +\begin{split} +\xx_t &= \Bb_t\BB\Ba_t\xx_{t-1} + \Ub_t\UU\Ua_t + \Qb_t\ww_t\\ +\yy_t &= \Zb_t\ZZ\Za_t\xx_t + \Ab_t\AA\Aa_t + \Rb_t\vv_t +\end{split} +\end{equation} +In vec form, this is: +\begin{equation}\label{eq:MARSS.ex3} +\begin{split} +\xx_t &= (\xx_{t-1}^\top \otimes \II_m)(\Ba_t^\top \otimes \Bb_t)\vec(\BB) + (\Ua_t^\top \otimes \Ub_t)\vec(\UU) ++ \Qb_t\ww_t\\ +&= (\xx_{t-1}^\top \otimes \II_m)(\Ba_t^\top \otimes \Bb_t)(\ff_b+\DD_b\bbeta) + (\Ua_t^\top \otimes \Ub_t)(\ff_u + \DD_u\uupsilon) + \Qb_t\ww_t\\ +\WW_t & \sim \MVN(0,\Qb_t\QQ\Qb_t^\top)\\ +\\ +\yy_t &= (\xx_t^\top \otimes \II_n)(\Za_t^\top \otimes \Zb_t)\vec(\ZZ) + (\Aa_t^\top \otimes \Ab_t)\vec(\AA) + \Rb_t\vv_t \\ +&= (\xx_t^\top \otimes \II_n)\mathbb{Z}_t(\ff_z+\DD_z\zzeta) + \mathbb{A}_t(\ff_a+\DD_a\aalpha) + \Rb_t\vv_t \\ +\VV_t &\sim \MVN(0,\Rb_t\RR\Rb_t^\top)\\ +\\ +\XX_{t_0} &\sim \MVN(\ff_\xi+\DD_\xi\pp,\FF\LAM\FF^\top), \text{ where } \vec(\LAM)=\ff_\lambda+\DD_\lambda\llambda +\end{split} +\end{equation} +We could write down a likelihood function for this model but written this way, the model presumes that $\Rb_t\RR\Rb_t^\top$, $\Qb_t\QQ\Qb_t^\top$, and $\FF\LAM\FF^\top$ are valid variance-covariance matrices. I will actually write this model differently below because I don't want to make that assumption. + +We define the $\ff$ and $\DD$ parameters as follows. +\begin{equation*} +\begin{split} +\vec(\BB_t) &= \ff_{t,b} + \DD_{t,b}\bbeta = (\Ba_t^\top \otimes \Bb_t)\ff_b + (\Ba_t^\top \otimes \Bb_t)\DD_b\bbeta\\ +\vec(\uu_t) &= \ff_{t,u} + \DD_{t,u}\uupsilon = (\Ua_t^\top \otimes \Ub_t)\ff_u + (\Ua_t^\top \otimes \Ub_t)\DD_u\uupsilon\\ +\vec(\QQ_t) &= \ff_{t,q} + \DD_{t,q}\qq = (\Qb_t \otimes \Qb_t)\ff_q + (\Qb_t \otimes \Qb_t)\DD_q\qq \\ +\vec(\ZZ_t) &= \ff_{t,z} + \DD_{t,z}\zzeta = (\Za_t^\top \otimes \Zb_t)\ff_z + (\Za_t^\top \otimes \Zb_t)\DD_z\zzeta\\ +\vec(\aa_t) &= \ff_{t,a} + \DD_{t,a}\aalpha = (\Aa_t^\top \otimes \Ab_t)\ff_a + (\Aa_t^\top \otimes \Ab_t)\DD_a\aalpha\\ +\vec(\RR_t) &= \ff_{t,r} + \DD_{t,r}\rr = (\Rb_t \otimes \Rb_t)\ff_q + (\Rb_t \otimes \Rb_t)\DD_r\rr\\ +\vec(\LAM)&= \ff_\lambda+\DD_\lambda\llambda = 0 + \DD_\lambda\llambda\\ +\vec(\xixi)&= \xixi=\ff_\xi+\DD_\xi\pp = 0+1\pp +\end{split} +\end{equation*} +Here, for example $\ff_b$ and $\DD_b$ indicate the linear constraints on $\BB$ and $\ff_{t,b}$ is $(\Ba_t^\top \otimes \Bb_t)\ff_b$ and $\DD_{t,b}$ is $(\Ba_t^\top \otimes \Bb_t)\DD_b$. The elements of $\BB$ that are being estimated are $\bbeta$ arranged as a column vector. + +As usual, this reformulation looks cumbersome, but would be hidden from the user presumably. + +\subsection{The expected log-likelihood function} +As mentioned above, we do not necessarily want to assume that $\HH_t\RR_t\HH_t^\top$, $\GG_t\QQ_t\GG_t^\top$, and $\FF\LAM\FF^\top$ are valid variance-covariance matrices. This would rule out many MARSS models that we would like to fit. For example, if $\QQ=\sigma^2$ and $\GG=\begin{bmatrix}1\\ 1\\ 1\end{bmatrix}$, $\GG\QQ\GG^\top$ would be an invalid variance-variance matrix. However, this is a valid MARSS model. We do need to be careful that $\HH_t$ and $\GG_t$ are specified such that the model has a solution. For example, a model where both $\GG$ and $\HH$ are $\begin{bmatrix}1\\ 1\\ 1\end{bmatrix}$ would not be solvable for all $\yy$. + +Instead I will define $\Phi_t=(\GG_t^\top\GG_t)^{-1}\GG_t^\top$, $\Xi_t=(\HH_t^\top\HH_t)^{-1}\HH_t^\top$, and $\Pi = (\FF^\top\FF)^{-1}\FF^\top$. I then require that the inverses of $\GG_t^\top\GG_t$, $\HH_t^\top\HH_t$, and $\FF^\top\FF$ exist and that $\ff_{t,q}+\DD_{t,q}\qq$, $\ff_{t,r}+\DD_{t,r}\rr$, and $\ff_\lambda+\DD_\lambda\llambda$ specify valid variance-covariance matrices. These are much less stringent restrictions. + +For the purpose of writing down the expected log-likelihood, our MARSS model is now written +\begin{equation}\label{eq:MARSS.ex.reformed} +\begin{gathered} +\Phi_t\xx_t = \Phi_t( \xx_{t-1}^\top \otimes \II_m)\vec(\BB_t) + \Phi_t\vec(\uu_t) + \ww_t, \quad +\text{ where } \WW_t \sim \mathrm{MVN}(0,\QQ_t)\\ +\Xi_t\yy_t = \Xi_t( \xx_t^\top \otimes \II_n)\vec(\ZZ_t) + \Xi_t\vec(\aa_t) + \vv_t,\quad \text{ where } \VV_t \sim \mathrm{MVN}(0,\RR_t)\\ +\Pi\xx_{t_0}=\Pi\xixi+\ll, \quad \text{ where } \LL \sim \MVN(0,\LAM) +\end{gathered} +\end{equation} +As mentioned before, this relies on $\GG$ and $\HH$ having forms that do not lead to over- or under-constrained linear systems. + +To derive the EM update equations, we need the expected log-likelihood function for the time-varying MARSS model. Using equation \ref{eq:MARSS.ex.reformed}, we get +\begin{equation}\label{eq:logL.vec.general} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - ( \XX_t^\top \otimes \II_m)\vec(\ZZ_t) - \vec(\aa_t) )^\top\Xi_t^\top \RR_t^{-1}\Xi_t\\ +&\quad (\YY_t-(\XX_t^\top \otimes \II_m)\vec(\ZZ_t) - \vec(\aa_t))+\sum_1^T \log |\RR_t|\\ +&\quad +\sum_{t_0+1}^T(\XX_t-(\XX_{t-1}^\top \otimes \II_m)\vec(\BB_t) - \vec(\uu_t) )^\top \Phi_t^\top\QQ_t^{-1}\Phi_t \\ +&\quad ( \XX_t-(\XX_{t-1}^\top \otimes \II_m)\vec(\BB_t) - \vec(\uu_t) )+\sum_{t_0+1}^T\log |\QQ_t|\\ +&\quad +(\XX_{t_0}-\vec(\xixi))^\top \Pi^\top\LAM^{-1}\Pi (\XX_{t_0}-\vec(\xixi)) + \log |\LAM| + \log 2\pi \bigg) +\end{split} +\end{equation} +If any $\GG_t$, $\HH_t$ or $\FF$ is all zero, then the line in the likelihood with $\RR_t$, $\QQ_t$ or $\LAM$, respectively, does not appear. If any $\xx_{t_0}$ are fixed, meaning all zero row in $\FF$, that $\XX_{t_0}\equiv\xixi$ anywhere it appears in the likelihood. The way I have written the general equation, some $\xx_{t_0}$ might be fixed and others stochastic. + +The vec of the model parameters are defined as follows: +\begin{equation*} +\begin{split} +\vec(\BB_t)&=\ff_{t,b}+\DD_{t,b}\bbeta\\ +\vec(\uu_t) &= \ff_{t,u}+\DD_{t,u}\uupsilon\\ +\vec(\ZZ_t)&=\ff_{t,z}+\DD_{t,z}\zzeta\\ +\vec(\aa_t) &= \ff_{t,a}+\DD_{t,a}\aalpha\\ +\vec(\QQ_t)&=\ff_{t,q}+\DD_{t,q}\qq\\ +\vec(\RR_t)&=\ff_{t,r}+\DD_{t,r}\rr\\ +\vec(\xixi)&=\ff_\xi+\DD_\xi\pp\\ +\vec(\LAM)&=\ff_\lambda+\DD_\lambda\llambda\\ +\Phi_t&=(\GG_t^\top\GG_t)^{-1}\GG_t^\top\\ +\Xi_t&=(\HH_t^\top\HH_t)^{-1}\HH_t^\top\\ +\Pi&=(\FF^\top\FF)^{-1}\FF^\top +\end{split} +\end{equation*} + +\section{The constrained update equations}\label{sec:constrained} +The derivation proceeds by taking the partial derivative of equation \ref{eq:logL.vec.general} with respect to the estimated terms, the $\zzeta$, $\aalpha$, etc, setting the derivative to zero, and solving for those estimated terms. Conceptually, the algebraic steps in the derivation are similar to those in the unconstrained derivation. See the notes in Sections \ref{sec:generalupdate} and \ref{sec:EMalgorithm} regarding implementation of the EM algorithm when $\Theta$ is broken into parts (e.g., $\BB$, $\uu$, $\QQ$, etc.). + +\subsection{The general $\uu$ update equations} +We take the derivative of $\Psi$ (equation \ref{eq:logL.vec.general}) with respect to $\uupsilon$. +\begin{equation}\label{eq:u.general1} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} + &= - \frac{1}{2}\sum_{t=1}^T \bigg(-\partial(\E[\XX_t^\top\Qm_t\DD_{t,u}\uupsilon])/\partial\pmb{\upsilon} + - \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t\XX_t])/\partial\pmb{\upsilon} \\ +&+ \partial(\E[(( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t))^\top\Qm_t\DD_{t,u}\uupsilon] )/\partial\pmb{\upsilon} + + \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t)])/\partial\pmb{\upsilon}\\ +&+ \partial(\uupsilon^\top\DD_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon)/\partial\pmb{\upsilon} ++ \partial(\E[\ff_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon])/\partial\pmb{\upsilon} + + \partial(\E[\uupsilon^\top\DD_{t,u}^\top\Qm_t\ff_{t,u}])/\partial\pmb{\upsilon} +\bigg) +\end{split} +\end{equation} +where $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t$. + +Since $\uupsilon$ is to the far left or right in each term, the derivative is simple using the derivative terms in table \ref{sec:MatrixDerivatives}. +$\partial\Psi/\partial\pmb{\upsilon}$ becomes: +\begin{equation}\label{eq:u.general1b} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} +&= - \frac{1}{2}\sum_{t=1}^T \bigg( +-2\E[\XX_t^\top\Qm_t\DD_{t,u}] + 2\E[(( \XX_{t-1}^\top \otimes \II_m)\vec(\BB_t))^\top \Qm_t\DD_{t,u}] \\ +&\quad + 2(\uupsilon^\top\DD_{t,u}^\top\Qm_t\DD_{t,u}) + 2\E[ \ff_{t,u}^\top\Qm_t\DD_{t,u} ] \bigg) +\end{split}\end{equation} +Set the left side to zero and transpose the whole equation. +\begin{equation}\label{eq:u.general4} +\begin{split} +\mathbf{0}= \sum_{t=1}^T \bigg( \DD_{t,u}^\top\Qm_t\E[\XX_t] - \DD_{t,u}^\top\Qm_t(\E[\XX_{t-1}]^\top \otimes \II_m)\vec(\BB_t) +- \DD_{t,u}^\top\Qm_t\DD_{t,u}\uupsilon + - \DD_{t,u}^\top\Qm_t\ff_{t,u} \bigg) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:u.general5} +\big(\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u} \big)\uupsilon + = \sum_{t=1}^T \DD_{t,u}^\top\Qm_t\big(\E[ \XX_t ]- (\E[\XX_{t-1}]^\top \otimes \II_m)\vec(\BB_t) - \ff_{t,u} \big) +\end{equation} +We solve for $\uupsilon$, and the new $\uupsilon$ for the $j+1$ iteration of the EM algorithm is +\begin{equation}\label{eq:u.general.update1} +\begin{split} +\uupsilon_{j+1} &= \bigg(\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u} \bigg)^{-1} + \sum_{t=1}^T \DD_{t,u}^\top\Qm_t\big(\hatxt- (\hatxtm^\top \otimes \II_m)\vec(\BB_t) - \ff_{t,u} \big) +\end{split} +\end{equation} +where $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t = \GG_t(\GG_t^\top\GG_t)^{-1}\QQ_t^{-1}(\GG_t^\top\GG_t)^{-1}\GG_t^\top$. + +The update equation requires that $\sum_{t=1}^T \DD_{t,u}^\top\Qm_t\DD_{t,u}$ is invertible. It generally will be if $\Phi_t\QQ_t\Phi_t^\top$ is a proper variance-covariance matrix (positive semi-definite) and $\DD_{t,u}$ is full rank. If $\GG_t$ has all-zero rows then $\Phi_t\QQ_t\Phi_t^\top$ has zeros on the diagonal and we have a partially deterministic model. In this case, $\Qm_t$ will have all-zero row/columns and $\DD_{t,u}^\top\Qm_t\DD_{t,u}$ will not be invertible unless the corresponding row of $\DD_{t,u}$ is zero. This means that if one of the $\xx$ rows is fully deterministic then the corresponding row of $\uu$ would need to be fixed. We can get around this, however. See section \ref{sec:degenerate} on the modifications to the update equation when some of the $\xx$'s are fully deterministic. + +\subsection{The general $\aa$ update equation}\label{sec:constA} +The derivation of the update equation for $\aalpha$ with fixed and shared values is completely analogous to the derivation for $\uupsilon$. We take the derivative of $\Psi$ with respect to $\aalpha$ and arrive at the analogous: +\begin{equation}\label{eq:general.a.update} +\begin{split} +\aalpha_{j+1} &= \big(\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a} \big)^{-1} + \sum_{t=1}^T \DD_{t,a}^\top\Rm_t\big(\hatyt- (\hatxt^\top \otimes \II_n)\vec(\ZZ_t) - \ff_{t,a} \big) \\ + &= \big(\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a} \big)^{-1} + \sum_{t=1}^T \DD_{t,a}^\top\Rm_t\big(\hatyt- \ZZ_t\hatxt - \ff_{t,a} \big) +\end{split} +\end{equation} +$\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a}$ must be invertible. + +\subsection{The general $\xixi$ update equation, stochastic initial state} +When $\xx_0$ is treated as stochastic with an unknown mean and known variance, the derivation of the update equation for $\xixi$ with fixed and shared values is as follows. Take the derivative of $\Psi$ (using equation \ref{eq:logL.vec.general}) with respect to $\pp$: +\begin{equation}\label{eq:pi.general1} +\partial\Psi/\partial\pp = +\big(\widetilde{\mbox{$\mathbf x$}}_0^\top \LAMm - \xixi^\top\LAMm \big) +\end{equation} +Replace $\xixi$ with $\ff_\xi + \DD_\xi\pp$, set the left side to zero and transpose: +\begin{equation}\label{eq:pi.general2} +\mathbf{0} = +\DD_\xi^\top\big(\LAMm\widetilde{\mbox{$\mathbf x$}}_0 - \LAMm\ff_\xi + \LAMm\DD_\xi\pp \big) +\end{equation} +Thus, +\begin{equation}\label{eq:pi.update.general1} +\pp_{j+1} = \big(\DD_\xi^\top\LAMm\DD_\xi \big)^{-1} +\DD_\xi^\top\LAMm(\widetilde{\mbox{$\mathbf x$}}_0 - \ff_\xi) +\end{equation} +and the new $\xixi$ is then, +\begin{equation}\label{eq:pi.update.general2} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} +When the initial state is defined as at $t=1$, replace $\widetilde{\mbox{$\mathbf x$}}_0$ with $\widetilde{\mbox{$\mathbf x$}}_1$ in equation \ref{eq:pi.update.general1}. + +\subsection{The general $\xixi$ update equation, fixed $\xx_0$}\label{sec:xi.constrained.x0} +For this case, $\xx_0$ is treated as fixed, i.e., as another parameter, and $\LAM$ does not appear in the equation. It will be easier to work with $\Psi$ written as follows: +\begin{equation}\label{eq:logL.vec.general.V0.is.0b} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - \ZZ_t\XX_t - \aa_t)^\top \Rm_t(\YY_t - \ZZ_t\XX_t - \aa_t) + +\sum_1^T \log |\RR_t|\\ +&\quad +\sum_1^T(\XX_t - \BB_t\XX_{t-1} - \uu_t)^\top \Qm_t (\XX_t - \BB_t\XX_{t-1} - \uu_t) + +\sum_1^T\log |\QQ_t| + \log 2\pi\bigg)\\ +&\quad \xx_0 \equiv \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} +This is the same as equation \ref{eq:logL.vec.general} except not written in vec form and $\LAM$ does not appear. Take the derivative of $\Psi$ using equation \ref{eq:logL.vec.general.V0.is.0b}. Terms not involving $\pp$ will drop out: +\begin{equation}\label{eq:pi.constrained.V0.is.0} +\begin{split} +&\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( -\E[\partial(\mathbb{P}_1^\top\Qm_1\BB_1\DD_\xi\pp)/\partial\pp] -\E[\partial(\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\mathbb{P}_1)/\partial\pp] \\ +&\quad +\E[\partial(\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\BB_1\DD_\xi\pp)/\partial\pp] +\bigg) +\end{split} +\end{equation} +where +\begin{equation} +\mathbb{P}_1=\XX_1 - \BB_1\ff_\xi - \uu_1 +\end{equation} + +After pulling the constants out of the expectations and taking the derivative, we arrive at: +\begin{equation} +\begin{split} +\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( - 2\E[\mathbb{P}_1]^\top\Qm_1\BB_1\DD_\xi ++ 2\pp^\top(\BB_1\DD_\xi)^\top\Qm_1\BB_1\DD_\xi +\bigg) +\end{split} +\end{equation} +Set the left side to zero, and solve for $\pp$. +\begin{equation}\label{eq:pi.constrained.V0.is.0.4} +\pp = (\DD_\xi^\top\BB_1^\top\Qm_1\BB_1\DD_\xi)^{-1}\DD_\xi^\top\BB_1^\top\Qm_1(\hatxone - \BB_1\ff_\xi - \uu_1) +\end{equation} + +This equation requires that the inverse right of the $=$ exists and it might not if $\BB_t$ or $\Qm_1$ has any all zero rows/columns. In that case, defining $\xixi \equiv \xx_1$ might work (section \ref{sec:general.x1.update}) or the problematic rows of $\xixi$ could be fixed. +The new $\xixi$ is then, +\begin{equation} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} + +\subsection{The general $\xixi$ update equation, fixed $\xx_1$}\label{sec:general.x1.update} +When $\xx_1$ is treated as fixed, i.e., as an estimated parameter, and $\LAM$ does not appear, the expected log likelihood, $\Psi$, is written as follows: +\begin{equation}\label{eq:logL.vec.general.V0.is.0.x1} +\begin{split} +&\EXy[\log\LL(\YY,\XX ; \Theta)] = -\frac{1}{2}\EXy\bigg( + \sum_1^T(\YY_t - \ZZ_t\XX_t - \aa_t)^\top \Rm_t (\YY_t - \ZZ_t\XX_t - \aa_t) +\sum_1^T \log |\RR_t|\\ +&\quad +\sum_2^T(\XX_t - \BB_t\XX_{t-1} - \uu_t)^\top \Qm_t (\XX_t - \BB_t\XX_{t-1} - \uu_t) + +\sum_2^T\log |\QQ_t| + \log 2\pi\bigg)\\ +&\quad \xx_1 \equiv \ff_\xi+\DD_\xi\pp +\end{split} +\end{equation} +Take the derivative of $\Psi$ using equation \ref{eq:logL.vec.general.V0.is.0.x1}: +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pp = -\frac{1}{2} \bigg( +-\E[\partial(\mathbb{O}_1^\top\Rm_1\ZZ_1\DD_\xi\pp)/\partial\pp] -\E[\partial((\ZZ_1\DD_\xi\pp)^\top\Rm_1\mathbb{O}_1)/\partial\pp] \\ +&\quad +\E[\partial((\ZZ_1\DD_\xi\pp)^\top\Rm_1\ZZ_1\DD_\xi\pp)/\partial\pp] + -\E[\partial(\mathbb{P}_2^\top\Qm_2\BB_2\DD_\xi\pp)/\partial\pp] -\E[\partial((\BB_2\DD_\xi\pp)^\top\Qm_2\mathbb{P}_2)/\partial\pp] \\ +&\quad +\E[\partial((\BB_2\DD_\xi\pp)^\top\Qm_2\BB_2\DD_\xi\pp)/\partial\pp] +\bigg) +\end{split} +\end{equation} +where +\begin{equation} +\begin{split} +\mathbb{P}_2&=\XX_2 - \BB_2\ff_\xi - \uu_2\\ +\mathbb{O}_1&=\YY_1 - \ZZ_1\ff_\xi - \aa_1\\ +\end{split} +\end{equation} + +In terms of the Kalman smoother output the new $\xixi$ for EM iteration $j+1$ when $\xixi \equiv \xx_1$ is +\begin{equation}\label{eq:pix1.unconstrained.V0.is.0.t.1.3} +\begin{split} +\pp_{j+1} &= ((\ZZ_1\DD_\xi)^\top\Rm_1\ZZ_1\DD_\xi + +(\BB_2\DD_\xi)^\top\Qm_2\BB_2\DD_\xi)^{-1} +( (\ZZ_1\DD_\xi)^\top\Rm_1\widetilde{\mathbb{O}}_1 + (\BB_2\DD_\xi)^\top\Qm_2\widetilde{\mathbb{P}}_2) +\end{split} +\end{equation} +where +\begin{equation} +\begin{split} +\widetilde{\mathbb{P}}_2 &=\widetilde{\mbox{$\mathbf x$}}_2 - \BB_2\ff_\xi - \uu_2\\ +\widetilde{\mathbb{O}}_1 &=\widetilde{\mbox{$\mathbf y$}}_1 - \ZZ_1\ff_\xi - \aa_1 +\end{split} +\end{equation} +The new $\xixi$ is +\begin{equation} +\xixi_{j+1} = \ff_\xi + \DD_\xi\pp_{j+1}, +\end{equation} + +\subsection{The general $\BB$ update equation} +Take the derivative of $\Psi$ with respect to $\bbeta$; terms in $\Psi$ do not involve $\bbeta$ will equal 0 and drop out. +\begin{equation}\label{eq:B.general1} +\begin{split} +\partial\Psi/\partial\bbeta + &= - \frac{1}{2}\sum_{t=1}^T \bigg( -\partial(\E[\XX_t^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + - \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\XX_t])/\partial\bbeta \\ +&+ \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + + \partial(\E[\uu_t^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta ++ \partial((\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\uu_t)/\partial\bbeta \\ +&+ \partial(\E[(\Bm_t\ff_{t,b})^\top\Qm_t\Bm_t\DD_{t,b}\bbeta])/\partial\bbeta + + \partial(\E[(\Bm_t\DD_{t,b}\bbeta)^\top\Qm_t\Bm_t\ff_{t,b}])/\partial\bbeta +\bigg)\end{split} +\end{equation} +where +\begin{equation} +\Bm_t = (\XX_{t-1}^\top \otimes \II_m) +\end{equation}Since $\bbeta$ is to the far left or right in each term, the derivative is simple using the derivative terms in table \ref{sec:MatrixDerivatives}. +$\partial\Psi/\partial\bbeta$ becomes: +\begin{equation}\label{eq:B.general1b} +\begin{split} +\partial\Psi/\partial\pmb{\upsilon} +&= - \frac{1}{2}\sum_{t=1}^T \bigg( +-2\E[\XX_t^\top\Qm_t\Bm_t\DD_{t,b}] + 2(\beta^\top\DD_{t,b}^\top\Bm_t^\top\Qm_t\Bm_t\DD_{t,b}) \\ +&+ 2\E[\uu_t^\top\Qm_t\Bm_t\DD_{t,b}] + 2\E[(\Bm_t\ff_{t,b})^\top\Qm_t\Bm_t\DD_{t,b}] \bigg) +\end{split}\end{equation} +Note that $\XX$ appears in $\Bm_t$ but not in other terms. We need to keep track of where $\XX$ appears so the we keep the expectation brackets around any terms involving $\XX$. +\begin{equation} +\begin{split} +\partial\Psi/\partial\bbeta += \sum_{t=1}^T \bigg( +\E[\XX_t^\top\Qm_t\Bm_t]\DD_{t,b} - \uu_t^\top\Qm_t\E[\Bm_t]\DD_{t,b} +- \bbeta^\top\DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} - \ff_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} \bigg) +\end{split} +\end{equation} +Set the left side to zero and transpose the whole equation. +\begin{equation} +\mathbf{0} + = \sum_{t=1}^T \bigg( +\DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\XX_t]- \DD_{t,b}^\top\E[\Bm_t]^\top\Qm_t\uu_t + - \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\ff_{t,b} + - \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b}\bbeta \bigg) +\end{equation} +Thus, +\begin{equation} +\big(\sum_{t=1}^T \DD_{t,b}^\top\E[\Bm_t^\top\Qm_t\Bm_t]\DD_{t,b} \big)\bbeta + = \sum_{t=1}^T \DD_{t,b}^\top\big( + \E[\Bm_t^\top\Qm_t\XX_t] + - \E[\Bm_t]^\top\Qm_t\uu_t + - \E[\Bm_t^\top\Qm_t\Bm_t]\ff_{t,b} \big) +\end{equation} +Now we need to deal with the expectations. +\begin{equation}\label{eq:B.expect1} +\begin{split} +\E[\Bm_t^\top\Qm_t\Bm_t] +&=\E[(\XX_{t-1}^\top \otimes \II_m)^\top\Qm_t(\XX_{t-1}^\top \otimes \II_m)]\\ +&=\E[(\XX_{t-1} \otimes \II_m)\Qm_t(\XX_{t-1}^\top \otimes \II_m)]\\ +&=\E[\XX_{t-1}\XX_{t-1}^\top \otimes \Qm_t]\\ +&=\E[\XX_{t-1}\XX_{t-1}^\top] \otimes \Qm_t\\ +&=\hatPtm \otimes \Qm_t +\end{split} +\end{equation} + +\begin{equation}\label{eq:B.expect2} +\begin{split} +\E[\Bm_t^\top\Qm_t\XX_t] +&=\E[(\XX_{t-1}^\top \otimes \II_m)^\top\Qm_t\XX_t]\\ +&=\E[(\XX_{t-1} \otimes \II_m)\Qm_t\XX_t]\\ +&=\E[(\XX_{t-1} \otimes \Qm_t)\XX_t]\\ +&=\E[\vec(\Qm_t\XX_t\XX_{t-1}^\top)]\\ +&=\vec(\Qm_t\hatPttm) +\end{split} +\end{equation} + +\begin{equation}\label{eq:B.expect3} +\begin{split} +\E[\Bm_t]^\top\Qm_t\uu_t&=(\E[\XX_{t-1}] \otimes \II_m)\Qm_t\uu_t \\ +&= (\hatxtm \otimes \Qm_t)\uu_t \\ +&= \vec(\Qm_t\uu_t\hatxtm^\top) +\end{split} +\end{equation} + +Thus, +\begin{equation} +\begin{split} +\big(\sum_{t=1}^T &\DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b} \big)\bbeta + = \sum_{t=1}^T \DD_{t,b}^\top \big(\vec(\Qm_t\hatPttm) - (\hatPtm \otimes \Qm_t)\ff_{t,b} - \vec(\Qm_t\uu_t\hatxtm^\top) \big) +\end{split} +\end{equation} +Then $\bbeta$ for the $j+1$ iteration of the EM algorithm is then: +\begin{equation}\label{eq:B.general4} +\begin{split} +\bbeta = \bigg(\sum_{t=1}^T \DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b} \bigg)^{-1} +\times \sum_{t=1}^T \DD_{t,b}^\top \big(\vec(\Qm_t\hatPttm) - (\hatPtm \otimes \Qm_t)\ff_{t,b} - \vec(\Qm_t\uu_t\hatxtm^\top) \big) +\end{split} +\end{equation} + +This requires that $\DD_{t,b}^\top(\hatPtm \otimes \Qm_t)\DD_{t,b}$ is invertible, and as usual we will run into trouble if $\Phi_t\QQ_t\Phi_t^\top$ has zeros on the diagonal. See section \ref{sec:degenerate}. + +\subsection{The general $\ZZ$ update equation}\label{sec:constZ} +The derivation of the update equation for $\zzeta$ with fixed and shared values is analogous to the derivation for $\bbeta$. The update equation for $\zzeta$ is +\begin{equation}\label{eq:general.Z.update} +\begin{split} +\zzeta_{j+1} = +\bigg(\sum_{t=1}^T \DD_{t,z}^\top(\hatPt \otimes \Rm_t)\DD_{t,z} \bigg)^{-1} +\times \sum_{t=1}^T \DD_{t,z}^\top \big(\vec(\Rm_t\hatYXt) - (\hatPt \otimes \Rm_t)\ff_{t,z} - \vec(\Rm_t\aa_t\hatxt^\top) \big) +\end{split} +\end{equation} + +This requires that $\DD_{t,z}^\top(\hatPt \otimes \Rm_t)\DD_{t,z}$ is invertible. If $\Xi_t\RR_t\Xi_t^\top$ has zeros on the diagonal, this will not be the case. See section \ref{sec:degenerate}. + +\subsection{The general $\QQ$ update equation}\label{sec:constrained.Q} +A general analytical solution for $\QQ$ is problematic because the inverse of $\QQ_t$ appears in the likelihood and $\QQ_t^{-1}$ cannot always be rewritten as a function of $\vec(\QQ_t)$. However, in a few important special---yet quite broad--- cases, an analytical solution can be derived. The most general of these special cases is a block-symmetric matrix with optional independent fixed blocks (subsection \ref{sec:Q.general}). Indeed, all other cases (diagonal, block-diagonal, unconstrained, equal variance-covariance) except one (a replicated block-diagonal) are special cases of the blocked matrix with optional independent fixed blocks. + +Unlike the other parameters, I need to put constraints on $\ff$ and $\DD$. I constrain $\DD$ to be a design matrix. It has only 1s and 0s, and the rows sums are either 1 or 0. Thus terms like $q_1+q_2$ are not allowed. A non-zero value in $\ff$ is only allowed if the corresponding row in $\DD$ is all zero. Thus elements like $f_1+q_1$ are not allowed in $\QQ$. These constraints, especially the constraint that $\DD$ only has 0s and 1s, might be loosened, but with the addition of $\GG_t$, we still have a very wide class of $\QQ$ matrices. + +The general update equation for $\QQ$ with these constraints is +\begin{equation}\label{eq:Q.general} +\begin{split} +\qq_{j+1} &= \big(\sum_{t=1}^T(\DD_{t,q}^\top\DD_{t,q})\big)^{-1} \sum_{t=1}^T\DD_{t,q}^\top\vec(\SS_t)\\ +\text{where }\SS_t&=\Phi_t\big(\hatPt - \hatPttm \BB_t^\top - \BB_t\hatPtmt +- \hatxt\uu_t^\top - \uu_t\hatxt^\top + \\ +&\quad \BB_t\hatPtm\BB_t^\top + \BB_t\hatxtm\uu_t^\top + \uu_t\hatxtm^\top\BB_t^\top + \uu_t\uu_t^\top \big)\Phi_t^\top\\ +\vec(\QQ_t)_{j+1}&=\ff_{t,q}+\DD_{t,q}\qq_{j+1} \\ +\text{where}\\ +\Phi_t = (\GG_t^\top\GG_t)^{-1}\GG_t^\top +\end{split} +\end{equation} + +The vec of $\QQ_t$ is written in the form of $\vec(\QQ_t) = \ff_{t,q} + \DD_{t,q} \pmb{q}$, where $\ff_{t,q}$ is a $p^2 \times 1$ column vector of the fixed values including zero, $\DD_{t,q}$ is the $p^2 \times s$ design matrix, and $\pmb{q}$ is a column vector of the $s$ free values in $\QQ_t$. This requires that $(\DD_{t,q}^\top\DD_{t,q})$ be invertible, which in a valid model must be true; if is not true you have specified an invalid variance-covariance structure since the implied variance-covariance matrix will not be full-rank and not invertible and thus an invalid variance-covariance matrix. + +Below I show how the $\QQ$ update equation arises by working through a few of the special cases. In these derivations the $q$ subscript is left off the $\DD$ and $\ff$ matrices. + +\subsubsection{Special case: diagonal $\QQ$ matrix (with shared or unique parameters)} +Let $\QQ$ be a non-time varying diagonal matrix with fixed and shared values such that it takes a form like so: +\begin{equation*} +\QQ= +\begin{bmatrix} +q_1&0&0&0&0\\ +0&f_1&0&0&0\\ +0&0&q_2&0&0\\ +0&0&0&f_2&0\\ +0&0&0&0&q_2 +\end{bmatrix} +\end{equation*} +Here, $f$'s are fixed values (constants) and $q$'s are free parameters elements. The $f$ and $q$ do not occur together; i.e., there are no terms like $f_1+q_1$. + + +The vec of $\QQ^{-1}$ can be written then as $\vec(\QQ^{-1}) = \ff^{*}_q + \DD_q \pmb{q^{*}}$, where $\ff^{*}$ is like $\ff_q$ but with the corresponding $i$-th non-zero fixed values replaced by $1/f_i$ and $\pmb{q^{*}}$ is a column vector of 1 over the $q_i$ values. For the example above, +\begin{equation*} +\pmb{q^{*}} = +\begin{bmatrix} +1/q_1 \\ 1/q_2 +\end{bmatrix} +\end{equation*} + +Take the partial derivative of $\Psi$ with respect to $\pmb{q^{*}}$. We can do this because $\QQ^{-1}$ is diagonal and thus each element of $\pmb{q^{*}}$ is independent of the other elements; otherwise we would not necessarily be able to vary one element of $\pmb{q^{*}}$ while holding the other elements constant. +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\partial\bigg( +\E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] +-\E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] \\ +&\quad -\E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] + - \E[\XX_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t] \\ +&\quad - \E[\uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\XX_t] ++ \E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] \\ +&\quad + \E[(\BB_t\XX_{t-1})^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t] ++ \E[\uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\BB_t\XX_{t-1}] + \uu_t^\top\Phi_t^\top\QQ^{-1}\Phi_t\uu_t \bigg)/\partial\pmb{q^{*}}\\ +& - \partial\big(\frac{T}{2}\log |\QQ| \big)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +Use vec operation Equation \ref{eq:vec.aTBa} to pull $\QQ^{-1}$ out from the middle\footnote{Another, more common, way to do this is to use a ``trace trick'', $\trace(\aa^\top\AA\bb)=\trace(\AA\bb\aa^\top)$, to pull $\QQ^{-1}$ out.}, using +$$\aa^\top \Phi^\top \QQ^{-1} \Phi \bb = (\bb^\top\Phi^\top \otimes \aa^\top \Phi^\top)\vec(\QQ^{-1}) = (\bb^\top \otimes \aa^\top)(\Phi^\top \otimes \Phi^\top)\vec(\QQ^{-1})$$. +Then replace the expectations with the Kalman smoother output, +\begin{equation}\label{eq:Q.gendiag2} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\partial\bigg( +\E[\XX_t^\top \otimes \XX_t^\top ] +-\E[\XX_t^\top \otimes (\BB_t\XX_{t-1})^\top] -\E[(\BB_t\XX_{t-1})^\top \otimes \XX_t^\top] \\ +&\quad - \E[\XX_t^\top \otimes \uu_t^\top] - \E[\uu_t^\top \otimes \XX_t^\top] ++ \E[(\BB_t\XX_{t-1})^\top \otimes (\BB_t\XX_{t-1})^\top] \\ +&\quad + \E[(\BB_t\XX_{t-1})^\top \otimes \uu_t^\top] ++ \E[\uu_t^\top \otimes (\BB\XX_{t-1})^\top] + (\uu_t^\top \otimes \uu_t^\top) \bigg)(\Phi_t \otimes \Phi_t)^\top\vec(\QQ^{-1})/\partial\pmb{q^{*}}\\ +& - \partial\bigg(\frac{T}{2}\log |\QQ| \bigg)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +This can be further reduced using +$$(\bb^\top \otimes \aa^\top)(\Phi^\top \otimes \Phi^\top)=(\vec(\aa\bb^\top))^\top (\Phi \otimes \Phi)^\top = \vec(\Phi \aa\bb^\top \Phi^\top)^\top$$ +With this reduction and replacing $\log|\QQ|$ with $-\log|\QQ^{-1}|$, we get +\begin{equation} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = -\frac{1}{2} \sum_{t=1}^T\vec(\SS_t)^\top\partial\big(\vec(\QQ^{-1})\big)/\partial\pmb{q^{*}} ++ \partial\big(\frac{T}{2}\log|\QQ^{-1}| \big)/\partial\pmb{q^{*}} \\ +&\text{where }\\ +&\SS_t=\Phi_t\big(\hatPt - \hatPttm \BB_t^\top - \BB\hatPtmt +- \hatxt\uu_t^\top - \uu_t \hatxt^\top + \\ +&\quad \BB_t\hatPtm\BB_t^\top + \BB_t\hatxtm\uu_t^\top + \uu_t\hatxtm^\top\BB_t^\top + \uu_t\uu_t^\top \big)\Phi_t^\top +\end{split} +\end{equation} +The determinant of a diagonal matrix is the product of its diagonal elements. Thus, +\begin{equation}\label{eq:Q.gendiag3} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}}= + -\bigg(\frac{1}{2} \sum_{t=1}^T \vec(\SS_t)^\top (\ff^{*} + \DD_q\pmb{q^{*}}) \\ +&\quad - \frac{1}{2}\sum_{t=1}^T(\log(f^{*}_1) + \log(f^{*}_2) ... k\log(q^{*}_1) + l\log(q^{*}_2)...)\bigg)/\partial\pmb{q^{*}}\\ +\end{split} +\end{equation} +where $k$ is the number of times $q_1$ appears on the diagonal of $\QQ$ and $l$ is the number of times $q_2$ appears, etc. + +Taking the derivatives and transposing the whole equation we get, +\begin{equation}\label{eq:Q.gendiag4} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = += \frac{1}{2} \sum_{t=1}^T\DD_q^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T(\log(f^{*}_1) + ... k\log(q^{*}_1) + l\log(q^{*}_2)...)/\partial\pmb{q^{*}}\\ +&\quad = \frac{1}{2} \sum_{t=1}^T\DD_q^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T\DD_q^\top\DD_q\pmb{q} +\end{split} +\end{equation} +$\DD_q^\top\DD_q$ is a $s \times s$ matrix with $k$, $l$, etc. along the diagonal and thus is invertible; as usual, $s$ is the number of free elements in $\QQ$. Set the left side to zero (a $1 \times s$ matrix of zeros) and solve for $\pmb{q}$. This gives us the update equation for $\qq$ and $\QQ$: +\begin{equation}\label{eq:Q.diag.update} +\begin{split} +\qq_{j+1} &= \big(\sum_{t=1}^T\DD_q^\top\DD_q\big)^{-1}\sum_{t=1}^T\DD_q^\top\vec(\SS_t)\\ +\vec(\QQ)_{j+1} &= \ff + \DD_q\pmb{q}_{j+1} +\end{split} +\end{equation} +Since in this example, $\DD_q$ is time-constant, this reduces to +\begin{equation*} +\pmb{q}_{j+1} = \frac{1}{T}(\DD_q^\top\DD_q)^{-1}\DD_q^\top\sum_{t=1}^T\vec(\SS_t) +\end{equation*} +$\SS_t$ is defined in equation \ref{eq:Q.gendiag2}. + +\subsubsection{Special case: $\QQ$ with one variance and one covariance} +\begin{equation*} +\QQ= +\begin{bmatrix} +\alpha&\beta&\beta&\beta\\ +\beta&\alpha&\beta&\beta\\ +\beta&\beta&\alpha&\beta\\ +\beta&\beta&\beta&\alpha +\end{bmatrix}\quad\quad +\QQ^{-1}= +\begin{bmatrix} +f(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&f(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&g(\alpha,\beta)&f(\alpha,\beta)&g(\alpha,\beta)\\ +g(\alpha,\beta)&g(\alpha,\beta)&g(\alpha,\beta)&f(\alpha,\beta) +\end{bmatrix} +\end{equation*} +This is a matrix with a single shared variance parameter on the diagonal and a single shared covariance on the off-diagonals. The derivation is the same as for the diagonal case, until the step involving the differentiation of $\log|\QQ^{-1}|$: +\begin{equation}\label{eq:Q.eqvarcov1} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = + \partial\bigg(-\frac{1}{2} \sum_{t=1}^T\big(\vec(\SS_t)^\top\big)\vec(\QQ^{-1}) ++ \frac{T}{2}\log |\QQ^{-1}|\bigg)/\partial\pmb{q^{*}} \\ +\end{split} +\end{equation} +It does not make sense to take the partial derivative of $\log |\QQ^{-1}|$ with respect to $\vec(\QQ^{-1})$ because many elements of $\QQ^{-1}$ are shared so it is not possible to fix one element while varying another. Instead, we can take the partial derivative of $\log |\QQ^{-1}|$ with respect to $g(\alpha,\beta)$ which is $\sum_{\{i,j\}\in \text{set}_g}\partial\log|\QQ^{-1}|/\partial\pmb{q^{*}}_{i,j}$. Set $g$ is those $i,j$ values where $\pmb{q^{*}}=g(\alpha,\beta)$. Because $g()$ and $f()$ are different functions of both $\alpha$ and $\beta$, we can hold one constant while taking the partial derivative with respect to the other (well, presuming there exists some combination of $\alpha$ and $\beta$ that would allow that). But if we have fixed values on the off-diagonal, this would not be possible. In this case (see below), we cannot hold $g()$ constant while varying $f()$ because both are only functions of $\alpha$: +\begin{equation*} +\QQ= +\begin{bmatrix} +\alpha&f&f&f\\ +f&\alpha&f&f\\ +f&f&\alpha&f\\ +f&f&f&\alpha +\end{bmatrix}\quad\quad +\QQ^{-1}= +\begin{bmatrix} +f(\alpha)&g(\alpha)&g(\alpha)&g(\alpha)\\ +g(\alpha)&f(\alpha)&g(\alpha)&g(\alpha)\\ +g(\alpha)&g(\alpha)&f(\alpha)&g(\alpha)\\ +g(\alpha)&g(\alpha)&g(\alpha)&f(\alpha) +\end{bmatrix} +\end{equation*} + +Taking the partial derivative of $\log |\QQ^{-1}|$ with respect to $\pmb{q^{*}}=\big[\begin{smallmatrix}f(\alpha,\beta)\\g(\alpha,\beta)\end{smallmatrix}\big]$, we arrive at the same equation as for the diagonal matrix: +\begin{equation}\label{eq:Q.eqvarcov2} +\begin{split} +&\partial\Psi/\partial\pmb{q^{*}} = +\frac{1}{2} \sum_{t=1}^T\DD^\top \vec(\SS_t) - \frac{1}{2}\sum_{t=1}^T(\DD^\top\DD)\pmb{q} +\end{split} +\end{equation} +where here $\DD^\top\DD$ is a $2 \times 2$ diagonal matrix with the number of times $f(\alpha,\beta)$ appears in element $(1,1)$ and the number of times $g(\alpha,\beta)$ appears in element $(2,2)$ of $\DD$; $s=2$ here since there are only 2 free parameters in $\QQ$. + +Setting to zero and solving for $\pmb{q^{*}}$ leads to the exact same update equation as for the diagonal $\QQ$, namely equation \ref{eq:Q.diag.update} in which $\ff_q = 0$ since there are no fixed values. + +\subsubsection{Special case: a block-diagonal matrices with replicated blocks} +\label{sec:Q.block.diagonal} +Because these operations extend directly to block-diagonal matrices, all results for individual matrix types can be extended to a block-diagonal matrix with those types: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{B}_1&0&0\\ +0&\mathbb{B}_2&0\\ +0&0&\mathbb{B}_3\\ +\end{bmatrix} +\end{equation*} +where $\mathbb{B}_i$ is a matrix from any of the allowed matrix types, such as unconstrained, diagonal (with fixed or shared elements), or equal variance-covariance. Blocks can also be shared: +\begin{equation*}\QQ= +\begin{bmatrix} +\mathbb{B}_1&0&0\\ +0&\mathbb{B}_2&0\\ +0&0&\mathbb{B}_2\\ +\end{bmatrix} +\end{equation*} +but the entire block must be identical $(\mathbb{B}_2 \equiv \mathbb{B}_3)$; one cannot simply share individual elements in different blocks. Either all the elements in two (or 3, or 4...) blocks are shared or none are shared. + +This is ok: +\begin{equation*} +\begin{bmatrix} +c&d&d&0&0&0\\ +d&c&d&0&0&0\\ +d&d&c&0&0&0\\ +0&0&0&c&d&d\\ +0&0&0&d&c&d\\ +0&0&0&d&d&c\\ +\end{bmatrix} +\end{equation*} +This is not ok: +\begin{equation*} +\begin{bmatrix} +c&d&d&0&0\\ +d&c&d&0&0\\ +d&d&c&0&0\\ +0&0&0&c&d\\ +0&0&0&d&c +\end{bmatrix} +\text{ nor } +\begin{bmatrix} +c&d&d&0&0&0\\ +d&c&d&0&0&0\\ +d&d&c&0&0&0\\ +0&0&0&c&e&e\\ +0&0&0&e&c&e\\ +0&0&0&e&e&c\\ +\end{bmatrix}\end{equation*} +The first is bad because the blocks are not identical; they need the same dimensions as well as the same values. The second is bad because again the blocks are not identical; all values must be the same. + +\subsubsection{Special case: a symmetric blocked matrix} +\label{sec:Q.symmetric blocked} +The same derivation translates immediately to blocked symmetric $\QQ$ matrices with the following form: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\\ +\end{bmatrix} +\end{equation*} +where the $\mathbb{E}$ are as above matrices with one value on the diagonal and another on the off-diagonals (no zeros!). The $\mathbb{C}$ matrices have only one free value or are all zero. Some $\mathbb{C}$ matrices can be zero while are others are non-zero, but a individual $\mathbb{C}$ matrix cannot have a combination of free values and zero values; they have to be one or the other. Also the whole matrix must stay block symmetric. Additionally, there can be shared $\mathbb{E}$ or $\mathbb{C}$ matrices but the whole matrix needs to stay block-symmetric. Here are the forms that $\mathbb{E}$ and $\mathbb{C}$ can take: +\begin{equation*} +\mathbb{E}_i= +\begin{bmatrix} +\alpha&\beta&\beta&\beta\\ +\beta&\alpha&\beta&\beta\\ +\beta&\beta&\alpha&\beta\\ +\beta&\beta&\beta&\alpha +\end{bmatrix} +\quad\quad +\mathbb{C}_i= +\begin{bmatrix} +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi\\ +\chi&\chi&\chi&\chi +\end{bmatrix} +\text{ or } +\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation*} +The following are block-symmetric: +\begin{equation*} +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\\ +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}&\mathbb{C}&\mathbb{C}\\ +\mathbb{C}&\mathbb{E}&\mathbb{C}\\ +\mathbb{C}&\mathbb{C}&\mathbb{E}\\ +\end{bmatrix} +\end{equation*} +\begin{equation*} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_1&\mathbb{E}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_{1,2}&\mathbb{C}_{1,2}&\mathbb{E}_2\\ +\end{bmatrix} +\end{equation*} +The following are NOT legal block-symmetric matrices: +\begin{equation*} +\begin{bmatrix} +\mathbb{E}_1&\mathbb{C}_{1,2}&0\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +0&\mathbb{C}_{2,3}&\mathbb{E}_3 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&0&\mathbb{C}_1\\ +0&\mathbb{E}_1&\mathbb{C}_2\\ +\mathbb{C}_1&\mathbb{C}_2&\mathbb{E}_2 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{E}_1&0&\mathbb{C}_{1,2}\\ +0&\mathbb{E}_1&\mathbb{C}_{1,2}\\ +\mathbb{C}_{1,2}&\mathbb{C}_{1,2}&\mathbb{E}_2\\ +\end{bmatrix} +\end{equation*} +\begin{equation*} +\text{ and } +\begin{bmatrix} +\mathbb{U}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3 +\end{bmatrix} +\text{ and } +\begin{bmatrix} +\mathbb{D}_1&\mathbb{C}_{1,2}&\mathbb{C}_{1,3}\\ +\mathbb{C}_{1,2}&\mathbb{E}_2&\mathbb{C}_{2,3}\\ +\mathbb{C}_{1,3}&\mathbb{C}_{2,3}&\mathbb{E}_3\end{bmatrix} +\end{equation*} +In the first row, the matrices have fixed values (zeros) and free values (covariances) on the same off-diagonal row and column. That is not allowed. If there is a zero on a row or column, all other terms on the off-diagonal row and column must be also zero. In the second row, the matrix is not block-symmetric since the upper corner is an unconstrained block ($\mathbb{U}_1$) in the left matrix and diagonal block ($\mathbb{D}_1$) in the right matrix instead of a equal variance-covariance matrix ($\mathbb{E}$). + +\subsubsection{The general case: a block-diagonal matrix with general blocks} +\label{sec:Q.general} +In it's most general form, $\QQ$ is allowed to have a block-diagonal form where the blocks, here called $\mathbb{G}$ are any of the previous allowed cases. No shared values across $\mathbb{G}$'s; shared values are allowed within $\mathbb{G}$'s. +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{G}_1&0&0\\ +0&\mathbb{G}_2&0\\ +0&0&\mathbb{G}_3\\ +\end{bmatrix} +\end{equation*} +The $\mathbb{G}$'s must be one of the special cases listed above: unconstrained, diagonal (with fixed or shared values), equal variance-covariance, block diagonal (with shared or unshared blocks), and block-symmetric (with shared or unshared blocks). Fixed blocks are allowed, but then the covariances with the free blocks must be zero: +\begin{equation*} +\QQ= +\begin{bmatrix} +\mathbb{F}&0&0&0\\ +0&\mathbb{G}_1&0&0\\ +0&0&\mathbb{G}_2&0\\ +0&0&0&\mathbb{G}_3 +\end{bmatrix} +\end{equation*} +Fixed blocks must have only fixed values (zero is a fixed value) but the fixed values can be different from each other. The free blocks must have only free values (zero is not a free value). + +\subsection{The general $\RR$ update equation} +The $\RR$ update equation for blocked symmetric matrices with optional independent fixed blocks is completely analogous to the $\QQ$ equation. Thus if $\RR$ has the form +\begin{equation*} +\RR= +\begin{bmatrix} +\mathbb{F}&0&0&0\\ +0&\mathbb{G}_1&0&0\\ +0&0&\mathbb{G}_2&0\\ +0&0&0&\mathbb{G}_3 +\end{bmatrix} +\end{equation*} +Again the $\mathbb{G}$'s must be one of the special cases listed above: unconstrained, diagonal (with fixed or shared values), equal variance-covariance, block diagonal (with shared or unshared blocks), and block-symmetric (with shared or unshared blocks). Fixed blocks are allowed, but then the covariances with the free blocks must be zero. Elements like $f_i+r_j$ and $r_i+r_j$ are not allowed in $\RR$. Only elements of the form $f_i$ and $r_i$ are allowed. If an element has a fixed component, it must be completely fixed. Each element in $\RR$ can have only one of the elements in $\rr$, but multiple elements in $\RR$ can have the same $\rr$ element. + +The update equation is +\begin{equation}\label{eq:R.general} +\begin{split} +&\rr_{j+1} = +\bigg(\sum_{t=1}^T\DD_{t,r}^\top \DD_{t,r}\bigg)^{-1} \sum_{t=1}^T \DD_{t,r}^\top\vec\bigg(\TT_{t,{j+1}} + \bigg)\\ +&\quad\quad\quad\quad\vec(\RR_t)_{j+1} = \ff_{t,r} + \DD_{t,r} \rr_{j+1} +\end{split} +\end{equation} +The $\TT_{t,j+1}$ used at time step $t$ in equation \ref{eq:R.general} is the term that appears in the summation in the unconstrained update equation with no missing values (equation \ref{eq:R.update.unconstrained}): +\begin{equation} +\begin{split} +\TT_{t,j+1}=\Xi_t\bigg( + \hatOt - \hatYXt\ZZ_t^\top - \ZZ_t\hatYXt^\top + - \hatyt\aa_t^\top - \aa_t\hatyt^\top + + \ZZ_t\hatPt\ZZ_t^\top + \ZZ_t\hatxt\aa_t^\top + \aa_t\hatxt^\top\ZZ_t^\top + + \aa_t\aa_t^\top \bigg)\Xi_t^\top +\end{split} +\end{equation} +where $\Xi_t = (\HH_t^\top\HH_t)^{-1}\HH_t^\top$. + + +\section{Computing the expectations in the update equations}\label{sec:compexpectations} +For the update equations, we need to compute the expectations of $\XX_t$ and $\YY_t$ and their products conditioned on 1) the observed data $\YY(1)=\yy(1)$ and 2) the parameters at time $t$, $\Theta_j$. This section shows how to compute these expectations. Throughout the section, I will normally leave off the conditional $\YY(1)=\yy(1),\Theta_j$ when specifying an expectation. Thus any $\E[ ]$ appearing without its conditional is conditioned on $\YY(1)=\yy(1),\Theta_j$. However if there are additional or different conditions those will be shown. Also all expectations are over the joint distribution of $XY$ unless explicitly specified otherwise. + +Before commencing, we need some notation for the observed and unobserved elements of the data. +The $n \times 1$ vector $\yy_t$ denotes the potential observations at time $t$. If some elements of $\yy_t$ are missing, that means some elements are equal to NA (or some other missing values marker): +\begin{equation} +\yy_t=\begin{bmatrix} +y_1\\ +NA\\ +y_3\\ +y_4\\ +NA\\ +y_6 +\end{bmatrix} +\end{equation} +We denote the non-missing observations as $\yy_t(1)$ and the missing observations as $\yy_t(2)$. Similar to $\yy_t$, $\YY_t$ denotes all the $\YY$ random variables at time $t$. The $\YY_t$'s with an observation are $\YY_t(1)$ and those without an observation are denoted $\YY_t(2)$. + +Let $\OMG_t^{(1)}$ be the matrix that extracts only $\YY_t(1)$ from $\YY_t$ and $\OMG_t(2)$ be the matrix that extracts only $\YY_t(2)$. For the example above, +\begin{equation} +\begin{split} +&\YY_t(1)=\OMG_t^{(1)} \YY_t,\quad \OMG_t^{(1)} = +\begin{bmatrix} +1&0&0&0&0&0\\ +0&0&1&0&0&0\\ +0&0&0&1&0&0\\ +0&0&0&0&0&1\\ +\end{bmatrix}\\ +&\YY_t(2)=\OMG_t^{(2)} \YY_t,\quad \OMG_t^{(2)} = +\begin{bmatrix} +0&1&0&0&0&0\\ +0&0&0&0&1&0 +\end{bmatrix} +\end{split} +\end{equation} + +We will define another set of matrices that zeros out the missing or non-missing values. Let $\IIm_t^{(1)}$ denote a diagonal matrix that zeros out the $\YY_t(2)$ in $\YY_t$ and $\IIm_t^{(2)}$ denote a matrix that zeros out the $\YY_t(1)$ in $\YY_t$. For the example above, +\begin{equation} +\begin{split} +\IIm_t^{(1)} &= (\OMG_t^{(1)})^\top\OMG_t^{(1)} = +\begin{bmatrix} +1&0&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&1&0&0&0\\ +0&0&0&1&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&0&1\\ +\end{bmatrix}\quad\text{and}\\ +\IIm_t^{(2)} &= (\OMG_t^{(2)})^\top\OMG_t^{(2)} = +\begin{bmatrix} +0&0&0&0&0&0\\ +0&1&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&0&0\\ +0&0&0&0&1&0\\ +0&0&0&0&0&0\\ +\end{bmatrix}. +\end{split} +\end{equation} + +\subsection{Expectations involving only $\XX_t$}\label{sec:kalman.smoother} +The Kalman smoother provides the expectations involving only $\XX_t$ conditioned on all the data from time 1 to $T$. The Kalman filter provides the expectations involving only $\XX_t$ conditioned on all the data from time 1 to $t-1$ and from time 1 to $t$. For the EM algorithm, we only need the smoother output and the expected values conditioned on the data from time 1 to $T$ and these are denoted with special symbol of a tilde over a variable. + +To present the algorithm for the Kalman smoother and filter, the expectations conditioned on time 1 to $t$ are needed. The notation for this general case will be $\xx_t^t$ to denote $\E[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]$ where $\yy(1)_1^t$ means the observed data (the $(1)$ part) from time 1 to $t$ (the superscript). This is fairly common notation for the conditional expectations in a Kalman filter and smoother and it is important to note that the superscript is not a power notation but the upper time extent. The the expectations used in the previous sections on the EM algorithm are the following: + +\begin{subequations}\label{eq:kfsoutput} +\begin{align} +&\hatxt \equiv \xx_t^T = \E[\XX_t|\YY(1)_1^T=\yy(1)_1^T,\Theta]\label{eq:xt}\\ +&\widetilde{\VV}_t \equiv \VV_t^T = \var[\XX_t|\YY(1)_1^T=\yy(1)_1^T,\Theta]\\ +&\widetilde{\VV}_{t,t-1} \equiv \VV_{t,t-1}^T = \cov[\XX_t,\XX_{t-1}|\YY(1)_1^T=\yy(1)_1^T,\Theta]\\ +&\text{From $\hatxt$, $\widetilde{\VV}_t$, and $\widetilde{\VV}_{t,t-1}$, we compute}\nonumber\\ +&\hatPt \equiv \PP_t^T =\E[\XX_t\XX_t^\top|\YY(1)_1^T=\yy(1)_1^T,\Theta]= \widetilde{\VV}_t + \hatxt\hatxt^\top\label{eq:Pt}\\ +&\hatPttm \equiv \PP_{t,t-1}^T =\E[\XX_{t}\XX_{t-1}^\top|\YY(1)_1^T=\yy(1)_1^T,\Theta]=\widetilde{\VV}_{t,t-1} +\hatxt\hatxtm^\top\label{eq:Ptt1} +\end{align} +\end{subequations} +The $\hatPt$ and $\hatPttm$ equations arise from the computational formula for variance (equation \ref{eq:comp.formula.variance}). When comparing the Kalman filter and smoother algorithms here to Shumway and Stoffer, keep in mind the difference in notation: $P_t^n$ in Shumway and Stoffer is $\VV_t^T$ here not $\PP_t^T$. + +In the presentation of the EM algorithm, $\YY(1)_1^T=\yy(1)_1^T,\Theta$ was dropped from the expectations to remove clutter; thus $E[\dots]$ always denoted the conditional expectation $\E[\dots|\YY(1)_1^T=\yy(1)_1^T,\Theta]$. To present the smoother algorithm, I present the other conditional expectations. +\begin{subequations}\label{eq:kffilteroutput} +\begin{align} +&\xx_t^{t-1} = \E[\XX_t|\YY(1)_1^{t-1}=\yy(1)_1^{t-1},\Theta]\\ +&\xx_t^t = \E[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]\\ +&\VV_t^{t-1} = \var[\XX_t|\YY(1)_1^{t-1}=\yy(1)_1^{t-1},\Theta]\\ +&\VV_t^t = \var[\XX_t|\YY(1)_1^t=\yy(1)_1^t,\Theta]\\ +\end{align} +\end{subequations} + +The first part of the Kalman smoother algorithm is the Kalman filter which gives the expectation at time $t$ conditioned on the data up to time $t$. The following the filter as shown in \citep[section 6.2, p. 331]{ShumwayStoffer2006}, although the notation is a little different. The recursion starts at time $t=1$ and repeats until $t=T$. +\begin{subequations}\label{eq:kffilter} +\begin{align} +&\xx_t^{t-1}=\BB_t\xx_{t-1}^{t-1}+\uu_t\label{eq:xtt1}\\ +&\VV_t^{t-1}=\BB_t\VV_{t-1}^{t-1}\BB_t^\top + \GG_t\QQ_t\GG_t^\top\label{eq:Vtt1}\\ +&\xx_t^t=\xx_t^{t-1}+\KK_t(\yy_t-\ZZ_t\xx_t^{t-1}-\aa_t)\label{eq:xtt}\\ +&\VV_t^t=(\II_m-\KK_t\ZZ_t)\VV_t^{t-1}\label{eq:Vtt}\\ +&\KK_t=\VV_t^{t-1}\ZZ_t^\top(\ZZ_t\VV_t^{t-1}\ZZ_t^\top+\HH_t\RR_t\HH_t^\top)^{-1}\label{eq:Kt} +\end{align} +\end{subequations} +If the initial value is defined at $t=0$, then the filter starts at $t=1$ with the first two equations with $\xx_{0}^{0} \equiv \xixi$ and $\VV_{0}^{}\equiv\LAM$. If the initial value is defined at $t=1$, then the filter starts at $t=1$ with the third and fourth equations with $\xx_{1}^{0}\equiv\xixi$ and $\VV_{1}^{0}\equiv\LAM$. + + +The Kalman smoother and lag-1 covariance smoother compute the expectations conditioned on all the data, 1 to $T$: +\begin{subequations}\label{eq:kfsmoother} +\begin{align} +&\xx_{t-1}^T=\xx_{t-1}^{t-1}+\JJ_{t-1}(\xx_t^T-\xx_t^{t-1})\label{eq:xt1T}\\ +&\VV_{t-1}^T=\VV_{t-1}^{t-1}+\JJ_{t-1}(\VV_t^T-\VV_t^{t-1})\JJ_{t-1}^\top\label{eq:Vt1T}\\ +&\JJ_{t-1}=\VV_{t-1}^{t-1}\BB_t^\top(\VV_t^{t-1})^{-1}\label{eq:Jt}\\ +\\ +&\VV_{T,T-1}^T=(\II-\KK_T\ZZ_T)\BB_T\VV_{T-1}^{T-1}\label{eq:VTT1T}\\ +&\VV_{t-1,t-2}^T=\VV_{t-1}^{t-1}\JJ_{t-2}^\top + \JJ_{t-1}((\VV_{t,t-1}^T-\BB_t\VV_{t-1}^{t-1}))\JJ_{t-2}^\top\label{eq:Vtt1T} +\end{align} +\end{subequations} + +The classic Kalman smoother is an algorithm to compute these expectations conditioned on no missing values in $\yy$. However, the algorithm can be easily modified to give the expected values of $\XX$ conditioned on the incomplete data, $\YY(1)=\yy(1)$ \citep[section 6.4, eqn 6.78, p. 348]{ShumwayStoffer2006}. +In this case, the usual filter and smoother equations are used with the following modifications to the parameters and data used in the equations. If the $i$-th element of $\yy_t$ is missing, zero out the $i$-th rows in $\yy_t$, $\aa$ and $\ZZ$. Thus if the 2nd and 5th elements of $\yy_t$ are missing, +\begin{equation}\label{eq:yaZ.miss} +\yy_t^*=\begin{bmatrix} +y_1\\ +0\\ +y_3\\ +y_4\\ +0\\ +y_6\\ +\end{bmatrix}, \quad +\aa_t^*=\begin{bmatrix} +a_1\\ +0\\ +a_3\\ +a_4\\ +0\\ +a_6\\ +\end{bmatrix}, \quad +\ZZ_t^*=\begin{bmatrix} +z_{1,1}&z_{1,2}&...\\ +0&0&...\\ +z_{3,1}&z_{3,2}&...\\ +z_{4,1}&z_{4,2}&...\\ +0&0&...\\ +z_{6,1}&z_{6,2}&...\\ +\end{bmatrix} +\end{equation} + +The $\RR_t$ parameter used in the filter equations is also modified. We need to zero out the covariances between the non-missing, $\yy_t(1)$, and missing, $\yy_t(2)$, data. For the example above, if +\begin{equation} +\RR_t = \Rb_t\RR\Rb_t^\top = \begin{bmatrix} +r_{1,1}&r_{1,2}&r_{1,3}&r_{1,4}&r_{1,5}&r_{1,6}\\ +r_{2,1}&r_{2,2}&r_{2,3}&r_{2,4}&r_{2,5}&r_{2,6}\\ +r_{3,1}&r_{3,2}&r_{3,3}&r_{3,4}&r_{3,5}&r_{3,6}\\ +r_{4,1}&r_{4,2}&r_{4,3}&r_{4,4}&r_{4,5}&r_{4,6}\\ +r_{5,1}&r_{5,2}&r_{5,3}&r_{5,4}&r_{5,5}&r_{5,6}\\ +r_{6,1}&r_{6,2}&r_{6,3}&r_{6,4}&r_{6,5}&r_{6,6}\\ +\end{bmatrix} +\end{equation} +then the $\RR_t$ we use at time $t$, will have zero covariances between the non-missing elements 1,3,4,6 and the missing elements 2,5: +\begin{equation} +\RR_t^* + = \begin{bmatrix} +r_{1,1}&0&r_{1,3}&r_{1,4}&0&r_{1,6}\\ +0&r_{2,2}&0&0&r_{2,5}&0\\ +r_{3,1}&0&r_{3,3}&r_{3,4}&0&r_{3,6}\\ +r_{4,1}&0&r_{4,3}&r_{4,4}&0&r_{4,6}\\ +0&r_{5,2}&0&0&r_{5,5}&0\\ +r_{6,1}&0&r_{6,3}&r_{6,4}&0&r_{6,6}\\ +\end{bmatrix} +\end{equation} + +Thus, the data and parameters used in the filter and smoother equations are +\begin{equation} +\begin{split} +\yy_t^*&=\IIm_t^{(1)}\yy_t\\ +\aa_t^*&=\IIm_t^{(1)}\aa_t\\ +\ZZ_t^*&=\IIm_t^{(1)}\ZZ_t\\ +\RR_t^* &= \IIm_t^{(1)}\RR_t\IIm_t^{(1)} + \IIm_t^{(2)}\RR_t\II_t^{(2)} +\end{split} +\end{equation} +$\aa_t^*$, $\ZZ_t^*$ and $\RR_t^*$ only are used in the Kalman filter and smoother. They are not used in the EM update equations. However when coding the algorithm, it is convenient to replace the NAs (or whatever the missing values placeholder is) in $\yy_t$ with zero so that there is not a problem with NAs appearing in the computations. + +\subsection{Expectations involving $\YY_t$}\label{sec:exp.Y} +First, replace the missing values in $\yy_t$ with zeros\footnote{The only reason is so that in your computer code, if you use NA or NaN as the missing value marker, NA-NA=0 and 0*NA=0 rather than NA.} and then the expectations are given by the following equations. The derivations for these equations are given in the subsections to follow. +\begin{subequations}\label{eq:Yt.exp} +\begin{align} +\hatyt &= \E[\YY_t]=\yy_t-\IR_t(\yy_t-\ZZ_t\hatxt-\aa_t)\label{eq:hatyt}\\ +\hatOt &= \E[\YY_t\YY_t^\top]=\IIm_t^{(2)}(\IR_t\HH_t\RR_t\HH_t^\top + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} + \hatyt\hatyt^\top \label{eq:hatOt}\\ +\hatYXt&= \E[\YY_t\XX_t^\top] = \IR_t\ZZ_t\hatVt + \hatyt\hatxt^\top \label{eq:hatyxttm}\\ +\hatYXttm&= \E[\YY_t\XX_{t-1}^\top] = \IR_t\ZZ_t\hatVttm + \hatyt\hatxtm^\top \label{eq:hatyxt}\\ +\text{where }\IR_t &= \II-\HH_t\RR_t\HH_t^\top(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\HH_t\RR_t\HH_t^\top(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}\label{eq.IRt}\\ +\text{and }\IIm_t^{(2)}&=(\OMG_t^{(2)})^\top\OMG_t^{(2)} +\label{eq:IRt} +\end{align} +\end{subequations} +If $\yy_t$ is all missing, $\OMG_t^{(1)}$ is a $0 \times n$ matrix, and we define $(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\RR(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}$ to be a $n \times n$ matrix of zeros. If $\RR_t$ is diagonal, then $\RR_t(\OMG_t^{(1)})^\top(\OMG_t^{(1)}\RR_t(\OMG_t^{(1)})^\top)^{-1}\OMG_t^{(1)}=\IIm_t^{(1)}$ and $\IR_t=\IIm_t^{(2)}$. This will mean that in $\hatyt$ the $\yy_t(2)$ are given by $\ZZ_t\hatxt+\aa_t$, as expected when $\yy_t(1)$ and $\yy_t(2)$ are independent. + +If there are zeros on the diagonal of $\RR_t$ (section \ref{sec:degenerate}), the definition of $\IR_t$ is changed slightly from that shown in equation \ref{eq:Yt.exp}. Let $\mho_t^{(r)}$ be the matrix that extracts the elements of $\yy_t$ where $\yy_t(i)$ is not missing AND $\HH_t\RR_t(i,i)\HH_t^\top$ is not zero. Then +\begin{equation} +\IR_t = \II-\HH_t\RR_t\HH_t^\top(\mho_t^{(r)})^\top +(\mho_t^{(r)}\HH_t\RR_t\HH_t^\top(\mho_t^{(r)})^\top)^{-1}\mho_t^{(r)} +\label{eq:IRt.degen} +\end{equation} + +\subsection{Derivation of the expected value of $\YY_t$} +In the MARSS equation, the observation errors are denoted $\HH_t\vv_t$. $\vv_t$ is a specific realization from a random variable $\VV_t$ that is distributed multivariate normal with mean 0 and variance $\RR_t$. $\VV_t$ is not to be confused with $\widetilde{\VV}_t$ in equation \ref{eq:kfsoutput}, which is unrelated\footnote{I apologize for the confusing notation, but $\widetilde{\VV}_t$ and $\vv_t$ are somewhat standard in the MARSS literature and it is standard to use a capital letter to refer to a random variable. Thus $\VV_t$ would be the standard way to refer to the random variable associated with $\vv_t$.} to $\VV_t$. If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t|\YY(1)=\yy(1)] = \E[\YY_t|\YY_t=\yy_t] = \yy_t\\ +\end{split} +\end{equation} +If there are no observed values, then +\begin{equation} +\begin{split} +\E[\YY_t|\YY(1)=\yy(1)]=\E[\YY_t] = \E[\ZZ_t\XX_t+\aa_t+\VV_t] = \ZZ_t\hatxt+\aa_t +\end{split} +\end{equation} +If only some of the $\YY_t$ are observed, then we use the conditional probability for a multivariate normal distribution (here shown for a bivariate case): +\begin{equation}\label{eq:cond.multi.normal} +\text{If, }\begin{bmatrix} +Y_1\\ +Y_2\end{bmatrix} +\sim +\MVN\biggl( \begin{bmatrix} +\mu_1\\ +\mu_2 +\end{bmatrix}, \begin{bmatrix} +\Sigma_{11}&\Sigma_{12}\\ +\Sigma_{21}&\Sigma_{22}\end{bmatrix}\biggr) +\end{equation} +Then, +\begin{equation} +\begin{split} +(Y_1|Y_1=y_1) &=y_1,\quad\text{and}\\ +(Y_2|Y_1=y_1) &\sim \MVN(\bar{\mu},\bar{\Sigma}),\quad\text{where}\\ +\bar{\mu}&= \mu_2+\Sigma_{21}\Sigma_{11}^{-1}(y_1-\mu_1)\\ +\bar{\Sigma} &= \Sigma_{22}-\Sigma_{21}\Sigma_{11}^{-1}\Sigma_{12} +\end{split} +\end{equation} + +From this property, we can write down the distribution of $\YY_t$ conditioned on $\YY_t(1)=\yy_t(1)$ and $\XX_t=\xx_t$: +\begin{equation} +\begin{split} +\begin{bmatrix} +\YY_t(1)|\XX_t=\xx_t\\ +\YY_t(2)|\XX_t=\xx_t +\end{bmatrix} +&\sim \\ +&\MVN\biggl( \begin{bmatrix} +\OMG_t^{(1)}(\ZZ_t\xx_t+\aa_t)\\ +\OMG_t^{(2)}(\ZZ_t\xx_t+\aa_t) +\end{bmatrix}, \begin{bmatrix} +(\HH_t\RR_t\HH_t^\top)_{11}&(\HH_t\RR_t\HH_t^\top)_{12}\\ +(\HH_t\RR_t\HH_t^\top)_{21}&(\HH_t\RR_t\HH_t^\top)_{22} +\end{bmatrix}\biggr) +\end{split} +\end{equation} +Thus, +\begin{equation}\label{eq:varY} +\begin{split} +(\YY_t(1)&|\YY_t(1)=\yy_t(1),\XX_t=\xx_t) = \OMG_t^{(1)}\yy_t\quad\text{and}\\ +(\YY_t(2)&|\YY_t(1)=\yy_t(1),\XX_t=\xx_t) \sim \MVN(\ddot{\mu},\ddot{\Sigma})\quad\text{where}\\ +\ddot{\mu}&= \OMG_t^{(2)}(\ZZ_t\xx_t+\aa_t)+\ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}(\yy_t-\ZZ_t\xx_t-\aa_t)\\ +\ddot{\Sigma}&= \ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12} \\ +\ddot{\RR}_t&= \HH_t\RR_t\HH_t^\top +\end{split} +\end{equation} + +Note that since we are conditioning on $\XX_t=\xx_t$, we can replace $\YY$ (all data from time 1 to $T$) by $\YY_t$ (data at time $t$) in the conditional: +$$\E[\YY_t|\YY(1)=\yy(1),\XX_t=\xx_t]=\E[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t].$$ +From this and the distributions in equation \ref{eq:varY}, we can write down $\hatyt=\E[\YY_t|\YY(1)=\yy(1),\Theta_j]$: +\begin{equation} +\begin{split} +\hatyt&=\E_{XY}[\YY_t|\YY(1)=\yy(1)]\\ +&=\int_{\xx_t}\int_{\yy_t}\yy_t f(\yy_t|\yy_t(1),\xx_t)d\yy_t f(\xx_t)d\xx_t \\ +&=\E_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]]\\ +&=\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]\\ +&=\yy_t-\IR_t(\yy_t-\ZZ_t\hatxt-\aa_t)\\ +\text{where }\IR_t &= \II-\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)} +\end{split} +\end{equation} +$(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}$ is a $n \times n$ matrix with 0s in the non-(11) positions. If the $k$-th element of $\yy_t$ is observed, then $k$-th row and column of $\IR_t$ will be zero. +Thus if there are no missing values at time $t$, $\IR_t=\II-\II=0$. If there are no observed values at time $t$, $\IR_t$ will reduce to $\II$. + +\subsection{Derivation of the expected value of $\YY_t\YY_t^\top$} +The following outlines a\footnote{The following derivations are painfully ugly. There are surely more elegant ways to do this; at least, there must be more elegant notations.} derivation. If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t &\YY_t^\top|\YY(1)=\yy(1)] = \E[\YY_t \YY_t^\top|\YY_t=\yy_t] = \yy_t\yy_t^\top. +\end{split} +\end{equation} +If there are no observed values at time $t$, then +\begin{equation} +\begin{split} +\E[\YY_t &\YY_t^\top]\\ +&=\var[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]+\E[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]\E[\ZZ_t\XX_t+\aa_t+\HH_t\VV_t]^\top\\ +&=\var[\VV_t]+\var[\ZZ_t\XX_t]+(\E[\ZZ_t\XX_t+\aa_t]+\E[\HH_t\VV_t])(\E[\ZZ_t\XX_t+\aa_t]+\E[\HH_t\VV_t])^\top\\ +&=\ddot{\RR}_t+\ZZ_t\hatVt\ZZ_t^\top + (\ZZ_t\hatxt+\aa_t)(\ZZ_t\hatxt+\aa_t)^\top +\end{split} +\end{equation} + +When only some of the $\YY_t$ are observed, we use again the conditional probability of a multivariate normal (equation \ref{eq:cond.multi.normal}). From this property, we know that +\begin{equation}\label{eq:var.Y.cond.x} +\begin{split} +&\var_{Y|x}[\YY_t(2)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12},\\ +&\var_{Y|x}[\YY_t(1)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=0\\ +\text{and }&\cov_{Y|x}[\YY_t(1),\YY_t(2)|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]=0\\ +\\ +\text{Thus }&\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]\\ +&=(\OMG_t^{(2)})^\top(\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12})\OMG_t^{(2)}\\ +&=(\OMG_t^{(2)})^\top(\OMG_t^{(2)}\ddot{\RR}_t(\OMG_t^{(2)})^\top - \OMG_t^{(2)}\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}\ddot{\RR}_t(\OMG_t^{(2)})^\top)\OMG_t^{(2)}\\ +&=\IIm_t^{(2)}(\ddot{\RR}_t-\ddot{\RR}_t(\OMG_t^{(1)})^\top(\ddot{\RR}_{t,11})^{-1}\OMG_t^{(1)}\ddot{\RR}_t)\IIm_t^{(2)}\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} +\end{split} +\end{equation} +The $\IIm_t^{(2)}$ bracketing both sides is zero-ing out the rows and columns corresponding to the $\yy_t(1)$ values. + +Now we can compute the $\E_{XY}[\YY_t\YY_t^\top|\YY(1)=\yy(1)]$. The subscripts are added to the $\E$ to emphasize that we are breaking the multivariate expectation into an inner and outer expectation. +\begin{equation} +\begin{split} +\hatOt&=\E_{XY}[\YY_t\YY_t^\top|\YY(1)=\yy(1)]=\E_X[\E_{Y|x}[\YY_t\YY_t^\top|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]]\\ +&=\E_X\bigl[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t] \\ +&\quad + \E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t] +\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t=\xx_t]^\top\bigr]\\ +&=\E_X[\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)}] +\E_X[(\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t))(\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t))^\top]\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} + \var_X\bigl[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)\bigr]\\ &\quad +\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]\E_X[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)]^\top\\ +&=\IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} + \IIm_t^{(2)}\IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top\IIm_t^{(2)} + \hatyt\hatyt^\top \\ +\end{split} +\end{equation} +Thus, +\begin{equation} +\hatOt=\IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} + \hatyt\hatyt^\top \\ +\end{equation} +and +\begin{equation}\label{eq:cond.var.Y} +\var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] = \IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} +\end{equation} + +The variance can be decomposed into two parts via the law of total variance: +\begin{equation}\label{eq:law.total.var.Y} +\var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] = \E_X[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] + +\var_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] +\end{equation} +Using equations \ref{eq:law.total.var.Y}, \ref{eq:var.Y.cond.x}, and \ref{eq:cond.var.Y}, we can solve for the variance (over $\xx_t$) of the expected value of $\YY_t|\YY_t(1)=\yy_t(1)$ conditioned on $\XX_t=\xx_t$: +\begin{equation} +\begin{split} +\var_X[\E_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] & \\ +&= \var_{XY}[\YY_t|\YY_t(1)=\yy_t(1)] - \E_X[\var_{Y|x}[\YY_t|\YY_t(1)=\yy_t(1),\XX_t]] \\ +&= \IIm_t^{(2)}(\IR_t\ddot{\RR}_t + \IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top)\IIm_t^{(2)} - \IIm_t^{(2)}\IR_t\ddot{\RR}_t\IIm_t^{(2)} \\ +&= \IIm_t^{(2)}\IR_t\ZZ_t\hatVt\ZZ_t^\top\IR_t^\top\IIm_t^{(2)} +\end{split} +\end{equation} +Though this variance is not used in the EM algoritm, it gives us the confidence intervals for the expected value of missing data while the variance of $\YY_t|\YY_t(1)=\yy_t(1)$ gives us the prediction intervals for missing data. + +\subsection{Derivation of the expected value of $\YY_t\XX_t^\top$} +If there are no missing values, then we condition on $\YY_t=\yy_t$ and +\begin{equation} +\begin{split} +\E[\YY_t \XX_t^\top|\YY(1)=\yy(1)] = \yy_t\E[\XX_t^\top]=\yy_t\hatxt^\top +\end{split} +\end{equation} +If there are no observed values at time $t$, then +\begin{equation} +\begin{split} +\E[\YY_t &\XX_t^\top|\YY(1)=\yy(1)]\\ +&=\E[(\ZZ_t\XX_t+\aa_t+\VV_t)\XX_t^\top]\\ +&=\E[\ZZ_t\XX_t\XX_t^\top+\aa_t\XX_t^\top+\VV_t\XX_t^\top]\\ +&=\ZZ_t\hatPt+\aa_t\hatxt^\top+\cov[\VV_t,\XX_t]+\E[\VV_t]\E[\XX_t]^\top\\ +&=\ZZ_t\hatPt+\aa_t\hatxt^\top +\end{split} +\end{equation} +Note that $\VV_t$ and $\XX_t$ are independent (equation \ref{eq:MARSS}). $\E[\VV_t]=0$ and $\cov[\VV_t,\XX_t]=0$. + +Now we can compute the $\E_{XY}[\YY_t\XX_t^\top|\YY_(1)=\yy(1)]$. +\begin{equation} +\begin{split} +\hatYXt&=\E_{XY}[\YY_t\XX_t^\top|\YY(1)=\yy(1)]\\ +&=\cov[\YY_t,\XX_t|\YY_t(1)=\yy_t(1)]+\E_{XY}[\YY_t|\YY(1)=\yy(1)]\E_{XY}[\XX_t^\top|\YY(1)=\yy(1)]^\top\\ +&=\cov[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)+\VV^*_t,\XX_t]+\hatyt\hatxt^\top \\ +&=\cov[\yy_t,\XX_t]-\cov[\IR_t\yy_t,\XX_t]+\cov[\IR_t\ZZ_t\XX_t,\XX_t] +\cov[\IR_t\aa_t,\XX_t]\\ +&\quad + \cov[\VV^*_t,\XX_t]+\hatyt\hatxt^\top \\ +&=0 - 0 + \IR_t\ZZ_t\hatVt + 0 + 0 + \hatyt\hatxt^\top \\ +&= \IR_t\ZZ_t\hatVt + \hatyt\hatxt^\top +\end{split} +\end{equation} +This uses the computational formula for covariance: $\E[\YY\XX^\top]=\cov[\YY,\XX]+\E[\YY]\E[\XX]^\top$. $\VV^*_t$ is a random variable with mean 0 and variance $\ddot{\RR}_{t,22} - \ddot{\RR}_{t,21}(\ddot{\RR}_{t,11})^{-1}\ddot{\RR}_{t,12}$ from equation \ref{eq:varY}. $\VV^*_t$ and $\XX_t$ are independent of each other, thus $\cov[\VV^*_t,\XX_t^\top]=0$. + +\subsection{Derivation of the expected value of $\YY_t\XX_{t-1}^\top$} +The derivation of $\E[\YY_t\XX_{t-1}^\top]$ is similar to the derivation of $\E[\YY_t\XX_{t-1}^\top]$: +\begin{equation} +\begin{split} +\hatYXt&=\E_{XY}[\YY_t\XX_{t-1}^\top|\YY(1)=\yy(1)]\\ +&=\cov[\YY_t,\XX_{t-1}|\YY_t(1)=\yy_t(1)] + \E_{XY}[\YY_t|\YY(1)=\yy(1)]\E_{XY}[\XX_{t-1}^\top|\YY(1)=\yy(1)]^\top\\ +&=\cov[\yy_t-\IR_t(\yy_t-\ZZ_t\XX_t-\aa_t)+\VV^*_t,\XX_{t-1}]+\hatyt\hatxtm^\top \\ +&=\cov[\yy_t,\XX_{t-1}]-\cov[\IR_t\yy_t,\XX_{t-1}]+\cov[\IR_t\ZZ_t\XX_t,\XX_{t-1}] \\ +&\quad +\cov[\IR_t\aa_t,\XX_{t-1}] + \cov[\VV^*_t,\XX_{t-1}]+\hatyt\hatxtm^\top \\ +&=0 - 0 + \IR_t\ZZ_t\hatVttm + 0 + 0 + \hatyt\hatxtm^\top \\ +&= \IR_t\ZZ_t\hatVttm + \hatyt\hatxtm^\top +\end{split} +\end{equation} + +\section{Degenerate variance models}\label{sec:degenerate} +It is possible that the model has deterministic and stochastic elements; mathematically this means that either $\GG_t$, $\HH_t$ or $\FF$ have all zero rows, and this means that some of the observation or state processes are deterministic\footnote{Deterministic means that given the parameters, the states or observation processes have known values and are not random variables.} Such models often arise when a MAR-p is put into MARSS-1 form. Assuming the model is solvable (one solution and not over-determined), we can modify the Kalman smoother and EM algorithm to handle models with deterministic elements. + +The motivation behind the degenerate variance modification is that we want to use one set of EM update equations for all models in the MARSS class---regardless of whether they are partially or fully degenerate\footnote{Degenerate means zeros on the diagonal of the variance-covariance matrix, which appears as a zero row in $\GG_t$, $\HH_t$ or $\FF$.}. The difficulties arise in getting the $\uu$ and $\xixi$ update equations. If we were to fix these or make $\xixi$ stochastic (a fixed mean and fixed variance), most of the trouble in this section could be avoided. However, fixing $\xixi$ or making it stochastic is putting a prior on it and placing a prior on the variance-covariance structure of $\xixi$ that conflicts logically with the model is often both unavoidable (since the correct variance-covariance structure depends on the parameters you are trying to estimate) and disastrous to one's estimation although the problem is often difficult to detect especially with long time series. Many papers have commented on this subtle problem. So, we want to be able to estimate $\xixi$ so we do not have to specify $\LAM$ (because we remove it from the model altogether). Note that in a univariate $\xx$ model (one state), $\LAM$ is just a variance so we do not run into this trouble. The problems arise when $\xx$ is multivariate (>1 state) and then we have to deal with the variance-covariance structure of the initial states. + +\subsection{Rewriting the state and observation models for degenerate variance systems} +Let's start with an example where $y_{2,t}$ (2nd $y$) has no added observation error. +\begin{equation} +\RR_t=\begin{bmatrix} +1&0.2\\ +0.2&1 +\end{bmatrix}\\ +\text{ and } +\HH_t=\begin{bmatrix} +1&0\\ +0&0\\ +0&1 +\end{bmatrix} +\end{equation} +Let $\OMG_{t,r}^+$ be a $p \times n$ matrix that extracts the $p$ non-zero rows from $\HH_t$. The diagonal matrix $(\OMG_{t,r}^+)^\top\OMG_{t,r}^+ \equiv \II_{t,r}^+$ is a diagonal matrix that can zero out the $\HH_t$ zero rows in any $n$ row matrix. + +\begin{equation} +\begin{split} +\OMG_{t,r}^+ &= +\begin{bmatrix} +1&0&0\\ +0&0&1 +\end{bmatrix}\quad\quad +\II_{t,r}^+ = (\OMG_{t,r}^+)^\top\OMG_{t,r}^+ = +\begin{bmatrix} +1&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\\ +\yy_t^+&=\OMG_{t,r}^+ \yy_t = +\begin{bmatrix} +y_1\\ +y_3 +\end{bmatrix}_t\quad\quad +\yy_t^+=\II_{t,r}^+ \yy_t = \begin{bmatrix} +y_1\\ +0\\ +y_3 +\end{bmatrix}_t +\end{split} +\end{equation} + +Let $\OMG_{t,r}^{(0)}$ be a $(n-p) \times n$ matrix that extracts the $n-p$ zero rows from $\HH_t$. For the example above, +\begin{equation} +\begin{split} +\OMG_{t,r}^{(0)} &= +\begin{bmatrix} +0&1&0\\ +\end{bmatrix}\quad\quad +\II_{t,r}^{(0)} = (\OMG_{t,r}^{(0)})^\top\OMG_{t,r}^{(0)} = +\begin{bmatrix} +0&0&0\\ +0&1&0\\ +0&0&0 +\end{bmatrix} +\\ +\yy_t^{(0)}&=\OMG_{t,r}^{(0)} \yy_t = \begin{bmatrix} +y_3 +\end{bmatrix}_t\quad\quad +\yy_t^{(0)}=\II_{t,r}^{(0)} \yy_t = \begin{bmatrix} +0\\ +y_2\\ +0 +\end{bmatrix}_t +\end{split} +\end{equation} +Similarly, $\OMG_{t,q}^+$ extracts the states associated with the non-zero rows in $\GG_t$ and $\OMG_{t,q}^{(0)}$ extracts the zero rows. $\II_{t,q}^+$ and $\II_{t,q}^{(0)}$ are defined similarly. + +Using these definitions, we can rewrite the state process part of the MARSS model by separating out the deterministic parts. $\xx_t^{(0)}$ is the rows of $\xx_t$ that are associated with all-zero rows of $\GG_t$, that means there is no $w_t$ in the $x_t$ equation for those rows\footnote{$x_{t,i}=\BB_{t,i}\xx_{t-1} + \uu_{t,i}$ where the $i$ subscript means $i$-th row.} +\begin{equation}\label{eq:degen.model.x1} +\begin{split} +\xx_t^{(0)}&=\OMG_{t,q}^{(0)}\xx_t=\OMG_{t,q}^{(0)}(\BB_t\xx_{t-1} + \uu_t)\\ +\xx_t^+&=\OMG_{t,q}^+\xx_t=\OMG_{t,q}^+(\BB_t\xx_{t-1} + \uu_t + \GG_t\ww_t)\\ +\ww_t^+ &\sim \MVN(0,\QQ_t) +\end{split} +\end{equation} +Similarly, we can rewrite the observation process part of the MARSS model by separating out the parts with no observation error: +\begin{equation}\label{eq:degen.model.y1} +\begin{split} +\yy_t^{(0)}&=\OMG_{t,r}^{(0)}\yy_t=\OMG_{t,r}^{(0)}(\ZZ_t\xx_t + \aa_t) \\ +&=\OMG_{t,r}^{(0)}(\ZZ_t\II_{t,q}^+\xx_t + \ZZ_t\II_{t,q}^{(0)}\xx_t + \aa_t)\\ +\yy_t^+&=\OMG_{t,r}^+\yy_t=\OMG_{t,r}^+(\ZZ_t\xx_t + \aa_t + \HH_t\vv_t)\\ +&=\OMG_{t,r}^+(\ZZ_t\II_{t,q}^+\xx_t + \ZZ_t\II_{t,q}^{(0)}\xx_t + \aa_t+\HH_t\vv_t)\\ +\vv_t^+ &\sim \MVN(0,\RR_t) +\end{split} +\end{equation} + +In order for this to be solvable using an EM algorithm with the Kalman filter, we require that no estimated $\BB$ or $\uu$ elements appear in the equation for $\yy_t^{(0)}$ (via $x_t$ in that equation). Since the $\yy_t^{(0)}$ do not appear in the likelihood function (since $\HH_t^{(0)}=0$), $\yy_t^{(0)}$ would not affect the estimate for the parameters appearing in the $\yy_t^{(0)}$ equation. This translates to the following constraints, $(1_{1 \times m} \otimes \OMG_{t,r}^{(0)}\ZZ_t\II_{t,q}^{(0)})\DD_{t,b}$ is all zeros and $\OMG_{t,r}^{(0)}\ZZ_t\II_{t,q}^{(0)}\DD_u$ is all zeros. +Also notice that $\OMG_{t,r}^{(0)}\ZZ_t$ and $\OMG_{t,r}^{(0)}\aa_t$ appear in the $\yy^{(0)}$ equation and not in the $\yy^+$ equation. This means that $\OMG_{t,r}^{(0)}\ZZ_t$ and $\OMG_{t,r}^{(0)}\aa_t$ must be only fixed terms. + +In summary, the degenerate model can be reduced to the following (with $\xx_0$ not specified yet). +\begin{equation}\label{eq:degen.model2} +\begin{split} +\xx_t^{(0)}&=\BB_t^{(0)}\xx_{t-1} + \uu_t^{(0)}\\ +\xx_t^+&=\BB_t^+\xx_{t-1} + \uu_t^+ + \GG_t^+\ww_t\\ +\ww_t &\sim \MVN(0,\QQ_t) +\\ +\yy_t^{(0)}&=\ZZ^{(0)}\II_q^+\xx_t + \ZZ^{(0)}\II_q^{(0)}\xx_t + \aa^{(0)}_t\\ +\yy_t^+&=\ZZ_t^+\xx_t + \aa_t^+ \HH_t^+\vv_t\\ +&=\ZZ_t^+\II_q^+\xx_t + \ZZ_t^+\II_q^{(0)}\xx_t + \aa_t^+ + \HH_t^+\vv_t\\ +\vv_t &\sim \MVN(0,\RR) +\end{split} +\end{equation} +where $\BB_t^{(0)}=\OMG_{t,q}^{(0)}\BB_t$ and $\BB_t^+=\OMG_{t,q}^+\BB_t$ so that $\BB_t^{(0)}$ are the rows of $\BB_t$ corresponding to the zero rows of $\GG_t$ and $\BB_t^+$ are the rows of $\BB_t$ corresponding to non-zero rows of $\GG_t$. The other parameters are similarly defined: $\uu_t^{(0)}=\OMG_{t,q}^{(0)}\uu_t$ and $\uu_t^+=\OMG_{t,q}^+\uu_t$, $\ZZ_t^{(0)}=\OMG_{t,r}^{(0)}\ZZ_t$ and $\ZZ_t^+=\OMG_{t,r}^+\ZZ_t$, and $\aa_t^{(0)}=\OMG_{t,r}^{(0)}\aa_t$ and $\aa_t^+=\OMG_{t,r}^+\aa_t$. + +\subsection{Identifying the fully deterministic $\xx$ rows}\label{sec:ident.xds} +To derive EM update equations, we need to take the derivative of the expected log-likelihood holding everything but the parameter of interest constant. If there are deterministic $\xx_t$ rows, then we cannot hold these constant and do this partial differentiation with respect to the state parameters. We need to identify these $\xx_t$ rows and remove them from the likelihood function by rewriting them in terms of only the state parameters\footnote{Then we can do the partial differentiation with respect to the parameters.}. For this derivation, I am going to make the simplifying assumption that the locations of the all-zero rows in $\GG_t$ and $\HH_t$ are time-invariant. This is not strictly necessary, but simplifies the algebra greatly. + +For the deterministic $\xx_t$ rows, denoted $\xx_t^d$, the process equation is $\xx_t = \BB_t\xx_{t-1}+\uu_t$, with no $\ww_t$ term. When we do the partial differentiation step in deriving the EM update equation for $\uu$, $\BB$ or $\xixi$, we will need to take a partial derivative while holding $\xx_t$ and $\xx_{t-1}$ constant. We cannot hold the deterministic rows of $\xx_t$ and $\xx_{t-1}$ constant while changing the corresponding rows of $\uu_t$ and $\BB_t$ (or $\xixi$ if $t=0$ or $t=1$). If a row of $\xx_t$ is fully deterministic, then that $x_{i,t}$ must change when row $i$ of $\uu_t$ or $\BB_t$ is changed. Thus we cannot do the partial differentiation step required in the EM update equation derivation. + +So we need to identify the fully deterministic $\xx_t$ and treat them differently in our likelihood so we can derive the update equation. First I will define some terminology regarding the $\xx_t$. +\begin{itemize} + \item $(0)$ rows of any $\xx$, $\BB$, $\uu$ or $\II$ matrix that are associated with all-zero rows of $\GG_t$, e.g. $\xx_t^{(0)}$. + \item $(+)$ rows of any $\xx$, $\BB$, $\uu$ or $\II$ matrix that are associated with non-zero rows of $\GG_t$, e.g. $\xx_t^{(+)}$. + \item 'directly stochastic' $\xx_t$ are denoted $\xx_t^{ds}$. These are the same as $\xx_t^{+}$. These $\xx_t$ have a $w_t$ from their row of $\GG_t$. + \item 'deterministic' $\xx_t$ are denoted $\xx_t^d$. These are those $\xx_t^{(0)}$ which have no $w_t$ terms either from their own row or picked up through $\BB$ from a non-zero row of $\GG_t$. + \item 'indirectly stochastic' $\xx_t$ are denoted $\xx_t^{is}$. Indirectly stochastic $\xx_t^{is}$ have a corresponding row of $\GG_t$ that is all zero, but pick up a $w_t$ from a non-zero row of $\GG_t$ through $\BB$ in one of the prior $\BB_t\xx_t$ steps. +\end{itemize} +The stochastic $\xx_t$ are denoted $\xx_t^s$ whether they are indirectly or directly stochastic. + +How do you determine the $d$, or deterministic, set of $\xx_t$ rows? These are the rows of $\xx_t$ with no $w$ terms, from time $t$ or from prior $t$. Note that the location of the $d$ rows is time-dependent, a row may be deterministic at time $t$ but pick up a $w$ at time $t+1$ and thus be indirectly stochastic thereafter. I am requiring that once a row becomes indirectly stochastic, it remains stochastic; rows are not allowed to flip back and forth between deterministic (no $w$ terms in them) and stochastic (containing a $w$ term). + +I will work through an example and then show a general algorithm to keep track of the deterministic rows at time $t$. + +\subsubsection*{Example} + +Let $\xx_0=\xixi$ (so $\FF$ is all zero and $\xx_0$ is not stochastic). Define $\II_t^{ds}$, $\II_t^{is}$, and $\II_t^d$ as diagonal indicator matrices with a 1 at $\II(i,i)$ if row $i$ is directly stochastic, indirectly stochastic, or deterministic respectively. $\II_t^{ds}+\II_t^{is}+\II_t^d=\II_m$. Let our state equation be $\xx_t=\BB\xx_{t-1}+\GG w_t$. +Let +\begin{equation} +\BB=\begin{bmatrix} +1&1&0&0\\ +1&0&0&0\\ +0&1&0&0\\ +0&0&0&1 +\end{bmatrix}\quad\quad +\GG=\begin{bmatrix} +1\\ +0\\ +0\\ +0 +\end{bmatrix} +\end{equation} +At $t=0$, $\xx_0$ is fixed, aka deterministic. +\begin{equation} +\xx_0=\begin{bmatrix} +\pi_1\\ +\pi_2\\ +\pi_3\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_0^d=\begin{bmatrix} +1&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_0^s=\II_0^{is}=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +At $t=1$, the $\xx_t$ begin picking up $w_t$ starting with $x_{1,t}$. +\begin{equation} +\xx_1=\begin{bmatrix} +\pi_1+\pi_2+w_1\\ +\pi_1\\ +\pi_2\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_1^d=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_1^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_1^{is}=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +At $t=2$, $x_{2,2}$ picks up $w_1$ through $\BB$. +\begin{equation} +\xx_2=\begin{bmatrix} +\dots+w_2\\ +\pi_1+\pi_2+w_1\\ +\pi_1\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_2^d=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&1&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_2^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_0^{is}=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +By $t=3$, the $\II^{d}$ and $\II^{is}$ stabilize. +\begin{equation} +\xx_3=\begin{bmatrix} +\dots+w_1+w_2+w_3\\ +\dots+w_1+w_2\\ +\pi_1+\pi_2+w_1\\ +\pi_4 +\end{bmatrix} +\end{equation} +\begin{equation} +\II_3^d=\begin{bmatrix} +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&1 +\end{bmatrix} +\quad +\II_3^{ds}=\begin{bmatrix} +1&0&0&0\\ +0&0&0&0\\ +0&0&0&0\\ +0&0&0&0 +\end{bmatrix} +\quad +\II_3^{is}=\begin{bmatrix} +0&0&0&0\\ +0&1&0&0\\ +0&0&1&0\\ +0&0&0&0 +\end{bmatrix} +\end{equation} +After time $t=3$ the location of the deterministic and indirectly stochastic rows is stabilized and no longer changes. + +\subsubsection*{Finding the indirectly stochastic rows} + +In general, it can take up to $m$ time steps for the location of the deterministic rows to stabilize. This is because $\BB_t$ is like an adjacency matrix, and I require that the location of the 0 elements in $\BB_1\BB_2\dots\BB_t$ is time invariant. If we replace all non-zero elements in $\BB_t$ with 1, then we have an adjacency matrix, let's call it $\MM$. If there is a path in $\MM$ from $x_{j,t}$, where $j$ is a $(0)$ row of $\xx$, to an $x_{i,t}$, where $i$ is a $(+)$ row, then row $j$ of $\xx$ will eventually be indirectly stochastic. Graph theory tells us that it takes at most $m$ steps for a $m \times m$ adjacency matrix to show full connectivity. This means that if element $(j,i)$ is 0 in $M^m$ then row $j$ is not connected to row $i$ by any path and thus will remain unconnected for $M^{t>m}$; note element $i,j$ can be 0 while $j,i$ is not. + +This means that to determine if $x_{j,t}$, in the $(0)$ rows, is indirectly stochastic, we raise $\MM$, to the $t$ power and look if there is a non-zero value in the $j$-th row and any $(+)$ columns of $\MM^t$. In words, we looking for a path from $x_{j,t}$ to any $x_{+}$ in the past. We do not need to do this past $t=m$ since the location of the indirectly stochastic and deterministic rows stabilize by then. + +Since my $\BB_t$ matrices are small, I use an inefficient strategy in the MARSS code to construct the indicator matrices $\II_d^t$. I define $\MM$ as $\BB_t$ with the non-zero $\BB$ replaced with 1; I require that the location of the non-zero elements in $\BB_t$ are time-invariant so there is only one $\MM$. Within the product $\MM^t$, those rows where only 0s appear in the 'stochastic' columns (non-zero $\GG_t$ rows) are the fully deterministic $\xx_{t+1}$ rows. Note, $t+1$ so one time step ahead. There are much faster algorithms for finding paths, but my $\MM$ tend to be small. Also, unfortunately, using $\BB^t$ in place of $\MM^t$ is not robust. Let's say $\BB=\bigl[ \begin{smallmatrix}-1&-2\\ 1&1\end{smallmatrix} \bigr]$, $\GG=\bigl[ \begin{smallmatrix}1\\ 0\end{smallmatrix} \bigr]$ and $\xx_0$ is fixed (not stochastic). +$\BB^2$ is a diagonal matrix suggesting that no connection between $x_2$ and $x_1$ at time $t=2$. That is incorrect. $x_{2,t}$ is indirectly stochastic. + +\subsubsection{Redefining the $\xx_t^d$ elements in the likelihood} +Because the deterministic rows of $\xx_t$ do not appear in the $\xx$ part of the likelihood (no error term = no likelihood), we have to move them into the $\yy$ part of the likelihood. To do that we need to re-write them in terms of only model parameters and remove all $\xx_{t-1}$ terms. This section walks through how to do that. + +By definition, all the $\BB_t$ elements in the $ds$ and $is$ columns of the $d$ rows of $\BB_t$ are 0. If they weren't, then $\xx_t^d$ wouldn't be a deterministic row because it would pick up a $w$ from a directly or indirectly stochastic $x$ from a prior $t-1$. This is due to the constraint that I have imposed that locations of 0s in $\BB_t$ are time-invariant and the location of the zero rows in $\GG_t$ also time-invariant: $\II_q^{+}$ and $\II_q^{(0)}$ are time-constant. + +\subsubsection*{Example} + +Consider this $\BB$ and $\GG$, which would arise in a MARSS version of an AR-3 model: +\begin{equation} +\BB=\begin{bmatrix} +b_1&b_2&b_3\\ +1&0&0\\ +0&1&0\end{bmatrix} +\quad +\GG=\begin{bmatrix} +1\\ +0\\ +0\end{bmatrix} +\end{equation} +Using $\xx_0=\xixi$ (so fixed and not stochastic): +\begin{equation} +\xx_0=\begin{bmatrix} +\pi_1\\ +\pi_2\\ +\pi_3 +\end{bmatrix} +\quad +\xx_1=\begin{bmatrix} +\dots+w_1\\ +\pi_1\\ +\pi_2 +\end{bmatrix} +\quad +\xx_2=\begin{bmatrix} +\dots+w_2\\ +\dots+w_1\\ +\pi_1\end{bmatrix} +\quad +\xx_3=\begin{bmatrix} +\dots+w_3\\ +\dots+w_2\\ +\dots+w_1 +\end{bmatrix} +\end{equation} +The $\dots$ just represent 'some values'. The key part is the $w$ appearing which is the stochasticity. At $t=1$, rows 2 and 3 are deterministic. At $t=2$, row 3 is deterministic, and at $t=3$, no rows are deterministic. + +The $\II^d$ are: +\begin{equation} +\II_{q,1}^d=\begin{bmatrix} +0&0&0\\ +0&1&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,2}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,3}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&0 +\end{bmatrix} +\end{equation} +The $\MM$ are: +\begin{equation} +\MM=\begin{bmatrix} +1&1&1\\ +1&0&0\\ +0&1&0 +\end{bmatrix} +\quad +\MM^2=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&1 +\end{bmatrix} +\quad +\II_{q,3}^d=\begin{bmatrix} +0&0&0\\ +0&0&0\\ +0&0&0 +\end{bmatrix} +\end{equation} + +We can rewrite the equation for the deterministic rows in $\xx_t$ as follows. $\xx_t^d$ is $\xx_t$ with the $d$ rows zeroed out, so $\xx_t^d = \II_{q,t}^d\xx_t$. +\begin{equation} \label{eq:xt.det.sum} +\begin{split} +\xx_1^{d}&=\II_{q,1}^d\xx_1\\ + &=\II_{q,1}^d(\BB_1 \xx_0 + \ff_{u,1} + \DD_{u,1}\uupsilon) \\ +\xx_2^{d}&=\II_{q,2}^d\xx_2\\ + &=\II_{q,2}^d(\BB_2 \xx_1 + \uu_2) \\ + &=\II_{q,2}\BB_2((\BB_1 \xx_0 + \ff_{u,1} + \DD_{u,1}\uupsilon) + \ff_{u,2} + \DD_{u,2}\uupsilon) \\ + &=\II_2^d(\BB_2\BB_1 \xx_0 + \BB_2\ff_{1,u} + \ff_{2,u} + (\BB_2\DD_{u,1} +\DD_{u,2})\uupsilon) \\ + \dots \\ +\end{split} +\end{equation} +The messy part is keeping track of which rows are deterministic because this will potentially change up to time $t=m$. + +We can rewrite the function for $\xx_t^d$, where $t_0$ is the $t$ at which the initial state is defined. It is either $t=0$ or $t=1$. +\begin{equation} \label{eq:xt.det.sum2} +\begin{split} +\xx_t^d &= \II_t^d(\BB^*_t\xx_{t_0} + \ff^*_t +\DD^*_t\uupsilon) \\ +\text{where}&\\ +\BB^*_{t_0} &= \II_m \\ +\BB^*_{t} &=\BB_t\BB^*_{t-1}\quad t > t_0 \\ +\\ +\ff^*_{t_0} &= 0 \\ +\ff^*_t &=\BB_t\ff^*_{t-1} + \ff_{t,u}\quad t > t_0\\ +\\ +\DD^*_{t_0} &= 0 \\ +\DD^*_t &= \BB_t\DD^*_{t-1} + \DD_{t,u}\quad t > t_0\\ +\\ +\II_{q,t_0}^d&=\II_\lambda^d\\ +\text{diag}(\II_{t_0+\tau}^d)&=\text{apply}(\OMG_q^{(0)}\MM^\tau\OMG_q^+ == 0, 1, \text{all}) +\end{split} +\end{equation} +The bottom line is written in R: $\II_{t_0+\tau}^d$ is a diagonal matrix with a 1 at $(i,i)$ where row $i$ of $\GG$ is all 0 and all $ds$ and $is$ columns in row $i$ of $\MM^t$ are equal to zero. + +In the expected log-likelihood, the term $\E[\XX_t^d]=\E[\XX_t^d|\YY=\yy]$, meaning the expected value of $\XX_t^d$ conditioned on the data, appears. Thus in the expected log-likelihood the function will be written: +\begin{equation} +\begin{split} +\XX_t^d &= \II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) \\ +\E[\XX_t^d] &= \II_t^d(\BB^*_t\E[\XX_{t_0}] + \ff^*_t +\DD^*_t\uupsilon) +\end{split} +\end{equation} + +When the $j$-th row of $\FF$ is all zero, meaning the $j$-th row of $\xx_0$ is fixed to be $\xi_j$, then $\E[X_{t_0,j}]\equiv\xi_j$. This is the case where we treat $x_{t_0,j}$ as fixed and we either estimate or specify its value. If $\xx_{t_0}$ is wholly treated as fixed, then $\E[\XX_{t_0}]\equiv\xixi$ and $\LAM$ does not appear in the model at all. In the general case, where some $x_{t_0,j}$ are treated as fixed and some as stochastic, we can write $\E[\XX_t^d]$ appearing in the expected log-likelihood as: +\begin{equation}\label{eq:EXtd} +\begin{split} +\E[\XX_{t_0}]=(\II_m-\II_\lambda^{(0)})\E[\XX_{t_0}]+\II_\lambda^{(0)}\xixi +\end{split} +\end{equation} +$\II_\lambda^{(0)}$ is a diagonal indicator matrix with 1 at $(j,j)$ if row $j$ of $\FF$ is all zero. + +If $\BB^{d,d}$ and $\uu^d$ are time-constant, we could use the matrix geometric series: +\begin{equation}\label{eq:xt.geo} +\begin{split} +\xx_t^{d}=&(\BB^{d,d})^t \xx_0^{d} + \sum_{i=0}^{t-1}(\BB^{d,d})^i \uu^{d} = +(\BB^{d,d})^t \xx_0^{d} + (\II - \BB^{d,d})^{-1}(\II-(\BB^{d,d})^t)\uu^{d}, \quad\text{if }\BB^{d,d} \neq \II\\ +&\xx_0^d + \uu^d,\quad\text{if }\BB^{d,d} = \II +\end{split} +\end{equation} +where $\BB^{d,d}$ is the block of $d$'s associated with the deterministic $\xx_t$. + +\subsubsection{Dealing with the $\xx_t^{is}$ elements in the likelihood and associated parameter rows} +Although $\ww_t^{is}=0$, these terms are connected to the stochastic $\xx$'s in earlier time steps though $\BB$, thus all $\xx_t^{is}$ are possible for a given $\uu_t$, $\BB_t$ or $\xixi$. However, all $\xx_t^{is}$ are not possible conditioned on $\xx_{t-1}$, so we are back in the position that we cannot both change $\xx_t$ and change $\uu_t$. + +Recall that for the partial differentiation step in the EM algorithm, we need to be able to hold the $E[\XX_t]$ appearing in the likelihood constant. We can deal with the deterministic $\xx_t$ because they are not stochastic and do not have 'expected values'. They can be removed from the likelihood by rewriting $\xx_t^d$ in terms of the model parameters. We cannot do that for $\xx_t^{is}$ because these $x$ are stochastic. There is no equation for them; all $\xx^{is}$ are possible but some are more likely than others. We also cannot replace $\xx_t^{is}$ with $\BB_t^{is}E[\XX_{t-1}]+\uu_t^{is}$ to force $\BB_t^{is}$ and $\uu^{is}$ to appear in the $\yy$ part of the likelihood. The reason is that $\E[\XX_t]$ and $\E[\XX_{t-1}]$ both appear in the likelihood and we cannot hold both constant (as we must for the partial differentiation) and at the same time change $\BB_t^{is}$ or $\uu_t^{is}$ as we are doing when we differentiate with respect to $\BB_t^{is}$ or $\uu)_t^{is}$. We cannot do that because $\xx_t^{is}$ is constrained to equal $\BB_t^{is}\xx_{t-1}+\uu_t^{is}$. + +This effectively means that we cannot estimate $\BB_t^{is}$ and $\uu_t^{is}$ because we cannot rewrite $\xx_t^{is}$ in terms of only the model parameters. This is specific to the EM algorithm because it is an iterative algorithm where the expected $\XX_t$ are computed with fixed parameters and then the $\E[\XX_t]$ are held fixed at their expected values while the parameters are updated. In my $\BB$ update equation, I assume that $\BB_t^{(0)}$ is fixed for all $t$. Thus I circumvent the problem altogether for $\BB$. For $\uu$, I assume that only the $\uu^{is}$ elements are fixed. + +\subsection{Expected log-likelihood for degenerate models} + +The basic idea is to replace $\II_q^d\E[\XX_t]$ with a deterministic function involving only the state parameters (and $\E[\XX_{t_0}]$ if $\XX_{t_0}$ is stochastic) . These appear in the $\yy$ part of the likelihood in $\ZZ_t\XX_t$ when the $d$ columns of $\ZZ_t$ have non-zero values. They appear in the $\xx$ part of the likelihood in $\BB_t\XX_{t-1}$ when the $d$ columns of $\BB_t$ have non-zero values. They do not appear in $\XX_t$ in the $\xx$ part of the likelihood because $\Qm_t$ has all the non-$s$ columns and rows zeroed out (non-$s$ includes both $d$ and $is$) and the element to the left of $\Qm_t$ is a row vector and to the right, it is a column vector. Thus any $\xx_t^d$ in $\XX_t$ are being zeroed out by $\Qm_t$. + +The first step is to pull out the $\II_t^{d}\XX_t$: +\begin{equation} +\begin{split} +\Psi^+ &= \E[\log\LL(\YY^+,\XX^+ ; \Theta)] = \E[-\frac{1}{2}\sum_1^T \\ +& (\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d\XX_t - \aa_t)^\top \Rm_t\\ +&(\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d\XX_t - \aa_t) -\frac{1}{2}\sum_1^T\log |\RR_t|\\ +& -\frac{1}{2}\sum_{t_0+1}^T (\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d\XX_{t-1}) - \uu_t)^\top \Qm_t \\ +&(\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d\XX_{t-1}) - \uu_t) - \frac{1}{2}\sum_{t_0+1}^T\log |\QQ_t| \\ +& - \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| -\frac{n}{2}\log 2\pi +\end{split} +\end{equation} +See section \ref{sec:ident.xds} for the definition of $\II_t^d$. + +Next we replace $\II_q^d\XX_t$ with equation \ref{eq:xt.det.sum2}. $\XX_{t_0}$ will appear in this function instead of $\xx_{t_0}$. I rewrite $\uu_t$ as $\ff_{u,t}+\DD_{u,t}\uupsilon$. This gives us the expected log-likelihood: +\begin{equation}\label{eq:degen.logL.x0} +\begin{split} +\Psi^+ &= \E[\log\LL(\YY^+,\XX^+ ; \Theta)] = \E[-\frac{1}{2}\sum_1^T \\ +& (\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) - \aa_t)^\top \Rm_t\\ +&(\YY_t - \ZZ_t(\II_m-\II_t^d)\XX_t - \ZZ_t\II_t^d(\BB^*_t\XX_{t_0} + \ff^*_t +\DD^*_t\uupsilon) - \aa_t) -\frac{1}{2}\sum_1^T\log |\RR_t|\\ +& -\frac{1}{2}\sum_{t_0+1}^T (\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d(\BB^*_{t-1}\XX_{t_0} + \ff^*_{t-1} +\DD^*_{t-1}\uupsilon)) - \ff_{u,t} - \DD_{u,t}\uupsilon)^\top \Qm_t \\ +&(\XX_t - \BB_t ((\II_m - \II_{t-1}^d)\XX_{t-1} + \II_{t-1}^d(\BB^*_{t-1}\XX_{t_0} + \ff^*_{t-1} +\DD^*_{t-1}+\uupsilon)) - \ff_{u,t} - \DD_{u,t}\uupsilon) \\ +&- \frac{1}{2}\sum_{t_0}^T\log |\QQ_t| - \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| -\frac{n}{2}\log 2\pi +\end{split} +\end{equation} +where $\BB^*$, $\ff^*$ and $\DD^*$ are defined in equation \ref{eq:xt.det.sum2}. $\Rm_t = \Xi_t^\top\RR_t^{-1}\Xi_t$ and $\Qm_t = \Phi_t^\top\QQ_t^{-1}\Phi_t$, $\LAMm = \Pi^\top\LAM^{-1}\Pi$. When $\xx_{t_0}$ is treated as fixed, $\LAMm=0$ and the last line will drop out altogether, however in general some rows of $\xx_{t_0}$ could be fixed and others stochastic. + +We can see directly in equation \ref{eq:degen.logL.x0} where $\uupsilon$ appears in the expected log-likelihood. Where $\pp$ appears is less obvious because it depends on $\FF$, which specifies which rows of $\xx_{t_0}$ are fixed. From equation \ref{eq:EXtd}, $$\E[\XX_{t_0}]=(\II_m-\II_l^{(0)})\E[\XX_{t_0}]+\II_l^{(0)}\xixi$$ +and $\xixi=\ff_\xi+\DD_\xi\pp$. Thus where $\pp$ appears in the expected log-likelihood depends on the location of zero rows in $\FF$ (and thus the zero rows in the indicator matrix $\II_l^{(0)}$). Recall that $\E[\XX_{t_0}]$ appearing in the expected log-likelihood function is conditioned on the data so $\E[\XX_{t_0}]$ in $\Psi$ is not equal to $\xixi$ if $\xx_{t_0}$ is stochastic. + +The case where $\xx_{t_0}$ is stochastic is a little odd because conditioned on $\XX_{t_0}=\xx_{t_0}$, $\xx_t^d$ is deterministic even though $\XX_0$ is a random variable in the model. Thus in the model, $\xx_t^d$ is a random variable through $\XX_{t_0}$. But when we do the partial differentiation step for the EM algorithm, we hold $\XX$ at its expected value thus we are holding $\XX_{t_0}$ at a specific value. We cannot do that and change $\uu$ at the same time because once we fix $\XX_{t_0}$ the $\xx_t^d$ are deterministic functions of $\uu$. + +\subsection{Logical constraints to ensure a consistent system of equations} +We need to ensure that the model remains internally consistent when $\RR$ or $\QQ$ goes to zero and that we do not have an over- or under-constrained system. + +As an example of a solvable versus unsolvable model, consider the following. +\begin{equation} +\HH_t\RR_t=\begin{bmatrix} +0&0\\ +1&0\\ +0&1\\ +0&0 +\end{bmatrix} +\begin{bmatrix} +a&0\\ +0&b\\ +\end{bmatrix} = \begin{bmatrix} +0&0&0&0\\ +0&a&0&0\\ +0&0&b&0\\ +0&0&0&0\\\end{bmatrix}, +\end{equation} +then following are bad versus ok $\ZZ$ matrices. +\begin{equation} +\ZZ_{\text{bad}}=\begin{bmatrix} +c&d&0\\ +z(2,1)&z(2,2)&z(2,3)\\ +z(3,1)&z(3,1)&z(3,1)\\ +c&d&0 +\end{bmatrix},\quad +\ZZ_{\text{ok}}=\begin{bmatrix} +c&0&0\\ +z(2,1)&z(2,2)&z(2,3)\\ +z(3,1)&z(3,1)&z(3,1)\\ +c&d\neq0&0 +\end{bmatrix} +\end{equation} +Because $y_t(1)$ and $y_t(4)$ have zero observation variance, the first $\ZZ$ reduces to this for $x_t(1)$ and $x_t(2)$: +\begin{equation} +\begin{bmatrix} +y_t(1)\\ +y_t(4) +\end{bmatrix}= +\begin{bmatrix} +c x_t(1) + d x_t(2)\\ +c x_t(1) + d x_t(2) +\end{bmatrix} +\end{equation} +and since $y_t(1)\neq y_t(4)$, potentially, that is not solvable. The second $\ZZ$ reduces to +\begin{equation} +\begin{bmatrix} +y_t(1)\\ +y_t(4) +\end{bmatrix}= +\begin{bmatrix} +c x_t(1)\\ +c x_t(1) + d x_t(4) +\end{bmatrix} +\end{equation}and that is solvable for any $y_t(1)$ and $y_t(4)$ combination. Notice that in the latter case, $x_t(1)$ and $x_t(2)$ are fully specified by $y_t(1)$ and $y_t(4)$. + +\subsubsection{Constraint 1: $\ZZ$ does not lead to an over-determined observation process} +We need to ensure that a $\xx_t$ exists for all $\yy^{(0)}_t$ such that: +$$\E[\YY^{(0)}_t]=\ZZ^{(0)}\E[\XX_t]+\aa^{(0)}.$$ If $\ZZ^{(0)}$ is invertible, such a $\xx_t$ certainly exists. But we do not require that only one $\xx_t$ exists, simply that at least one exists. Thus the system can be under-constrained but not over-constrained. One way to test for this is to use the singular value decomposition (SVD) of $\ZZ^{(0)}$ ($\ZZ^{(0)}$ square). If the number of singular values of $\ZZ^{(0)}$ is less than the number of columns in $\ZZ$, which is the number of $\xx$ rows, then $\ZZ^{(0)}$ specifies an over-constrained system ($y=Zx$\footnote{This is the classic problem of solving the system of linear equations, which is standardly written $Ax=b$.}) Using the R language, you would test if the length of \verb@svd(Z)$d@ is less than than \verb@dim(Z)[2]@. If $\ZZ^{(0)}$ specifies and under-determined system, some of the singular values would be equal to 0 (within machine tolerance). It is possible that $\ZZ^{(0)}$ could specify both an over- and under-determined system at the same time. That is, the number of singular values could be less than the number of columns in $\ZZ^{(0)}$ and some of the singular values could be 0. + +Doesn't a $\ZZ$ with more rows than columns automatically specify a over-determined system? No. Considered this $\ZZ$ +\begin{equation} +\begin{bmatrix} +1&0\\ +0&1\\ +0&0 +\end{bmatrix} +\end{equation} +This $\ZZ$ is fine, although obviously the last row of $\yy$ will not hold any information about the $\xx$. But it could have information about $\RR$ and $\aa$, which might be shared with the other $\yy$, so we don't want to prevent the user from specifying a $\ZZ$ like this. + + +\subsubsection{Constraint 2: the state processes are not over-constrained. } +We also need to be concerned with the state process being over-constrained when both $\QQ=0$ and $\RR=0$ because we can have a situation where the constraint imposed by the observation process is at odds with the constraint imposed by the state process. Here is an example: + +\begin{equation} +\begin{split} +\yy_t=\begin{bmatrix} +1&0\\ +0&1 +\end{bmatrix} +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_t\\ +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_t= +\begin{bmatrix} +1&0\\ +0&0 +\end{bmatrix} +\begin{bmatrix} +x_1\\x_2 +\end{bmatrix}_{t-1} ++ +\begin{bmatrix} +w_1\\0 +\end{bmatrix}_{t-1} +\end{split} +\end{equation} + +In this case, some of the $x$'s are deterministic, $\QQ=0$ and not linked through $\BB$ to a stochastic $x$, and the corresponding $y$ are also deterministic. These cases will show up as errors in the Kalman filter/smoother because in the Kalman gain equation (equation \ref{eq:Kt}), the term $\ZZ_t\VV_t^{t-1}\ZZ_t^\top$ will appear when $\RR=0$. We need to make sure that 0 rows in $\BB_t$, $\ZZ_t$ and $\QQ_t$ do not line up in such a way that 0 rows/cols do not appear in $\ZZ_t\VV_t^{t-1}\ZZ_t^\top$ at the same place as 0 rows/cols in $\RR$. In MARSS, this is checked by doing a pre-run of the Kalman smoother to see if it throws an error in the Kalman gain step. + +\section{EM algorithm modifications for degenerate models} + +The $\RR$, $\QQ$, $\ZZ$, and $\aa$ update equations are largely unchanged. The real difficulties arise for the $\uu$ and $\xixi$ update equations when $\uu^{(0)}$ or $\xixi^{(0)}$ are estimated. For $\BB$, I do not have a degenerate update equation, so I need to assume that $\BB^{(0)}$ elements are fixed (not estimated). + +\subsection{$\RR$ and $\QQ$ update equations} +The constrained update equations for $\QQ$ and $\RR$ work fine because their update equations do not involve any inverses of non-invertible matrices. However if $\HH_t\RR_t\HH_t^\top$ is non-diagonal and there are missing values, then the $\RR$ update equation involves $\hatyt$. That will involve the inverse of $\HH_t\RR_{11}\HH_t^\top$ (section \ref{sec:exp.Y}), which might have zeros on the diagonal. In that case, use the $\IR_t$ modification that deals with such zeros (equation \ref{eq:IRt.degen}). + + +\subsection{$\ZZ$ and $\aa$ update equations} +We need to deal with $\ZZ$ and $\aa$ elements that appear in rows where the diagonal of $\RR=0$. These values will not appear in the likelihood function unless they also happen to also appear on the rows where the diagonal of $\RR$ is not 0 (because they are constrained to be equal for example). However, in this case the $\ZZ^{(0)}$ and $\aa^{(0)}$ are logically constrained by the equation +$$\yy_t^{(0)}=\ZZ_t^{(0)}\E[\xx_t]+\aa_t^{(0)}.$$ +Notice there is no $\ww_t$ since $\RR=0$ for these rows. The $\E[\xx_t]$ is ML estimate of $\xx_t$ computed in the Kalman smoother from the parameter values at iteration $i$ of the EM algorithm, so there is no information in this equation for $\ZZ$ and $\aa$ at iteration $i+1$. The nature of the smoother is that it will find the $\xx_t$ that is most consistent with the data. For example if our $y=Zx+a$ equation looks like so +\begin{equation} +\begin{bmatrix} +0\\ +2\\ +\end{bmatrix} += +\begin{bmatrix} +1\\ +1\\ +\end{bmatrix} +x, +\end{equation} +there is no $x$ that will solve this. However $x=1$ is the closest (lowest squared error) and so this is the information in the data about $x$. The Kalman filter will use this and the relative value of $\QQ$ and $\RR$ to come up with the estimated $x$. In this case, $\RR=0$, so the information in the data will completely determine $x$ and the smoother would return $x=1$ regardless of the process equation. + +The $\aa$ and $\ZZ$ update equations require that $\sum_{t=1}^T \DD_{t,a}^\top\Rm_t\DD_{t,a}$ and $\sum_{t=1}^T \DD_{t,z}^\top\Rm_t\DD_{t,z}$ are invertible. If $\ZZ_t^{(0)}$ and $\aa_t^{(0)}$ are fixed, this will be satisfied, however the restriction is a little less restrictive than that since it is possible that $\Rm_t$ does not have zeros on the diagonal in the same places so that the sum over $t$ could be invertible while the individual values at $t$ are not. The section on the summary of constraints has the test for this constraint. + +The update equations also +involve $\hatyt$, and the modified algorithm for $\hatyt$ when $\HH_t$ has all zero rows will be needed. Other than that, the constrained update equations work (sections \ref{sec:constA} and \ref{sec:constZ}). + +\subsection{$\uu$ update equation} + +Here I discuss the update for $\uu$, or more specifically $\uupsilon$ which appears in $\uu$, when $\GG_t$ or $\HH_t$ have zero rows. I require that $\uu^{is}_t$ is not estimated. All the $\uu^{is}_t$ are fixed values. The $\uu_t^d$ may be estimated or more specifically there may be $\uupsilon$ in $\uu_t^d$ that are estimated; $\uu_t^d = \ff_{u,t}^d+\DD_{u,t}^d\uupsilon$. + + +For the constrained $\uu$ update equation with deterministic $\xx$'s takes the following form. It is similar to the unconstrained update equation except that that a part from the $\yy$ part of the likelihood now appears: +\begin{equation} +\begin{split}\label{eq:u.update.degen.2} +\pmb{\upsilon}_{j+1} = \bigg(\sum_{t=1}^T(\Delta_{t,2}^\top\Rm_t\Delta_{t,2} + \Delta_{t,4}^\top\Qm_t\Delta_{t,4})\bigg)^{-1} \times + \bigg( \sum_{t=1}^T \big( \Delta_{t,2}^\top\Rm_t\Delta_{t,1} + \Delta_{t,4}^\top\Qm_t\Delta_{t,3} \big) \bigg)\\ +\end{split} +\end{equation} + +Conceptually, I think the approach described here is the similar to the approach presented in section 4.2.5 of \citep{Harvey1989}, but it is more general because it deals with the case where some $\uu$ elements are shared (linear functions of some set of shared values), possibly across deterministic and stochastic elements. Also, I present it here within the context of the EM algorithm, so solving for the maximum-likelihood $\uu$ appears in the context of maximizing $\Psi^+$ with respect to $\uu$ for the update equation at iteration $j+1$. + +\subsubsection{$\uu^{(0)}$ is not estimated} +When $\uu^{(0)}$ is not estimated (since it is at some user defined value via $\DD_u$ and $\ff_u$), the part we are estimating, $\uu^+$, only appears in the $\xx$ part of the likelihood. The update equation for $\uu$ remains equation \ref{eq:u.general.update1}. + +\subsubsection{$\uu^d$ is estimated} +The derivation of the update equation proceeds as usual. We need to take the partial derivative of $\Psi^+$ (equation \ref{eq:degen.logL.x0}) holding everything constant except $\uupsilon$, elements of which might appear in both $\uu_t^d$ and $\uu_t^s$ (but not $\uu_t^{is}$ since I require that $\uu_t^{is}$ has no estimated elements). + +The expected log-likelihood takes the following form, where $t_0$ is the time where the initial state is defined ($t=0$ or $t=1$): +\begin{equation}\label{eq:degen.logL.u} +\begin{split} +\Psi^+ = +-\frac{1}{2}\sum_1^T (\Delta_{t,1} - \Delta_{t,2}\pmb{\upsilon})^\top\Rm_t(\Delta_{t,1} - \Delta_{t,2}\pmb{\upsilon}) - \frac{1}{2}\sum_1^T\log |\RR_t| \\ +-\frac{1}{2}\sum_{t_0+1}^T (\Delta_{t,3} - \Delta_{t,4}\pmb{\upsilon})^\top\Qm_t(\Delta_{t,3} - \Delta_{t,4}\pmb{\upsilon}) - \frac{1}{2}\sum_{t_0+1}^T\log |\QQ_t| \\ +- \frac{1}{2}(\XX_{t_0} - \xixi)^\top \LAMm(\XX_{t_0} - \xixi) - \frac{1}{2}\log |\LAM| - \frac{n}{2}\log 2\pi \\ +\end{split} +\end{equation} +$\LAMm=\FF^\top\LAM^{-1}\FF$. If $\xx_{t_0}$ is treated as fixed, $\FF$ is all zero and the line with $\LAMm$ drops out. If some but not all $\xx_{t_0}$ are treated as fixed, then only the stochastic rows appear in the last line. In any case, the last line does not contain $\uupsilon$, thus when we do the partial differentiation with respect to $\uupsilon$, this line drops out. + +The $\Delta$ terms are defined as: +\begin{equation}\label{eq:degen.u.update.Deltas} +\begin{split} +\Delta_{t,1}&=\hatyt - \ZZ_t(\II_m - \II_t^d)\hatxt - \ZZ_t\II_t^{d}(\BB^*_t\E[\XX_{t_0}] + \ff^*_t) - \aa_t \\ +\Delta_{t,2}&= \ZZ_t\II_t^{d}\DD^*_t \\ +\Delta_{t_0,3}&=0_{m\times 1} \\ +\Delta_{t,3}&=\hatxt - \BB_t(\II_m - \II_{t-1}^d)\hatxtm - \BB_t\II_{t-1}^{d}(\BB^*_{t-1} \E[\XX_{t_0}] + \ff^*_{t-1}) - \ff_{t,u} \\ +\Delta_{t_0,4}&=0_{m\times m} \DD_{1,u} \\ +\Delta_{t,4}&=\DD_{t,u}+\BB_t\II_{t-1}^{d}\DD^*_{t-1} \\ +\E[\XX_{t_0}]&=((\II_m-\II_\lambda^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \xixi) +\end{split} +\end{equation} +$\II^d_t$, $\BB_t^*$, $\ff_t*$, and $\DD_t^*$ are defined in equation \ref{eq:xt.det.sum2}. The values of these at $t_0$ is special so that the math works out. The expectation ($\E$) has been subsumed into the $\Delta$s since $\Delta_2$ and $\Delta_4$ do not involve $\XX$ or $\YY$, so terms like $\XX^\top\XX$ never appear. + +Take the derivative of this with respect to $\uupsilon$ and arrive at: +\begin{equation} +\begin{split} +\label{eq:p.degen.update.u} +\uupsilon_{j+1} = \big(\sum_{t=1}^T\Delta_{t,4}^\top\Qm_t\Delta_{t,4} + \sum_{t=1}^T\Delta_{t,2}^\top\Rm_t\Delta_{t,2}\big)^{-1} \times + \bigg(\sum_{t=1}^T\Delta_{1,4}^\top\Qm_t\Delta_{1,3} + \sum_{t=1}^T \Delta_{t,2}^\top\Rm_t\Delta_{t,1})\bigg) +\end{split} +\end{equation} + +\subsection{$\xixi$ update equation} + +\subsubsection{$\xixi$ is stochastic} +This means that none of the rows of $\FF$ (in $\FF\lambda$) are zero, so $\II_\lambda^{(0)}$ is all zero and the update equation reduces to a constrained version of the classic $\xixi$ update equation: +\begin{equation} +\label{eq:p.degen.update.x0.0.a} +\pp_{j+1} = \big(\DD_\xi^\top\LAM^{-1}\DD_\xi\big)^{-1}\DD_\xi^\top\LAM^{-1}(\E[\XX_{t_0}] - \ff_\xi) +\end{equation} +\subsubsection{$\xixi^{(0)}$ is not estimated} +When $\xixi^{(0)}$ is not estimated (because you fixed it as some value), we do not need to take the partial derivative with respect to $\xixi^{(0)}$ since we will not be estimating it. Thus the update equation is unchanged from the constrained update equation. + +\subsubsection{$\xixi^{(0)}$ is estimated} +Using the same approach as for $\uu$ update equation, we take the derivative of \ref{eq:degen.logL.x0} with respect to $\pp$ where $\xixi=\ff_\xi+\DD_\xi\pp$. $\Psi^+$ will take the following form: +\begin{equation}\label{eq:degen.logL.x0.0} +\begin{split} +\Psi^+ &= \\ +&-\frac{1}{2}\sum_{t=1}^T (\Delta_{t,5} - \Delta_{t,6}\pp)^\top\Rm_t(\Delta_{t,5} - \Delta_{t,6}\pp) - \frac{1}{2}\sum_1^T\log |\RR_t| \\ +& -\frac{1}{2}\sum_{t=1}^T (\Delta_{t,7} - \Delta_{t,8}\pp)^\top\Qm_t(\Delta_{t,7} - \Delta_{t,8}\pp) - \frac{1}{2}\sum_1^T\log |\QQ_t| \\ +& -\frac{1}{2} (\E[\XX_{t_0}] - \ff_\xi - \DD_\xi\pp)^\top\LAMm(\E[\XX_{t_0}] - \ff_\xi - \DD_\xi\pp) - \frac{1}{2}\log |\LAM| \\ +& - \frac{n}{2}\log 2\pi \\ +\end{split} +\end{equation} + +The $\Delta$'s are defined as follows using $ \E[\XX_{t_0}]=(\II_m-\II_l^{(0)})\widetilde{\xx}_{t_0}+\II_l^{(0)}\xixi$ where it appears in $\II_t^d\E[\XX_t]$. +\begin{equation}\label{eq:degen.x0.update.Deltas} +\begin{split} +\Delta_{t,5}&=\hatyt - \ZZ_t(\II_m - \II_t^d)\hatxt - \ZZ_t\II_t^{d}(\BB^*_t((\II_m-\II_\lambda^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \ff_\xi) + \uu^*_t) - \aa_t \\ +\Delta_{t,6}&= \ZZ_t\II_t^{d}\BB^*_t\II_\lambda^{(0)}\DD_\xi \\ +\Delta_{t_0,7}&=0_{m\times 1} \\ +\Delta_{t,7}&=\hatxt - \BB_t(\II_m - \II_{t-1}^d)\hatxtm - \BB_t\II_{t-1}^{d}(\BB^*_{t-1} ((\II_m-\II_l^{(0)})\widetilde{\xx}_{t_0}+\II_\lambda^{(0)} \ff_\xi) + \uu^*_{t-1}) - \uu_t \\ +\Delta_{t_0,8}&=0_{m\times m} \DD_\xi\\ +\Delta_{t,8}&=\BB_t\II_{t-1}^{d}\BB^*_{t-1}\II_\lambda^{(0)}\DD_\xi\\ +\uu^*_t=\ff^*_t+\DD^*_t\uupsilon +\end{split} +\end{equation} +The expectation can be pulled inside the $\Delta$s since the $\Delta$s in front of $\pp$ do not involve $\XX$ or $\YY$. + +Take the derivative of this with respect to $\pp$ and arrive at: +\begin{equation} +\begin{split} +\label{eq:p.degen.update.x0.0.a.fixed} +\pp_{j+1} &= \big(\sum_{t=1}^T\Delta_{t,8}^\top\Qm_t\Delta_{t,8} + \sum_{t=1}^T\Delta_{t,6}^\top\Rm_t\Delta_{t,6} + \DD_\xi^\top\LAMm\DD_\xi\big)^{-1} \times\\ +&\quad \bigg(\sum_{t=1}^T\Delta_{1,8}^\top\Qm_t\Delta_{1,7} + \sum_{t=1}^T \Delta_{t,6}^\top\Rm_t\Delta_{t,5} + \DD_\xi^\top\LAMm(\E[\XX_{t_0}] - \ff_\xi)\bigg) +\end{split} +\end{equation} + +\subsubsection{When $\HH_t$ has 0 rows in addition to $\GG_t$} +When $\HH_t$ has all zero rows, some of the $\pp$ or $\uupsilon$ may constrained by the model, but these constraints do not appear in $\Psi^+$ since $\Rm_t$ zeros out those constraints. For example, if $H_t$ is all zeros and $\xx_1 \equiv \xixi$, then $\xixi$ is constrained to equal $\ZZ^{-1}(\hatyone-\aa_1)$. + +The model needs to be internally consistent and we need to be able to estimate all the $\pp$ and the $\uupsilon$. Rather than try to estimate the correct $\pp$ and $\uupsilon$ to ensure internal consistency of the model with the data when some of the $\HH_t$ have 0 rows, I test by running the Kalman filter with the degenerate variance modification (in particular the modification for $\FF$ with zero rows is critical) before starting the EM algorithm. Then I test that $\hatyt-\ZZ_t\hatxt-\aa_t$ is all zeros. If it is not, within machine accuracy, then there is a problem. This is reported and the algorithm stopped\footnote{In some cases, it is easy to determine the correct $\xixi$. For example, when $\HH_t$ is all zero rows, $t_0=1$ and there is no missing data at time $t=1$, $\xixi=\ZZ^*(\yy_1-\aa_1)$, where $\ZZ^*$ is the pseudoinverse. One would want to use the SVD pseudoinverse calculation in case $\ZZ$ leads to an under-constrained system (some of the singular values of $\ZZ$ are 0). } + +I also test that $\big(\sum_{t=1}^T\Delta_{t,8}^\top\Qm_t\Delta_{t,8} + \sum_{t=1}^T\Delta_{t,6}^\top\Rm_t\Delta_{t,6} + \DD_\xi^\top\LAMm\DD_\xi\big)$ is invertible to ensure that all the $\pp$ can be solved for, and I test that $\big(\sum_{t=1}^T\Delta_{t,4}^\top\Qm_t\Delta_{t,4} + \sum_{t=1}^T\Delta_{t,2}^\top\Rm_t\Delta_{t,2}\big)$ is invertible so that all the $\uupsilon$ can be solved for. If errors are present, they should be apparent in iteration 1, are reported and the EM algorithm stopped. + +\subsection{$\BB^{(0)}$ update equation for degenerate models} +I do not have an update equation for $\BB^{(0)}$ and for now, I side-step this problem by requiring that any $\BB^{(0)}$ terms are fixed. + +\section{Kalman filter and smoother modifications for degenerate models} + +\subsection{Modifications due to degenerate $\RR$ and $\QQ$} +[1/1/2012 note. These modifications mainly have to do with inverses that appear in the Shumway and Stoffer's presentation of the Kalman filter. The MARSS package uses Koopman's smoother algorithm which avoids these inverses altogether however these appear in the MARSSkfss() function (the Shumway and Stoffer implementation).] + +In principle, when either $\GG_t\QQ_t$ or $\HH_t\RR_t$ has zero rows, the standard Kalman filter/smoother equations would still work and provide the correct state outputs and likelihood. In practice however errors will be generated because under certain situations, one of the matrix inverses in the Kalman filter/smoother equations will involve a matrix with a zero on the diagonal and this will lead to the computer code throwing an error. + +When $\HH_t\RR_t$ has zero rows, problems arise in the Kalman update part of the Kalman filter. +The Kalman gain is +\begin{equation}\label{eq:KKt.2} +\KK_t = \VV_t^{t-1}(\ZZ_t^*)^\top(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)^{-1} +\end{equation} +Here, $\ZZ_t^*$ is the missing values modified $\ZZ_t$ matrix with the $i$-th rows zero-ed out if the $i$-th element of $\yy_t$ is missing (section \ref{sec:kalman.smoother}, equation \ref{eq:yaZ.miss}). Thus if the $i$-th element of $\yy_t$ is missing and the $i$-th row of $\HH_t$ is zero, the $(i,i)$ element of $(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)$ will be zero also and one cannot take its inverse. In addition, if the initial value $\xx_1$ is treated as fixed but unknown then $\VV_1^0$ will be a $m \times m$ matrix of zeros. Again in this situation $(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)$ will have zeros at any $(i,i)$ elements where the $i$-th row of $\HH_t$ is also zero. + +The first case, where zeros on the diagonal arise due to missing values in the data, can be solved using the matrix which pulls out the rows and columns corresponding to the non-missing values ($\OMG_t^{(1)}$). Replace $\big(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top\big)^{-1}$ in equation \ref{eq:KKt.2} with +\begin{equation} +(\OMG_t^{(1)})^\top\big(\OMG_t^{(1)}(\ZZ_t^*\VV_t^{t-1}(\ZZ_t^*)^\top + \HH_t\RR_t^*\HH_t^\top)(\OMG_t^{(1)})^\top\big)^{-1}\OMG_t^{(1)} +\end{equation} +Wrapping in $\OMG_t^{(1)}(\OMG_t^{(1)})^\top$ gets rid of all the zero rows/columns in $\ZZ_t^\prime\VV_t^{t-1}(\ZZ_t^\prime)^\top + \HH_t\RR_t^\prime\HH_t^\top$, and the matrix is reassembled with the zero rows/columns reinserted by wrapping in $(\OMG_t^{(1)})^\top\OMG_t^{(1)}$. This works because $\RR_t^\prime$ is the missing values modified $\RR$ (section \ref{sec:missing}) and is block diagonal across the $i$ and non-$i$ rows/columns, and $\ZZ_t^\prime$ has the $i$-columns zero-ed out. Thus removing the $i$ columns and rows before taking the inverse has no effect on the product $\ZZ_t(...)^{-1}$. When $\VV_1^0=\mathbf{0}$, set $\KK_1=\mathbf{0}$ without computing the inverse (see equation \ref{eq:KKt.2} where $\VV_1^0$ appears on the left). + +There is also a numerical issue to deal with. When the $i$-th row of $\HH_t$ is zero, some of the elements of $\xx_t$ may be completely specified (fully known) given $\yy_t$. Let's call these fully known elements of $\xx_t$, the $k$-th elements. In this case, the $k$-th row and column of $\VV_t^t$ must be zero because given $y_t(i)$, $x_t(k)$ is known (is fixed) and its variance, $\VV_t^t(k,k)$, is zero. Because $\KK_t$ is computed using a numerical estimate of the inverse, the standard $\VV_t^t$ update equation (which uses $\KK_t$) will cause these elements to be close to zero but not precisely zero, and they may even be slightly negative on the diagonal. This will cause serious problems when the Kalman filter output is passed on to the EM algorithm. Thus after $\VV_t^t$ is computed using the normal Kalman update equation, we will want to explicitly zero out the $k$ rows and columns in the filter. + +When $\GG_t$ has zero rows, then we might also have similar numerical errors in $\JJ$ in the Kalman smoother. The $\JJ$ equation is +\begin{equation}\label{eq:Jt.2} +\begin{split} +\JJ_t &= \VV_{t-1}^{t-1}\BB_t^\top(\VV_t^{t-1})^{-1}\\ +&\text{where }\VV_t^{t-1} = \BB_t \VV_{t-1}^{t-1} \BB_t^\top + \GG_t\QQ_t\GG_t^\top +\end{split} +\end{equation} +If there are zeros on the diagonals of ($\LAM$ and/or $\BB_t$) and zero rows in $\GG_t$ and these zeros line up, then if the $\BB_t^{(0)}$ and $\BB_T^{(1)}$ elements in $\BB_t$ are blocks\footnote{This means the following. Let the rows where the diagonal elements in $\QQ$ equal zero be denoted $i$ and the the rows where there are non-zero diagonals be denoted $j$. The $\BB_t^{(0)}$ elements are the $\BB_t$ elements where both row and column are in $i$. The $\BB_t^{(1)}$ elements are the $\BB$ elements where both row and column are in $j$. If the $\BB_t^{(0)}$ and $\BB_t^{(1)}$ elements in $\BB$ are blocks, this means all the $\BB_t(i,j)$ are 0; no deterministic components interact with the stochastic components.}, there will be zeros on the diagonal of $\VV_t^t$. Thus there will be zeros on the diagonal of $\VV_t^{t-1}$ and it cannot be inverted. In this case, the corresponding elements of $\VV_t^T$ need to be zero since what's happening is that those elements are deterministic and thus have 0 variance. + +We want to catch these zero variances in $\VV_t^{t-1}$ so that we can take the inverse. Note that this can only happen when there are zeros on the diagonal of $\GG_t\QQ_t\GG_t^\top$ since $\BB_t\VV_{t-1}^{t-1} \BB_t^\top$ can never be negative on the diagonal since $\BB_t\BB_t^\top$ must be positive-definite and so is $\VV_{t-1}^{t-1}$. The basic idea is the same as above. We replace $(\VV_t^{t-1})^{-1}$ with: +\begin{equation} +(\OMG_{Vt}^+)^\top\big(\OMG_{Vt}^+(\VV_t^{t-1})(\OMG_{Vt}^+)^\top\big)^{-1}\OMG_{Vt}^+ +\end{equation} +where $\OMG_{Vt}^+$ is a matrix that removes all the positive $\VV_t^{t-1}$ rows analogous to $\OMG_t^{(1)}$. + +\subsection{Modifications due to fixed initial states} +When the initial state of $\xx$ is fixed, then it is a bit like $\LAM=0$ although actually $\LAM$ does not appear in the model and $\xixi$ has a different interpretation. + +When the initial state of $\xx$ is treated as stochastic, then if $t_0=0$, $\xixi$ is the expected value of $\xx_0$ conditioned on no data. In the Kalman filter this means $\xx_0^0=\xixi$ and $\VV_0^0=\LAM$; in words, the expected value of $\xx_0$ conditioned on $\yy_0$ is $\xixi$ and the variance of $\xx_0^0$ conditioned on $\yy_0$ is $\LAM$. When $t_0=1$, then $\xixi$ is the expected value of $\xx_1$ conditioned on no data. In the Kalman filter this means $\xx_1^0=\xixi$ and $\VV_1^0=\LAM$. Thus where $\xixi$ and $\LAM$ appear in the Kalman filter equations is different depending on $t_0$; the $\xx_t^t$ and $\VV_t^{t}$ initial condition versus the $\xx_t^{t-1}$ and $\VV_t^{t-1}$ initial condition. + +When some or all of the $\xx_{t_0}$ are fixed, denoted the $\II_\lambda^{(0)}\xx_{t_0}$, the fixed values are not a random variables. While technically speaking, the expected value of a fixed value does not exist, we can think of it as a random variable with a probability density function with all the weight on the fixed value. Thus $\II_\lambda^{(0)}\E[\xx_{t_0}]=\xixi$ regardless of the data. The data have no information for $\II_\lambda^{(0)}\xx_{t_0}$ since we fix $\II_\lambda^{(0)}\xx_{t_0}$ at $\II_\lambda^{(0)}\xixi$. If $t_0=0$, we initialize the Kalman filter as usual with $\xx_0^0=\xixi$ and $\VV_0^0=\FF\LAM\FF^\top$, where the fixed $\xx_{t_0}$ rows correspond to the zero row/columns in $\FF\LAM\FF^\top$. The Kalman filter will return the correct expectations even when some of the diagonals of $\HH\RR\HH^\top$ or $\GG\QQ\GG^\top$ are 0---with the constraint that we have no purely deterministic elements in the model (meaning there are no errors terms from either $\RR$ or $\QQ$). + +When $t_0=1$, $\II_\lambda^{(0)}\xx_1^0$ and $\II_l^{(0)}\xx_1^1=\xixi$ regardless of the data and $\VV_1^0=\FF\LAM\FF^\top$ and $\VV_1^1=\FF\LAM\FF^\top$, where the fixed rows of $\xx_1$ correspond with the 0 row/columns in $\FF\LAM\FF^\top$. We also set $\II_\lambda^{(0)}\KK_1$, meaning the rows of $\xx_1$ that are fixed, to all zero because $\KK_1$ is the information in $\yy_1$ regarding $\xx_1$ and there is no information in the data regarding the values of $\xx_1$ that are fixed to equal $\II_\lambda^{(0)}\xixi$. + +With $\VV_1^1$, $\xx_1^1$ and $\KK_1$ set to their correct initial values, the normal Kalman filter equations will work fine. However it is possible for the data at $t=1$ to be inconsistent with the model if the rows of $\yy_1$ corresponding to any zero row/columns in $\ZZ_1\FF\LAM\FF^\top\ZZ_1^\top+\HH_1\RR_1\HH_1^\top$ are not equal to $\ZZ_1\xixi + \aa_1$. Here is a trivial example, let the model be $x_t=x_{t-1}+w_t$, $y_t=x_t$, $x_1=1$. Then if $y_1$ is anything except 1, the model is impossible. Technically, the likelihood of $x_1$ conditioned on $Y_1=y_1$ does not exist since neither $x_1$ nor $y_1$ are realizations of a random variable (since they are fixed), so when the likelihood is computed using the innovations form of the likelihood, the $t=1$ does not appear, at least for those $\yy_1$ corresponding to any zero row/columns in $\ZZ_1\FF\LAM\FF^\top\ZZ_1^\top+\HH_1\RR_1\HH_1^\top$. Thus these internal inconsistencies would neither provoke an error nor cause Inf to be returned for the likelihood. In the MARSS package, the Kalman filter has been modified to return LL=Inf and an error. + +\section{Summary of requirements for degenerate models} +Below are discussed the update equations for the different parameters. Here I summarize the constraints that are scattered throughout these subsections. These requirements are coded into the function MARSSkemcheck() in the MARSS package but some tests must be repeated in the function degen.test(), which tests if any of the $\RR$ or $\QQ$ diagonals can be set to zero if it appears they are going to zero. A model that is allowed when $\RR$ and $\QQ$ are non-zero, might be disallowed if $\RR$ or $\QQ$ diagonals were to be set to zero. degen.test() does this check. + +\begin{itemize} +\item $(\II_m \otimes \II_r^{(0)}\ZZ_t\II_q^{(0)})\DD_{t,b}$, is all zeros. If there is a all zero row in $\HH_t$ and it is linked (through $\ZZ$) to a all zero row in $\GG_t$, then the corresponding $\BB_t$ elements are fixed instead of estimated. Corresponding $\BB$ rows means those rows in $\BB$ where there is a non-zero column in $\ZZ$. We need $\II_r^{(0)}\ZZ_t\II_q^{(0)}\BB_t$ to only specify fixed $\BB_t$ elements, which means $\vec(\II_r^{(0)}\ZZ_t\II_q^{(0)}\BB_t\II_m)$ only specifies fixed values. This in turn leads to the condition above. MARSSkemcheck() +\item $(\II_1 \otimes \II_r^{(0)}\ZZ_t\II_q^{(0)})\DD_{t,u}$ is all zeros; if there is a all zero row in $\HH_t$ and it is linked (through $\ZZ_t$) to a all zero row in $\GG_t$, then the corresponding $\uu_t$ elements are fixed instead of estimated. MARSSkemcheck() +\item $(\II_m \otimes \II_r^{(0)})\DD_{t,z}$, where is all zeros; if $y$ has no observation error, then the corresponding $\ZZ_t$ rows are fixed values. $(\II_m \otimes \II_r^{(0)})$ is a diagonal matrix with 1s for the rows of $\DD_{t,z}$ that correspond to elements of $\ZZ_t$ on the $R=0$ rows. MARSSkemcheck() +\item $(\II_1 \otimes \II_r^{(0)})\DD_{t,a}$ is all zeros; if $y$ has no observation error, then the corresponding $\aa_t$ rows are fixed values. MARSSkemcheck() +\item $(\II_m \otimes \II_q^{(0)})\DD_{t,b}$ is all zeros. This means $\BB^{(0)}$ (the whole row) is fixed. While $\BB^d$ could potentially be estimated potentially, my derivation assumes it is not. MARSSkemcheck() +\item $(\II_1 \otimes \II_{q,t>m}^{is})\DD_{t,u}$ is all zeros. This means $\uu^{is}$ is fixed. Here $is$ is defined as those rows that are indirectly stochastic at time $m$, where $m$ is the dimension of $\BB$; it can take up to $m$ steps for the $is$ rows to be connected to the $s$ rows through $\BB$. MARSSkemcheck() +\item If $\uu^{(0)}$ or $\xixi^{(0)}$ are being estimated, then the adjacency matrices defined by $\BB_t \neq 0$ are not time-varying. This means that the locations of the 0s in $\BB_t$ are not changing over time. $\BB_t$ however may be time-varying. MARSSkemcheck() +\item $\II_q^{(0)}$ and $\II_r^{(0)}$ are time invariant (an imposed assumption). This means that the location of the 0 rows in $\GG_t$ and $\HH_t$ (and thus in $\ww_t$ and $\vv_t$) are not changing through time. It would be easy enough to allow $\II_r^{(0)}$ to be time varying, but to make my derivation easier, I assume it is time constant. +\item $\ZZ_t^{(0)}$ in $\E[\YY_t^{(0)}]=\ZZ_t^{(0)}\E[\XX_t]+\aa_t^{(0)}$ does not imply an over-determined system of equations. Because the $\vv_t$ rows are zero for the ${(0)}$ rows of $\yy$, it must be possible for this equality to hold. This means that $\ZZ_t^{(0)}$ cannot specify an over-determined system although an underdetermined system is ok. The check is in MARSSkfss() since the fully-specified $x$ need to be known for the MARSSkfss() filter. If $\ZZ_t^{(0)}$ is square, its inverse is attempted and if that throws and error an error is reported (re over-constrained model). The function to find the fully determined $\xx$ is fully.det.x() in the utility functions. +\item The state process cannot be over-determined via constraints imposed from the deterministic observation process ($\RR=0$) and the deterministic state process ($\QQ=0$). If this is the case the Kalman gain equation (in the Kalman filter) will throw an error. Checked in MARSS() via call to MARSSkf() before fitting call; degen.test(), in MARSSkem() will also test via MARSSkf call if some R or Q are attempted to be set to 0. If B or Z changes during kem or optim iterations such that this constraint does not hold, then algorithm will exit with an error message. +\item The location of the 0s in $\BB$ are time-invariant. The $\BB$ can be time-varying but not the location of 0s. Also, I want $\BB$ to be such that once a row becomes indirectly stochastic is stays that way. For example, if $\BB=\bigl[ \begin{smallmatrix} +0&1\\ 1&0 \end{smallmatrix} \bigr]$, then row 2 flips back and forth from being indirectly stochastic to deterministic. +\end{itemize} +The dimension of the identity matrices in the above constraints is given by the subscript on $\II$ except when it is implicit. + +\section{Implementation comments}\label{sec:implementation} +The EM algorithm is a hill-climbing algorithm and like all hill-climbing algorithms it can get stuck on local maxima. There are a number approaches to doing a pre-search of the initial conditions space, but a brute force random Monte Carol search appears to work well \citep{Biernackietal2003}. It is slow, but normally sufficient. However an initial conditions search should be done before reporting final estimates for an analysis. In our papers on the distributional properties of MARSS parameter estimates, we rarely found that an initial conditions search changed the estimates---except in cases where $\ZZ$ and $\BB$ are estimated as unconstrained and as the fraction of missing data in the data set became large. + +The EM algorithm will quickly home in on parameter estimates that are close to the maximum, but once the values are close, the EM algorithm can slow to a crawl. Some researchers start with an EM algorithm to get close to the maximum-likelihood parameters and then switch to a quasi-Newton method for the final search. In many ecological applications, parameter estimates that differ by less than 3 decimal places are for all practical purposes the same. Thus we have not used the quasi-Newton final search. + +Shumway and Stoffer (2006; chapter 6) imply in their discussion of the EM algorithm that both $\xixi$ and $\LAM$ can be estimated, though not simultaneously. Harvey (1989), in contrast, discusses that there are only two allowable cases for the initial conditions: 1) fixed but unknown and 2) a initial condition set as a prior. In case 1, $\xixi$ is $\xx_0$ (or $\xx_1$) and is then estimated as a parameter; $\LAM$ is held fixed at 0. In case 2, $\xixi$ and $\LAM$ specify the mean and variance of $\XX_0$ (or $\XX_1$) respectively. Neither are estimated; instead, they are specified as part of the model. + +As mentioned in the introduction, misspecification of the prior on $\xx_0$ can have catastrophic and undetectable effects on your parameter estimates. For many MARSS models, you will never see this problem. However, if you are fitting models that imply a correlation structure between the hidden states, i.e., the variance-covariance matrix of the $\XX$'s is not diagonal, then your prior can definitely create problems if it does not have the same correlation structure as that implied by your MLE model. A common default is to use a prior with a diagonal variance-covariance matrix. This can lead to serious problems if the implied variance-covariance of the $\XX$'s is not diagonal. A diffuse prior does not get around this since it has a correlation structure also even if it has infinite variance. + +One way you can detect that you have a problem is to start the EM algorithm at the outputs from a Newton-esque algorithm. If the EM estimates diverge and the likelihood drops, you have a problem. Here are a few suggestions for getting around the problem: +\begin{itemize} + \item Treat $\xx_0$ as an estimated parameter and set $\VV_0$=0. If the model is not stable going backwards in time, then treat $\xx_1$ as the estimated parameter; this will allow the data to constrain the $\xx_1$ estimate (since there is no data at $t=0$, $\xx_0$ has no data to constrain it). + \item Try a diffuse prior, but first read the info in the KFAS R package about diffuse priors since MARSS uses the KFAS implementation. In particular, note that you will still be imposing an information on the correlation structure using a diffuse prior; whatever $\VV_0$ you use is telling the algorithm what correlation structure to use. If there is a mismatch between the correlation structure in the prior and the correlation structure implied by the MLE model, you will not be escaping the prior problem. But sometimes you will know your implied correlation structure. For example, you may know that the $\xx$'s are independent or you may be able to solve for the stationary distribution a priori if your stationary distribution is not a function of the parameters you are trying to estimate. Other times you are estimating a parameter that determines the correlation structure (like $\BB$) and you will not know a priori what the correlation structure is. +\end{itemize} + +In some cases, the update equation for one parameter needs other parameters. Technically, the Kalman filter/smoother should be run between each parameter update, however following \citet{GhahramaniHinton1996} the default MARSS algorithm skips this step (unless the user sets \verb@control$safe=TRUE@) and each updated parameter is used for subsequent update equations. If you see warnings that the log-likelihood drops, then try setting \verb@control$safe=TRUE@. This will increase computation time greatly. + +\section{MARSS R package} +R code for the Kalman filter, Kalman smoother, and EM algorithm is provided as a separate R package, MARSS, available on CRAN (https://CRAN.R-project.org/package=MARSS). MARSS was developed by Elizabeth Holmes, Eric Ward and Kellie Wills and provides maximum-likelihood estimation and model-selection for both unconstrained and constrained MARSS models. The package contains a detailed user guide which shows various applications. In addition to model fitting via the EM algorithm, the package provides algorithms for bootstrapping, confidence intervals, auxiliary residuals, and model selection criteria. + +\bibliography{./EMDerivation} +\bibliographystyle{apalike} + +\end{document} diff --git a/vignettes/Learning_MARSS.Rmd b/vignettes/Learning_MARSS.Rmd index dc57a4d..286fca8 100644 --- a/vignettes/Learning_MARSS.Rmd +++ b/vignettes/Learning_MARSS.Rmd @@ -16,7 +16,7 @@ The MARSS R package: is part of the [Applied Time Series Analysis](https://atsa-es.github.io/) for Environmental Science suite of software and educational material for time series analysis. See the GitHub repository for the [MARSS source -code](https://github.com/atsa-es/MARSS). +code](https://github.com/atsa-es/MARSS). For fast fitting to large datasets or DFA models, see our companion package, [marssTMB](https://atsa-es.github.io/marssTMB/).

diff --git a/vignettes/Learning_MARSS.html b/vignettes/Learning_MARSS.html new file mode 100644 index 0000000..27b3a17 --- /dev/null +++ b/vignettes/Learning_MARSS.html @@ -0,0 +1,357 @@ + + + + + + + + + + + + + + +Learning MARSS + + + + + + + + + + + + + + + + + + + + + + + +

Learning MARSS

+ + + +

The MARSS R package: https://cran.r-project.org/package=MARSS is part of the +Applied Time Series Analysis +for Environmental Science suite of software and educational material for +time series analysis. See the GitHub repository for the MARSS source code. For fast +fitting to large datasets or DFA models, see our companion package, marssTMB.

+
+

Documentation

+ +
+
+

Tutorials

+

+ +
+

For Statisticians

+

For those who work on MARSS models. A good place to start might be +the chapter at the end of the User Guide on the comparison of KFAS and +MARSS outputs and terminology. Comparing the terminology between the two +packages should help understanding the MARSS output. Similarly the +chapter on StructTS will help understand the difference in notation and +terminology.

+

MARSS is designed to provide access to every possible conditional +expectation of \(\mathbf{X}\) and \(\mathbf{Y}\). “Every possible” means all +the temporal conditionings (time 1 to \(t-1\), \(t\) or \(T\)) and all the possible standardizations +(none, marginal, Cholesky). It will return the standard errors for all +of these combinations. The Residuals subsection in the KFAS chapter will +compare the residual options in KFAS to the MARSS residuals. The KFAS +terminology may be more familiar and a table in that chapter shows you +what terminology is associated with what conditional expectation. Note, +KFAS and MARSS give the same values. The difference is notation and +terminology.

+

The EM Derivation paper goes into the nitty-gritty of the underlying +EM algorithm. The Residuals paper goes through the Residuals algorithms. +All the help files for the functions that implement algorithms have the +details for statisticians/developers. My notes on computing the Fisher +Information matrix for MARSS are in a series of notes: Notes +on computing the Fisher Information matrix for MARSS models +I-IV.

+
+
+
+

CITATION

+

If you use MARSS results in publications, please cite the primary +citation:

+

Holmes, E. E., Ward, E. J. and Wills, K. (2012) MARSS: Multivariate +Autoregressive State-space Models for Analyzing Time-series Data. The R +Journal. 4(1):11-19

+

You can also cite the package and user guide:

+

Elizabeth E. Holmes, Eric J. Ward, Mark D. Scheuerell and Kellie +Wills (2023). MARSS: Multivariate Autoregressive State-Space Modeling. R +package version 3.11.7.

+

Holmes, E. E., M. D. Scheuerell, and E. J. Ward (“, year,”) Analysis +of multivariate time-series using the MARSS package. Version “, +meta$Version,”. NOAA Fisheries, Northwest Fisheries Science Center, 2725 +Montlake Blvd E., Seattle, WA 98112, DOI: 10.5281/zenodo.5781847

+

Type citation("MARSS") at the command line to get the +most up to data citations.

+
+

PUBLICATIONS

+

To see our publications using MARSS models, see the Applied Time Series Analysis +website.

+
+
+

NOAA Disclaimer

+

The MARSS R package is a scientific product and is not official +communication of the National Oceanic and Atmospheric Administration, or +the United States Department of Commerce. All NOAA code is provided on +an ‘as is’ basis and the user assumes responsibility for its use. Any +claims against the Department of Commerce or Department of Commerce +bureaus stemming from the use of this GitHub project will be governed by +all applicable Federal law. Any reference to specific commercial +products, processes, or services by service mark, trademark, +manufacturer, or otherwise, does not constitute or imply their +endorsement, recommendation or favoring by the Department of Commerce. +The Department of Commerce seal and logo, or the seal and logo of a DOC +bureau, shall not be used in any manner to imply endorsement of any +commercial product or activity by DOC or the United States +Government.

+
+
+ + + + + + + + + + + diff --git a/vignettes/Quick_Start.R b/vignettes/Quick_Start.R new file mode 100644 index 0000000..52c9624 --- /dev/null +++ b/vignettes/Quick_Start.R @@ -0,0 +1,63 @@ +## ----------------------------------------------------------------------------- +B1 <- matrix(list("b",0,0,"b"),2,2) +U1 <- matrix(0,2,1) +Q1 <- matrix(c("q11","q12","q12","q22"),2,2) +Z1 <- matrix(c(1,0,1,1,1,0),3,2) +A1 <- matrix(list("a1",0,0),3,1) +R1 <- matrix(list("r11",0,0,0,"r",0,0,0,"r"),3,3) +pi1 <- matrix(0,2,1); V1=diag(1,2) +model.list <- list(B=B1,U=U1,Q=Q1,Z=Z1,A=A1,R=R1,x0=pi1,V0=V1,tinitx=0) + +## ----eval=FALSE--------------------------------------------------------------- +# fit <- MARSS(y, model=model.list) + +## ----------------------------------------------------------------------------- +library(MARSS) +set.seed(1234) +x <- rbind(arima.sim(n=50,list(ar=0.95), sd=0.4), + arima.sim(n=50,list(ar=0.95), sd=.02)) +y <- Z1 %*% x + matrix(rnorm(3*50,0,0.1), 3, 50) +fit <- MARSS(y, model=model.list, silent=TRUE) +tidy(fit) + +## ----eval=FALSE--------------------------------------------------------------- +# fit1 <- MARSS(y, model=model.list) +# fit2 <- MARSS(y, model=model.list, method="BFGS") +# fit3 <- MARSS(y, model=model.list, method="TMB") + +## ----results="hide"----------------------------------------------------------- +fit1 <- MARSS(y, model=model.list, control = list(maxit=15)) +fit2 <- MARSS(y, model=model.list, method="BFGS", inits = fit1) + +## ----------------------------------------------------------------------------- +temp <- matrix(rnorm(50, seq(0,1,1/50), 0.1),nrow=1) +C1 <- matrix(c("temp1","temp2"),2,1) +model.list$C <- C1 +model.list$c <- temp + +## ----results="hide"----------------------------------------------------------- +fit <- MARSS(y, model=model.list, method="BFGS") + +## ----------------------------------------------------------------------------- +yts <- ts(t(y), frequency = 12) # requires time down the rows +fcov <- forecast::fourier(yts,1) |> t() + +## ----------------------------------------------------------------------------- +yts <- ts(t(y), frequency = 12) # monthly data +mcov <- forecast::seasonaldummy(yts) |> t() # month factor + +## ----------------------------------------------------------------------------- +B1 <- matrix(list("-0.1+1*b",0,0,"0.1+1*b"),2,2) +Q1 <- matrix(list(1,0,0,1),2,2) +Z1 <- matrix(list("1*z1+-1*z2",0,"z2","2*z1","z1",0),3,2) +model.list <- list(B=B1,U=U1,Q=Q1,Z=Z1,A=A1,R=R1,x0=pi1,V0=V1,tinitx=0) + +## ----------------------------------------------------------------------------- +fit <- MARSS(y, model=model.list, silent = TRUE) + +## ----------------------------------------------------------------------------- +TT <- dim(y)[2] +B1 <- array(list(),dim=c(2,2,TT)) +B1[,,1:20] <- matrix(list("b",0,0,"b_1"),2,2) +B1[,,21:TT] <- matrix(list("b",0,0,"b_2"),2,2) + diff --git a/vignettes/Quick_Start.html b/vignettes/Quick_Start.html new file mode 100644 index 0000000..7ecf554 --- /dev/null +++ b/vignettes/Quick_Start.html @@ -0,0 +1,2072 @@ + + + + + + + + + + + + + +Quick Start Guide + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+
+
+
+
+ +
+ + + + + + + +
+

1 tldr;

+

Put data (y) in a \(n \times +T\) matrix or ts/mts object.

+

Specify each of the parameters in a list for the model +argument.

+

Fit with

+
fit <- MARSS(y, model=list(...), method=c("kem", "BFGS", "TMB"))
+

Choose one method from c("kem", "BFGS", "TMB").

+

Specification of a properly constrained model with a unique +solution is the responsibility of the user because the {MARSS} package +has no way to tell if you have specified an insufficiently constrained +model.

+
+
+

2 The MARSS model

+

The {MARSS} package fits multivariate autoregressive state-space +(MARSS) models of the form: \[\begin{equation} +\begin{gathered} +\boldsymbol{x}_t = \mbox{$\mathbf B$}_t\boldsymbol{x}_{t-1} + +\mbox{$\mathbf U$}_t + \mbox{$\mathbf C$}_t\mbox{$\mathbf c$}_t + +\mbox{$\mathbf G$}_t\boldsymbol{w}_t, \text{ where } \boldsymbol{W}_t +\sim \,\textup{\textrm{MVN}}(0,\mbox{$\mathbf Q$}_t)\\ +\boldsymbol{y}_t = \mbox{$\mathbf Z$}_t\boldsymbol{x}_t + \mbox{$\mathbf +A$}_t + \mbox{$\mathbf D$}_t\mbox{$\mathbf d$}_t + \mbox{$\mathbf +H$}_t\boldsymbol{v}_t, \text{ where } \boldsymbol{V}_t \sim +\,\textup{\textrm{MVN}}(0,\mbox{$\mathbf R$}_t)\\ +\boldsymbol{X}_1 \sim +\,\textup{\textrm{MVN}}(\boldsymbol{\xi},\boldsymbol{\Lambda}) \text{ or +} \boldsymbol{X}_0 \sim +\,\textup{\textrm{MVN}}(\boldsymbol{\xi},\boldsymbol{\Lambda}) +\end{gathered} +\end{equation}\] \(\mbox{$\mathbf +c$}\) and \(\mbox{$\mathbf d$}\) +are inputs (aka, exogenous variables or covariates or indicator +variables) and must have no missing values. The \(\mbox{$\mathbf R$}\), \(\mbox{$\mathbf Q$}\) and \(\boldsymbol{\Lambda}\) variances can can +have zeros on the diagonal to specify partially deterministic systems. +This allows you to write MAR(p) models in MARSS form for example. See +the User Guide. The {MARSS} package is designed to handle linear +constraints within the parameter matrices. Linear constraint means you +can write the elements of the matrix as a linear equation of all the +other elements. See section below on linear constraints.

+

Example: a mean-reverting random walk model with three observation +time series: \[\begin{gather} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t += \begin{bmatrix}b&0\\ 0&b\end{bmatrix} +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_{t-1} ++ \begin{bmatrix}w_1\\ w_2\end{bmatrix}_t, \quad +\begin{bmatrix}w_1\\ w_2\end{bmatrix}_t \sim +\,\textup{\textrm{MVN}}\begin{pmatrix}\begin{bmatrix}0\\0\end{bmatrix},\begin{bmatrix}q_{11}&q_{12}\\ +q_{12}&q_{22}\end{bmatrix} \end{pmatrix} +\\ +\begin{bmatrix}y_1\\y_2\\y_3\end{bmatrix}_t += \begin{bmatrix}1&1\\ 0&1\\ 1&0\end{bmatrix} +\begin{bmatrix}x_1\\x_2\end{bmatrix}_t ++ \begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t,\quad +\begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t \sim +\,\textup{\textrm{MVN}}\begin{pmatrix}\begin{bmatrix}a_1\\ 0\\ +0\end{bmatrix}, +\begin{bmatrix}r_{11}&0&0\\ 0&r&0\\ +0&0&r\end{bmatrix} \end{pmatrix} +\\ +\begin{bmatrix}x_1\\ x_2\end{bmatrix}_0 \sim +\,\textup{\textrm{MVN}}\begin{pmatrix}\begin{bmatrix}0\\ +0\end{bmatrix},\begin{bmatrix}1&0\\ 0&1\end{bmatrix} +\end{pmatrix} +\end{gather}\]

+
+

2.1 Model +specification

+

Model specification is via a list with the structure of each of the +model parameters: \(\mbox{$\mathbf +B$}\), \(\mbox{$\mathbf U$}\), +\(\mbox{$\mathbf C$}\), \(\mbox{$\mathbf Q$}\), \(\mbox{$\mathbf Z$}\), \(\mbox{$\mathbf A$}\), \(\mbox{$\mathbf D$}\), \(\mbox{$\mathbf R$}\), \(\boldsymbol{\xi}\), and\(\boldsymbol{\Lambda}\). There is a +one-to-one correspondence between the model in and the math version of +the model. The model written in matrix form is translated into +equivalent matrices (or arrays if time-varying) in code. Matrices that +combine fixed and estimated values are specified using a list matrix +with numerical values for fixed values and character names for the +estimated values.

+

For the MARSS model above, this would be:

+
B1 <- matrix(list("b",0,0,"b"),2,2)
+U1 <- matrix(0,2,1)
+Q1 <- matrix(c("q11","q12","q12","q22"),2,2)
+Z1 <- matrix(c(1,0,1,1,1,0),3,2)
+A1 <- matrix(list("a1",0,0),3,1)
+R1 <- matrix(list("r11",0,0,0,"r",0,0,0,"r"),3,3)
+pi1 <- matrix(0,2,1); V1=diag(1,2)
+model.list <- list(B=B1,U=U1,Q=Q1,Z=Z1,A=A1,R=R1,x0=pi1,V0=V1,tinitx=0)
+

The tinitx element tells MARSS whether the initial state +for \(x\) is at \(t=1\) (tinitx=1) or \(t=0\) (tinitx=0).

+

MARSS has a number of text shortcuts for common parameter forms, such +as "diagonal and unequal"; see below for the possible +shortcuts.

+
+
+
+

3 Data and fitting

+
+

3.1 Data

+

The data must be entered as a \(n \times +T\) matrix, or a ts() (or mts) object or vector +(which will be converted to a \(n \times +T\) matrix).

+
+
+

3.2 Fit call

+

The call to fit the model is.

+
fit <- MARSS(y, model=model.list)
+

See ?MARSS for all other arguments. The common ones are +method to change the fitting method from default of EM +(slow). See below. control is used to pass in a list to +control fitting, e.g. control=list(maxit=1000) to increase +maximum iterations if the fit does not converge.

+

Example with simulated data:

+
library(MARSS)
+set.seed(1234)
+x <- rbind(arima.sim(n=50,list(ar=0.95), sd=0.4), 
+           arima.sim(n=50,list(ar=0.95), sd=.02))
+y <- Z1 %*% x + matrix(rnorm(3*50,0,0.1), 3, 50)
+fit <- MARSS(y, model=model.list, silent=TRUE)
+tidy(fit)
+
##    term     estimate    std.error      conf.low      conf.up
+## 1  A.a1 0.0184598413 0.0269628326 -0.0343863395 0.0713060221
+## 2 R.r11 0.0188070225 0.0062216241  0.0066128633 0.0310011817
+## 3   R.r 0.0115645650 0.0024433098  0.0067757658 0.0163533641
+## 4   B.b 0.8605716318 0.0634069752  0.7362962441 0.9848470195
+## 5 Q.q11 0.1301323970 0.0288070155  0.0736716842 0.1865931098
+## 6 Q.q12 0.0020987299 0.0029632765 -0.0037091853 0.0079066452
+## 7 Q.q22 0.0001353807 0.0003058603 -0.0004640944 0.0007348558
+
+
+

3.3 Different fitting +methods

+

The EM algorithm in the {MARSS} package is in R and on top of that EM +algorithms are famously slow. You can try method="BFGS" and +see if that is faster. For some models, it will be much faster and for +others slower. The companion package {marssTMB} allows you to +fit these models with TMB and will be the fastest, often much faster. +Definitely if you are doing Dynamic Factor Analysis or working with +large data sets, you will want to use {marssTMB}.

+
fit1 <- MARSS(y, model=model.list)
+fit2 <- MARSS(y, model=model.list, method="BFGS")
+fit3 <- MARSS(y, model=model.list, method="TMB")
+

method="BFGS" and method="TMB" are both +using quasi-Newton methods to optimize and these can be sensitive to +initial conditions. You can run EM a few iterations use that as initial +conditions for BFGS or TMB, and this will guard against poor initial +conditions issues.

+
fit1 <- MARSS(y, model=model.list, control = list(maxit=15))
+fit2 <- MARSS(y, model=model.list, method="BFGS", inits = fit1)
+
+
+

3.4 Defaults for +model list

+

Form of the model list is list(B=..., U=...) etc.

+
+

3.4.1 +form="marxss"

+

For form="marxss" (the default), matrix names in the +model list must be B, U, C, +c, Q, Z, A, +D, d, R, x0 (\(\boldsymbol{\xi}\)), and V0 +(\(\boldsymbol{\Lambda}\)), just like +in the MARSS equation. There are defaults each parameter and you can +leave off matrix names and the defaults will be used. Type +?MARSS.marxss additional information.

+
    +
  • B="identity" \(m \times +m\) identity matrix
    • +
  • U="unequal" Each element in the \(m \times 1\) matrix \(\mbox{$\mathbf U$}\) is estimated and +allowed to be different.
    • +
  • Q="diagonal and unequal" \(\mbox{$\mathbf Q$}\) is a diagonal matrix +and each element on the diagonal is allowed to be different.
    • +
  • Z="identity" \(n \times +n\) identity matrix thus in the default model each \(y\) is associated with one \(x\).
    • +
  • A="scaling" If \(\mbox{$\mathbf Z$}\) is identity, \(\mbox{$\mathbf A$}\) is zero. Otherwise, +the first \(y\) associated with a \(x\) is set to 0 and the rest are +estimated.
    • +
  • R="diagonal and equal" \(\mbox{$\mathbf R$}\) is a diagonal matrix +and each element on the diagonal is the same.
    • +
  • x0="unequal" Each element in the \(m \times 1\) matrix \(\boldsymbol{\xi}\) is estimated and allowed +to be different.
    • +
  • V0="zero" \(\boldsymbol{\Lambda}\) is set to zero thus +\(\boldsymbol{x}_0\) is treated as an +estimated parameter.
    • +
  • tinitx=0 The initial condition for \(\boldsymbol{x}\) is set at \(t=0\).
    • +
+
+
+

3.4.2 +form="dfa"

+

Special form for fitting DFA models. Pass in form="dfa" +to the MARSS() call. Typically only these would be in the +model list:

+
    +
  • m=1 Number of factors.
    • +
  • R="diagonal and equal" \(\mbox{$\mathbf R$}\) is a diagonal matrix +and each element on the diagonal is the same.
    • +
  • d="zero" If there are \(p\) covariates, pass in as a \(p \times T\) matrix.
    • +
  • D="unconstrained" if covariates passed in.
    • +
+

Defaults.

+
    +
  • Z A special unconstrained matrix with the upper +triangle (without the diagonal) set to zero.
    • +
  • Q="identity" \(\mbox{$\mathbf +Q$}\) is a diagonal matrix and each element on the diagonal is +allowed to be different.
    • +
  • x0="zero" Each element in the \(m \times 1\) matrix \(\boldsymbol{\xi}\) is estimated and allowed +to be different.
    • +
  • V0=diag(5,n) \(\boldsymbol{\Lambda}\) is set to a diagonal +matrix with 5 on the diagonal.
    • +
  • tinitx=0 The initial condition for \(\boldsymbol{x}\) is set at \(t=0\).
    • +
  • B="identity" \(m \times +m\) identity matrix
    • +
  • U="zero"
    • +
  • A="zero"
    • +
+
+
+
+
+

4 Showing the model fits +and getting the parameters

+

There are plot.marssMLE(), +autoplot.marssMLE(), print, +summary, coef, fitted, +residuals and predict functions for marssMLE +objects. ?print.MARSS will show you how to get standard +output from your fitted model objects and where that output is stored in +the marssMLE object. See coef.marssMLE() for the different +formats for displaying the estimated parameters. To see plots of your +states and fits plus diagnostic plots, use plot(fit) or, +better, ggplot2::autoplot(fit). For summaries of the +residuals (model and state), use the residuals function. +See ?residuals.marssMLE. To produce predictions and +forecasts from a MARSS model, see ?predict.marssMLE.

+
+
+

5 Tips and +Troubleshooting

+
+

5.1 Tips

+

Use ggplot2::autoplot(fit) (or plot(fit)) +to see a series of standard plots and diagnostics for your model. Use +tidy(fit) for parameter estimates or +coef(fit). Use fitted(fit) for model (\(\boldsymbol{y}\)) estimates and +tsSmooth(fit) for states (\(\boldsymbol{x}\)) estimates. You can also +use fit$states for the states.

+

Let’s say you specified your model with some text short-cuts, like +Q="unconstrained", but you want the list matrix for for a +next step. a <- summary(fit$model) returns that list +(invisibly). Because the model argument of MARSS() will +understand a list of list matrices, you can pass in model=a +to specify the model. +MARSSkfas(fit, return.kfas.model=TRUE) will return your +model in {KFAS} format (class SSModel), thus you can use all the +functions available in the {KFAS} package on your model.

+
+
+

5.2 Troubleshooting

+

Try MARSSinfo() if you get errors you don’t understand +or fitting is taking a long time to converge. When fitting a model with +MARSS(), pass in silent=2 to see what +MARSS() is doing. This puts it in verbose mode. Use +fit=FALSE to set up a model without fitting. Let’s say you +do fit <- MARSS(..., fit=FALSE). Now you can do +summary(fit$model) to see what MARSS() thinks +you are trying to fit.

+

You can also try toLatex(fit$model) to make a LaTeX file +and pdf version of your model (saved in the working directory). This +loads the {Hmisc} package (and all its dependencies) and requires that +you are able to process LaTeX files.

+
+
+
+

6 More information and +tutorials

+

Many example analyses can be found in the MARSS User Guide (pdf). +In addition, recorded lectures and more examples on fitting multivariate +models can be found at our course website and in the ATSA +course eBook html.

+

The MARSS User Guide starts with some tutorials on MARSS models and +walks through many examples showing how to write multivariate +time-series models in MARSS form. The User Guide also has vignettes: how +to write AR(p) models in state-space form, dynamic linear models +(regression models where the regression parameters are AR(p)), +multivariate regression models with regression parameters that are +time-varying and enter the non-AR part of your model or the AR part, +detecting breakpoints using state-space models, and dynamic factor +analysis. All of these can be written in MARSS form. It also has a +series of vignettes on analysis of multivariate biological data.

+

Background on the algorithms used in the {MARSS} package is included +in the User Guide.

+
+
+

7 Shortcuts and all +allowed model structures

+

All parameters except x0 and V0 may be +time-varying. If time-varying, then text shortcuts cannot be used. Enter +as an array with the 3rd dimension being time. Time dimension must be 1 +or equal to the number of time-steps in the data.

+

The model list elements can have the following values:

+
+

7.1 Z

+

Defaults to "identity". Can be a text string, +"identity", "unconstrained", +"diagonal and unequal", "diagonal and equal", +"equalvarcov", or "onestate", or a length +\(n\) vector of factors specifying +which of the \(m\) hidden state time +series correspond to which of the n observation time series. May be +specified as a \(n \times m\) list +matrix for general specification of both fixed and shared elements +within the matrix. May also be specified as a numeric \(n \times m\) matrix to use a custom fixed +\(\mbox{$\mathbf Z$}\). +"onestate" gives a \(n \times +1\) matrix of 1s. The text shortcuts all specify \(n \times n\) matrices.

+
+
+

7.2 B

+

Defaults to "identity". Can be a text string, +"identity", "unconstrained", +"diagonal and unequal", "diagonal and equal", +"equalvarcov", "zero". Can also be specified +as a list matrix for general specification of both fixed and shared +elements within the matrix. May also be specified as a numeric \(m \times m\) matrix to use custom fixed +\(\mbox{$\mathbf B$}\), but in this +case all the eigenvalues of \(\mbox{$\mathbf +B$}\) must fall in the unit circle.

+
+
+

7.3 U and +x0

+

Defaults to "unequal". Can be a text string, +"unconstrained", "equal", +"unequal" or "zero". May be specified as a +\(m \times 1\) list matrix for general +specification of both fixed and shared elements within the matrix. May +also be specified as a numeric \(m \times +1\) matrix to use a custom fixed \(\mbox{$\mathbf U$}\) or \(\boldsymbol{x}_0\).

+
+
+

7.4 A

+

Defaults to "scaling". Can be a text string, +"scaling" ,"unconstrained", +"equal", “unequal” or “zero”. May be specified as a n x 1 +list matrix for general specification of both fixed and shared elements +within the matrix. May also be specified as a numeric \(n \times 1\) matrix to use a custom fixed +\(\mbox{$\mathbf A$}\). Care must be +taken so that the model is not under-constrained and unsolvable model. +The default, "scaling", only applies to \(\mbox{$\mathbf Z$}\) matrices that are +design matrices (only 1s and 0s and all rows sum to 1). When a column in +\(\mbox{$\mathbf Z$}\) has multiple 1s, +the first row in the \(\mbox{$\mathbf +A$}\) matrix associated with those \(\mbox{$\mathbf Z$}\) rows is 0 and the +other associated \(\mbox{$\mathbf A$}\) +rows have an estimated value. This treats \(\mbox{$\mathbf A$}\) as an intercept where +one intercept for each \(\boldsymbol{x}\) (hidden state) is fixed at +0 and any other intercepts associated with that \(\boldsymbol{x}\) have an estimated +intercept. This ensures a solvable model when \(\mbox{$\mathbf Z$}\) is a design +matrix.

+
+
+

7.5 Q, +R and V0

+

Can be a text string, "identity", +"unconstrained", "diagonal and unequal", +"diagonal and equal", "equalvarcov", “zero”. +May be specified as a list matrix for general specification of both +fixed and shared elements within the matrix. May also be specified as a +numeric matrix to use a custom fixed matrix.

+

V0 defaults to "zero", which means that +\(\boldsymbol{x}_0\) is treated as an +estimated parameter.

+
+
+

7.6 D and +C

+

Defaults to "zero" or if no covariates, defaults to +"unconstrained". Can also be any of the options available +for the variance matrices.

+
+
+

7.7 d and +c

+

Defaults to "zero". Numeric matrix. No missing values +allowed. Must have 1 column or the same number of columns as the data, +The numbers of rows in must match the corresponding \(\mbox{$\mathbf D$}\) or \(\mbox{$\mathbf C$}\) matrix.

+
+
+

7.8 G and +H

+

Defaults to "identity". Can be specified as a numeric +matrix or array for time-varying cases. Size must match the +corresponding \(\mbox{$\mathbf Q$}\) or +\(\mbox{$\mathbf R$}\) matrix.

+
+
+
+

8 Covariates, Linear +constraints and time-varying parameters

+
+

8.1 Covariates

+

Inputs, aka covariates, are in \(\mbox{$\mathbf c$}\) and \(\mbox{$\mathbf d$}\). The are passed in via +the model list and must be a numeric matrix (no missing values). \(\mbox{$\mathbf C$}\) and \(\mbox{$\mathbf D$}\) are the estimated +parameters, aka covariate effects.

+

Let’s say you have temperature data and you want to include a linear +effect of temperature that is different for each \(\boldsymbol{x}\) time series:

+
temp <- matrix(rnorm(50, seq(0,1,1/50), 0.1),nrow=1)
+C1 <- matrix(c("temp1","temp2"),2,1)
+model.list$C <- C1
+model.list$c <- temp
+

Fit as normal:

+
fit <- MARSS(y, model=model.list, method="BFGS")
+

A seasonal effect can be easily included via sine/cosine pairs. The +fourier() function in the {forecast} package simplifies +this. You will need to make your data into a ts/mts object.

+
yts <- ts(t(y), frequency = 12) # requires time down the rows
+fcov <- forecast::fourier(yts,1) |> t()
+
## Registered S3 method overwritten by 'quantmod':
+##   method            from
+##   as.zoo.data.frame zoo
+

If you want a factor effect, then you can use the +seasonaldummy() function in {forecast}

+
yts <- ts(t(y), frequency = 12) # monthly data
+mcov <- forecast::seasonaldummy(yts) |> t() # month factor
+
+
+

8.2 Linear +constraints

+

Your model can have simple linear constraints within all the +parameters except \(\mbox{$\mathbf +Q$}\), \(\mbox{$\mathbf R$}\) +and \(\boldsymbol{\Lambda}\). For +example \(1+2a-3b\) is a linear +constraint. When entering this value for you matrix, you specify this as +"1+2*a+-3*b". NOTE: \(+\)’s join parts so +-3*b to +specify \(-3b\). Anything after +* is a parameter. So 1*1 has a parameter +called "1". Example, let’s change the \(\mbox{$\mathbf B$}\) and \(\mbox{$\mathbf Q$}\) matrices in the +previous model to: \[\begin{equation*} +\mbox{$\mathbf B$}= \begin{bmatrix}b-0.1&0\\ +0&b+0.1\end{bmatrix}\quad +\mbox{$\mathbf Q$}= \begin{bmatrix}1&0\\ 0&1\end{bmatrix}\quad +\mbox{$\mathbf Z$}= \begin{bmatrix}z_1-z_2&2 z_1\\ 0&z_1\\ +z_2&0\end{bmatrix} +\end{equation*}\] \(\mbox{$\mathbf +Q$}\) is fixed because \(\mbox{$\mathbf +Z$}\) is estimated and estimating both creates a statistically +confounded model (both scale the variance of \(\boldsymbol{x}\)).

+

This would be specified as (notice "1*z1+-1*z2" for +z1-z2):

+
B1 <- matrix(list("-0.1+1*b",0,0,"0.1+1*b"),2,2)
+Q1 <- matrix(list(1,0,0,1),2,2)
+Z1 <- matrix(list("1*z1+-1*z2",0,"z2","2*z1","z1",0),3,2)
+model.list <- list(B=B1,U=U1,Q=Q1,Z=Z1,A=A1,R=R1,x0=pi1,V0=V1,tinitx=0)
+

Fit as usual:

+
fit <- MARSS(y, model=model.list, silent = TRUE)
+
+
+

8.3 Time-varying +parameters

+

The default model form allows you to pass in a 3-D array for a +time-varying parameter (\(T\) is the +number of time-steps in your data and is the 3rd dimension in the +array):
+\[\begin{equation} +\begin{gathered} +\boldsymbol{x}_t = \mbox{$\mathbf B$}_t\boldsymbol{x}_{t-1} + +\mbox{$\mathbf U$}_t + \mbox{$\mathbf C$}_t\mbox{$\mathbf c$}_t + +\mbox{$\mathbf G$}_t\boldsymbol{w}_t, \quad +\boldsymbol{W}_t \sim \,\textup{\textrm{MVN}}(0,\mbox{$\mathbf Q$}_t)\\ +\boldsymbol{y}_t = \mbox{$\mathbf Z$}_t\boldsymbol{x}_t + \mbox{$\mathbf +A$}_t + \mbox{$\mathbf D$}_t\mbox{$\mathbf d$}_t + \mbox{$\mathbf +H$}_t\boldsymbol{v}_t, \quad +\boldsymbol{V}_t \sim \,\textup{\textrm{MVN}}(0,\mbox{$\mathbf R$}_t)\\ +\boldsymbol{x}_{t_0} \sim +\,\textup{\textrm{MVN}}(\boldsymbol{\xi},\boldsymbol{\Lambda}) +\end{gathered} +\end{equation}\] Zeros are allowed on the diagonals of \(\mbox{$\mathbf Q$}\), \(\mbox{$\mathbf R$}\) and \(\boldsymbol{\Lambda}\). NOTE(!!), the time +indexing. Make sure you enter your arrays such that the correct +parameter (or input) at time \(t\) +lines up with \(\boldsymbol{x}_t\); +e.g., it is common for state equations to have \(\mbox{$\mathbf B$}_{t-1}\) lined up with +\(\boldsymbol{x}_t\) so you might need +to enter the \(\mbox{$\mathbf B$}\) +array such that your \(\mbox{$\mathbf +B$}_{t-1}\) is entered at Bt[,,t] in your code.

+

The length of the 3rd dimension must be the same as your data. For +example, say in your mean-reverting random walk model (the example on +the first page) you wanted \(\mbox{$\mathbf +B$}(2,2)\) to be one value before \(t=20\) and another value after but \(\mbox{$\mathbf B$}(1,1)\) to be time +constant. You can pass in the following:

+
TT <- dim(y)[2]
+B1 <- array(list(),dim=c(2,2,TT))
+B1[,,1:20] <- matrix(list("b",0,0,"b_1"),2,2)
+B1[,,21:TT] <- matrix(list("b",0,0,"b_2"),2,2)
+

Notice the specification is one-to-one to your \(\mbox{$\mathbf B$}_t\) matrices on +paper.

+
+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + diff --git a/vignettes/Residuals-concordance.tex b/vignettes/Residuals-concordance.tex new file mode 100644 index 0000000..b879b38 --- /dev/null +++ b/vignettes/Residuals-concordance.tex @@ -0,0 +1,2 @@ +\Sconcordance{concordance:Residuals.tex:/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/Residuals.Rnw:% +1 175 1 1 0 628 1} diff --git a/vignettes/Residuals.aux b/vignettes/Residuals.aux new file mode 100644 index 0000000..e6a2a49 --- /dev/null +++ b/vignettes/Residuals.aux @@ -0,0 +1,109 @@ +\relax +\citation{Harveyetal1998} +\citation{HarveyKoopman1992,Harveyetal1998,deJongPenzer1998,CommandeurKoopman2007} +\citation{Harveyetal1998} +\citation{deJong1988} +\@writefile{toc}{\contentsline {section}{\numberline {1}Overview of MARSS residuals}{2}{}\protected@file@percent } +\newlabel{eq:residsMARSS}{{1}{2}} +\newlabel{eq:resids}{{2}{2}} +\newlabel{eq:unconditiondistofVt}{{3}{2}} +\@writefile{toc}{\contentsline {section}{\numberline {2}Distribution of MARSS smoothation residuals}{2}{}\protected@file@percent } +\newlabel{sec:smoothations}{{2}{2}} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.1}Notation and relations}{2}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.1.1}Law of total variance}{3}{}\protected@file@percent } +\newlabel{eq:lawoftotvar}{{4}{3}} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.2}Model residuals conditioned on all the data}{3}{}\protected@file@percent } +\newlabel{eq:vtT}{{7}{3}} +\newlabel{eq:var.vtT}{{8}{3}} +\citation{Holmes2010} +\citation{Holmes2010} +\newlabel{eq:varvvtgeneral}{{9}{4}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.2.1}First term on right hand side of Equation \ref {eq:varvvtgeneral}}{4}{}\protected@file@percent } +\newlabel{eq:first.term.rhs.varvvtgeneral}{{10}{4}} +\newlabel{eq:no.hat.on.V}{{14}{4}} +\newlabel{eq:varianceVt}{{15}{4}} +\newlabel{eq:var.E.vtT}{{16}{4}} +\newlabel{eq:var.E.vtT.R}{{17}{4}} +\newlabel{eq:varvtcondy}{{18}{4}} +\newlabel{eq:var.Vt.yy}{{19}{4}} +\newlabel{eq:conditionalvtfinala}{{20}{5}} +\newlabel{eq:conditionalvtfinal}{{21}{5}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.2.2}Second term on right hand side of Equation \ref {eq:varvvtgeneral}}{5}{}\protected@file@percent } +\newlabel{eq:second.term.rhs.9}{{22}{5}} +\newlabel{eq:second.term.rhs.9final}{{24}{5}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.2.3}Putting together the first and second terms}{5}{}\protected@file@percent } +\newlabel{eq:first.and.secons.vvtgeneral}{{25}{5}} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\newlabel{eq:cov.Yt.Xt.no.missing.vals}{{26}{6}} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.3}State residuals conditioned on the data}{6}{}\protected@file@percent } +\newlabel{eq:Wlawoftotvar}{{29}{6}} +\newlabel{eq:varwwt}{{32}{6}} +\newlabel{eq:var.W.cond.y1}{{34}{6}} +\newlabel{eq:E.var.Wt.yt}{{35}{6}} +\citation{Holmes2010} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.4}Covariance of the conditional model and state residuals}{7}{}\protected@file@percent } +\newlabel{eq:covhatVtWt1}{{37}{7}} +\newlabel{eq:covhatVtWt3}{{38}{7}} +\newlabel{eq:covhatVtWt2}{{41}{7}} +\newlabel{eq:covVtWt}{{42}{7}} +\newlabel{eq:covVtWt2}{{43}{7}} +\newlabel{eq:conditionalcovvtwt}{{44}{7}} +\citation{Harveyetal1998} +\@writefile{toc}{\contentsline {subsection}{\numberline {2.5}Joint distribution of the conditional residuals}{8}{}\protected@file@percent } +\newlabel{eq:jointcondresid1general}{{54}{8}} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\newlabel{eq:jointcondresid2}{{57}{9}} +\@writefile{toc}{\contentsline {section}{\numberline {3}Harvey et al. 1998 algorithm for the conditional residuals}{9}{}\protected@file@percent } +\newlabel{eq:residsMARSSHarvey}{{58}{9}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Algorithm for the non-normalized residuals}{9}{}\protected@file@percent } +\citation{Harveyetal1998} +\citation{ShumwayStoffer2006} +\citation{Holmes2010} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\citation{Harveyetal1998} +\newlabel{eq:Harveyalgo}{{59}{10}} +\newlabel{eq:Harveyresiduals}{{60}{10}} +\newlabel{eq:Harveyvariance}{{61}{10}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}Difference in notation}{10}{}\protected@file@percent } +\citation{HarveyKoopman1992} +\citation{Harveyetal1998} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}Computing the normalized residuals}{11}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {3.4}Computing the Cholesky standardized residuals}{11}{}\protected@file@percent } +\newlabel{eq:std.resid}{{64}{11}} +\@writefile{toc}{\contentsline {section}{\numberline {4}Distribution of the MARSS innovation residuals}{11}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsection}{\numberline {4.1}One-step-ahead model residuals}{11}{}\protected@file@percent } +\newlabel{eq:vtt1}{{66}{11}} +\newlabel{eq:innov.model}{{67}{11}} +\newlabel{eq:innov.model2}{{68}{12}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.2}One-step ahead state residuals}{12}{}\protected@file@percent } +\newlabel{eq:wtt1}{{69}{12}} +\newlabel{eq:wtt1.2}{{70}{12}} +\newlabel{eq:wtt1.3}{{71}{12}} +\newlabel{eq:var.Wt}{{72}{12}} +\@writefile{toc}{\contentsline {subsection}{\numberline {4.3}Joint distribution of the conditional one-step-ahead residuals}{12}{}\protected@file@percent } +\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.1}with the state residuals defined from $t-1$ to $t$}{12}{}\protected@file@percent } +\newlabel{eq:covhatVtWtp.onestep}{{74}{12}} +\newlabel{eq:jointcondresid.onestep}{{75}{12}} +\bibdata{./EMDerivation} +\bibcite{CommandeurKoopman2007}{{1}{2007}{{Commandeur and Koopman}}{{}}} +\@writefile{toc}{\contentsline {subsubsection}{\numberline {4.3.2}with the state residuals defined from $t$ to $t+1$}{13}{}\protected@file@percent } +\newlabel{eq:covhatVtWtp.onestep.2}{{80}{13}} +\newlabel{eq:jointcondresid.onestep2}{{81}{13}} +\@writefile{toc}{\contentsline {section}{\numberline {5}Distribution of the MARSS contemporaneous model residuals}{13}{}\protected@file@percent } +\newlabel{eq:vtt}{{84}{13}} +\newlabel{eq:contemp.model}{{85}{13}} +\bibcite{deJong1988}{{2}{1988}{{de~Jong}}{{}}} +\bibcite{deJongPenzer1998}{{3}{1998}{{de~Jong and Penzer}}{{}}} +\bibcite{HarveyKoopman1992}{{4}{1992}{{Harvey and Koopman}}{{}}} +\bibcite{Harveyetal1998}{{5}{1998}{{Harvey et~al.}}{{}}} +\bibcite{Holmes2010}{{6}{2012}{{Holmes}}{{}}} +\bibcite{ShumwayStoffer2006}{{7}{2006}{{Shumway and Stoffer}}{{}}} +\bibstyle{apalike} +\gdef \@abspage@last{14} diff --git a/vignettes/Residuals.bbl b/vignettes/Residuals.bbl new file mode 100644 index 0000000..799f1fd --- /dev/null +++ b/vignettes/Residuals.bbl @@ -0,0 +1,38 @@ +\begin{thebibliography}{} + +\bibitem[Commandeur and Koopman, 2007]{CommandeurKoopman2007} +Commandeur, J.~J. and Koopman, S.~J. (2007). +\newblock {\em An introduction to state space time series analysis}. +\newblock Practical Econometrics. Oxford University Press, Oxford. + +\bibitem[de~Jong, 1988]{deJong1988} +de~Jong, P. (1988). +\newblock A cross-validation filter for time series models. +\newblock {\em Biometrika}, 75(3):594--600. + +\bibitem[de~Jong and Penzer, 1998]{deJongPenzer1998} +de~Jong, P. and Penzer, J. (1998). +\newblock Diagnosing shocks in time series. +\newblock {\em Journal of the American Statistical Association}, 93(442):796--806. + +\bibitem[Harvey and Koopman, 1992]{HarveyKoopman1992} +Harvey, A. and Koopman, S.~J. (1992). +\newblock Diagnostic checking of unobserved-components time series models. +\newblock {\em Journal of Business and Economic Statistics,}, 10:377--389. + +\bibitem[Harvey et~al., 1998]{Harveyetal1998} +Harvey, A., Koopman, S.~J., and Penzer, J. (1998). +\newblock Messy time series: a unified approach. +\newblock {\em Advances in Econometrics}, 13:103--143. + +\bibitem[Holmes, 2012]{Holmes2010} +Holmes, E.~E. (2012). +\newblock Derivation of the {EM} algorithm for constrained and unconstrained {MARSS} models. +\newblock Technical report, arXiv:1302.3919 [stat.ME]. + +\bibitem[Shumway and Stoffer, 2006]{ShumwayStoffer2006} +Shumway, R. and Stoffer, D. (2006). +\newblock {\em Time series analysis and its applications}. +\newblock Springer-Science+Business Media, LLC, New York, New York, 2nd edition. + +\end{thebibliography} diff --git a/vignettes/Residuals.blg b/vignettes/Residuals.blg new file mode 100644 index 0000000..936d36c --- /dev/null +++ b/vignettes/Residuals.blg @@ -0,0 +1,46 @@ +This is BibTeX, Version 0.99d (TeX Live 2023) +Capacity: max_strings=200000, hash_size=200000, hash_prime=170003 +The top-level auxiliary file: Residuals.aux +The style file: apalike.bst +Database file #1: ./EMDerivation.bib +You've used 7 entries, + 1935 wiz_defined-function locations, + 526 strings with 4812 characters, +and the built_in function-call counts, 2497 in all, are: += -- 246 +> -- 84 +< -- 6 ++ -- 30 +- -- 26 +* -- 203 +:= -- 448 +add.period$ -- 22 +call.type$ -- 7 +change.case$ -- 48 +chr.to.int$ -- 7 +cite$ -- 7 +duplicate$ -- 95 +empty$ -- 183 +format.name$ -- 41 +if$ -- 491 +int.to.chr$ -- 1 +int.to.str$ -- 0 +missing$ -- 8 +newline$ -- 38 +num.names$ -- 21 +pop$ -- 34 +preamble$ -- 1 +purify$ -- 48 +quote$ -- 0 +skip$ -- 73 +stack$ -- 0 +substring$ -- 172 +swap$ -- 6 +text.length$ -- 0 +text.prefix$ -- 0 +top$ -- 0 +type$ -- 38 +warning$ -- 0 +while$ -- 18 +width$ -- 0 +write$ -- 95 diff --git a/vignettes/Residuals.log b/vignettes/Residuals.log new file mode 100644 index 0000000..08deeb9 --- /dev/null +++ b/vignettes/Residuals.log @@ -0,0 +1,244 @@ +This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex 2023.5.14) 19 MAY 2023 23:06 +entering extended mode + restricted \write18 enabled. + %&-line parsing enabled. +**\input ./Residuals.tex \input ./Residuals.tex \input ./Residuals.tex \input ./Residuals.tex + (./Residuals.tex (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/article.cls +Document Class: article 2022/07/02 v1.4n Standard LaTeX document class +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/size10.clo +File: size10.clo 2022/07/02 v1.4n Standard LaTeX file (size option) +) +\c@part=\count185 +\c@section=\count186 +\c@subsection=\count187 +\c@subsubsection=\count188 +\c@paragraph=\count189 +\c@subparagraph=\count190 +\c@figure=\count191 +\c@table=\count192 +\abovecaptionskip=\skip48 +\belowcaptionskip=\skip49 +\bibindent=\dimen140 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/multirow/multirow.sty +Package: multirow 2021/03/15 v2.8 Span multiple rows of a table +\multirow@colwidth=\skip50 +\multirow@cntb=\count193 +\multirow@dima=\skip51 +\bigstrutjot=\dimen141 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/footmisc/footmisc.sty +Package: footmisc 2022/03/08 v6.0d a miscellany of footnote facilities +\FN@temptoken=\toks16 +\footnotemargin=\dimen142 +\@outputbox@depth=\dimen143 +Package footmisc Info: Declaring symbol style bringhurst on input line 695. +Package footmisc Info: Declaring symbol style chicago on input line 703. +Package footmisc Info: Declaring symbol style wiley on input line 712. +Package footmisc Info: Declaring symbol style lamport-robust on input line 723. +Package footmisc Info: Declaring symbol style lamport* on input line 743. +Package footmisc Info: Declaring symbol style lamport*-robust on input line 764. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/natbib/natbib.sty +Package: natbib 2010/09/13 8.31b (PWD, AO) +\bibhang=\skip52 +\bibsep=\skip53 +LaTeX Info: Redefining \cite on input line 694. +\c@NAT@ctr=\count194 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsmath.sty +Package: amsmath 2022/04/08 v2.17n AMS math features +\@mathmargin=\skip54 + +For additional information on amsmath, use the `?' option. +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amstext.sty +Package: amstext 2021/08/26 v2.01 AMS text + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsgen.sty +File: amsgen.sty 1999/11/30 v2.0 generic functions +\@emptytoks=\toks17 +\ex@=\dimen144 +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsbsy.sty +Package: amsbsy 1999/11/29 v1.2d Bold Symbols +\pmbraise@=\dimen145 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsmath/amsopn.sty +Package: amsopn 2022/04/08 v2.04 operator names +) +\inf@bad=\count195 +LaTeX Info: Redefining \frac on input line 234. +\uproot@=\count196 +\leftroot@=\count197 +LaTeX Info: Redefining \overline on input line 399. +LaTeX Info: Redefining \colon on input line 410. +\classnum@=\count198 +\DOTSCASE@=\count199 +LaTeX Info: Redefining \ldots on input line 496. +LaTeX Info: Redefining \dots on input line 499. +LaTeX Info: Redefining \cdots on input line 620. +\Mathstrutbox@=\box51 +\strutbox@=\box52 +LaTeX Info: Redefining \big on input line 722. +LaTeX Info: Redefining \Big on input line 723. +LaTeX Info: Redefining \bigg on input line 724. +LaTeX Info: Redefining \Bigg on input line 725. +\big@size=\dimen146 +LaTeX Font Info: Redeclaring font encoding OML on input line 743. +LaTeX Font Info: Redeclaring font encoding OMS on input line 744. +\macc@depth=\count266 +LaTeX Info: Redefining \bmod on input line 905. +LaTeX Info: Redefining \pmod on input line 910. +LaTeX Info: Redefining \smash on input line 940. +LaTeX Info: Redefining \relbar on input line 970. +LaTeX Info: Redefining \Relbar on input line 971. +\c@MaxMatrixCols=\count267 +\dotsspace@=\muskip16 +\c@parentequation=\count268 +\dspbrk@lvl=\count269 +\tag@help=\toks18 +\row@=\count270 +\column@=\count271 +\maxfields@=\count272 +\andhelp@=\toks19 +\eqnshift@=\dimen147 +\alignsep@=\dimen148 +\tagshift@=\dimen149 +\tagwidth@=\dimen150 +\totwidth@=\dimen151 +\lineht@=\dimen152 +\@envbody=\toks20 +\multlinegap=\skip55 +\multlinetaggap=\skip56 +\mathdisplay@stack=\toks21 +LaTeX Info: Redefining \[ on input line 2953. +LaTeX Info: Redefining \] on input line 2954. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/amsfonts.sty +Package: amsfonts 2013/01/14 v3.01 Basic AMSFonts support +\symAMSa=\mathgroup4 +\symAMSb=\mathgroup5 +LaTeX Font Info: Redeclaring math symbol \hbar on input line 98. +LaTeX Font Info: Overwriting math alphabet `\mathfrak' in version `bold' +(Font) U/euf/m/n --> U/euf/b/n on input line 106. +) (/Library/Frameworks/R.framework/Resources/share/texmf/tex/latex/Sweave.sty +Package: Sweave + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/ifthen.sty +Package: ifthen 2022/04/13 v1.1d Standard LaTeX ifthen package (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/iftex/iftex.sty +Package: iftex 2022/02/03 v1.0f TeX engine tests +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphicx.sty +Package: graphicx 2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/keyval.sty +Package: keyval 2022/05/29 v1.15 key=value parser (DPC) +\KV@toks@=\toks22 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphics.sty +Package: graphics 2022/03/10 v1.4e Standard LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/trig.sty +Package: trig 2021/08/11 v1.11 sin cos tan (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-cfg/graphics.cfg +File: graphics.cfg 2016/06/04 v1.11 sample graphics configuration +) +Package graphics Info: Driver file: pdftex.def on input line 107. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-def/pdftex.def +File: pdftex.def 2022/09/22 v1.2b Graphics/color driver for pdftex +)) +\Gin@req@height=\dimen153 +\Gin@req@width=\dimen154 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty +Package: fancyvrb 2023/01/19 4.5a verbatim text (tvz,hv) +\FV@CodeLineNo=\count273 +\FV@InFile=\read2 +\FV@TabBox=\box53 +\c@FancyVerbLine=\count274 +\FV@StepNumber=\count275 +\FV@OutFile=\write3 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/textcomp.sty +Package: textcomp 2020/02/02 v2.0n Standard LaTeX package +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/fontenc.sty +Package: fontenc 2021/04/29 v2.0v Standard LaTeX package +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/l3backend/l3backend-pdftex.def +File: l3backend-pdftex.def 2023-04-19 L3 backend support: PDF output (pdfTeX) +\l__color_backend_stack_int=\count276 +\l__pdf_internal_box=\box54 +) (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/Residuals.aux) +\openout1 = `Residuals.aux'. + +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 177. +LaTeX Font Info: ... okay on input line 177. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/epstopdf-pkg/epstopdf-base.sty +Package: epstopdf-base 2020-01-24 v2.11 Base part for package epstopdf + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/infwarerr/infwarerr.sty +Package: infwarerr 2019/12/03 v1.5 Providing info/warning/error messages (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/grfext/grfext.sty +Package: grfext 2019/12/03 v1.3 Manage graphics extensions (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/kvdefinekeys/kvdefinekeys.sty +Package: kvdefinekeys 2019-12-19 v1.6 Define keys (HO) +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvoptions/kvoptions.sty +Package: kvoptions 2022-06-15 v3.15 Key value format for package options (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/ltxcmds/ltxcmds.sty +Package: ltxcmds 2020-05-10 v1.25 LaTeX kernel commands for general use (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvsetkeys/kvsetkeys.sty +Package: kvsetkeys 2022-10-05 v1.19 Key value parser (HO) +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/pdftexcmds/pdftexcmds.sty +Package: pdftexcmds 2020-06-27 v0.33 Utility functions of pdfTeX for LuaTeX (HO) +Package pdftexcmds Info: \pdf@primitive is available. +Package pdftexcmds Info: \pdf@ifprimitive is available. +Package pdftexcmds Info: \pdfdraftmode found. +) +Package epstopdf-base Info: Redefining graphics rule for `.eps' on input line 485. +Package grfext Info: Graphics extension search list: +(grfext) [.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2,.eps] +(grfext) \AppendGraphicsExtensions on input line 504. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/latexconfig/epstopdf-sys.cfg +File: epstopdf-sys.cfg 2010/07/13 v1.3 Configuration of (r)epstopdf for TeX Live +)) (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/Residuals-concordance.tex) +LaTeX Font Info: Trying to load font information for U+msa on input line 184. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsa.fd +File: umsa.fd 2013/01/14 v3.01 AMS symbols A +) +LaTeX Font Info: Trying to load font information for U+msb on input line 184. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/amsfonts/umsb.fd +File: umsb.fd 2013/01/14 v3.01 AMS symbols B +) +Underfull \hbox (badness 10000) in paragraph at lines 184--184 +[][]\T1/cmr/m/n/8 Northwest Fish-eries Sci-ence Cen-ter, NOAA Fish-eries, Seat-tle, WA 98112, eli.holmes@noaa.gov, + [] + +[1 + +{/Users/eli.holmes/Library/TinyTeX/texmf-var/fonts/map/pdftex/updmap/pdftex.map}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-t1.enc}{/Users/eli.holmes/Library/TinyTeX/texmf-dist/fonts/enc/dvips/cm-super/cm-super-ts1.enc}] [2] [3] +LaTeX Font Info: Trying to load font information for T1+cmtt on input line 326. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/t1cmtt.fd +File: t1cmtt.fd 2022/07/10 v2.5l Standard LaTeX font definitions +) [4] [5] [6] [7] [8] +Overfull \hbox (8.32883pt too wide) detected at line 562 +[][] \OML/cmm/m/it/10 : + [] + +[9] [10] [11] [12] +Overfull \hbox (3.60258pt too wide) in paragraph at lines 800--801 +[]\T1/cmr/m/n/10 Equation 85[] gives the equa-tion for the case where $[][]$ is par-tially ob-served. $[][]$ is out-put by the [][]\T1/cmtt/m/n/10 MARSShatyt() + [] + +(/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/Residuals.bbl [13]) [14] (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/Residuals.aux) ) +Here is how much of TeX's memory you used: + 4132 strings out of 478007 + 66788 string characters out of 5838177 + 1913999 words of memory out of 5000000 + 24210 multiletter control sequences out of 15000+600000 + 536532 words of font info for 95 fonts, out of 8000000 for 9000 + 14 hyphenation exceptions out of 8191 + 72i,22n,76p,1346b,300s stack positions out of 10000i,1000n,20000p,200000b,200000s + +Output written on Residuals.pdf (14 pages, 593324 bytes). +PDF statistics: + 245 PDF objects out of 1000 (max. 8388607) + 150 compressed objects within 2 object streams + 0 named destinations out of 1000 (max. 500000) + 5 words of extra memory for PDF output out of 10000 (max. 10000000) + diff --git a/vignettes/Residuals.pdf b/vignettes/Residuals.pdf new file mode 100644 index 0000000..e40cb43 Binary files /dev/null and b/vignettes/Residuals.pdf differ diff --git a/vignettes/Residuals.tex b/vignettes/Residuals.tex new file mode 100644 index 0000000..7795954 --- /dev/null +++ b/vignettes/Residuals.tex @@ -0,0 +1,805 @@ +%\VignetteIndexEntry{Residuals} +%\VignettePackage{MARSS} +\documentclass[]{article} +%set margins to 1in without fullsty + \addtolength{\oddsidemargin}{-.875in} + \addtolength{\evensidemargin}{-.875in} + \addtolength{\textwidth}{1.75in} + + \addtolength{\topmargin}{-.875in} + \addtolength{\textheight}{1.75in} +%\usepackage{fullpage} %more standardized margins + +% choose options for [] as required from the list +% in the Reference Guide, Sect. 2.2 + +\usepackage{multirow} +\usepackage[bottom]{footmisc}% places footnotes at page bottom +\usepackage[round]{natbib} + +% Math stuff +\usepackage{amsmath} % the standard math package +\usepackage{amsfonts} % the standard math package +%%%% bold maths symbol system: +\def\uupsilon{\pmb{\upsilon}} +\def\llambda{\pmb{\lambda}} +\def\bbeta{\pmb{\beta}} +\def\aalpha{\pmb{\alpha}} +\def\zzeta{\pmb{\zeta}} +\def\etaeta{\mbox{\boldmath $\eta$}} +\def\xixi{\mbox{\boldmath $\xi$}} +\def\pipi{\pmb{\pi}} +\def\ep{\mbox{\boldmath $\epsilon$}} +\def\DEL{\mbox{\boldmath $\Delta$}} +\def\PHI{\mbox{\boldmath $\Phi$}} +\def\PI{\mbox{\boldmath $\Pi$}} +\def\LAM{\mbox{\boldmath $\Lambda$}} +\def\LAMm{\mathbb{L}} +\def\GAM{\mbox{\boldmath $\Gamma$}} +\def\OMG{\mbox{\boldmath $\Omega$}} +\def\SI{\mbox{\boldmath $\Sigma$}} +\def\TH{\mbox{\boldmath $\Theta$}} +\def\UPS{\mbox{\boldmath $\Upsilon$}} +\def\XI{\mbox{\boldmath $\Xi$}} +\def\AA{\mbox{$\mathbf A$}} \def\aa{\mbox{$\mathbf a$}} +\def\Ab{\mbox{$\mathbf D$}} \def\Aa{\mbox{$\mathbf d$}} \def\Am{\PI} +\def\BB{\mbox{$\mathbf B$}} \def\bb{\mbox{$\mathbf b$}} \def\Bb{\mbox{$\mathbf J$}} \def\Ba{\mbox{$\mathbf L$}} \def\Bm{\UPS} +\def\CC{\mbox{$\mathbf C$}} \def\cc{\mbox{$\mathbf c$}} +\def\Ca{\Delta} \def\Cb{\GAM} +\def\DD{\mbox{$\mathbf D$}} \def\dd{\mbox{$\mathbf d$}} +\def\EE{\mbox{$\mathbf E$}} \def\ee{\mbox{$\mathbf e$}} +\def\E{\,\textup{\textrm{E}}} +\def\EXy{\,\textup{\textrm{E}}_{\text{{\bf XY}}}} +\def\FF{\mbox{$\mathbf F$}} \def\ff{\mbox{$\mathbf f$}} +\def\GG{\mbox{$\mathbf G$}} \def\gg{\mbox{$\mathbf g$}} +\def\HH{\mbox{$\mathbf H$}} \def\hh{\mbox{$\mathbf h$}} +\def\II{\mbox{$\mathbf I$}} \def\ii{\mbox{$\mathbf i$}} +\def\IIm{\mbox{$\mathbf I$}} +\def\JJ{\mbox{$\mathbf J$}} +\def\KK{\mbox{$\mathbf K$}} +\def\LL{\mbox{$\mathbf L$}} \def\ll{\mbox{$\mathbf l$}} +\def\MM{\mbox{$\mathbf M$}} \def\mm{\mbox{$\mathbf m$}} +\def\N{\,\textup{\textrm{N}}} +\def\MVN{\,\textup{\textrm{MVN}}} +\def\OO{\mbox{$\mathbf O$}} +\def\PP{\mbox{$\mathbf P$}} \def\pp{\mbox{$\mathbf p$}} +\def\QQ{\mbox{$\mathbf Q$}} \def\qq{\mbox{$\mathbf q$}} \def\Qb{\mbox{$\mathbf G$}} \def\Qm{\mathbb{Q}} +\def\RR{\mbox{$\mathbf R$}} \def\rr{\mbox{$\mathbf r$}} \def\Rb{\mbox{$\mathbf H$}} \def\Rm{\mathbb{R}} +\def\Ss{\mbox{$\mathbf S$}} +\def\UU{\mbox{$\mathbf U$}} \def\uu{\mbox{$\mathbf u$}} +\def\Ub{\mbox{$\mathbf C$}} \def\Ua{\mbox{$\mathbf c$}} \def\Um{\UPS} +%\def\VV{\mbox{$\mathbf V$}} \def\vv{\mbox{$\mathbf v$}} +\def\VV{\mbox{$\pmb{V}$}} \def\vv{\mbox{$\pmb{v}$}} +%\def\WW{\mbox{$\mathbf W$}} \def\ww{\mbox{$\mathbf w$}} +\def\WW{\mbox{$\pmb{W}$}} \def\ww{\mbox{$\pmb{w}$}} +%\def\XX{\mbox{$\mathbf X$}} +\def\XX{\mbox{$\pmb{X}$}} \def\xx{\mbox{$\pmb{x}$}} +%\def\xx{\mbox{$\mathbf x$}} +%\def\YY{\mbox{$\mathbf Y$}} +\def\YY{\mbox{$\pmb{Y}$}} \def\yy{\mbox{$\pmb{y}$}} +%\def\yy{\mbox{$\mathbf y$}} +\def\ZZ{\mbox{$\mathbf Z$}} \def\zz{\mbox{$\mathbf z$}} \def\Zb{\mbox{$\mathbf M$}} \def\Za{\mbox{$\mathbf N$}} \def\Zm{\XI} +\def\zer{\mbox{\boldmath $0$}} +\def\chol{\,\textup{\textrm{chol}}} +\def\vec{\,\textup{\textrm{vec}}} +\def\var{\,\textup{\textrm{var}}} +\def\cov{\,\textup{\textrm{cov}}} +\def\diag{\,\textup{\textrm{diag}}} +\def\trace{\,\textup{\textrm{trace}}} +\def\dg{\,\textup{\textrm{dg}}} +\def\hatxtT{\widetilde{\xx}_t^T} +\def\hatxtpT{\widetilde{\xx}_{t+1}^T} +\def\hatxtt{\widetilde{\xx}_t^{t}} +\def\hatxttm{\widetilde{\xx}_t^{t-1}} +\def\hatxone{\widetilde{\xx}_1} +\def\hatxzero{\widetilde{\xx}_0} +\def\hatxtmT{\widetilde{\xx}_{t-1}^T} +\def\hatxtmt1{\widetilde{\xx}_{t-1}^{t-1}} +\def\hatxtpt1{\widetilde{\xx}_{t+1}^{t-1}} +\def\hatxQtm{\widetilde{\mathbb{x}}_{t-1}} +\def\hatyt{\widetilde{\yy}_t} +\def\hatyyt{\widetilde{\mbox{$\mathbf y$}\mbox{$\mathbf y$}^\top}_t} +\def\hatyone{\widetilde{\yy}_1} +\def\hatOt{\widetilde{\OO}_t} +\def\hatWt{\widehat{\WW}_t} +\def\hatWtp{\widehat{\WW}_{t+1}} +\def\hatwt{\widehat{\ww}_t} +\def\hatwtp{\widehat{\ww}_{t+1}} +\def\checkWt{\overline{\WW}_{t}} +\def\checkWtp{\overline{\WW}_{t+1}} +\def\checkwt{\overline{\ww}_t} +\def\checkwtp{\overline{\ww}_{t+1}} +\def\hatYXt{\widetilde{\mbox{$\yy\xx$}}_t} +\def\hatXYt{\widetilde{\mbox{$\xx\yy$}}_t} +\def\hatYXttm{\widetilde{\mbox{$\yy\xx$}}_{t,t-1}} +\def\hatPt{\widetilde{\PP}_t} +\def\hatPtm{\widetilde{\PP}_{t-1}} +\def\hatPQtm{\widetilde{\mathbb{P}}_{t-1}} +\def\hatPttm{\widetilde{\PP}_{t,t-1}} +\def\hatPQttm{\widetilde{\mathbb{P}}_{t,t-1}} +\def\hatPtmt{\widetilde{\PP}_{t-1,t}} +\def\hatVt{\widehat{\VV}_t} +\def\hatvt{\widehat{\vv}_t} +\def\checkvt{\overline{\vv}_t} +\def\checkvtp{\overline{\vv}_{t+1}} +\def\checkVtp{\overline{\VV}_{t+1}} +\def\checkVt{\overline{\VV}_t} +\def\dotvt{\dot{\vv}_t} +\def\dotvtp{\dot{\vv}_{t+1}} +\def\dotVtp{\dot{\VV}_{t+1}} +\def\dotVt{\dot{\VV}_t} +\def\hatVtT{\widetilde{\VV}_t^T} +\def\hatVttm{\widetilde{\VV}_t^{t-1}} +\def\hatVtt{\widetilde{\VV}_t^{t}} +\def\hatVtmT{\widetilde{\VV}_{t-1}^T} +\def\hatVtmt1{\widetilde{\VV}_{t-1}^{t-1}} +\def\hatVttmT{\widetilde{\VV}_{t,t-1}^T} +\def\hatVtmtT{\widetilde{\VV}_{t-1,t}^T} +\def\hatVttmt1{\widetilde{\VV}_{t,t-1}^{t-1}} +\def\hatVtpT{\widetilde{\VV}_{t+1}^T} +\def\hatVttpT{\widetilde{\VV}_{t,t+1}^T} +\def\hatVttpt1{\widetilde{\VV}_{t,t+1}^{t-1}} +\def\hatVtptT{\widetilde{\VV}_{t+1,t}^T} +\def\hatVtptt1{\widetilde{\VV}_{t+1,t}^{t-1}} +\def\hatUtT{\widetilde{\UU}_t^T} +\def\hatUtt1{\widetilde{\UU}_t^{t-1}} +\def\hatStT{\widetilde{\Ss}_t^T} +\def\hatSttm{\widetilde{\Ss}_t^{t-1}} +\def\hatStt{\widetilde{\Ss}_t^{t}} +\def\hatSttmT{\widetilde{\Ss}_{t,t-1}^T} +\def\hatSttmt1{\widetilde{\Ss}_{t,t-1}^{t-1}} +\def\hatSttpT{\widetilde{\Ss}_{t,t+1}^T} +\def\hatSttpt1{\widetilde{\Ss}_{t,t+1}^{t-1}} +\def\hatBmt{\widetilde{\Bm}_t} +\def\hatCat{\widetilde{\Ca}_t} +\def\hatCbt{\widetilde{\Cb}_t} +\def\hatZmt{\widetilde{\Zm}_t} +\def\YYr{\dot{\mbox{$\pmb{Y}$}}} +\def\yyr{\dot{\mbox{$\pmb{y}$}}} +\def\aar{\dot{\mbox{$\mathbf a$}}} +\def\ZZr{\dot{\mbox{$\mathbf Z$}}} +\def\RRr{\dot{\mbox{$\mathbf R$}}} +\def\IR{\nabla} +\usepackage[round]{natbib} % to get references that are like in ecology papers +% \citet{} for inline citation name (year); \citep for citation in parens (name year) + +%allow lines in matrix +\makeatletter +\renewcommand*\env@matrix[1][*\c@MaxMatrixCols c]{% + \hskip -\arraycolsep + \let\@ifnextchar\new@ifnextchar + \array{#1}} +\makeatother +\setcounter{tocdepth}{1} %no subsections in toc + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\usepackage{Sweave} +\begin{document} +\input{Residuals-concordance} +\author{E. E. Holmes\footnote{Northwest Fisheries Science Center, NOAA Fisheries, Seattle, WA 98112, + eli.holmes@noaa.gov, http://faculty.washington.edu/eeholmes}} +\title{Computation of Standardized Residuals for MARSS Models} +\date{original 31 Oct 2014 \\ +\small{\emph{added normalization calculations, 20 Oct 2020}}} +\maketitle +\begin{abstract} +This report walks through a derivation of the variance-covariance matrix for the joint conditional model and state residuals for multivariate autoregressive Gaussian state-space (MARSS) models. The bulk of the report focuses on `smoothations' residuals \citep{Harveyetal1998}, which are the residuals conditioned on all the data $t=1$ to $T$. The final part of the report covers `innovations' residuals, which are residuals conditioned on the data $t=1$ to $t-1$. + +The MARSS model can be written: $\xx_t=\BB\xx_{t-1}+\uu+\ww_t$, $\yy_t=\ZZ\xx_t+\zz+\vv_t$, where $\ww_t$ and $\vv_t$ are independent multivariate Gaussian error-terms with variance-covariance matrices $\QQ_t$ and $\RR_t$ respectively. The joint conditional residuals are the $\ww_t$ and $\vv_t$ conditioned on the observed data, which may be incomplete (missing values). Harvey, Koopman and Penzer (1998) show a recursive algorithm for the smoothation residuals (residuals conditioned on all the data). I show an alternate algorithm to compute these residuals using the conditional variances of the states and the conditional covariance between unobserved data and states. This allows one to compute the variance of un-observed smoothation residuals (residuals associated with missing or left-out data), which is needed for leave-one-out cross-validation tests using smoothation residuals. I show how to modify the Harvey et al. algorithm in the case of missing values and how to modify it to return the non-normalized conditional residuals. +\end{abstract} +Keywords: Time-series analysis, Kalman filter, residuals, maximum-likelihood, vector autoregressive model, dynamic linear model, parameter estimation, state-space +\vfill +{\noindent \small citation: Holmes, E. E. 2014. Computation of standardized residuals for (MARSS) models. Technical Report. arXiv:1411.0045 } + \newpage + +\section{Overview of MARSS residuals} + +This report discusses the computation of the variance of the conditional model and state residuals for MARSS models of the form: +\begin{equation}\label{eq:residsMARSS} +\begin{gathered} +\xx_t = \BB_t\xx_{t-1} + \uu_t + \ww_t, \text{ where } \WW_t \sim \MVN(0,\QQ_t)\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \vv_t, \text{ where } \VV_t \sim \MVN(0,\RR_t)\\ +\XX_0 \sim \MVN(\xixi,\LAM) \text{ or } \xx_0 = \pipi . +\end{gathered} +\end{equation} +The state and model residuals are respectively +\begin{equation}\label{eq:resids} +\begin{gathered} +\ww_t = \xx_t - \BB_t\xx_{t-1} - \uu_t\\ +\vv_t = \yy_t - \ZZ_t\xx_t - \aa_t . +\end{gathered} +\end{equation} +The model (and state) residuals are a random variables since $\yy_t$ and $\xx_t$ are drawn from the joint multivariate distribution of $\YY_t$ and $\XX_t$ defined by the MARSS equations (Equation \ref{eq:residsMARSS}). +The unconditional\footnote{meaning not conditioning on any particular set of observed data but rather taking the expectation across all possible values of $\yy_t$ and $\xx_t$.} variance of the model residuals is +\begin{equation}\label{eq:unconditiondistofVt} +\var_{XY}[\VV_t] = \var_{XY}[\YY_t - (\ZZ_t \XX_t + \aa_t)] = \RR_t\\ +\end{equation} +based on the distribution of $\VV_t$ in Equation \ref{eq:residsMARSS}. $\var_{XY}$ indicates that the integration is over the joint unconditional distribution of $\XX$ and $\YY$. + +Once we have data, $\RR_t$ is not the variance-covariance matrix of our model residuals because our residuals are now conditioned\footnote{`conditioned' means that the probability distribution of the residual has changed. The distribution is now the distribution given that $\YY=\yy$, say. Expectations and variances $\var[ ]$ are integrals over the value that a random variable might take multiplied by the probability of that value. When presenting an `expectation', the probability distribution is normally implicit but for derivations involving conditional expectations, it is important to be explicit about the distribution that is being integrated over.} on a set of observed data. There are two types of conditional model residuals used in MARSS analyses: innovations and smoothations. Innovations are the model residuals at time $t$ using the expected value of $\XX_t$ conditioned on the data from 1 to $t-1$. Smoothations are the model residuals using the expected value of $\XX_t$ conditioned on all the data, $t=1$ to $T$. Smoothations are used in computing standardized residuals for outlier and structural break detection \citep{HarveyKoopman1992, Harveyetal1998, deJongPenzer1998, CommandeurKoopman2007}. + +It should be noted that all the calculations discussed here are conditioned on the MARSS parameters: $\BB$, $\QQ$, $\UU$, $\RR$, $\ZZ$ and $\AA$. These are treated as known. This is different than standard discussions of residual distributions for linear models where the uncertainty in the model parameters enters into the calculations (as it enters into the calculation of the influence of $\yy$ on the expected (or fitted) value of $\yy$). In the calculations in this report, $\yy$ does not affect the estimates of the parameters (which are fixed, perhaps at estimated values) but does affect the expected value of $\YY_t$ by affecting the estimate of the expected value and variance of $\XX_t$. + +\section{Distribution of MARSS smoothation residuals}\label{sec:smoothations} + +This section discusses computation of the variance of the model and state residuals conditioned on all the data from $t=1$ to $T$. These MARSS residuals are often used for outlier detection and shock detection, and in this case you only need the distribution of the model residuals for the observed values. However if you wanted to do a leave-one-out cross-validation, you would need to know the distribution of the residuals for data points you left out (treated as unobserved). The equations in this report give you the former and the latter, while the algorithm by \citet{Harveyetal1998} gives only the former. These equations for residuals for `left-out` data are different that other (typical) discussions of state-space cross-validation \citep{deJong1988} in that they are conditioned on all the data (smoothations residuals) rather than conditioned on data up to $t-1$ (innovations residuals). + +\subsection{Notation and relations} + +Throughout, I follow the convention that capital letters are random variables and small letters are a realization from the random variable. This only applies to random variables; parameters are not random variables\footnote{in a frequentist framework}. Parameters are shown in Roman font while while random variables are bold slanted font. Parameters written as capital letters are matrices, while parameters written in small letters are strictly column matrices. + +In this report, the distribution over which the integration is done in an expectation or variance is given by the subscript; e.g., $\E_A[f(A)]$ indicates an unconditional expectation over the distribution of $A$ without conditioning on another random variable while $\E_{A|b}[f(A)|b]$ would indicate an expectation over the distribution of $A$ conditioned on $B=b$; presumably $A$ and $B$ are not independent otherwise $B=b$ would have no effect on $A$. $\E_{A|b}[f(A)|b]$ is a fixed value, not random. It is the expected value when $B=b$. In contrast, $\E_{A|B}[f(A)|B]$ denotes the random variable over all the possible $\E_{A|b}[f(A)|b]$ given all the possible $b$ values that $B$ might take. The variance of $\E_{A|B}[f(A)|B]$ is the variance of this random variable. The variance of $\E_{A|b}[f(A)|b]$ in contrast is 0 since it is a fixed value. We will often be working with the random variables, $\E_{A|B}[f(A)|B]$ or $\var_{A|B}[f(A)|B]$, inside an expectation or variance: such as $\var_B[\E_{A|B}[f(A)|B]]$. + +\subsubsection{Law of total variance} + +The ``law of total variance'' can be written +\begin{equation}\label{eq:lawoftotvar} +\var_A[A] = \var_B[\E_{A|B}[A|B]] + \E_B[\var_{A|B}[A|B]] . +\end{equation} +The subscripts on the inner expectations make it explicit that the expectations are being taken over the conditional distributions. $\var_{A|B}[A|B]$ and $\E_{A|B}[A|B]$ are random variables because the $B$ in the conditional is a random variable. We take the expectation or variance with $B$ fixed at one value, $b$, but $B$ can take other values of $b$ also. + +Going forward, I will write the law or total variance more succinctly as +\begin{equation} +\var[A] = \var_B[\E[A|B]] + \E_B[\var[A|B]] . +\end{equation} +I leave off the subscript on the inner conditional expectation or variance. Just remember that when you see a conditional in an expectation or variance, the integration is over over the conditional distribution of $A$ conditioned on $B=b$. Even when you see $A|B$, the conditioning is on $B=b$ and the $B$ indicates that this is a random variable because $B$ can take different $b$ values. When computing $\var_B[\E_{A|B}[A|B]]$, we will typically compute $\E_{A|b}[A|b]$ and then compute (or infer) the variance or expectation of that over all possible values of $b$. + +The law of total variance will appear in this report in the following form: +\begin{equation} +\var_{XY}[f(\YY,\XX)] = \var_{Y^{(1)}}[\E_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] + \E_{Y^{(1)}}[\var_{XY|Y^{(1)}}[f(\YY,\XX)|\YY^{(1)}]] , +\end{equation} +where $f(\YY_t,\XX_t)$ is some function of $\XX_t$ and $\YY_t$ and $\YY^{(1)}$ is the observed data from $t=1$ to $T$ ($\YY^{(2)}$ is the unobserved data). + + +\subsection{Model residuals conditioned on all the data} + +Define the smoothations $\hatvt$ as: +\begin{equation}\label{eq:vtT} +\hatvt = \yy_t - \ZZ_t\hatxtT - \aa_t, +\end{equation} +where $\hatxtT$ is $\E[\XX_t|\yy^{(1)}]$. The smoothation is different from $\vv_t$ because it uses $\hatxtT$ not $\xx_t$; $\xx_t$ is not known, and $\hatxtT$ is its estimate. $\hatxtT$ is output by the Kalman smoother. $\yy^{(1)}$ means all the observed data from $t=1$ to $T$. $\yy^{(1)}$ is a sample from the random variable $\YY^{(1)}$. The unobserved $\yy$ will be termed $\yy^{(2)}$ and is a sample from the random variable $\YY^{(2)}$. When $\YY$ appears without a superscript, it means both $\YY^{(1)}$ and $\YY^{(2)}$ together. Similarly $\yy$ means both $\yy^{(1)}$ and $\yy^{(2)}$ together---the observed data that we use to estimate $\hatxtT$ and the unobserved data that we do not use and may or may not know. $\hatvt$ exists for both $\yy^{(1)}$ and $\yy^{(2)}$, though we might not know $\yy^{(2)}$ and thus might not know its corresponding $\hatvt$. In some cases, however, we do know $\yy^{(2)}$; they are data that we left out of our model fitting, in say a k-fold or leave-one-out cross-validation. + +$\hatvt$ is a sample from the random variable $\hatVt$. We want to compute the mean and variance of this random variable over all possibles values that $\XX_t$ and $\YY_t$ might take. The mean of $\hatVt$ is 0 and we are concerned only with computing the variance: +\begin{equation}\label{eq:var.vtT} +\var[\hatVt] = \var_{XY}[\YY_t - \ZZ_t\E[\XX_t|\YY^{(1)}] - \aa_t] . +\end{equation} +Notice we have an unconditional variance over ${\XX,\YY}$ on the outside and a conditional expectation over a specific value of $\YY^{(1)}$ on the inside (in the $\E[\;]$). + +From the law of total variance (Equation \ref{eq:lawoftotvar}), we can write the variance of the model residuals as +\begin{equation}\label{eq:varvvtgeneral} +\var[\hatVt] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] . +\end{equation} + +\subsubsection{First term on right hand side of Equation \ref{eq:varvvtgeneral}} + +The random variable inside the $\var[\;]$ in the first term is +\begin{equation}\label{eq:first.term.rhs.varvvtgeneral} +\E[\hatVt|\YY^{(1)}]= \E[(\YY_t + \ZZ_t \E[\XX_t|\YY^{(1)}] + \aa_t)|\YY^{(1)}] . +\end{equation} +Let's consider this for a specific value $\YY^{(1)}=\yy^{(1)}$. +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[(\YY_t + \ZZ_t \E[\XX_t|\yy^{(1)}] + \aa_t)|\yy^{(1)}] = +\E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +$\E[\XX_t|\yy^{(1)}]$ is a fixed value, and the expected value of a fixed value is itself. So $\E[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=\E[\XX_t|\yy^{(1)}]$. +Thus, +\begin{equation} +\E[\hatVt|\yy^{(1)}] = \E[\YY_t|\yy^{(1)}] + \ZZ_t \E[\XX_t|\yy^{(1)}] + \E[\aa_t|\yy^{(1)}] . +\end{equation} +We can move the conditional out and write +\begin{equation} +\E[\hatVt|\yy^{(1)}]= \E[(\YY_t + \ZZ_t \XX_t + \aa_t)|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]. +\end{equation} +The right side is $\E[\VV_t|\yy^{(1)}]$, no `hat' on the $\VV_t$, and this applies for all $\yy^{(1)}$. This means that the first term in Equation \ref{eq:varvvtgeneral} can be written with no hat on $\VV$: +\begin{equation}\label{eq:no.hat.on.V} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}]] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] . +\end{equation} +If $\YY_t$ were completely observed (no missing values), this would be zero since $\E[\VV_t|\yy]$ would be a fixed value in that case. But $\YY_t$ is not assumed to be fully observed; it may have $\YY^{(2)}_t$ which is unobserved, or more precisely, not included in the estimation of $VV_t$ for whatever reason (`unknown" because it was unobserved being one reason). The derivation of $\E[\YY_t|\yy^{(1)}]$ is given in \citet{Holmes2010}\footnote{$\E[\YY^{(2)}_t|\yy^{(1)}]$ is not $\ZZ_t \hatxtT + \aa_t$ in general since $\YY^{(2)}_t$ and $\YY^{(1)}_t$ may be correlated through $\RR$ in addition to being correlated through $\hatxtT$}. + +Using the law of total variance, we can re-write $\var[\VV_t]$ as: +\begin{equation}\label{eq:varianceVt} +\var[\VV_t] = \var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:varianceVt}, we can solve for $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]]$: +\begin{equation}\label{eq:var.E.vtT} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \var[\VV_t] - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} +From Equation \ref{eq:unconditiondistofVt}, we know that $\var[\VV_t]=\RR_t$ (this is the unconditional variance). Thus, +\begin{equation}\label{eq:var.E.vtT.R} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}]] = \RR_t - \E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]. +\end{equation} + +The second term in Equation \ref{eq:var.E.vtT.R} to the right of the equal sign and inside the expectation is $\var[\VV_t|\YY^{(1)}]$. This is the variance of $\VV_t$ with $\YY^{(1)}$ held at a specific fixed $\yy^{(1)}$. The variability in $\var[\VV_t|\yy^{(1)}]$ (notice $\yy^{(1)}$ not $\YY^{(1)}$ now) comes from $\XX_t$ and $\YY^{(2)}$ which are random variables. Let's compute this variance for a specific $\yy^{(1)}$ value. +\begin{equation}\label{eq:varvtcondy} +\var[\VV_t|\yy^{(1)}] = \var[ \YY_t - \ZZ_t\XX_t-\aa_t | \yy^{(1)} ]. +\end{equation} +Notice that there is no $\E$ (expectation) on the $\XX_t$; this is $\VV_t$ not $\hatVt$. $\aa_t$ is a fixed value and can be dropped. + +Equation \ref{eq:varvtcondy} can be written as\footnote{$\var(A+B)=\var(A)+\var(B)+\cov(A,B)+\cov(B,A)$}: +\begin{equation}\label{eq:var.Vt.yy} +\begin{split} +\var[\VV_t|\yy^{(1)}] &= \var[ \YY_t - \ZZ_t\XX_t | \yy^{(1)} ]\\ +&=\var[ - \ZZ_t\XX_t | \yy^{(1)} ] + \var[ \YY_t|\yy^{(1)}] + \cov[ \YY_t, - \ZZ_t\XX_t | \yy^{(1)} ] + \cov[ - \ZZ_t\XX_t, \YY_t | \yy^{(1)} ]\\ +&=\ZZ_t \hatVtT \ZZ_t^\top + \hatUtT - \hatStT\ZZ_t^\top - \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +$\hatVtT = \var[ \XX_t | \yy^{(1)} ]$ and is output by the Kalman smoother. $\hatUtT=\var[\YY_t|\yy^{(1)}]$ and $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$. The equations for these are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package\footnote{$\hatUtT$ is \texttt{OtT - tcrossprod(ytT)} in the \texttt{MARSShatyt()} output.}. If there were no missing data, i.e., if $\yy^{(1)}=\yy$, then $\hatUtT$ and $\hatStT$ would be zero because $\YY_t$ would be fixed at $\yy_t$. This would reduce Equation \ref{eq:var.Vt.yy} to $\ZZ_t \hatVtT \ZZ_t^\top$. But we are concerned with the case where there are missing values. Those missing values need not be for all $t$. That is, there may be some observed $y$ at time t and some missing $y$. $\yy_t$ is multivariate. + +From Equation \ref{eq:var.Vt.yy}, we know $\var[\VV_t|\yy^{(1)}]$ for a specific $\yy^{(1)}$. We want $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$ which is its expected value over all possible values of $\yy^{(1)}$. $\VV_t$ is a multivariate normal random variable with two random variables $\YY^{(1)}$ and $\YY^{(2)}$. The conditional variance of a multivariate Normal does not depend on the value that you are conditioning on. Let the $\AA$ be a N-dimensional multivariate Normal random variable partitioned into $\AA_1$ and $\AA_2$ with variance-covariance matrix $\Sigma = \begin{bmatrix} +\Sigma_1 & \Sigma_{12} \\ +\Sigma_21 & \Sigma_{2} +\end{bmatrix}$. The variance-covariance matrix of $\AA$ conditioned on $\AA_1=\aa$ is $\Sigma = \begin{bmatrix} +0 & 0 \\ +0 & \Sigma_2 - \Sigma_{12}\Sigma_{1}\Sigma_{21} +\end{bmatrix}$. Notice that $\aa$ does not appear in the conditional variance matrix. This means that $\var[\VV_t|\yy^{(1)}]$ does not depend on $\yy^{(1)}$. Its variance only depends on the MARSS model parameters\footnote{This also implies that $\hatVtT$, $\hatUtT$ and $\hatStT$ do not depend on $\yy^{(1)}$, which is rather counter-intuitive since $\yy^{(1)}$ is part of the algorithm (Kalman filter and smoother) used to compute these values. The value of $\yy^{(1)}$ affects the expected values of $\XX_t$ but only its presence\ (versus absence) affects $\XX_t$'s conditional variance.}. + +Because $\var[\VV_t|\yy^{(1)}]$ only depends on the MARSS parameters values, $\QQ$, $\BB$, $\RR$, etc., the second term in Equation \ref{eq:var.E.vtT}, $\E_{Y^{(1)}}[\var[\VV_t|\YY^{(1)}]]$, is equal to $\var[\VV_t|\yy^{(1)}]$ (Equation \ref{eq:var.Vt.yy}). Putting this into Equation \ref{eq:var.E.vtT.R}, we have +\begin{equation}\label{eq:conditionalvtfinala} +\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \RR_t - \var[\VV_t|\yy^{(1)}] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} +Since $\var_{Y^{(1)}}[\E[\VV_t|\YY^{(1)})]] = \var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]]$ (Equation \ref{eq:no.hat.on.V}), this means that the first term in Equation \ref{eq:varvvtgeneral} is +\begin{equation}\label{eq:conditionalvtfinal} +\var_{Y^{(1)}}[\E[\hatVt|\YY^{(1)})]] = \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top. +\end{equation} + +\subsubsection{Second term on right hand side of Equation \ref{eq:varvvtgeneral}} + +Consider the second term in Equation \ref{eq:varvvtgeneral}. This term is +\begin{equation}\label{eq:second.term.rhs.9} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \E_{Y^{(1)}}[\var[(\YY_t-\ZZ_t\E[\XX_t|\YY^{(1)}]-\aa_t)|\YY^{(1)}]] . +\end{equation} +The middle term is: +\begin{equation} +\E_{Y^{(1)}}[\var[\E[\XX_t|\YY^{(1)}]|\YY^{(1)}]]. +\end{equation} +Let's solve the inner part for a specific $\YY^{(1)}=\yy^{(1)}$. $\E[\XX_t|\yy^{(1)}]$ is a fixed value. Thus $\var[\E[\XX_t|\yy^{(1)}]|\yy^{(1)}]=0$ since the variance of a fixed value is 0. This is true for all $\yy^{(1)}$ so the middle term reduces to 0. $\aa_t$ is also fixed and its variance is also 0. The covariance between a random variable and a fixed value is 0\footnote{$\var[A+B] = \var[A]+\var[B]+\cov[A,B]$}. Thus for a specific $\YY^{(1)}=\yy^{(1)}$, the inside of the right hand side expectation reduces to $\var[\YY_t|\yy^{(1)}]$ which is $\hatUtT$. As noted in the previous section, $\hatUtT$ is only a function of the MARSS parameters; it is not a function of $\yy^{(1)}$ and $\var[\YY_t|\yy^{(1)}]=\hatUtT$ for all $\yy^{(1)}$. Thus the second term in Equation \ref{eq:varvvtgeneral} is simply $\hatUtT$: +\begin{equation}\label{eq:second.term.rhs.9final} +\E_{Y^{(1)}}[\var[\hatVt|\YY^{(1)}]] = \var[\hatVt|\yy^{(1)}] = \hatUtT . +\end{equation} + +\subsubsection{Putting together the first and second terms} + +We can now put the first and second terms in Equation \ref{eq:varvvtgeneral} together (Equations \ref{eq:conditionalvtfinal} and \ref{eq:second.term.rhs.9final}) and write out the variance of the model residuals: +\begin{equation}\label{eq:first.and.secons.vvtgeneral} +\begin{split} +\var[\hatVt] &= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top - \hatUtT + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top + \hatUtT\\ +&= \RR_t - \ZZ_t \hatVtT \ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top . +\end{split} +\end{equation} +Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t - \ZZ_t \hatVtT \ZZ_t^\top$ if $\yy_t$ has no missing values since $\hatStT = 0$ in this case. If $\yy_t$ is all missing values, $\hatStT = \ZZ_t \hatVtT$ because +\begin{equation}\label{eq:cov.Yt.Xt.no.missing.vals} +\cov[\YY_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t + \aa_t + \VV_t, \XX_t|\yy^{(1)}] = \cov[\ZZ_t \XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \cov[\XX_t, \XX_t|\yy^{(1)}] = \ZZ_t \hatVtT . +\end{equation} +The reduction in Equation \ref{eq:cov.Yt.Xt.no.missing.vals} occurs because $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent in the form of MARSS model used in this report (Equation \ref{eq:residsMARSS})\footnote{This is not the case for the \citet{Harveyetal1998} form of the MARSS model where $\VV_t$ and $\WW_t$ are allowed to be correlated.}. Thus when $\yy_t$ is all missing values, Equation \ref{eq:first.and.secons.vvtgeneral} will reduce to $\RR_t + \ZZ_t \hatVtT \ZZ_t^\top$ . The behavior if $\yy_t$ has some missing and some not missing values depends on whether $\RR_t$ is a diagonal matrix or not, i.e., if the $\yy_t^{(1)}$ and $\yy_t^{(2)}$ are correlated. + +\subsection{State residuals conditioned on the data} + +The state residuals are $\xx_t - (\BB_t \xx_{t-1} + \uu_t)=\ww_t$. The unconditional expected value of the state residuals is $\E[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \E[\WW_t] = 0$ and the unconditional variance of the state residuals is +\begin{equation} +\var[\XX_t - (\BB_t \XX_{t-1} + \uu_t)] = \var[\WW_t] = \QQ_t +\end{equation} +based on the definition of $\WW_t$ in Equation \ref{eq:residsMARSS}. +The conditional state residuals (conditioned on the data from $t=1$ to $t=T$) are defined as +\begin{equation} +\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t. +\end{equation} +where $\hatxtT = E[\XX_t|\yy^{(1)}]$ and $\hatxtmT = E[\XX_{t-1}|\yy^{(1)}]$. $\hatwt$ is a sample from the random variable $\hatWt$; random over different possible data sets. The expected value of $\hatWt$ is 0, and we are concerned with computing its variance. + +We can write the variance of $\WW_t$ (no hat) using the law of total variance. +\begin{equation}\label{eq:Wlawoftotvar} +\var[\WW_t] = \var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Notice that +\begin{equation} +\E[\WW_t|\yy^{(1)}] = \E[(\XX_t - \BB_t \XX_{t-1} - \uu_t)|\yy^{(1)}] = \hatxtT - \BB_t \hatxtmT - \uu_t = \E[\hatWt|\yy^{(1)}] = \hatwt . +\end{equation} +This is true for all $\yy^{(1)}$, thus $\E[\WW_t|\YY^{(1)}]$ is $\hatWt$, and $\var_{Y^{(1)}}[\E[\WW_t|\YY^{(1)}]] = \var[\hatWt]$. Equation \ref{eq:Wlawoftotvar} can thus be written +\begin{equation} +\var[\WW_t] = \var[\hatWt] + \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] . +\end{equation} +Solve for $\var[\hatWt]$: +\begin{equation}\label{eq:varwwt} +\var[\hatWt] = \var[\WW_t] - \E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]. +\end{equation} + +The variance in the expectation on the far right for a specific $\YY^{(1)}=\yy^{(1)}$ is +\begin{equation} +\var[\WW_t|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}-\uu_t) | \yy^{(1)} ] . +\end{equation} +$\uu_t$ is not a random variable and can be dropped. Thus\footnote{$\var[A-B]=\var[A]+\var[B]+\cov[A,-B]+\cov[-B,A]$. Be careful about the signs in this case as they are a little non-intuitive.}, +\begin{equation}\label{eq:var.W.cond.y1} +\begin{split} +\var[\WW_t&|\yy^{(1)}] = \var[ (\XX_t - \BB_t\XX_{t-1}) | \yy^{(1)} ] \\ +& = \var[ \XX_t | \yy^{(1)} ] + \var[\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[\XX_t, -\BB_t\XX_{t-1} | \yy^{(1)} ] + \cov[ -\BB_t\XX_{t-1}, \XX_t | \yy^{(1)} ]\\ +& = \hatVtT + \BB_t \hatVtmT \BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{split} +\end{equation} +Again this is conditional multivariate normal variance, and its value does not depend on the value, $\yy^{(1)}$ that we are conditioning on. It depends only on the parameters values, $\QQ$, $\BB$, $\RR$, etc., and is the same for all values of $\yy^{(1)}$. So $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \var[\WW_t|\yy^{(1)}]$, using any value of $\yy^{(1)}$. Thus +\begin{equation}\label{eq:E.var.Wt.yt} +\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]] = \hatVtT + \BB_t\hatVtmT\BB_t^\top - \hatVttmT\BB_t^\top - \BB_t\hatVtmtT . +\end{equation} + +Putting $\E_{Y^{(1)}}[\var[\WW_t|\YY^{(1)}]]$ from Equation \ref{eq:E.var.Wt.yt} and $\var[\WW_t]=\QQ_t$ into Equation \ref{eq:varwwt}, the variance of the conditional state residuals is +\begin{equation} +\var[\hatWt] = \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT . +\end{equation} + +\subsection{Covariance of the conditional model and state residuals} + +The unconditional model and state residuals, $\VV_t$ and $\WW_t$, are independent by definition\footnote{This independence is specific to the way the MARSS model for this report (Equation \ref{eq:residsMARSS}). It is possible for the model and state residuals to covary. In the MARSS model written in \citet{Harveyetal1998} form, they do covary.} (in Equation \ref{eq:residsMARSS}), i.e., $\cov[\VV_t,\WW_t]=0$. However the conditional model and state residuals, $\cov[\hatVt,\hatWt]$, are not independent since both depend on $\yy^{(1)}$. +Using the law of total covariance, we can write +\begin{equation}\label{eq:covhatVtWt1} +\cov[\hatVt,\hatWt] = +\cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]] + \E_{Y^{(1)}}[\cov[\hatVt, \hatWt|\YY^{(1)}]] . +\end{equation} + +For a specific value of $\YY^{(1)}=\yy^{(1)}$, the covariance in the second term on the right is $\cov[\hatVt, \hatWt|\yy^{(1)}]$. Conditioned on a specific value of $\YY^{(1)}$, $\hatWt$ is a fixed value, $\hatwt = \hatxtT - \BB_t\hatxtmT - \uu_t$, and conditioned on $\yy^{(1)}$, $\hatxtT$ and $\hatxtmT$ are fixed values. $\uu_t$ is also fixed; it is a parameter. $\hatVt$ is not a fixed value because it has $\YY_t^{(2)}$ and that is a random variable. Thus $\cov[\hatVt, \hatWt|\yy^{(1)}]$ is the covariance between a random variable and a fixed variable and thus the covariance is 0. This is true for all $\yy^{(1)}$. +Thus the second right-side term in Equation \ref{eq:covhatVtWt1} is zero, and the equation reduces to +\begin{equation}\label{eq:covhatVtWt3} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\hatVt|\YY^{(1)}],\E[\hatWt|\YY^{(1)}]]. +\end{equation} +Notice that $\E[\hatWt|\yy^{(1)}]=\E[\WW_t|\yy^{(1)}]$ and $\E[\hatVt|\yy^{(1)}]=\E[\VV_t|\yy^{(1)}]$ since +\begin{equation} +\E[\WW_t|\yy^{(1)}]= \E[\XX_t|\yy^{(1)}]-\BB_t\E[\XX_{t-1}|\yy^{(1)}] - \uu_t = \hatxtT-\BB_t\hatxtmT - \uu_t = \hatwt = \E[\hatWt|\yy^{(1)}] +\end{equation} +and +\begin{equation} +\E[\VV_t|\yy^{(1)}]= \E[\YY_t|\yy^{(1)}]-\ZZ_t\E[\XX_{t}|\yy^{(1)}] - \aa_t = \E[\YY_t|\yy^{(1)}]-\ZZ_t \hatxtT - \aa_t = \E[\hatVt|\yy^{(1)}] . +\end{equation} +Thus the right side of Equation \ref{eq:covhatVtWt3} can be written in terms of $\VV_t$ and $\WW_t$ instead of $\hatVt$ and $\hatWt$: +\begin{equation}\label{eq:covhatVtWt2} +\cov[\hatVt,\hatWt] = \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]]. +\end{equation} + +Using the law of total covariance, we can write: +\begin{equation}\label{eq:covVtWt} +\cov[\VV_t, \WW_t] = \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] + \cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] . +\end{equation} +The unconditional covariance of $\VV_t$ and $\WW_t$ is 0. Thus the left side of Equation \ref{eq:covVtWt} is 0 and we can rearrange the equation as +\begin{equation}\label{eq:covVtWt2} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_t|\YY^{(1)}]] = - \E_{Y^{(1)}}[\cov[\VV_t, \WW_t|\YY^{(1)}]] . +\end{equation} +Combining Equation \ref{eq:covhatVtWt2} and \ref{eq:covVtWt2}, we get +\begin{equation}\label{eq:conditionalcovvtwt} +\cov[\hatVt,\hatWt] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ] , +\end{equation} +and our problem reduces to solving for the conditional covariance of the model and state residuals (right side of Equation \ref{eq:conditionalcovvtwt}). + +For a specific $\YY^{(1)}=\yy^{(1)}$, the conditional covariance $\cov[\VV_t, \WW_t|\yy^{(1)}]$ can be written out as +\begin{equation} +\cov[\VV_t, \WW_t|\yy^{(1)}] = \cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_t-\BB_t\XX_{t-1}-\uu_t|\yy^{(1)}] . +\end{equation} +$\aa_t$ and $\uu_t$ are fixed values and can be dropped. Thus\footnote{$\cov[\BB \mathbf{A},\CC \mathbf{D}]=\BB\cov[\mathbf{A},\mathbf{D}]\CC^\top$.} +\begin{equation} +\begin{split} +\cov&[\VV_t, \WW_t|\yy^{(1)}] =\cov[\YY_t-\ZZ_t\XX_t, \XX_t-\BB_t\XX_{t-1}|\yy^{(1)}] \\ +& =\cov[\YY_t,\XX_t|\yy^{(1)}] + \cov[\YY_t,-\BB_t\XX_{t-1}|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,\XX_t|\yy^{(1)}] + \cov[-\ZZ_t\XX_t,-\BB_t\XX_{t-1}|\yy^{(1)}]\\ +& = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top , +\end{split} +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$ and $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$; the equations for $\hatStT$ and $\hatSttmT$ are given in \citet{Holmes2010} and are output by the \verb@MARSShatyt()@ function in the \{MARSS\} package. + +Both $\VV_t$ and $\WW_t$ are multivariate normal random variables that depend on $\YY^{(1)}$ and $\YY^{(2)}$ and the conditional covariance is not a function of the variable that we condition on (in this case $\yy^{(1)}$). The conditional covariance is only a function of the MARSS parameters\footnote{By extension, this is also the case for $\hatVtT$, $\hatVttmT$, $\hatStT$ and $\hatSttmT$ which may seem counter-intuitive, but you can show it is true by working through the Kalman filter and smoother equations starting at t=1. Or run a Kalman filter/smoother algorithm with different data and the same parameters and you will see that the variances do not change with different data.}. Thus +\begin{equation} +\E_{Y^{(1)}}[ \cov[\VV_t, \WW_t|\YY^{(1)}] ]= \cov[\VV_t, \WW_t|\yy^{(1)}] = \hatStT - \hatSttmT\BB_t^\top - \ZZ_t \hatVtT + \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} +$\cov[\hatVt,\hatWt]$ is the negative of this (Equation \ref{eq:conditionalcovvtwt}), thus +\begin{equation} +\cov[\hatVt,\hatWt] = - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t \hatVtT - \ZZ_t\hatVttmT\BB_t^\top . +\end{equation} + +The Harvey et al. algorithm (next section) gives the joint distribution of the model residuals at time $t$ and state residuals at time $t+1$. Using the law of total covariance as above, the covariance in this case is +\begin{equation} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] +\end{equation} +and +\begin{equation} +\begin{split} +\cov[\VV_t, \WW_{t+1}|\yy^{(1)}] & =\cov[\YY_t-\ZZ_t\XX_t-\aa_t,\, \XX_{t+1}-\BB_{t+1}\XX_t-\uu_{t+1}|\yy^{(1)}] \\ +& =\cov[\YY_t-\ZZ_t\XX_t,\, \XX_{t+1}-\BB_{t+1}\XX_t|\yy^{(1)}] \\ +& = \hatSttpT - \hatStT\BB_{t+1}^\top - \ZZ_t\hatVttpT + \ZZ_t \hatVtT \BB_{t+1}^\top . +\end{split} +\end{equation} +Thus, +\begin{equation} +\begin{split} +\cov_{Y^{(1)}}[\E[\VV_t|\YY^{(1)}],\E[\WW_{t+1}|\YY^{(1)}]] & = - \E_{Y^{(1)}}[ \cov[\VV_t, \WW_{t+1}|\YY^{(1)}] ] \\ +& = - \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top. +\end{split} +\end{equation} + + +\subsection{Joint distribution of the conditional residuals} + +We now can write the variance of the joint distribution of the conditional residuals. Define +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwt\end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtT - \BB_t\hatxtmT - \uu_t \end{bmatrix}. +\end{equation} +$\widehat{\varepsilon}_t$ is a sample drawn from the distribution of the random variable $\widehat{\mathcal{E}}_t$. The expected value of $\widehat{\mathcal{E}}_t$ over all possible $\yy$ is 0 and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} +\widehat{\Sigma}_t = \var[\widehat{\mathcal{E}}_t] = \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWt] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWt])^\top& + \var[\hatWt] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid1general} + \begin{bmatrix}[c|c] + \RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top+\ZZ_t(\hatStT)^\top& + - \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top\\ + \rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ + (- \hatStT + \hatSttmT\BB_t^\top + \ZZ_t\hatVtT - \ZZ_t\hatVttmT\BB_t^\top)^\top& + \QQ_t - \hatVtT - \BB_t\hatVtmT\BB_t^\top + \hatVttmT\BB_t^\top + \BB_t\hatVtmtT \end{bmatrix}, +\end{equation} +where $\hatStT=\cov[\YY_t,\XX_t|\yy^{(1)}]$, $\hatSttmT=\cov[\YY_t,\XX_{t-1}|\yy^{(1)}]$, $\hatVtT=\var[\XX_t|\yy^{(1)}]$, $\hatVttmT=\cov[\XX_t,\XX_{t-1}|\yy^{(1)}]$, and $\hatVtmtT=\cov[\XX_{t-1},\XX_t|\yy^{(1)}]$. This gives the variance of both `observed' model residuals (the ones associated with $\yy^{(1)}$) and the unobserved model residuals (the ones associated with $\yy^{(2)}$). +When there are no missing values in $\yy_t$, the $\hatStT$ and $\hatSttmT$ terms equal 0 and drop out. + +If the residuals are defined as in \citet{Harveyetal1998} with $\hatvt$ on top and $\hatwtp$ on the bottom instead of $\hatwt$, then +\begin{equation} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} = +\begin{bmatrix}\yy_t - \ZZ_t\hatxtT - \aa_t\\ \hatxtpT - \BB_{t+1}\hatxtT - \uu_{t+1} \end{bmatrix} +\end{equation} +and the variance of $\widehat{\mathcal{E}}_t$ is +\begin{equation} + \begin{bmatrix}[c|c] + \var[\hatVt]& + \cov[\hatVt, \hatWtp] \\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ + (\cov[\hatVt, \hatWtp])^\top& + \var[\hatWtp] \end{bmatrix} +\end{equation} +which is +\begin{equation}\label{eq:jointcondresid2} +\begin{bmatrix}[c|c] +\RR_t - \ZZ_t\hatVtT\ZZ_t^\top + \hatStT\ZZ_t^\top + \ZZ_t(\hatStT)^\top& +- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top \\ +\rule[.5ex]{40ex}{0.25pt} & \rule[.5ex]{50ex}{0.25pt} \\ +(- \hatSttpT + \hatStT\BB_{t+1}^\top + \ZZ_t\hatVttpT - \ZZ_t\hatVtT\BB_{t+1}^\top)^\top& +\QQ_{t+1} - \hatVtpT - \BB_{t+1}\hatVtT\BB_{t+1}^\top + \hatVtptT \BB_{t+1}^\top + \BB_{t+1}\hatVttpT \end{bmatrix} . +\end{equation} + + + +\section{Harvey et al. 1998 algorithm for the conditional residuals} +\citet[pgs 112-113]{Harveyetal1998} give a recursive algorithm for computing the variance of the conditional residuals when the time-varying MARSS equation is written as: +\begin{equation}\label{eq:residsMARSSHarvey} +\begin{gathered} +\xx_{t+1} = \BB_{t+1}\xx_t + \uu_{t+1} + \HH_{t+1}\epsilon_{t},\\ +\yy_t = \ZZ_t\xx_t + \aa_t + \GG_t\epsilon_t,\\ +\mbox{ where } \epsilon_t \sim \MVN(0,\II_{m+n \times m+n}) \\ +\HH_t\HH_t^\top=\QQ_t, \GG_t\GG_t^\top=\RR_t, \text{ and } \HH_t\GG_t^\top = \cov[\WW_t, \VV_t] +\end{gathered} +\end{equation} +The $\HH_t$ and $\GG_t$ matrices specify the variance and covariance of $\WW_t$ and $\VV_t$. $\HH_t$ has $m$ rows and $m+n$ columns and $\GG_t$ has $n$ rows and $m+n$ columns. In the MARSS equation for this report (Equation \ref{eq:residsMARSS}), $\WW_t$ and $\VV_t$ are independent. To achieve this in the Harvey et al. form (Equation \ref{eq:residsMARSSHarvey}), the first $n$ columns of $\HH_t$ are all 0 and the last $m$ columns of $\GG_t$ are all zero. + +The algorithm in \citet{Harveyetal1998} gives the variance of the `normalized' residuals, the $\epsilon_t$. I have modified their algorithm so it returns the `non-normalized' residuals: +$$\varepsilon_t=\begin{bmatrix}\GG_t\epsilon_t\\ \HH_{t+1}\epsilon_t\end{bmatrix}=\begin{bmatrix}\vv_t\\ \ww_{t+1} \end{bmatrix}.$$ + +The Harvey et al. algorithm is a backwards recursion using the following output from the Kalman filter: the one-step ahead prediction covariance $\FF_t$, the Kalman gain $\KK_t$, $\hatxttm=\E[\XX_t|\yy^{(1),1:{t-1}}]$ and $\hatVttm=\var[\XX_t|\yy^{(1),1:{t-1}}]$. In the \{MARSS\} package, these are output from \texttt{MARSSkfss()} in \texttt{Sigma}, \texttt{Kt}, \texttt{xtt1} and \texttt{Vtt1}. + +\subsection{Algorithm for the non-normalized residuals} + +Start from $t=T$ and work backwards to $t=1$. At time $T$, $r_T=0_{1 \times m}$ and $N_T=0_{m \times m}$. $\BB_{t+1}$ and $\QQ_{t+1}$ can be set to NA or 0. They will not appear in the algorithm at time $T$ since $r_T=0$ and $N_T=0$. Note that the $\ww$ residual and its associated variance and covariance with $\vv$ at time $T$ is NA since this residual would be for $\xx_T$ to $\xx_{T+1}$. + +% algorithm with \GG_t and \HH_t +% \begin{equation}\label{eq:Harveyalgo} +% \begin{gathered} +% \FF_t = \ZZ_t\hatVt\ZZ_t^\top+\RR_t\\ +% G_t= \GG_t\QQ_t\GG_t^\top, \mbox{ }H_t = \HH_t\RR_t\HH_t^\top, \mbox{ } K_t = \BB_t\KK^{*}_t\\ +% L_t = \BB_t - K_t\ZZ_t, \mbox{ } J_t= H_t - K_t G_t, \mbox{ } u_t = \FF_t^{-1} - K_t^\top r_t\\ +% r_{t-1} = \ZZ_t^\top u_t + \BB_t^\top r_t, \mbox{ } N_{t-1} = K_t^\top N_t K_t + L_t^\top N_t L_t +% \end{gathered} +% \end{equation} + +\begin{equation}\label{eq:Harveyalgo} +\begin{gathered} +\QQ^\prime_{t+1}=\begin{bmatrix}0_{m \times n}&\QQ_{t+1}\end{bmatrix}, \mbox{ } \RR^\prime_t=\begin{bmatrix}\RR_t^* & 0_{n \times m}\end{bmatrix}\\ +\FF_t = \ZZ_t^*\hatVttm{\ZZ_t^*}^\top+\RR_t^* , \,\, n \times n \\ +K_t = \BB_{t+1}\KK_t = \BB_{t+1} \hatVttm{\ZZ_t^*}^\top \FF_t^{-1} , \,\, m \times n \\ +L_t = \BB_{t+1} - K_t\ZZ_t^* , \,\, m \times m \\ +J_t= \QQ^\prime_{t+1} - K_t \RR^\prime_t , \,\, m \times (n+m) \\ +v_t = \yy_t^* - \ZZ_t\hatxttm - \aa_t , \,\, n \times 1 \\ +u_t = \FF_t^{-1} v_t - K_t^\top r_t , \,\, n \times 1 \\ +r_{t-1} = {\ZZ_t^*}^\top u_t + \BB_{t+1}^\top r_t , \,\, m \times 1 \\ +N_{t-1} = {\ZZ_t^*}^\top \FF_t^{-1} \ZZ_t^* + L_t^\top N_t L_t , \,\, m \times m . +\end{gathered} +\end{equation} +$\yy_t^*$ is the observed data at time $t$ with the $i$-th rows set to 0 if the $i$-th $y$ is missing. +Bolded terms are the same as in Equation \ref{eq:residsMARSSHarvey} (and are output by \texttt{MARSSkfss()}). Unbolded terms are terms used in \citet{Harveyetal1998}. The * on $\ZZ_t$ and $\RR_t$, indicates that they are the missing value modified versions discussed in \citet[section 6.4]{ShumwayStoffer2006} and \citet{Holmes2010}: to construct $\ZZ_t^*$ and $\RR_t^*$, the rows of $\ZZ_t$ corresponding to missing rows of $\yy_t$ are set to zero and the $(i,j)$ and $(j,i)$ terms of $\RR_t$ corresponding the missing rows of $\yy_t$ are set to zero. For the latter, this means if the $i$-th row of $\yy_t$ is missing, then then the $i$-th row and column (including the value on the diagonal) in $\RR_t$ are set to 0. Notice that $\FF_t$ will have 0's on the diagonal if there are missing values. A modified inverse of $\FF_t$ is used: any 0's on the diagonal of $\FF_t$ are replaced with 1, the inverse is taken, and 1s on diagonals is replaced back with 0s. + +The residuals \citep[eqn 24]{Harveyetal1998} are +\begin{equation}\label{eq:Harveyresiduals} +\widehat{\varepsilon}_t = \begin{bmatrix}\hatvt\\ \hatwtp \end{bmatrix} =({\RR^\prime_t})^\top u_t + ({\QQ^\prime_{t+1}})^\top r_t +\end{equation} +The expected value of $\widehat{\mathcal{E}}_t$ is 0 and its variance is +\begin{equation}\label{eq:Harveyvariance} +\widehat{\Sigma]}_t = \var[\widehat{\mathcal{E}}_t] ={\RR^\prime_t}^\top \FF_t^{-1} \RR^\prime_t + J_t^\top N_t J_t . +\end{equation} +These $\widehat{\varepsilon}_t$ and $\widehat{\Sigma]}_t$ are for both the non-missing and missing $\yy_t$. This is a modification to the \citet{Harveyetal1998} algorithm which does not give the variance for missing $\yy$. + +\subsection{Difference in notation} + +In Equation 20 in \citet{Harveyetal1998}, their $T_t$ is my $\BB_{t+1}$ and their $H_t H_t^\top$ is my $\QQ_{t+1}$. Notice the difference in the time indexing. My time indexing on $\BB$ and $\QQ$ matches the left $\xx$ while in theirs, $T$ and $H$ indexing matches the right $\xx$. Thus in my implementation of their algorithm \citep[eqns. 21-24]{Harveyetal1998}, $\BB_{t+1}$ appears in place of $T_t$ and $\QQ_{t+1}$ appears in place of $H_t$. See comments below on normalization and the difference between $\QQ$ and $H$. + +\citet[eqns. 19, 20]{Harveyetal1998} use $G_t$ to refer to the $\chol(\RR_t)^\top$ (non-zero part of the $n \times n+m$ matrix) and $H_t$ to refer to $\chol(\QQ_t)^\top$. I have replaced these with $\RR_t^\prime$ and $\QQ_t^\prime$ (Equation \ref{eq:Harveyalgo}) which causes my variant of their algorithm (Equation \ref{eq:Harveyalgo}) to give the `non-normalized' variance of the residuals. The residuals function in the \{MARSS\} package has an option to give either normalized or non-normalized residuals. + +$\KK_t$ is the Kalman gain output by the \{MARSS\} package \verb@MARSSkf()@ function. The Kalman gain as used in the \citet{Harveyetal1998} algorithm is $K_t=\BB_{t+1}\KK_t$. Notice that Equation 21 in \citet{Harveyetal1998} has $H_t G_t^\top$ in the equation for $K_t$. This is the covariance of the state and observation errors, which is allowed to be non-zero given the way Harvey et al. write the errors in their Equations 19 and 20. The way the \{MARSS\} package model is written, the state and observation errors are independent of each other. Thus $H_t G_t^\top = 0$ and this term drops out of the $K_t$ equation in Equation \ref{eq:Harveyalgo}. + +\subsection{Computing the normalized residuals} + +To compute the normalized residuals and residuals variance, a block diagonal matrix with the inverse of the $\RR$ and $\QQ$ matrices is used. The normalized residuals are: +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\varepsilon}_t +\end{equation} +The variance of the normalized residuals is +\begin{equation} +\begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} \widehat{\Sigma]}_t \begin{bmatrix}\RR^{-1}_t&0\\0&\QQ^{-1}_t\end{bmatrix} +\end{equation} + +\subsection{Computing the Cholesky standardized residuals} + +The Cholesky standardized residuals are computed by multiplying $\widehat{\varepsilon}_t$ by $(\widehat{\Sigma}_t)^{-1/2}$ (the inverse of the Cholesky decomposition of the variance-covariance matrix for $\widehat{\varepsilon}_t$): +\begin{equation}\label{eq:std.resid} +\widehat{\varepsilon}_{t, std} = (\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t . +\end{equation} +These residuals are uncorrelated (across the residuals at time $t$ in $\widehat{\varepsilon}_t$). See \citet{HarveyKoopman1992} and \citet[section V]{Harveyetal1998} for a discussion on how to use these residuals for outlier detection and structural break detection. + +It is also common to use the marginal standardized residuals, which would be $\widehat{\varepsilon}_t$ multiplied by the inverse of the square-root of $\dg(\widehat{\Sigma}_t)$, where $\dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. +\begin{equation} +\widehat{\varepsilon}_{t, mar} = \dg(\widehat{\Sigma}_t)^{-1/2}\widehat{\varepsilon}_t +\end{equation} +Marginal standardized residuals may be correlated at time $t$ (unlike the Cholesky standardized residuals) but are a bit easier to interpret when there is correlation across the model residuals. + +\section{Distribution of the MARSS innovation residuals} + +One-step-ahead predictions (innovations) are often shown for MARSS models and these are used for likelihood calculations. Innovations are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t-1$. This section gives the residual variance for the innovations and the analogous values for the states. Innovations residuals are the more common residuals discussed for state-space models; these are also known as the `one-step-ahead` prediction residuals. + +\subsection{One-step-ahead model residuals} + +Define the innovations $\checkvt$ as: +\begin{equation}\label{eq:vtt1} +\checkvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxttm - \aa_t, +\end{equation} +where $\hatxttm$ is $\E[\XX_t|\yy^{(1),t-1}]$ (expected value of $\XX_t$ conditioned on the data up to time $t-1$). The random variable, innovations over all possible $\yy_t$, is $\checkVt$. Its mean is 0 and we want to find its variance. + +This is conceptually different than the observed `innovations'. First, this is the random variable `innovation'. $\yy^{(1)}_t$ here is not the actual data that you observe (the one data set that you have). It's the data that you could observe. $\yy_t$ is a sample from the random variable $\YY_t$ and $\checkvt$ is a sample from the innovations you could observe. Second, $\checkvt$ includes both $\yy_t^{(1)}$ and $\yy_t^{(2)}$ (observed and unobserved $\yy$). Normally, the innovations for missing data would appear as 0s, e.g., from a call to \verb@MARSSfss()@. For missing data, $\checkvt$ is not necessarily 0. For example if $\yy$ is multivariate and correlated with each other through $\RR$ or a shared $\xx$ dependency. + +The derivation of the variance of $\checkVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t-1$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:innov.model} +\var[\checkVt] = \RR_t - \ZZ_t \hatVttm \ZZ_t^\top + \hatSttm\ZZ_t^\top + \ZZ_t(\hatSttm)^\top +\end{equation} +where the $\hatVttm$ and $\hatSttm$ are now conditioned on only the data from 1 to $t-1$. +$\hatSttm = \cov[\YY_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t-1}]$. +$\yy_t$ is not in the conditional since it only includes data up to $t-1$. Without $\yy_t$ in the conditional, $\VV_t$ and $\WW_t$ and by extension $\VV_t$ and $\XX_t$ are independent\footnote{This is only true given the way the MARSS equation is written in this report where $V_t$ and $W_t$ are independent. This is not the case for the more general Harvey et al. MARSS model which allows covariance between $V_t$ and $W_t$.} and $\cov[\ZZ_t \XX_t + \aa_t + \VV_t,\XX_t|\yy^{(1), t-1}] = \cov[\ZZ_t \XX_t,\XX_t|\yy^{(1), t-1}] = \ZZ_t \hatVttm$. Therefore, $\ZZ_t(\hatSttm)^\top = \ZZ_t \hatVttm \ZZ_t^\top = \hatSttm(\ZZ_t)^\top$. Thus Equation \ref{eq:innov.model} reduces to +\begin{equation}\label{eq:innov.model2} +\var[\checkVt] = \RR_t + \ZZ_t \hatVttm \ZZ_t^\top. +\end{equation} + +Note $\var[\checkVt]$ is a standard output from Kalman filter functions and is used to compute the likelihood of the data (conditioned on a set of parameters). In the Kalman filter in the \{MARSS\} package, it is output as \texttt{Sigma} from \texttt{MARSSkfss()}. + + +\subsection{One-step ahead state residuals} + +Define the state residuals conditioned on the data from 1 to $t-1$ as $\checkwt$. +\begin{equation}\label{eq:wtt1} +\checkwt = \hatxtt - \BB_t\hatxtmt1 - \uu_t, +\end{equation} +where $\hatxtmt1$ is $\E[\XX_{t-1}|\yy^{(1),t-1}]$ (expected value of $\XX_{t-1}$ conditioned on the data up to time $t-1$) and $\hatxtt$ is $\E[\XX_{t}|\yy^{(1),t}]$ (expected value of $\XX_{t}$ conditioned on the data up to time $t$). +From the Kalman filter equations: +\begin{equation}\label{eq:wtt1.2} +\hatxtt = \BB_t\hatxtmt1 + \uu_t + \KK_t \checkvt +\end{equation} +Thus, $\checkwt$ is a transformed $\checkvt$: +\begin{equation}\label{eq:wtt1.3} +\checkwt = \KK_t \checkvt, +\end{equation} +where $\KK_t$ is the Kalman gain. $\KK_t = \hatVttm \ZZ_t^\top[\ZZ_t \hatVttm \ZZ_t^\top + \RR_t]^{-1}$ and $\ZZ_t$ is the missing values modified $\ZZ_t$ where if the $i$-th $\yy_t$ is missing, the $i$-th row of $\ZZ_t$ is set to all 0s (Shumway and Stoffer 2006, equation 6.78). +Thus the variance of $\checkWt$ is +\begin{equation}\label{eq:var.Wt} +\var[\checkWt] = \KK_t \var[\checkVt] \KK_t^\top +\end{equation} + +\subsection{Joint distribution of the conditional one-step-ahead residuals} + +\subsubsection{with the state residuals defined from $t-1$ to $t$} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t = \begin{bmatrix}\checkvt\\ \checkwt \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWt$ is +\begin{equation}\label{eq:covhatVtWtp.onestep} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t}\checkVt] = \var[\checkVt]\KK_{t}^\top +\end{equation} + + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep} +\overline{\Sigma}_t = \var[\overline{\varepsilon}_t] = \begin{bmatrix}[c|c] + \var[\checkVt]& \var[\checkVt]\KK_{t}^\top\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +\KK_{t}\var[\checkVt]& \KK_{t}\var[\checkVt]\KK_{t}^\top \end{bmatrix}, +\end{equation} + +Since $\checkwt=\KK_t \checkvt$, the state one-step-ahead residuals are perfectly correlated with the model one-step-ahead residuals so the joint distribution is not useful (all the information is in the variance of $\checkVt$). + + +The Cholesky standardized residuals for $\overline{\varepsilon}_t$ are +\begin{equation} +\overline{\Sigma}_t^{-1/2} \overline{\varepsilon}_t +\end{equation} +However the Cholesky standardized joint residuals cannot be computed since $\overline{\Sigma}_t$ is not positive definite. Because $\checkwt$ equals $\KK_t \checkvt$, the state residuals are completely explained by the model residuals. However we can compute the Cholesky standardized model residuals using +\begin{equation} +\var[\checkVt]^{-1/2} \checkvt +\end{equation} +$\var[\checkVt]^{-1/2}$ is the inverse of the lower triangle of the Cholesky decomposition of $\var[\checkVt]$. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t$ (both model and state one-step ahead residuals) can be computed with the inverse of the square root of the diagonal of $\overline{\Sigma}_t$: +\begin{equation} +\dg(\overline{\Sigma}_t)^{-1/2} \overline{\varepsilon}_t +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\subsubsection{with the state residuals defined from $t$ to $t+1$} + +\emph{Note that the model residual is conditioned on data 1 to $t-1$ and the state residual on data 1 to $t$ in this case.} + +Define the one-step ahead residuals as +\begin{equation} +\overline{\varepsilon}_t^* = \begin{bmatrix}\checkvt\\ \checkwtp \end{bmatrix} +\end{equation} + +The covariance of $\checkVt$ and $\checkWtp$ is +\begin{equation}\label{eq:covhatVtWtp.onestep.2} +\cov[\checkVt,\checkWtp] = \cov[\checkVt,\KK_{t+1}\checkVtp] = \cov[\checkVt, \checkVtp]\KK_{t+1}^\top +\end{equation} +Innovations residuals are temporally uncorrelated, thus $\cov[\checkVt,\checkVtp]=0$ and thus $\cov[\checkVt,\checkWtp]=0$. + +The joint variance-covariance matrix is +\begin{equation}\label{eq:jointcondresid.onestep2} +\overline{\Sigma}_t^* = \var[\overline{\varepsilon}_t^*] = \begin{bmatrix}[c|c] + \var[\checkVt]& 0\\ + \rule[.5ex]{20ex}{0.25pt} & \rule[.5ex]{20ex}{0.25pt} \\ +0 & \KK_{t+1}\var[\checkVtp]\KK_{t+1}^\top \end{bmatrix}, +\end{equation} + +The Cholesky standardized residuals for $\overline{\varepsilon}_t^*$ are +\begin{equation} +(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} + $\overline{\Sigma}_t^*$ is positive definite so its Cholesky decomposition can be computed. + +The marginal standardized joint residuals for $\overline{\varepsilon}_t^*$ are: +\begin{equation} +\dg(\overline{\Sigma}_t^*)^{-1/2} \overline{\varepsilon}_t^* +\end{equation} +where $dg(\AA)$ is a diagonal matrix formed from the diagonal of the square matrix $\AA$. + +\section{Distribution of the MARSS contemporaneous model residuals} + +Contemporaneous model residuals are the difference between the data at time $t$ minus the prediction of $\yy_t$ given data up to $t$. This section gives the residual variance for these residuals. There are no state residuals for this case as that would require the expected value of $\XX_t$ conditioned on the data up to $t+1$. + +Define the contemporaneous model residuals $\dotvt$ as: +\begin{equation}\label{eq:vtt} +\dotvt = E[\YY_t|\yy^{(1)}_t] - \ZZ_t\hatxtt - \aa_t, +\end{equation} +where $\hatxtt$ is $\E[\XX_t|\yy^{(1),t}]$ (expected value of $\XX_t$ conditioned on the data up to time $t$). The random variable, contemporaneous model residuals over all possible $\yy_t$, is $\dotVt$. Its mean is 0 and we want to find its variance. + +The derivation of the variance of $\dotVt$ follows the exact same steps as the smoothations $\hatVt$, except that we condition on the data up to $t$ not up to $T$. Thus using Equation \ref{eq:first.and.secons.vvtgeneral}, we can write the variance directly as: +\begin{equation}\label{eq:contemp.model} +\var[\dotVt] = \RR_t - \ZZ_t \hatVtt \ZZ_t^\top + \hatStt\ZZ_t^\top + \ZZ_t(\hatStt)^\top +\end{equation} +where the $\hatVtt$ and $\hatStt$ are now conditioned on only the data from 1 to $t$. +$\hatStt = \cov[\YY_t,\XX_t|\yy^{(1), t}] = \cov[\ZZ_t \XX_t + \aa_t+\VV_t,\XX_t|\yy^{(1), t}]$. +If $\yy_t$ has no missing values, this reduces to $\RR_t - \ZZ_t \hatVtt \ZZ_t^\top$ while if $\yy_t$ is all missing values, this reduces to $\RR_t + \ZZ_t \hatVtt \ZZ_t^\top$. See discussion of this after Equation \ref{eq:first.and.secons.vvtgeneral}. + +Equation \ref{eq:contemp.model} gives the equation for the case where $\yy_t$ is partially observed. $\hatStt$ is output by the \verb@MARSShatyt()@ function in the \{MARSS\} package and $\hatVtt$ is output by the \verb@MARSSkfss()@ function. + +\bibliography{./EMDerivation} +\bibliographystyle{apalike} + +\end{document} diff --git a/vignettes/UserGuide.aux b/vignettes/UserGuide.aux new file mode 100644 index 0000000..04ae2f6 --- /dev/null +++ b/vignettes/UserGuide.aux @@ -0,0 +1,16 @@ +\relax +\providecommand\hyper@newdestlabel[2]{} +\providecommand\HyperFirstAtBeginDocument{\AtBeginDocument} +\HyperFirstAtBeginDocument{\ifx\hyper@anchor\@undefined +\global\let\oldnewlabel\newlabel +\gdef\newlabel#1#2{\newlabelxx{#1}#2} +\gdef\newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}} +\AtEndDocument{\ifx\hyper@anchor\@undefined +\let\newlabel\oldnewlabel +\fi} +\fi} +\global\let\hyper@last\relax +\gdef\HyperFirstAtBeginDocument#1{#1} +\providecommand\HyField@AuxAddToFields[1]{} +\providecommand\HyField@AuxAddToCoFields[2]{} +\gdef \@abspage@last{335} diff --git a/vignettes/UserGuide.log b/vignettes/UserGuide.log new file mode 100644 index 0000000..557a77a --- /dev/null +++ b/vignettes/UserGuide.log @@ -0,0 +1,5671 @@ +This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex 2023.5.14) 19 MAY 2023 23:06 +entering extended mode + restricted \write18 enabled. + %&-line parsing enabled. +**\input ./UserGuide.tex \input ./UserGuide.tex + (./UserGuide.tex (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/article.cls +Document Class: article 2022/07/02 v1.4n Standard LaTeX document class +(/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/size10.clo +File: size10.clo 2022/07/02 v1.4n Standard LaTeX file (size option) +) +\c@part=\count185 +\c@section=\count186 +\c@subsection=\count187 +\c@subsubsection=\count188 +\c@paragraph=\count189 +\c@subparagraph=\count190 +\c@figure=\count191 +\c@table=\count192 +\abovecaptionskip=\skip48 +\belowcaptionskip=\skip49 +\bibindent=\dimen140 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hyperref/hyperref.sty +Package: hyperref 2023-04-22 v7.00x Hypertext links for LaTeX + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/ltxcmds/ltxcmds.sty +Package: ltxcmds 2020-05-10 v1.25 LaTeX kernel commands for general use (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/iftex/iftex.sty +Package: iftex 2022/02/03 v1.0f TeX engine tests +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/pdftexcmds/pdftexcmds.sty +Package: pdftexcmds 2020-06-27 v0.33 Utility functions of pdfTeX for LuaTeX (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/infwarerr/infwarerr.sty +Package: infwarerr 2019/12/03 v1.5 Providing info/warning/error messages (HO) +) +Package pdftexcmds Info: \pdf@primitive is available. +Package pdftexcmds Info: \pdf@ifprimitive is available. +Package pdftexcmds Info: \pdfdraftmode found. +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/keyval.sty +Package: keyval 2022/05/29 v1.15 key=value parser (DPC) +\KV@toks@=\toks16 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvsetkeys/kvsetkeys.sty +Package: kvsetkeys 2022-10-05 v1.19 Key value parser (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/kvdefinekeys/kvdefinekeys.sty +Package: kvdefinekeys 2019-12-19 v1.6 Define keys (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/pdfescape/pdfescape.sty +Package: pdfescape 2019/12/09 v1.15 Implements pdfTeX's escape features (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hycolor/hycolor.sty +Package: hycolor 2020-01-27 v1.10 Color options for hyperref/bookmark (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/letltxmacro/letltxmacro.sty +Package: letltxmacro 2019/12/03 v1.6 Let assignment for LaTeX macros (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/auxhook/auxhook.sty +Package: auxhook 2019-12-17 v1.6 Hooks for auxiliary files (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hyperref/nameref.sty +Package: nameref 2022-05-17 v2.50 Cross-referencing by name of section + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/refcount/refcount.sty +Package: refcount 2019/12/15 v3.6 Data extraction from label references (HO) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/gettitlestring/gettitlestring.sty +Package: gettitlestring 2019/12/15 v1.6 Cleanup title references (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/kvoptions/kvoptions.sty +Package: kvoptions 2022-06-15 v3.15 Key value format for package options (HO) +)) +\c@section@level=\count193 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/etoolbox/etoolbox.sty +Package: etoolbox 2020/10/05 v2.5k e-TeX tools for LaTeX (JAW) +\etb@tempcnta=\count194 +) +\@linkdim=\dimen141 +\Hy@linkcounter=\count195 +\Hy@pagecounter=\count196 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hyperref/pd1enc.def +File: pd1enc.def 2023-04-22 v7.00x Hyperref: PDFDocEncoding definition (HO) +Now handling font encoding PD1 ... +... no UTF-8 mapping file for font encoding PD1 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/intcalc/intcalc.sty +Package: intcalc 2019/12/15 v1.3 Expandable calculations with integers (HO) +) +\Hy@SavedSpaceFactor=\count197 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hyperref/puenc.def +File: puenc.def 2023-04-22 v7.00x Hyperref: PDF Unicode definition (HO) +Now handling font encoding PU ... +... no UTF-8 mapping file for font encoding PU +) +Package hyperref Info: Hyper figures OFF on input line 4182. +Package hyperref Info: Link nesting OFF on input line 4187. +Package hyperref Info: Hyper index ON on input line 4190. +Package hyperref Info: Plain pages OFF on input line 4197. +Package hyperref Info: Backreferencing OFF on input line 4202. +Package hyperref Info: Implicit mode ON; LaTeX internals redefined. +Package hyperref Info: Bookmarks ON on input line 4449. +\c@Hy@tempcnt=\count198 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/url/url.sty +\Urlmuskip=\muskip16 +Package: url 2013/09/16 ver 3.4 Verb mode for urls, etc. +) +LaTeX Info: Redefining \url on input line 4787. +\XeTeXLinkMargin=\dimen142 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/bitset/bitset.sty +Package: bitset 2019/12/09 v1.3 Handle bit-vector datatype (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/bigintcalc/bigintcalc.sty +Package: bigintcalc 2019/12/15 v1.5 Expandable calculations on big integers (HO) +)) +\Fld@menulength=\count199 +\Field@Width=\dimen143 +\Fld@charsize=\dimen144 +Package hyperref Info: Hyper figures OFF on input line 6066. +Package hyperref Info: Link nesting OFF on input line 6071. +Package hyperref Info: Hyper index ON on input line 6074. +Package hyperref Info: backreferencing OFF on input line 6081. +Package hyperref Info: Link coloring OFF on input line 6086. +Package hyperref Info: Link coloring with OCG OFF on input line 6091. +Package hyperref Info: PDF/A mode OFF on input line 6096. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/atbegshi-ltx.sty +Package: atbegshi-ltx 2021/01/10 v1.0c Emulation of the original atbegshi +package with kernel methods +) +\Hy@abspage=\count266 +\c@Item=\count267 +\c@Hfootnote=\count268 +) +Package hyperref Info: Driver (autodetected): hpdftex. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/hyperref/hpdftex.def +File: hpdftex.def 2023-04-22 v7.00x Hyperref driver for pdfTeX + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/atveryend-ltx.sty +Package: atveryend-ltx 2020/08/19 v1.0a Emulation of the original atveryend package +with kernel methods +) +\Fld@listcount=\count269 +\c@bookmark@seq@number=\count270 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/rerunfilecheck/rerunfilecheck.sty +Package: rerunfilecheck 2022-07-10 v1.10 Rerun checks for auxiliary files (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/generic/uniquecounter/uniquecounter.sty +Package: uniquecounter 2019/12/15 v1.4 Provide unlimited unique counter (HO) +) +Package uniquecounter Info: New unique counter `rerunfilecheck' on input line 285. +) +\Hy@SectionHShift=\skip50 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/pdfpages/pdfpages.sty +Package: pdfpages 2022/12/19 v0.5x Insert pages of external PDF documents (AM) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/ifthen.sty +Package: ifthen 2022/04/13 v1.1d Standard LaTeX ifthen package (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/tools/calc.sty +Package: calc 2017/05/25 v4.3 Infix arithmetic (KKT,FJ) +\calc@Acount=\count271 +\calc@Bcount=\count272 +\calc@Adimen=\dimen145 +\calc@Bdimen=\dimen146 +\calc@Askip=\skip51 +\calc@Bskip=\skip52 +LaTeX Info: Redefining \setlength on input line 80. +LaTeX Info: Redefining \addtolength on input line 81. +\calc@Ccount=\count273 +\calc@Cskip=\skip53 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/eso-pic/eso-pic.sty +Package: eso-pic 2023/05/03 v3.0c eso-pic (RN) +\ESO@tempdima=\dimen147 +\ESO@tempdimb=\dimen148 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/xcolor/xcolor.sty +Package: xcolor 2022/06/12 v2.14 LaTeX color extensions (UK) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-cfg/color.cfg +File: color.cfg 2016/01/02 v1.6 sample color configuration +) +Package xcolor Info: Driver file: pdftex.def on input line 227. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-def/pdftex.def +File: pdftex.def 2022/09/22 v1.2b Graphics/color driver for pdftex +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/mathcolor.ltx) +Package xcolor Info: Model `cmy' substituted by `cmy0' on input line 1353. +Package xcolor Info: Model `hsb' substituted by `rgb' on input line 1357. +Package xcolor Info: Model `RGB' extended on input line 1369. +Package xcolor Info: Model `HTML' substituted by `rgb' on input line 1371. +Package xcolor Info: Model `Hsb' substituted by `hsb' on input line 1372. +Package xcolor Info: Model `tHsb' substituted by `hsb' on input line 1373. +Package xcolor Info: Model `HSB' substituted by `hsb' on input line 1374. +Package xcolor Info: Model `Gray' substituted by `gray' on input line 1375. +Package xcolor Info: Model `wave' substituted by `hsb' on input line 1376. +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphicx.sty +Package: graphicx 2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/graphics.sty +Package: graphics 2022/03/10 v1.4e Standard LaTeX Graphics (DPC,SPQR) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/trig.sty +Package: trig 2021/08/11 v1.11 sin cos tan (DPC) +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics-cfg/graphics.cfg +File: graphics.cfg 2016/06/04 v1.11 sample graphics configuration +) +Package graphics Info: Driver file: pdftex.def on input line 107. +) +\Gin@req@height=\dimen149 +\Gin@req@width=\dimen150 +) +\AM@pagewidth=\dimen151 +\AM@pageheight=\dimen152 +\AM@fboxrule=\dimen153 + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/pdfpages/pppdftex.def +File: pppdftex.def 2022/12/19 v0.5x Pdfpages driver for pdfTeX (AM) +) +\pdfpages@includegraphics@status=\count274 +\AM@pagebox=\box51 +\AM@global@opts=\toks17 +\AM@pagecnt=\count275 +\AM@toc@title=\toks18 +\AM@lof@heading=\toks19 +\c@AM@survey=\count276 +\AM@templatesizebox=\box52 +) (/Library/Frameworks/R.framework/Resources/share/texmf/tex/latex/Sweave.sty +Package: Sweave + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty +Package: fancyvrb 2023/01/19 4.5a verbatim text (tvz,hv) +\FV@CodeLineNo=\count277 +\FV@InFile=\read2 +\FV@TabBox=\box53 +\c@FancyVerbLine=\count278 +\FV@StepNumber=\count279 +\FV@OutFile=\write3 +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/textcomp.sty +Package: textcomp 2020/02/02 v2.0n Standard LaTeX package +) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/base/fontenc.sty +Package: fontenc 2021/04/29 v2.0v Standard LaTeX package +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/l3backend/l3backend-pdftex.def +File: l3backend-pdftex.def 2023-04-19 L3 backend support: PDF output (pdfTeX) +\l__color_backend_stack_int=\count280 +\l__pdf_internal_box=\box54 +) (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/UserGuide.aux) +\openout1 = `UserGuide.aux'. + +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for PD1/pdf/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +LaTeX Font Info: Checking defaults for PU/pdf/m/n on input line 7. +LaTeX Font Info: ... okay on input line 7. +Package hyperref Info: Link coloring OFF on input line 7. + (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/UserGuide.out) (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/UserGuide.out) +\@outlinefile=\write4 +\openout4 = `UserGuide.out'. + + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/epstopdf-pkg/epstopdf-base.sty +Package: epstopdf-base 2020-01-24 v2.11 Base part for package epstopdf + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/grfext/grfext.sty +Package: grfext 2019/12/03 v1.3 Manage graphics extensions (HO) +) +Package epstopdf-base Info: Redefining graphics rule for `.eps' on input line 485. +Package grfext Info: Graphics extension search list: +(grfext) [.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2,.eps] +(grfext) \AppendGraphicsExtensions on input line 504. + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/latexconfig/epstopdf-sys.cfg +File: epstopdf-sys.cfg 2010/07/13 v1.3 Configuration of (r)epstopdf for TeX Live +)) (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/pdflscape/pdflscape.sty +Package: pdflscape 2022-10-27 v0.13 Display of landscape pages in PDF + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/pdflscape/pdflscape-nometadata.sty +Package: pdflscape-nometadata 2022-10-28 v0.13 Display of landscape pages in PDF (HO) + (/Users/eli.holmes/Library/TinyTeX/texmf-dist/tex/latex/graphics/lscape.sty +Package: lscape 2020/05/28 v3.02 Landscape Pages (DPC) +) +Package pdflscape Info: Auto-detected driver: pdftex on input line 81. +)) + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=4, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf used on input line 8. +(pdftex.def) Requested size: 276.00105pt x 357.1752pt. + + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf used on input line 8. +(pdftex.def) Requested size: 276.00105pt x 357.1752pt. + + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed + + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=7, page=1, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page1 used on input line 8. +(pdftex.def) Requested size: 614.29349pt x 794.96806pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page1 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page1 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page1 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page1 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[1 + + <../inst/doc/UserGuide.pdf{/Users/eli.holmes/Library/TinyTeX/texmf-var/fonts/map/pdftex/updmap/pdftex.map}>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=17, page=2, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page2 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page2 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page2 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[2 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=22, page=3, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page3 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page3 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page3 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[3 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=35, page=4, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page4 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page4 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page4 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[4 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=40, page=5, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page5 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page5 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page5 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[5 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=46, page=6, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page6 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page6 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page6 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[6 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=71, page=7, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page7 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page7 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page7 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[7 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=77, page=8, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page8 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page8 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page8 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[8 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=82, page=9, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page9 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page9 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page9 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[9 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=87, page=10, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page10 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page10 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page10 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[10 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=92, page=11, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page11 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page11 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page11 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[11 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=97, page=12, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page12 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page12 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page12 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[12 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=102, page=13, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page13 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page13 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page13 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[13 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=113, page=14, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page14 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page14 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page14 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[14 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=118, page=15, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page15 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page15 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page15 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[15 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=128, page=16, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page16 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page16 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page16 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[16 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=133, page=17, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page17 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page17 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page17 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[17 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=142, page=18, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page18 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page18 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page18 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[18 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=147, page=19, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page19 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page19 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page19 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[19 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=153, page=20, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page20 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page20 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page20 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[20 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=158, page=21, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page21 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page21 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page21 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[21 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=163, page=22, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page22 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page22 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page22 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[22 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=168, page=23, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page23 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page23 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page23 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[23 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=173, page=24, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page24 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page24 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page24 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[24 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=178, page=25, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page25 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page25 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page25 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[25 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=184, page=26, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page26 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page26 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page26 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[26 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=190, page=27, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page27 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page27 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page27 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[27 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=195, page=28, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page28 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page28 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page28 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[28 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=200, page=29, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page29 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page29 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page29 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[29 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=205, page=30, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page30 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page30 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page30 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[30 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=210, page=31, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page31 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page31 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page31 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[31 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=216, page=32, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page32 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page32 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page32 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[32 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=221, page=33, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page33 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page33 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page33 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[33 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=226, page=34, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page34 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page34 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page34 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[34 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=231, page=35, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page35 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page35 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page35 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[35 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=238, page=36, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page36 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page36 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page36 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[36 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=243, page=37, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page37 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page37 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page37 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[37 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=249, page=38, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page38 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page38 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page38 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[38 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=254, page=39, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page39 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page39 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page39 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[39 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=259, page=40, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page40 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page40 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page40 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[40 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=264, page=41, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page41 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page41 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page41 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[41 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=269, page=42, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page42 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page42 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page42 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[42 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=274, page=43, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page43 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page43 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page43 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[43 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=280, page=44, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page44 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page44 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page44 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[44 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=285, page=45, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page45 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page45 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page45 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[45 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=290, page=46, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page46 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page46 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page46 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[46 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=295, page=47, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page47 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page47 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page47 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[47 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=300, page=48, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page48 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page48 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page48 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[48 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=305, page=49, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page49 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page49 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page49 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[49 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=311, page=50, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page50 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page50 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page50 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[50 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=316, page=51, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page51 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page51 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page51 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[51 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=321, page=52, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page52 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page52 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page52 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[52 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=326, page=53, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page53 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page53 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page53 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[53 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=331, page=54, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page54 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page54 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page54 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[54 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=336, page=55, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page55 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page55 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page55 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[55 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=342, page=56, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page56 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page56 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page56 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[56 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=347, page=57, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page57 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page57 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page57 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[57 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=352, page=58, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page58 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page58 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page58 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[58 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=358, page=59, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page59 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page59 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page59 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[59 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=367, page=60, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page60 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page60 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page60 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[60 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=372, page=61, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page61 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page61 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page61 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[61 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=378, page=62, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page62 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page62 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page62 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[62 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=383, page=63, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page63 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page63 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page63 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[63 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=388, page=64, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page64 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page64 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page64 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[64 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=393, page=65, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page65 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page65 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page65 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[65 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=398, page=66, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page66 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page66 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page66 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[66 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=403, page=67, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page67 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page67 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page67 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[67 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=409, page=68, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page68 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page68 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page68 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[68 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=414, page=69, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page69 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page69 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page69 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[69 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=419, page=70, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page70 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page70 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page70 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[70 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=424, page=71, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page71 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page71 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page71 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[71 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=429, page=72, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page72 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page72 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page72 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[72 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=434, page=73, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page73 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page73 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page73 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[73 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=440, page=74, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page74 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page74 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page74 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[74 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=445, page=75, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page75 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page75 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page75 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[75 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=450, page=76, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page76 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page76 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page76 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[76 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=455, page=77, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page77 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page77 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page77 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[77 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=460, page=78, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page78 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page78 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page78 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[78 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=465, page=79, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page79 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page79 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page79 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[79 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=471, page=80, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page80 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page80 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page80 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[80 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=476, page=81, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page81 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page81 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page81 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[81 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=484, page=82, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page82 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page82 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page82 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[82 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=493, page=83, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page83 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page83 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page83 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[83 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=498, page=84, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page84 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page84 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page84 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[84 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=503, page=85, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page85 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page85 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page85 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[85 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=509, page=86, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page86 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page86 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page86 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[86 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=514, page=87, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page87 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page87 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page87 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[87 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=519, page=88, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page88 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page88 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page88 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[88 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=524, page=89, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page89 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page89 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page89 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[89 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=530, page=90, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page90 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page90 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page90 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[90 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=535, page=91, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page91 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page91 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page91 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[91 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=541, page=92, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page92 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page92 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page92 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[92 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=546, page=93, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page93 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page93 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page93 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[93 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=551, page=94, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page94 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page94 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page94 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[94 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=557, page=95, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page95 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page95 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page95 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[95 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=562, page=96, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page96 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page96 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page96 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[96 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=567, page=97, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page97 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page97 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page97 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[97 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=573, page=98, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page98 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page98 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page98 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[98 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=578, page=99, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page99 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page99 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page99 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[99 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=583, page=100, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page100 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page100 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page100 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[100 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=588, page=101, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page101 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page101 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page101 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[101 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=593, page=102, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page102 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page102 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page102 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[102 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=598, page=103, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page103 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page103 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page103 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[103 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=604, page=104, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page104 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page104 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page104 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[104 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=609, page=105, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page105 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page105 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page105 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[105 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=616, page=106, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page106 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page106 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page106 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[106 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=621, page=107, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page107 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page107 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page107 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[107 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=626, page=108, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page108 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page108 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page108 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[108 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=631, page=109, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page109 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page109 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page109 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[109 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=637, page=110, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page110 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page110 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page110 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[110 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=642, page=111, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page111 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page111 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page111 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[111 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=647, page=112, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page112 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page112 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page112 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[112 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=652, page=113, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page113 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page113 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page113 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[113 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=657, page=114, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page114 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page114 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page114 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[114 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=662, page=115, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page115 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page115 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page115 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[115 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=668, page=116, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page116 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page116 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page116 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[116 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=679, page=117, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page117 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page117 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page117 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[117 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=684, page=118, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page118 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page118 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page118 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[118 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=689, page=119, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page119 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page119 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page119 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[119 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=694, page=120, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page120 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page120 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page120 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[120 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=700, page=121, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page121 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page121 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page121 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[121 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=706, page=122, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page122 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page122 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page122 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[122 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=711, page=123, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page123 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page123 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page123 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[123 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=716, page=124, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page124 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page124 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page124 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[124 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=721, page=125, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page125 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page125 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page125 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[125 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=726, page=126, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page126 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page126 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page126 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[126 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=731, page=127, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page127 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page127 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page127 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[127 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=737, page=128, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page128 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page128 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page128 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[128 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=742, page=129, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page129 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page129 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page129 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[129 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=747, page=130, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page130 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page130 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page130 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[130 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=752, page=131, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page131 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page131 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page131 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[131 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=757, page=132, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page132 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page132 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page132 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[132 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=762, page=133, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page133 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page133 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page133 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[133 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=768, page=134, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page134 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page134 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page134 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[134 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=773, page=135, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page135 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page135 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page135 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[135 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=778, page=136, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page136 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page136 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page136 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[136 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=783, page=137, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page137 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page137 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page137 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[137 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=788, page=138, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page138 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page138 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page138 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[138 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=793, page=139, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page139 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page139 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page139 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[139 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=799, page=140, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page140 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page140 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page140 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[140 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=804, page=141, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page141 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page141 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page141 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[141 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=809, page=142, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page142 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page142 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page142 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[142 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=814, page=143, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page143 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page143 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page143 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[143 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=819, page=144, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page144 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page144 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page144 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[144 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=825, page=145, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page145 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page145 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page145 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[145 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=831, page=146, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page146 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page146 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page146 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[146 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=836, page=147, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page147 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page147 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page147 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[147 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=841, page=148, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page148 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page148 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page148 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[148 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=846, page=149, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page149 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page149 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page149 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[149 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=851, page=150, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page150 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page150 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page150 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[150 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=856, page=151, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page151 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page151 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page151 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[151 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=862, page=152, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page152 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page152 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page152 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[152 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=867, page=153, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page153 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page153 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page153 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[153 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=873, page=154, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page154 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page154 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page154 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[154 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=878, page=155, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page155 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page155 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page155 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[155 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=883, page=156, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page156 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page156 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page156 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[156 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=888, page=157, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page157 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page157 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page157 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[157 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=894, page=158, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page158 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page158 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page158 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[158 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=899, page=159, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page159 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page159 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page159 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[159 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=904, page=160, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page160 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page160 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page160 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[160 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=909, page=161, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page161 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page161 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page161 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[161 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=914, page=162, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page162 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page162 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page162 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[162 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=919, page=163, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page163 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page163 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page163 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[163 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=925, page=164, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page164 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page164 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page164 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[164 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=930, page=165, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page165 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page165 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page165 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[165 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=935, page=166, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page166 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page166 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page166 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[166 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=940, page=167, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page167 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page167 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page167 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[167 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=945, page=168, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page168 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page168 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page168 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[168 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=950, page=169, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page169 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page169 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page169 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[169 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=956, page=170, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page170 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page170 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page170 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[170 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=961, page=171, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page171 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page171 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page171 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[171 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=966, page=172, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page172 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page172 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page172 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[172 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=971, page=173, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page173 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page173 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page173 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[173 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=976, page=174, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page174 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page174 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page174 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[174 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=981, page=175, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page175 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page175 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page175 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[175 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=987, page=176, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page176 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page176 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page176 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[176 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=992, page=177, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page177 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page177 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page177 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[177 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=997, page=178, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page178 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page178 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page178 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[178 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1002, page=179, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page179 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page179 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page179 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[179 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1007, page=180, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page180 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page180 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page180 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[180 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1012, page=181, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page181 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page181 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page181 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[181 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1018, page=182, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page182 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page182 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page182 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[182 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1023, page=183, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page183 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page183 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page183 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[183 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1028, page=184, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page184 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page184 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page184 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[184 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1033, page=185, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page185 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page185 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page185 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[185 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1038, page=186, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page186 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page186 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page186 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[186 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1044, page=187, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page187 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page187 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page187 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[187 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1050, page=188, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page188 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page188 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page188 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[188 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1055, page=189, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page189 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page189 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page189 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[189 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1060, page=190, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page190 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page190 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page190 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[190 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1065, page=191, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page191 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page191 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page191 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[191 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1070, page=192, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page192 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page192 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page192 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[192 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1075, page=193, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page193 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page193 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page193 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[193 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1081, page=194, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page194 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page194 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page194 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[194 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1086, page=195, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page195 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page195 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page195 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[195 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1091, page=196, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page196 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page196 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page196 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[196 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1096, page=197, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page197 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page197 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page197 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[197 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1101, page=198, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page198 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page198 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page198 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[198 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1106, page=199, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page199 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page199 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page199 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[199 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1112, page=200, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page200 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page200 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page200 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[200 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1117, page=201, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page201 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page201 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page201 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[201 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1122, page=202, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page202 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page202 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page202 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[202 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1127, page=203, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page203 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page203 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page203 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[203 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1132, page=204, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page204 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page204 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page204 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[204 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1137, page=205, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page205 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page205 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page205 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[205 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1143, page=206, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page206 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page206 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page206 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[206 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1148, page=207, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page207 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page207 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page207 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[207 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1153, page=208, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page208 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page208 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page208 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[208 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1160, page=209, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page209 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page209 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page209 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[209 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1165, page=210, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page210 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page210 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page210 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[210 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1170, page=211, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page211 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page211 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page211 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[211 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1176, page=212, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page212 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page212 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page212 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[212 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1181, page=213, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page213 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page213 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page213 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[213 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1186, page=214, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page214 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page214 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page214 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[214 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1191, page=215, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page215 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page215 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page215 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[215 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1196, page=216, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page216 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page216 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page216 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[216 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1201, page=217, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page217 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page217 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page217 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[217 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1207, page=218, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page218 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page218 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page218 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[218 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1212, page=219, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page219 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page219 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page219 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[219 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1218, page=220, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page220 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page220 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page220 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[220 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1223, page=221, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page221 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page221 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page221 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[221 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1228, page=222, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page222 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page222 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page222 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[222 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1233, page=223, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page223 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page223 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page223 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[223 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1243, page=224, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page224 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page224 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page224 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[224 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1248, page=225, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page225 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page225 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page225 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[225 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1253, page=226, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page226 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page226 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page226 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[226 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1260, page=227, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page227 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page227 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page227 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[227 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1265, page=228, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page228 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page228 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page228 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[228 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1270, page=229, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page229 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page229 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page229 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[229 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1276, page=230, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page230 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page230 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page230 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[230 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1281, page=231, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page231 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page231 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page231 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[231 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1286, page=232, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page232 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page232 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page232 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[232 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1291, page=233, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page233 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page233 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page233 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[233 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1296, page=234, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page234 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page234 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page234 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[234 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1301, page=235, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page235 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page235 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page235 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[235 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1307, page=236, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page236 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page236 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page236 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[236 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1312, page=237, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page237 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page237 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page237 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[237 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1317, page=238, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page238 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page238 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page238 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[238 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1322, page=239, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page239 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page239 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page239 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[239 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1327, page=240, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page240 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page240 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page240 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[240 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1332, page=241, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page241 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page241 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page241 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[241 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1338, page=242, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page242 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page242 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page242 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[242 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1343, page=243, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page243 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page243 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page243 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[243 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1348, page=244, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page244 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page244 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page244 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[244 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1353, page=245, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page245 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page245 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page245 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[245 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1358, page=246, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page246 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page246 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page246 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[246 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1363, page=247, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page247 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page247 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page247 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[247 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1369, page=248, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page248 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page248 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page248 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[248 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1374, page=249, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page249 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page249 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page249 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[249 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1379, page=250, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page250 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page250 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page250 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[250 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1384, page=251, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page251 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page251 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page251 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[251 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1390, page=252, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page252 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page252 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page252 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[252 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1395, page=253, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page253 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page253 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page253 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[253 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1401, page=254, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page254 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page254 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page254 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[254 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1406, page=255, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page255 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page255 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page255 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[255 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1411, page=256, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page256 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page256 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page256 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[256 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1416, page=257, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page257 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page257 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page257 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[257 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1421, page=258, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page258 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page258 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page258 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[258 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1426, page=259, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page259 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page259 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page259 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[259 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1432, page=260, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page260 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page260 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page260 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[260 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1437, page=261, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page261 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page261 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page261 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[261 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1442, page=262, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page262 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page262 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page262 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[262 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1447, page=263, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page263 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page263 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page263 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[263 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1452, page=264, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page264 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page264 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page264 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[264 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1457, page=265, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page265 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page265 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page265 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[265 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1463, page=266, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page266 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page266 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page266 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[266 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1468, page=267, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page267 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page267 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page267 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[267 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1473, page=268, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page268 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page268 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page268 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[268 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1480, page=269, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page269 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page269 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page269 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[269 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1485, page=270, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page270 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page270 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page270 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[270 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1490, page=271, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page271 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page271 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page271 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[271 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1496, page=272, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page272 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page272 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page272 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[272 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1501, page=273, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page273 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page273 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page273 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[273 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1506, page=274, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page274 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page274 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page274 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[274 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1511, page=275, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page275 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page275 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page275 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[275 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1516, page=276, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page276 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page276 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page276 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[276 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1521, page=277, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page277 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page277 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page277 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[277 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1527, page=278, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page278 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page278 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page278 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[278 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1532, page=279, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page279 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page279 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page279 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[279 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1537, page=280, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page280 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page280 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page280 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[280 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1542, page=281, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page281 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page281 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page281 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[281 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1547, page=282, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page282 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page282 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page282 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[282 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1552, page=283, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page283 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page283 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page283 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[283 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1558, page=284, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page284 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page284 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page284 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[284 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1564, page=285, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page285 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page285 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page285 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[285 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1569, page=286, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page286 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page286 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page286 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[286 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1574, page=287, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page287 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page287 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page287 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[287 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1579, page=288, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page288 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page288 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page288 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[288 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1584, page=289, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page289 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page289 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page289 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[289 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1590, page=290, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page290 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page290 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page290 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[290 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1595, page=291, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page291 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page291 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page291 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[291 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1600, page=292, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page292 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page292 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page292 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[292 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1605, page=293, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page293 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page293 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page293 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[293 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1610, page=294, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page294 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page294 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page294 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[294 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1615, page=295, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page295 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page295 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page295 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[295 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1621, page=296, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page296 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page296 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page296 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[296 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1626, page=297, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page297 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page297 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page297 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[297 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1631, page=298, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page298 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page298 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page298 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[298 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1636, page=299, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page299 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page299 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page299 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[299 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1641, page=300, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page300 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page300 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page300 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[300 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1646, page=301, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page301 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page301 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page301 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[301 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1652, page=302, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page302 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page302 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page302 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[302 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1657, page=303, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page303 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page303 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page303 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[303 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1663, page=304, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page304 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page304 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page304 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[304 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1668, page=305, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page305 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page305 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page305 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[305 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1673, page=306, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page306 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page306 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page306 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[306 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1678, page=307, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page307 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page307 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page307 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[307 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1684, page=308, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page308 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page308 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page308 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[308 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1689, page=309, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page309 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page309 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page309 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[309 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1694, page=310, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page310 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page310 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page310 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[310 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1699, page=311, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page311 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page311 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page311 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[311 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1704, page=312, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page312 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page312 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page312 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[312 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1709, page=313, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page313 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page313 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page313 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[313 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1715, page=314, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page314 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page314 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page314 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[314 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1720, page=315, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page315 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page315 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page315 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[315 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1725, page=316, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page316 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page316 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page316 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[316 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1730, page=317, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page317 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page317 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page317 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[317 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1736, page=318, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page318 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page318 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page318 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[318 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1741, page=319, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page319 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page319 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page319 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[319 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1747, page=320, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page320 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page320 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page320 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[320 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1752, page=321, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page321 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page321 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page321 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[321 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1757, page=322, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page322 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page322 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page322 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[322 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1762, page=323, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page323 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page323 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page323 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[323 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1767, page=324, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page324 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page324 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page324 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[324 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1772, page=325, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page325 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page325 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page325 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[325 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1778, page=326, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page326 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page326 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page326 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[326 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1783, page=327, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page327 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page327 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page327 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[327 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1788, page=328, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page328 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page328 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page328 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[328 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1793, page=329, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page329 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page329 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page329 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[329 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1798, page=330, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page330 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page330 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page330 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[330 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1803, page=331, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page331 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page331 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page331 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[331 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1809, page=332, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page332 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page332 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page332 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[332 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1814, page=333, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page333 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page333 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page333 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[333 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1819, page=334, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page334 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page334 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page334 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[334 <../inst/doc/UserGuide.pdf>] + +pdfTeX warning: pdflatex (file ../inst/doc/UserGuide.pdf): PDF inclusion: found PDF version <1.6>, but at most version <1.5> allowed +<../inst/doc/UserGuide.pdf, id=1824, page=335, 614.295pt x 794.97pt> +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page335 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page335 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +File: ../inst/doc/UserGuide.pdf Graphic file (type pdf) + +Package pdftex.def Info: ../inst/doc/UserGuide.pdf , page335 used on input line 8. +(pdftex.def) Requested size: 614.58406pt x 795.3441pt. +[335 <../inst/doc/UserGuide.pdf>] (/Users/eli.holmes/Documents/GitHub/MARSS/vignettes/UserGuide.aux) +Package rerunfilecheck Info: File `UserGuide.out' has not changed. +(rerunfilecheck) Checksum: D41D8CD98F00B204E9800998ECF8427E;0. + ) +Here is how much of TeX's memory you used: + 11546 strings out of 478007 + 211480 string characters out of 5838177 + 1852999 words of memory out of 5000000 + 31273 multiletter control sequences out of 15000+600000 + 513050 words of font info for 33 fonts, out of 8000000 for 9000 + 14 hyphenation exceptions out of 8191 + 75i,17n,76p,288b,569s stack positions out of 10000i,1000n,20000p,200000b,200000s + +Output written on UserGuide.pdf (335 pages, 1699234 bytes). +PDF statistics: + 1930 PDF objects out of 2073 (max. 8388607) + 1225 compressed objects within 13 object streams + 336 named destinations out of 1000 (max. 500000) + 1691 words of extra memory for PDF output out of 10000 (max. 10000000) + diff --git a/vignettes/UserGuide.out b/vignettes/UserGuide.out new file mode 100644 index 0000000..e69de29 diff --git a/vignettes/UserGuide.pdf b/vignettes/UserGuide.pdf new file mode 100644 index 0000000..228a320 Binary files /dev/null and b/vignettes/UserGuide.pdf differ diff --git a/vignettes/UserGuide.tex b/vignettes/UserGuide.tex new file mode 100644 index 0000000..2032945 --- /dev/null +++ b/vignettes/UserGuide.tex @@ -0,0 +1,9 @@ +%\VignetteIndexEntry{User Guide} +%\VignettePackage{MARSS} +\documentclass{article} +\usepackage{hyperref} +\usepackage{pdfpages} +\usepackage{Sweave} +\begin{document} +\includepdf[fitpaper=true,pages=-]{../inst/doc/UserGuide.pdf} +\end{document}