Improve documentation + examples of gmo function

Clean up imports, exports; Add long description

Author: Express50

DESCRIPTION

@@ -4,14 +4,12 @@ Title: Overdispersion Models using Generalized Estimating Equations
 Version: 1.0
 Author: Victoria Landsman, David Landsman
 Maintainer: David Landsman <david.landsman@mail.utoronto.ca>
-Description: More about what it does (maybe more than one line)
-    Use four spaces when indenting paragraphs within the Description.
+Description: Provides an implementation of a GEE solver for estimating 
+  the parameters of an overdispersion model. The solver supports data with
+  both an independence and exchangeable correlation model.
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 RoxygenNote: 6.1.1
-Imports: 
-  base,
-  stats,
-  psych,
+Imports:
   rootSolve

NAMESPACE

@@ -1,6 +1,8 @@
-exportPattern("^[[:alpha:]]+")
+# Generated by roxygen2: do not edit by hand
+
+S3method(print,gmo.glogit)
+S3method(print,gmo.ident)
 export(gmo)
 
-importFrom("psych", "tr")
 importFrom("rootSolve", "multiroot")
-importFrom("stats", "uniroot")
+importFrom("stats", "uniroot")

R/gmo.r

@@ -1,16 +1,27 @@
 #' GMO - General Multinomial Overdisperion Model
 #'
-#' Creates an General Multinomial Overdispersion Model for the given data
+#' Creates an General Multinomial Overdispersion Model for the given data matrix.
+#' The data passed in should be in the form of multinomial clusters.
 #'
+#' The `corstr` option specifies the intra-cluster correlation structure:
+#'    - `independence` is used when there is no intra-cluster correlation (i.e.: rho = 0) (default)
+#'    - `exchangebale` is used when there is intra-cluster correlation
+#'
+#' The `link` option specifies the format of the output:
+#'    - `glogit` option gives the estimates and variance matrix in terms of beta (real-valued) (default)
+#'    - `identity` option gives the estimates and variance matrix in terms of pi's in [0, 1]
 #'
 #' @param dat matrix of multinomial clusters
 #' @param corstr one of: independence, exchangeable
 #' @param link one of: glogit, identity
-#' @param ... parameters to be passed on to \code{iterative_function}
+#'
+#' @examples
+#' dat <- matrix(c(6, 4, 4, 3, 1, 2, 2, 2, 1, 3, 15, 6, 5, 8, 4, 2, 2, 1, 13, 10, 8, 1, 3, 2, 10, 22, 11, 31, 10, 14), nrow=10, ncol=3, byrow=TRUE)
+#' gmo(dat, link='identity')
 #'
 #' @return a GMO object
 #' @export
-gmo <- function (dat, corstr = "independence", link = "glogit", ...) {
+gmo <- function (dat, corstr = "independence", link = "glogit") {
   if (!is.matrix(dat))
     stop("dat must be a matrix")
   if (!(corstr %in% c("independence", "exchangeable")))
@@ -50,7 +61,7 @@ gmo <- function (dat, corstr = "independence", link = "glogit", ...) {
 
 #' Print GMO glogit
 #'
-#' Prints GMO glogit object
+#' Prints GMO glogit object.
 #'
 #' @param x gom glogit object
 #' @param ... additional params to \code{print(x, ...)}
@@ -75,7 +86,7 @@ print.gmo.glogit <- function(x, ...) {
 
 #' Print GMO identity
 #'
-#' Prints GMO identity object
+#' Prints GMO identity object.
 #'
 #' @param x gom identity object
 #' @param ... additional params to \code{print(x, ...)}
@@ -96,7 +107,4 @@ print.gmo.ident <- function(x, ...) {
 
   cat('\nVar-Covar Matrix: \n')
   print(round(x$var.mat, 6), ...)
-}
-
-registerS3method("print", "gmo.glogit", "print.gmo.glogit")
-registerS3method("print", "gmo.ident", "print.gmo.ident")
+}

R/helpers.r

@@ -0,0 +1,9 @@
+#' Compute trace of a square matrix, that is, the sum
+#' of its diagonal elements.
+#'
+#' @param m a square matrix
+#'
+#' @return trace of input matrix
+tr <- function(m) {
+    sum(diag(m))
+}

R/iterative.r

@@ -1,3 +1,5 @@
+library(rootSolve)
+
 #' Iterative GEE Function
 #'
 #' Iteratively finds coefficients and overdispersion parameter using
@@ -9,7 +11,6 @@
 #' @param thresholds vector of thresholds for betas and rho
 #'
 #' @return list containing estimates (probabilities and rho) and number of iterations
-#' @export
 iterative_function <- function(dat, RHO = FALSE, max.iter = 10, thresholds = NULL) {
   n <- dim(dat)[[2]]
   if (is.null(thresholds)) thresholds <- rep(0.00000001, n)

R/variance.r

@@ -7,7 +7,6 @@
 #' @param dat matrix of multinomial clusters
 #'
 #' @return matrix of covariance
-#' @export
 get_var_ident <- function (p.vec, rho, dat) {
   n <- dim(dat)[[2]]  # dimensions of multinom
   m <- n - 1  # order of multinom
@@ -47,7 +46,6 @@ get_var_ident <- function (p.vec, rho, dat) {
 #' @param dat matrix of multinomial clusters
 #'
 #' @return matrix of covariance
-#' @export
 get_var_glogit <- function(betas, rho, dat) {
   n <- dim(dat)[[2]]  # dimensions of multinom
   m <- n - 1  # order of multinom