fitDiagFDSLRM: Fitting and diagnostic of FDSLRM

In gajdosandrej/fdslrm: R package for modeling and prediction of time series using linear mixed models

Description

fitDiagFSDLRM(x, times, freq_mean, poly_trend_degree = 0, include_fixed_eff, freq_random, include_random_eff, var_estim_method = "REML", fit_function = "lme", season_period = 0, display_plots = FALSE) fits particular FDSLRM (in the form of linear mixed model - LMM or classical linear regression model - CLRM) to time series data, returns estimates of all model's parameters and it also returns the model diagnostic (numerical and graphical).

Usage

fitDiagFDSLRM(
  x,
  times,
  freq_mean,
  poly_trend_degree = 0,
  include_fixed_eff,
  freq_random,
  include_random_eff,
  fit_function = "lme",
  var_estim_method = "REML",
  season_period = 0,
  display_plots = FALSE
)

Arguments

x	time series observation.
times	vector of observation times.
freq_mean	vector of (Fourier) frequencies to create the design matrix for fixed effects.
poly_trend_degree	degree of polynomial in linear regression representing the mean value. Default is poly_trend_degree = 0. Available just for fit_function = lme.
include_fixed_eff	vector of zeros / ones to indicate which cosine and sine component corresponding to particular frequency in freq_mean should be excluded / included.
freq_random	vector of (Fourier) frequencies to create the design matrix for random effects.
include_random_eff	vector of zeros / ones to indicate which cosine and sine component corresponding to particular frequency in freq_random should be excluded / included.
fit_function	type of function to fit the model. One of the following types is acceptable: "lme", "mixed", "mmer". Default is fit_function = "lme".
var_estim_method	type of method for estimating variance parameters. Default is "REML". For fit_function = "lme" the "REML" and "ML" estimates are available. For fit_function = "mixed" the following estimates are available: "ML", "REML", "MINQEI", "MINQEUI".
season_period	input parameter of type numeric expressing the period of seasonality. Default is season_period = 0.
display_plots	input parameter of type logical indicating if all diagnostic plots should be drawn. Default value is display_plots = FALSE.

Details

Fitting functions lme (lm in case of CLRM), mixed (Witkovsky, 2002; Gajdos 2018), mmer (Covarrubias-Pazaran, 2016) consequently offer a little bit different diagnostic tools and outputs. For example when lme is used the residual diagnostic is created with the help of open source R code from Singer et al. (2017).

If there are no frequencies for random effects as input, just the frequencies for fixed effects then the CLRM is fitted automatically by the lm function.

Value

This function returns an output - result, which is a list with the following elements (for LMM):

• result$fixed_effects estimates of fixed effects (regression parameter β),

• result$random_effects BLUPs of random effects Y,

• result$error_variance estimate of variance of white noise component,

• result$rand_eff_variance estimates of variances of random effects,

• result$marg_fitted_values marginal fitted values (i.e. trend i.e. mean value estimate),

• result$cond_fitted_values conditional fitted values (estimate of trend plus BLUP of random effects),

• result$marg_residuals marginal residuals,

• result$cond_residuals conditional residuals,

• result$norm_cond_resid normalized conditional residuals,

• result$pearson_resid Pearson's residuals,

• result$Box_test Box test of conditional residuals independence (not adjusted for time series (non)-seasonality),

• result$BoxLjung_test Box-Ljung test of conditional residuals independence (not adjusted for time series (non)-seasonality),

• result$ShapiroWilk_test_norm_cond_resid Shapiro-Wilk normality test of normalized residuals,

• result$ShapiroWilk_test_stand_least_conf_residShapiro-Wilk normality test of least confounded conditional residuals,

• result$lme_fit object inheriting from class lme, an output of function lme containing details about model fitting,

• result$fit_summary summary info about model fitting,

• result$diag_resid an ouput (list) of diagnostic function created by Singer et al. (2017),

• result$time_series original time series data (input for model fitting),

• result$matrix_F design matrix for fixed effects,

• result$matrix_V design matrix for random effects,

• result$data_frame data frame containing original time series, design matrices, grouping factors (for lme fitting),

• result$output$Box_test_season_resid Box test of conditional residuals independence (accounts for time series seasonality), available if season_period input argument is greater than zero,

• result$output$BoxLjung_test_season_resid Box-Ljung test of conditional residuals independence (accounts for time series seasonality), available if season_period input argument is greater than zero,

• result$Box_test_lag10_resid Box test of conditional residuals independence (accounts for time series non-seasonality), available if season_period = 0,

• result$BoxLjung_test_lag10_resid Box-Ljung test of conditional residuals independence (accounts for time series non-seasonality), available if season_period = 0,

• result$diagnostic_plots_names vector of available diagnostic plots names, these can be displayed by function drawDiagPlots.

For CLRM (using lm) and also for other fitting functions than lme the output looks slightly different. If set the diagnostic plots could be drawn.

Note

Ver.: 13-Jan-2019 11:15:48.

References

Covarrubias-Pazaran G. 2016: Genome assisted prediction of quantitative traits using the R package sommer. PLoS ONE 11(6):1-15.

Gajdos, A. (2018): MMEinR: R version of Witkovsky's Matlab implementation of iterative solving of Henderson's mixed model equations. https://github.com/gajdosandrej/MMEinR.

Pinheiro J., Bates D., DebRoy S., Sarkar D. and R Core Team (2019): _nlme: Linear and Nonlinear Mixed Effects Models_. R package version 3.1-131, <URL: https://CRAN.R-project.org/package=nlme>.

Singer, J. M., Rocha, F. M. M., and Nobre, J. S. (2017): Graphical Tools for Detecting Departures from Linear Mixed Model Assumptions and Some Remedial Measures. International Statistical Review, 85: 290-324.

Witkovsky, V.: MATLAB Algorithm for solving Henderson's Mixed Model Equations. Technical Report No. 3/2000, Institute of Measurement Science, Slovak Academy of Sciences, Bratislava, 2000.

Examples

## EXAMPLE 1 (LMM)
# load all necessary R packages and functions to fit and make diagnostic of FDSLRM
initialFDSLRM()
# the following data set was adapted from Hyndman's package fpp2 (Hyndman 2018)
# data represent total quarterly visitor nights (in millions) from 1998-2016 in one of the regions
# of Australia - inner zone of Victoria state
# the number of time series observations is  n = 76
# data visualization
autoplot(window(visnights)[,15], ylab = "Visnights")
# time series realization, observation times
dt <- as.numeric((window(visnights)[,15]))
t <- 1:length(dt)
# periodogram to identify the most significant frequencies to build the model (design matrices)
periodo <- spec.pgram(dt, log="no")
# according to periodogram we choose the frequencies 1/80, 2/80 for trend
# and the frequencies 20/80, 40/80 for random component
# fit the model with lme function
output_lme <- fitDiagFDSLRM(dt, t, c(1/80, 2/80), include_fixed_eff = c(1,0,0,1),
                          freq_random = c(20/80, 40/80), include_random_eff = c(1,1,1,0),
                          poly_trend_degree = 0, season_period = 4)
# draw diagnostic plots
drawDiagPlots("all", output_lme)
drawDiagPlots(output_lme$diagnostic_plots_names$FittedTimeSeries, output_lme)
# show summary of model fit
str(output_lme$fit_summary)
# fit the model with mixed function
output_mixed <- fitDiagFDSLRM(dt, t, c(1/80, 2/80), include_fixed_eff = c(1,0,0,1),
                            freq_random = c(20/80, 40/80), include_random_eff = c(1,1,1,0),
                            var_estim_method = "MINQEI",
                            fit_function = "mixed", season_period = 4)
# draw diagnostic plots
drawDiagPlots("all", output_mixed)
drawDiagPlots(output_mixed$diagnostic_plots_names$CumulatPeriodogCondResid, output_lme)
# show summary of model fit
str(output_mixed$mixed_fit)

# fit the model with mmer function
output_mmer <- fitDiagFDSLRM(dt, t, c(1/80, 2/80), include_fixed_eff = c(1,0,0,1),
                            freq_random = c(20/80, 40/80), include_random_eff = c(1,1,1,0),
                            fit_function = "mmer", season_period = 4)
# draw diagnostic plots
drawDiagPlots("all", output_mmer)
drawDiagPlots(output_mmer$diagnostic_plots_names$CumulatPeriodogCondResid, output_mmer)
# show summary of model fit
str(output_mmer$mmer_fit)

## EXAMPLE 2 (CLRM)
# load all necessary R packages and functions to fit and make diagnostic of FDSLRM
initialFDSLRM()
# the following data set was adapted from Hyndman's package fpp2 (Hyndman 2018)
# data represent total quarterly visitor nights (in millions) from 1998-2016 in one of the regions
# of Australia - inner zone of Victoria state
# the number of time series observations is  n = 76
# data visualization
autoplot(window(visnights)[,15], ylab = "Visnights")
# time series realization, observation times
dt <- as.numeric((window(visnights)[,15]))
t <- 1:length(dt)
# periodogram to identify the most significant frequencies to build the model (design matrices)
periodo <- spec.pgram(dt, log="no")
# according to periodogram we choose the frequencies 1/80, 2/80 for trend
# and the frequencies 20/80, 40/80 for random component
# fit the model with lme function
output_lm <- fitDiagFDSLRM(dt, t, c(1/80, 2/80, 20/80, 40/80), include_fixed_eff = c(1,0,0,1,0,1,1,0), season_period = 4)
# draw diagnostic plots
drawDiagPlots("all", output_lm)
drawDiagPlots(output_lm$diagnostic_plots_names$FittedTimeSeries, output_lme)
# show summary of model fit
str(output_lm$fit_summary)

gajdosandrej/fdslrm documentation built on April 28, 2020, 11:35 a.m.