Perform GAM analysis

Source: R/gamTest.r

Perform GAM analysis. Relies on mgcv::gam to perform general additive model. gam The baseDay function has been added to this package from the smwrBase package.

gamTest(
  df,
  dep,
  stat,
  layer = NA,
  analySpec,
  gamTable = TRUE,
  gamPlot = 10,
  gamDiffModel = NA,
  flow.detrended = NA,
  salinity.detrended = NA
)

Arguments

df

data frame

dep

dependent variable

stat

station

layer

layer

analySpec

analytical specifications

gamTable

gam table setting (set to FALSE to turn off table output)

gamPlot

gam plot setting (set to FALSE to turn off plotting)

gamDiffModel

GAM model(s) used for computing differences on sub-annual/multi-period basis

flow.detrended

data generated by detrended.flow. Default = NA.

salinity.detrended

data generated by detrended.flow. Default = NA.

Value

Returns a list with results

  • stat.gam.result – Data frame with summary results in a tabular format suitable for output to a csv file

  • chng.gam.result – Data frame with estimate of change for sub-annual differences based on the settings specified in gamDiffModel. Includes all data from stat.gam.result and sub-annual estimates of change in a tabular format suitable for output to a csv file.

  • data – Data frame of data used in analysis (for example years with large proportion of censored data might be removed from the analysis and not included in this data frame)

  • data.all – Data frame of all potential data available for analysis

  • iSpec – List of baytrends analysis settings used for a specific analysis of station and parameter

  • gamOutput0 – Results including model predictions for gam formula 0 (i.e., gam0)

  • gamOutput1 – Results including model predictions for gam formula 1 (i.e., gam1)

  • gamOutput2 – Results including model predictions for gam formula 2 (i.e., gam2)

  • gamOutput3 – Results including model predictions for gam formula 3 (i.e., gam3)

  • gamOutput4 – Results including model predictions for gam formula 4 (i.e., gam4)

  • gamOutput5 – Results including model predictions for gam formula 5 (i.e., gam5)

  • gamOutput6 – Results including model predictions for gam formula 6 (i.e., gam6)

gamOutput* – For each evaluated model, gamOutput* (see above element list) is a list with the following elements:

  • gamOption – gam formula ID, i.e., 0, 1, 2, 3, 4 , 5, 6 corresponding to gam0, gam1, gam2, etc.

  • gamRslt – mgcv::gam output

  • gamRsltSum – "summary" of mgcv::gam, i.e., summary(mgcv::gam)

  • gamANOVAtbl – GAM Analysis of Variance table

  • gamCoefftbl – GAM Parameter Coefficients table

  • gamDiagnostics – GAM Diagnostics table(AIC, RMSE, and Adj. R-squared)

  • perChange – Estimates of Change table

  • porDiff.regular – Estimate of change in list format

  • porDiff.adjusted – Estimate of change adjusted for interventions in list format

  • predictions – Data frame of gam predictions (all information used to create baytrends graphics excluding measurements)

Details

Set gamPlot=FALSE to turn off plotting. Computing the information ("predictions") to create plots is one of the more time consumings aspects of the gamTest function. Setting gamPlot=FALSE turns off these computations and speeds up gamTest. The disadvantage is that no predictions are returned; however, the tabularized results stored in stat.gam.result and, if requested, chng.gam.result are still returned.

Setting gamPlot to a value between 1-30 changes the resolution of the resulting figure by setting the interval on which the prediction data set is made. By default gamPlot is set to 10. That is, a prediction is made every 10th day, or about 36 predictions per year. Values closer to 1 result in larger returned prediction data sets and take more computation time. Values closer to 30 result in smaller returned data sets and take less computation time. Although there is no change in the fitted model, values closer to 30 may have slight degraded figure quality if there is subtantial seasonality in the fitted model since the seasonal minimum and maximum might not be included in the prediction data set and therefore not plotted. Values greater than 30 are treated as 30. Setting gamPlot=30 might be advantangeous when the analysis only requires cursory figure examination.

Setting gamTable=FALSE will turn off table output to the console. This may be advantageous to reduce the amount of output. Since these computations do not significantly affect gamTest run time, the standard Analysis of Variance, GAM Parameter Coefficients, Diagnostics, and Estimates of Change tables are returned from gamTest regardless of the gamTable setting. Many of the values from these tables are also returned as part of tabularized stat.gam.result.

The default settings for gamDiffModel (i.e., gamDiffModel=NA) will not result in sub-annual (i.e., seasonal) differences being computed. In this default setting, the returned chng.gam.result that is returned from gamTest will be empty. If gamDiffModel is a value (i.e., not NA), then chng.gam.result will include one row for each combination of years specified in analySpec$gamDiffPeriods, seasons specified in analySpec$gamDiffSeason, and the number of models listed in gamDiffModel. For example gamDiffModel=c(0,1,2) would result in sub-annual being computed for gam0, gam1, and gam2.

Flow and Salinity Adjustments (gam4). It is necessary to create and pass properly formatted data via the flow.detrended and salinity.detrended arguments to evaluate gam4 models. See detrended.flow and detrended.salinity for more information on how to create properly formatted data.

Examples

if (FALSE) { # \dontrun{
# Specify parameter and station to analyze
dep        <- 'do'
stat       <- 'CB5.4'
layer      <- 'B'

# Prepare data and set up specifications for analysis
dfr <- analysisOrganizeData (dataCensored)
df        <- dfr[[1]]
analySpec <- dfr[[2]]

# Apply gamTest 
gamResult <- gamTest(df, dep, stat, layer, analySpec=analySpec)
gamPlotDisp(gamResult = gamResult, analySpec = analySpec,
            fullModel = 2, seasAvgModel = 2, seasonalModel = 2,
            diffType = "regular", obserPlot = TRUE, interventionPlot = TRUE,
            seasAvgPlot = TRUE, seasAvgConfIntPlot = FALSE,
            seasAvgSigPlot = FALSE, fullModelPlot = TRUE, seasModelPlot = TRUE,
            BaseCurrentMeanPlot = FALSE, adjustedPlot = FALSE)

# Apply gamTestSeason
gamResult2 <- gamTestSeason(df, dep, stat, layer, analySpec=analySpec,
                            gamSeasonPlot = c("7/15-8/15", "purple", "range"))
gamPlotDispSeason(gamResult = gamResult2, analySpec = analySpec,
                  fullModel = 2, seasAvgModel = 2, seasonalModel = 2,
                  diffType = "regular", obserPlot = TRUE, interventionPlot = TRUE,
                  seasAvgPlot = TRUE, seasAvgConfIntPlot = FALSE,
                  seasAvgSigPlot = FALSE, fullModelPlot = FALSE, seasModelPlot = FALSE,
                  BaseCurrentMeanPlot = TRUE, adjustedPlot = FALSE, gamSeasonFocus = TRUE)
} # }