From 8c8c6fd92994c33a36cb7c1b2831c8fab486ac4b Mon Sep 17 00:00:00 2001 From: James Dunham Date: Sat, 28 Oct 2017 19:37:24 -0400 Subject: [PATCH 1/2] tweak formatting and organization of docs, pkgdown site --- R/class-dgirt_fit.r | 4 +- R/class-dgirtin.r | 6 +- R/class-dgmrp_fit.r | 2 +- R/class-dgo_fit.r | 2 +- R/dgirt.r | 4 +- R/methods-dgirtfit-plot.r | 19 +++--- R/methods-dgirtfit-poststratify.r | 2 +- R/methods-dgirtin.r | 30 +++------ R/shape.r | 2 +- R/toy_dgirt_in.r | 2 +- R/toy_dgirtfit.r | 2 +- _pkgdown.yml | 4 ++ docs/reference/dgirt.html | 6 +- docs/reference/dgirt_fit-class.html | 62 +++++++++---------- docs/reference/dgirtfit-class.html | 4 +- docs/reference/dgirtin-class.html | 29 +++------ docs/reference/dgmrp_fit-class.html | 4 +- docs/reference/dgo_fit-class.html | 4 +- docs/reference/dgo_fit-methods.html | 96 ++++++++++++++--------------- docs/reference/index.html | 36 +++++++++-- docs/reference/plot-method.html | 12 ++-- docs/reference/poststratify.html | 4 +- docs/reference/shape.html | 4 +- docs/reference/toy_dgirt_in.html | 4 +- docs/reference/toy_dgirtfit.html | 4 +- man/dgirt.Rd | 4 +- man/dgirt_fit-class.Rd | 2 +- man/dgirtfit-class.Rd | 2 +- man/dgirtin-class.Rd | 29 +++------ man/dgmrp_fit-class.Rd | 2 +- man/dgo_fit-class.Rd | 2 +- man/plot-method.Rd | 11 +--- man/poststratify.Rd | 2 +- man/shape.Rd | 2 +- man/toy_dgirt_in.Rd | 2 +- man/toy_dgirtfit.Rd | 2 +- 36 files changed, 194 insertions(+), 214 deletions(-) diff --git a/R/class-dgirt_fit.r b/R/class-dgirt_fit.r index 83931b0..efbe378 100644 --- a/R/class-dgirt_fit.r +++ b/R/class-dgirt_fit.r @@ -1,4 +1,4 @@ -#' Class \code{dgirt_fit}: a class for fitted models +#' A class for fitted dynamic group IRT models #' #' \code{\link{dgirt}} returns a fitted model object of class \code{dgirt_fit}, #' which inherits from \code{\link{dgo_fit}}. @@ -29,7 +29,7 @@ #' head(as.data.frame(toy_dgirtfit, pars = 'theta_bar')) dgirt_fit <- setClass("dgirt_fit", contains = c("dgo_fit")) -#' Class \code{dgirtfit}: a class for fitted models +#' A class for fitted dynamic group IRT models #' #' dgo 0.2.8 deprecated the \code{dgirtfit} class and replaced it with the #' \code{\link{dgirt_fit}} class. diff --git a/R/class-dgirtin.r b/R/class-dgirtin.r index 3007250..c7c2e29 100644 --- a/R/class-dgirtin.r +++ b/R/class-dgirtin.r @@ -1,7 +1,7 @@ -#' Class \code{dgirtIn}: data prepared for modeling with \code{dgirt} +#' A class for data ready to model #' -#' \code{shape} generates objects of class \code{dgirtIn} for modeling with -#' \code{dgirt} and \code{dgmrp}. +#' \code{shape()} generates objects of class \code{dgirtIn} for modeling with +#' \code{dgirt()} and \code{dgmrp()}. #' #' @aliases dgirtin-class, get_item_n, get_item_names, get_n, dgirtIn-method, #' print.dgirtIn, diff --git a/R/class-dgmrp_fit.r b/R/class-dgmrp_fit.r index 48bbab0..3e8341e 100644 --- a/R/class-dgmrp_fit.r +++ b/R/class-dgmrp_fit.r @@ -1,4 +1,4 @@ -#' Class \code{dgmrp_fit}: a class for fitted models +#' A class for fitted dynamic group MRP models #' #' \code{\link{dgmrp}} returns a fitted model object of class \code{dgmrp_fit}, #' which inherits from \code{\link{dgo_fit}}. diff --git a/R/class-dgo_fit.r b/R/class-dgo_fit.r index 4db9a00..41ebe73 100644 --- a/R/class-dgo_fit.r +++ b/R/class-dgo_fit.r @@ -1,4 +1,4 @@ -#' Class \code{dgo_fit}: a class for fitted models +#' A class for fitted models #' #' \code{dgo_fit} is a superclass for \code{\link{dgirt_fit}} and #' \code{\link{dgmrp_fit}} that inherits from the diff --git a/R/dgirt.r b/R/dgirt.r index e57bc85..9b65016 100644 --- a/R/dgirt.r +++ b/R/dgirt.r @@ -1,4 +1,4 @@ -#' \code{dgirt} and \code{dgmrp}: fit a DGIRT or single-issue MRP model +#' Fit a dynamic group IRT or single-issue MRP model #' #' \code{dgirt} and \code{dgmrp} make calls to \code{\link[rstan]{stan}} with #' the Stan code and data for their respective models. @@ -34,7 +34,7 @@ #' @param hierarchical_model Whether a hierarchical model should be used to #' smooth the group IRT estimates. If set to FALSE, the model will return raw #' group-IRT model estimates for each group. Default \code{TRUE}. -#' @param model A Stan model object of class `stanmodel` to be used in +#' @param model A Stan model object of class \code{stanmodel} to be used in #' estimation. Specifying this argument avoids repeated model compilation. Note #' that the Stan model object for a model fitted with \code{dgirt()} or #' \code{dgmrp()} can be found in the the \code{stanmodel} slot of the resulting diff --git a/R/methods-dgirtfit-plot.r b/R/methods-dgirtfit-plot.r index dd4665e..8f64824 100644 --- a/R/methods-dgirtfit-plot.r +++ b/R/methods-dgirtfit-plot.r @@ -4,7 +4,10 @@ utils::globalVariables(c("facet_vars")) setGeneric("dgirt_plot", signature = "x", function(x, ...) standardGeneric("dgirt_plot")) -#' \code{dgirt_plot}: plot \code{dgo_fit}-class objects +#' Plot estimates and diagnostic statistics +#' +#' \code{dgirt_plot} plots estimates from a dgo model. \code{plot_rhats} plots +#' split R-hats. #' #' @param x A \code{dgo_fit-class} object. #' @param y_fun Summary function to be plotted as \code{y}. @@ -37,15 +40,13 @@ setMethod("dgirt_plot", signature(x = "dgo_fit"), y_min, y_max) }) -#' \code{dgirt_plot}: plot \code{data.frame} objects -#' +#' @rdname plot-method #' @param group_names Discrete grouping variables, if any, which will be used as #' the \code{color} argument in \code{aes}. #' @param time_name A time variable with numeric values that will be plotted on #' the x axis. #' @param geo_name A variable representing local areas that will be used in #' faceting. -#' @rdname plot-method #' @export #' @examples #' \dontrun{ @@ -103,12 +104,10 @@ plot_internal <- function(samples, group_names, time_name, geo_name, y_fun, p } -#' \code{plot}: plot method for \code{dgo_fit}-class objects -#' +#' @rdname plot-method #' @param y Ignored. #' @param ... Further arguments to \code{\link{dgirt_plot}}. #' -#' @rdname plot-method #' @export #' @examples #' \dontrun{ @@ -125,15 +124,11 @@ setMethod("plot", signature(x = "dgo_fit", y = "missing"), setGeneric("plot_rhats", signature = "x", function(x, ...) standardGeneric("plot_rhats")) -#' \code{plot_rhats}: plot split R-hats from \code{dgo_fit}-class objects -#' -#' This function plots R-hats from a dgirt model. -#' +#' @rdname plot-method #' @param facet_vars Optionally, one or more variables passed to \code{facet_wrap} #' @param shape_var,color_var,x_var Optionally, a variable passed to the #' \code{shape}, \code{color}, or \code{x} arguments of \code{aes_string}, #' respectively. -#' @rdname plot-method #' @export #' @examples #' \dontrun{ diff --git a/R/methods-dgirtfit-poststratify.r b/R/methods-dgirtfit-poststratify.r index 2569471..68c65bf 100644 --- a/R/methods-dgirtfit-poststratify.r +++ b/R/methods-dgirtfit-poststratify.r @@ -1,6 +1,6 @@ utils::globalVariables(c("value", "scaled_prop")) -#' \code{poststratify}: reweight and aggregate estimates +#' Reweight and aggregate estimates #' #' This function reweights and aggregates estimates from \code{dgirt} for strata #' defined by modeled variables. The names of each of the model's time, diff --git a/R/methods-dgirtin.r b/R/methods-dgirtin.r index 4f52381..4bac928 100644 --- a/R/methods-dgirtin.r +++ b/R/methods-dgirtin.r @@ -1,13 +1,11 @@ #' @rdname dgirtin-class setGeneric("summary") -#' Summarize DGIRT Data -#' +#' @rdname dgirtin-class #' @param x An object of class \code{dgirtIn} as returned by \code{shape}. #' @param ... Unused. #' @param object An object of class \code{dgirtIn} as returned by \code{shape}. #' -#' @rdname dgirtin-class #' @include class-dgirtin.r #' @export setMethod("summary", c(object = "dgirtIn"), @@ -48,14 +46,12 @@ setMethod("print", c("x" = "dgirtIn"), setGeneric("get_item_names", signature = "x", function(x) standardGeneric("get_item_names")) -#' Get Items Names in DGIRT Data. -#' +#' @rdname dgirtin-class #' @return A list of item names. #' @examples #' data(toy_dgirt_in) #' get_item_names(toy_dgirt_in) #' @include class-dgirtin.r -#' @rdname dgirtin-class #' @aliases get_item_names #' @export setMethod("get_item_names", c("x" = "dgirtIn"), @@ -69,12 +65,11 @@ setGeneric("get_n", signature = c("x", "by", "aggregate_name"), function(x, by = NULL, aggregate_name = NULL) standardGeneric("get_n")) -#' Count Respondents in DGIRT Data. -#' +#' @rdname dgirtin-class #' @param by The name of a grouping variable. -#' @param aggregate_name If specified `get_n` will operate on the table passed -#' to `shape` as `aggregate_data` instead of on the individual data and count -#' nonmissingness in the given variable. +#' @param aggregate_name If specified \code{get_n} will operate on the table +#' passed to \code{shape} as \code{aggregate_data} instead of on the individual +#' data and count nonmissingness in the given variable. #' #' @examples #' # respondent count @@ -87,10 +82,8 @@ setGeneric("get_n", signature = c("x", "by", "aggregate_name"), #' # respondent count by year and survey identifier #' get_n(toy_dgirt_in, by = c("year", "source")) #' -#' @seealso `\link{get_item_n}, \link{get_item_names}` #' @include class-dgirtin.r #' @aliases get_n -#' @rdname dgirtin-class #' @export setMethod("get_n", c("x" = "dgirtIn"), function(x, by = NULL, aggregate_name = NULL) { @@ -117,17 +110,15 @@ stop_if_no_aggregates <- function(x) { setGeneric("get_item_n", signature = c("x", "by", "aggregate_data"), function(x, by = NULL, aggregate_data = FALSE) standardGeneric("get_item_n")) -#' Count Respondents for Items in DGIRT Data -#' -#' @include class-dgirtin.r #' @rdname dgirtin-class +#' @include class-dgirtin.r #' @examples #' data(toy_dgirt_in) #' get_item_n(toy_dgirt_in) #' get_item_n(toy_dgirt_in, by = "year") #' @aliases get_item_n -#' @param aggregate_data If specified `get_item_n` will operate on the table passed -#' to `shape` as `aggregate_data` instead of on the individual data. +#' @param aggregate_data If specified \code{get_item_n} will operate on the table passed +#' to \code{shape} as \code{aggregate_data} instead of on the individual data. #' @export setMethod("get_item_n", c("x" = "dgirtIn"), function(x, by = NULL, aggregate_data = FALSE) { @@ -157,8 +148,7 @@ zero_nas <- function(n, by) { .SDcols = setdiff(names(n), by)] } -#' Show Summary of DGIRT Data -#' @include class-dgirtin.r #' @rdname dgirtin-class +#' @include class-dgirtin.r #' @export setMethod("show", c("dgirtIn"), function(object) summary(object)) diff --git a/R/shape.r b/R/shape.r index eacfe9b..9e88f17 100644 --- a/R/shape.r +++ b/R/shape.r @@ -1,4 +1,4 @@ -#' \code{shape}: prepare data for modeling with \code{dgirt} or \code{dgmrp} +#' Prepare data for modeling #' #' This function shapes data for use in a dgirt or dgmrp model. Most #' arguments give the name or names of key variables in the data. These diff --git a/R/toy_dgirt_in.r b/R/toy_dgirt_in.r index 670a88c..8868abe 100644 --- a/R/toy_dgirt_in.r +++ b/R/toy_dgirt_in.r @@ -1,4 +1,4 @@ -#' Class \code{dgirtIn}: a minimal example object +#' A minimal example of shaped data #' #' \code{\link[dgo]{shape}} returns a \code{\link[dgo]{dgirtin-class}} object #' used with \code{\link[dgo]{dgirt}} for DGIRT modeling. \code{toy_dgirt_in} is diff --git a/R/toy_dgirtfit.r b/R/toy_dgirtfit.r index 8a07ea9..2832c66 100644 --- a/R/toy_dgirtfit.r +++ b/R/toy_dgirtfit.r @@ -1,4 +1,4 @@ -#' Class \code{dgirtfit}: a minimal example object +#' A minimal example of a fitted model #' #' \code{\link[dgo]{dgirt}} returns a \code{\link[dgo]{dgirtfit}}-class object #' that extends \code{\link[rstan]{stanfit-class}}. \code{toy_dgirtfit} is a diff --git a/_pkgdown.yml b/_pkgdown.yml index 13d40c9..3edd979 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -15,11 +15,15 @@ reference: contents: - shape - toy_dgirt_in + - dgirtin-class - title: Estimation contents: - dgirt - dgmrp - toy_dgirtfit + - dgirt_fit-class + - dgmrp_fit-class + - dgo_fit-class - title: Postestimation contents: - poststratify diff --git a/docs/reference/dgirt.html b/docs/reference/dgirt.html index 7979717..f6709d5 100644 --- a/docs/reference/dgirt.html +++ b/docs/reference/dgirt.html @@ -6,7 +6,7 @@ -<code>dgirt</code> and <code>dgmrp</code>: fit a DGIRT or single-issue MRP model — dgirt • dgo +Fit a dynamic group IRT or single-issue MRP model — dgirt • dgo @@ -84,7 +84,7 @@
-

dgirt and dgmrp: fit a DGIRT or single-issue MRP model

+

Fit a dynamic group IRT or single-issue MRP model

@@ -155,7 +155,7 @@

Ar model -

A Stan model object of class `stanmodel` to be used in +

A Stan model object of class stanmodel to be used in estimation. Specifying this argument avoids repeated model compilation. Note that the Stan model object for a model fitted with dgirt() or dgmrp() can be found in the the stanmodel slot of the resulting diff --git a/docs/reference/dgirt_fit-class.html b/docs/reference/dgirt_fit-class.html index e7a1ed8..83d73a2 100644 --- a/docs/reference/dgirt_fit-class.html +++ b/docs/reference/dgirt_fit-class.html @@ -6,7 +6,7 @@ -Class <code>dgirt_fit</code>: a class for fitted models — dgirt_fit-class • dgo +A class for fitted dynamic group IRT models — dgirt_fit-class • dgo @@ -84,7 +84,7 @@

-

Class dgirt_fit: a class for fitted models

+

A class for fitted dynamic group IRT models

@@ -114,48 +114,48 @@

Examp 
data(toy_dgirtfit)
 # summarize the fitted results
 summary(toy_dgirtfit, pars = 'xi')
#> dgirt samples from 4 chains of 400 iterations, 200 warmup, thinned every 1 
-#>   Drawn Thu Oct 26 09:22:11 2017 
+#>   Drawn Sat Oct 28 09:40:04 2017 
 #>   Package version 0.2.11 
 #>   Model version 2017_01_04 
 #>   43 parameters; 12 theta_bars (year state race3)
 #>   2 periods 2009 to 2010 
 #> 
 #> n_eff
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
-#>   51.66  125.45  234.09  280.10  379.44  800.00 
#> 
+#>    47.4   122.5   152.3   241.1   323.1   667.5 
#> 
 #> Rhat
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
-#>  0.9977  1.0027  1.0061  1.0102  1.0126  1.0461 
#> 
+#>  0.9967  1.0051  1.0161  1.0140  1.0214  1.0394 
#> 
 #> Elapsed time
#>    chain warmup sample total
-#> 1:     1     4S     5S    9S
-#> 2:     2     4S     6S   10S
-#> 3:     3     6S     5S   11S
-#> 4:     4     5S     4S    9S

+#> 1:     1     4S     3S    7S
+#> 2:     2     4S     4S    8S
+#> 3:     3     4S     3S    7S
+#> 4:     4     4S     3S    7S

 # get posterior means with a convenience function
-get_posterior_mean(toy_dgirtfit, pars = 'theta_bar')
#>         param state race3 year        mean
-#>  1: theta_bar    SC black 2009  2.24559756
-#>  2: theta_bar    SC black 2010  1.15755259
-#>  3: theta_bar    SC other 2009 -1.29813621
-#>  4: theta_bar    SC other 2010  0.03000299
-#>  5: theta_bar    SC white 2009 -1.59792561
-#>  6: theta_bar    SC white 2010 -1.29950834
-#>  7: theta_bar    VA black 2009  2.02881527
-#>  8: theta_bar    VA black 2010  1.40617435
-#>  9: theta_bar    VA other 2009 -0.93038106
-#> 10: theta_bar    VA other 2010  0.27922913
-#> 11: theta_bar    VA white 2009 -0.91333932
-#> 12: theta_bar    VA white 2010 -0.71577875

+get_posterior_mean(toy_dgirtfit, pars = 'theta_bar')
#>         param state race3 year       mean
+#>  1: theta_bar    SC black 2009  2.3366278
+#>  2: theta_bar    SC black 2010  1.2377753
+#>  3: theta_bar    SC other 2009 -1.3572482
+#>  4: theta_bar    SC other 2010  0.0488835
+#>  5: theta_bar    SC white 2009 -1.6299612
+#>  6: theta_bar    SC white 2010 -1.3977524
+#>  7: theta_bar    VA black 2009  2.0786160
+#>  8: theta_bar    VA black 2010  1.4686529
+#>  9: theta_bar    VA other 2009 -1.0419862
+#> 10: theta_bar    VA other 2010  0.2789239
+#> 11: theta_bar    VA white 2009 -0.9452116
+#> 12: theta_bar    VA white 2010 -0.8000586

 # generally apply functions to posterior samples after warmup; n.b.
 # `as.array` is iterations x chains x parameters so `MARGIN = 3` applies
 # `FUN` over iterations and chains
-apply(as.array(toy_dgirtfit, pars = 'xi'), 3, mean)
#>     xi[1]     xi[2] 
-#> 1.4992850 0.1369921 

+apply(as.array(toy_dgirtfit, pars = 'xi'), 3, mean)
#>    xi[1]    xi[2] 
+#> 1.632168 0.104962 

 # access the posterior samples
-head(as.data.frame(toy_dgirtfit, pars = 'theta_bar'))
#>        param state race3 year iteration     value
-#> 1: theta_bar    SC black 2009         1 2.3585309
-#> 2: theta_bar    SC black 2009         2 3.7881672
-#> 3: theta_bar    SC black 2009         3 2.5182470
-#> 4: theta_bar    SC black 2009         4 4.9504883
-#> 5: theta_bar    SC black 2009         5 0.5702558
-#> 6: theta_bar    SC black 2009         6 1.4339072
+head(as.data.frame(toy_dgirtfit, pars = 'theta_bar'))

#> param state race3 year iteration value +#> 1: theta_bar SC black 2009 1 3.116552 +#> 2: theta_bar SC black 2009 2 4.538157 +#> 3: theta_bar SC black 2009 3 1.369630 +#> 4: theta_bar SC black 2009 4 2.999939 +#> 5: theta_bar SC black 2009 5 1.752752 +#> 6: theta_bar SC black 2009 6 1.553516