\HeaderA{modelsCompare}{Functions for comparing results: LRE, compare, agrees}{modelsCompare}
\aliasA{LRE}{modelsCompare}{LRE}
\aliasA{modelBetas}{modelsCompare}{modelBetas}
\aliasA{modelsAgree}{modelsCompare}{modelsAgree}
\aliasA{modelSummary}{modelsCompare}{modelSummary}
\keyword{misc}{modelsCompare}
\keyword{debugging}{modelsCompare}
\begin{Description}\relax
Use these functions to compare a set of results from an analysis, to check if they 
agree to a certain number of significant digits.
\end{Description}
\begin{Usage}
\begin{verbatim}
        # compare numeric values against correct values
        LRE(x,correct, use.LAE=TRUE, cutoff=16)

        # compare the results from two possibly identical models
        modelsAgree(model, model2=NULL, digits=3, ...)
        modelsCompare(model, model2=NULL, param.function=modelBetas,
                                 similarity.function=LRE, summary.function=min)
                                                        
        # extract betas or entire coefficient summaries
        modelBetas(model)
        modelSummary(model)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] vector of computed values
\item[\code{correct}] vector of correct values
\item[\code{use.LAE}] use log absolute error if $c\_i$==0. If false, returns NA where $c\_i$==0
\item[\code{cutoff}] In LRE results, convert INF to cutoff. Since perfect agreement yields an infinite LRE otherwise. Default value of 16 is based on the number of significant digits for doubles.
\item[\code{model}] first model for comparison, or if model2=NULL, supply a list  of models for comparison
\item[\code{model2}] second model for comparison, if 
\item[\code{digits}] number of digits to use for comparison
\item[\code{param.function}] function used to extract model parameters for comparison
\item[\code{similarity.function}] function used to compute similarity between sets of model parameters
\item[\code{summary.function}] function used to summarize differences
\item[\code{...}] parameters to pass from modelsAgree to modelsCompare
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
modelsAgree is a convenienence function that calls modelsCompare to summarize similarities
between models results.
\end{Details}
\begin{Value}
Returns a new vector of log-relative-errors (log absolute error where $c\_i$ ==0).
The resulting values are roughly interpretable as the number of significant digits
of agreement between c and x. Larger numbers indicate that x is a relatively
more accurate approximation of c. Numbers less than or equal to zero indicate
complete disagreement between x and c.
\end{Value}
\begin{Author}\relax
Micah Altman
\email{Micah\_Altman@harvard.edu}
\url{http://www.hmdc.harvard.edu/micah_altman/}, Michael McDonald
\end{Author}
\begin{References}\relax
Altman, M., J. Gill and M. P. McDonald.  2003.  \emph{Numerical Issues in Statistical
Computing for the Social Scientist}.  John Wiley \& Sons.
\url{http://www.hmdc.harvard.edu/numerical_issues/}
\end{References}
\begin{SeeAlso}\relax
See Also as \code{\LinkA{ttst}{ttst}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

# simple LRE examples
LRE(1.001,1) # roughly 3 significant digits agreement
LRE(1,1) # complete agreement
LRE(20,1) # complete disagreement

# compare two models

if (is.R()) {
 hasNmle=require(nlme,quietly=TRUE) 
}  else {
  hasNmle=require(nlme3,quietly=TRUE)
}

if (hasNmle) { 
  O2<-Orthodont
  O3<-Orthodont
  
  O2[,2]<-O2[,2]+.1                                    
  O3[,2]<-O2[,2]+.11 
  if (is.R()) {                                   
    fm1<- lmList(Orthodont)
    fm2<- lmList(O2)
    fm3<- lmList(O2)
  } else {
    # workaround bug in lmlist in S-Plus
    fm1<- eval(substitute(lmList(Orthodont)))
    fm2<- eval(substitute(lmList(O2)))
    fm3<- eval(substitute(lmList(O2)))
  }

  # do the three models agree? 
  print(modelsAgree(list(fm1,fm2,fm2)))

  # show details of diagreement between first 2 models
  print(modelsCompare(fm1,fm2))

  #compare betas at 2 significant digits
  print(modelsAgree(fm1,fm2,digits=2,param.function=modelBetas))
  #compare betas at 1 significant digit
  print(modelsAgree(fm1,fm2,digits=1,param.function=modelBetas))
}



\end{ExampleCode}
\end{Examples}

