####################################################################
##
##THIS FILE DOCUMENTS CHANGES TO FUNCTIONS IN PACKAGE AICcmodavg
##Author:  Marc J. Mazerolle <marc.mazerolle@uqat.ca>
##
####################################################################
#revision 1.34 (13 November 2013)
#- added functionality to compute model-averaged estimates (means)
#  with 'mult.comp'
#- added functionality for clogit models
#- added one-way ANOVA turkey data set
#- added two-way ANOVA iron data set
#- modified 'predictSE.zip' to handle offsets and added c.hat argument
#- added functionality of overdispersion correction for N-mixture models
#  in 'aictab', 'modavg', 'modavgpred', 'modavg.effect'
#  'modavg.shrink', 'predictSE.zip'
#- added functions 'Nmix.gof.test' and 'Nmix.chisq' to assess GOF of 
#  N-mixture models



####################################################################
#revision 1.33 (12 September 2013)
#- added 'mult.comp' function to compute multiple comparisons on factors
#- added 'boot.wt' function to compute bootstrapped relative frequencies
#- corrected minor bug in 'mb.chisq' for certain patterns of missing values
#- added conditional test to avoid problems on CRAN with some packages unavailable
#  on certain platforms
#- added the lizards habitat preference data set


####################################################################
#revision 1.32 (5 July 2013)
#- corrected minor bug in 'modavg' when model-averaging with models of classes 'clm' and 'clmm' when the 'exclude' argument was used
#- corrected bug with certain types of missing values in mb.chisq( )
#- added function to extract DIC and create model selection tables based on DIC (functions 'DIC' and 'dictab')



####################################################################
#revision 1.31 (26 June 2013)
#- added functions to work with new 'merMod' classes of package lme4




####################################################################
#revision 1.30 (16 May 2013)
#- modified example code of predictSE.zip( ) to avoid errors on some platforms during package building



####################################################################
#revision 1.29 (22 April 2013)
#- added 'mb.chisq' to implement MacKenzie and Bailey (2004) goodness-of-fit test on single-season occupancy models
#  and 'mb.gof.test' to compute P-values, c-hat, and histogram of bootstrapped test statistics
#- corrected bug for offsets in predictSE.mer( )



####################################################################
#revision 1.28 (21 March 2013)
#- added functionality for zip models to compute SE's of predictions on abundance of N-mixture models from unmarked
#- added functionality for 'occuFP' models (detections with false-positives)



####################################################################
#revision 1.27 (7 February 2013)
#- implemented model-averaging estimates and predictions for 'gdistsamp' models
#- added support for nonlinear mixed models of class 'nlme'


####################################################################
#revision 1.26 (30 August 2012)
#- added support for robust regression models of class 'rlm' - AICc, aictab, importance, modavg, modavg.effect, modavg.shrink, modavgpred
#- added support for ordinal logistic regression models of classes 'clm' and 'clmm' - AICc, aictab, importance, modavg, modavg.effect, modavg.shrink 
#- modified modavg.unmarked( ) to enable treatment of gamma parameter in pcountOpen models 
#  with different formulations (Const, Trend, AR)
#- added reference of Luckacs et al. 2010 about model averaging with shrinkage in modavg.shrink.Rd file
#- added references Burnham et al. 2011 for using model selection as alternative to multiple comparisons in modavg.effect.Rd file
#- removed white space from formulas to reduce chance of reaching character limit in parse( ) in predictSE.mer( ), predictSE.lme( ), and predictSE.gls( )
#- changed treatment of parm with modavg.unmarked to add object parm.strip (line 35) to enable functionality with regexpr( )



####################################################################
##revision 1.25 (7 June 2012)
##- added Cox proportional hazards model support
##- added modavg.effect functions to compute model-averaged effect
##  sizes for true experiments as an information-theoretic analogue 
##  to multiple comparisons



####################################################################
##revision 1.24 (6 February 2012)
##- corrected minor bug in AICc.nls( ) to determine number of observations
##  automatically when "second.ord = TRUE"



####################################################################
##revision 1.23 (27 January 2012)
##- corrected minor bug following revision 1.22 on predictSE.mer( ) 
##  to avoid problems with factors



####################################################################
##revision 1.22 (19 January 2012)
##- modified example in modavg( ) help file
##- added error message for models without intercept with modavg( )
##- added support for offset variable in predictSE.mer( ) for Poisson GLMM
##- added support for 'distsamp' and 'gdistsamp' models from unmarked package 
##  (Poisson or negative binomial abundance with log link)
##- added example in modavg( ) and modavgpred( ) for 'distsamp' models
##- added example for Poisson GLMM with log link and offset



####################################################################
##revision 1.21 (4 November 2011)
##- corrected error in computing sample size for binomial model with events/trials syntax in AICc.glm( ) and AICc.mer( )



####################################################################
##revision 1.20 (3 October 2011)
##- added functionality of 'nobs' argument for objects created 
##  in unmarked package



####################################################################
##revision 1.19 (14 September 2011)
##- created function 'predictSE.gls' to compute predicted values 
##  and SE's from 'gls' model fits and added functionality of 
##  'modavgpred' with 'gls' model fit
##- added documentation with examples for 'gls' 



####################################################################
##revision 1.18 (26 August 2011)
##- added NAMESPACE
##- modified functions 'extractSE.mer' and streamlined extraction of estimate 
##  labels of 'mer' objects in 'modavg.mer', 'modavg.shrink.mer', 'importance'



####################################################################
##revision 1.17 (17 June 2011)
##- fixed minor bug for external calls to AICc to assign 'unmarkedFit' classes
##- added functionality of 'AICc', 'aictab', 'evidence', 'importance', 'confset' with 'nls' fits



########################################################
##revision 1.16 (27 May 2011)
##- added model selection and multimodel inference functionality with 
##  unmarked package for objects of classes unmarkedFitOccu, 
##  unmarkedFitColExt, unmarkedFitPCount, unmarkedFitPCO, unmarkedFitOccuRN
##  for models incorporating detectability 
##- modifications of functions 'aictab', 'importance', 'confset', 'evidence', 
##  'modavg', 'modavgpred', 'modavg.shrink', and extract.LL.unmarked utility 
##  function added
##- added new argument parm.type, to specify class of parameters for objects
##   of unmarkedFit classes
##- added several examples for dealing with objects of 'unmarkedFit' classes
##- modified 'modavg', 'modavg.shrink', 'importance', and 'reverse.exclude' 
##  functions to strip white spaces within elements entered inadvertently 
##  by user in the parm and exclude arguments



########################################################
##revision 1.15 (21 April 2011)
##- in 'modavg' and related functions, added functionality of dealing with specification of interaction terms (e.g., A:B, B:A, A*B, B*A)
##  by adding two new utility functions to recognize the terms when user is not consistent in his model syntax
##- created function 'modavg.shrink' for the shrinkage version of model-averaging estimates to reduce model selection bias when 
##  the same number of models include/exclude a variable  



########################################################
##revision 1.14 (11 March 2011)
##- fixed minor bug in 'modavg.mer' regarding exclusion of interaction terms as 'formula' includes spaces within interaction terms



########################################################
##revision 1.13 (10 January 2011)
##- fixed minor bug in 'AICc.lme' on the computation of n in certain lme's with several levels



#######################################################
##revision 1.12 (22 November 2010)
##- fixed minor bug in 'modavgpred.lme' that generated error message when second.ord = FALSE
##- fixed minor bug by dispatching 'mer' class objects to 'AICc.mer'
##- fixed minor bug with incorrect computation of n for 'mer' models with binomial distribution using 
##  cbind(incidence, size - incidence) or binary syntax



#######################################################
##revision 1.11 (8 October 2010)
##- fixed minor bug in 'modavgpred.glm' that generated an error message for Poisson, binomial, and negative 
##  binomial distributions when 'c.hat' = 1 
##- added additional example in 'predictSE.mer' with gaussian distribution but with log link



#######################################################
##revision 1.10 (7 October 2010)
##- fixed minor bug in 'modavgpred.glm' for SE's of predictions from gaussian model
##- fixed minor bug in 'modavg.glm' for SE's of beta estimates from negative binomial glm



#######################################################
##revision 1.09 (16 September 2010)
##  - added function 'predictSE.mer' to compute predictions and SE's on predictions
##    accounting only for fixed effects (mean population prediction) from objects
##    of 'mer' class
##  - added functionality to 'modavgpred' to include computation of model-averaged
##    predictions from objects of class 'mer'
##  - added a check for link function to ensure same link function was used for all models in 'modavg' when
##    model averaging beta estimates
##  - created a utility function to determine family and link function for objects of 'mer' class called by
##    'modavg', 'modavgpred', and 'predictSE.mer'
##  - added a warning when some models have an identical (Q)AIC(c) and are possibly redundant in 'aictab'
##  - corrected minor bug in number of observations in 'modavgpred'
##  - added a check for binomial family with events/trials syntax to use sum of weights as number of observations
##    in 'AICc.mer' when nobs = NULL



#######################################################
##revision 1.08 (16 August 2010)
##  - added Suggests "lme4" in DESCRIPTION file



#######################################################
##revision 1.07 (24 May 2010)
##  - modified modavg to include 'nobs' argument in call to modavg.lme and modavg.gls
##  - added support for generalized linear mixed models of the mer class for AICc, aictab, modavg, evidence, importance, confset functions
##  - updated information on support for 'mer' class in help files
##  - added examples in some of the help files with 'mer'



#######################################################
#revisions 1.06 (6 February 2010)
## -added a 'polr' class check to 'AICc' function;
## -added function 'predictSE.lme' to make predictions based on fixed effects for objects
##  of class 'lme' (mean population predictions) and compute associated SE's;
## -added function 'modvagpred.lme' to compute model-averaged predictions and unconditional 
##  standard errors for 'lme' models;
## -added statement in Rd files for 'aictab', 'confset', 'evidence', 'importance', 'modavgpred', 
##  'modavg',  and generics 'nobs = NULL' defaults to total number of observations in 
##  computations of information criteria;
## -added NEWS file to document changes across versions of AICcmodavg package;
## -added check that same response variable is used throughout model set for 'aictab' and generics
##  with lapply(X = cand.set, FUN = function(b) formula(b)[2]);
## -added functionality of 'AICc', 'aictab', 'confset', 'evidence', 'importance', 'modavg' with
##  objects of 'gls' class;
## -added additional flexibility to 'evidence' function when model selection table provided is not
##  sorted ('evidence' now sorts table internally) and set default comparison to top-ranked model 
##  vs second-ranked model;
## -added check/error message when no dispersion parameter (i.e., 'gamdisp') is specified for 'modavg'
##  and 'modavgpred' and generics with gamma regression models;
## -added additional check/error message when c.hat < 1 in 'AICc.glm';



#######################################################
##revisions 1.05 (3 December 2009):
## -modified number of digits to print with 'importance' to be consistent with revision 1.04;
## -added parenthesis where one was missing in aictab.Rd under value at line for (Q)AIC(c);
## -corrected example in evidence.Rd for faulty name of model.low - should have been 
##  'model.low = raw density';
## -deleted CumWt when 'sort = FALSE' in 'aictab' - by modifying argument in 'print.aictab';
## -for 'AICc.glm', 'AICc.mult', c.hat > 1 && c.hat <= 4 now gives warning;
## -added a column for logLik, quasi-logLik, or restricted logLik in 'aictab';
## -added options in 'print.aictab' to select items to display;
## -added a check for 'exclude =' in 'modavg' and generics to warn if exclude is not a list:
##  
##  if(!is.null(exclude)) {
##    if(!is.list(exclude)) stop(cat("\n\'exclude\' should be a list\n"))
##  }
##
## -documented 'aictab' with new LL, Quasi.LL, Res.LL elements
## -used 'vcov' and argument 'dispersion =' to scale SE's in a single step instead of adding 
##  more code to scale it on separate lines - works with Poisson, Binomial, Gamma;
## -in 'modavg.polr' and 'modavg.mult', added a logical test to distinguish between 'coef' 
##  or zeta which are the intercepts; 
## -modified 'print.aictab' so that c_hat is printed only when c_hat appears in AICc table 
##  (i.e, when any(names(x)=="c_hat"));
## -modified 'print.modavg' so that c_hat is printed only when c_hat appears in AICc table 
##  (i.e, when any(names(oldtab)=="c_hat")) AND deleted Cum.Wt from x$Mod.avg.table;
##  -added a check for the order for aictab and modavg and generics so that LL and other 
##  measures are displayed properly in table and sorted at the very end (placed line of sort 
##  and cumsum at very end of code) with Results[rev(order(Results[,5])), ];
## -added Cum.Wt in last column of Results;
## -changed order of elements with colnames so that prints nicely - this affects 'importance', 
##  'confset', and 'evidence' - number of columns used might differ depending on what is 
##  requested;
## -in 'modavg' and generics, changed 'regexpr' to determine whether parameter appears alone 
##  in the model and added 'fixed = TRUE', to find matches "as is" to avoid problems with 
##  'mult' (e.g., "well|mild");



#######################################################
##revision 1.04 (11 November 2009):
## -added the new equation for unconditional SE based on equation 6.12 of Burnham and 
##  Anderson (2002) in 'modavg' and 'modavgpred' and new argument 'uncond.se' with default 
##  value "revised" -  'uncond.se = old' uses equation 4.19;
## -added a check to determine whether all link functions are identical for 'modavg' 
##  as averaging over beta estimates under different link functions is not appropriate 
##  and returns error);
## -added a check to determine whether all link functions are identical for 'modavgpred' 
##  when linear predictor is used;
## -changed default to display only 2 digits after decimal point for all output 'print' 
##  generic functions;



#######################################################
##revision 1.03 (21 October 2009):
## -replaced 'regexpr' in 'modavg.glm', 'modavg.lme', 'modavg.mult' with 'match';
## -add functionality for 'polr';
## -cleaned up code with indentations;
## -added 'exclude' argument to manually exclude models with interaction terms/quadratic 
##  terms in 'modavg';
## -added 'warn' argument (to suppress warning that variables with similar names appear 
##  in a given model) to 'modavg' function.  This is a fundamental difference with the 
##  previous versions of the function as now the user must specify the variables (as a list) 
##  to exclude models for the computation of model-averaged estimates (case when 
##  interaction/polynomial terms are present).  This modication also solved the 
##  problem of variables with similar names;



#######################################################
##revision 1.02 (29 September 2009):
## -corrected small bug for computation of AICc (in 'AICc.glm') for binomial models with 
##  events/trials syntax to use the correct sample size;
## -added function to compute (Q)AIC(c) for multinomial models and updated 'aictab' 
##  function accordingly;
## -added citation file;
## -changed 'Depends' to 'Suggests' for packages MASS, nnet, nlme;
## -modified 'importance' to include 'multinom' objects;
## -removed dependencies with nlme to avoid potential problems with lme4;



#######################################################
##revision 1.01:
## -cleaned up documentation file, added a few more sentences and added space within formulas 
##  for the example to display properly in pdf;


