From 8ea84920737412023c310275573347d1088dd48a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20L=C3=BCdecke?= Date: Sun, 5 Mar 2017 09:42:58 +0100 Subject: [PATCH] release 2.3.1 on CRAN --- DESCRIPTION | 6 +- NEWS | 4 +- NEWS.md | 4 +- R/set_theme.R | 48 +++--- R/sjPlotAnova.R | 52 +++---- R/sjPlotClusterAnalysis.R | 298 ++++++++++++++++++------------------- R/sjPlotCorr.R | 12 +- R/sjPlotDist.R | 188 ++++++++++++----------- R/sjPlotFrequencies.R | 224 ++++++++++++++-------------- R/sjPlotGLME.R | 41 ++--- R/sjPlotGroupFrequencies.R | 278 +++++++++++++++++----------------- R/sjPlotGroupPropTable.R | 18 +-- R/sjPlotInteractions.R | 194 ++++++++++++------------ R/sjPlotLikert.R | 49 +++--- R/sjPlotLinreg.R | 26 ++-- R/sjPlotOdds.R | 8 +- R/sjPlotOddsMultiple.R | 106 ++++++------- R/sjPlotPCA.R | 123 ++++++--------- R/sjPlotPearsonsChi2Test.R | 39 ++--- R/sjPlotPolynomials.R | 66 ++++---- R/sjPlotPropTable.R | 82 +++++----- R/sjPlotResiduals.R | 60 ++++---- R/sjPlotScatter.R | 42 +++--- R/sjPlotSetTheme.R | 54 +++---- R/sjPlotStackFrequencies.R | 92 +++++------- R/sjTabCorr.R | 8 +- R/sjTabFrequencies.R | 57 +++---- R/sjTabGrpmean.R | 2 +- R/sjTabItemAnalysis.R | 102 ++++++------- R/sjTabLinReg.R | 82 +++++----- R/sjTabMannWhitney.R | 2 +- R/sjTabOdds.R | 14 +- R/sjTabPCA.R | 128 ++++++++-------- R/sjTabPropTable.R | 24 +-- R/sjTabSPSS.R | 91 ++++++----- man/dist_chisq.Rd | 18 +-- man/dist_f.Rd | 16 +- man/dist_norm.Rd | 18 +-- man/dist_t.Rd | 14 +- man/set_theme.Rd | 2 +- man/sjc.cluster.Rd | 40 ++--- man/sjc.dend.Rd | 14 +- man/sjc.elbow.Rd | 4 +- man/sjc.grpdisc.Rd | 4 +- man/sjc.kgap.Rd | 12 +- man/sjc.qclus.Rd | 68 ++++----- man/sjp.aov1.Rd | 47 +++--- man/sjp.chi2.Rd | 8 +- man/sjp.corr.Rd | 16 +- man/sjp.frq.Rd | 93 ++++++------ man/sjp.glm.Rd | 67 +++++---- man/sjp.glmer.Rd | 75 +++++----- man/sjp.glmm.Rd | 55 +++---- man/sjp.gpt.Rd | 30 ++-- man/sjp.grpfrq.Rd | 90 +++++------ man/sjp.int.Rd | 104 ++++++------- man/sjp.likert.Rd | 71 ++++----- man/sjp.lm.Rd | 67 +++++---- man/sjp.lmer.Rd | 71 ++++----- man/sjp.lmm.Rd | 43 +++--- man/sjp.pca.Rd | 97 ++++-------- man/sjp.poly.Rd | 43 +++--- man/sjp.resid.Rd | 20 +-- man/sjp.scatter.Rd | 44 +++--- man/sjp.setTheme.Rd | 54 +++---- man/sjp.stackfrq.Rd | 50 ++----- man/sjp.xtab.Rd | 76 +++++----- man/sjt.corr.Rd | 40 ++--- man/sjt.df.Rd | 16 +- man/sjt.frq.Rd | 76 +++++----- man/sjt.glm.Rd | 94 ++++++------ man/sjt.glmer.Rd | 90 +++++------ man/sjt.grpmean.Rd | 26 ++-- man/sjt.itemanalysis.Rd | 44 +++--- man/sjt.lm.Rd | 94 ++++++------ man/sjt.lmer.Rd | 94 ++++++------ man/sjt.mwu.Rd | 18 +-- man/sjt.pca.Rd | 60 +++----- man/sjt.stackfrq.Rd | 32 ++-- man/sjt.xtab.Rd | 48 +++--- man/view_df.Rd | 47 +++--- 81 files changed, 2353 insertions(+), 2481 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 1a3dc479..fce646f2 100755 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,8 +2,8 @@ Package: sjPlot Type: Package Encoding: UTF-8 Title: Data Visualization for Statistics in Social Science -Version: 2.3.0.9001 -Date: 2017-02-14 +Version: 2.3.1 +Date: 2017-03-04 Authors@R: c( person("Daniel", "Lüdecke", email = "d.luedecke@uke.de", role = c("aut", "cre")), person("Carsten", "Schwemmer", email = "carsten.schwemmer@uni-bamberg.de", role = "ctb") @@ -39,7 +39,7 @@ Imports: purrr, scales, sjmisc (>= 2.3.0), - sjstats (>= 0.8.0.9000), + sjstats (>= 0.8.0), tibble (>= 1.2.0), tidyr (>= 0.6.0) Suggests: diff --git a/NEWS b/NEWS index 68b2488c..a7d57aa4 100755 --- a/NEWS +++ b/NEWS @@ -1,4 +1,4 @@ -Version 2.3.0.9000 +Version 2.3.1 ----------------------------------------------------------------------------- General: * All `sjt`-functions can now be directly integrated into knitr-code-chunks, because sjPlot exports a knitr-print-method (see `vignette("sjtbasic", "sjPlot")`). @@ -15,7 +15,7 @@ Changes to functions: * Argument `emph.p` for printing tables of regression models now defaults to `FALSE`. Bug fixes: -* Fixed bug in `sjt.frq()` for variables with many missign values and labelled values that did not occur on that variable. +* Fixed bug in `sjt.frq()` for variables with many missing values and labelled values that did not occur on that variable. * Argument `value.labels` had no effect for `sjt.frq()`. * Automatic label detection in `sjt.grpmean()` sometimes not worked for factors without variable labels. * `sjp.glm()` used "Odds Ratios" as default title for y-axis when plotting marginal effects. Fixed, now y-axis is correctly labelled. diff --git a/NEWS.md b/NEWS.md index 9aa8a42b..08afd163 100755 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# sjPlot 2.3.0.9000 +# sjPlot 2.3.1 ## General @@ -18,7 +18,7 @@ ## Bug fixes -* Fixed bug in `sjt.frq()` for variables with many missign values and labelled values that did not occur on that variable. +* Fixed bug in `sjt.frq()` for variables with many missing values and labelled values that did not occur on that variable. * Argument `value.labels` had no effect for `sjt.frq()`. * Automatic label detection in `sjt.grpmean()` sometimes not worked for factors without variable labels. * `sjp.glm()` used _Odds Ratios_ as default title for y-axis when plotting marginal effects. Fixed, now y-axis is correctly labelled. diff --git a/R/set_theme.R b/R/set_theme.R index ae1823a4..44727d11 100755 --- a/R/set_theme.R +++ b/R/set_theme.R @@ -1,8 +1,8 @@ #' @title Set default theme for sjp-functions #' @name set_theme -#' +#' #' @description Set default theme for sjp-functions. -#' +#' #' @param theme Name of a pre-set theme. May be one of: #' \describe{ #' \item{\code{"blank"}}{a theme with no grids and axes.} @@ -12,25 +12,25 @@ #' \item{\code{"scatter"}}{a theme for scatter plots in 539-theme-style.} #' \item{\code{"538w"}, \code{"539w"}, \code{"scatterw"} and \code{"forestw"}}{for themes as described above, however all with white backgrounds.} #' } -#' @param ... other arguments passed down to \code{\link{sjp.setTheme}}. -#' +#' @param ... Other arguments passed down to \code{\link{sjp.setTheme}}. +#' #' @return The customized theme object. -#' +#' #' @seealso \href{http://www.strengejacke.de/sjPlot/custplot/}{sjPlot manual: customize plot appearance} -#' +#' #' @references \itemize{ #' \item \href{http://zevross.com/blog/2014/08/04/beautiful-plotting-in-r-a-ggplot2-cheatsheet-3/}{Beautiful plotting in R: A ggplot2 cheatsheet} #' \item \href{http://minimaxir.com/2015/02/ggplot-tutorial/}{An Introduction on How to Make Beautiful Charts With R and ggplot2} #' } -#' +#' #' @examples #' library(sjmisc) #' data(efc) -#' +#' #' # of the ggplot base theme #' set_theme("539") #' sjp.xtab(efc$e42dep, efc$e16sex) -#' +#' #' @import ggplot2 #' @importFrom scales brewer_pal grey_pal #' @importFrom dplyr case_when @@ -38,9 +38,9 @@ set_theme <- function(theme = c("forest", "538", "539", "scatter", "forestw", "538w", "539w", "scatterw", "blank"), ...) { - + theme <- match.arg(theme) - + if (theme == "blank") { return(sjp.setTheme( base = theme_classic(), @@ -51,12 +51,12 @@ set_theme <- function(theme = c("forest", "538", "539", "scatter", "forestw", ... )) } - + g.palette <- scales::brewer_pal(palette = "Greys")(9) col.ind <- dplyr::case_when( - theme == "538" ~ 2, - theme == "539" ~ 2, + theme == "538" ~ 2, + theme == "539" ~ 2, theme == "forest" ~ 2, theme == "scatter" ~ 2, theme == "539w" ~ 1, @@ -70,36 +70,36 @@ set_theme <- function(theme = c("forest", "538", "539", "scatter", "forestw", theme %in% c("forest", "forestw") ~ col.ind, TRUE ~ 4 ) - + axis.linecolor <- dplyr::case_when( - theme == "538" ~ g.palette[col.ind], + theme == "538" ~ g.palette[col.ind], theme == "538w" ~ g.palette[col.ind], TRUE ~ g.palette[5] ) - + axis.linecolor.x <- dplyr::case_when( - theme == "538" ~ g.palette[col.ind], + theme == "538" ~ g.palette[col.ind], theme == "538w" ~ g.palette[col.ind], TRUE ~ g.palette[5] ) - + axis.linecolor.y <- dplyr::case_when( - theme == "scatter" ~ g.palette[5], + theme == "scatter" ~ g.palette[5], theme == "scatterw" ~ g.palette[5], TRUE ~ g.palette[col.ind] ) - + panel.gridcol.x <- dplyr::case_when( theme %in% c("539", "539w", "538", "538w", "forest", "forestw") ~ g.palette[col.ind], TRUE ~ g.palette[4] - ) - + ) + if (theme %in% c("scatter", "scatterw")) { panel.major.linetype <- panel.minor.linetype <- 2 } else { panel.major.linetype <- panel.minor.linetype <- NULL } - + return(sjp.setTheme( base = ggplot2::theme_bw(), # plot diff --git a/R/sjPlotAnova.R b/R/sjPlotAnova.R index 790ea018..60ddc67c 100755 --- a/R/sjPlotAnova.R +++ b/R/sjPlotAnova.R @@ -4,41 +4,41 @@ utils::globalVariables(c("pv", "xv")) #' @title Plot One-Way-Anova tables #' @name sjp.aov1 -#' -#' @description Plot One-Way-Anova table sum of squares (SS) of each factor level (group) -#' against the dependent variable. The SS of the factor variable against the +#' +#' @description Plot One-Way-Anova table sum of squares (SS) of each factor level (group) +#' against the dependent variable. The SS of the factor variable against the #' dependent variable (variance within and between groups) is printed to #' the model summary. -#' +#' #' @seealso \code{\link{sjt.grpmean}} -#' -#' @param var.dep dependent variable. Will be used with following formula: +#' +#' @param var.dep Dependent variable. Will be used with following formula: #' \code{aov(var.dep ~ var.grp)} -#' @param var.grp factor with the cross-classifying variable, where \code{var.dep} +#' @param var.grp Factor with the cross-classifying variable, where \code{var.dep} #' is grouped into the categories represented by \code{var.grp}. -#' @param meansums logical, if \code{TRUE}, the values reported are the true group mean values (see also \code{\link{sjt.grpmean}}). +#' @param meansums Logical, if \code{TRUE}, the values reported are the true group mean values (see also \code{\link{sjt.grpmean}}). #' If \code{FALSE} (default), the values are reported in the standard way, i.e. the values indicate the difference of #' the group mean in relation to the intercept (reference group). -#' @param string.interc string that indicates the reference group (intercept), that is appended to +#' @param string.interc Character vector that indicates the reference group (intercept), that is appended to #' the value label of the grouping variable. Default is \code{"(Intercept)"}. -#' +#' #' @inheritParams sjp.grpfrq #' @inheritParams sjp.lm #' @inheritParams sjp.glmer #' @inheritParams sjp.xtab #' @inheritParams sjp.gpt -#' +#' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{df}). -#' +#' #' @examples #' library(sjmisc) #' data(efc) #' # note: "var.grp" does not need to be a factor. #' # coercion to factor is done by the function #' sjp.aov1(efc$c12hour, efc$e42dep) -#' -#' +#' +#' #' @import ggplot2 #' @importFrom sjmisc get_label get_labels trim word_wrap to_value #' @importFrom stats confint aov summary.lm @@ -72,7 +72,7 @@ sjp.aov1 <- function(var.dep, # -------------------------------------------------------- # try to automatically set labels is not passed as parameter # -------------------------------------------------------- - if (is.null(axis.labels)) axis.labels <- sjmisc::get_labels(var.grp, + if (is.null(axis.labels)) axis.labels <- sjmisc::get_labels(var.grp, attr.only = F, include.values = NULL, include.non.labelled = T) @@ -86,8 +86,8 @@ sjp.aov1 <- function(var.dep, # remove titles if empty # -------------------------------------------------------- if (!is.null(axis.labels) && axis.labels == "") axis.labels <- NULL - if (!is.null(axis.title) && axis.title == "") axis.title <- NULL - if (!is.null(title) && title == "") title <- NULL + if (!is.null(axis.title) && axis.title == "") axis.title <- NULL + if (!is.null(title) && title == "") title <- NULL # -------------------------------------------------------- # unlist labels # -------------------------------------------------------- @@ -179,7 +179,7 @@ sjp.aov1 <- function(var.dep, if (show.p) { for (i in seq_len(length(means.p))) { ps[i] <- sjmisc::trim(paste(ps[i], get_p_stars(means.p[i]))) - } + } } # -------------------------------------------------------- # check whether order of category items should be reversed @@ -229,7 +229,7 @@ sjp.aov1 <- function(var.dep, minval <- min(df$lower) if (maxval > 0) limfac <- ifelse(abs(maxval) < 5, 5, 10) - else + else limfac <- ifelse(abs(minval) < 5, 5, 10) upper_lim <- ifelse(maxval == 0, 0, limfac * ceiling((maxval + 1) / limfac)) lower_lim <- ifelse(minval == 0, 0, limfac * floor(minval / limfac)) @@ -245,9 +245,9 @@ sjp.aov1 <- function(var.dep, # -------------------------------------------------------- # Set up plot padding (margins inside diagram) # -------------------------------------------------------- - scaley <- scale_y_continuous(limits = c(lower_lim, upper_lim), - breaks = ticks, - labels = ticks) + scaley <- scale_y_continuous(limits = c(lower_lim, upper_lim), + breaks = ticks, + labels = ticks) # -------------------------------------------------------- # Start plot here! # -------------------------------------------------------- @@ -256,7 +256,7 @@ sjp.aov1 <- function(var.dep, geom_point(size = geom.size, colour = df$geocol) + # and error bar geom_errorbar(aes(ymin = lower, ymax = upper), colour = df$geocol, width = 0) + - # Print p-values. With vertical adjustment, so + # Print p-values. With vertical adjustment, so # they don't overlap with the errorbars geom_text(aes(label = pv, y = means), nudge_x = y.offset, show.legend = FALSE) + # set y-scale-limits, breaks and tick labels @@ -270,8 +270,8 @@ sjp.aov1 <- function(var.dep, if (show.summary) { # add annotations with model summary # annotations include intercept-value and model's r-square - anovaplot <- anovaplot + - annotate("text", label = modsum, parse = TRUE, x = -Inf, y = Inf, + anovaplot <- anovaplot + + annotate("text", label = modsum, parse = TRUE, x = -Inf, y = Inf, hjust = "right", vjust = "bottom") } # --------------------------------------------------------- @@ -282,7 +282,7 @@ sjp.aov1 <- function(var.dep, # set proper column names # ------------------------------------- df <- tibble::rownames_to_column(df) - colnames(df) <- c("term", "estimate", "conf.low", "conf.high", + colnames(df) <- c("term", "estimate", "conf.low", "conf.high", "p.value", "p.string", "xpos", "geom.color") # ------------------------------------- # return results diff --git a/R/sjPlotClusterAnalysis.R b/R/sjPlotClusterAnalysis.R index 7315f76e..268732c2 100755 --- a/R/sjPlotClusterAnalysis.R +++ b/R/sjPlotClusterAnalysis.R @@ -6,18 +6,18 @@ utils::globalVariables(c("xpos", "value", "Var2", "grp", "prc", "fg", "cprc", "s #' @name sjc.qclus #' @description Compute a quick kmeans or hierarchical cluster analysis and displays "cluster characteristics" #' as plot. -#' +#' #' @references Maechler M, Rousseeuw P, Struyf A, Hubert M, Hornik K (2014) cluster: Cluster Analysis Basics and Extensions. R package. -#' -#' @param data \code{data.frame} with variables that should be used for the +#' +#' @param data A data frame with variables that should be used for the #' cluster analysis. -#' @param groupcount amount of groups (clusters) used for the cluster solution. May also be +#' @param groupcount Amount of groups (clusters) used for the cluster solution. May also be #' a set of initial (distinct) cluster centres, in case \code{method = "kmeans"} -#' (see \code{\link{kmeans}} for details on \code{centers} argument). -#' If \code{groupcount = NULL} and \code{method = "kmeans"}, the optimal -#' amount of clusters is calculated using the gap statistics (see +#' (see \code{\link{kmeans}} for details on \code{centers} argument). +#' If \code{groupcount = NULL} and \code{method = "kmeans"}, the optimal +#' amount of clusters is calculated using the gap statistics (see #' \code{\link{sjc.kgap}}). For \code{method = "hclust"}, \code{groupcount} -#' needs to be specified. Following functions may be helpful for estimating +#' needs to be specified. Following functions may be helpful for estimating #' the amount of clusters: #' \itemize{ #' \item Use \code{\link{sjc.elbow}} to determine the group-count depending on the elbow-criterion. @@ -25,48 +25,48 @@ utils::globalVariables(c("xpos", "value", "Var2", "grp", "prc", "fg", "cprc", "s #' \item If \code{method = "hclust"} (hierarchical clustering, default), use \code{\link{sjc.dend}} to inspect different cluster group solutions. #' \item Use \code{\link{sjc.grpdisc}} to inspect the goodness of grouping (accuracy of classification). #' } -#' @param groups optional, by default, this argument is \code{NULL} and will be +#' @param groups Optional, by default, this argument is \code{NULL} and will be #' ignored. However, to plot existing cluster groups, specify \code{groupcount} -#' and \code{groups}. \code{groups} is a vector of same length as -#' \code{nrow(data)} and indicates the group classification of the cluster +#' and \code{groups}. \code{groups} is a vector of same length as +#' \code{nrow(data)} and indicates the group classification of the cluster #' analysis. The group classification can be computed with the #' \code{\link{sjc.cluster}} function. See 'Examples'. -#' @param method method for computing the cluster analysis. By default (\code{"kmeans"}), a -#' kmeans cluster analysis will be computed. Use \code{"hclust"} to -#' compute a hierarchical cluster analysis. You can specify the +#' @param method Method for computing the cluster analysis. By default (\code{"kmeans"}), a +#' kmeans cluster analysis will be computed. Use \code{"hclust"} to +#' compute a hierarchical cluster analysis. You can specify the #' initial letters only. -#' @param distance distance measure to be used when \code{method = "hclust"} (for hierarchical -#' clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, +#' @param distance Distance measure to be used when \code{method = "hclust"} (for hierarchical +#' clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, #' \code{"canberra"}, \code{"binary"} or \code{"minkowski"}. See \code{\link{dist}}. #' If is \code{method = "kmeans"} this argument will be ignored. -#' @param agglomeration agglomeration method to be used when \code{method = "hclust"} (for hierarchical -#' clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, +#' @param agglomeration Agglomeration method to be used when \code{method = "hclust"} (for hierarchical +#' clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, #' \code{"mcquitty"}, \code{"median"} or \code{"centroid"}. Default is \code{"ward"} (see \code{\link{hclust}}). #' If \code{method = "kmeans"} this argument will be ignored. See 'Note'. -#' @param iter.max maximum number of iterations allowed. Only applies, if +#' @param iter.max Maximum number of iterations allowed. Only applies, if #' \code{method = "kmeans"}. See \code{\link{kmeans}} for details on this argument. -#' @param algorithm algorithm used for calculating kmeans cluster. Only applies, if -#' \code{method = "kmeans"}. May be one of \code{"Hartigan-Wong"} (default), -#' \code{"Lloyd"} (used by SPSS), or \code{"MacQueen"}. See \code{\link{kmeans}} +#' @param algorithm Algorithm used for calculating kmeans cluster. Only applies, if +#' \code{method = "kmeans"}. May be one of \code{"Hartigan-Wong"} (default), +#' \code{"Lloyd"} (used by SPSS), or \code{"MacQueen"}. See \code{\link{kmeans}} #' for details on this argument. -#' @param show.accuracy logical, if \code{TRUE}, the \code{\link{sjc.grpdisc}} function will be called, -#' which computes a linear discriminant analysis on the classified cluster groups and plots a +#' @param show.accuracy Logical, if \code{TRUE}, the \code{\link{sjc.grpdisc}} function will be called, +#' which computes a linear discriminant analysis on the classified cluster groups and plots a #' bar graph indicating the goodness of classification for each group. -#' @param show.grpcnt if \code{TRUE} (default), the count within each cluster group is added to the +#' @param show.grpcnt Logical, if \code{TRUE} (default), the count within each cluster group is added to the #' legend labels (e.g. \code{"Group 1 (n=87)"}). -#' @param reverse.axis if \code{TRUE}, the values on the x-axis are reversed. +#' @param reverse.axis Logical, if \code{TRUE}, the values on the x-axis are reversed. #' #' @inheritParams sjp.grpfrq #' #' @return (Invisibly) returns an object with #' \itemize{ -#' \item \code{data}: the used data frame for plotting, +#' \item \code{data}: the used data frame for plotting, #' \item \code{plot}: the ggplot object, #' \item \code{groupcount}: the number of found cluster (as calculated by \code{\link{sjc.kgap}}) #' \item \code{classification}: the group classification (as calculated by \code{\link{sjc.cluster}}), including missing values, so this vector can be appended to the original data frame. #' \item \code{accuracy}: the accuracy of group classification (as calculated by \code{\link{sjc.grpdisc}}). #' } -#' +#' #' @details Following steps are computed in this function: #' \enumerate{ #' \item If \code{method = "kmeans"}, this function first determines the optimal group count via gap statistics (unless argument \code{groupcount} is specified), using the \code{\link{sjc.kgap}} function. @@ -76,27 +76,27 @@ utils::globalVariables(c("xpos", "value", "Var2", "grp", "prc", "fg", "cprc", "s #' } #' This method can also be used to plot existing cluster solution as graph witouth computing #' a new cluster analysis. See argument \code{groups} for more details. -#' +#' #' @note See 'Note' in \code{\link{sjc.cluster}} -#' +#' #' @examples #' \dontrun{ #' # k-means clustering of mtcars-dataset #' sjc.qclus(mtcars) -#' +#' #' # k-means clustering of mtcars-dataset with 4 pre-defined #' # groups in a faceted panel #' sjc.qclus(airquality, groupcount = 4, facet.grid = TRUE)} -#' +#' #' # k-means clustering of airquality data #' # and saving the results. most likely, 3 cluster #' # groups have been found (see below). #' airgrp <- sjc.qclus(airquality) -#' +#' #' # "re-plot" cluster groups, without computing #' # new k-means cluster analysis. #' sjc.qclus(airquality, groupcount = 3, groups = airgrp$classification) -#' +#' #' @import ggplot2 #' @importFrom stats na.omit #' @importFrom graphics plot @@ -148,9 +148,9 @@ sjc.qclus <- function(data, # Trim labels and title to appropriate size # -------------------------------------------------------- # check length of diagram title and split longer string at into new lines - if (!is.null(title)) title <- sjmisc::word_wrap(title, wrap.title) + if (!is.null(title)) title <- sjmisc::word_wrap(title, wrap.title) # check length of legend title and split longer string at into new lines - if (!is.null(legend.title)) legend.title <- sjmisc::word_wrap(title, wrap.legend.title) + if (!is.null(legend.title)) legend.title <- sjmisc::word_wrap(title, wrap.legend.title) # check length of y-axis title and split longer string at into new lines if (!is.null(legend.labels)) legend.labels <- sjmisc::word_wrap(legend.labels, wrap.legend.labels) # check length of x-axis-labels and split longer strings at into new lines @@ -200,9 +200,9 @@ sjc.qclus <- function(data, # -------------------------------------------------------- # show goodness of classification # -------------------------------------------------------- - grp.accuracy <- sjc.grpdisc(data, - groups = grp, - groupcount = groupcount, + grp.accuracy <- sjc.grpdisc(data, + groups = grp, + groupcount = groupcount, prnt.plot = show.accuracy) # --------------------------------------------- # Add group count to legend labels @@ -261,11 +261,11 @@ sjc.qclus <- function(data, gp <- ggplot(df, aes_string(x = "x", y = "y", fill = "group")) } gp <- gp + - geom_bar(stat = "identity", - position = position_dodge(geom.size + geom.spacing), + geom_bar(stat = "identity", + position = position_dodge(geom.size + geom.spacing), width = geom.size) + - scale_x_discrete(breaks = seq_len(colnr), - limits = seq_len(colnr), + scale_x_discrete(breaks = seq_len(colnr), + limits = seq_len(colnr), labels = axis.labels) + labs(title = title, x = "Cluster group characteristics", y = "Mean of z-scores", fill = legend.title) # -------------------------------------------------------- @@ -280,11 +280,11 @@ sjc.qclus <- function(data, # --------------------------------------------------------- # set geom colors # --------------------------------------------------------- - gp <- sj.setGeomColors(gp, - geom.colors, - length(legend.labels), + gp <- sj.setGeomColors(gp, + geom.colors, + length(legend.labels), show.legend, - legend.labels) + legend.labels) # -------------------------------------------------------- # plot # -------------------------------------------------------- @@ -305,19 +305,19 @@ sjc.qclus <- function(data, #' @name sjc.cluster #' @description Compute hierarchical or kmeans cluster analysis and return the group #' association for each observation as vector. -#' +#' #' @references Maechler M, Rousseeuw P, Struyf A, Hubert M, Hornik K (2014) cluster: Cluster Analysis Basics and Extensions. R package. #' #' @inheritParams sjc.qclus -#' +#' #' @return The group classification for each observation as vector. This group #' classification can be used for \code{\link{sjc.grpdisc}}-function to #' check the goodness of classification. -#' The returned vector includes missing values, so it can be appended +#' The returned vector includes missing values, so it can be appended #' to the original data frame \code{data}. -#' -#' @note Since R version > 3.0.3, the \code{"ward"} option has been replaced by -#' either \code{"ward.D"} or \code{"ward.D2"}, so you may use one of +#' +#' @note Since R version > 3.0.3, the \code{"ward"} option has been replaced by +#' either \code{"ward.D"} or \code{"ward.D2"}, so you may use one of #' these values. When using \code{"ward"}, it will be replaced by \code{"ward.D2"}. #' \cr \cr #' To get similar results as in SPSS Quick Cluster function, following points @@ -330,14 +330,14 @@ sjc.qclus <- function(data, #' } #' This ensures a fixed initial set of cluster centers (as in SPSS), while \code{\link{kmeans}} in R #' always selects initial cluster sets randomly. -#' +#' #' @examples #' # Hierarchical clustering of mtcars-dataset #' groups <- sjc.cluster(mtcars, 5) -#' +#' #' # K-means clustering of mtcars-dataset #' groups <- sjc.cluster(mtcars, 5, method="k") -#' +#' #' @import ggplot2 #' @importFrom stats dist na.omit hclust kmeans cutree #' @export @@ -365,7 +365,7 @@ sjc.cluster <- function(data, complete.groups <- rep(NA, times = nrow(data.origin)) # Prepare Data # listwise deletion of missing - data <- stats::na.omit(data) + data <- stats::na.omit(data) # remove missings data.origin <- stats::na.omit(data.origin) # --------------------------------------------- @@ -398,7 +398,7 @@ sjc.cluster <- function(data, # distance matrix d <- stats::dist(data, method = distance) # hierarchical clustering, using ward - hc <- stats::hclust(d, method = agglomeration) + hc <- stats::hclust(d, method = agglomeration) # cut tree into x clusters groups <- stats::cutree(hc, k = groupcount) } else { @@ -423,30 +423,30 @@ sjc.cluster <- function(data, #' dendrogram with highlighted rectangles around the classified groups. #' Can be used, for instance, as visual tool to verify the elbow-criterion #' (see \code{\link{sjc.elbow}}). -#' +#' #' @param groupcount The amount of groups (clusters) that should be used. #' \itemize{ #' \item Use \code{\link{sjc.elbow}}-function to determine the group-count depending on the elbow-criterion. #' \item Use \code{\link{sjc.grpdisc}}-function to inspect the goodness of grouping (accuracy of classification). #' } #' Solutions for multiple cluster groups can be plotted, for instance with \code{"groupcount = c(3:6)"}. -#' +#' #' @inheritParams sjc.qclus -#' -#' @note Since R version > 3.0.3, the \code{"ward"} option has +#' +#' @note Since R version > 3.0.3, the \code{"ward"} option has #' been replaced by either \code{"ward.D"} or \code{"ward.D2"}, -#' so you may use one of these values. When using \code{"ward"}, +#' so you may use one of these values. When using \code{"ward"}, #' it will be replaced by \code{"ward.D2"}. -#' +#' #' @examples #' # Plot dendrogram of hierarchical clustering of mtcars-dataset #' # and show group classification #' sjc.dend(mtcars, 5) -#' +#' #' # Plot dendrogram of hierarchical clustering of mtcars-dataset #' # and show group classification for 2 to 4 groups #' sjc.dend(mtcars, 2:4) -#' +#' #' @importFrom stats dist hclust cutree na.omit rect.hclust #' @importFrom scales brewer_pal #' @importFrom graphics plot rect par @@ -454,7 +454,7 @@ sjc.cluster <- function(data, sjc.dend <- function(data, groupcount, distance = "euclidean", agglomeration = "ward") { # Prepare Data # listwise deletion of missing - data <- stats::na.omit(data) + data <- stats::na.omit(data) # -------------------------------------------------- # Ward Hierarchical Clustering # -------------------------------------------------- @@ -463,11 +463,11 @@ sjc.dend <- function(data, groupcount, distance = "euclidean", agglomeration = " # check for argument and R version if (agglomeration == "ward") agglomeration <- "ward.D2" # hierarchical clustering, using ward - hc <- stats::hclust(d, method = agglomeration) + hc <- stats::hclust(d, method = agglomeration) # display simple dendrogram - graphics::plot(hc, - main = "Cluster Dendrogramm", - xlab = sprintf("Hierarchical Cluster Analysis, %s-Method", + graphics::plot(hc, + main = "Cluster Dendrogramm", + xlab = sprintf("Hierarchical Cluster Analysis, %s-Method", agglomeration)) # now plot overlaying rectangles, depending on the amount of groupcounts gl <- length(groupcount) @@ -483,19 +483,19 @@ sjc.dend <- function(data, groupcount, distance = "euclidean", agglomeration = " clustab <- table(cluster)[unique(cluster[hc$order])] m <- c(0, cumsum(clustab)) which <- 1L:k - # draw dendrogram with red borders around the clusters + # draw dendrogram with red borders around the clusters # source code taken from "rect.hclust" from base-package for (n in seq_along(which)) { - graphics::rect(m[which[n]] + 0.46 + (cnt * 0.2), - graphics::par("usr")[3L], - m[which[n] + 1] + 0.53 - (cnt * 0.2), - mean(rev(hc$height)[(k - 1):k]), + graphics::rect(m[which[n]] + 0.46 + (cnt * 0.2), + graphics::par("usr")[3L], + m[which[n] + 1] + 0.53 - (cnt * 0.2), + mean(rev(hc$height)[(k - 1):k]), border = color[cnt], lwd = 2) } } } else { - # draw dendrogram with red borders around the clusters + # draw dendrogram with red borders around the clusters stats::rect.hclust(hc, k = groupcount, border = "red") } } @@ -506,7 +506,7 @@ sjc.dend <- function(data, groupcount, distance = "euclidean", agglomeration = " #' @description Computes linear discriminant analysis on classified cluster groups. #' This function plots a bar graph indicating the goodness of classification #' for each group. -#' +#' #' @param groups group classification of the cluster analysis that was returned #' from the \code{\link{sjc.cluster}}-function #' @param groupcount amount of groups (clusters) that should be used. Use @@ -521,20 +521,20 @@ sjc.dend <- function(data, groupcount, distance = "euclidean", agglomeration = " #' #' @return (Invisibly) returns an object with #' \itemize{ -#' \item \code{data}: the used data frame for plotting, +#' \item \code{data}: the used data frame for plotting, #' \item \code{plot}: the ggplot object, #' \item \code{accuracy}: a vector with the accuracy of classification for each group, #' \item \code{total.accuracy}: the total accuracy of group classification. #' } -#' +#' #' @examples #' # retrieve group classification from hierarchical cluster analysis #' # on the mtcars data set (5 groups) #' groups <- sjc.cluster(mtcars, 5) -#' +#' #' # plot goodness of group classificatoin #' sjc.grpdisc(mtcars, groups, 5) -#' +#' #' @importFrom stats na.omit #' @importFrom graphics plot #' @importFrom MASS lda @@ -607,37 +607,37 @@ sjc.grpdisc <- function(data, groups, groupcount, clss.fit = TRUE, prnt.plot = T # fill bars scale_fill_manual(values = c("#235a80", "#80acc8")) + # give chart and X-axis a title - labs(title = "Accuracy of cluster group classification (in %)", - x = "cluster groups", + labs(title = "Accuracy of cluster group classification (in %)", + x = "cluster groups", y = NULL) + # print value labels into bar chart - geom_text(aes_string(label = "cprc", y = "cprc"), - vjust = 1.2, + geom_text(aes_string(label = "cprc", y = "cprc"), + vjust = 1.2, colour = "white") + # larger font size for axes - theme(axis.line = element_line(colour = "gray"), - axis.text = element_text(size = rel(1.2)), + theme(axis.line = element_line(colour = "gray"), + axis.text = element_text(size = rel(1.2)), axis.title = element_text(size = rel(1.2))) + # set ticks scale_y_continuous(breaks = seq(0, 100, 10)) + # change range on x-axis, so the text annotation is visible and # beside the bars and not printed into them - coord_cartesian(ylim = c(0, 100), + coord_cartesian(ylim = c(0, 100), xlim = c(-0.5, groupcount + 1)) if (clss.fit) { classplot <- classplot + # set line across all bars which indicates the total percentage of # correct assigned cases - geom_hline(yintercept = totalcorrect, - linetype = 2, + geom_hline(yintercept = totalcorrect, + linetype = 2, colour = "#333333") + # print text annotation - annotate("text", - x = 0, - y = totalcorrect, - vjust = 1.2, - label = paste("overall", c(totalcorrect), sep = "\n"), - size = 5, + annotate("text", + x = 0, + y = totalcorrect, + vjust = 1.2, + label = paste("overall", c(totalcorrect), sep = "\n"), + size = 5, colour = "#333333") } # -------------------------------------------------------- @@ -663,19 +663,19 @@ sjc.grpdisc <- function(data, groups, groupcount, clss.fit = TRUE, prnt.plot = T #' and a second plot that maps the differences between each #' "step" (i.e. between elbow values) on the y-axis. An #' increase in the second plot may indicate the elbow criterion. -#' -#' @param data data frame containing all variables that should be used for +#' +#' @param data data frame containing all variables that should be used for #' determining the elbow criteria #' @param steps maximum group-count for the k-means cluster analysis for #' which the elbow-criterion should be displayed. Default is \code{15}. -#' @param show.diff logical, if \code{TRUE}, an additional plot with the differences between +#' @param show.diff logical, if \code{TRUE}, an additional plot with the differences between #' each fusion step of the Elbow criterion calculation is shown. This plot #' may help identifying the "elbow". Default for this argument is \code{FALSE}. -#' +#' #' @examples #' # plot elbow values of mtcars dataset #' sjc.elbow(mtcars) -#' +#' #' @import ggplot2 #' @importFrom tidyr gather #' @importFrom grDevices rgb @@ -685,7 +685,7 @@ sjc.grpdisc <- function(data, groups, groupcount, clss.fit = TRUE, prnt.plot = T sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { # Prepare Data # listwise deletion of missing - data <- stats::na.omit(data) + data <- stats::na.omit(data) # define line linecolor lcol <- grDevices::rgb(128, 172, 200, maxColorValue = 255) # calculate elbow values (sum of squares) @@ -698,9 +698,9 @@ sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { # calculate differences between each step diff <- c() for (i in 2:steps) diff <- cbind(diff,wssround[i - 1] - wssround[i]) - dfElbowDiff <- tidyr::gather(as.data.frame(diff), - "Var2", - "value", + dfElbowDiff <- tidyr::gather(as.data.frame(diff), + "Var2", + "value", seq_len(ncol(diff)), factor_key = TRUE) # -------------------------------------------------- @@ -708,12 +708,12 @@ sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { # all pointes are connected with a line # a bend the in curve progression might indicate elbow # -------------------------------------------------- - graphics::plot(ggplot(dfElbowValues, aes_string(x = "xpos", y = "wssround", label = "wssround")) + - geom_line(colour = lcol) + + graphics::plot(ggplot(dfElbowValues, aes_string(x = "xpos", y = "wssround", label = "wssround")) + + geom_line(colour = lcol) + geom_point(colour = lcol, size = 3) + geom_text(hjust = -0.3) + - labs(title = "Elbow criterion (sum of squares)", - x = "Number of clusters", + labs(title = "Elbow criterion (sum of squares)", + x = "Number of clusters", y = "elbow value")) # -------------------------------------------------- # Plot diagram with differences between each step @@ -721,12 +721,12 @@ sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { # might indicate elbow # -------------------------------------------------- if (show.diff) { - graphics::plot(ggplot(dfElbowDiff, aes_string(x = "Var2", y = "value", label = "value")) + - geom_line(colour = lcol) + + graphics::plot(ggplot(dfElbowDiff, aes_string(x = "Var2", y = "value", label = "value")) + + geom_line(colour = lcol) + geom_point(colour = lcol, size = 3) + geom_text(hjust = -0.3) + - labs(title = "Elbow criterion (differences between sum of squares)", - x = "difference to previews cluster", + labs(title = "Elbow criterion (differences between sum of squares)", + x = "difference to previews cluster", y = "delta")) } } @@ -738,20 +738,20 @@ sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { #' "Estimating the number of clusters in a data set via the gap statistic". #' This function calls the \code{\link[cluster]{clusGap}}-function of the #' \pkg{cluster}-package to calculate the data for the plot. -#' +#' #' @seealso \code{\link{sjc.elbow}} -#' -#' @param x matrix, where rows are observations and columns are individual dimensions, +#' +#' @param x matrix, where rows are observations and columns are individual dimensions, #' to compute and plot the gap statistic (according to a uniform reference distribution). #' @param max maximum number of clusters to consider, must be at least two. Default #' is 10. #' @param B integer, number of Monte Carlo ("bootstrap") samples. Default is 100. -#' @param SE.factor [When \code{method} contains "SE"] Determining the optimal -#' number of clusters, Tibshirani et al. proposed the "1 S.E."-rule. +#' @param SE.factor [When \code{method} contains "SE"] Determining the optimal +#' number of clusters, Tibshirani et al. proposed the "1 S.E."-rule. #' Using an SE.factor f, the "f S.E."-rule is used, more generally. -#' @param method character string indicating how the "optimal" number of clusters, -#' k^, is computed from the gap statistics (and their standard deviations), -#' or more generally how the location k^ of the maximum of f[k] should be +#' @param method character string indicating how the "optimal" number of clusters, +#' k^, is computed from the gap statistics (and their standard deviations), +#' or more generally how the location k^ of the maximum of f[k] should be #' determined. Default is \code{"Tibs2001SEmax"}. Possible value are: #' \describe{ #' \item{\code{"globalmax"}}{simply corresponds to the global maximum, i.e., is which.max(f).} @@ -762,33 +762,33 @@ sjc.elbow <- function(data, steps = 15, show.diff = FALSE) { #' } #' @param plotResults logical, if \code{TRUE} (default), a graph visualiting the gap statistic will #' be plotted. Use \code{FALSE} to omit the plot. -#' +#' #' @return An object containing the used data frame for plotting, the ggplot object #' and the number of found cluster. -#' +#' #' @references \itemize{ #' \item Tibshirani R, Walther G, Hastie T (2001) Estimating the number of clusters in a data set via gap statistic. J. R. Statist. Soc. B, 63, Part 2, pp. 411-423 #' \item Maechler, M., Rousseeuw, P., Struyf, A., Hubert, M., Hornik, K.(2013). cluster: Cluster Analysis Basics and Extensions. R package version 1.14.4. (\href{https://cran.r-project.org/package=cluster}{web}) #' } -#' +#' #' @examples #' \dontrun{ #' # plot gap statistic and determine best number of clusters #' # in mtcars dataset #' sjc.kgap(mtcars) -#' +#' #' # and in iris dataset #' sjc.kgap(iris[,1:4])} -#' +#' #' @import ggplot2 #' @importFrom stats na.omit #' @importFrom graphics plot #' @export -sjc.kgap <- function(x, - max = 10, - B = 100, - SE.factor = 1, - method = "Tibs2001SEmax", +sjc.kgap <- function(x, + max = 10, + B = 100, + SE.factor = 1, + method = "Tibs2001SEmax", plotResults = TRUE) { # ------------------------ # check if suggested package is available @@ -798,22 +798,22 @@ sjc.kgap <- function(x, } # Prepare Data # listwise deletion of missing - x <- stats::na.omit(x) + x <- stats::na.omit(x) # Gap Statistic for Estimating the Number of Clusters gap <- cluster::clusGap(x, kmeans, max, B) stopifnot((K <- nrow(T <- gap$Tab)) >= 1, SE.factor >= 0) - message("Clustering Gap statistic [\"clusGap\"].\n", - sprintf("B=%d simulated reference sets, k = 1..%d\n", gap$B, K), + message("Clustering Gap statistic [\"clusGap\"].\n", + sprintf("B=%d simulated reference sets, k = 1..%d\n", gap$B, K), sep = "") # Gap Statistic for Estimating the Number of Clusters - nc <- cluster::maxSE(f = T[, "gap"], - SE.f = T[, "SE.sim"], - method = method, + nc <- cluster::maxSE(f = T[, "gap"], + SE.f = T[, "SE.sim"], + method = method, SE.factor = SE.factor) message(sprintf(" --> Number of clusters (method '%s'%s): %d\n", method, - if (grepl("SE", method, fixed = T)) sprintf(", SE.factor=%g", SE.factor) else "", + if (grepl("SE", method, fixed = T)) sprintf(", SE.factor=%g", SE.factor) else "", nc)) # point size for cluster solution nclus <- rep(2, max) @@ -822,22 +822,22 @@ sjc.kgap <- function(x, cclus <- rep("black", max) cclus[nc] <- "#cc3366" # create data frame - df <- data.frame(x = seq_len(max), - y = gap$Tab[, 'gap'], - se = gap$Tab[, 'SE.sim'], - psize = nclus, + df <- data.frame(x = seq_len(max), + y = gap$Tab[, 'gap'], + se = gap$Tab[, 'SE.sim'], + psize = nclus, pcol = cclus) # plot cluster solution - gp <- ggplot(df, aes_string(x = "x", y = "y")) + - geom_errorbar(aes(ymin = y - se, ymax = y + se), - width = 0, - size = 0.5, + gp <- ggplot(df, aes_string(x = "x", y = "y")) + + geom_errorbar(aes(ymin = y - se, ymax = y + se), + width = 0, + size = 0.5, colour = "#3366cc") + geom_line(colour = "gray50") + geom_point(colour = df$pcol, size = df$psize) + scale_x_discrete(breaks = seq_len(nrow(df))) + - labs(x = "Number of clusters", - y = "Gap", + labs(x = "Number of clusters", + y = "Gap", title = sprintf("Estimation of clusters (gap statistics)\n%i-cluster solution found", nc)) + theme_classic() if (plotResults) graphics::plot(gp) diff --git a/R/sjPlotCorr.R b/R/sjPlotCorr.R index ebf247e6..cc0b10ea 100755 --- a/R/sjPlotCorr.R +++ b/R/sjPlotCorr.R @@ -8,23 +8,23 @@ utils::globalVariables(c("ordx", "ordy")) #' #' @seealso \code{\link{sjt.corr}} #' -#' @param data matrix with correlation coefficients as returned by the +#' @param data Matrix with correlation coefficients as returned by the #' \code{\link{cor}}-function, or a \code{data.frame} of variables where #' correlations between columns should be computed. -#' @param sort.corr logical, if \code{TRUE} (default), the axis labels are sorted +#' @param sort.corr Logical, if \code{TRUE} (default), the axis labels are sorted #' according to the correlation strength. If \code{FALSE}, axis labels #' appear in order of how variables were included in the cor-computation or #' data frame. -#' @param decimals indicates how many decimal values after comma are printed when +#' @param decimals Indicates how many decimal values after comma are printed when #' the values labels are shown. Default is 3. Only applies when #' \code{show.values = TRUE}. -#' @param na.deletion indicates how missing values are treated. May be either +#' @param na.deletion Indicates how missing values are treated. May be either #' \code{"listwise"} (default) or \code{"pairwise"}. May be #' abbreviated. -#' @param corr.method indicates the correlation computation method. May be one of +#' @param corr.method Indicates the correlation computation method. May be one of #' \code{"spearman"} (default), \code{"pearson"} or \code{"kendall"}. #' May be abbreviated. -#' @param p.numeric logical, if \code{TRUE}, the p-values are printed +#' @param p.numeric Logical, if \code{TRUE}, the p-values are printed #' as numbers. If \code{FALSE} (default), asterisks are used. #' #' @inheritParams sjp.grpfrq diff --git a/R/sjPlotDist.R b/R/sjPlotDist.R index 8ea4e314..e17d0c6e 100755 --- a/R/sjPlotDist.R +++ b/R/sjPlotDist.R @@ -1,46 +1,42 @@ -# bind global variables -utils::globalVariables(c("p.level")) - - #' @title Plot normal distributions #' @name dist_norm -#' +#' #' @description This function plots a simple normal distribution or a normal distribution -#' with shaded areas that indicate at which value a significant p-level +#' with shaded areas that indicate at which value a significant p-level #' is reached. -#' -#' @param norm numeric, optional. If specified, a normal distribution with \code{mean} and \code{sd} +#' +#' @param norm Numeric, optional. If specified, a normal distribution with \code{mean} and \code{sd} #' is plotted and a shaded area at \code{norm} value position is plotted that #' indicates whether or not the specified value is significant or not. #' If both \code{norm} and \code{p} are not specified, a distribution without shaded #' area is plotted. -#' @param mean numeric. Mean value for normal distribution. By default 0. -#' @param sd numeric. Standard deviation for normal distribution. By default 1. -#' @param p numeric, optional. If specified, a normal distribution with \code{mean} and \code{sd} +#' @param mean Numeric. Mean value for normal distribution. By default 0. +#' @param sd Numeric. Standard deviation for normal distribution. By default 1. +#' @param p Numeric, optional. If specified, a normal distribution with \code{mean} and \code{sd} #' is plotted and a shaded area at the position where the specified p-level -#' starts is plotted. If both \code{norm} and \code{p} are not specified, a distribution +#' starts is plotted. If both \code{norm} and \code{p} are not specified, a distribution #' without shaded area is plotted. -#' @param xmax numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis +#' @param xmax Numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis #' ranges to a value where a p-level of 0.00001 is reached. -#' @param geom.alpha specified the alpha-level of the shaded area. Default is 0.7, range between 0 to 1. -#' +#' @param geom.alpha Specifies the alpha-level of the shaded area. Default is 0.7, range between 0 to 1. +#' #' @inheritParams sjp.grpfrq -#' +#' #' @examples #' # a simple normal distribution #' dist_norm() -#' -#' # a simple normal distribution with different mean and sd. +#' +#' # a simple normal distribution with different mean and sd. #' # note that curve looks similar to above plot, but axis range #' # has changed. #' dist_norm(mean = 2, sd = 4) -#' +#' #' # a simple normal distribution #' dist_norm(norm = 1) -#' +#' #' # a simple normal distribution #' dist_norm(p = 0.2) -#' +#' #' @import ggplot2 #' @importFrom stats qchisq pchisq dchisq qf pf df qnorm pnorm dnorm qt pt dt #' @export @@ -80,7 +76,7 @@ dist_norm <- function(norm = NULL, # density normal distribution mydat$y <- stats::dnorm(mydat$x, mean, sd) # base plot with normal-distribution - gp <- ggplot(mydat, aes(x = x, y = y)) + geom_line() + gp <- ggplot(mydat, aes_string(x = "x", y = "y")) + geom_line() sub.df <- NULL if (!is.null(p)) { # plot area for indicated x-value... @@ -95,12 +91,12 @@ dist_norm <- function(norm = NULL, cs <- stats::qnorm(0.05, mean, sd, lower.tail = F) gp <- gp + geom_ribbon(data = sub.df, - aes(ymax = y, fill = p.level), + aes_string(ymax = "y", fill = "p.level"), ymin = 0, alpha = geom.alpha) + - annotate("text", - label = sprintf("x = %.2f", cs), - x = cs, + annotate("text", + label = sprintf("x = %.2f", cs), + x = cs, y = 0, vjust = 1.3) # add limit of p-value @@ -108,9 +104,9 @@ dist_norm <- function(norm = NULL, pv <- stats::pnorm(norm, mean, sd, lower.tail = F) if (pv >= 0.05) { gp <- gp + - annotate("text", - label = sprintf("p = %.2f", pv), - x = norm, + annotate("text", + label = sprintf("p = %.2f", pv), + x = norm, y = 0, hjust = -0.1, vjust = -0.5, @@ -126,33 +122,33 @@ dist_norm <- function(norm = NULL, #' @title Plot chi-squared distributions #' @name dist_chisq -#' +#' #' @description This function plots a simple chi-squared distribution or a chi-squared distribution -#' with shaded areas that indicate at which chi-squared value a significant p-level +#' with shaded areas that indicate at which chi-squared value a significant p-level #' is reached. -#' -#' @param chi2 numeric, optional. If specified, a chi-squared distribution with \code{deg.f} degrees +#' +#' @param chi2 Numeric, optional. If specified, a chi-squared distribution with \code{deg.f} degrees #' of freedom is plotted and a shaded area at \code{chi2} value position is plotted that #' indicates whether or not the specified value is significant or not. #' If both \code{chi2} and \code{p} are not specified, a distribution without shaded #' area is plotted. -#' @param deg.f numeric. The degrees of freedom for the chi-squared distribution. Needs to +#' @param deg.f Numeric. The degrees of freedom for the chi-squared distribution. Needs to #' be specified. -#' @param p numeric, optional. If specified, a chi-squared distribution with \code{deg.f} degrees +#' @param p Numeric, optional. If specified, a chi-squared distribution with \code{deg.f} degrees #' of freedom is plotted and a shaded area at the position where the specified p-level -#' starts is plotted. If both \code{chi2} and \code{p} are not specified, a distribution +#' starts is plotted. If both \code{chi2} and \code{p} are not specified, a distribution #' without shaded area is plotted. -#' @param xmax numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis +#' @param xmax Numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis #' ranges to a value where a p-level of 0.00001 is reached. -#' +#' #' @inheritParams dist_norm #' @inheritParams sjp.grpfrq -#' +#' #' @examples #' # a simple chi-squared distribution #' # for 6 degrees of freedom #' dist_chisq(deg.f = 6) -#' +#' #' # a chi-squared distribution for 6 degrees of freedom, #' # and a shaded area starting at chi-squared value of ten. #' # With a df of 6, a chi-squared value of 12.59 would be "significant", @@ -160,16 +156,16 @@ dist_norm <- function(norm = NULL, #' # while the area starting from chi-squared value 12.59 is filled as #' # "significant" #' dist_chisq(chi2 = 10, deg.f = 6) -#' +#' #' # a chi-squared distribution for 6 degrees of freedom, #' # and a shaded area starting at that chi-squared value, which has #' # a p-level of about 0.125 (which equals a chi-squared value of about 10). #' # With a df of 6, a chi-squared value of 12.59 would be "significant", -#' # thus the shaded area from 10 to 12.58 (p-level 0.125 to p-level 0.05) -#' # is filled as "non-significant", while the area starting from chi-squared +#' # thus the shaded area from 10 to 12.58 (p-level 0.125 to p-level 0.05) +#' # is filled as "non-significant", while the area starting from chi-squared #' # value 12.59 (p-level < 0.05) is filled as "significant". #' dist_chisq(p = 0.125, deg.f = 6) -#' +#' #' @import ggplot2 #' @export dist_chisq <- function(chi2 = NULL, @@ -217,7 +213,7 @@ dist_chisq <- function(chi2 = NULL, # density distribution of chi2 mydat$y <- stats::dchisq(mydat$x, deg.f) # base plot with chi2-distribution - gp <- ggplot(mydat, aes(x = x, y = y)) + geom_line() + gp <- ggplot(mydat, aes_string(x = "x", y = "y")) + geom_line() sub.df <- NULL if (!is.null(p)) { # plot area for indicated chi2-value... @@ -232,13 +228,13 @@ dist_chisq <- function(chi2 = NULL, cs <- stats::qchisq(0.05, deg.f, lower.tail = F) gp <- gp + geom_ribbon(data = sub.df, - aes(ymax = y, fill = p.level), + aes_string(ymax = "y", fill = "p.level"), ymin = 0, alpha = geom.alpha) + - annotate("text", - label = as.character(as.expression(substitute(chi^2 == c2, list(c2 = sprintf("%.2f", cs))))), - parse = TRUE, - x = cs, + annotate("text", + label = as.character(as.expression(substitute(chi^2 == c2, list(c2 = sprintf("%.2f", cs))))), + parse = TRUE, + x = cs, y = 0, vjust = 1.2) # add limit of p-value @@ -246,9 +242,9 @@ dist_chisq <- function(chi2 = NULL, pv <- stats::pchisq(chi2, deg.f, lower.tail = F) if (pv >= 0.05) { gp <- gp + - annotate("text", - label = sprintf("p = %.2f", pv), - x = chi2, + annotate("text", + label = sprintf("p = %.2f", pv), + x = chi2, y = 0, hjust = -0.1, vjust = -0.5, @@ -264,44 +260,44 @@ dist_chisq <- function(chi2 = NULL, #' @title Plot F distributions #' @name dist_f -#' +#' #' @description This function plots a simple F distribution or an F distribution -#' with shaded areas that indicate at which F value a significant p-level +#' with shaded areas that indicate at which F value a significant p-level #' is reached. -#' -#' @param f numeric, optional. If specified, an F distribution with \code{deg.f1} and \code{deg.f2} degrees +#' +#' @param f Numeric, optional. If specified, an F distribution with \code{deg.f1} and \code{deg.f2} degrees #' of freedom is plotted and a shaded area at \code{f} value position is plotted that #' indicates whether or not the specified value is significant or not. #' If both \code{f} and \code{p} are not specified, a distribution without shaded #' area is plotted. -#' @param deg.f1 numeric. The first degrees of freedom for the F distribution. Needs to +#' @param deg.f1 Numeric. The first degrees of freedom for the F distribution. Needs to #' be specified. -#' @param deg.f2 numeric. The second degrees of freedom for the F distribution. Needs to +#' @param deg.f2 Numeric. The second degrees of freedom for the F distribution. Needs to #' be specified. -#' @param p numeric, optional. If specified, a F distribution with \code{deg.f1} and \code{deg.f2} degrees +#' @param p Numeric, optional. If specified, a F distribution with \code{deg.f1} and \code{deg.f2} degrees #' of freedom is plotted and a shaded area at the position where the specified p-level -#' starts is plotted. If both \code{f} and \code{p} are not specified, a distribution +#' starts is plotted. If both \code{f} and \code{p} are not specified, a distribution #' without shaded area is plotted. -#' @param xmax numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis +#' @param xmax Numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis #' ranges to a value where a p-level of 0.00001 is reached. -#' +#' #' @inheritParams dist_norm #' @inheritParams sjp.grpfrq -#' +#' #' @examples #' # a simple F distribution for 6 and 45 degrees of freedom #' dist_f(deg.f1 = 6, deg.f2 = 45) -#' +#' #' # F distribution for 6 and 45 degrees of freedom, #' # and a shaded area starting at F value of two. #' # F-values equal or greater than 2.31 are "significant" #' dist_f(f = 2, deg.f1 = 6, deg.f2 = 45) -#' +#' #' # F distribution for 6 and 45 degrees of freedom, #' # and a shaded area starting at a p-level of 0.2 #' # (F-Value about 1.5). #' dist_f(p = 0.2, deg.f1 = 6, deg.f2 = 45) -#' +#' #' @import ggplot2 #' @export dist_f <- function(f = NULL, @@ -346,7 +342,7 @@ dist_f <- function(f = NULL, # density distribution of f mydat$y <- stats::df(mydat$x, deg.f1, deg.f2) # base plot with f-distribution - gp <- ggplot(mydat, aes(x = x, y = y)) + geom_line() + gp <- ggplot(mydat, aes_string(x = "x", y = "y")) + geom_line() sub.df <- NULL if (!is.null(p)) { # plot area for indicated f-value... @@ -360,12 +356,12 @@ dist_f <- function(f = NULL, fv <- stats::qf(0.05, deg.f1, deg.f2, lower.tail = F) gp <- gp + geom_ribbon(data = sub.df, - aes(ymax = y, fill = p.level), + aes_string(ymax = "y", fill = "p.level"), ymin = 0, alpha = geom.alpha) + - annotate("text", - label = sprintf("F = %.2f", fv), - x = fv, + annotate("text", + label = sprintf("F = %.2f", fv), + x = fv, y = 0, vjust = 1.3) # add limit of p-value @@ -373,9 +369,9 @@ dist_f <- function(f = NULL, pv <- stats::pf(f, deg.f1, deg.f2, lower.tail = F) if (pv >= 0.05) { gp <- gp + - annotate("text", - label = sprintf("p = %.2f", pv), - x = f, + annotate("text", + label = sprintf("p = %.2f", pv), + x = f, y = 0, hjust = -0.1, vjust = -0.5, @@ -392,43 +388,43 @@ dist_f <- function(f = NULL, #' @title Plot t-distributions #' @name dist_t -#' +#' #' @description This function plots a simple t-distribution or a t-distribution -#' with shaded areas that indicate at which t-value a significant p-level +#' with shaded areas that indicate at which t-value a significant p-level #' is reached. -#' -#' @param t numeric, optional. If specified, a t-distribution with \code{deg.f} degrees +#' +#' @param t Numeric, optional. If specified, a t-distribution with \code{deg.f} degrees #' of freedom is plotted and a shaded area at \code{t} value position is plotted that #' indicates whether or not the specified value is significant or not. #' If both \code{t} and \code{p} are not specified, a distribution without shaded #' area is plotted. -#' @param deg.f numeric. The degrees of freedom for the t-distribution. Needs to +#' @param deg.f Numeric. The degrees of freedom for the t-distribution. Needs to #' be specified. -#' @param p numeric, optional. If specified, a t-distribution with \code{deg.f} degrees +#' @param p Numeric, optional. If specified, a t-distribution with \code{deg.f} degrees #' of freedom is plotted and a shaded area at the position where the specified p-level -#' starts is plotted. If both \code{t} and \code{p} are not specified, a distribution +#' starts is plotted. If both \code{t} and \code{p} are not specified, a distribution #' without shaded area is plotted. -#' @param xmax numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis +#' @param xmax Numeric, optional. Specifies the maximum x-axis-value. If not specified, the x-axis #' ranges to a value where a p-level of 0.00001 is reached. -#' +#' #' @inheritParams dist_norm #' @inheritParams sjp.grpfrq -#' +#' #' @examples #' # a simple t-distribution #' # for 6 degrees of freedom #' dist_t(deg.f = 6) -#' +#' #' # a t-distribution for 6 degrees of freedom, #' # and a shaded area starting at t-value of one. #' # With a df of 6, a t-value of 1.94 would be "significant". #' dist_t(t = 1, deg.f = 6) -#' +#' #' # a t-distribution for 6 degrees of freedom, #' # and a shaded area starting at p-level of 0.4 #' # (t-value of about 0.26). #' dist_t(p = 0.4, deg.f = 6) -#' +#' #' @import ggplot2 #' @export dist_t <- function(t = NULL, @@ -476,7 +472,7 @@ dist_t <- function(t = NULL, # density distribution of t mydat$y <- stats::dt(mydat$x, deg.f) # base plot with t-distribution - gp <- ggplot(mydat, aes(x = x, y = y)) + geom_line() + gp <- ggplot(mydat, aes_string(x = "x", y = "y")) + geom_line() sub.df <- NULL if (!is.null(p)) { # plot area for indicated t-value... @@ -491,12 +487,12 @@ dist_t <- function(t = NULL, tv <- stats::qt(0.05, deg.f, lower.tail = F) gp <- gp + geom_ribbon(data = sub.df, - aes(ymax = y, fill = p.level), + aes_string(ymax = "y", fill = "p.level"), ymin = 0, alpha = geom.alpha) + - annotate("text", - label = sprintf("t = %.2f", tv), - x = tv, + annotate("text", + label = sprintf("t = %.2f", tv), + x = tv, y = 0, vjust = 1.3) # add limit of p-value @@ -504,9 +500,9 @@ dist_t <- function(t = NULL, pv <- stats::pt(t, deg.f, lower.tail = F) if (pv >= 0.05) { gp <- gp + - annotate("text", - label = sprintf("p = %.2f", pv), - x = t, + annotate("text", + label = sprintf("p = %.2f", pv), + x = t, y = 0, hjust = -0.1, vjust = -0.5, diff --git a/R/sjPlotFrequencies.R b/R/sjPlotFrequencies.R index de0e4a22..58e59e0e 100755 --- a/R/sjPlotFrequencies.R +++ b/R/sjPlotFrequencies.R @@ -4,75 +4,75 @@ utils::globalVariables(c("val", "frq", "grp", "label.pos", "upper.ci", "lower.ci #' @title Plot frequencies of variables #' @name sjp.frq -#' +#' #' @seealso \itemize{ #' \item \href{http://www.strengejacke.de/sjPlot/sjp.frq/}{sjPlot manual: sjp.frq} #' \item \code{\link{sjt.frq}} #' } -#' +#' #' @description Plot frequencies of a variable as bar graph, histogram, #' box plot etc. -#' +#' #' @note This function only works with variables with integer values (or numeric #' factor levels), i.e. scales / centred variables #' with decimals may result in unexpected behaviour. -#' -#' @param sort.frq Determines whether categories should be sorted -#' according to their frequencies or not. Default is \code{"none"}, so +#' +#' @param sort.frq Determines whether categories should be sorted +#' according to their frequencies or not. Default is \code{"none"}, so #' categories are not sorted by frequency. Use \code{"asc"} or #' \code{"desc"} for sorting categories ascending or descending order. -#' @param geom.colors user defined color for geoms, e.g. \code{geom.colors = "#0080ff"}. -#' @param errorbar.color color of confidence interval bars (error bars). -#' Only applies to \code{type = "bar"}. In case of dot plots, error bars +#' @param geom.colors User defined color for geoms, e.g. \code{geom.colors = "#0080ff"}. +#' @param errorbar.color Color of confidence interval bars (error bars). +#' Only applies to \code{type = "bar"}. In case of dot plots, error bars #' will have same colors as dots (see \code{geom.colors}). -#' @param show.mean logical, if \code{TRUE}, a vertical line in histograms -#' is drawn to indicate the mean value of the variables. Only +#' @param show.mean Logical, if \code{TRUE}, a vertical line in histograms +#' is drawn to indicate the mean value of the variables. Only #' applies to histogram-charts. -#' @param show.mean.val logical, if \code{TRUE} (default), the mean value +#' @param show.mean.val Logical, if \code{TRUE} (default), the mean value #' is printed to the vertical line that indicates the variable's #' mean. Only applies to histogram-charts. -#' @param show.sd logical, if \code{TRUE}, the standard deviation +#' @param show.sd Logical, if \code{TRUE}, the standard deviation #' is annotated as shaded rectangle around the mean intercept #' line. Only applies to histogram-charts. -#' @param mean.line.type numeric value, indicating the linetype of the mean -#' intercept line. Only applies to histogram-charts and +#' @param mean.line.type Numeric value, indicating the linetype of the mean +#' intercept line. Only applies to histogram-charts and #' when \code{show.mean = TRUE}. -#' @param mean.line.size numeric, size of the mean intercept line. Only +#' @param mean.line.size Numeric, size of the mean intercept line. Only #' applies to histogram-charts and when \code{show.mean = TRUE}. -#' @param normal.curve logical, if \code{TRUE}, a normal curve, which is adjusted to the data, +#' @param normal.curve Logical, if \code{TRUE}, a normal curve, which is adjusted to the data, #' is plotted over the histogram or density plot. Default is #' \code{FALSE}. Only applies when histograms or density plots are plotted (see \code{type}). -#' @param normal.curve.color color of the normal curve line. Only +#' @param normal.curve.color Color of the normal curve line. Only #' applies if \code{normal.curve = TRUE}. -#' @param normal.curve.size numeric, size of the normal curve line. Only +#' @param normal.curve.size Numeric, size of the normal curve line. Only #' applies if \code{normal.curve = TRUE}. -#' @param normal.curve.alpha transparancy level (alpha value) of the normal curve. Only +#' @param normal.curve.alpha Transparancy level (alpha value) of the normal curve. Only #' applies if \code{normal.curve = TRUE}. -#' @param xlim numeric vector of length two, defining lower and upper axis limits -#' of the x scale. By default, this argument is set to \code{NULL}, i.e. the +#' @param xlim Numeric vector of length two, defining lower and upper axis limits +#' of the x scale. By default, this argument is set to \code{NULL}, i.e. the #' x-axis fits to the required range of the data. -#' +#' #' @inheritParams sjp.grpfrq #' @inheritParams sjp.lm #' @inheritParams sjp.glmer -#' +#' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{data}). -#' +#' #' @examples #' # boxplot #' sjp.frq(ChickWeight$weight, type = "box") -#' +#' #' # histogram #' sjp.frq(discoveries, type = "hist", show.mean = TRUE) -#' +#' #' # violin plot #' sjp.frq(ChickWeight$weight, type = "v") -#' +#' #' # bar plot #' sjp.frq(ChickWeight$Diet) -#' -#' +#' +#' #' # bar plot with EUROFAMCARE sample dataset #' # dataset was importet from an SPSS-file, using: #' # efc <- sjmisc::read_spss("efc.sav", enc = "UTF-8") @@ -80,29 +80,29 @@ utils::globalVariables(c("val", "frq", "grp", "label.pos", "upper.ci", "lower.ci #' data(efc) #' # you may use sjp.setTheme here to change axis textangle #' sjp.frq(efc$e15relat) -#' +#' #' # bar plot with EUROFAMCARE sample dataset #' # grouped variable #' ageGrp <- group_var(efc$e17age) #' ageGrpLab <- group_labels(efc$e17age) #' sjp.frq(ageGrp, title = get_label(efc$e17age), axis.labels = ageGrpLab) -#' +#' #' # negative impact scale, ranging from 7-28 #' sjp.frq(efc$neg_c_7) -#' +#' #' # plotting confidence intervals. expand grid and v/hjust for text labels #' sjp.frq(efc$e15relat, type = "dot", show.ci = TRUE, sort.frq = "desc", -#' coord.flip = TRUE, expand.grid = TRUE, vjust = "bottom", +#' coord.flip = TRUE, expand.grid = TRUE, vjust = "bottom", #' hjust = "left") -#' +#' #' # Simulate ggplot-default histogram #' sjp.frq(efc$c160age, type = "h", geom.size = 3) -#' +#' #' # histogram with overlayed normal curve #' sjp.frq(efc$c160age, type = "h", show.mean = TRUE, show.mean.val = TRUE, #' normal.curve = TRUE, show.sd = TRUE, normal.curve.color = "blue", #' normal.curve.size = 3, ylim = c(0,50)) -#' +#' #' @import ggplot2 #' @importFrom sjstats wtd_sd #' @importFrom sjmisc set_labels group_labels group_var to_value @@ -148,11 +148,11 @@ sjp.frq <- function(var.cnt, hjust = "center", y.offset = NULL, prnt.plot = TRUE) { - + # get variable name, used as default label if variable # has no label attributes var.name <- get_var_name(deparse(substitute(var.cnt))) - + # try to find some useful default offsets for textlabels, # depending on plot range and flipped coordinates if (is.null(y.offset)) { @@ -178,7 +178,7 @@ sjp.frq <- function(var.cnt, } else { y_offset <- y.offset } - + # try to automatically set labels, if not passed as argument ----- # to make plot annotations more beautiful, supporting labelled data if (is.null(axis.labels)) { @@ -189,21 +189,21 @@ sjp.frq <- function(var.cnt, include.non.labelled = T ) } - + if (is.null(axis.title)) axis.title <- sjmisc::get_label(var.cnt, def.value = var.name) if (is.null(title)) title <- sjmisc::get_label(var.cnt, def.value = var.name) - + # remove titles if empty if (!is.null(axis.title) && axis.title == "") axis.title <- NULL - if (!is.null(title) && title == "") title <- NULL - + if (!is.null(title) && title == "") title <- NULL + # check color argument if (length(geom.colors) > 1) geom.colors <- geom.colors[1] # Match arguments ----- type <- match.arg(type) sort.frq <- match.arg(sort.frq) - + # default grid-expansion if (isTRUE(expand.grid) || (missing(expand.grid) && type == "histogram")) { expand.grid <- ggplot2::waiver() @@ -213,16 +213,16 @@ sjp.frq <- function(var.cnt, # for histograms or density plots... xv <- sjmisc::to_value(stats::na.omit(var.cnt)) - + # check for nice bin-width defaults if (type %in% c("histogram", "density") && !is.null(geom.size) && geom.size < round(diff(range(xv)) / 40)) message("Using very small binwidth. Consider adjusting `geom.size` argument.") - + # create second data frame hist.dat <- data.frame(xv) - + # check default geom.size ----- if (is.null(geom.size)) { geom.size <- dplyr::case_when( @@ -236,7 +236,7 @@ sjp.frq <- function(var.cnt, TRUE ~ .7 ) } - + # check whether variable should be auto-grouped ----- if (!is.null(auto.group) && length(unique(var.cnt)) >= auto.group) { message(sprintf( @@ -244,68 +244,68 @@ sjp.frq <- function(var.cnt, var.name, length(unique(var.cnt)) )) - + # group axis labels axis.labels <- sjmisc::group_labels( sjmisc::to_value(var.cnt, keep.labels = F), groupsize = "auto", groupcount = auto.group ) - + # group variable var.cnt <- sjmisc::group_var( - sjmisc::to_value(var.cnt, keep.labels = F), - groupsize = "auto", - as.num = TRUE, + sjmisc::to_value(var.cnt, keep.labels = F), + groupsize = "auto", + as.num = TRUE, groupcount = auto.group ) - + # set label attributes var.cnt <- sjmisc::set_labels(var.cnt, labels = axis.labels) } - + # create frequency data frame ----- df.frq <- create.frq.df( - var.cnt, - wrap.labels = wrap.labels, - order.frq = sort.frq, + var.cnt, + wrap.labels = wrap.labels, + order.frq = sort.frq, round.prz = 2, - na.rm = !show.na, + na.rm = !show.na, weight.by = weight.by ) - + mydat <- df.frq$mydat - + # any labels detected? - if (!is.null(df.frq$labels) && is.null(axis.labels)) + if (!is.null(df.frq$labels) && is.null(axis.labels)) axis.labels <- df.frq$labels else if (!is.null(axis.labels) && sort.frq != "none") # sort labels in required order axis.labels <- axis.labels[mydat$order] - + # define text label position if (show.ci) mydat$label.pos <- mydat$upper.ci else mydat$label.pos <- mydat$frq - + # Trim labels and title to appropriate size ----- # check length of diagram title and split longer string into new lines # every 50 chars if (!is.null(title)) { # if we have weighted values, say that in diagram's title if (!is.null(title.wtd.suffix)) title <- paste(title, title.wtd.suffix, sep = "") - title <- sjmisc::word_wrap(title, wrap.title) + title <- sjmisc::word_wrap(title, wrap.title) } # check length of x-axis title and split longer string into new lines # every 50 chars - if (!is.null(axis.title)) axis.title <- sjmisc::word_wrap(axis.title, wrap.title) - + if (!is.null(axis.title)) axis.title <- sjmisc::word_wrap(axis.title, wrap.title) + # count variable may not be a factor! if (is.factor(var.cnt) || is.character(var.cnt)) { var.cnt <- sjmisc::to_value(var.cnt, keep.labels = F) } - + # If we have a histogram, caluclate means of groups if (is.null(weight.by)) { mittelwert <- mean(var.cnt, na.rm = TRUE) @@ -314,7 +314,7 @@ sjp.frq <- function(var.cnt, mittelwert <- stats::weighted.mean(var.cnt, weight.by, na.rm = TRUE) stddev <- sjstats::wtd_sd(var.cnt, weights = weight.by) } - + # If we have boxplots, use different data frame structure if (type == "boxplot" || type == "violin") { mydat <- stats::na.omit(data.frame(cbind( @@ -323,12 +323,12 @@ sjp.frq <- function(var.cnt, val = var.cnt ))) mydat$grp <- as.factor(mydat$grp) - } - + } + # Prepare bar charts trimViolin <- FALSE lower_lim <- 0 - + # calculate upper y-axis-range # if we have a fixed value, use this one here if (!is.null(ylim) && length(ylim) == 2) { @@ -363,10 +363,10 @@ sjp.frq <- function(var.cnt, upper_lim <- max(pretty(table(var.cnt) * 1.1)) } } - + # If we want to include NA, use raw percentages as valid percentages if (show.na) mydat$valid.prc <- mydat$raw.prc - + # don't display value labels when we have boxplots or violin plots if (type == "boxplot" || type == "violin") show.values <- FALSE if (show.values) { @@ -414,7 +414,7 @@ sjp.frq <- function(var.cnt, # no labels ggvaluelabels <- geom_text(aes(y = frq), label = "") } - + # Set up grid breaks maxx <- max(mydat$val) + 1 if (is.null(grid.breaks)) { @@ -424,7 +424,7 @@ sjp.frq <- function(var.cnt, gridbreaks <- c(seq(lower_lim, upper_lim, by = grid.breaks)) histgridbreaks <- c(seq(lower_lim, maxx, by = grid.breaks)) } - + # set Y-axis, depending on the calculated upper y-range. # It either corresponds to the maximum amount of cases in the data set # (length of var) or to the highest count of var's categories. @@ -442,7 +442,7 @@ sjp.frq <- function(var.cnt, labels = NULL ) } - + # bar and dot plot start here! ----- if (type == "bar" || type == "dot") { # define geom @@ -451,34 +451,34 @@ sjp.frq <- function(var.cnt, } else if (type == "dot") { geob <- geom_point(size = geom.size, colour = geom.colors) } - + # mydat is a data frame that only contains one variable (var). # Must be declared as factor, so the bars are central aligned to - # each x-axis-break. - baseplot <- ggplot(mydat, aes(x = factor(val), y = frq)) + + # each x-axis-break. + baseplot <- ggplot(mydat, aes(x = factor(val), y = frq)) + geob + - yscale + + yscale + # remove guide / legend guides(fill = FALSE) + # show absolute and percentage value of each bar. ggvaluelabels + # print value labels to the x-axis. - # If argument "axis.labels" is NULL, the category numbers (1 to ...) + # If argument "axis.labels" is NULL, the category numbers (1 to ...) # appear on the x-axis scale_x_discrete(labels = axis.labels) - + # add error bars if (show.ci) { ebcol <- ifelse(type == "dot", geom.colors, errorbar.color) # print confidence intervalls (error bars) - baseplot <- baseplot + + baseplot <- baseplot + geom_errorbar(aes_string(ymin = "lower.ci", ymax = "upper.ci"), colour = ebcol, width = 0) } - + # check whether coordinates should be flipped, i.e. # swap x and y axis if (coord.flip) baseplot <- baseplot + coord_flip() - + # Start box plot here ----- } else if (type == "boxplot" || type == "violin") { # setup base plot @@ -486,26 +486,26 @@ sjp.frq <- function(var.cnt, # and x-axis scalex <- scale_x_discrete(labels = "") if (type == "boxplot") { - baseplot <- baseplot + + baseplot <- baseplot + geom_boxplot(width = geom.size, fill = geom.colors) } else { - baseplot <- baseplot + + baseplot <- baseplot + geom_violin(trim = trimViolin, width = geom.size, fill = geom.colors) + # if we have a violin plot, add an additional boxplot inside to show # more information geom_boxplot(width = inner.box.width, fill = "white") } - + # if we have boxplots or violon plots, also add a point that indicates # the mean value # different fill colours, because violin boxplots have white background fcsp <- ifelse(type == "boxplot", "white", "black") baseplot <- baseplot + - stat_summary(fun.y = "mean", geom = "point", shape = 21, + stat_summary(fun.y = "mean", geom = "point", shape = 21, size = inner.box.dotsize, fill = fcsp) # no additional labels for the x- and y-axis, only diagram title baseplot <- baseplot + yscale + scalex - + # Start density plot here ----- } else if (type == "density") { # First, plot histogram with density curve @@ -515,7 +515,7 @@ sjp.frq <- function(var.cnt, geom_density(aes(y = ..density..), fill = "cornsilk", alpha = 0.3) + # remove margins from left and right diagram side scale_x_continuous(expand = expand.grid, breaks = histgridbreaks, limits = xlim) - + # check whether user wants to overlay the histogram # with a normal curve if (normal.curve) { @@ -533,7 +533,7 @@ sjp.frq <- function(var.cnt, } } else { # Since the density curve shows no absolute numbers (counts) on the - # y-axis, have also the opportunity to plot "real" histrograms with + # y-axis, have also the opportunity to plot "real" histrograms with # counts on the y-axis if (type == "histogram") { # original data needed for normal curve @@ -566,12 +566,12 @@ sjp.frq <- function(var.cnt, } # if we have a histogram, add mean-lines if (show.mean) { - baseplot <- baseplot + + baseplot <- baseplot + # vertical lines indicating the mean geom_vline(xintercept = mittelwert, linetype = mean.line.type, size = mean.line.size) # check whether meanvalue should be shown. if (show.mean.val) { - baseplot <- baseplot + + baseplot <- baseplot + # use annotation instead of geomtext, because we need mean value only printed once annotate( "text", @@ -592,37 +592,37 @@ sjp.frq <- function(var.cnt, if (show.sd) { baseplot <- baseplot + # first draw shaded rectangle. these are by default in grey colour with very high transparancy - annotate("rect", - xmin = mittelwert - stddev, - xmax = mittelwert + stddev, - ymin = 0, - ymax = c(upper_lim), - fill = "grey70", + annotate("rect", + xmin = mittelwert - stddev, + xmax = mittelwert + stddev, + ymin = 0, + ymax = c(upper_lim), + fill = "grey70", alpha = 0.2) + # draw border-lines for shaded rectangle - geom_vline(xintercept = mittelwert - stddev, - linetype = 3, - size = mean.line.size, + geom_vline(xintercept = mittelwert - stddev, + linetype = 3, + size = mean.line.size, alpha = 0.7) + - geom_vline(xintercept = mittelwert + stddev, - linetype = 3, - size = mean.line.size, + geom_vline(xintercept = mittelwert + stddev, + linetype = 3, + size = mean.line.size, alpha = 0.7) } } - + # show absolute and percentage value of each bar. baseplot <- baseplot + yscale + # continuous x-scale for histograms scale_x_continuous(limits = xlim, expand = expand.grid, breaks = histgridbreaks) } - - # set axes text and + + # set axes text and baseplot <- baseplot + labs(title = title, x = axis.title, y = NULL) # Check whether ggplot object should be returned or plotted if (prnt.plot) graphics::plot(baseplot) - + # return results invisible(structure(class = "sjpfrq", list(plot = baseplot, data = mydat))) } diff --git a/R/sjPlotGLME.R b/R/sjPlotGLME.R index d083ae9a..2b472c09 100755 --- a/R/sjPlotGLME.R +++ b/R/sjPlotGLME.R @@ -16,8 +16,8 @@ utils::globalVariables(c("estimate", "nQQ", "ci", "fixef", "fade", "conf.low", " #' Furthermore, this function also plots predicted probabilities / #' incidents or diagnostic plots. #' -#' @param fit a fitted model as returned by the \code{\link[lme4]{glmer}}-function. -#' @param type type of plot. Use one of following: +#' @param fit A fitted model as returned by the \code{\link[lme4]{glmer}}-function. +#' @param type Type of plot. Use one of following: #' \describe{ #' \item{\code{"re"}}{(default) for conditional modes (odds or incidents ratios) of random effects} #' \item{\code{"fe"}}{for odds or incidents ratios of fixed effects} @@ -31,29 +31,29 @@ utils::globalVariables(c("estimate", "nQQ", "ci", "fixef", "fade", "conf.low", " #' \item{\code{"pred.fe"}}{to plot predicted probabilities or incidents for the response, related to specific model predictors, only for fixed effects. See 'Details'.} #' \item{\code{"ma"}}{to check model assumptions. Note that only argument \code{fit} applies to this plot type. All other arguments are ignored.} #' } -#' @param vars numeric vector with column indices of selected variables or a character vector with +#' @param vars Numeric vector with column indices of selected variables or a character vector with #' variable names of selected variables from the fitted model, which should be used to plot #' - depending on \code{type} - estimates, fixed effects slopes or predicted values #' (mean, probabilities, incidents rates, ...). See 'Examples'. -#' @param ri.nr numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, +#' @param ri.nr Numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, #' and fitted model has more than one random intercept, \code{ri.nr} indicates #' which random effects of which random intercept (or: which list elements #' of \code{\link[lme4]{ranef}}) will be plotted. Default is \code{NULL}, #' so all random effects will be plotted. -#' @param emph.grp numeric vector with index numbers of grouping levels (from random effect). +#' @param emph.grp Numeric vector with index numbers of grouping levels (from random effect). #' If \code{type = "ri.slope"} and \code{facet.grid = FALSE}, #' an integrated plot of predicted probabilities of fixed effects resp. fixed #' effects slopes for each grouping level is plotted. To better find #' certain groups, use this argument to emphasize these groups in the plot. #' See 'Examples'. -#' @param title character vector with one or more labels that are used as plot title. -#' @param string.interc string, axis label of intercept estimate. Only applies, +#' @param title Character vector with one or more labels that are used as plot title. +#' @param string.interc String, axis label of intercept estimate. Only applies, #' if \code{show.intercept = TRUE} and \code{axis.labels} is not \code{NULL}. -#' @param point.alpha alpha value of point-geoms in the scatter plots. Only applies, +#' @param point.alpha Alpha value of point-geoms in the scatter plots. Only applies, #' if \code{show.scatter = TRUE}. -#' @param point.color color of of point-geoms in the scatter plots. Only applies, +#' @param point.color Color of of point-geoms in the scatter plots. Only applies, #' if \code{show.scatter = TRUE}. -#' @param sort.est determines in which way estimates are sorted in the plot: +#' @param sort.est Determines in which way estimates are sorted in the plot: #' \itemize{ #' \item If \code{NULL} (default), no sorting is done and estimates are sorted in order of model coefficients. #' \item If \code{sort.est = "sort.all"}, estimates are re-sorted for each coefficient (only applies if \code{type = "re"} and \code{facet.grid = FALSE}), i.e. the estimates of the random effects for each predictor are sorted and plotted to an own plot. @@ -61,25 +61,28 @@ utils::globalVariables(c("estimate", "nQQ", "ci", "fixef", "fade", "conf.low", " #' \item If \code{type = "re"}, specify a predictor's / coefficient's name to sort estimates according to this coefficient. #' } #' See 'Examples'. -#' @param fade.ns if \code{TRUE}, non significant estimates will be printed in slightly faded colors. -#' @param axis.labels character vector with labels for the model terms, used as axis labels. +#' @param fade.ns Logical, if \code{TRUE}, non significant estimates will be printed in slightly faded colors. +#' @param axis.labels Character vector with labels for the model terms, used as axis labels. #' For mixed models, should either be vector of fixed effects variable labels #' (if \code{type = "fe"} or \code{type = "fe.std"}) or a vector of group (value) #' labels from the random intercept's categories (if \code{type = "re"}). -#' @param axis.title character vector of length one or two (depending on +#' @param axis.title Character vector of length one or two (depending on #' the plot function and type), used as title(s) for the x and y axis. #' If not specified, a default labelling is chosen. To set multiple #' axis titles (e.g. with \code{type = "eff"} for many predictors), #' \code{axis.title} must be a character vector of same length of plots #' that are printed. In this case, each plot gets an own axis title #' (applying, for instance, to the y-axis for \code{type = "eff"}). -#' @param vline.type linetype of the vertical "zero point" line. Default is \code{2} (dashed line). -#' @param vline.color color of the vertical "zero point" line. Default value is \code{"grey70"}. -#' @param digits numeric, amount of digits after decimal point when rounding estimates and values. -#' @param free.scale if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid +#' \strong{Note:} Some plot types do not support this argument. In such +#' cases, use the return value and add axis titles manually with +#' \code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)} +#' @param vline.type Linetype of the vertical "zero point" line. Default is \code{2} (dashed line). +#' @param vline.color Color of the vertical "zero point" line. Default value is \code{"grey70"}. +#' @param digits Numeric, amount of digits after decimal point when rounding estimates and values. +#' @param free.scale Logical, if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid #' gets its own fitted scale. If \code{free.scale = FALSE}, each facet in #' the grid has the same scale range. -#' @param sample.n numeric vector. only applies, if \code{type = "rs.ri"}. If +#' @param sample.n Numeric vector. only applies, if \code{type = "rs.ri"}. If #' plot has many random intercepts (grouping levels), overplotting of #' regression lines may occur. In this case, consider random sampling of #' grouping levels. If \code{sample.n} is of length 1, a random sample @@ -88,7 +91,7 @@ utils::globalVariables(c("estimate", "nQQ", "ci", "fixef", "fade", "conf.low", " #' the values in \code{sample.n} are selected to plot random effects. #' Use the latter option to always select a fixed, identical set of #' random effects for plotting (useful when ecomparing multiple models). -#' @param ... other arguments passed down to further functions. Currently, following +#' @param ... Other arguments passed down to further functions. Currently, following #' arguments are supported: #' \describe{ #' \item{\code{?effects::effect}}{ diff --git a/R/sjPlotGroupFrequencies.R b/R/sjPlotGroupFrequencies.R index b607c6df..b95a4bf9 100755 --- a/R/sjPlotGroupFrequencies.R +++ b/R/sjPlotGroupFrequencies.R @@ -4,26 +4,26 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' @title Plot grouped or stacked frequencies #' @name sjp.grpfrq -#' +#' #' @seealso \href{http://www.strengejacke.de/sjPlot/sjp.grpfrq/}{sjPlot manual: sjp.grpfrq} -#' -#' @description Plot grouped or stacked frequencies of variables as bar/dot, +#' +#' @description Plot grouped or stacked frequencies of variables as bar/dot, #' box or violin plots, or line plot. -#' -#' @param var.cnt vector of counts, for which frequencies or means will be plotted or printed. -#' @param var.grp factor with the cross-classifying variable, where \code{var.cnt} +#' +#' @param var.cnt Vector of counts, for which frequencies or means will be plotted or printed. +#' @param var.grp Factor with the cross-classifying variable, where \code{var.cnt} #' is grouped into the categories represented by \code{var.grp}. -#' @param weight.by weight factor that will be applied to weight all cases. -#' Must be a vector of same length as the input vector. Default is +#' @param weight.by Vector of weights that will be applied to weight all cases. +#' Must be a vector of same length as the input vector. Default is #' \code{NULL}, so no weights are used. -#' @param title.wtd.suffix suffix (as string) for the title, if \code{weight.by} is specified, -#' e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +#' @param title.wtd.suffix Suffix (as string) for the title, if \code{weight.by} is specified, +#' e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so #' title will not have a suffix when cases are weighted. -#' @param intr.var an interaction variable which can be used for box plots. Divides each category indicated +#' @param intr.var An interaction variable which can be used for box plots. Divides each category indicated #' by \code{var.grp} into the factors of \code{intr.var}, so that each category of \code{var.grp} -#' is subgrouped into \code{intr.var}'s categories. Only applies when +#' is subgrouped into \code{intr.var}'s categories. Only applies when #' \code{type = "boxplot"} or \code{type = "violin"}. -#' @param bar.pos indicates whether bars should be positioned side-by-side (default), +#' @param bar.pos Indicates whether bars should be positioned side-by-side (default), #' or stacked (\code{bar.pos = "stack"}). May be abbreviated. #' @param type Specifies the plot type. May be abbreviated. #' \describe{ @@ -38,12 +38,12 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' @param show.legend logical, if \code{TRUE}, and depending on plot type and #' function, a legend is added to the plot. #' @param ylim numeric vector of length two, defining lower and upper axis limits -#' of the y scale. By default, this argument is set to \code{NULL}, i.e. the +#' of the y scale. By default, this argument is set to \code{NULL}, i.e. the #' y-axis fits to the required range of the data. -#' @param facet.grid \code{TRUE} to arrange the lay out of of multiple plots -#' in a grid of an integrated single plot. This argument calls +#' @param facet.grid \code{TRUE} to arrange the lay out of of multiple plots +#' in a grid of an integrated single plot. This argument calls #' \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -#' to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +#' to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects #' as an arranged grid with \code{\link[gridExtra]{grid.arrange}}. #' @param title character vector, used as plot title. Depending on plot type and function, #' will be set automatically. If \code{title = ""}, no title is printed. @@ -59,21 +59,21 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' @param legend.labels character vector with labels for the guide/legend. #' @param wrap.title numeric, determines how many chars of the plot title are displayed in #' one line and when a line break is inserted. -#' @param wrap.labels numeric, determines how many chars of the value, variable or axis +#' @param wrap.labels numeric, determines how many chars of the value, variable or axis #' labels are displayed in one line and when a line break is inserted. -#' @param wrap.legend.title numeric, determines how many chars of the legend's title +#' @param wrap.legend.title numeric, determines how many chars of the legend's title #' are displayed in one line and when a line break is inserted. -#' @param wrap.legend.labels numeric, determines how many chars of the legend labels are +#' @param wrap.legend.labels numeric, determines how many chars of the legend labels are #' displayed in one line and when a line break is inserted. -#' @param grid.breaks numeric; sets the distance between breaks for the axis, +#' @param grid.breaks numeric; sets the distance between breaks for the axis, #' i.e. at every \code{grid.breaks}'th position a major grid is being printed. -#' @param inner.box.width width of the inner box plot that is plotted inside of violin plots. Only applies +#' @param inner.box.width width of the inner box plot that is plotted inside of violin plots. Only applies #' if \code{type = "violin"}. Default value is 0.15 -#' @param inner.box.dotsize size of mean dot insie a violin or box plot. Applies only +#' @param inner.box.dotsize size of mean dot insie a violin or box plot. Applies only #' when \code{type = "violin"} or \code{"boxplot"}. #' @param geom.colors user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}. -#' @param geom.size size resp. width of the geoms (bar width, line thickness or point size, -#' depending on plot type and function). Note that bar and bin widths mostly +#' @param geom.size size resp. width of the geoms (bar width, line thickness or point size, +#' depending on plot type and function). Note that bar and bin widths mostly #' need smaller values than dot sizes. #' @param geom.spacing the spacing between geoms (i.e. bar spacing) #' @param smooth.lines prints a smooth line curve. Only applies, when argument \code{type = "line"}. @@ -86,38 +86,38 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' should be printed or not. #' @param show.prc logical, if \code{TRUE} (default), percentage values are plotted to each bar #' If \code{FALSE}, percentage values are removed. -#' @param emph.dots logical, if \code{TRUE}, the groups of dots in a dot-plot are highlighted +#' @param emph.dots logical, if \code{TRUE}, the groups of dots in a dot-plot are highlighted #' with a shaded rectangle. -#' @param show.summary logical, if \code{TRUE} (default), a summary with chi-squared -#' statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. -#' is shown. If a cell contains expected values lower than five (or lower than 10 -#' if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is -#' computed instead of chi-squared test. If the table's matrix is larger +#' @param show.summary logical, if \code{TRUE} (default), a summary with chi-squared +#' statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. +#' is shown. If a cell contains expected values lower than five (or lower than 10 +#' if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is +#' computed instead of chi-squared test. If the table's matrix is larger #' than 2x2, Fisher's excact test with Monte Carlo simulation is computed. -#' @param show.grpcnt logical, if \code{TRUE}, the count within each group is added +#' @param show.grpcnt logical, if \code{TRUE}, the count within each group is added #' to the category labels (e.g. \code{"Cat 1 (n=87)"}). Default value is \code{FALSE}. -#' @param summary.pos position of the model summary which is printed when \code{show.summary} -#' is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. +#' @param summary.pos position of the model summary which is printed when \code{show.summary} +#' is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. #' Use \code{"l"} for upper left corner. #' @param axis.titles character vector of length one or two, defining the title(s) #' for the x-axis and y-axis. -#' @param auto.group numeric value, indicating the minimum amount of unique values -#' in the count variable, at which automatic grouping into smaller units -#' is done (see \code{\link[sjmisc]{group_var}}). Default value for +#' @param auto.group numeric value, indicating the minimum amount of unique values +#' in the count variable, at which automatic grouping into smaller units +#' is done (see \code{\link[sjmisc]{group_var}}). Default value for #' \code{auto.group} is \code{NULL}, i.e. auto-grouping is off. #' See \code{\link[sjmisc]{group_var}} for examples on grouping. #' @param coord.flip logical, if \code{TRUE}, the x and y axis are swapped. -#' @param vjust character vector, indicating the vertical position of value -#' labels. Allowed are same values as for \code{vjust} aesthetics from +#' @param vjust character vector, indicating the vertical position of value +#' labels. Allowed are same values as for \code{vjust} aesthetics from #' \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -#' new options like "inward" and "outward", which align text towards and +#' new options like "inward" and "outward", which align text towards and #' away from the center of the plot respectively. -#' @param hjust character vector, indicating the horizontal position of value -#' labels. Allowed are same values as for \code{vjust} aesthetics from +#' @param hjust character vector, indicating the horizontal position of value +#' labels. Allowed are same values as for \code{vjust} aesthetics from #' \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -#' new options like "inward" and "outward", which align text towards and +#' new options like "inward" and "outward", which align text towards and #' away from the center of the plot respectively. -#' @param y.offset numeric, offset for text labels when their alignment is adjusted +#' @param y.offset numeric, offset for text labels when their alignment is adjusted #' to the top/bottom of the geom (see \code{hjust} and \code{vjust}). #' @param show.na logical, if \code{TRUE}, \code{\link{NA}}'s (missing values) #' are added to the output. @@ -125,9 +125,9 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' want to plot any graphs. In either case, the ggplot-object will be returned as value. #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{df}). -#' -#' @details \code{geom.colors} may be a character vector of color values -#' in hex-format, valid color value names (see \code{demo("colors")} or +#' +#' @details \code{geom.colors} may be a character vector of color values +#' in hex-format, valid color value names (see \code{demo("colors")} or #' a name of a \href{http://colorbrewer2.org}{color brewer} palette. #' Following options are valid for the \code{geom.colors} argument: #' \itemize{ @@ -143,22 +143,22 @@ utils::globalVariables(c(".", "label", "prz", "frq", "ypos", "wb", "ia", "mw", " #' library(sjmisc) #' data(efc) #' sjp.grpfrq(efc$e17age, efc$e16sex, show.values = FALSE) -#' +#' #' # boxplot #' sjp.grpfrq(efc$e17age, efc$e42dep, type = "box") -#' +#' #' # grouped bars #' sjp.grpfrq(efc$e42dep, efc$e16sex, title = NULL) #' -#' # box plots with interaction variable +#' # box plots with interaction variable #' sjp.grpfrq(efc$e17age, efc$e42dep, intr.var = efc$e16sex, type = "box") -#' +#' #' # Grouped bar plot #' sjp.grpfrq(efc$neg_c_7, efc$e42dep, show.values = FALSE) -#' +#' #' # same data as line plot #' sjp.grpfrq(efc$neg_c_7, efc$e42dep, type = "line") -#' +#' #' @import ggplot2 #' @importFrom sjstats weight2 #' @importFrom tidyr gather @@ -208,36 +208,36 @@ sjp.grpfrq <- function(var.cnt, vjust = "bottom", hjust = "center", prnt.plot = TRUE) { - + # get variable names var.name.cnt <- get_var_name(deparse(substitute(var.cnt))) var.name.grp <- get_var_name(deparse(substitute(var.grp))) - + # copy titles if (is.null(axis.titles)) { axisTitle.x <- NULL axisTitle.y <- NULL } else { axisTitle.x <- axis.titles[1] - if (length(axis.titles) > 1) + if (length(axis.titles) > 1) axisTitle.y <- axis.titles[2] else axisTitle.y <- NULL } - + # match arguments type <- match.arg(type) bar.pos <- match.arg(bar.pos) - + # turn off legend by default for facet grids if (facet.grid && missing(show.legend)) show.legend <- FALSE - + # Plot margins if (expand.grid) expand.grid <- ggplot2::waiver() else expand.grid <- c(0, 0) - + # check default geom.size if (is.null(geom.size)) { geom.size <- dplyr::case_when( @@ -249,16 +249,16 @@ sjp.grpfrq <- function(var.cnt, TRUE ~ .7 ) } - + # set text label offset if (is.null(y.offset)) { # get maximum y-pos y.offset <- ceiling(max(table(var.cnt, var.grp)) / 100) - + if (coord.flip) { if (missing(vjust)) vjust <- "center" if (missing(hjust)) hjust <- "bottom" - + # for flipped coordinates, we need to adjust # y-offset according to horizontal adjustemnt of labels if (hjust == "bottom") @@ -280,15 +280,15 @@ sjp.grpfrq <- function(var.cnt, } else { y_offset <- y.offset } - + # Interaction variable defined for invalid plot type? if (!is.null(intr.var) && type != "boxplot" && type != "violin") { message("`intr.var` only applies to boxplots and violinplots (see `type`) and will be ignored.") } - + # auto-set plot title for box plots? if (missing(title) && (type == "boxplot" || type == "violin")) title <- NULL - + # check whether variable should be auto-grouped if (!is.null(auto.group) && length(unique(var.cnt)) >= auto.group) { message(sprintf( @@ -296,10 +296,10 @@ sjp.grpfrq <- function(var.cnt, var.name.cnt, length(unique(var.cnt)) )) - + # check for default auto-group-size or user-defined groups agcnt <- ifelse(auto.group < 30, auto.group, 30) - + # group axis labels axis.labels <- sjmisc::group_labels( @@ -307,7 +307,7 @@ sjp.grpfrq <- function(var.cnt, groupsize = "auto", groupcount = agcnt ) - + # group variable grp.var.cnt <- sjmisc::group_var( @@ -316,13 +316,13 @@ sjp.grpfrq <- function(var.cnt, as.num = TRUE, groupcount = agcnt ) - + # set value labels grp.var.cnt <- sjmisc::set_labels(grp.var.cnt, labels = axis.labels) } else { grp.var.cnt <- var.cnt } - + # create cross table of frequencies and percentages mydat <- create.xtab.df( @@ -332,11 +332,11 @@ sjp.grpfrq <- function(var.cnt, na.rm = !show.na, weight.by = weight.by ) - + # x-position as numeric factor, added later after # tidying bars.xpos <- seq_len(nrow(mydat$mydat)) - + # try to automatically set labels if not passed as argument if (missing(axis.labels) && (type == "boxplot" || type == "violin")) { axis.labels <- mydat$labels.grp @@ -344,18 +344,18 @@ sjp.grpfrq <- function(var.cnt, # unless explicitely set to FALSE if (missing(show.legend)) show.legend <- !is.null(intr.var) } - + if (is.null(axis.labels)) axis.labels <- mydat$labels.cnt - + # we need to know later whether user has supplied legend labels or not we_have_legend_labels <- FALSE - + # check for auto-getting labels, ot if user passed legend labels as argument - if (is.null(legend.labels)) + if (is.null(legend.labels)) legend.labels <- mydat$labels.grp else we_have_legend_labels <- TRUE - + # go to interaction terms. in this case, due to interaction, the axis # labels become legend labels, but only if user has not specified # legend labels yet. In the latter case, leave legend labels unchanged. @@ -366,75 +366,75 @@ sjp.grpfrq <- function(var.cnt, include.values = F, include.non.labelled = T ) - + # create repeating label for x-axis intr.var.labels <- rep(intr.var.labels, length.out = length(axis.labels) * length(intr.var.labels)) - + # we need a legend, cause x axis is labelled with interaction var value show.legend <- TRUE - + # has user specified legend labels before? if (!we_have_legend_labels) legend.labels <- axis.labels } - + if (is.null(axisTitle.x)) axisTitle.x <- sjmisc::get_label(var.cnt, def.value = var.name.cnt) if (is.null(legend.title)) legend.title <- sjmisc::get_label(var.grp, def.value = var.name.grp) - + if (is.null(title)) { t1 <- sjmisc::get_label(var.cnt, def.value = var.name.cnt) t2 <- sjmisc::get_label(var.grp, def.value = var.name.grp) if (!is.null(t1) && !is.null(t2)) title <- paste0(t1, " by ", t2) } - + # remove titles if empty if (!is.null(legend.title) && legend.title == "") legend.title <- NULL if (!is.null(axisTitle.x) && axisTitle.x == "") axisTitle.x <- NULL if (!is.null(axisTitle.y) && axisTitle.y == "") axisTitle.y <- NULL if (!is.null(title) && title == "") title <- NULL - + # variables may not be factors if (anyNA(as.numeric(na.omit(var.cnt)))) var.cnt <- sjmisc::to_value(var.cnt, keep.labels = F) else var.cnt <- as.numeric(var.cnt) - + if (anyNA(as.numeric(na.omit(var.grp)))) var.grp <- sjmisc::to_value(var.grp, keep.labels = F) else var.grp <- as.numeric(var.grp) - + # Define amount of categories grpcount <- length(legend.labels) - + # create cross table for stats, summary etc. # and weight variable mydf <- tidyr::gather(mydat$mydat, "group", "frq", 2:(grpcount + 1), factor_key = TRUE) - + # add xpos now mydf$xpos <- as.factor(as.numeric(bars.xpos)) - + # add half of Percentage values as new y-position for stacked bars # mydat <- ddply(mydat, "count", transform, ypos = cumsum(frq) - 0.5*frq) mydf <- mydf %>% dplyr::group_by(label) %>% dplyr::mutate(ypos = cumsum(frq) - 0.5 * frq) %>% dplyr::arrange(label) - + # add percentages mydf$prz <- round(100 * mydf$frq / sum(mydf$frq), 2) - + # If we have boxplots, use different data frame structure if (type == "boxplot" || type == "violin") { # weight variable w <- ifelse(is.null(weight.by), 1, weight.by) - + # interaction variable - if (is.null(intr.var)) + if (is.null(intr.var)) iav <- 1 - else + else iav <- intr.var - + # new data frame for box plots mydf <- stats::na.omit(data.frame(cbind( @@ -443,11 +443,11 @@ sjp.grpfrq <- function(var.cnt, ia = iav, wb = w ))) - + mydf$ia <- as.factor(mydf$ia) mydf$group <- as.factor(mydf$group) } - + # create expression with model summarys. used # for plotting in the diagram later mannwhitneyu <- function(count, grp) { @@ -463,14 +463,14 @@ sjp.grpfrq <- function(var.cnt, xsub <- as.numeric(stats::na.omit(xsub)) ysub <- as.numeric(stats::na.omit(ysub)) wt <- stats::wilcox.test(xsub ~ ysub) - + if (wt$p.value < 0.001) { modsum <- as.character(as.expression(substitute( p[pgrp] < pval, list(pgrp = sprintf("(%i|%i)", i, j), pval = 0.001) ))) } else { modsum <- as.character(as.expression(substitute( - p[pgrp] == pval, + p[pgrp] == pval, list(pgrp = sprintf("(%i|%i)", i, j), pval = sprintf("%.3f", wt$p.value))))) } @@ -484,7 +484,7 @@ sjp.grpfrq <- function(var.cnt, substring(completeString, 12), sep = "")) } - + # Check whether table summary should be printed modsum <- NULL if (show.summary) { @@ -493,30 +493,30 @@ sjp.grpfrq <- function(var.cnt, else modsum <- crosstabsum(var.cnt, var.grp, weight.by) } - + # Prepare and trim legend labels to appropriate size if (!is.null(legend.labels)) legend.labels <- sjmisc::word_wrap(legend.labels, wrap.legend.labels) - + if (!is.null(legend.title)) legend.title <- sjmisc::word_wrap(legend.title, wrap.legend.title) - + if (!is.null(title)) { # if we have weighted values, say that in diagram's title if (!is.null(title.wtd.suffix)) title <- paste(title, title.wtd.suffix, sep = "") title <- sjmisc::word_wrap(title, wrap.title) } - + if (!is.null(axisTitle.x)) axisTitle.x <- sjmisc::word_wrap(axisTitle.x, wrap.title) - + if (!is.null(axisTitle.y)) axisTitle.y <- sjmisc::word_wrap(axisTitle.y, wrap.title) - + if (!is.null(axis.labels)) axis.labels <- sjmisc::word_wrap(axis.labels, wrap.labels) - + if (!is.null(intr.var)) { if (!is.null(intr.var.labels)) { intr.var.labels <- sjmisc::word_wrap(intr.var.labels, wrap.labels) @@ -528,7 +528,7 @@ sjp.grpfrq <- function(var.cnt, intr.var.labels <- 1:iavarLabLength } } - + # add group counts to category labels if (show.grpcnt) { nas <- ifelse(isTRUE(show.na), "ifany", "no") @@ -560,11 +560,11 @@ sjp.grpfrq <- function(var.cnt, legend.labels <- paste(legend.labels, " (n=", sums, ")", sep = "") } } - + # Prepare bar charts trimViolin <- FALSE lower_lim <- 0 - + # calculate upper y-axis-range # if we have a fixed value, use this one here if (!is.null(ylim) && length(ylim) == 2) { @@ -591,7 +591,7 @@ sjp.grpfrq <- function(var.cnt, upper_lim <- max(pretty(table(grp.var.cnt, var.grp) * 1.05)) } } - + # align dodged position of labels to bar positions if (type == "line") posdodge <- 0 @@ -599,10 +599,10 @@ sjp.grpfrq <- function(var.cnt, posdodge <- geom.spacing else posdodge <- geom.size + geom.spacing - + # init shaded rectangles for plot ganno <- NULL - + # check whether we have dots or bars if (type == "dot") { # position_dodge displays dots in a dodged position so we avoid overlay here. This may lead @@ -639,17 +639,17 @@ sjp.grpfrq <- function(var.cnt, } else { geob <- geom_bar(stat = "identity", position = bar.pos, width = geom.size) } - + # don't display value labels when we have boxplots or violin plots if (type == "boxplot" || type == "violin") show.values <- FALSE - + if (show.values) { # set text positioning if (facet.grid) text.pos <- "identity" else text.pos <- position_dodge(posdodge) - + # if we have stacked bars, we need to apply # this stacked y-position to the labels as well if (bar.pos == "stack") { @@ -683,9 +683,9 @@ sjp.grpfrq <- function(var.cnt, ggvaluelabels <- geom_text( aes(y = frq + y_offset, label = sprintf("%i\n(%.01f%%)", frq, prz)), - position = text.pos, - vjust = vjust, - hjust = hjust, + position = text.pos, + vjust = vjust, + hjust = hjust, show.legend = FALSE ) } @@ -714,18 +714,18 @@ sjp.grpfrq <- function(var.cnt, } else { ggvaluelabels <- geom_text(aes(y = frq), label = "", show.legend = FALSE) } - + # Set up grid breaks if (is.null(grid.breaks)) gridbreaks <- ggplot2::waiver() else gridbreaks <- seq(lower_lim, upper_lim, by = grid.breaks) - + # Print plot if (type == "line") { # line plot need numeric x-scale mydf$xpos <- sjmisc::to_value(mydf$xpos, keep.labels = FALSE) - + # lines need colour aes baseplot <- ggplot(mydf, @@ -735,12 +735,12 @@ sjp.grpfrq <- function(var.cnt, colour = "group", linetype = "group" )) + geob - + # continuous scale for lines needed scalex <- scale_x_continuous() } else if (type == "boxplot" || type == "violin") { if (is.null(intr.var)) { - baseplot <- + baseplot <- ggplot(mydf, aes_string( x = "group", @@ -750,7 +750,7 @@ sjp.grpfrq <- function(var.cnt, )) + geob scalex <- scale_x_discrete(labels = axis.labels) } else { - baseplot <- + baseplot <- ggplot(mydf, aes( x = interaction(ia, group), y = frq, @@ -759,14 +759,14 @@ sjp.grpfrq <- function(var.cnt, )) + geob scalex <- scale_x_discrete(labels = intr.var.labels) } - + # if we have a violin plot, add an additional boxplot inside to show # more information if (type == "violin") { baseplot <- baseplot + geom_boxplot(width = inner.box.width, fill = "white", outlier.colour = NA) } - + # if we have boxplots or violon plots, also add a point that indicates # the mean value # different fill colours, because violin boxplots have white background @@ -777,7 +777,7 @@ sjp.grpfrq <- function(var.cnt, } else { if (type == "dot") { baseplot <- ggplot(mydf, aes_string(x = "xpos", y = "frq", colour = "group")) - + # check whether we have dots plotted, and if so, use annotation # We have to use annotation first, because the diagram's layers are plotted # in the order as they're passed to the ggplot-command. Since we don't want the @@ -786,18 +786,18 @@ sjp.grpfrq <- function(var.cnt, } else { baseplot <- ggplot(mydf, aes_string(x = "xpos", y = "frq", fill = "group")) } - + # add geom baseplot <- baseplot + geob - + # define x axis scalex <- scale_x_discrete(labels = axis.labels) } - + # If we have bars or dot plots, we show # Pearson's chi-square test results baseplot <- print.table.summary(baseplot, modsum, summary.pos) - + # prepare y-axis and # show or hide y-axis-labels if (show.axis.values) { @@ -814,7 +814,7 @@ sjp.grpfrq <- function(var.cnt, labels = NULL ) } - + # continue with plot objects... baseplot <- baseplot + # show absolute and percentage values for each bar @@ -835,10 +835,10 @@ sjp.grpfrq <- function(var.cnt, # It either corresponds to the maximum amount of cases in the data set # (length of var) or to the highest count of var's categories. y_scale - + # check whether coordinates should be flipped if (coord.flip) baseplot <- baseplot + coord_flip() - + # Here we start when we have a faces grid instead of # a grouped bar plot. if (facet.grid) { @@ -847,7 +847,7 @@ sjp.grpfrq <- function(var.cnt, theme(strip.text = element_text(face = "bold", size = rel(1.2))) + facet_wrap(~group) } - + # set geom colors baseplot <- sj.setGeomColors(baseplot, @@ -855,10 +855,10 @@ sjp.grpfrq <- function(var.cnt, length(legend.labels), show.legend, legend.labels) - + # Plot integrated bar chart here if (prnt.plot) suppressWarnings(graphics::plot(baseplot)) - + # return results invisible(structure( class = c("sjp", "sjpgrpfrq"), diff --git a/R/sjPlotGroupPropTable.R b/R/sjPlotGroupPropTable.R index 16b356ad..00d3a8b6 100755 --- a/R/sjPlotGroupPropTable.R +++ b/R/sjPlotGroupPropTable.R @@ -7,22 +7,22 @@ utils::globalVariables(c("dep", "n")) #' each level of \code{x} for the highest category in \code{y} #' is plotted, for each subgroup of \code{groups}. #' -#' @param x categorical variable, where the proportion of each category in +#' @param x Categorical variable, where the proportion of each category in #' \code{x} for the highest category of \code{y} will be printed #' along the x-axis. -#' @param y categorical or numeric variable. If not a binary variable, \code{y} +#' @param y Categorical or numeric variable. If not a binary variable, \code{y} #' will be recoded into a binary variable, dichtomized at the highest #' category and all remaining categories. -#' @param groups grouping variable, which will define the y-axis -#' @param shape.fill.color optional color vector, fill-color for non-filled shapes -#' @param shapes numeric vector with shape styles, used to map the different +#' @param groups Grouping variable, which will define the y-axis +#' @param shape.fill.color Optional color vector, fill-color for non-filled shapes +#' @param shapes Numeric vector with shape styles, used to map the different #' categories of \code{x}. -#' @param show.total logical, if \code{TRUE}, a total summary line for all aggregated +#' @param show.total Logical, if \code{TRUE}, a total summary line for all aggregated #' \code{groups} is added. -#' @param annotate.total logical, if \code{TRUE} and \code{show.total = TRUE}, +#' @param annotate.total Logical, if \code{TRUE} and \code{show.total = TRUE}, #' the total-row in the figure will be highlighted with a slightly #' shaded background. -#' @param axis.lim numeric vector of length 2, defining the range of the plot axis. +#' @param axis.lim Numeric vector of length 2, defining the range of the plot axis. #' Depending on plot type, may effect either x- or y-axis, or both. #' For multiple plot outputs (e.g., from \code{type = "eff"} or #' \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may @@ -175,7 +175,7 @@ sjp.gpt <- function(x, # recode dependent variable's categorues # max and all others, so we have proportion # between maximux value and rest - mydf$dep <- sjmisc::rec(mydf$dep, rec = "max=1;else=0") + mydf$dep <- sjmisc::rec(mydf$dep, recodes = "max=1;else=0") # group data by grouping variable, and inside # groups, group the x-variable diff --git a/R/sjPlotInteractions.R b/R/sjPlotInteractions.R index 1317d42c..16411d39 100755 --- a/R/sjPlotInteractions.R +++ b/R/sjPlotInteractions.R @@ -13,7 +13,7 @@ #' #' @seealso \href{http://www.strengejacke.de/sjPlot/sjp.int/}{sjPlot manual: sjp.int} #' -#' @description Plot regression (predicted values) or probability lines (predicted probabilities) of +#' @description Plot regression (predicted values) or probability lines (predicted probabilities) of #' significant interaction terms to better understand effects #' of moderations in regression models. This function accepts following fitted model classes: #' \itemize{ @@ -27,10 +27,10 @@ #' \item panel data estimators (\code{\link[plm]{plm}}) #' } #' Note that beside interaction terms, also the single predictors of each interaction (main effects) -#' must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, +#' must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, #' but \code{lm(dep ~ pred1:pred2)} won't! #' -#' @param fit the fitted (generalized) linear (mixed) model object, including interaction terms. Accepted model +#' @param fit A fitted (generalized) linear (mixed) model object, including interaction terms. Accepted model #' classes are #' \itemize{ #' \item linear models (\code{\link{lm}}) @@ -42,23 +42,23 @@ #' \item generalized least squares models (\code{\link[nlme]{gls}}, but only for \code{type = "eff"}) #' \item panel data estimators (\code{\link[plm]{plm}}) #' } -#' @param type interaction plot type. Use one of following values: +#' @param type Interaction plot type. Use one of following values: #' \describe{ #' \item{\code{type = "eff"}}{(default) plots the overall moderation effect on the response value. See 'Details'.} #' \item{\code{type = "cond"}}{plots the mere \emph{change} of the moderating effect on the response value (conditional effect). See 'Details'.} #' \item{\code{type = "emm"}}{plots the estimated marginal means (least square means). If this type is chosen, not all function arguments are applicable. See 'Details'.} #' } -#' @param int.term name of interaction term of \code{fit} (as character), which should be plotted +#' @param int.term Name of interaction term of \code{fit} (as character), which should be plotted #' when using \code{type = "eff"}. By default, this argument will be ignored #' (i.e. \code{int.term = NULL}). See 'Details'. -#' @param int.plot.index numeric vector with index numbers that indicate which +#' @param int.plot.index Numeric vector with index numbers that indicate which #' interaction terms should be plotted in case the \code{fit} has more than #' one interaction. By default, this value is \code{NULL}, hence all interactions #' are plotted. -#' @param diff if \code{FALSE} (default), the minimum and maximum interaction effects of the moderating variable +#' @param diff Logical, if \code{FALSE} (default), the minimum and maximum interaction effects of the moderating variable #' is shown (one line each). if \code{TRUE}, only the difference between minimum and maximum interaction effect #' is shown (single line). Only applies to \code{type = "cond"}. -#' @param mdrt.values indicates which values of the moderator variable should be +#' @param mdrt.values Indicates which values of the moderator variable should be #' used when plotting the interaction effects. #' \describe{ #' \item{\code{"minmax"}}{(default) minimum and maximum values (lower and upper bounds) of the moderator are used to plot the interaction between independent variable and moderator.} @@ -67,48 +67,48 @@ #' \item{\code{"quart"}}{calculates and uses the quartiles (lower, median and upper) of the moderator value.} #' \item{\code{"all"}}{uses all values of the moderator variable. Note that this option only applies to \code{type = "eff"}, for numeric moderator values.} #' } -#' @param swap.pred if \code{TRUE}, the predictor on the x-axis and the moderator value in an interaction are +#' @param swap.pred Logical, if \code{TRUE}, the predictor on the x-axis and the moderator value in an interaction are #' swapped. For \code{type = "eff"}, the first interaction term is used as moderator and the second term -#' is plotted at the x-axis. For \code{type = "cond"}, the interaction's predictor with less unique values is -#' printed along the x-axis. Default is \code{FALSE}, so the second predictor in an interaction, respectively +#' is plotted at the x-axis. For \code{type = "cond"}, the interaction's predictor with less unique values is +#' printed along the x-axis. Default is \code{FALSE}, so the second predictor in an interaction, respectively #' the predictor with more unique values is printed along the x-axis. -#' @param plevel indicates at which p-value an interaction term is considered as \emph{significant}, +#' @param plevel Numeric, indicates at which p-value an interaction term is considered as \emph{significant}, #' i.e. at which p-level an interaction term will be considered for plotting. Default is #' 0.1 (10 percent), hence, non-significant interactions are excluded by default. This #' argument does not apply to \code{type = "eff"}. -#' @param title default title used for the plots. Should be a character vector +#' @param title Default title used for the plots. Should be a character vector #' of same length as interaction plots to be plotted. Default value is \code{NULL}, which means that each plot's title #' includes the dependent variable as well as the names of the interaction terms. -#' @param fill.color fill color of the shaded area between the minimum and maximum lines. Default is \code{"grey"}. +#' @param fill.color Fill color of the shaded area between the minimum and maximum lines. Default is \code{"grey"}. #' Either set \code{fill.color} to \code{NULL} or use 0 for \code{fill.alpha} if you want to hide the shaded area. -#' @param fill.alpha alpha value (transparancy) of the shaded area between the minimum and maximum lines. Default is 0.4. +#' @param fill.alpha Alpha value (transparancy) of the shaded area between the minimum and maximum lines. Default is 0.4. #' Use either 0 or set \code{fill.color} to \code{NULL} if you want to hide the shaded area. -#' @param geom.colors vector of color values or name of a valid color brewer palette. -#' If not a color brewer palette name, \code{geom.colors} must be of same +#' @param geom.colors Vector of color values or name of a valid color brewer palette. +#' If not a color brewer palette name, \code{geom.colors} must be of same #' length as moderator values used in the plot (see \code{mdrt.values}). #' See also 'Details' in \code{\link{sjp.grpfrq}}. -#' @param axis.title a default title used for the x-axis. Should be a character vector +#' @param axis.title Default title used for the x-axis. Should be a character vector #' of same length as interaction plots to be plotted. Default value is \code{NULL}, #' which means that each plot's x-axis uses the predictor's name as title. -#' @param axis.labels character vector with value labels of the interaction, used +#' @param axis.labels Character vector with value labels of the interaction, used #' to label the x-axis. Only applies to \code{type = "emm"}. -#' @param legend.title title of the plot's legend. A character vector of same length as +#' @param legend.title Title of the plot's legend. A character vector of same length as #' amount of interaction plots to be plotted (i.e. one vector element for each #' plot's legend title). -#' @param legend.labels labels for the guide/legend. Either a character vector of same length as +#' @param legend.labels Labels for the guide/legend. Either a character vector of same length as #' amount of legend labels of the plot, or a \code{list} of character vectors, if more than one #' interaction plot is plotted (i.e. one vector of legend labels for each interaction plot). -#' Default is \code{NULL}, so the name of the predictor with min/max-effect is used +#' Default is \code{NULL}, so the name of the predictor with min/max-effect is used #' as legend label. -#' @param jitter.ci logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +#' @param jitter.ci Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence #' bands are displayed as error bars, adds jittering to lines and error bars #' to avoid overlapping. -#' +#' #' @inheritParams sjp.grpfrq #' @inheritParams sjp.frq #' @inheritParams sjp.lmer #' @inheritParams sjp.glmer -#' +#' #' @return (Insisibily) returns the ggplot-objects with the complete plot-list (\code{plot.list}) #' as well as the data frames that were used for setting up the ggplot-objects (\code{data.list}). #' @@ -119,23 +119,23 @@ #' You can pass further arguments down to \code{allEffects} for flexible #' function call via the \code{...}-argument. #' } -#' \item{\code{type = "cond"}}{plots the effective \emph{change} or \emph{impact} -#' (conditional effect) on a dependent variable of a moderation effect, as -#' described by Grace-Martin, i.e. the difference of the moderation effect on the -#' dependent variable in \emph{presence} and \emph{absence} of the moderating effect +#' \item{\code{type = "cond"}}{plots the effective \emph{change} or \emph{impact} +#' (conditional effect) on a dependent variable of a moderation effect, as +#' described by Grace-Martin, i.e. the difference of the moderation effect on the +#' dependent variable in \emph{presence} and \emph{absence} of the moderating effect #' (\emph{simple slope} plot or \emph{conditional effect}, see Hayes 2012). All #' remaining predictors are set to zero (i.e. ignored and not adjusted for). -#' Hence, this plot type may be used especially for \emph{binary or dummy coded} +#' Hence, this plot type may be used especially for \emph{binary or dummy coded} #' moderator values (see also Esarey and Summer 2015). #' This type \emph{does not} show the overall effect (marginal mean, i.e. adjusted -#' for all other predictors and covariates) of interactions on the result of Y. Use -#' \code{type = "eff"} for effect displays similar to the \code{\link[effects]{effect}}-function +#' for all other predictors and covariates) of interactions on the result of Y. Use +#' \code{type = "eff"} for effect displays similar to the \code{\link[effects]{effect}}-function #' from the \pkg{effects}-package. #' } #' \item{\code{type = "emm"}}{plots the estimated marginal means of repeated measures designs, -#' like two-way repeated measures AN(C)OVA. In detail, this type plots estimated marginal means +#' like two-way repeated measures AN(C)OVA. In detail, this type plots estimated marginal means #' (also called \emph{least square means} or \emph{marginal means}) of (significant) interaction terms. -#' The fitted models may be linear (mixed effects) +#' The fitted models may be linear (mixed effects) #' models of class \code{\link{lm}} or \code{\link[lme4]{merMod}}. This function may be used, for example, #' to plot differences in interventions between control and treatment groups over multiple time points. #' } @@ -149,7 +149,7 @@ #' See 'Examples'. #' #' @note Note that beside interaction terms, also the single predictors of each interaction (main effects) -#' must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, +#' must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, #' but \code{lm(dep ~ pred1:pred2)} won't! \cr \cr #' For \code{type = "emm"}, all interaction terms have to be factors. #' Furthermore, for \code{type = "eff"}, predictors of interactions that are introduced first into the model @@ -162,7 +162,7 @@ #' #' # fit "dummy" model. Note that moderator should enter #' # first the model, followed by predictor. Else, use -#' # argument "swap.pred" to change predictor on +#' # argument "swap.pred" to change predictor on #' # x-axis with moderator #' fit <- lm(weight ~ Diet * Time, data = ChickWeight) #' @@ -189,11 +189,11 @@ #' fit <- lm(usage ~ .*., data = mydf) #' summary(fit) #' -#' # plot interactions. note that type = "cond" only considers -#' # significant interactions by default. use "plevel" to +#' # plot interactions. note that type = "cond" only considers +#' # significant interactions by default. use "plevel" to #' # adjust p-level sensivity #' sjp.int(fit, type = "cond") -#' +#' #' # plot only selected interaction term for #' # type = "eff" #' sjp.int(fit, type = "eff", int.term = "sex*education") @@ -223,7 +223,7 @@ #' # plot interaction, increase p-level sensivity #' sjp.int(fit, type = "eff", legend.labels = get_labels(efc$c161sex), plevel = 0.1) #' sjp.int(fit, type = "cond", legend.labels = get_labels(efc$c161sex), plevel = 0.1) -#' +#' #' \dontrun{ #' # ------------------------------- #' # Plot estimated marginal means @@ -261,7 +261,7 @@ #' mydf$barthel <- efc$barthtot #' # re-fit model with continuous variable #' fit <- lm(burden ~ .*., data = mydf) -#' +#' #' # plot effects #' sjp.int(fit, type = "eff", show.ci = TRUE) #' @@ -380,7 +380,7 @@ sjp.int <- function(fit, return(sjp.emm(fit, swap.pred, plevel, title, geom.colors, geom.size, axis.title, axis.labels, legend.title, legend.labels, show.values, digits, show.ci, p.kr, wrap.title, - wrap.legend.title, wrap.legend.labels, y.offset, ylim, + wrap.legend.title, wrap.legend.labels, y.offset, ylim, grid.breaks, facet.grid, prnt.plot, ...)) } # -------------------------------------------------------- @@ -394,8 +394,8 @@ sjp.int <- function(fit, if (type == "eff") { return(sjp.eff.int(fit, int.term, int.plot.index, mdrt.values, swap.pred, plevel, title, geom.colors, geom.size, axis.title, - legend.title, legend.labels, show.values, wrap.title, wrap.legend.labels, - wrap.legend.title, xlim, ylim, y.offset, grid.breaks, + legend.title, legend.labels, show.values, wrap.title, wrap.legend.labels, + wrap.legend.title, xlim, ylim, y.offset, grid.breaks, show.ci, jitter.ci, p.kr, facet.grid, prnt.plot, fun, ...)) } # ----------------------------------------------------------- @@ -405,7 +405,7 @@ sjp.int <- function(fit, if ((fun == "glm" || fun == "glmer")) { if (binom_fam) y_title <- "Change in Predicted Probability" - else + else y_title <- "Change in Incidents Rates" } # ----------------------------------------------------------- @@ -430,7 +430,7 @@ sjp.int <- function(fit, plotlist <- list() dflist <- list() # ----------------------------------------------------------- - # when we have linear mixed effects models and both interaction + # when we have linear mixed effects models and both interaction # terms are factors, we may have the same interaction term names # multiples times - thus, remove redundant duplicates # ----------------------------------------------------------- @@ -456,7 +456,7 @@ sjp.int <- function(fit, interactionterms <- unlist(strsplit(intnames[cnt], ":")) labx <- c() # Label on y-axis is name of dependent variable - laby <- paste0("Change in ", sjmisc::get_label(modfram[[git[["depvar.label"]]]], + laby <- paste0("Change in ", sjmisc::get_label(modfram[[git[["depvar.label"]]]], def.value = git[["depvar.label"]])) # ----------------------------------------------------------- # find estimates (beta values) for each single predictor of @@ -502,7 +502,7 @@ sjp.int <- function(fit, # calculate regression line # ----------------------------------------------------------- if (useFirstPredOnY) { - labx <- sjmisc::get_label(modfram[[interactionterms[1]]], + labx <- sjmisc::get_label(modfram[[interactionterms[1]]], def.value = interactionterms[1]) predy <- interactionterms[2] # ----------------------------------------------------------- @@ -515,7 +515,7 @@ sjp.int <- function(fit, # ----------------------------------------------------------- b.pred <- b1 } else { - labx <- sjmisc::get_label(modfram[[interactionterms[2]]], + labx <- sjmisc::get_label(modfram[[interactionterms[2]]], def.value = interactionterms[2]) predy <- interactionterms[1] # ----------------------------------------------------------- @@ -563,8 +563,8 @@ sjp.int <- function(fit, # the estimates of each term and the associated interaction term, # i.e.: y = b0 + (b1 * pred1) + (b2 * pred2) + (b3 * pred1 * pred2) # ----------------------------------------------------------- - # We now calculate the conditional effect of predictor 1 under absence - # (or lowest impact) of predictor 2 on the dependent variable. Thus, + # We now calculate the conditional effect of predictor 1 under absence + # (or lowest impact) of predictor 2 on the dependent variable. Thus, # the slope for predictor 2 is not calculated. see # http://www.theanalysisfactor.com/interpreting-interactions-in-regression/ # http://www.theanalysisfactor.com/clarifications-on-interpreting-interactions-in-regression/ @@ -572,7 +572,7 @@ sjp.int <- function(fit, miny <- (b.pred * pred.value) + (b3 * pred.value * ymin) # ------------------------------ # here we calculate the conditional effect of predictor 1 under presence - # (or strongest impact) of predictor 2 on the dependent variable. Thus, + # (or strongest impact) of predictor 2 on the dependent variable. Thus, # the slope for predictor 2 only is not needed. see references above # ------------------------------ maxy <- (b.pred * pred.value) + (b3 * pred.value * ymax) @@ -642,7 +642,7 @@ sjp.int <- function(fit, lowerLim.y <- floor(min(intdf$y, na.rm = T)) upperLim.y <- ceiling(max(intdf$y, na.rm = T)) } - } + } } else { lowerLim.y <- ylim[1] upperLim.y <- ylim[2] @@ -674,7 +674,7 @@ sjp.int <- function(fit, interactionterms[ifelse(isTRUE(useFirstPredOnY), 2, 1)], ") on ", git[["depvar.label"]]) } else { - # copy plot counter + # copy plot counter l_nr <- cnt # check if we have enough labels. if not, use last labels if (l_nr > length(title)) l_nr <- length(title) @@ -721,7 +721,7 @@ sjp.int <- function(fit, } } } else { - # copy plot counter + # copy plot counter l_nr <- cnt # check if we have enough labels. if not, use last labels if (l_nr > length(legend.labels)) l_nr <- length(legend.labels) @@ -734,7 +734,7 @@ sjp.int <- function(fit, if (is.null(legend.title)) { lTitle <- sjmisc::get_label(modfound, def.value = predy) } else { - # copy plot counter + # copy plot counter l_nr <- cnt # check if we have enough legend titles, if not, use last legend title if (l_nr > length(legend.title)) l_nr <- length(legend.title) @@ -745,7 +745,7 @@ sjp.int <- function(fit, # x axis titles # ----------------------------------------------------------- if (!is.null(axis.title)) { - # copy plot counter + # copy plot counter l_nr <- cnt # check if we have enough axis titles, if not, use last legend title if (l_nr > length(axis.title)) l_nr <- length(axis.title) @@ -855,8 +855,8 @@ sjp.int <- function(fit, list(plot.list = plotlist, data.list = dflist))) } - - + + #' @importFrom stats na.omit model.frame #' @importFrom dplyr if_else sjp.eff.int <- function(fit, @@ -900,26 +900,26 @@ sjp.eff.int <- function(fit, if (is.null(grid.breaks)) gridbreaks.x <- gridbreaks.y <- ggplot2::waiver() # init default binom_fam <- FALSE - + # additional arguments for 'effects()'-function? add.args <- lapply(match.call(expand.dots = F)$`...`, function(x) x) # check whether we have a "transformation" argument t.add <- which(names(add.args) == "transformation") - # if we have a "transformation" argument, and it's NULL, + # if we have a "transformation" argument, and it's NULL, # no transformation of scale no.transform <- !sjmisc::is_empty(t.add) && is.null(eval(add.args[[t.add]])) # --------------------------------------- # get ...-arguments # --------------------------------------- dot.args <- get_dot_args(match.call(expand.dots = FALSE)$`...`) - + # ------------------------ # calculate effects of higher order terms and # check if fitted model contains any interaction terms - # allEffects returns a list, with all interaction effects + # allEffects returns a list, with all interaction effects # (or higher order terms) as separate list element. each list # element contains the higher-order-term of the fitted model, - # where the 'term' attribute of interaction terms have a "*". + # where the 'term' attribute of interaction terms have a "*". # So we just need to look at each 'term' attribute of each # list element and see if there is a "*"... # ------------------------ @@ -943,7 +943,7 @@ sjp.eff.int <- function(fit, intpos <- 1 } # select only specific plots - if (!is.null(int.plot.index) && !any(int.plot.index > length(intpos))) intpos <- intpos[int.plot.index] + if (!is.null(int.plot.index) && !any(int.plot.index > length(intpos))) intpos <- intpos[int.plot.index] # init vector that saves ggplot objects plotlist <- list() dflist <- list() @@ -976,7 +976,7 @@ sjp.eff.int <- function(fit, x_is_factor <- is.factor(intdf[[pred_x.name]]) || (length(unique(na.omit(intdf[[pred_x.name]]))) < 3) mod_is_factor <- is.factor(intdf[[moderator.name]]) # ----------------------------------------------------------- - # check for moderator values, but only, if moderator + # check for moderator values, but only, if moderator # is no factor value. In this case, we can choose # the values for continuous moderator intentionally, # e.g. only min/max, or mean and sd. We don't need these @@ -993,7 +993,7 @@ sjp.eff.int <- function(fit, # ----------------------------------------------------------- mdrt.values <- mv_check(mdrt.values, modval) # we have more than two values, so re-calculate effects, just using - # min and max value of moderator. + # min and max value of moderator. if (mdrt.values == "minmax" && length(unique(intdf[[moderator.name]])) > 2) { # retrieve min and max values mv.min <- min(modval, na.rm = T) @@ -1033,19 +1033,19 @@ sjp.eff.int <- function(fit, # combine lists if (is.null(int.term)) { # re-compute effects - eff.tmp <- effects::allEffects(fit, xlevels = c(xl1, xl2), KR = p.kr, + eff.tmp <- effects::allEffects(fit, xlevels = c(xl1, xl2), KR = p.kr, confidence.level = dot.args[["ci.lvl"]], ...) # reset data frame intdf <- data.frame(eff.tmp[[intpos[i]]]) } else { # re-compute effects - eff.tmp <- effects::effect(int.term, fit, xlevels = c(xl1, xl2), + eff.tmp <- effects::effect(int.term, fit, xlevels = c(xl1, xl2), KR = p.kr, confidence.level = dot.args[["ci.lvl"]], ...) # reset data frame intdf <- data.frame(eff.tmp) } # ----------------------------------------------------------- - # check for predictor values on x-axis. if it + # check for predictor values on x-axis. if it # is no factor, select whole range of possible # values. # ----------------------------------------------------------- @@ -1158,14 +1158,14 @@ sjp.eff.int <- function(fit, # -------------------------------------------------------- # for logistic reg. if (binom_fam) { - ysc <- dplyr::if_else(isTRUE(no.transform), - true = "log-odds", - false = "probabilities", + ysc <- dplyr::if_else(isTRUE(no.transform), + true = "log-odds", + false = "probabilities", missing = "values") } else if (poisson_fam) { - ysc <- dplyr::if_else(isTRUE(no.transform), - true = "log-mean", - false = "incidents", + ysc <- dplyr::if_else(isTRUE(no.transform), + true = "log-mean", + false = "incidents", missing = "values") } else { ysc <- "values" @@ -1226,7 +1226,7 @@ sjp.eff.int <- function(fit, labtitle <- paste0("Interaction effect of ", moderator.name, " and ", pred_x.name, " on ", response.name) } else { - # copy plot counter + # copy plot counter l_nr <- i # check if we have enough labels. if not, use last labels if (l_nr > length(title)) l_nr <- length(title) @@ -1239,13 +1239,13 @@ sjp.eff.int <- function(fit, if (is.null(legend.labels)) { # try to get labels, but only for factors if (mod_is_factor) { - lLabels <- sjmisc::get_labels(stats::model.frame(fit)[[moderator.name]], + lLabels <- sjmisc::get_labels(stats::model.frame(fit)[[moderator.name]], attr.only = F) } # if we still have no labels, get values from group if (is.null(lLabels)) lLabels <- unique(as.character(intdf$grp)) } else { - # copy plot counter + # copy plot counter l_nr <- i # check if we have enough labels. if not, use last labels if (l_nr > length(legend.labels)) l_nr <- length(legend.labels) @@ -1262,10 +1262,10 @@ sjp.eff.int <- function(fit, # legend titles # ----------------------------------------------------------- if (is.null(legend.title)) { - lTitle <- sjmisc::get_label(stats::model.frame(fit)[[moderator.name]], + lTitle <- sjmisc::get_label(stats::model.frame(fit)[[moderator.name]], def.value = moderator.name) } else { - # copy plot counter + # copy plot counter l_nr <- i # check if we have enough legend titles, if not, use last legend title if (l_nr > length(legend.title)) l_nr <- length(legend.title) @@ -1276,7 +1276,7 @@ sjp.eff.int <- function(fit, # x axis titles # ----------------------------------------------------------- if (!is.null(axis.title)) { - # copy plot counter + # copy plot counter l_nr <- i # check if we have enough axis titles, if not, use last legend title if (l_nr > length(axis.title)) l_nr <- length(axis.title) @@ -1314,7 +1314,7 @@ sjp.eff.int <- function(fit, if (jitter.ci) { baseplot <- baseplot + geom_errorbar(aes_string(ymin = "conf.low", ymax = "conf.high", colour = "grp", linetype = "grp"), - width = dot.args[["eb.width"]], show.legend = FALSE, + width = dot.args[["eb.width"]], show.legend = FALSE, position = position_dodge(.2)) + geom_point(position = position_dodge(.2), shape = 16) + geom_line(size = geom.size, position = position_dodge(.2)) @@ -1330,8 +1330,8 @@ sjp.eff.int <- function(fit, } } else { # ------------------------------------------------- - # for continuous variables, we add continuous - # confidence region instead of error bars + # for continuous variables, we add continuous + # confidence region instead of error bars # ------------------------------------------------- baseplot <- baseplot + geom_ribbon(aes_string(ymin = "conf.low", ymax = "conf.high", colour = NULL, fill = "grp"), @@ -1345,7 +1345,7 @@ sjp.eff.int <- function(fit, # plot value labels # ------------------------------------------------------------ if (show.values) { - # don't need geom_point, because point-layer already + # don't need geom_point, because point-layer already # added with x_is_factor if (!x_is_factor) baseplot <- baseplot + geom_point() # add value label text @@ -1361,29 +1361,29 @@ sjp.eff.int <- function(fit, # we have specified labels for factors on x-axis only... if (x_is_factor && !is.null(x_labels)) { baseplot <- baseplot + - scale_x_continuous(limits = c(lowerLim.x, upperLim.x), + scale_x_continuous(limits = c(lowerLim.x, upperLim.x), breaks = gridbreaks.x, labels = x_labels) - + } else { # ...else, we use waiver-labels baseplot <- baseplot + - scale_x_continuous(limits = c(lowerLim.x, upperLim.x), + scale_x_continuous(limits = c(lowerLim.x, upperLim.x), breaks = gridbreaks.x) } # ------------------------ - # for logistic regression, use + # for logistic regression, use # 0 to 1 scale limits and percentage scale # ------------------------ if (binom_fam && !no.transform) { baseplot <- baseplot + - scale_y_continuous(limits = c(lowerLim.y, upperLim.y), + scale_y_continuous(limits = c(lowerLim.y, upperLim.y), breaks = gridbreaks.y, labels = scales::percent) } else { baseplot <- baseplot + # set axis scale breaks - scale_y_continuous(limits = c(lowerLim.y, upperLim.y), + scale_y_continuous(limits = c(lowerLim.y, upperLim.y), breaks = gridbreaks.y) } # --------------------------------------------------------- @@ -1393,10 +1393,10 @@ sjp.eff.int <- function(fit, # --------------------------------------------------------- # set geom colors # --------------------------------------------------------- - baseplot <- sj.setGeomColors(baseplot, - geom.colors, - pal.len = length(unique(stats::na.omit(intdf$grp))), - show.legend = !is.null(lLabels) & !facet.grid, + baseplot <- sj.setGeomColors(baseplot, + geom.colors, + pal.len = length(unique(stats::na.omit(intdf$grp))), + show.legend = !is.null(lLabels) & !facet.grid, lLabels) # --------------------------------------------------------- # Check whether ggplot object should be returned or plotted @@ -1564,4 +1564,4 @@ getInteractionTerms <- function(fit, fun, plevel, p.kr) { b0 = b0, fitdat = fitdat, depvar.label = depvar.label)) -} \ No newline at end of file +} diff --git a/R/sjPlotLikert.R b/R/sjPlotLikert.R index 7fdf968c..8b4b5959 100755 --- a/R/sjPlotLikert.R +++ b/R/sjPlotLikert.R @@ -18,18 +18,18 @@ utils::globalVariables(c("offset")) #' of categories fails. In such cases, specify the amount of categories #' with the \code{catcount}-argument. #' -#' @param catcount optional, amount of categories of \code{items} (e.g. \emph{"strongly disagree", +#' @param catcount Optional, amount of categories of \code{items} (e.g. \emph{"strongly disagree", #' "disagree", "agree"} and \emph{"strongly agree"} would be \code{catcount = 4}). #' Note that this argument only applies to "valid" answers, i.e. if you #' have an additional neutral category (see \code{cat.neutral}) like \emph{"don't know"}, #' this won't count for \code{catcount} (e.g. "strongly disagree", #' "disagree", "agree", "strongly agree" and neutral category "don't know" #' would still mean that \code{catcount = 4}). See 'Note'. -#' @param cat.neutral if there's a neutral category (like "don't know" etc.), specify +#' @param cat.neutral If there's a neutral category (like "don't know" etc.), specify #' the index number (value) for this category. Else, set \code{cat.neutral = NULL} (default). #' The proportions of neutral category answers are plotted as grey bars on the left side of #' the figure. -#' @param sort.frq indicates whether the items of \code{items} should be ordered by +#' @param sort.frq Indicates whether the items of \code{items} should be ordered by #' total sum of positive or negative answers. #' \describe{ #' \item{\code{"pos.asc"}}{to order ascending by sum of positive answers} @@ -38,19 +38,19 @@ utils::globalVariables(c("offset")) #' \item{\code{"neg.desc"}}{for sorting descending negative answers} #' \item{\code{NULL}}{(default) for no sorting} #' } -#' @param reverse.colors logical, if \code{TRUE}, the color scale from \code{geom.colors} will be reversed, +#' @param reverse.colors Logical, if \code{TRUE}, the color scale from \code{geom.colors} will be reversed, #' so positive and negative values switch colors. -#' @param cat.neutral.color color of the neutral category, if plotted (see \code{cat.neutral}). -#' @param intercept.line.color color of the vertical intercept line that divides positive and negative values. -#' @param values determines style and position of percentage value labels on the bars: +#' @param cat.neutral.color Color of the neutral category, if plotted (see \code{cat.neutral}). +#' @param intercept.line.color Color of the vertical intercept line that divides positive and negative values. +#' @param values Determines style and position of percentage value labels on the bars: #' \describe{ #' \item{\code{"show"}}{(default) shows percentage value labels in the middle of each category bar} #' \item{\code{"hide"}}{hides the value labels, so no percentage values on the bars are printed} #' \item{\code{"sum.inside"}}{shows the sums of percentage values for both negative and positive values and prints them inside the end of each bar} #' \item{\code{"sum.outide"}}{shows the sums of percentage values for both negative and positive values and prints them outside the end of each bar} #' } -#' @param show.prc.sign logical, if \code{TRUE}, \%-signs for value labels are shown. -#' @param grid.range numeric, limits of the x-axis-range, as proportion of 100. +#' @param show.prc.sign Logical, if \code{TRUE}, \%-signs for value labels are shown. +#' @param grid.range Numeric, limits of the x-axis-range, as proportion of 100. #' Default is 1, so the x-scale ranges from zero to 100\% on #' both sides from the center. You can use values beyond 1 #' (100\%) in case bar labels are not printed because they exceed the axis range. @@ -67,27 +67,6 @@ utils::globalVariables(c("offset")) #' \code{df.pos} for the positive values and \code{df.neutral} for the neutral category values). #' #' @examples -#' # prepare data for 4-category likert scale, with neutral category 5 items -#' Q1 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.2, .3, .1, .4))) -#' Q2 <- as.factor(sample(1:5, 500, replace = TRUE, prob = c(.5, .25, .12, .09, .03))) -#' Q3 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.25, .1, .4, .25))) -#' Q4 <- as.factor(sample(1:5, 500, replace = TRUE, prob = c(.1, .3, .38, .1, .12))) -#' Q5 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.35, .25, .15, .25))) -#' -#' likert_4 <- data.frame(Q1, Q2, Q3, Q4, Q5) -#' -#' # create labels -#' levels_4 <- c("Strongly agree", "Agree", "Disagree", -#' "Strongly Disagree", "Don't know") -#' -#' # create item labels -#' items <- c("Q1", "Q2", "Q3", "Q4", "Q5") -#' -#' # plot 4-category-likert-scale, no sorting -#' sjp.likert(likert_4, cat.neutral = 5, legend.labels = levels_4, -#' axis.labels = items, grid.range = 1.2, expand.grid = FALSE, -#' values = "sum.outside", show.prc.sign = TRUE) -#' #' # Data from the EUROFAMCARE sample dataset #' library(dplyr) #' library(sjmisc) @@ -96,6 +75,14 @@ utils::globalVariables(c("offset")) #' # variable name, and then plot that subset as likert-plot #' efc[, find_var(efc, "cop")] %>% sjp.likert() #' +#' sjp.likert( +#' find_var(efc, "cop", as.df = TRUE), +#' grid.range = 1.2, +#' expand.grid = FALSE, +#' values = "sum.outside", +#' show.prc.sign = TRUE +#' ) +#' #' @import ggplot2 #' @importFrom stats na.omit xtabs #' @importFrom sjmisc is_odd set_na @@ -264,7 +251,7 @@ sjp.likert <- function(items, collapse = ";"), ";else=copy" ) # finally, recode data - items <- sjmisc::rec(items, rec = recode.pattern) + items <- sjmisc::rec(items, recodes = recode.pattern) # re-order legend labels as well ll.order <- c(seq_len(catcount + adding)[-cat.neutral], cat.neutral) legend.labels <- legend.labels[ll.order] diff --git a/R/sjPlotLinreg.R b/R/sjPlotLinreg.R index 4a9f2536..f8bd20ad 100755 --- a/R/sjPlotLinreg.R +++ b/R/sjPlotLinreg.R @@ -69,8 +69,8 @@ utils::globalVariables(c("fit", "vars", "stdbeta", "x", "ydiff", "y", "grp", ".s #' between model's predictors.} #' } #' -#' @param fit fitted linear regression model (of class \code{\link{lm}}, \code{\link[nlme]{gls}} or \code{plm}). -#' @param type type of plot. Use one of following: +#' @param fit Fitted linear regression model (of class \code{\link{lm}}, \code{\link[nlme]{gls}} or \code{plm}). +#' @param type Type of plot. Use one of following: #' \describe{ #' \item{\code{"lm"}}{(default) for forest-plot like plot of estimates. If the fitted model only contains one predictor, intercept and slope are plotted.} #' \item{\code{"std"}}{for forest-plot like plot of standardized beta values. If the fitted model only contains one predictor, intercept and slope are plotted.} @@ -83,37 +83,37 @@ utils::globalVariables(c("fit", "vars", "stdbeta", "x", "ydiff", "y", "grp", ".s #' \item{\code{"ma"}}{to check model assumptions. Note that only three arguments are relevant for this option \code{fit} and \code{complete.dgns}. All other arguments are ignored.} #' \item{\code{"vif"}}{to plot Variance Inflation Factors.} #' } -#' @param sort.est logical, determines whether estimates should be sorted according to their values. +#' @param sort.est Logical, determines whether estimates should be sorted according to their values. #' If \code{group.estimates} is \emph{not} \code{NULL}, estimates are sorted #' according to their group assignment. -#' @param resp.label name of dependent variable, as string. Only +#' @param resp.label Name of dependent variable, as string. Only #' used if fitted model has only one predictor and \code{type = "lm"}. -#' @param geom.colors user defined color palette for geoms. If \code{group.estimates} +#' @param geom.colors User defined color palette for geoms. If \code{group.estimates} #' is \emph{not} specified, must either be vector with two color values or a specific #' color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if #' \code{group.estimates} is specified, \code{geom.colors} must be a vector #' of same length as groups. See 'Examples'. -#' @param group.estimates numeric or character vector, indicating a group identifier for +#' @param group.estimates Numeric or character vector, indicating a group identifier for #' each estimate. Dots and confidence intervals of estimates are coloured #' according to their group association. See 'Examples'. -#' @param remove.estimates character vector with coefficient names that indicate +#' @param remove.estimates Character vector with coefficient names that indicate #' which estimates should be removed from the plot. #' \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default #' is \code{NULL}, i.e. all estimates are printed. -#' @param show.p logical, adds significance levels to values, or value and +#' @param show.p Logical, adds significance levels to values, or value and #' variable labels. -#' @param show.summary logical, if \code{TRUE}, a summary with model statistics +#' @param show.summary Logical, if \code{TRUE}, a summary with model statistics #' is added to the plot. -#' @param show.ci logical, if \code{TRUE}, depending on \code{type}, a confidence +#' @param show.ci Logical, if \code{TRUE}, depending on \code{type}, a confidence #' interval or region is added to the plot. -#' @param show.scatter logical, if \code{TRUE} (default), adds a scatter plot of +#' @param show.scatter Logical, if \code{TRUE} (default), adds a scatter plot of #' data points to the plot. Only applies for slope-type or predictions plots. #' For most plot types, dots are jittered to avoid overplotting, hence the #' points don't reflect exact values in the data. -#' @param legend.title character vector, used as title for the plot legend. Note that +#' @param legend.title Character vector, used as title for the plot legend. Note that #' only some plot types have legends (e.g. \code{type = "pred"} or when #' grouping estimates with \code{group.estimates}). -#' @param complete.dgns logical, if \code{TRUE}, additional tests are performed. Default is \code{FALSE} +#' @param complete.dgns Logical, if \code{TRUE}, additional tests are performed. Default is \code{FALSE} #' Only applies if \code{type = "ma"}. #' #' @inheritParams sjp.grpfrq diff --git a/R/sjPlotOdds.R b/R/sjPlotOdds.R index b9d6a1d2..dbb8edc2 100755 --- a/R/sjPlotOdds.R +++ b/R/sjPlotOdds.R @@ -12,8 +12,8 @@ utils::globalVariables(c("OR", "lower", "upper", "p", "grp.est", "ci.low", "ci.h #' assumptions for generalized linear models, or marginal effects #' (predicted probabilities or events). #' -#' @param fit fitted generalized linear model (\code{\link{glm}}- or \code{logistf}-object). -#' @param type type of plot. Use one of following: +#' @param fit Fitted generalized linear model (\code{\link{glm}}- or \code{logistf}-object). +#' @param type Type of plot. Use one of following: #' \describe{ #' \item{\code{"dots"}}{(or \code{"glm"} or \code{"or"} (default)) for odds or incident rate ratios (forest plot). Note that this type plots the exponentiated estimates, thus being appropriate only for specific link-functions.} #' \item{\code{"slope"}}{to plot probability or incidents slopes (predicted probabilities or incidents) for each model term, where all remaining co-variates are set to zero (i.e. ignored). Use \code{facet.grid} to decide whether to plot each coefficient as separate plot or as integrated faceted plot.} @@ -22,12 +22,12 @@ utils::globalVariables(c("OR", "lower", "upper", "p", "grp.est", "ci.low", "ci.h #' \item{\code{"ma"}}{to check model assumptions. Note that the only relevant argument for this option is \code{fit}. All other arguments are ignored.} #' \item{\code{"vif"}}{to plot Variance Inflation Factors.} #' } -#' @param trns.ticks logical, if \code{TRUE}, the grid lines have exponential +#' @param trns.ticks Logical, if \code{TRUE}, the grid lines have exponential #' distances (equidistant), i.e. they visually have the same distance from #' one panel grid to the next. If \code{FALSE}, grids are #' plotted on every \code{grid.breaks}'s position, thus the grid lines become narrower with #' higher odds ratio values. -#' @param show.intercept logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +#' @param show.intercept Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. #' Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential #' transformation of estimates, the intercept in some cases can not be calculated, thus the #' function call is interrupted and no plot printed. diff --git a/R/sjPlotOddsMultiple.R b/R/sjPlotOddsMultiple.R index 5cf2ff27..8f4b6edc 100755 --- a/R/sjPlotOddsMultiple.R +++ b/R/sjPlotOddsMultiple.R @@ -1,34 +1,34 @@ #' @title Plot estimates of multiple fitted glm(er)'s #' @name sjp.glmm -#' -#' @description Plot and compare odds or incidents ratios (forest plots) of multiple fitted -#' generalized linear (mixed effects) models with confidence +#' +#' @description Plot and compare odds or incidents ratios (forest plots) of multiple fitted +#' generalized linear (mixed effects) models with confidence #' intervals in one plot. -#' -#' @param ... one or more fitted \code{glm}- or \code{glmerMod}-objects. May -#' also be a \code{\link{list}}-object with +#' +#' @param ... One or more fitted \code{glm}- or \code{glmerMod}-objects. May +#' also be a \code{\link{list}}-object with #' fitted models, instead of separating each model with comma. See 'Examples'. -#' +#' #' @inheritParams sjp.lmm #' @inheritParams sjp.glm #' @inheritParams sjp.lm #' @inheritParams sjp.grpfrq #' @inheritParams sjt.lm -#' -#' @note The fitted models may have differing predictors, but only in a +#' +#' @note The fitted models may have differing predictors, but only in a #' "stepwise" sense; i.e., models should share a common set of predictors, #' while some models may have additional predictors (e.g. added via #' the \code{\link[stats]{update}} function). See 'Examples'. -#' +#' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{data}). -#' +#' #' @examples #' # prepare dummy variables for binary logistic regression #' y1 <- ifelse(swiss$Fertility < median(swiss$Fertility), 0, 1) #' y2 <- ifelse(swiss$Infant.Mortality < median(swiss$Infant.Mortality), 0, 1) #' y3 <- ifelse(swiss$Agriculture 1 ggplot(mydat, aes(x = xpos, y = eigen, colour = eigen > 1)) + geom_line() + geom_point() + geom_hline(yintercept = 1, linetype = 2, colour = "grey50") + # print best number of factors according to eigen value - annotate("text", label = sprintf("Factors: %i", pcadata.kaiser), + annotate("text", label = sprintf("Factors: %i", pcadata.kaiser), x = Inf, y = Inf, vjust = "top", hjust = "top") + scale_x_continuous(breaks = seq(1, nrow(mydat), by = 2)) + labs(title = NULL, y = "Eigenvalue", x = "Number of factors") @@ -180,13 +149,13 @@ sjp.pca <- function(data, # -------------------------------------------------------- # check for predefined number of factors if (!is.null(nmbr.fctr) && is.numeric(nmbr.fctr)) pcadata.kaiser <- nmbr.fctr - + # rotate matrix if (rotation == "varimax") pcadata.rotate <- varimaxrota(pcadata, pcadata.kaiser) else if (rotation == "oblimin") pcadata.rotate <- psych::principal(r = data, nfactors = pcadata.kaiser, rotate = "oblimin") - + # create data frame with factor loadings df <- as.data.frame(pcadata.rotate$loadings[, seq_len(ncol(pcadata.rotate$loadings))]) # df <- as.data.frame(pcadata.varim$rotmat[, 1:pcadata.kaiser]) @@ -234,7 +203,7 @@ sjp.pca <- function(data, # -------------------------------------------------------- # this function retrieves a list with the column index ("factor" index) # where each case of the data frame has its highedt factor loading. - # So we know to which "group" (factor dimension) each case of the + # So we know to which "group" (factor dimension) each case of the # data frame belongs to according to the pca results # -------------------------------------------------------- getItemLoadings <- function(dataframe) { @@ -290,7 +259,7 @@ sjp.pca <- function(data, # rename columns, so we have numbers on x axis names(df) <- seq_len(ncol(df)) # convert to long data - df <- tidyr::gather(df, "xpos", "value", seq_len(ncol(df)), factor_key = TRUE) + df <- tidyr::gather(df, "xpos", "value", seq_len(ncol(df)), factor_key = TRUE) # we need new columns for y-positions and point sizes df <- cbind(df, ypos = seq_len(nrow(pcadata.rotate$loadings)), psize = exp(abs(df$value)) * geom.size) if (!show.values) { @@ -324,9 +293,9 @@ sjp.pca <- function(data, } heatmap <- heatmap + geo + # -------------------------------------------------------- - # fill gradient colour from distinct color brewer palette. - # negative correlations are dark red, positive corr. are dark blue, - # and they become lighter the closer they are to a correlation + # fill gradient colour from distinct color brewer palette. + # negative correlations are dark red, positive corr. are dark blue, + # and they become lighter the closer they are to a correlation # coefficient of zero # -------------------------------------------------------- scale_fill_gradientn(colours = geom.colors, limits = c(-1, 1)) + @@ -336,24 +305,24 @@ sjp.pca <- function(data, # facet bars, and flip coordinates # -------------------------------------------------------- if (type == "bar") { - heatmap <- heatmap + + heatmap <- heatmap + scale_x_discrete(labels = rev(axis.labels)) + scale_y_continuous(limits = c(0, 1), breaks = seq(0, 1, .2)) + facet_grid(~xpos) + geom_text(label = valueLabels, hjust = -0.2) + coord_flip() } else { - heatmap <- heatmap + + heatmap <- heatmap + geom_text(label = valueLabels) + - scale_y_reverse(breaks = seq(1, length(axis.labels), by = 1), + scale_y_reverse(breaks = seq(1, length(axis.labels), by = 1), labels = axis.labels) # -------------------------------------------------------- - # show cronbach's alpha value for each scale + # show cronbach's alpha value for each scale # -------------------------------------------------------- if (show.cronb) { heatmap <- heatmap + - annotate("text", x = alphaValues$nr, y = Inf, parse = TRUE, - label = sprintf("alpha == %.*f", digits, alphaValues$alpha), + annotate("text", x = alphaValues$nr, y = Inf, parse = TRUE, + label = sprintf("alpha == %.*f", digits, alphaValues$alpha), vjust = -0.5) } } diff --git a/R/sjPlotPearsonsChi2Test.R b/R/sjPlotPearsonsChi2Test.R index 3163d9ef..1e204644 100755 --- a/R/sjPlotPearsonsChi2Test.R +++ b/R/sjPlotPearsonsChi2Test.R @@ -1,19 +1,20 @@ #' @title Plot Pearson's Chi2-Test of multiple contingency tables #' @name sjp.chi2 -#' +#' #' @seealso \href{http://talesofr.wordpress.com/2013/05/05/ridiculously-photogenic-factors-heatmap-with-p-values/}{Tales of R}. -#' -#' @description Plot p-values of Pearson's Chi2-tests for multiple contingency tables as ellipses or tiles. +#' +#' @description Plot p-values of Pearson's Chi2-tests for multiple contingency tables as ellipses or tiles. #' Requires a data frame with dichotomous (dummy) variables. -#' Calculation of Chi2-matrix taken from +#' Calculation of Chi2-matrix taken from #' \href{https://talesofr.wordpress.com/2013/05/05/ridiculously-photogenic-factors-heatmap-with-p-values/}{Tales of R}. -#' -#' @param df data frame with (dichotomous) factor variables. +#' +#' @param df A data frame with (dichotomous) factor variables. +#' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{mydf}). -#' +#' #' @inheritParams sjp.grpfrq -#' +#' #' @examples #' # create data frame with 5 dichotomous (dummy) variables #' mydf <- data.frame(as.factor(sample(1:2, 100, replace=TRUE)), @@ -23,10 +24,10 @@ #' as.factor(sample(1:2, 100, replace=TRUE))) #' # create variable labels #' items <- list(c("Item 1", "Item 2", "Item 3", "Item 4", "Item 5")) -#' +#' #' # plot Chi2-contingency-table #' sjp.chi2(mydf, axis.labels = items) -#' +#' #' @import ggplot2 #' @importFrom dplyr bind_rows #' @export @@ -57,10 +58,10 @@ sjp.chi2 <- function(df, m <- data.frame() for (i in seq_len(ncol(combos))) { test <- chisq.test(df[, combos[1, i]], df[, combos[2, i]]) - out <- data.frame(Row = colnames(df)[combos[1, i]], + out <- data.frame(Row = colnames(df)[combos[1, i]], Column = colnames(df)[combos[2, i]], - Chi.Square = round(test$statistic, 4), - df = test$parameter, + Chi.Square = round(test$statistic, 4), + df = test$parameter, p.value = round(test$p.value, 4)) m <- suppressWarnings(dplyr::bind_rows(m, out)) } @@ -89,14 +90,14 @@ sjp.chi2 <- function(df, geom_tile() + scale_x_discrete(labels = axis.labels) + scale_y_discrete(labels = axis.labels) + - scale_fill_gradient2(low = rgb(128, 205, 193, maxColorValue = 255), - mid = "white", - high = rgb(5, 113, 176, maxColorValue = 255), + scale_fill_gradient2(low = rgb(128, 205, 193, maxColorValue = 255), + mid = "white", + high = rgb(5, 113, 176, maxColorValue = 255), midpoint = 0.05) + geom_text(label = sprintf("%.3f", m$p.value)) + - labs(title = title, - x = NULL, - y = NULL, + labs(title = title, + x = NULL, + y = NULL, fill = legend.title) # --------------------------------------------------------- # hide legend? diff --git a/R/sjPlotPolynomials.R b/R/sjPlotPolynomials.R index c7485d4e..612e3212 100755 --- a/R/sjPlotPolynomials.R +++ b/R/sjPlotPolynomials.R @@ -7,46 +7,46 @@ #' polynomial curves. A loess-smoothed line can be added to see #' which of the polynomial curves fits best to the data. #' -#' @param x a vector, representing the response variable of a linear (mixed) model; or +#' @param x A vector, representing the response variable of a linear (mixed) model; or #' a linear (mixed) model as returned by \code{\link{lm}} or \code{\link[lme4]{lmer}}. -#' @param poly.term if \code{x} is a vector, \code{poly.term} should also be a vector, representing +#' @param poly.term If \code{x} is a vector, \code{poly.term} should also be a vector, representing #' the polynomial term (independent variabl) in the model; if \code{x} is a #' fitted model, \code{poly.term} should be the polynomial term's name as character string. #' See 'Examples'. -#' @param poly.degree numeric, or numeric vector, indicating the degree of the polynomial. +#' @param poly.degree Numeric, or numeric vector, indicating the degree of the polynomial. #' If \code{poly.degree} is a numeric vector, multiple polynomial curves for #' each degree are plotted. See 'Examples'. -#' @param poly.scale logical, if \code{TRUE}, \code{poly.term} will be scaled before +#' @param poly.scale Logical, if \code{TRUE}, \code{poly.term} will be scaled before #' linear regression is computed. Default is \code{FALSE}. Scaling the polynomial #' term may have an impact on the resulting p-values. -#' @param fun linear function when modelling polynomial terms. Use \code{fun = "lm"} +#' @param fun Linear function when modelling polynomial terms. Use \code{fun = "lm"} #' for linear models, or \code{fun = "glm"} for generalized linear models. #' When \code{x} is not a vector, but a fitted model object, the function #' is detected automatically. If \code{x} is a vector, \code{fun} defaults #' to \code{"lm"}. -#' @param show.loess If \code{TRUE}, an additional loess-smoothed line is plotted. -#' @param show.loess.ci If \code{TRUE}, a confidence region for the loess-smoothed line +#' @param show.loess Logical, if \code{TRUE}, an additional loess-smoothed line is plotted. +#' @param show.loess.ci Logical, if \code{TRUE}, a confidence region for the loess-smoothed line #' will be plotted. -#' @param show.p logical, if \code{TRUE} (default), p-values for polynomial terms are +#' @param show.p Logical, if \code{TRUE} (default), p-values for polynomial terms are #' printed to the console. -#' @param loess.color color of the loess-smoothed line. Only applies, if \code{show.loess = TRUE}. -#' @return (insisibily) returns +#' @param loess.color Color of the loess-smoothed line. Only applies, if \code{show.loess = TRUE}. +#' @return (Insisibily) returns #' \describe{ #' \item{\code{plot}}{the ggplot-object with the complete plot} #' \item{\code{df}}{the data frame that was used for setting up the ggplot-object} #' \item{\code{cutpoints}}{a data frame that indicates x-values and predicted y-values of each direction change in the loess curvature} #' } -#' +#' #' @inheritParams sjp.glmer #' @inheritParams sjp.lm -#' +#' #' @details For each polynomial degree, a simple linear regression on \code{x} (resp. #' the extracted response, if \code{x} is a fitted model) is performed, #' where only the polynomial term \code{poly.term} is included as independent variable. -#' Thus, \code{lm(y ~ x + I(x^2) + ... + I(x^i))} is repeatedly computed +#' Thus, \code{lm(y ~ x + I(x^2) + ... + I(x^i))} is repeatedly computed #' for all values in \code{poly.degree}, and the predicted values of #' the reponse are plotted against the raw values of \code{poly.term}. -#' If \code{x} is a fitted model, other covariates are ignored when +#' If \code{x} is a fitted model, other covariates are ignored when #' finding the best fitting polynomial. \cr \cr #' This function evaluates raw polynomials, \emph{not orthogonal} polynomials. #' Polynomials are computed using the \code{\link{poly}} function, @@ -55,23 +55,23 @@ #' line (in dark grey) can be added (with \code{show.loess = TRUE}). The polynomial curves #' that comes closest to the loess-smoothed line should be the best #' fit to the data. -#' +#' #' @seealso To plot marginal effects of polynomial terms, call \code{\link{sjp.lm}} with \code{type = "poly"}, #' or \code{\link{sjp.lmer}} respectively for linear mixed models. -#' -#' @examples +#' +#' @examples #' library(sjmisc) #' data(efc) #' # linear fit. loess-smoothed line indicates a more #' # or less cubic curve #' sjp.poly(efc$c160age, efc$quol_5, 1) -#' +#' #' # quadratic fit #' sjp.poly(efc$c160age, efc$quol_5, 2) -#' +#' #' # linear to cubic fit #' sjp.poly(efc$c160age, efc$quol_5, 1:4, show.scatter = FALSE) -#' +#' #' library(sjmisc) #' data(efc) #' # fit sample model @@ -83,20 +83,20 @@ #' # indicates best fit. Looks like x^4 has the best fit, #' # however, only x^3 has significant p-values. #' sjp.poly(fit, "e17age", 2:4, show.scatter = FALSE) -#' +#' #' \dontrun{ #' # fit new model #' fit <- lm(tot_sc_e ~ c12hour + e42dep + e17age + I(e17age^2) + I(e17age^3), #' data = efc) #' # plot marginal effects of polynomial term #' sjp.lm(fit, type = "poly", poly.term = "e17age")} -#' +#' #' @import ggplot2 #' @importFrom scales grey_pal brewer_pal #' @importFrom stats lm glm binomial predict #' @export -sjp.poly <- function(x, - poly.term, +sjp.poly <- function(x, + poly.term, poly.degree, poly.scale = FALSE, fun = NULL, @@ -125,7 +125,7 @@ sjp.poly <- function(x, # -------------------------------------------- # parameter check: fitted model or variables? # -------------------------------------------- - if (is_merMod(x)) { + if (is_merMod(x)) { # retrieve response vector resp <- lme4::getME(x, "y") # get model frame @@ -183,8 +183,8 @@ sjp.poly <- function(x, # or a float value poly.digit <- ifelse(i %% 1 == 0, 0, 1) # create data frame with raw data and the fitted poly-curve - plot.df <- rbind(plot.df, cbind(mydat, - stats::predict(fit), + plot.df <- rbind(plot.df, cbind(mydat, + stats::predict(fit), sprintf("x^%.*f", poly.digit, i))) # print p-values? if (show.p) { @@ -205,17 +205,17 @@ sjp.poly <- function(x, # create plot polyplot <- ggplot(plot.df, aes_string(x = "x", y = "y", colour = "grp")) # show scatter plot as well? - if (show.scatter) polyplot <- polyplot + + if (show.scatter) polyplot <- polyplot + geom_jitter(colour = point.color, alpha = point.alpha, shape = 16) # show loess curve? this curve indicates the "perfect" curve through # the data - if (show.loess) polyplot <- polyplot + stat_smooth(method = "loess", + if (show.loess) polyplot <- polyplot + stat_smooth(method = "loess", color = loess.color, se = show.loess.ci, size = geom.size) # add curves for polynomials - polyplot <- polyplot + - geom_line(aes_string(y = "pred"), size = geom.size) + + polyplot <- polyplot + + geom_line(aes_string(y = "pred"), size = geom.size) + scale_color_manual(values = geom.colors, labels = lapply(poly.degree, function(j) bquote(x^.(j)))) + labs(x = axis.title, y = axisTitle.y, colour = "Polynomial\ndegrees") # --------------------------------------------------------- @@ -265,6 +265,6 @@ get_loess_cutpoints <- function(mydat) { } cnt <- cnt + 1 } - + return(data.frame(cutpoint.x = xvals, cutpoint.y = cutpoints)) -} \ No newline at end of file +} diff --git a/R/sjPlotPropTable.R b/R/sjPlotPropTable.R index 63930223..6dd0b72c 100755 --- a/R/sjPlotPropTable.R +++ b/R/sjPlotPropTable.R @@ -3,82 +3,82 @@ utils::globalVariables(c("rowname", "total", "ges", "prc", "n", "Count", "Group" #' @title Plot contingency tables #' @name sjp.xtab -#' +#' #' @seealso \itemize{ #' \item \href{http://www.strengejacke.de/sjPlot/sjp.xtab}{sjPlot manual: sjp.xtab} #' \item \code{\link{sjt.xtab}} #' } -#' +#' #' @description Plot proportional crosstables (contingency tables) of two variables as ggplot diagram. -#' -#' @param x a vector of values (variable) describing the bars which make up the plot. -#' @param grp grouping variable of same length as \code{x}, where \code{x} +#' +#' @param x A vector of values (variable) describing the bars which make up the plot. +#' @param grp Grouping variable of same length as \code{x}, where \code{x} #' is grouped into the categories represented by \code{grp}. -#' @param type plot type. may be either \code{"bar"} (default) for bar charts, +#' @param type Plot type. may be either \code{"bar"} (default) for bar charts, #' or \code{"line"} for line diagram. -#' @param margin indicates which data of the proportional table should be plotted. Use \code{"row"} for +#' @param margin Indicates which data of the proportional table should be plotted. Use \code{"row"} for #' calculating row percentages, \code{"col"} for column percentages and \code{"cell"} for cell percentages. #' If \code{margin = "col"}, an additional bar with the total sum of each column #' can be added to the plot (see \code{show.total}). -#' @param rev.order logical, if \code{TRUE}, order of categories (groups) is reversed. -#' @param dot.size dot size, only applies, when argument \code{type = "line"}. -#' @param string.total string for the legend label when a total-column is added. Only applies +#' @param rev.order Logical, if \code{TRUE}, order of categories (groups) is reversed. +#' @param dot.size Dot size, only applies, when argument \code{type = "line"}. +#' @param string.total String for the legend label when a total-column is added. Only applies #' if \code{show.total = TRUE}. Default is \code{"Total"}. -#' @param show.total when \code{margin = "col"}, an additional bar -#' with the sum within each category and it's percentages will be added +#' @param show.total When \code{margin = "col"}, an additional bar +#' with the sum within each category and it's percentages will be added #' to each category. -#' +#' #' @inheritParams sjp.grpfrq -#' +#' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{mydf}). -#' +#' #' @examples #' # create 4-category-items #' grp <- sample(1:4, 100, replace = TRUE) #' # create 3-category-items #' x <- sample(1:3, 100, replace = TRUE) -#' +#' #' # plot "cross tablulation" of x and grp #' sjp.xtab(x, grp) -#' +#' #' # plot "cross tablulation" of x and y, including labels #' sjp.xtab(x, grp, axis.labels = c("low", "mid", "high"), #' legend.labels = c("Grp 1", "Grp 2", "Grp 3", "Grp 4")) -#' +#' #' # plot "cross tablulation" of x and grp #' # as stacked proportional bars -#' sjp.xtab(x, grp, margin = "row", bar.pos = "stack", +#' sjp.xtab(x, grp, margin = "row", bar.pos = "stack", #' show.summary = TRUE, coord.flip = TRUE) -#' +#' #' # example with vertical labels #' library(sjmisc) #' data(efc) #' sjp.setTheme(geom.label.angle = 90) #' sjp.xtab(efc$e42dep, efc$e16sex, vjust = "center", hjust = "bottom") -#' +#' #' # grouped bars with EUROFAMCARE sample dataset #' # dataset was importet from an SPSS-file, #' # see ?sjmisc::read_spss #' data(efc) #' efc.val <- get_labels(efc) #' efc.var <- get_label(efc) -#' +#' #' sjp.xtab(efc$e42dep, efc$e16sex, title = efc.var['e42dep'], #' axis.labels = efc.val[['e42dep']], legend.title = efc.var['e16sex'], #' legend.labels = efc.val[['e16sex']]) -#' +#' #' sjp.xtab(efc$e16sex, efc$e42dep, title = efc.var['e16sex'], #' axis.labels = efc.val[['e16sex']], legend.title = efc.var['e42dep'], #' legend.labels = efc.val[['e42dep']]) -#' +#' #' # ------------------------------- #' # auto-detection of labels works here #' # so no need to specify labels. For #' # title-auto-detection, use NULL #' # ------------------------------- #' sjp.xtab(efc$e16sex, efc$e42dep, title = NULL) -#' +#' #' sjp.xtab(efc$e16sex, efc$e42dep, margin = "row", #' bar.pos = "stack", coord.flip = TRUE) #' @@ -145,7 +145,7 @@ sjp.xtab <- function(x, axisTitle.y <- NULL } else { axisTitle.x <- axis.titles[1] - if (length(axis.titles) > 1) + if (length(axis.titles) > 1) axisTitle.y <- axis.titles[2] else axisTitle.y <- NULL @@ -218,8 +218,8 @@ sjp.xtab <- function(x, # -------------------------------------------------------- if (!is.null(legend.title) && legend.title == "") legend.title <- NULL if (!is.null(axisTitle.x) && axisTitle.x == "") axisTitle.x <- NULL - if (!is.null(axisTitle.y) && axisTitle.y == "") axisTitle.y <- NULL - if (!is.null(title) && title == "") title <- NULL + if (!is.null(axisTitle.y) && axisTitle.y == "") axisTitle.y <- NULL + if (!is.null(title) && title == "") title <- NULL # -------------------------------------------------------- # Check if user wants to add total column, and if so, # define amount of categories @@ -321,9 +321,9 @@ sjp.xtab <- function(x, } else if (bar.pos == "stack") { # check upper limits. we may have rounding errors, so values # sum up to more than 100% - ul <- max(mydf %>% - dplyr::group_by(rowname) %>% - dplyr::summarize(ges = sum(prc)) %>% + ul <- max(mydf %>% + dplyr::group_by(rowname) %>% + dplyr::summarize(ges = sum(prc)) %>% dplyr::select(ges), na.rm = T) if (ul > 1L) upper_lim <- ul @@ -408,7 +408,7 @@ sjp.xtab <- function(x, if (type == "bar") { if (bar.pos == "dodge") { geob <- geom_bar(stat = "identity", - position = position_dodge(posdodge), + position = position_dodge(posdodge), width = geom.size) } else { geob <- geom_bar(stat = "identity", @@ -428,7 +428,7 @@ sjp.xtab <- function(x, baseplot <- ggplot(mydf, aes_string(x = "xpos", y = "prc", fill = "group")) + geob # if we have line diagram, print lines here if (type == "line") { - baseplot <- baseplot + + baseplot <- baseplot + geom_point(size = dot.size, shape = 21, show.legend = FALSE) } # ------------------------------------------ @@ -441,15 +441,15 @@ sjp.xtab <- function(x, # no additional labels for the x- and y-axis, only diagram title labs(title = title, x = axisTitle.x, y = axisTitle.y, fill = legend.title) + # print value labels to the x-axis. - # If argument "axis.labels" is NULL, the category numbers (1 to ...) + # If argument "axis.labels" is NULL, the category numbers (1 to ...) # appear on the x-axis scalex + # set Y-axis, depending on the calculated upper y-range. # It either corresponds to the maximum amount of cases in the data set # (length of var) or to the highest count of var's categories. - scale_y_continuous(breaks = gridbreaks, - limits = c(lower_lim, upper_lim), - expand = expand.grid, + scale_y_continuous(breaks = gridbreaks, + limits = c(lower_lim, upper_lim), + expand = expand.grid, labels = scales::percent) # check whether coordinates should be flipped, i.e. # swap x and y axis @@ -457,10 +457,10 @@ sjp.xtab <- function(x, # --------------------------------------------------------- # set geom colors # --------------------------------------------------------- - baseplot <- sj.setGeomColors(baseplot, - geom.colors, - length(legend.labels), - show.legend, + baseplot <- sj.setGeomColors(baseplot, + geom.colors, + length(legend.labels), + show.legend, legend.labels) # --------------------------------------------------------- # Check whether ggplot object should be returned or plotted diff --git a/R/sjPlotResiduals.R b/R/sjPlotResiduals.R index 65e64c04..81acaad0 100755 --- a/R/sjPlotResiduals.R +++ b/R/sjPlotResiduals.R @@ -6,17 +6,17 @@ utils::globalVariables(c("predicted", "residuals")) #' #' @description This function plots observed and predicted values of the response #' of linear (mixed) models for each coefficient and highlights the -#' observed values according to their distance (residuals) to the -#' predicted values. This allows to investigate how well actual and +#' observed values according to their distance (residuals) to the +#' predicted values. This allows to investigate how well actual and #' predicted values of the outcome fit across the predictor variables. #' -#' @param fit fitted linear (mixed) regression model (including objects of class +#' @param fit Fitted linear (mixed) regression model (including objects of class #' \code{\link[nlme]{gls}} or \code{plm}). -#' @param show.lines logical, if \code{TRUE}, a line connecting predicted and +#' @param show.lines Logical, if \code{TRUE}, a line connecting predicted and #' residual values is plotted. Set this argument to \code{FALSE}, if #' plot-building is too time consuming. -#' @param show.resid logical, if \code{TRUE}, residual values are plotted. -#' @param show.pred logical, if \code{TRUE}, predicted values are plotted. +#' @param show.resid Logical, if \code{TRUE}, residual values are plotted. +#' @param show.pred Logical, if \code{TRUE}, predicted values are plotted. #' @inheritParams sjp.lm #' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}), @@ -31,26 +31,26 @@ utils::globalVariables(c("predicted", "residuals")) #' data(efc) #' # fit model #' fit <- lm(neg_c_7 ~ c12hour + e17age + e42dep, data = efc) -#' +#' #' # plot residuals for all independent variables #' sjp.resid(fit) -#' +#' #' # remove some independent variables from output #' sjp.resid(fit, remove.estimates = c("e17age", "e42dep")) -#' +#' #' # show pattern #' sjp.resid(fit, remove.estimates = c("e17age", "e42dep"))$pattern #' #' @export -sjp.resid <- function(fit, geom.size = 2, remove.estimates = NULL, show.lines = TRUE, +sjp.resid <- function(fit, geom.size = 2, remove.estimates = NULL, show.lines = TRUE, show.resid = TRUE, show.pred = TRUE, show.ci = F, prnt.plot = TRUE) { # show lines only when both residual and predicted # values are plotted - else, lines make no sense if (!show.pred || !show.resid) show.lines <- FALSE - + # Obtain predicted and residual values mydat <- stats::model.frame(fit) - + # check whether estimates should be removed from plot if (!is.null(remove.estimates)) { keep <- which(!colnames(mydat) %in% remove.estimates) @@ -59,54 +59,54 @@ sjp.resid <- function(fit, geom.size = 2, remove.estimates = NULL, show.lines = } mydat$predicted <- stats::predict(fit) mydat$residuals <- stats::residuals(fit) - + # get name of response, used in ggplot-aes rv <- sjstats::resp_var(fit) - + # remove estimates, if required dummy <- mydat %>% dplyr::select(keep, predicted, residuals) - + # set default variable labels, used as column names, so labelled # data variable labels appear in facet grid header. sel <- 2:length(keep) var.labels <- sjmisc::get_label(dummy, def.value = colnames(dummy)[sel])[sel] if (is.null(var.labels) || all(var.labels == "")) var.labels <- colnames(dummy)[sel] colnames(dummy)[sel] <- var.labels - + # melt data - mydat <- suppressWarnings(dummy %>% + mydat <- suppressWarnings(dummy %>% tidyr::gather(key = "grp", value = "x", -1, -predicted, -residuals)) - + # melt data, build basic plot res.plot <- ggplot(mydat, aes_string(x = "x", y = rv)) + stat_smooth(method = "lm", se = show.ci, colour = "grey70") - - if (show.lines) res.plot <- res.plot + + + if (show.lines) res.plot <- res.plot + geom_segment(aes_string(xend = "x", yend = "predicted"), alpha = .3) - - if (show.resid) res.plot <- res.plot + + + if (show.resid) res.plot <- res.plot + geom_point(aes_string(fill = "residuals"), size = geom.size, shape = 21, colour = "grey50") - - if (show.pred) res.plot <- res.plot + + + if (show.pred) res.plot <- res.plot + geom_point(aes_string(y = "predicted"), shape = 1, size = geom.size) - + # residual plot res.plot <- res.plot + facet_grid(~grp, scales = "free") + scale_fill_gradient2(low = "#003399", mid = "white", high = "#993300") + guides(color = FALSE, fill = FALSE) + labs(x = NULL, y = sjmisc::get_label(mydat[[1]], def.value = rv)) - + # residual plot, showing pattern - pattern.plot <- ggplot(mydat, aes_string(x = "x", y = "residuals")) + - geom_hline(yintercept = 0, colour = "white", size = 2) + + pattern.plot <- ggplot(mydat, aes_string(x = "x", y = "residuals")) + + geom_hline(yintercept = 0, colour = "white", size = 2) + geom_line() + facet_grid(~grp, scales = "free") + labs(x = NULL, y = sjmisc::get_label(mydat[[1]], def.value = rv)) - + # Check whether ggplot object should be returned or plotted if (prnt.plot) graphics::plot(res.plot) - + # return results invisible(structure(class = "sjpresid", list(plot = res.plot, diff --git a/R/sjPlotScatter.R b/R/sjPlotScatter.R index 2f28aafc..4e580465 100755 --- a/R/sjPlotScatter.R +++ b/R/sjPlotScatter.R @@ -7,43 +7,43 @@ #' #' @seealso \href{http://www.strengejacke.de/sjPlot/sjp.scatter}{sjPlot manual: sjp.scatter} #' -#' @param x vector indicating the x positions. If not specified (i.e. if +#' @param x Vector indicating the x positions. If not specified (i.e. if #' \code{NULL}), a range from 1 to length of \code{y} is used to spread the #' dots along the x axis. -#' @param y vector indicating the y positions. If not specified (i.e. if +#' @param y Vector indicating the y positions. If not specified (i.e. if #' \code{NULL}), a range from 1 to length of \code{x} is used to spread the #' dots along the y axis. -#' @param grp grouping variable. If not \code{NULL}, the scatter plot will be grouped. See +#' @param grp Grouping variable. If not \code{NULL}, the scatter plot will be grouped. See #' 'Examples'. Default is \code{NULL}, i.e. not grouping is done. -#' @param dot.labels character vector with names for each coordinate pair given -#' by \code{x} and \code{y}, so text labels are added to the plot. +#' @param dot.labels Character vector with names for each coordinate pair given +#' by \code{x} and \code{y}, so text labels are added to the plot. #' Must be of same length as \code{x} and \code{y}. #' If \code{dot.labels} has a different length, data points will be trimmed #' to match \code{dot.labels}. If \code{dot.labels = NULL} (default), #' no labels are printed. #' @param label.size Size of text labels if argument \code{dot.labels} is used. -#' @param fit.line.grps logical, if \code{TRUE}, a fitted line for each group +#' @param fit.line.grps Logical, if \code{TRUE}, a fitted line for each group #' is drawn. See \code{fitmethod} to change the fit method of the fitted lines. -#' @param fit.line logical, if \code{TRUE}, a fitted line for the overall +#' @param fit.line Logical, if \code{TRUE}, a fitted line for the overall #' scatterplot is drawn. See \code{fitmethod} to change the fit method #' of the fitted line. #' @param fitmethod By default, a linear method (\code{"lm"}) is used for fitting #' the fit lines. Possible values are for instance \code{"lm"}, \code{"glm"}, #' \code{"loess"} or \code{"auto"}. -#' @param jitter.dots logical, if \code{TRUE}, points will be jittered (to avoid overplotting). -#' @param emph.dots logical, if \code{TRUE}, overlapping points at same coordinates +#' @param jitter.dots Logical, if \code{TRUE}, points will be jittered (to avoid overplotting). +#' @param emph.dots Logical, if \code{TRUE}, overlapping points at same coordinates #' will be becomme larger, so point size indicates amount of overlapping. -#' @param auto.jitter logical, if \code{TRUE}, points will be jittered according +#' @param auto.jitter Logical, if \code{TRUE}, points will be jittered according #' to an overlap-estimation. A matrix of \code{x} and \code{y} values #' is created and the amount of cells (indicating a unique point position) #' is calculated. If more than 15\% (see \code{jitter.ratio}) of the #' approximated amount of unique point coordinates seem to #' overlap, they are automatically jittered. -#' @param jitter.ratio ratio of tolerated overlapping (see \code{auto.jitter}). +#' @param jitter.ratio Ratio of tolerated overlapping (see \code{auto.jitter}). #' If approximated amount of overlapping points exceed this ratio, #' they are automatically jittered. Default is 0.15. Valid values range #' between 0 and 1. -#' @param show.rug logical, if \code{TRUE}, a marginal rug plot is displayed +#' @param show.rug Logical, if \code{TRUE}, a marginal rug plot is displayed #' in the graph. #' #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that @@ -86,12 +86,12 @@ #' sjp.scatter(y = fit$residuals, fit.line = TRUE) #' #' # "hide" axis titles -#' sjp.scatter(efc$c160age, efc$e17age, efc$e42dep, title = "", +#' sjp.scatter(efc$c160age, efc$e17age, efc$e42dep, title = "", #' axis.titles = c("", "")) #' #' # plot text labels #' pl <- c(1:10) -#' for (i in 1:10) +#' for (i in 1:10) #' pl[i] <- paste(sample(c(0:9, letters, LETTERS), 8, replace = TRUE), collapse = "") #' sjp.scatter(runif(10), runif(10), dot.labels = pl) #' @@ -151,7 +151,7 @@ sjp.scatter <- function(x = NULL, axisTitle.y <- NULL } else { axisTitle.x <- axis.titles[1] - if (length(axis.titles) > 1) + if (length(axis.titles) > 1) axisTitle.y <- axis.titles[2] else axisTitle.y <- NULL @@ -295,7 +295,7 @@ sjp.scatter <- function(x = NULL, scatter <- scatter + geom_jitter(size = geom.size) # do we have text? if (!is.null(dot.labels)) - scatter <- scatter + + scatter <- scatter + ggrepel::geom_text_repel(aes_string(label = "dot.lab"), size = label.size, position = "jitter") } else { if (emph.dots) { @@ -307,17 +307,17 @@ sjp.scatter <- function(x = NULL, } # do we have text? if (!is.null(dot.labels)) { - scatter <- scatter + + scatter <- scatter + ggrepel::geom_text_repel(aes_string(label = "dot.lab"), size = label.size) - + } } # -------------------------------------------------------- # Show fitted lines # -------------------------------------------------------- - if (fit.line.grps) scatter <- scatter + + if (fit.line.grps) scatter <- scatter + stat_smooth(data = df, aes_string(colour = "grp"), method = fitmethod, se = show.ci) - if (fit.line) scatter <- scatter + + if (fit.line) scatter <- scatter + stat_smooth(method = fitmethod, se = show.ci, colour = "black") # -------------------------------------------------------- # set font size for axes. @@ -327,7 +327,7 @@ sjp.scatter <- function(x = NULL, # -------------------------------------------------------- # Hide or show tick marks # -------------------------------------------------------- - if (!show.axis.values) + if (!show.axis.values) scatter <- scatter + scale_y_continuous(labels = NULL) + scale_x_continuous(labels = NULL) # -------------------------------------- diff --git a/R/sjPlotSetTheme.R b/R/sjPlotSetTheme.R index 01cd3c70..4d0b99e2 100755 --- a/R/sjPlotSetTheme.R +++ b/R/sjPlotSetTheme.R @@ -7,42 +7,42 @@ #' metrics from \code{theme_gray()} are used. See 'Details'. #' @param theme.font base font family for the plot. #' @param title.size size of plot title. Default is 1.3. -#' @param title.color color of plot title. Default is \code{"black"}. +#' @param title.color Color of plot title. Default is \code{"black"}. #' @param title.align alignment of plot title. Must be one of \code{"left"} (default), #' \code{"center"} or \code{"right"}. You may use initial letter only. #' @param title.vjust numeric, vertical adjustment for plot title. #' @param geom.outline.size size of bar outlines. Default is 0.1. Use #' size of \code{0} to remove geom outline. -#' @param geom.outline.color color of geom outline. Only applies, if \code{geom.outline.size} +#' @param geom.outline.color Color of geom outline. Only applies, if \code{geom.outline.size} #' is larger than 0. #' @param geom.boxoutline.size size of outlines and median bar especially for boxplots. #' Default is 0.5. Use size of \code{0} to remove boxplot outline. -#' @param geom.boxoutline.color color of outlines and median bar especially for boxplots. +#' @param geom.boxoutline.color Color of outlines and median bar especially for boxplots. #' Only applies, if \code{geom.boxoutline.size} is larger than 0. #' @param geom.alpha specifies the transparancy (alpha value) of geoms #' @param geom.linetype linetype of line geoms. Default is \code{1} (solid line). #' @param geom.errorbar.size size (thickness) of error bars. Default is \code{0.8} #' @param geom.errorbar.linetype linetype of error bars. Default is \code{1} (solid line). -#' @param geom.label.color color of geom's value and annotation labels +#' @param geom.label.color Color of geom's value and annotation labels #' @param geom.label.size size of geom's value and annotation labels #' @param geom.label.alpha alpha level of geom's value and annotation labels #' @param geom.label.angle angle of geom's value and annotation labels -#' @param axis.title.color color of x- and y-axis title labels +#' @param axis.title.color Color of x- and y-axis title labels #' @param axis.title.size size of x- and y-axis title labels #' @param axis.title.x.vjust numeric, vertical adjustment of x-axis-title. #' @param axis.title.y.vjust numeric, vertical adjustment of y-axis-title. #' @param axis.angle.x angle for x-axis labels #' @param axis.angle.y angle for y-axis labels #' @param axis.angle angle for x- and y-axis labels. If set, overrides both \code{axis.angle.x} and \code{axis.angle.y} -#' @param axis.textcolor.x color for x-axis labels. If not specified, a default dark gray +#' @param axis.textcolor.x Color for x-axis labels. If not specified, a default dark gray #' color palette will be used for the labels. -#' @param axis.textcolor.y color for y-axis labels. If not specified, a default dark gray +#' @param axis.textcolor.y Color for y-axis labels. If not specified, a default dark gray #' color palette will be used for the labels. -#' @param axis.textcolor color for both x- and y-axis labels. +#' @param axis.textcolor Color for both x- and y-axis labels. #' If set, overrides both \code{axis.textcolor.x} and \code{axis.textcolor.y} -#' @param axis.linecolor.x color of x-axis border -#' @param axis.linecolor.y color of y-axis border -#' @param axis.linecolor color for both x- and y-axis borders. +#' @param axis.linecolor.x Color of x-axis border +#' @param axis.linecolor.y Color of y-axis border +#' @param axis.linecolor Color for both x- and y-axis borders. #' If set, overrides both \code{axis.linecolor.x} and \code{axis.linecolor.y}. #' @param axis.line.size size (thickness) of axis lines. Only affected, if \code{axis.linecolor} #' is set. @@ -53,25 +53,25 @@ #' @param axis.ticksize.x size of tick marks at x-axis. #' @param axis.ticksize.y size of tick marks at y-axis. #' @param axis.tickslen length of axis tick marks -#' @param axis.tickscol color of axis tick marks +#' @param axis.tickscol Color of axis tick marks #' @param axis.ticksmar margin between axis labels and tick marks -#' @param panel.bordercol color of whole diagram border (panel border) -#' @param panel.backcol color of the diagram's background -#' @param panel.col color of both diagram's border and background. +#' @param panel.bordercol Color of whole diagram border (panel border) +#' @param panel.backcol Color of the diagram's background +#' @param panel.col Color of both diagram's border and background. #' If set, overrides both \code{panel.bordercol} and \code{panel.backcol}. -#' @param panel.major.gridcol color of the major grid lines of the diagram background -#' @param panel.minor.gridcol color of the minor grid lines of the diagram background -#' @param panel.gridcol color for both minor and major grid lines of the diagram background. +#' @param panel.major.gridcol Color of the major grid lines of the diagram background +#' @param panel.minor.gridcol Color of the minor grid lines of the diagram background +#' @param panel.gridcol Color for both minor and major grid lines of the diagram background. #' If set, overrides both \code{panel.major.gridcol} and \code{panel.minor.gridcol}. -#' @param panel.gridcol.x see \code{panel.gridcol}. -#' @param panel.gridcol.y see \code{panel.gridcol}. +#' @param panel.gridcol.x See \code{panel.gridcol}. +#' @param panel.gridcol.y See \code{panel.gridcol}. #' @param panel.major.linetype line type for major grid lines #' @param panel.minor.linetype line type for minor grid lines #' @param plot.margins numeric vector of length 4, indicating the top, right, #' bottom and left margin of the plot region. -#' @param plot.backcol color of the plot's background -#' @param plot.bordercol color of whole plot's border (panel border) -#' @param plot.col color of both plot's region border and background. +#' @param plot.backcol Color of the plot's background +#' @param plot.bordercol Color of whole plot's border (panel border) +#' @param plot.col Color of both plot's region border and background. #' If set, overrides both \code{plot.backcol} and \code{plot.bordercol}. #' @param legend.pos position of the legend, if a legend is drawn. #' \describe{ @@ -95,14 +95,14 @@ #' @param legend.inside logical, use \code{TRUE} to put legend inside the plotting area. See \code{legend.pos}. #' @param legend.size text size of the legend. Default is 1. Relative size, so #' recommended values are from 0.3 to 2.5 -#' @param legend.color color of the legend labels +#' @param legend.color Color of the legend labels #' @param legend.title.size text size of the legend title -#' @param legend.title.color color of the legend title +#' @param legend.title.color Color of the legend title #' @param legend.title.face font face of the legend title. By default, \code{"bold"} face is used. -#' @param legend.bordercol color of the legend's border. Default is \code{"white"}, so no visible border is drawn. +#' @param legend.bordercol Color of the legend's border. Default is \code{"white"}, so no visible border is drawn. #' @param legend.backgroundcol fill color of the legend's background. Default is \code{"white"}, so no visible background is drawn. #' @param legend.item.size size of legend's item (legend key), in centimetres. -#' @param legend.item.bordercol color of the legend's item-border. Default is \code{"white"}. +#' @param legend.item.bordercol Color of the legend's item-border. Default is \code{"white"}. #' @param legend.item.backcol fill color of the legend's item-background. Default is \code{"grey90"}. #' #' @return The customized theme object, or \code{NULL}, if a ggplot-theme was used. diff --git a/R/sjPlotStackFrequencies.R b/R/sjPlotStackFrequencies.R index e102e088..63596fa7 100755 --- a/R/sjPlotStackFrequencies.R +++ b/R/sjPlotStackFrequencies.R @@ -1,19 +1,19 @@ #' @title Plot stacked proportional bars #' @name sjp.stackfrq -#' +#' #' @seealso \itemize{ #' \item \href{http://www.strengejacke.de/sjPlot/sjp.stackfrq/}{sjPlot manual: sjp.stackfrq} #' \item \code{\link{sjt.stackfrq}} #' } -#' +#' #' @description Plot items (variables) of a scale as stacked proportional bars. This #' function is useful when several items with identical scale/categoroies #' should be plotted to compare the distribution of answers. -#' +#' #' @note Thanks to \href{http://www.clas.ufl.edu/users/forrest/}{Forrest Stevens} for bug fixes. -#' -#' @param items \code{data.frame} with each column representing one item. -#' @param sort.frq indicates whether the \code{items} should be ordered by +#' +#' @param items Data frame, with each column representing one item. +#' @param sort.frq Indicates whether the \code{items} should be ordered by #' by highest count of first or last category of \code{items}. #' \describe{ #' \item{\code{"first.asc"}}{to order ascending by lowest count of first category,} @@ -22,34 +22,16 @@ #' \item{\code{"last.desc"}}{to order descending by lowest count of last category,} #' \item{\code{NULL}}{(default) for no sorting.} #' } -#' @param show.prc If \code{TRUE} (default), the percentage values at the x-axis are shown. +#' @param show.prc Logical, if \code{TRUE} (default), the percentage values at the x-axis are shown. #' @return (Insisibily) returns the ggplot-object with the complete plot (\code{plot}) as well as the data frame that #' was used for setting up the ggplot-object (\code{df}). -#' +#' #' @inheritParams sjp.grpfrq #' @inheritParams sjp.frq #' @inheritParams sjp.glmer -#' +#' #' @examples -#' # random data for 4-category likert scale, 5 items -#' Q1 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.2, 0.3, 0.1, 0.4))) -#' Q2 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.5, 0.25, 0.15, 0.1))) -#' Q3 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.25, 0.1, 0.4, 0.25))) -#' Q4 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.1, 0.4, 0.4, 0.1))) -#' Q5 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.35, 0.25, 0.15, 0.25))) -#' -#' likert_4 <- data.frame(Q1, Q2, Q3, Q4, Q5) -#' -#' # create labels -#' levels_4 <- c("Independent", "Slightly dependent", -#' "Dependent", "Severely dependent") -#' -#' # plot stacked frequencies of 5 (ordered) item-scales -#' sjp.stackfrq(likert_4, legend.labels = levels_4) -#' -#' # ------------------------------- #' # Data from the EUROFAMCARE sample dataset -#' # ------------------------------- #' library(sjmisc) #' data(efc) #' # recveive first item of COPE-index scale @@ -57,9 +39,9 @@ #' # recveive first item of COPE-index scale #' end <- which(colnames(efc) == "c90cop9") #' # auto-detection of labels -#' sjp.stackfrq(efc[, c(start:end)]) -#' -#' +#' sjp.stackfrq(efc[, start:end]) +#' +#' #' @import ggplot2 #' @importFrom dplyr group_by mutate arrange #' @importFrom scales percent @@ -133,14 +115,14 @@ sjp.stackfrq <- function(items, # -------------------------------------------------------- # try to automatically set labels if not passed as parameter # -------------------------------------------------------- - if (is.null(legend.labels)) + if (is.null(legend.labels)) legend.labels <- sjmisc::get_labels( - items[[1]], + items[[1]], attr.only = F, - include.values = NULL, + include.values = NULL, include.non.labelled = T ) - + if (is.null(axis.labels)) { axis.labels <- sjmisc::get_label(items, def.value = colnames(items)) } @@ -171,8 +153,8 @@ sjp.stackfrq <- function(items, # -------------------------------------------------------- if (show.n) { for (i in seq_len(length(axis.labels))) { - axis.labels[i] <- paste(axis.labels[i], - sprintf(" (n=%i)", length(stats::na.omit(items[[i]]))), + axis.labels[i] <- paste(axis.labels[i], + sprintf(" (n=%i)", length(stats::na.omit(items[[i]]))), sep = "") } } @@ -218,7 +200,7 @@ sjp.stackfrq <- function(items, # need to be numeric, so percentage values (see below) are # correctly assigned, i.e. missing categories are considered df$var <- sjmisc::to_value(df$var, keep.labels = F) + diff # if categories start with zero, fix this here - # Create a vector of zeros + # Create a vector of zeros prc <- rep(0, countlen) # Replace the values in prc for those indices which equal df$var prc[df$var] <- df$prc @@ -230,30 +212,30 @@ sjp.stackfrq <- function(items, mydat <- data.frame(rbind(mydat, mydf)) } # ---------------------------- - # make sure group and count variable + # make sure group and count variable # are factor values # ---------------------------- mydat$grp <- as.factor(mydat$grp) mydat$cat <- as.factor(mydat$cat) # add half of Percentage values as new y-position for stacked bars - mydat <- mydat %>% - dplyr::group_by(grp) %>% - dplyr::mutate(ypos = cumsum(prc) - 0.5 * prc) %>% + mydat <- mydat %>% + dplyr::group_by(grp) %>% + dplyr::mutate(ypos = cumsum(prc) - 0.5 * prc) %>% dplyr::arrange(grp) # -------------------------------------------------------- # Prepare and trim legend labels to appropriate size # -------------------------------------------------------- # wrap legend text lines - legend.labels <- sjmisc::word_wrap(legend.labels, wrap.legend.labels) + legend.labels <- sjmisc::word_wrap(legend.labels, wrap.legend.labels) # check whether we have a title for the legend # if yes, wrap legend title line if (!is.null(legend.title)) legend.title <- sjmisc::word_wrap(legend.title, wrap.legend.title) # check length of diagram title and split longer string at into new lines # every 50 chars - if (!is.null(title)) title <- sjmisc::word_wrap(title, wrap.title) + if (!is.null(title)) title <- sjmisc::word_wrap(title, wrap.title) # check length of x-axis-labels and split longer strings at into new lines # every 10 chars, so labels don't overlap - if (!is.null(axis.labels)) axis.labels <- sjmisc::word_wrap(axis.labels, wrap.labels) + if (!is.null(axis.labels)) axis.labels <- sjmisc::word_wrap(axis.labels, wrap.labels) # ---------------------------- # Check if ordering was requested # ---------------------------- @@ -272,7 +254,7 @@ sjp.stackfrq <- function(items, # example: # we have 4 items, and they may be ordered like this: # 1 3 4 2 - # so the first item is the one with the lowest count , item 3 is on second postion, + # so the first item is the one with the lowest count , item 3 is on second postion, # item 4 is on third position and item 2 is the last item (with highest count) # we now need their order as subsequent vector: 1 4 2 3 # (i.e. item 1 is on first pos, item 2 is on fourth pos, item 3 is on @@ -283,7 +265,7 @@ sjp.stackfrq <- function(items, dummy2[facord] <- dummy1 } # now we have the order of either lowest to highest counts of first - # or last category of "items". We now need to repeat these values as + # or last category of "items". We now need to repeat these values as # often as we have answer categories orderedrow <- unlist(tapply(dummy2, seq_len(length(dummy2)), function(x) rep(x, countlen))) # replace old grp-order by new order @@ -330,7 +312,7 @@ sjp.stackfrq <- function(items, baseplot <- ggplot(mydat, aes(x = rev(grp), y = prc, fill = cat)) } else { baseplot <- ggplot(mydat, aes(x = grp, y = prc, fill = cat)) - } + } baseplot <- baseplot + # plot bar chart geom_bar(stat = "identity", position = position_stack(reverse = TRUE), width = geom.size) @@ -350,15 +332,15 @@ sjp.stackfrq <- function(items, # no additional labels for the x- and y-axis, only diagram title labs(title = title, x = axisTitle.x, y = axisTitle.y, fill = legend.title) + # print value labels to the x-axis. - # If parameter "axis.labels" is NULL, the category numbers (1 to ...) + # If parameter "axis.labels" is NULL, the category numbers (1 to ...) # appear on the x-axis scale_x_discrete(labels = axis.labels) + # set Y-axis, depending on the calculated upper y-range. # It either corresponds to the maximum amount of cases in the data set # (length of var) or to the highest count of var's categories. - scale_y_continuous(breaks = gridbreaks, - limits = c(0, 1), - expand = expgrid, + scale_y_continuous(breaks = gridbreaks, + limits = c(0, 1), + expand = expgrid, labels = perc.val) # check whether coordinates should be flipped, i.e. # swap x and y axis @@ -366,10 +348,10 @@ sjp.stackfrq <- function(items, # --------------------------------------------------------- # set geom colors # --------------------------------------------------------- - baseplot <- sj.setGeomColors(baseplot, - geom.colors, - length(legend.labels), - show.legend, + baseplot <- sj.setGeomColors(baseplot, + geom.colors, + length(legend.labels), + show.legend, legend.labels) # --------------------------------------------------------- # Check whether ggplot object should be returned or plotted diff --git a/R/sjTabCorr.R b/R/sjTabCorr.R index f176fcc8..33f9eb57 100755 --- a/R/sjTabCorr.R +++ b/R/sjTabCorr.R @@ -10,12 +10,12 @@ #' a \code{\link{data.frame}} or a matrix with correlation coefficients #' as returned by the \code{\link{cor}}-function. #' -#' @param fade.ns logical, if \code{TRUE} (default), non-significant correlation-values +#' @param fade.ns Logical, if \code{TRUE} (default), non-significant correlation-values #' appear faded (by using a lighter grey text color). See 'Note'. -#' @param triangle indicates whether only the upper right (use \code{"upper"}), lower left (use \code{"lower"}) +#' @param triangle Indicates whether only the upper right (use \code{"upper"}), lower left (use \code{"lower"}) #' or both (use \code{"both"}) triangles of the correlation table is filled with values. Default #' is \code{"both"}. You can specifiy the inital letter only. -#' @param val.rm specify a number between 0 and 1 to suppress the output of correlation values +#' @param val.rm Specify a number between 0 and 1 to suppress the output of correlation values #' that are smaller than \code{val.rm}. The absolute correlation values are used, so #' a correlation value of \code{-.5} would be greater than \code{val.rm = .4} and thus not be #' omitted. By default, this argument is \code{NULL}, hence all values are shown in the table. @@ -23,7 +23,7 @@ #' the HTML table, but made "invisible" with white foreground color. You can use the \code{CSS} #' argument (\code{"css.valueremove"}) to change color and appearance of those correlation value that are smaller than #' the limit specified by \code{val.rm}. -#' @param string.diag a vector with string values of the same length as \code{ncol(data)} (number of +#' @param string.diag A vector with string values of the same length as \code{ncol(data)} (number of #' correlated items) that can be used to display content in the diagonal cells #' where row and column item are identical (i.e. the "self-correlation"). By defauilt, #' this argument is \code{NULL} and the diagnal cells are empty. diff --git a/R/sjTabFrequencies.R b/R/sjTabFrequencies.R index 3694b92c..15cf4e9c 100755 --- a/R/sjTabFrequencies.R +++ b/R/sjTabFrequencies.R @@ -8,71 +8,72 @@ #' \item \code{\link{sjp.frq}} #' } #' -#' @param data variables which frequencies should be printed as table. Either use a single variable -#' (vector) or a data frame where each column represents a variable (see 'Examples'). -#' @param file destination file, if the output should be saved as file. +#' @param data A vector or a data frame, for which frequencies should be printed +#' as table. +#' @param file Destination file, if the output should be saved as file. #' If \code{NULL} (default), the output will be saved as temporary file and #' openend either in the IDE's viewer pane or the default web browser. -#' @param title table caption, as character vector. -#' @param value.labels character vector (or \code{list} of character vectors) +#' @param title Table caption, as character vector. +#' @param value.labels Character vector (or \code{list} of character vectors) #' with value labels of the supplied variables, which will be used #' to label variable values in the output. -#' @param altr.row.col logical, if \code{TRUE}, alternating rows are highlighted with a light gray +#' @param altr.row.col Logical, if \code{TRUE}, alternating rows are highlighted with a light gray #' background color. -#' @param string.val label for the very first table column containing the values (see +#' @param string.val Character label for the very first table column containing the values (see #' \code{value.labels}). -#' @param string.cnt label for the first table data column containing the counts. Default is \code{"N"}. -#' @param string.prc label for the second table data column containing the raw percentages. Default is \code{"raw \%"}. -#' @param string.vprc String label for the third data table column containing the valid percentages, i.e. the +#' @param string.cnt Character label for the first table data column containing the counts. Default is \code{"N"}. +#' @param string.prc Character label for the second table data column containing the raw percentages. Default is \code{"raw \%"}. +#' @param string.vprc Character label for the third data table column containing the valid percentages, i.e. the #' count percentage value exluding possible missing values. -#' @param string.cprc String label for the last table data column containing the cumulative percentages. -#' @param string.na String label for the last table data row containing missing values. -#' @param emph.md If \code{TRUE}, the table row indicating the median value will +#' @param string.cprc Character label for the last table data column containing the cumulative percentages. +#' @param string.na Character label for the last table data row containing missing values. +#' @param emph.md Logical, if \code{TRUE}, the table row indicating the median value will #' be emphasized. -#' @param emph.quart If \code{TRUE}, the table row indicating the lower and upper quartiles will +#' @param emph.quart Logical, if \code{TRUE}, the table row indicating the lower and upper quartiles will #' be emphasized. -#' @param skip.zero If \code{TRUE}, rows with only zero-values are not printed +#' @param skip.zero Logical, if \code{TRUE}, rows with only zero-values are not printed #' (e.g. if a variable has values or levels 1 to 8, and levels / values #' 4 to 6 have no counts, these values would not be printed in the table). #' Use \code{FALSE} to print also zero-values, or use \code{"auto"} (default) #' to detect whether it makes sense or not to print zero-values (e.g., a variable #' "age" with values from 10 to 100, where at least 25 percent of all possible values have no #' counts, zero-values would be skipped automatically). -#' @param show.summary If \code{TRUE} (default), a summary row with total and valid N as well as mean and +#' @param show.summary Logical, if \code{TRUE} (default), a summary row with total and valid N as well as mean and #' standard deviation is shown. -#' @param show.skew If \code{TRUE}, the variable's skewness is added to the summary. +#' @param show.skew Logical, if \code{TRUE}, the variable's skewness is added to the summary. #' The skewness is retrieved from the \code{\link[psych]{describe}}-function #' of the \pkg{psych}-package and indicated by a lower case Greek gamma. -#' @param show.kurtosis If \code{TRUE}, the variable's kurtosis is added to the summary. +#' @param show.kurtosis Logical, if \code{TRUE}, the variable's kurtosis is added to the summary. #' The kurtosis is retrieved from the \code{\link[psych]{describe}}-function #' of the \pkg{psych}-package and indicated by a lower case Greek omega. -#' @param ignore.strings If \code{TRUE} (default), character vectors / string variables will be removed from +#' @param ignore.strings Logical, if \code{TRUE} (default), character vectors / string variables will be removed from #' \code{data} before frequency tables are computed. -#' @param auto.grp.strings if \code{TRUE} (default), string values in character +#' @param auto.grp.strings Logical, if \code{TRUE} (default), string values in character #' vectors (string variables) are automatically grouped based on their #' similarity. The similarity is estimated with the \pkg{stringdist}-package. #' You can specify a distance-measure via \code{max.string.dist} argument. This argument only #' applies if \code{ignore.strings} is \code{FALSE}. -#' @param max.string.dist the allowed distance of string values in a character vector, which indicates +#' @param max.string.dist Numeric, the allowed distance of string values in a character vector, which indicates #' when two string values are merged because they are considered as close enough. #' See \code{auto.grp.strings}. -#' @param encoding string, indicating the charset encoding used for variable and +#' @param encoding String, indicating the charset encoding used for variable and #' value labels. Default is \code{NULL}, so encoding will be auto-detected #' depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for #' Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts). -#' @param CSS \code{\link{list}}-object with user-defined style-sheet-definitions, according to the +#' @param CSS A \code{\link{list}} with user-defined style-sheet-definitions, according to the #' \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, #' see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in #' \code{\link{sjt.frq}}. -#' @param use.viewer If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +#' @param use.viewer Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If #' \code{FALSE} or no viewer available, the HTML table is opened in a web browser. -#' @param no.output logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +#' @param no.output Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in #' the viewer pane and not even saved to file. This option is useful when the html output #' should be used in \code{knitr} documents. The html output can be accessed via the return #' value. -#' @param remove.spaces logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +#' @param remove.spaces Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string #' that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source #' may look less pretty, but it may help when exporting html-tables to office tools. +#' #' @return Invisibly returns #' \itemize{ #' \item the web page style sheet (\code{page.style}), @@ -86,12 +87,12 @@ #' @inheritParams sjp.grpfrq #' @inheritParams sjp.frq #' -#' @note The HTML tables can either be saved as file and manually opened (specify argument \code{file}) or +#' @note The HTML tables can either be saved as file and manually opened (use argument \code{file}) or #' they can be saved as temporary files and will be displayed in the RStudio Viewer pane (if working with RStudio) #' or opened with the default web browser. Displaying resp. opening a temporary file is the #' default behaviour (i.e. \code{file = NULL}). #' -#' @details \bold{How does the \code{CSS}-argument work?} +#' @details \bold{How do I use \code{CSS}-argument?} #' \cr \cr #' With the \code{CSS}-argument, the visual appearance of the tables #' can be modified. To get an overview of all style-sheet-classnames diff --git a/R/sjTabGrpmean.R b/R/sjTabGrpmean.R index 993a3f0f..df762e93 100755 --- a/R/sjTabGrpmean.R +++ b/R/sjTabGrpmean.R @@ -6,7 +6,7 @@ #' #' @seealso \code{\link{sjp.aov1}} #' -#' @param digits.summary amount of digits for summary statistics (Anova). +#' @param digits.summary Amount of digits for summary statistics (Anova). #' #' @inheritParams sjt.frq #' @inheritParams sjp.glmer diff --git a/R/sjTabItemAnalysis.R b/R/sjTabItemAnalysis.R index 4974b0a9..8c0600bd 100755 --- a/R/sjTabItemAnalysis.R +++ b/R/sjTabItemAnalysis.R @@ -1,9 +1,9 @@ #' @title Summary of item analysis of an item scale as HTML table #' @name sjt.itemanalysis -#' +#' #' @description This function performs an item analysis with certain statistics that are #' useful for scale or index development. The resulting tables are shown in the -#' viewer pane resp. webbrowser or can be saved as file. Following statistics are +#' viewer pane resp. webbrowser or can be saved as file. Following statistics are #' computed for each item of a data frame: #' \itemize{ #' \item percentage of missing values @@ -27,37 +27,37 @@ #' #' @seealso \href{http://www.strengejacke.de/sjPlot/sjt.itemanalysis/}{sjPlot manual: sjt.itemanalysis} #' -#' @param df data frame with items -#' @param factor.groups if not \code{NULL}, \code{df} will be splitted into sub-groups, -#' where the item analysis is carried out for each of these groups. Must be a vector of same +#' @param df A data frame with items. +#' @param factor.groups If not \code{NULL}, \code{df} will be splitted into sub-groups, +#' where the item analysis is carried out for each of these groups. Must be a vector of same #' length as \code{ncol(df)}, where each item in this vector represents the group number of #' the related columns of \code{df}. See 'Examples'. -#' @param factor.groups.titles titles for each factor group that will be used as table caption for each +#' @param factor.groups.titles Titles for each factor group that will be used as table caption for each #' component-table. Must be a character vector of same length as \code{length(unique(factor.groups))}. #' Default is \code{"auto"}, which means that each table has a standard caption \emph{Component x}. #' Use \code{NULL} to suppress table captions. -#' @param scale logical, if \code{TRUE}, the data frame's vectors will be scaled when calculating the -#' Cronbach's Alpha value (see \code{\link[sjstats]{reliab_test}}). Recommended, when +#' @param scale Logical, if \code{TRUE}, the data frame's vectors will be scaled when calculating the +#' Cronbach's Alpha value (see \code{\link[sjstats]{reliab_test}}). Recommended, when #' the variables have different measures / scales. -#' @param min.valid.rowmean minimum amount of valid values to compute row means for index scores. +#' @param min.valid.rowmean Minimum amount of valid values to compute row means for index scores. #' Default is 2, i.e. the return values \code{index.scores} and \code{df.index.scores} are #' computed for those items that have at least \code{min.valid.rowmean} per case (observation, or #' technically, row). See \code{mean_n} for details. -#' @param show.shapiro logical, if \code{TRUE}, a Shapiro-Wilk normality test is computed for each item. +#' @param show.shapiro Logical, if \code{TRUE}, a Shapiro-Wilk normality test is computed for each item. #' See \code{\link{shapiro.test}} for details. -#' @param show.kurtosis logical, if \code{TRUE}, the kurtosis for each item will also be shown (see \code{\link[psych]{kurtosi}} +#' @param show.kurtosis Logical, if \code{TRUE}, the kurtosis for each item will also be shown (see \code{\link[psych]{kurtosi}} #' and \code{\link[psych]{describe}} in the \code{psych}-package for more details. -#' @param show.corr.matrix logical, if \code{TRUE} (default), a correlation matrix of each component's +#' @param show.corr.matrix Logical, if \code{TRUE} (default), a correlation matrix of each component's #' index score is shown. Only applies if \code{factor.groups} is not \code{NULL} and \code{df} has #' more than one group. First, for each case (df's row), the sum of all variables (df's columns) is #' scaled (using the \code{\link{scale}}-function) and represents a "total score" for #' each component (a component is represented by each group of \code{factor.groups}). #' After that, each case (df's row) has a scales sum score for each component. #' Finally, a correlation of these "scale sum scores" is computed. -#' +#' #' @inheritParams sjt.frq #' @inheritParams sjt.df -#' +#' #' @return Invisibly returns #' \itemize{ #' \item \code{df.list}: List of data frames with the item analysis for each sub.group (or complete, if \code{factor.groups} was \code{NULL}) @@ -69,56 +69,56 @@ #' \item \code{knitr}: html-table of all complete output with inline-css for use with knitr #' \item \code{complete.page}: Complete html-output. #' } -#' If \code{factor.groups} was \code{NULL}, each list contains only one elment, since just one -#' table is printed for the complete scale indicated by \code{df}. If \code{factor.groups} +#' If \code{factor.groups = NULL}, each list contains only one elment, since just one +#' table is printed for the complete scale indicated by \code{df}. If \code{factor.groups} #' is a vector of group-index-values, the lists contain elements for each sub-group. -#' +#' #' @note \itemize{ #' \item The \emph{Shapiro-Wilk Normality Test} (see column \code{W(p)}) tests if an item has a distribution that is significantly different from normal. #' \item \emph{Item difficulty} should range between 0.2 and 0.8. Ideal value is \code{p+(1-p)/2} (which mostly is between 0.5 and 0.8). #' \item For \emph{item discrimination}, acceptable values are 0.20 or higher; the closer to 1.00 the better. See \code{\link[sjstats]{reliab_test}} for more details. #' \item In case the total \emph{Cronbach's Alpha} value is below the acceptable cut-off of 0.7 (mostly if an index has few items), the \emph{mean inter-item-correlation} is an alternative measure to indicate acceptability. Satisfactory range lies between 0.2 and 0.4. See also \code{\link[sjstats]{mic}}. #' } -#' +#' #' @note See 'Notes' in \code{\link{sjt.frq}}. -#' +#' #' @details See 'Details' in \code{\link{sjt.frq}}. -#' +#' #' @references \itemize{ #' \item Jorion N, Self B, James K, Schroeder L, DiBello L, Pellegrino J (2013) Classical Test Theory Analysis of the Dynamics Concept Inventory. (\href{https://www.academia.edu/4104752/Classical_Test_Theory_Analysis_of_the_Dynamics_Concept_Inventory}{web}) #' \item Briggs SR, Cheek JM (1986) The role of factor analysis in the development and evaluation of personality scales. Journal of Personality, 54(1), 106-148. \doi{10.1111/j.1467-6494.1986.tb00391.x} #' \item McLean S et al. (2013) Stigmatizing attitudes and beliefs about bulimia nervosa: Gender, age, education and income variability in a community sample. International Journal of Eating Disorders. \doi{10.1002/eat.22227} #' \item Trochim WMK (2008) Types of Reliability. (\href{http://www.socialresearchmethods.net/kb/reltypes.php}{web}) #' } -#' +#' #' @examples #' # Data from the EUROFAMCARE sample dataset #' library(sjmisc) #' data(efc) -#' +#' #' # retrieve variable and value labels #' varlabs <- get_label(efc) -#' +#' #' # recveive first item of COPE-index scale #' start <- which(colnames(efc) == "c82cop1") #' # recveive last item of COPE-index scale #' end <- which(colnames(efc) == "c90cop9") -#' +#' #' # create data frame with COPE-index scale #' mydf <- data.frame(efc[, c(start:end)]) #' colnames(mydf) <- varlabs[c(start:end)] -#' +#' #' \dontrun{ #' sjt.itemanalysis(mydf) -#' +#' #' # auto-detection of labels #' sjt.itemanalysis(efc[, c(start:end)]) -#' +#' #' # Compute PCA on Cope-Index, and perform a #' # item analysis for each extracted factor. #' factor.groups <- sjt.pca(mydf, no.output = TRUE)$factor.index #' sjt.itemanalysis(mydf, factor.groups)} -#' +#' #' @importFrom psych describe #' @importFrom stats shapiro.test #' @importFrom sjstats reliab_test mean_n mic cronb @@ -253,9 +253,9 @@ sjt.itemanalysis <- function(df, # ----------------------------------- # create dummy data frame # ----------------------------------- - df.dummy <- data.frame(cbind(sprintf("%.2f %%", missings.prz), - round(dstat$mean, 2), - round(dstat$sd, 2), + df.dummy <- data.frame(cbind(sprintf("%.2f %%", missings.prz), + round(dstat$mean, 2), + round(dstat$sd, 2), round(dstat$skew, 2))) df.colnames <- c("Missings", "Mean", "SD", "Skew") # ----------------------------------- @@ -280,7 +280,7 @@ sjt.itemanalysis <- function(df, # set names of data frame # ----------------------------------- colnames(df.dummy) <- df.colnames - rownames(df.dummy) <- df.names + rownames(df.dummy) <- df.names # ----------------------------------- # add results to return list # ----------------------------------- @@ -316,17 +316,17 @@ sjt.itemanalysis <- function(df, # check if we have titles for each component-table if (!is.null(factor.groups.titles)) dftitle <- factor.groups.titles[i] # get html-table from data frame - html <- sjt.df(df.ia[[i]], - describe = FALSE, - no.output = TRUE, - title = dftitle, - sort.asc = sort.asc, - sort.col = sort.col, - altr.row.col = altr.row.col, - CSS = CSS, - encoding = encoding, + html <- sjt.df(df.ia[[i]], + describe = FALSE, + no.output = TRUE, + title = dftitle, + sort.asc = sort.asc, + sort.col = sort.col, + altr.row.col = altr.row.col, + CSS = CSS, + encoding = encoding, hide.progress = TRUE, - show.cmmn.row = TRUE, + show.cmmn.row = TRUE, string.cmmn = sprintf("Mean inter-item-correlation=%.3f · Cronbach's α=%.3f", mic.total[[i]], cronbach.total[[i]])) # add to complete html-page complete.page <- paste0(complete.page, html$knitr) @@ -340,18 +340,18 @@ sjt.itemanalysis <- function(df, # check if we have enough components if (length(df.comcor) > 1) { # copy all component correlation values to a data frame - df.cc <- data.frame(matrix(unlist(df.comcor), - nrow = nrow(df), + df.cc <- data.frame(matrix(unlist(df.comcor), + nrow = nrow(df), byrow = FALSE)) # give proper columm names colnames(df.cc) <- sprintf("Component %i", seq_len(ncol(df.cc))) # compute correlation table, store html result html <- sjt.corr(df.cc, - na.deletion = "listwise", - p.numeric = TRUE, - triangle = "lower", - string.diag = sprintf("α=%.3f", unlist(cronbach.total)), - encoding = encoding, + na.deletion = "listwise", + p.numeric = TRUE, + triangle = "lower", + string.diag = sprintf("α=%.3f", unlist(cronbach.total)), + encoding = encoding, no.output = TRUE) # add to html that is printed complete.page <- paste0(complete.page, html$knitr) @@ -374,8 +374,8 @@ sjt.itemanalysis <- function(df, # ------------------------------------- # check if html-content should be printed # ------------------------------------- - #out.html.table(no.output, file, knitr, complete.page, use.viewer) - + #out.html.table(no.output, file, knitr, complete.page, use.viewer) + structure( class = c("sjTable", "sjtitemanalysis"), list( diff --git a/R/sjTabLinReg.R b/R/sjTabLinReg.R index 93a7023e..e99fafba 100755 --- a/R/sjTabLinReg.R +++ b/R/sjTabLinReg.R @@ -10,98 +10,98 @@ #' #' @seealso \href{http://strengejacke.de/sjPlot/sjt.lm/}{sjPlot manual: sjt.lm} #' -#' @param ... one or more fitted linear (mixed) models. -#' @param pred.labels character vector with labels of predictor variables. +#' @param ... One or more fitted linear (mixed) models. +#' @param pred.labels Character vector with labels of predictor variables. #' If not \code{NULL}, \code{pred.labels} will be used in the first #' table column with the predictors' names. If \code{NULL}, variable #' labels are set based on label attributes (see \code{\link[sjmisc]{get_label}}). #' If \code{pred.labels = ""}, column names (vector names) are used #' as predictor labels. See 'Examples'. -#' @param depvar.labels character vector with labels of dependent +#' @param depvar.labels Character vector with labels of dependent #' variables of all fitted models. See 'Examples'. -#' @param string.pred character vector,used as headline for the predictor column. +#' @param string.pred Character vector,used as headline for the predictor column. #' Default is \code{"Predictors"}. -#' @param string.dv character vector, used as headline for the +#' @param string.dv Character vector, used as headline for the #' dependent variable columns. Default is \code{"Dependent Variables"}. -#' @param show.header logical, if \code{TRUE}, the header strings \code{string.pred} +#' @param show.header Logical, if \code{TRUE}, the header strings \code{string.pred} #' and \code{string.dv} are shown. By default, they're hidden. -#' @param string.interc character vector, used as headline for the Intercept row. +#' @param string.interc Character vector, used as headline for the Intercept row. #' Default is \code{"Intercept"}. #' @param string.obs character vector, used in the summary row for the count of observation #' (cases). Default is \code{"Observations"}. -#' @param string.est character vector, used for the column heading of estimates. -#' @param string.std character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}. -#' @param string.ci character vector, used for the column heading of confidence interval values. Default is \code{"CI"}. -#' @param string.se character vector, used for the column heading of standard error values. Default is \code{"std. Error"}. -#' @param string.p character vector, used for the column heading of p values. Default is \code{"p"}. -#' @param show.est logical, if \code{TRUE} (default), the estimates are printed. -#' @param show.ci logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use +#' @param string.est Character vector, used for the column heading of estimates. +#' @param string.std Character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}. +#' @param string.ci Character vector, used for the column heading of confidence interval values. Default is \code{"CI"}. +#' @param string.se Character vector, used for the column heading of standard error values. Default is \code{"std. Error"}. +#' @param string.p Character vector, used for the column heading of p values. Default is \code{"p"}. +#' @param show.est Logical, if \code{TRUE} (default), the estimates are printed. +#' @param show.ci Logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use #' \code{FALSE} to omit the CI in the table. -#' @param show.std indicates whether standardized beta-coefficients should +#' @param show.std Indicates whether standardized beta-coefficients should #' also printed, and if yes, which type of standardization is done. #' See 'Details'. -#' @param show.se logical, if \code{TRUE}, the standard errors are also printed. +#' @param show.se Logical, if \code{TRUE}, the standard errors are also printed. #' Default is \code{FALSE}. -#' @param ci.hyphen character vector, indicating the hyphen for confidence interval range. +#' @param ci.hyphen Character vector, indicating the hyphen for confidence interval range. #' May be an HTML entity. See 'Examples'. #' @param minus.sign string, indicating the minus sign for negative numbers. #' May be an HTML entity. See 'Examples'. -#' @param digits.est amount of decimals for estimates -#' @param digits.p amount of decimals for p-values -#' @param digits.ci amount of decimals for confidence intervals -#' @param digits.se amount of decimals for standard error -#' @param digits.std amount of decimals for standardized beta -#' @param digits.summary amount of decimals for values in model summary -#' @param emph.p logical, if \code{TRUE}, significant p-values are shown bold faced. +#' @param digits.est Amount of decimals for estimates +#' @param digits.p Amount of decimals for p-values +#' @param digits.ci Amount of decimals for confidence intervals +#' @param digits.se Amount of decimals for standard error +#' @param digits.std Amount of decimals for standardized beta +#' @param digits.summary Amount of decimals for values in model summary +#' @param emph.p Logical, if \code{TRUE}, significant p-values are shown bold faced. #' @param p.zero logical, if \code{TRUE}, p-values have a leading 0 before the #' period (e.g. \emph{0.002}), else p-values start with a period and #' without a zero (e.g. \emph{.002}). -#' @param robust logical, if \code{TRUE}, robust standard errors and confidence +#' @param robust Logical, if \code{TRUE}, robust standard errors and confidence #' intervals will be reported. Computation of robust standard errors is #' based on the \code{\link[sjstats]{robust}}-function in the #' \pkg{sjstats}-package. -#' @param separate.ci.col if \code{TRUE}, the CI values are shown in a separate table column. +#' @param separate.ci.col Logical, if \code{TRUE}, the CI values are shown in a separate table column. #' Default is \code{FALSE}. -#' @param newline.ci logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break +#' @param newline.ci Logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break #' between estimate and CI values. If \code{FALSE}, CI values are printed in the same #' line as estimate values. -#' @param group.pred logical, if \code{TRUE} (default), automatically groups table rows with +#' @param group.pred Logical, if \code{TRUE} (default), automatically groups table rows with #' factor levels of same factor, i.e. predictors of type \code{\link{factor}} will #' be grouped, if the factor has more than two levels. Grouping means that a separate headline #' row is inserted to the table just before the predictor values. -#' @param show.col.header logical, if \code{TRUE} (default), the table data columns have a headline with +#' @param show.col.header Logical, if \code{TRUE} (default), the table data columns have a headline with #' abbreviations for estimates, std. beta-values, confidence interval and p-values. -#' @param show.r2 logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed +#' @param show.r2 Logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed #' in the model summary. For linear mixed models, the R2 and Omega-squared values are printed #' (see \code{\link[sjstats]{r2}} for details). -#' @param show.icc logical, if \code{TRUE}, the intra-class-correlation for each +#' @param show.icc Logical, if \code{TRUE}, the intra-class-correlation for each #' model is printed in the model summary. Only applies to mixed models. -#' @param show.re.var logical, if \code{TRUE}, the variance parameters for the random +#' @param show.re.var Logical, if \code{TRUE}, the variance parameters for the random #' effects for each model are printed in the model summary. Only applies to mixed models. #' For details output, see 'Note' in \code{\link[sjstats]{icc}}. -#' @param show.fstat If \code{TRUE}, the F-statistics for each model is printed +#' @param show.fstat Logical, if \code{TRUE}, the F-statistics for each model is printed #' in the model summary. Default is \code{FALSE}. This argument does not apply to #' \code{\link{sjt.lmer}}. -#' @param show.aic logical, if \code{TRUE}, the AIC value for each model is printed +#' @param show.aic Logical, if \code{TRUE}, the AIC value for each model is printed #' in the model summary. Default is \code{FALSE}. -#' @param show.aicc logical, if \code{TRUE}, the second-order AIC value for each model +#' @param show.aicc Logical, if \code{TRUE}, the second-order AIC value for each model #' is printed in the model summary. Default is \code{FALSE}. -#' @param show.dev logical, if \code{TRUE}, the deviance for each model +#' @param show.dev Logical, if \code{TRUE}, the deviance for each model #' is printed in the model summary. -#' @param remove.estimates numeric vector with indices (order equals to row index of \code{coef(fit)}) +#' @param remove.estimates Numeric vector with indices (order equals to row index of \code{coef(fit)}) #' or character vector with coefficient names that indicate which estimates should be removed #' from the table output. The first estimate is the intercept, followed by the model predictors. #' \emph{The intercept cannot be removed from the table output!} \code{remove.estimates = c(2:4)} #' would remove the 2nd to the 4th estimate (1st to 3rd predictor after intercept) from the output. #' \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default #' is \code{NULL}, i.e. all estimates are printed. -#' @param cell.spacing numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is +#' @param cell.spacing Numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is #' suitable for viewing the table. Decrease this value (0.05 to 0.1) if you want to import the table #' into Office documents. This is a convenient argument for the \code{CSS} argument for changing #' cell spacing, which would be: \code{CSS = list(css.thead = "padding:0.2cm;", css.tdata = "padding:0.2cm;")}. -#' @param cell.gpr.indent indent for table rows with grouped factor predictors. Only applies +#' @param cell.gpr.indent Indent for table rows with grouped factor predictors. Only applies #' if \code{group.pred = TRUE}. -#' @param sep.column logical, if \code{TRUE}, an empty table column is added after +#' @param sep.column Logical, if \code{TRUE}, an empty table column is added after #' each model column, to add margins between model columns. By default, this #' column will be added to the output; however, when copying tables to #' office applications, it might be helpful not to add this separator column @@ -1345,7 +1345,7 @@ sjt.lm <- function(..., #' efc$grp = as.factor(efc$e15relat) #' levels(x = efc$grp) <- get_labels(efc$e15relat) #' efc$care.level <- sjmisc::rec(efc$n4pstu, -#' rec = "0=0;1=1;2=2;3:4=3", +#' recodes = "0=0;1=1;2=2;3:4=3", #' as.num = FALSE) #' levels(x = efc$care.level) <- c("none", "I", "II", "III") #' diff --git a/R/sjTabMannWhitney.R b/R/sjTabMannWhitney.R index 8956f16a..51ccd56d 100755 --- a/R/sjTabMannWhitney.R +++ b/R/sjTabMannWhitney.R @@ -5,7 +5,7 @@ #' from the Mann-Whitney-test are obtained by the \code{\link[sjstats]{mwu}} #' function from the \pkg{sjstats}-package. #' -#' @param x results of a Mann-Whitney-U test, provided by \code{\link[sjstats]{mwu}}. See 'Examples'. +#' @param x Results of a Mann-Whitney-U test, provided by \code{\link[sjstats]{mwu}}. See 'Examples'. #' #' @inheritParams sjt.frq #' @inheritParams sjt.df diff --git a/R/sjTabOdds.R b/R/sjTabOdds.R index 696ca8ea..e0dc9033 100755 --- a/R/sjTabOdds.R +++ b/R/sjTabOdds.R @@ -5,28 +5,28 @@ #' as HTML table, or saves them as file. The fitted models may have different predictors, #' e.g. when comparing different stepwise fitted models. #' -#' @param ... one or more fitted generalized linear (mixed) models. -#' @param exp.coef logical, if \code{TRUE} (default), regression coefficients and +#' @param ... One or more fitted generalized linear (mixed) models. +#' @param exp.coef Logical, if \code{TRUE} (default), regression coefficients and #' confidence intervals are exponentiated. Use \code{FALSE} for #' non-exponentiated coefficients (log-odds) as provided by #' the \code{\link{summary}} function. -#' @param show.r2 logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed +#' @param show.r2 Logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed #' in the model summary. R2cs is the Cox-Snell-pseudo R-squared value, R2n is Nagelkerke's #' pseudo R-squared value and \code{D} is Tjur's Coefficient of Discrimination #' (see \code{\link[sjstats]{cod}}). -#' @param show.loglik logical, if \code{TRUE}, the Log-Likelihood for each model is printed +#' @param show.loglik Logical, if \code{TRUE}, the Log-Likelihood for each model is printed #' in the model summary. Default is \code{FALSE}. -#' @param show.chi2 logical, if \code{TRUE}, the p-value of the chi-squared value for each +#' @param show.chi2 Logical, if \code{TRUE}, the p-value of the chi-squared value for each #' model's residual deviance against the null deviance is printed #' in the model summary. Default is \code{FALSE}. A well-fitting model #' with predictors should significantly differ from the null-model #' (without predictors), thus, a p-value less than 0.05 indicates a #' good model-fit. -#' @param show.hoslem logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is +#' @param show.hoslem Logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is #' performed. A well-fitting model shows no significant difference between #' the model and the observed data, i.e. the reported p-values should be #' greater than 0.05. -#' @param show.family logical, if \code{TRUE}, the family object and link function for each fitted model +#' @param show.family Logical, if \code{TRUE}, the family object and link function for each fitted model #' are printed. Can be used in case you want to compare models with different link functions #' and same predictors and response, to decide which model fits best. See \code{\link{family}} #' for more details. It is recommended to inspect the model \code{\link{AIC}} (see \code{show.aic}) to get a diff --git a/R/sjTabPCA.R b/R/sjTabPCA.R index 05f84903..d489a9e6 100755 --- a/R/sjTabPCA.R +++ b/R/sjTabPCA.R @@ -1,49 +1,49 @@ #' @title Summary of principal component analysis as HTML table #' @name sjt.pca -#' -#' @description Performes a principle component analysis on a data frame or matrix -#' (with varimax rotation) and displays the factor solution as HTML -#' table, or saves them as file. \cr \cr In case a data frame is used as +#' +#' @description Performes a principle component analysis on a data frame or matrix +#' (with varimax or oblimin rotation) and displays the factor solution as HTML +#' table, or saves them as file. \cr \cr In case a data frame is used as #' parameter, the Cronbach's Alpha value for each factor scale will be calculated, #' i.e. all variables with the highest loading for a factor are taken for the #' reliability test. The result is an alpha value for each factor dimension. -#' +#' #' @seealso \itemize{ #' \item \href{http://www.strengejacke.de/sjPlot/sjt.pca/}{sjPlot manual: sjt.pca} #' \item \code{\link{sjp.pca}} #' } -#' -#' @param data \code{data.frame} that should be used to compute a PCA, or a \code{\link{prcomp}} object. -#' @param rotation rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation +#' +#' @param data A data frame that should be used to compute a PCA, or a \code{\link{prcomp}} object. +#' @param rotation Rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation #' or \code{"oblimin"} for oblique transformation. -#' @param nmbr.fctr number of factors used for calculating the varimax +#' @param nmbr.fctr Number of factors used for calculating the varimax #' rotation. By default, this value is \code{NULL} and the amount of factors is #' calculated according to the Kaiser-criteria. -#' @param fctr.load.tlrn specifies the minimum difference a variable needs to have between +#' @param fctr.load.tlrn Specifies the minimum difference a variable needs to have between #' factor loadings (components) in order to indicate a clear loading on just one factor and not -#' diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading +#' diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading #' on 3 possible factors can not be clearly assigned to just one factor and thus would be removed #' from the principal component analysis. By default, the minimum difference of loading values #' between the highest and 2nd highest factor should be 0.1 -#' @param show.cronb logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, +#' @param show.cronb Logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, #' i.e. all variables with the highest loading for a factor are taken for the #' reliability test. The result is an alpha value for each factor dimension. #' Only applies when \code{data} is a data frame and no \code{\link{prcomp}} object. -#' @param show.msa logical, if \code{TRUE}, shows an additional column with the measure of sampling adequacy according +#' @param show.msa Logical, if \code{TRUE}, shows an additional column with the measure of sampling adequacy according #' dor each component. -#' @param show.var logical, if \code{TRUE}, the proportions of variances for each component as well as cumulative +#' @param show.var Logical, if \code{TRUE}, the proportions of variances for each component as well as cumulative #' variance are shown in the table footer. -#' @param string.pov string for the table row that contains the proportions of variances. By default, +#' @param string.pov String for the table row that contains the proportions of variances. By default, #' \emph{"Proportion of Variance"} will be used. -#' @param string.cpov string for the table row that contains the cumulative variances. By default, +#' @param string.cpov String for the table row that contains the cumulative variances. By default, #' \emph{"Cumulative Proportion"} will be used. -#' +#' #' @inheritParams sjt.frq #' @inheritParams sjt.xtab #' @inheritParams sjt.df #' @inheritParams sjp.grpfrq #' @inheritParams sjt.corr -#' +#' #' @return Invisibly returns #' \itemize{ #' \item the web page style sheet (\code{page.style}), @@ -56,35 +56,23 @@ #' for further use. #' #' @note See 'Notes' in \code{\link{sjt.frq}}. -#' This PCA uses the \code{\link{prcomp}} function and -#' the \code{\link{varimax}} rotation. -#' +#' #' @details See 'Details' in \code{\link{sjt.frq}}. -#' -#' +#' +#' #' @examples #' \dontrun{ #' # Data from the EUROFAMCARE sample dataset #' library(sjmisc) #' data(efc) -#' -#' # retrieve variable and value labels -#' varlabs <- get_label(efc) -#' +#' #' # recveive first item of COPE-index scale #' start <- which(colnames(efc) == "c82cop1") #' # recveive last item of COPE-index scale #' end <- which(colnames(efc) == "c90cop9") -#' -#' # create data frame with COPE-index scale -#' mydf <- as.data.frame(efc[, c(start:end)]) -#' colnames(mydf) <- varlabs[c(start:end)] -#' -#' sjt.pca(mydf) -#' #' # auto-detection of labels #' sjt.pca(efc[, c(start:end)])} -#' +#' #' @importFrom psych KMO #' @importFrom stats prcomp #' @export @@ -129,9 +117,9 @@ sjt.pca <- function(data, show.msa <- FALSE } else { pcadata <- stats::prcomp( - stats::na.omit(data), - retx = TRUE, - center = TRUE, + stats::na.omit(data), + retx = TRUE, + center = TRUE, scale. = TRUE ) dataframeparam <- TRUE @@ -151,12 +139,12 @@ sjt.pca <- function(data, tag.tdata <- "tdata" tag.centeralign <- "centeralign" tag.rightalign <- "rightalign" - tag.cronbach <- "cronbach" - tag.msa <- "msa" - tag.pov <- "pov" + tag.cronbach <- "cronbach" + tag.msa <- "msa" + tag.pov <- "pov" tag.cpov <- "cpov" tag.rotation <- "rotation" - tag.kmo <- "kmo" + tag.kmo <- "kmo" tag.arc <- "arc" tag.minval <- "minval" tag.removable <- "removable" @@ -168,12 +156,12 @@ sjt.pca <- function(data, css.tdata <- "padding:0.2cm;" css.centeralign <- "text-align:center;" css.rightalign <- "text-align:right;" - css.cronbach <- "font-style:italic;" - css.msa <- "font-style:italic; color:#666666;" - css.kmo <- "font-style:italic; border-bottom:double;" - css.rotation <- "font-style:italic; font-size:0.9em;" - css.pov <- "font-style:italic; border-top:1px solid;" - css.cpov <- "font-style:italic;" + css.cronbach <- "font-style:italic;" + css.msa <- "font-style:italic; color:#666666;" + css.kmo <- "font-style:italic; border-bottom:double;" + css.rotation <- "font-style:italic; font-size:0.9em;" + css.pov <- "font-style:italic; border-top:1px solid;" + css.cpov <- "font-style:italic;" css.minval <- "color:#cccccc;" css.arc <- "background-color:#eaeaea;" css.removable <- "background-color:#eacccc;" @@ -210,12 +198,12 @@ sjt.pca <- function(data, # set page style # ------------------------ page.style <- sprintf("", - tag.table, css.table, tag.caption, css.caption, tag.thead, css.thead, + tag.table, css.table, tag.caption, css.caption, tag.thead, css.thead, tag.tdata, css.tdata, tag.cronbach, css.cronbach, tag.minval, css.minval, tag.removable, css.removable, tag.firsttablerow, css.firsttablerow, tag.firsttablecol, css.firsttablecol, tag.centeralign, css.centeralign, tag.rightalign, css.rightalign, tag.rotation, css.rotation, - tag.msa, css.msa, tag.kmo, css.kmo, tag.pov, css.pov, tag.cpov, + tag.msa, css.msa, tag.kmo, css.kmo, tag.pov, css.pov, tag.cpov, css.cpov, tag.arc, css.arc) # ------------------------ # start content @@ -236,13 +224,13 @@ sjt.pca <- function(data, # -------------------------------------------------------- # check for predefined number of factors if (!is.null(nmbr.fctr) && is.numeric(nmbr.fctr)) pcadata.kaiser <- nmbr.fctr - + # rotate matrix if (rotation == "varimax") pcadata.rotate <- varimaxrota(pcadata, pcadata.kaiser) else if (rotation == "oblimin") pcadata.rotate <- psych::principal(r = data, nfactors = pcadata.kaiser, rotate = "oblimin") - + # create data frame with factor loadings df <- as.data.frame(pcadata.rotate$loadings[, seq_len(ncol(pcadata.rotate$loadings))]) # ---------------------------- @@ -289,7 +277,7 @@ sjt.pca <- function(data, # -------------------------------------------------------- # this function retrieves a list with the column index ("factor" index) # where each case of the data frame has its highedt factor loading. - # So we know to which "group" (factor dimension) each case of the + # So we know to which "group" (factor dimension) each case of the # data frame belongs to according to the pca results # -------------------------------------------------------- getItemLoadings <- function(dataframe) { @@ -395,22 +383,22 @@ sjt.pca <- function(data, # write tr-tag with class-attributes page.content <- paste0(page.content, " \n") # print first table cell - page.content <- paste0(page.content, sprintf(" %s\n", + page.content <- paste0(page.content, sprintf(" %s\n", arcstring, rowcss, var.labels[i])) # iterate all columns for (j in seq_len(ncol(df))) { # start table column colcss <- sprintf(" class=\"tdata centeralign%s%s\"", arcstring, rowcss) - if (maxdf[[i]] != max(abs(df[i, j]))) + if (maxdf[[i]] != max(abs(df[i, j]))) colcss <- sprintf(" class=\"tdata centeralign minval%s%s\"", arcstring, rowcss) - page.content <- paste0(page.content, sprintf(" %.*f\n", + page.content <- paste0(page.content, sprintf(" %.*f\n", colcss, digits, df[i, j])) } # check if msa column should be shown - if (show.msa) page.content <- paste0(page.content, sprintf(" %.*f\n", - arcstring, - rowcss, - digits, + if (show.msa) page.content <- paste0(page.content, sprintf(" %.*f\n", + arcstring, + rowcss, + digits, kmo$MSAi[[i]])) # close row page.content <- paste0(page.content, " \n") @@ -425,8 +413,8 @@ sjt.pca <- function(data, page.content <- paste0(page.content, sprintf(" %s\n", string.pov)) # iterate alpha-values for (i in 1:length(pov)) { - page.content <- paste0(page.content, sprintf(" %.*f %%\n", - digits, + page.content <- paste0(page.content, sprintf(" %.*f %%\n", + digits, 100 * pov[i])) } # check if msa column should be shown @@ -436,8 +424,8 @@ sjt.pca <- function(data, page.content <- paste0(page.content, sprintf(" %s\n", string.cpov)) # iterate alpha-values for (i in 1:length(pov)) { - page.content <- paste0(page.content, sprintf(" %.*f %%\n", - digits, + page.content <- paste0(page.content, sprintf(" %.*f %%\n", + digits, 100 * cpov[i])) } # check if msa column should be shown @@ -454,8 +442,8 @@ sjt.pca <- function(data, page.content <- paste0(page.content, " Cronbach's α\n") # iterate alpha-values for (i in seq_len(length(alphaValues))) { - page.content <- paste0(page.content, sprintf(" %.*f\n", - digits, + page.content <- paste0(page.content, sprintf(" %.*f\n", + digits, alphaValues[i])) } # check if msa column should be shown @@ -523,10 +511,10 @@ sjt.pca <- function(data, knitr <- gsub(tag.cpov, css.cpov, knitr, fixed = TRUE, useBytes = TRUE) knitr <- gsub(tag.kmo, css.kmo, knitr, fixed = TRUE, useBytes = TRUE) knitr <- gsub(tag.rotation, css.rotation, knitr, fixed = TRUE, useBytes = TRUE) - knitr <- gsub(tag.minval, css.minval, knitr, fixed = TRUE, useBytes = TRUE) - knitr <- gsub(tag.removable, css.removable, knitr, fixed = TRUE, useBytes = TRUE) - knitr <- gsub(tag.firsttablerow, css.firsttablerow, knitr, fixed = TRUE, useBytes = TRUE) - knitr <- gsub(tag.firsttablecol, css.firsttablecol, knitr, fixed = TRUE, useBytes = TRUE) + knitr <- gsub(tag.minval, css.minval, knitr, fixed = TRUE, useBytes = TRUE) + knitr <- gsub(tag.removable, css.removable, knitr, fixed = TRUE, useBytes = TRUE) + knitr <- gsub(tag.firsttablerow, css.firsttablerow, knitr, fixed = TRUE, useBytes = TRUE) + knitr <- gsub(tag.firsttablecol, css.firsttablecol, knitr, fixed = TRUE, useBytes = TRUE) # ------------------------------------- # remove spaces? # ------------------------------------- diff --git a/R/sjTabPropTable.R b/R/sjTabPropTable.R index cf6dbbe1..ea127558 100755 --- a/R/sjTabPropTable.R +++ b/R/sjTabPropTable.R @@ -8,17 +8,17 @@ #' \item \code{\link{sjp.xtab}} #' } #' -#' @param var.row variable that should be displayed in the table rows. -#' @param var.col variable that should be displayed in the table columns. -#' @param var.labels character vector with variable names, which will be used +#' @param var.row Variable that should be displayed in the table rows. +#' @param var.col Cariable that should be displayed in the table columns. +#' @param var.labels Character vector with variable names, which will be used #' to label variables in the output. -#' @param string.total label for the total column / row header -#' @param show.cell.prc logical, if \code{TRUE}, cell percentage values are shown -#' @param show.row.prc logical, if \code{TRUE}, row percentage values are shown -#' @param show.col.prc logical, if \code{TRUE}, column percentage values are shown -#' @param show.obs logical, if \code{TRUE}, observed values are shown -#' @param show.exp logical, if \code{TRUE}, expected values are also shown -#' @param show.summary logical, if \code{TRUE}, a summary row with +#' @param string.total Character label for the total column / row header +#' @param show.cell.prc Logical, if \code{TRUE}, cell percentage values are shown +#' @param show.row.prc Logical, if \code{TRUE}, row percentage values are shown +#' @param show.col.prc Logical, if \code{TRUE}, column percentage values are shown +#' @param show.obs Logical, if \code{TRUE}, observed values are shown +#' @param show.exp Logical, if \code{TRUE}, expected values are also shown +#' @param show.summary Logical, if \code{TRUE}, a summary row with #' chi-squared statistics, degrees of freedom and Cramer's V or Phi #' coefficient and p-value for the chi-squared statistics. #' @param tdcol.n Color for highlighting count (observed) values in table cells. Default is black. @@ -26,9 +26,9 @@ #' @param tdcol.cell Color for highlighting cell percentage values in table cells. Default is red. #' @param tdcol.row Color for highlighting row percentage values in table cells. Default is blue. #' @param tdcol.col Color for highlighting column percentage values in table cells. Default is green. -#' @param emph.total logical, if \code{TRUE}, the total column and row will be emphasized with a +#' @param emph.total Logical, if \code{TRUE}, the total column and row will be emphasized with a #' different background color. See \code{emph.color}. -#' @param emph.color logical, if \code{emph.total = TRUE}, this color value will be used +#' @param emph.color Logical, if \code{emph.total = TRUE}, this color value will be used #' for painting the background of the total column and row. Default is a light grey. #' @param prc.sign The percentage sign that is printed in the table cells, in HTML-format. #' Default is \code{" \%"}, hence the percentage sign has a non-breaking-space after diff --git a/R/sjTabSPSS.R b/R/sjTabSPSS.R index cdff9a0f..8594aba4 100755 --- a/R/sjTabSPSS.R +++ b/R/sjTabSPSS.R @@ -3,31 +3,30 @@ #' #' @description Save (or show) content of an imported SPSS, SAS or Stata data file, #' or any similar labelled \code{data.frame}, as HTML table. -#' Similar to the SPSS variable view. This quick overview shows -#' variable ID numner, name, label, type and associated -#' value labels. The result can be considered as "codeplan" of -#' the data frame. +#' This quick overview shows variable ID number, name, label, +#' type and associated value labels. The result can be +#' considered as "codeplan" of the data frame. #' #' @seealso \itemize{ #' \item \href{http://www.strengejacke.de/sjPlot/datainit/}{sjPlot manual: data initialization} #' \item \href{http://www.strengejacke.de/sjPlot/view_spss/}{sjPlot manual: inspecting (SPSS imported) data frames} #' } #' -#' @param x \code{data.frame}, imported by \code{\link[sjmisc]{read_spss}}, +#' @param x A (labelled) data frame, imported by \code{\link[sjmisc]{read_spss}}, #' \code{\link[sjmisc]{read_sas}} or \code{\link[sjmisc]{read_stata}} function, #' or any similar labelled data frame (see \code{\link[sjmisc]{set_label}} #' and \code{\link[sjmisc]{set_labels}}). -#' @param show.id logical, if \code{TRUE} (default), the variable ID is shown in the first column. -#' @param show.values logical, if \code{TRUE} (default), the variable values are shown as additional column. -#' @param show.labels logical, if \code{TRUE} (default), the value labels are shown as additional column. -#' @param show.frq logical, if \code{TRUE}, an additional column with frequencies for each variable is shown. -#' @param show.prc logical, if \code{TRUE}, an additional column with percentage of frequencies for each variable is shown. -#' @param show.wtd.frq logical, if \code{TRUE}, an additional column with weighted +#' @param show.id Logical, if \code{TRUE} (default), the variable ID is shown in the first column. +#' @param show.values Logical, if \code{TRUE} (default), the variable values are shown as additional column. +#' @param show.labels Logical, if \code{TRUE} (default), the value labels are shown as additional column. +#' @param show.frq Logical, if \code{TRUE}, an additional column with frequencies for each variable is shown. +#' @param show.prc Logical, if \code{TRUE}, an additional column with percentage of frequencies for each variable is shown. +#' @param show.wtd.frq Logical, if \code{TRUE}, an additional column with weighted #' frequencies for each variable is shown. Weights strem from \code{weight.by}. -#' @param show.wtd.prc logical, if \code{TRUE}, an additional column with weighted +#' @param show.wtd.prc Logical, if \code{TRUE}, an additional column with weighted #' percentage of frequencies for each variable is shown. #' Weights strem from \code{weight.by}. -#' @param sort.by.name logical, if \code{TRUE}, rows are sorted according to the variable +#' @param sort.by.name Logical, if \code{TRUE}, rows are sorted according to the variable #' names. By default, rows (variables) are ordered according to their #' order in the data frame. #' @@ -54,7 +53,7 @@ #' # init dataset #' library(sjmisc) #' data(efc) -#' +#' #' # view variables #' view_df(efc) #' @@ -64,9 +63,7 @@ #' # view variables including variable typed, orderd by name #' view_df(efc, sort.by.name = TRUE, show.type = TRUE) #' -#' # ---------------------------------------------------------------- #' # User defined style sheet -#' # ---------------------------------------------------------------- #' view_df(efc, #' CSS = list(css.table = "border: 2px solid;", #' css.tdata = "border: 1px solid;", @@ -98,19 +95,19 @@ view_df <- function(x, remove.spaces = TRUE) { # check encoding encoding <- get.encoding(encoding, x) - + # make data frame of single variable, so we have # unique handling for the data if (!is.data.frame(x)) stop("Parameter needs to be a data frame!", call. = FALSE) - + # retrieve value and variable labels df.var <- sjmisc::get_label(x) df.val <- sjmisc::get_labels(x) - + # get row count and ID's colcnt <- ncol(x) id <- seq_len(colcnt) - + # Order data set if requested if (sort.by.name) id <- id[order(colnames(x))] @@ -127,7 +124,7 @@ view_df <- function(x, css.tdata <- "padding:0.2cm; text-align:left; vertical-align:top;" css.arc <- "background-color:#eaeaea" css.caption <- "font-weight: bold; text-align:left;" - + # check user defined style sheets if (!is.null(CSS)) { if (!is.null(CSS[['css.table']])) css.table <- ifelse(substring(CSS[['css.table']], 1, 1) == '+', paste0(css.table, substring(CSS[['css.table']], 2)), CSS[['css.table']]) @@ -136,18 +133,18 @@ view_df <- function(x, if (!is.null(CSS[['css.arc']])) css.arc <- ifelse(substring(CSS[['css.arc']], 1, 1) == '+', paste0(css.arc, substring(CSS[['css.arc']], 2)), CSS[['css.arc']]) if (!is.null(CSS[['css.caption']])) css.caption <- ifelse(substring(CSS[['css.caption']], 1, 1) == '+', paste0(css.caption, substring(CSS[['css.caption']], 2)), CSS[['css.caption']]) } - + # set style sheet page.style <- sprintf("", tag.table, css.table, tag.thead, css.thead, tag.tdata, css.tdata, tag.arc, css.arc, tag.caption, css.caption) - + # table init toWrite <- sprintf("\n\n\n%s\n\n\n", encoding, page.style) - + # table caption, data frame name page.content <- sprintf("\n \n", deparse(substitute(x))) - + # header row page.content <- paste0(page.content, " \n ") if (show.id) page.content <- paste0(page.content, "") @@ -162,33 +159,33 @@ view_df <- function(x, if (show.wtd.frq) page.content <- paste0(page.content, "") if (show.wtd.prc) page.content <- paste0(page.content, "") page.content <- paste0(page.content, "\n \n") - + # create progress bar if (!hide.progress) pb <- utils::txtProgressBar(min = 0, max = colcnt, style = 3) - + # subsequent rows for (ccnt in seq_len(colcnt)) { # get index number, depending on sorting index <- id[ccnt] # default row string arcstring <- "" - + # if we have alternating row colors, set css if (altr.row.col) arcstring <- ifelse(sjmisc::is_even(ccnt), " arc", "") page.content <- paste0(page.content, " \n") - + # ID if (show.id) page.content <- paste0(page.content, sprintf(" \n", arcstring, index)) - + # name, and note if (!is.null(sjmisc::get_note(x[[index]]))) td.title.tag <- sprintf(" title=\"%s\"", sjmisc::get_note(x[[index]])) else td.title.tag <- "" - + page.content <- paste0( page.content, @@ -199,7 +196,7 @@ view_df <- function(x, colnames(x)[index] ) ) - + # type if (show.type) { vartype <- get.vartype(x[[index]]) @@ -218,7 +215,7 @@ view_df <- function(x, varlab <- "" } page.content <- paste0(page.content, sprintf(" \n", arcstring, varlab)) - + # missings and missing percentage if (show.na) { page.content <- paste0( @@ -254,7 +251,7 @@ view_df <- function(x, paste0(page.content, sprintf(" \n", arcstring, valstring)) } - + # value labels if (show.labels) { valstring <- "" @@ -277,7 +274,7 @@ view_df <- function(x, } page.content <- paste0(page.content, sprintf(" \n", arcstring, valstring)) } - + # frequencies if (show.frq) { page.content <- @@ -288,7 +285,7 @@ view_df <- function(x, frq.value(index, x, df.val) )) } - + # percentage of frequencies if (show.prc) { page.content <- @@ -299,7 +296,7 @@ view_df <- function(x, prc.value(index, x, df.val) )) } - + # frequencies if (show.wtd.frq && !is.null(weight.by)) { page.content <- @@ -310,7 +307,7 @@ view_df <- function(x, frq.value(index, x, df.val, weight.by) )) } - + # percentage of frequencies if (show.prc && !is.null(weight.by)) { page.content <- @@ -321,41 +318,41 @@ view_df <- function(x, prc.value(index, x, df.val, weight.by) )) } - + # update progress bar if (!hide.progress) utils::setTxtProgressBar(pb, ccnt) # close row tag page.content <- paste0(page.content, " \n") } if (!hide.progress) close(pb) - + # finish html page page.content <- paste(page.content, "
Data frame: %s
IDweighted Freq.weighted %
%i%s%s%s
", sep = "\n") toWrite <- paste0(toWrite, sprintf("%s\n", page.content)) - + # replace class attributes with inline style, # useful for knitr knitr <- page.content - + # set style attributes for main table tags knitr <- gsub("class=", "style=", knitr, fixed = TRUE, useBytes = TRUE) knitr <- gsub(" 3.0.3, the \code{"ward"} option has been replaced by - either \code{"ward.D"} or \code{"ward.D2"}, so you may use one of +Since R version > 3.0.3, the \code{"ward"} option has been replaced by + either \code{"ward.D"} or \code{"ward.D2"}, so you may use one of these values. When using \code{"ward"}, it will be replaced by \code{"ward.D2"}. \cr \cr To get similar results as in SPSS Quick Cluster function, following points diff --git a/man/sjc.dend.Rd b/man/sjc.dend.Rd index ba54aaeb..96ca7b65 100755 --- a/man/sjc.dend.Rd +++ b/man/sjc.dend.Rd @@ -7,7 +7,7 @@ sjc.dend(data, groupcount, distance = "euclidean", agglomeration = "ward") } \arguments{ -\item{data}{\code{data.frame} with variables that should be used for the +\item{data}{A data frame with variables that should be used for the cluster analysis.} \item{groupcount}{The amount of groups (clusters) that should be used. @@ -17,13 +17,13 @@ cluster analysis.} } Solutions for multiple cluster groups can be plotted, for instance with \code{"groupcount = c(3:6)"}.} -\item{distance}{distance measure to be used when \code{method = "hclust"} (for hierarchical -clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, +\item{distance}{Distance measure to be used when \code{method = "hclust"} (for hierarchical +clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, \code{"canberra"}, \code{"binary"} or \code{"minkowski"}. See \code{\link{dist}}. If is \code{method = "kmeans"} this argument will be ignored.} -\item{agglomeration}{agglomeration method to be used when \code{method = "hclust"} (for hierarchical -clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, +\item{agglomeration}{Agglomeration method to be used when \code{method = "hclust"} (for hierarchical +clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, \code{"mcquitty"}, \code{"median"} or \code{"centroid"}. Default is \code{"ward"} (see \code{\link{hclust}}). If \code{method = "kmeans"} this argument will be ignored. See 'Note'.} } @@ -34,9 +34,9 @@ Computes a hierarchical cluster analysis and plots a hierarchical (see \code{\link{sjc.elbow}}). } \note{ -Since R version > 3.0.3, the \code{"ward"} option has +Since R version > 3.0.3, the \code{"ward"} option has been replaced by either \code{"ward.D"} or \code{"ward.D2"}, - so you may use one of these values. When using \code{"ward"}, + so you may use one of these values. When using \code{"ward"}, it will be replaced by \code{"ward.D2"}. } \examples{ diff --git a/man/sjc.elbow.Rd b/man/sjc.elbow.Rd index f020c487..c0eaf0a7 100755 --- a/man/sjc.elbow.Rd +++ b/man/sjc.elbow.Rd @@ -7,13 +7,13 @@ sjc.elbow(data, steps = 15, show.diff = FALSE) } \arguments{ -\item{data}{data frame containing all variables that should be used for +\item{data}{data frame containing all variables that should be used for determining the elbow criteria} \item{steps}{maximum group-count for the k-means cluster analysis for which the elbow-criterion should be displayed. Default is \code{15}.} -\item{show.diff}{logical, if \code{TRUE}, an additional plot with the differences between +\item{show.diff}{logical, if \code{TRUE}, an additional plot with the differences between each fusion step of the Elbow criterion calculation is shown. This plot may help identifying the "elbow". Default for this argument is \code{FALSE}.} } diff --git a/man/sjc.grpdisc.Rd b/man/sjc.grpdisc.Rd index 38e77304..4c01f125 100755 --- a/man/sjc.grpdisc.Rd +++ b/man/sjc.grpdisc.Rd @@ -7,7 +7,7 @@ sjc.grpdisc(data, groups, groupcount, clss.fit = TRUE, prnt.plot = TRUE) } \arguments{ -\item{data}{\code{data.frame} with variables that should be used for the +\item{data}{A data frame with variables that should be used for the cluster analysis.} \item{groups}{group classification of the cluster analysis that was returned @@ -27,7 +27,7 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v \value{ (Invisibly) returns an object with \itemize{ - \item \code{data}: the used data frame for plotting, + \item \code{data}: the used data frame for plotting, \item \code{plot}: the ggplot object, \item \code{accuracy}: a vector with the accuracy of classification for each group, \item \code{total.accuracy}: the total accuracy of group classification. diff --git a/man/sjc.kgap.Rd b/man/sjc.kgap.Rd index c290cf48..4c228849 100755 --- a/man/sjc.kgap.Rd +++ b/man/sjc.kgap.Rd @@ -8,7 +8,7 @@ sjc.kgap(x, max = 10, B = 100, SE.factor = 1, method = "Tibs2001SEmax", plotResults = TRUE) } \arguments{ -\item{x}{matrix, where rows are observations and columns are individual dimensions, +\item{x}{matrix, where rows are observations and columns are individual dimensions, to compute and plot the gap statistic (according to a uniform reference distribution).} \item{max}{maximum number of clusters to consider, must be at least two. Default @@ -16,13 +16,13 @@ is 10.} \item{B}{integer, number of Monte Carlo ("bootstrap") samples. Default is 100.} -\item{SE.factor}{[When \code{method} contains "SE"] Determining the optimal -number of clusters, Tibshirani et al. proposed the "1 S.E."-rule. +\item{SE.factor}{[When \code{method} contains "SE"] Determining the optimal +number of clusters, Tibshirani et al. proposed the "1 S.E."-rule. Using an SE.factor f, the "f S.E."-rule is used, more generally.} -\item{method}{character string indicating how the "optimal" number of clusters, -k^, is computed from the gap statistics (and their standard deviations), -or more generally how the location k^ of the maximum of f[k] should be +\item{method}{character string indicating how the "optimal" number of clusters, +k^, is computed from the gap statistics (and their standard deviations), +or more generally how the location k^ of the maximum of f[k] should be determined. Default is \code{"Tibs2001SEmax"}. Possible value are: \describe{ \item{\code{"globalmax"}}{simply corresponds to the global maximum, i.e., is which.max(f).} diff --git a/man/sjc.qclus.Rd b/man/sjc.qclus.Rd index 008645ab..66e9ce35 100755 --- a/man/sjc.qclus.Rd +++ b/man/sjc.qclus.Rd @@ -17,16 +17,16 @@ sjc.qclus(data, groupcount = NULL, groups = NULL, method = c("kmeans", coord.flip = FALSE, reverse.axis = FALSE, prnt.plot = TRUE) } \arguments{ -\item{data}{\code{data.frame} with variables that should be used for the +\item{data}{A data frame with variables that should be used for the cluster analysis.} -\item{groupcount}{amount of groups (clusters) used for the cluster solution. May also be +\item{groupcount}{Amount of groups (clusters) used for the cluster solution. May also be a set of initial (distinct) cluster centres, in case \code{method = "kmeans"} -(see \code{\link{kmeans}} for details on \code{centers} argument). -If \code{groupcount = NULL} and \code{method = "kmeans"}, the optimal -amount of clusters is calculated using the gap statistics (see +(see \code{\link{kmeans}} for details on \code{centers} argument). +If \code{groupcount = NULL} and \code{method = "kmeans"}, the optimal +amount of clusters is calculated using the gap statistics (see \code{\link{sjc.kgap}}). For \code{method = "hclust"}, \code{groupcount} -needs to be specified. Following functions may be helpful for estimating +needs to be specified. Following functions may be helpful for estimating the amount of clusters: \itemize{ \item Use \code{\link{sjc.elbow}} to determine the group-count depending on the elbow-criterion. @@ -35,38 +35,38 @@ the amount of clusters: \item Use \code{\link{sjc.grpdisc}} to inspect the goodness of grouping (accuracy of classification). }} -\item{groups}{optional, by default, this argument is \code{NULL} and will be +\item{groups}{Optional, by default, this argument is \code{NULL} and will be ignored. However, to plot existing cluster groups, specify \code{groupcount} -and \code{groups}. \code{groups} is a vector of same length as -\code{nrow(data)} and indicates the group classification of the cluster +and \code{groups}. \code{groups} is a vector of same length as +\code{nrow(data)} and indicates the group classification of the cluster analysis. The group classification can be computed with the \code{\link{sjc.cluster}} function. See 'Examples'.} -\item{method}{method for computing the cluster analysis. By default (\code{"kmeans"}), a -kmeans cluster analysis will be computed. Use \code{"hclust"} to -compute a hierarchical cluster analysis. You can specify the +\item{method}{Method for computing the cluster analysis. By default (\code{"kmeans"}), a +kmeans cluster analysis will be computed. Use \code{"hclust"} to +compute a hierarchical cluster analysis. You can specify the initial letters only.} -\item{distance}{distance measure to be used when \code{method = "hclust"} (for hierarchical -clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, +\item{distance}{Distance measure to be used when \code{method = "hclust"} (for hierarchical +clustering). Must be one of \code{"euclidean"}, \code{"maximum"}, \code{"manhattan"}, \code{"canberra"}, \code{"binary"} or \code{"minkowski"}. See \code{\link{dist}}. If is \code{method = "kmeans"} this argument will be ignored.} -\item{agglomeration}{agglomeration method to be used when \code{method = "hclust"} (for hierarchical -clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, +\item{agglomeration}{Agglomeration method to be used when \code{method = "hclust"} (for hierarchical +clustering). This should be one of \code{"ward"}, \code{"single"}, \code{"complete"}, \code{"average"}, \code{"mcquitty"}, \code{"median"} or \code{"centroid"}. Default is \code{"ward"} (see \code{\link{hclust}}). If \code{method = "kmeans"} this argument will be ignored. See 'Note'.} -\item{iter.max}{maximum number of iterations allowed. Only applies, if +\item{iter.max}{Maximum number of iterations allowed. Only applies, if \code{method = "kmeans"}. See \code{\link{kmeans}} for details on this argument.} -\item{algorithm}{algorithm used for calculating kmeans cluster. Only applies, if -\code{method = "kmeans"}. May be one of \code{"Hartigan-Wong"} (default), -\code{"Lloyd"} (used by SPSS), or \code{"MacQueen"}. See \code{\link{kmeans}} +\item{algorithm}{Algorithm used for calculating kmeans cluster. Only applies, if +\code{method = "kmeans"}. May be one of \code{"Hartigan-Wong"} (default), +\code{"Lloyd"} (used by SPSS), or \code{"MacQueen"}. See \code{\link{kmeans}} for details on this argument.} -\item{show.accuracy}{logical, if \code{TRUE}, the \code{\link{sjc.grpdisc}} function will be called, -which computes a linear discriminant analysis on the classified cluster groups and plots a +\item{show.accuracy}{Logical, if \code{TRUE}, the \code{\link{sjc.grpdisc}} function will be called, +which computes a linear discriminant analysis on the classified cluster groups and plots a bar graph indicating the goodness of classification for each group.} \item{title}{character vector, used as plot title. Depending on plot type and function, @@ -80,25 +80,25 @@ argument, since in most cases, axis labels are set automatically.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.spacing}{the spacing between geoms (i.e. bar spacing)} @@ -106,7 +106,7 @@ need smaller values than dot sizes.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.grpcnt}{if \code{TRUE} (default), the count within each cluster group is added to the +\item{show.grpcnt}{Logical, if \code{TRUE} (default), the count within each cluster group is added to the legend labels (e.g. \code{"Group 1 (n=87)"}).} \item{legend.title}{character vector, used as title for the plot legend.} @@ -115,7 +115,7 @@ legend labels (e.g. \code{"Group 1 (n=87)"}).} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} -\item{reverse.axis}{if \code{TRUE}, the values on the x-axis are reversed.} +\item{reverse.axis}{Logical, if \code{TRUE}, the values on the x-axis are reversed.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} @@ -123,7 +123,7 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v \value{ (Invisibly) returns an object with \itemize{ - \item \code{data}: the used data frame for plotting, + \item \code{data}: the used data frame for plotting, \item \code{plot}: the ggplot object, \item \code{groupcount}: the number of found cluster (as calculated by \code{\link{sjc.kgap}}) \item \code{classification}: the group classification (as calculated by \code{\link{sjc.cluster}}), including missing values, so this vector can be appended to the original data frame. @@ -156,7 +156,7 @@ sjc.qclus(mtcars) # k-means clustering of mtcars-dataset with 4 pre-defined # groups in a faceted panel sjc.qclus(airquality, groupcount = 4, facet.grid = TRUE)} - + # k-means clustering of airquality data # and saving the results. most likely, 3 cluster # groups have been found (see below). diff --git a/man/sjp.aov1.Rd b/man/sjp.aov1.Rd index f8f63ffa..56f79a51 100755 --- a/man/sjp.aov1.Rd +++ b/man/sjp.aov1.Rd @@ -12,13 +12,13 @@ sjp.aov1(var.dep, var.grp, meansums = FALSE, title = NULL, show.summary = FALSE, prnt.plot = TRUE) } \arguments{ -\item{var.dep}{dependent variable. Will be used with following formula: +\item{var.dep}{Dependent variable. Will be used with following formula: \code{aov(var.dep ~ var.grp)}} -\item{var.grp}{factor with the cross-classifying variable, where \code{var.dep} +\item{var.grp}{Factor with the cross-classifying variable, where \code{var.dep} is grouped into the categories represented by \code{var.grp}.} -\item{meansums}{logical, if \code{TRUE}, the values reported are the true group mean values (see also \code{\link{sjt.grpmean}}). +\item{meansums}{Logical, if \code{TRUE}, the values reported are the true group mean values (see also \code{\link{sjt.grpmean}}). If \code{FALSE} (default), the values are reported in the standard way, i.e. the values indicate the difference of the group mean in relation to the intercept (reference group).} @@ -30,20 +30,23 @@ to define titles for each sub-plot or facet.} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{rev.order}{logical, if \code{TRUE}, order of categories (groups) is reversed.} +\item{rev.order}{Logical, if \code{TRUE}, order of categories (groups) is reversed.} -\item{string.interc}{string that indicates the reference group (intercept), that is appended to +\item{string.interc}{Character vector that indicates the reference group (intercept), that is appended to the value label of the grouping variable. Default is \code{"(Intercept)"}.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may @@ -52,34 +55,34 @@ plot (only if non-faceted).} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{show.values}{logical, whether values should be plotted or not.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared -statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. -is shown. If a cell contains expected values lower than five (or lower than 10 -if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is -computed instead of chi-squared test. If the table's matrix is larger +\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared +statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. +is shown. If a cell contains expected values lower than five (or lower than 10 +if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is +computed instead of chi-squared test. If the table's matrix is larger than 2x2, Fisher's excact test with Monte Carlo simulation is computed.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't @@ -90,8 +93,8 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v was used for setting up the ggplot-object (\code{df}). } \description{ -Plot One-Way-Anova table sum of squares (SS) of each factor level (group) - against the dependent variable. The SS of the factor variable against the +Plot One-Way-Anova table sum of squares (SS) of each factor level (group) + against the dependent variable. The SS of the factor variable against the dependent variable (variance within and between groups) is printed to the model summary. } diff --git a/man/sjp.chi2.Rd b/man/sjp.chi2.Rd index 1ad465dd..66c045f7 100755 --- a/man/sjp.chi2.Rd +++ b/man/sjp.chi2.Rd @@ -9,7 +9,7 @@ sjp.chi2(df, title = "Pearson's Chi2-Test of Independence", show.legend = FALSE, legend.title = NULL, prnt.plot = TRUE) } \arguments{ -\item{df}{data frame with (dichotomous) factor variables.} +\item{df}{A data frame with (dichotomous) factor variables.} \item{title}{character vector, used as plot title. Depending on plot type and function, will be set automatically. If \code{title = ""}, no title is printed. @@ -22,7 +22,7 @@ argument, since in most cases, axis labels are set automatically.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and @@ -38,9 +38,9 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v was used for setting up the ggplot-object (\code{mydf}). } \description{ -Plot p-values of Pearson's Chi2-tests for multiple contingency tables as ellipses or tiles. +Plot p-values of Pearson's Chi2-tests for multiple contingency tables as ellipses or tiles. Requires a data frame with dichotomous (dummy) variables. - Calculation of Chi2-matrix taken from + Calculation of Chi2-matrix taken from \href{https://talesofr.wordpress.com/2013/05/05/ridiculously-photogenic-factors-heatmap-with-p-values/}{Tales of R}. } \examples{ diff --git a/man/sjp.corr.Rd b/man/sjp.corr.Rd index 966f2363..fb1f0743 100755 --- a/man/sjp.corr.Rd +++ b/man/sjp.corr.Rd @@ -12,7 +12,7 @@ sjp.corr(data, title = NULL, axis.labels = NULL, sort.corr = TRUE, p.numeric = FALSE, prnt.plot = TRUE) } \arguments{ -\item{data}{matrix with correlation coefficients as returned by the +\item{data}{Matrix with correlation coefficients as returned by the \code{\link{cor}}-function, or a \code{data.frame} of variables where correlations between columns should be computed.} @@ -24,20 +24,20 @@ to define titles for each sub-plot or facet.} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{sort.corr}{logical, if \code{TRUE} (default), the axis labels are sorted +\item{sort.corr}{Logical, if \code{TRUE} (default), the axis labels are sorted according to the correlation strength. If \code{FALSE}, axis labels appear in order of how variables were included in the cor-computation or data frame.} -\item{decimals}{indicates how many decimal values after comma are printed when +\item{decimals}{Indicates how many decimal values after comma are printed when the values labels are shown. Default is 3. Only applies when \code{show.values = TRUE}.} -\item{na.deletion}{indicates how missing values are treated. May be either +\item{na.deletion}{Indicates how missing values are treated. May be either \code{"listwise"} (default) or \code{"pairwise"}. May be abbreviated.} -\item{corr.method}{indicates the correlation computation method. May be one of +\item{corr.method}{Indicates the correlation computation method. May be one of \code{"spearman"} (default), \code{"pearson"} or \code{"kendall"}. May be abbreviated.} @@ -46,7 +46,7 @@ May be abbreviated.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and @@ -56,10 +56,10 @@ function, a legend is added to the plot.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't diff --git a/man/sjp.frq.Rd b/man/sjp.frq.Rd index 71110113..1f0d436d 100755 --- a/man/sjp.frq.Rd +++ b/man/sjp.frq.Rd @@ -20,23 +20,23 @@ sjp.frq(var.cnt, title = "", weight.by = NULL, title.wtd.suffix = NULL, y.offset = NULL, prnt.plot = TRUE) } \arguments{ -\item{var.cnt}{vector of counts, for which frequencies or means will be plotted or printed.} +\item{var.cnt}{Vector of counts, for which frequencies or means will be plotted or printed.} \item{title}{character vector, used as plot title. Depending on plot type and function, will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{title.wtd.suffix}{suffix (as string) for the title, if \code{weight.by} is specified, -e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +\item{title.wtd.suffix}{Suffix (as string) for the title, if \code{weight.by} is specified, +e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so title will not have a suffix when cases are weighted.} -\item{sort.frq}{Determines whether categories should be sorted -according to their frequencies or not. Default is \code{"none"}, so +\item{sort.frq}{Determines whether categories should be sorted +according to their frequencies or not. Default is \code{"none"}, so categories are not sorted by frequency. Use \code{"asc"} or \code{"desc"} for sorting categories ascending or descending order.} @@ -51,42 +51,45 @@ categories are not sorted by frequency. Use \code{"asc"} or \item{\code{"violin"}}{for violin plots} }} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{geom.colors}{user defined color for geoms, e.g. \code{geom.colors = "#0080ff"}.} +\item{geom.colors}{User defined color for geoms, e.g. \code{geom.colors = "#0080ff"}.} -\item{errorbar.color}{color of confidence interval bars (error bars). -Only applies to \code{type = "bar"}. In case of dot plots, error bars +\item{errorbar.color}{Color of confidence interval bars (error bars). +Only applies to \code{type = "bar"}. In case of dot plots, error bars will have same colors as dots (see \code{geom.colors}).} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{xlim}{numeric vector of length two, defining lower and upper axis limits -of the x scale. By default, this argument is set to \code{NULL}, i.e. the +\item{xlim}{Numeric vector of length two, defining lower and upper axis limits +of the x scale. By default, this argument is set to \code{NULL}, i.e. the x-axis fits to the required range of the data.} \item{ylim}{numeric vector of length two, defining lower and upper axis limits -of the y scale. By default, this argument is set to \code{NULL}, i.e. the +of the y scale. By default, this argument is set to \code{NULL}, i.e. the y-axis fits to the required range of the data.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{expand.grid}{logical, if \code{TRUE}, the plot grid is expanded, i.e. there is a small margin between @@ -103,71 +106,71 @@ If \code{FALSE}, percentage values are removed.} \item{show.axis.values}{logical, whether category, count or percentage values for the axis should be printed or not.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{show.na}{logical, if \code{TRUE}, \code{\link{NA}}'s (missing values) are added to the output.} -\item{show.mean}{logical, if \code{TRUE}, a vertical line in histograms -is drawn to indicate the mean value of the variables. Only +\item{show.mean}{Logical, if \code{TRUE}, a vertical line in histograms +is drawn to indicate the mean value of the variables. Only applies to histogram-charts.} -\item{show.mean.val}{logical, if \code{TRUE} (default), the mean value +\item{show.mean.val}{Logical, if \code{TRUE} (default), the mean value is printed to the vertical line that indicates the variable's mean. Only applies to histogram-charts.} -\item{show.sd}{logical, if \code{TRUE}, the standard deviation +\item{show.sd}{Logical, if \code{TRUE}, the standard deviation is annotated as shaded rectangle around the mean intercept line. Only applies to histogram-charts.} -\item{mean.line.type}{numeric value, indicating the linetype of the mean -intercept line. Only applies to histogram-charts and +\item{mean.line.type}{Numeric value, indicating the linetype of the mean +intercept line. Only applies to histogram-charts and when \code{show.mean = TRUE}.} -\item{mean.line.size}{numeric, size of the mean intercept line. Only +\item{mean.line.size}{Numeric, size of the mean intercept line. Only applies to histogram-charts and when \code{show.mean = TRUE}.} -\item{inner.box.width}{width of the inner box plot that is plotted inside of violin plots. Only applies +\item{inner.box.width}{width of the inner box plot that is plotted inside of violin plots. Only applies if \code{type = "violin"}. Default value is 0.15} -\item{inner.box.dotsize}{size of mean dot insie a violin or box plot. Applies only +\item{inner.box.dotsize}{size of mean dot insie a violin or box plot. Applies only when \code{type = "violin"} or \code{"boxplot"}.} -\item{normal.curve}{logical, if \code{TRUE}, a normal curve, which is adjusted to the data, +\item{normal.curve}{Logical, if \code{TRUE}, a normal curve, which is adjusted to the data, is plotted over the histogram or density plot. Default is \code{FALSE}. Only applies when histograms or density plots are plotted (see \code{type}).} -\item{normal.curve.color}{color of the normal curve line. Only +\item{normal.curve.color}{Color of the normal curve line. Only applies if \code{normal.curve = TRUE}.} -\item{normal.curve.size}{numeric, size of the normal curve line. Only +\item{normal.curve.size}{Numeric, size of the normal curve line. Only applies if \code{normal.curve = TRUE}.} -\item{normal.curve.alpha}{transparancy level (alpha value) of the normal curve. Only +\item{normal.curve.alpha}{Transparancy level (alpha value) of the normal curve. Only applies if \code{normal.curve = TRUE}.} -\item{auto.group}{numeric value, indicating the minimum amount of unique values -in the count variable, at which automatic grouping into smaller units -is done (see \code{\link[sjmisc]{group_var}}). Default value for +\item{auto.group}{numeric value, indicating the minimum amount of unique values +in the count variable, at which automatic grouping into smaller units +is done (see \code{\link[sjmisc]{group_var}}). Default value for \code{auto.group} is \code{NULL}, i.e. auto-grouping is off. See \code{\link[sjmisc]{group_var}} for examples on grouping.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} -\item{vjust}{character vector, indicating the vertical position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{vjust}{character vector, indicating the vertical position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} -\item{hjust}{character vector, indicating the horizontal position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{hjust}{character vector, indicating the horizontal position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't @@ -192,7 +195,7 @@ sjp.frq(ChickWeight$weight, type = "box") # histogram sjp.frq(discoveries, type = "hist", show.mean = TRUE) - + # violin plot sjp.frq(ChickWeight$weight, type = "v") @@ -219,7 +222,7 @@ sjp.frq(efc$neg_c_7) # plotting confidence intervals. expand grid and v/hjust for text labels sjp.frq(efc$e15relat, type = "dot", show.ci = TRUE, sort.frq = "desc", - coord.flip = TRUE, expand.grid = TRUE, vjust = "bottom", + coord.flip = TRUE, expand.grid = TRUE, vjust = "bottom", hjust = "left") # Simulate ggplot-default histogram diff --git a/man/sjp.glm.Rd b/man/sjp.glm.Rd index 3e294867..9d503666 100755 --- a/man/sjp.glm.Rd +++ b/man/sjp.glm.Rd @@ -17,9 +17,9 @@ sjp.glm(fit, type = "dots", vars = NULL, group.estimates = NULL, facet.grid = TRUE, prnt.plot = TRUE, ...) } \arguments{ -\item{fit}{fitted generalized linear model (\code{\link{glm}}- or \code{logistf}-object).} +\item{fit}{Fitted generalized linear model (\code{\link{glm}}- or \code{logistf}-object).} -\item{type}{type of plot. Use one of following: +\item{type}{Type of plot. Use one of following: \describe{ \item{\code{"dots"}}{(or \code{"glm"} or \code{"or"} (default)) for odds or incident rate ratios (forest plot). Note that this type plots the exponentiated estimates, thus being appropriate only for specific link-functions.} \item{\code{"slope"}}{to plot probability or incidents slopes (predicted probabilities or incidents) for each model term, where all remaining co-variates are set to zero (i.e. ignored). Use \code{facet.grid} to decide whether to plot each coefficient as separate plot or as integrated faceted plot.} @@ -29,21 +29,21 @@ sjp.glm(fit, type = "dots", vars = NULL, group.estimates = NULL, \item{\code{"vif"}}{to plot Variance Inflation Factors.} }} -\item{vars}{numeric vector with column indices of selected variables or a character vector with +\item{vars}{Numeric vector with column indices of selected variables or a character vector with variable names of selected variables from the fitted model, which should be used to plot - depending on \code{type} - estimates, fixed effects slopes or predicted values (mean, probabilities, incidents rates, ...). See 'Examples'.} -\item{group.estimates}{numeric or character vector, indicating a group identifier for +\item{group.estimates}{Numeric or character vector, indicating a group identifier for each estimate. Dots and confidence intervals of estimates are coloured according to their group association. See 'Examples'.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{sort.est}{logical, determines whether estimates should be sorted according to their values. +\item{sort.est}{Logical, determines whether estimates should be sorted according to their values. If \code{group.estimates} is \emph{not} \code{NULL}, estimates are sorted according to their group assignment.} @@ -52,26 +52,29 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector @@ -80,80 +83,80 @@ of same length as groups. See 'Examples'.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may also be a list of vectors of length 2, defining axis limits for each plot (only if non-faceted).} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} -\item{trns.ticks}{logical, if \code{TRUE}, the grid lines have exponential +\item{trns.ticks}{Logical, if \code{TRUE}, the grid lines have exponential distances (equidistant), i.e. they visually have the same distance from one panel grid to the next. If \code{FALSE}, grids are plotted on every \code{grid.breaks}'s position, thus the grid lines become narrower with higher odds ratio values.} -\item{show.intercept}{logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +\item{show.intercept}{Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential transformation of estimates, the intercept in some cases can not be calculated, thus the function call is interrupted and no plot printed.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.summary}{logical, if \code{TRUE}, a summary with model statistics +\item{show.summary}{Logical, if \code{TRUE}, a summary with model statistics is added to the plot.} -\item{show.scatter}{logical, if \code{TRUE} (default), adds a scatter plot of +\item{show.scatter}{Logical, if \code{TRUE} (default), adds a scatter plot of data points to the plot. Only applies for slope-type or predictions plots. For most plot types, dots are jittered to avoid overplotting, hence the points don't reflect exact values in the data.} -\item{point.alpha}{alpha value of point-geoms in the scatter plots. Only applies, +\item{point.alpha}{Alpha value of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{point.color}{color of of point-geoms in the scatter plots. Only applies, +\item{point.color}{Color of of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{jitter.ci}{logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +\item{jitter.ci}{Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence bands are displayed as error bars, adds jittering to lines and error bars to avoid overlapping.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} -\item{...}{other arguments passed down to further functions. Currently, following +\item{...}{Other arguments passed down to further functions. Currently, following arguments are supported: \describe{ \item{\code{?effects::effect}}{ diff --git a/man/sjp.glmer.Rd b/man/sjp.glmer.Rd index 2052575b..5f49ebb3 100755 --- a/man/sjp.glmer.Rd +++ b/man/sjp.glmer.Rd @@ -17,9 +17,9 @@ sjp.glmer(fit, type = "re", vars = NULL, ri.nr = NULL, prnt.plot = TRUE, ...) } \arguments{ -\item{fit}{a fitted model as returned by the \code{\link[lme4]{glmer}}-function.} +\item{fit}{A fitted model as returned by the \code{\link[lme4]{glmer}}-function.} -\item{type}{type of plot. Use one of following: +\item{type}{Type of plot. Use one of following: \describe{ \item{\code{"re"}}{(default) for conditional modes (odds or incidents ratios) of random effects} \item{\code{"fe"}}{for odds or incidents ratios of fixed effects} @@ -34,34 +34,34 @@ sjp.glmer(fit, type = "re", vars = NULL, ri.nr = NULL, \item{\code{"ma"}}{to check model assumptions. Note that only argument \code{fit} applies to this plot type. All other arguments are ignored.} }} -\item{vars}{numeric vector with column indices of selected variables or a character vector with +\item{vars}{Numeric vector with column indices of selected variables or a character vector with variable names of selected variables from the fitted model, which should be used to plot - depending on \code{type} - estimates, fixed effects slopes or predicted values (mean, probabilities, incidents rates, ...). See 'Examples'.} -\item{ri.nr}{numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, +\item{ri.nr}{Numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, and fitted model has more than one random intercept, \code{ri.nr} indicates which random effects of which random intercept (or: which list elements of \code{\link[lme4]{ranef}}) will be plotted. Default is \code{NULL}, so all random effects will be plotted.} -\item{group.estimates}{numeric or character vector, indicating a group identifier for +\item{group.estimates}{Numeric or character vector, indicating a group identifier for each estimate. Dots and confidence intervals of estimates are coloured according to their group association. See 'Examples'.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{emph.grp}{numeric vector with index numbers of grouping levels (from random effect). +\item{emph.grp}{Numeric vector with index numbers of grouping levels (from random effect). If \code{type = "ri.slope"} and \code{facet.grid = FALSE}, an integrated plot of predicted probabilities of fixed effects resp. fixed effects slopes for each grouping level is plotted. To better find certain groups, use this argument to emphasize these groups in the plot. See 'Examples'.} -\item{sample.n}{numeric vector. only applies, if \code{type = "rs.ri"}. If +\item{sample.n}{Numeric vector. only applies, if \code{type = "rs.ri"}. If plot has many random intercepts (grouping levels), overplotting of regression lines may occur. In this case, consider random sampling of grouping levels. If \code{sample.n} is of length 1, a random sample @@ -71,7 +71,7 @@ the values in \code{sample.n} are selected to plot random effects. Use the latter option to always select a fixed, identical set of random effects for plotting (useful when ecomparing multiple models).} -\item{sort.est}{determines in which way estimates are sorted in the plot: +\item{sort.est}{Determines in which way estimates are sorted in the plot: \itemize{ \item If \code{NULL} (default), no sorting is done and estimates are sorted in order of model coefficients. \item If \code{sort.est = "sort.all"}, estimates are re-sorted for each coefficient (only applies if \code{type = "re"} and \code{facet.grid = FALSE}), i.e. the estimates of the random effects for each predictor are sorted and plotted to an own plot. @@ -80,101 +80,104 @@ random effects for plotting (useful when ecomparing multiple models).} } See 'Examples'.} -\item{title}{character vector with one or more labels that are used as plot title.} +\item{title}{Character vector with one or more labels that are used as plot title.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} -\item{axis.labels}{character vector with labels for the model terms, used as axis labels. +\item{axis.labels}{Character vector with labels for the model terms, used as axis labels. For mixed models, should either be vector of fixed effects variable labels (if \code{type = "fe"} or \code{type = "fe.std"}) or a vector of group (value) labels from the random intercept's categories (if \code{type = "re"}).} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector of same length as groups. See 'Examples'.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.intercept}{logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +\item{show.intercept}{Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential transformation of estimates, the intercept in some cases can not be calculated, thus the function call is interrupted and no plot printed.} -\item{string.interc}{string, axis label of intercept estimate. Only applies, +\item{string.interc}{String, axis label of intercept estimate. Only applies, if \code{show.intercept = TRUE} and \code{axis.labels} is not \code{NULL}.} -\item{show.scatter}{logical, if \code{TRUE} (default), adds a scatter plot of +\item{show.scatter}{Logical, if \code{TRUE} (default), adds a scatter plot of data points to the plot. Only applies for slope-type or predictions plots. For most plot types, dots are jittered to avoid overplotting, hence the points don't reflect exact values in the data.} -\item{point.alpha}{alpha value of point-geoms in the scatter plots. Only applies, +\item{point.alpha}{Alpha value of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{point.color}{color of of point-geoms in the scatter plots. Only applies, +\item{point.color}{Color of of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{jitter.ci}{logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +\item{jitter.ci}{Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence bands are displayed as error bars, adds jittering to lines and error bars to avoid overlapping.} -\item{fade.ns}{if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} +\item{fade.ns}{Logical, if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may also be a list of vectors of length 2, defining axis limits for each plot (only if non-faceted).} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} -\item{free.scale}{if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid +\item{free.scale}{Logical, if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid gets its own fitted scale. If \code{free.scale = FALSE}, each facet in the grid has the same scale range.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} -\item{...}{other arguments passed down to further functions. Currently, following +\item{...}{Other arguments passed down to further functions. Currently, following arguments are supported: \describe{ \item{\code{?effects::effect}}{ diff --git a/man/sjp.glmm.Rd b/man/sjp.glmm.Rd index 658c4c06..c9dd8e57 100755 --- a/man/sjp.glmm.Rd +++ b/man/sjp.glmm.Rd @@ -16,11 +16,11 @@ sjp.glmm(..., remove.estimates = NULL, title = NULL, depvar.labels = NULL, coord.flip = TRUE, prnt.plot = TRUE) } \arguments{ -\item{...}{one or more fitted \code{glm}- or \code{glmerMod}-objects. May -also be a \code{\link{list}}-object with +\item{...}{One or more fitted \code{glm}- or \code{glmerMod}-objects. May +also be a \code{\link{list}}-object with fitted models, instead of separating each model with comma. See 'Examples'.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} @@ -30,10 +30,10 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} @@ -43,15 +43,18 @@ indicates the p-values. Default is \code{"p-level"}. Only applies if \code{p.sha \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may @@ -61,29 +64,29 @@ plot (only if non-faceted).} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} -\item{trns.ticks}{logical, if \code{TRUE}, the grid lines have exponential +\item{trns.ticks}{Logical, if \code{TRUE}, the grid lines have exponential distances (equidistant), i.e. they visually have the same distance from one panel grid to the next. If \code{FALSE}, grids are plotted on every \code{grid.breaks}'s position, thus the grid lines become narrower with higher odds ratio values.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.spacing}{spacing between the dots and error bars of the plotted fitted models. Default is 0.3.} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector @@ -94,12 +97,12 @@ of same length as groups. See 'Examples'.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.intercept}{logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +\item{show.intercept}{Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential transformation of estimates, the intercept in some cases can not be calculated, thus the function call is interrupted and no plot printed.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} \item{fade.ns}{if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} @@ -107,16 +110,16 @@ variable labels.} \item{p.shape}{If \code{TRUE}, significant levels are distinguished by different point shapes and a related legend is plotted. Default is \code{FALSE}.} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} @@ -129,12 +132,12 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v was used for setting up the ggplot-object (\code{data}). } \description{ -Plot and compare odds or incidents ratios (forest plots) of multiple fitted - generalized linear (mixed effects) models with confidence +Plot and compare odds or incidents ratios (forest plots) of multiple fitted + generalized linear (mixed effects) models with confidence intervals in one plot. } \note{ -The fitted models may have differing predictors, but only in a +The fitted models may have differing predictors, but only in a "stepwise" sense; i.e., models should share a common set of predictors, while some models may have additional predictors (e.g. added via the \code{\link[stats]{update}} function). See 'Examples'. diff --git a/man/sjp.gpt.Rd b/man/sjp.gpt.Rd index 6fa40017..37273384 100755 --- a/man/sjp.gpt.Rd +++ b/man/sjp.gpt.Rd @@ -14,25 +14,25 @@ sjp.gpt(x, y, groups, geom.colors = "Set1", geom.size = 2.5, show.n = TRUE, prnt.plot = TRUE) } \arguments{ -\item{x}{categorical variable, where the proportion of each category in +\item{x}{Categorical variable, where the proportion of each category in \code{x} for the highest category of \code{y} will be printed along the x-axis.} -\item{y}{categorical or numeric variable. If not a binary variable, \code{y} +\item{y}{Categorical or numeric variable. If not a binary variable, \code{y} will be recoded into a binary variable, dichtomized at the highest category and all remaining categories.} -\item{groups}{grouping variable, which will define the y-axis} +\item{groups}{Grouping variable, which will define the y-axis} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{shape.fill.color}{optional color vector, fill-color for non-filled shapes} +\item{shape.fill.color}{Optional color vector, fill-color for non-filled shapes} -\item{shapes}{numeric vector with shape styles, used to map the different +\item{shapes}{Numeric vector with shape styles, used to map the different categories of \code{x}.} \item{title}{character vector, used as plot title. Depending on plot type and function, @@ -53,33 +53,33 @@ for the x-axis and y-axis.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may also be a list of vectors of length 2, defining axis limits for each plot (only if non-faceted).} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} -\item{show.total}{logical, if \code{TRUE}, a total summary line for all aggregated +\item{show.total}{Logical, if \code{TRUE}, a total summary line for all aggregated \code{groups} is added.} -\item{annotate.total}{logical, if \code{TRUE} and \code{show.total = TRUE}, +\item{annotate.total}{Logical, if \code{TRUE} and \code{show.total = TRUE}, the total-row in the figure will be highlighted with a slightly shaded background.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} \item{show.n}{logical, if \code{TRUE}, adds total number of cases for each diff --git a/man/sjp.grpfrq.Rd b/man/sjp.grpfrq.Rd index 17285c79..d1ae4a2b 100755 --- a/man/sjp.grpfrq.Rd +++ b/man/sjp.grpfrq.Rd @@ -20,9 +20,9 @@ sjp.grpfrq(var.cnt, var.grp, type = c("bar", "dot", "line", "boxplot", y.offset = NULL, vjust = "bottom", hjust = "center", prnt.plot = TRUE) } \arguments{ -\item{var.cnt}{vector of counts, for which frequencies or means will be plotted or printed.} +\item{var.cnt}{Vector of counts, for which frequencies or means will be plotted or printed.} -\item{var.grp}{factor with the cross-classifying variable, where \code{var.cnt} +\item{var.grp}{Factor with the cross-classifying variable, where \code{var.cnt} is grouped into the categories represented by \code{var.grp}.} \item{type}{Specifies the plot type. May be abbreviated. @@ -36,16 +36,16 @@ is grouped into the categories represented by \code{var.grp}.} \item{\code{"violin"}}{for violin plots} }} -\item{bar.pos}{indicates whether bars should be positioned side-by-side (default), +\item{bar.pos}{Indicates whether bars should be positioned side-by-side (default), or stacked (\code{bar.pos = "stack"}). May be abbreviated.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{intr.var}{an interaction variable which can be used for box plots. Divides each category indicated +\item{intr.var}{An interaction variable which can be used for box plots. Divides each category indicated by \code{var.grp} into the factors of \code{intr.var}, so that each category of \code{var.grp} -is subgrouped into \code{intr.var}'s categories. Only applies when +is subgrouped into \code{intr.var}'s categories. Only applies when \code{type = "boxplot"} or \code{type = "violin"}.} \item{title}{character vector, used as plot title. Depending on plot type and function, @@ -53,8 +53,8 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{title.wtd.suffix}{suffix (as string) for the title, if \code{weight.by} is specified, -e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +\item{title.wtd.suffix}{Suffix (as string) for the title, if \code{weight.by} is specified, +e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so title will not have a suffix when cases are weighted.} \item{legend.title}{character vector, used as title for the plot legend.} @@ -75,17 +75,17 @@ These labels replace the \code{axis.labels}. Only applies, when using box or vio \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.spacing}{the spacing between geoms (i.e. bar spacing)} @@ -103,7 +103,7 @@ If \code{FALSE}, percentage values are removed.} \item{show.axis.values}{logical, whether category, count or percentage values for the axis should be printed or not.} -\item{show.grpcnt}{logical, if \code{TRUE}, the count within each group is added +\item{show.grpcnt}{logical, if \code{TRUE}, the count within each group is added to the category labels (e.g. \code{"Cat 1 (n=87)"}). Default value is \code{FALSE}.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and @@ -112,65 +112,65 @@ function, a legend is added to the plot.} \item{show.na}{logical, if \code{TRUE}, \code{\link{NA}}'s (missing values) are added to the output.} -\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared -statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. -is shown. If a cell contains expected values lower than five (or lower than 10 -if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is -computed instead of chi-squared test. If the table's matrix is larger +\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared +statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. +is shown. If a cell contains expected values lower than five (or lower than 10 +if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is +computed instead of chi-squared test. If the table's matrix is larger than 2x2, Fisher's excact test with Monte Carlo simulation is computed.} -\item{auto.group}{numeric value, indicating the minimum amount of unique values -in the count variable, at which automatic grouping into smaller units -is done (see \code{\link[sjmisc]{group_var}}). Default value for +\item{auto.group}{numeric value, indicating the minimum amount of unique values +in the count variable, at which automatic grouping into smaller units +is done (see \code{\link[sjmisc]{group_var}}). Default value for \code{auto.group} is \code{NULL}, i.e. auto-grouping is off. See \code{\link[sjmisc]{group_var}} for examples on grouping.} \item{ylim}{numeric vector of length two, defining lower and upper axis limits -of the y scale. By default, this argument is set to \code{NULL}, i.e. the +of the y scale. By default, this argument is set to \code{NULL}, i.e. the y-axis fits to the required range of the data.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{expand.grid}{logical, if \code{TRUE}, the plot grid is expanded, i.e. there is a small margin between axes and plotting region. Default is \code{FALSE}.} -\item{inner.box.width}{width of the inner box plot that is plotted inside of violin plots. Only applies +\item{inner.box.width}{width of the inner box plot that is plotted inside of violin plots. Only applies if \code{type = "violin"}. Default value is 0.15} -\item{inner.box.dotsize}{size of mean dot insie a violin or box plot. Applies only +\item{inner.box.dotsize}{size of mean dot insie a violin or box plot. Applies only when \code{type = "violin"} or \code{"boxplot"}.} \item{smooth.lines}{prints a smooth line curve. Only applies, when argument \code{type = "line"}.} -\item{emph.dots}{logical, if \code{TRUE}, the groups of dots in a dot-plot are highlighted +\item{emph.dots}{logical, if \code{TRUE}, the groups of dots in a dot-plot are highlighted with a shaded rectangle.} -\item{summary.pos}{position of the model summary which is printed when \code{show.summary} -is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. +\item{summary.pos}{position of the model summary which is printed when \code{show.summary} +is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. Use \code{"l"} for upper left corner.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} -\item{vjust}{character vector, indicating the vertical position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{vjust}{character vector, indicating the vertical position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} -\item{hjust}{character vector, indicating the horizontal position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{hjust}{character vector, indicating the horizontal position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't @@ -181,12 +181,12 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v was used for setting up the ggplot-object (\code{df}). } \description{ -Plot grouped or stacked frequencies of variables as bar/dot, +Plot grouped or stacked frequencies of variables as bar/dot, box or violin plots, or line plot. } \details{ -\code{geom.colors} may be a character vector of color values - in hex-format, valid color value names (see \code{demo("colors")} or +\code{geom.colors} may be a character vector of color values + in hex-format, valid color value names (see \code{demo("colors")} or a name of a \href{http://colorbrewer2.org}{color brewer} palette. Following options are valid for the \code{geom.colors} argument: \itemize{ @@ -209,7 +209,7 @@ sjp.grpfrq(efc$e17age, efc$e42dep, type = "box") # grouped bars sjp.grpfrq(efc$e42dep, efc$e16sex, title = NULL) -# box plots with interaction variable +# box plots with interaction variable sjp.grpfrq(efc$e17age, efc$e42dep, intr.var = efc$e16sex, type = "box") # Grouped bar plot @@ -217,7 +217,7 @@ sjp.grpfrq(efc$neg_c_7, efc$e42dep, show.values = FALSE) # same data as line plot sjp.grpfrq(efc$neg_c_7, efc$e42dep, type = "line") - + } \seealso{ \href{http://www.strengejacke.de/sjPlot/sjp.grpfrq/}{sjPlot manual: sjp.grpfrq} diff --git a/man/sjp.int.Rd b/man/sjp.int.Rd index 0e6ea7de..c8b445a6 100755 --- a/man/sjp.int.Rd +++ b/man/sjp.int.Rd @@ -16,7 +16,7 @@ sjp.int(fit, type = c("eff", "cond", "emm"), int.term = NULL, digits = 2, facet.grid = FALSE, prnt.plot = TRUE, ...) } \arguments{ -\item{fit}{the fitted (generalized) linear (mixed) model object, including interaction terms. Accepted model +\item{fit}{A fitted (generalized) linear (mixed) model object, including interaction terms. Accepted model classes are \itemize{ \item linear models (\code{\link{lm}}) @@ -29,23 +29,23 @@ classes are \item panel data estimators (\code{\link[plm]{plm}}) }} -\item{type}{interaction plot type. Use one of following values: +\item{type}{Interaction plot type. Use one of following values: \describe{ \item{\code{type = "eff"}}{(default) plots the overall moderation effect on the response value. See 'Details'.} \item{\code{type = "cond"}}{plots the mere \emph{change} of the moderating effect on the response value (conditional effect). See 'Details'.} \item{\code{type = "emm"}}{plots the estimated marginal means (least square means). If this type is chosen, not all function arguments are applicable. See 'Details'.} }} -\item{int.term}{name of interaction term of \code{fit} (as character), which should be plotted +\item{int.term}{Name of interaction term of \code{fit} (as character), which should be plotted when using \code{type = "eff"}. By default, this argument will be ignored (i.e. \code{int.term = NULL}). See 'Details'.} -\item{int.plot.index}{numeric vector with index numbers that indicate which +\item{int.plot.index}{Numeric vector with index numbers that indicate which interaction terms should be plotted in case the \code{fit} has more than one interaction. By default, this value is \code{NULL}, hence all interactions are plotted.} -\item{mdrt.values}{indicates which values of the moderator variable should be +\item{mdrt.values}{Indicates which values of the moderator variable should be used when plotting the interaction effects. \describe{ \item{\code{"minmax"}}{(default) minimum and maximum values (lower and upper bounds) of the moderator are used to plot the interaction between independent variable and moderator.} @@ -55,72 +55,72 @@ used when plotting the interaction effects. \item{\code{"all"}}{uses all values of the moderator variable. Note that this option only applies to \code{type = "eff"}, for numeric moderator values.} }} -\item{swap.pred}{if \code{TRUE}, the predictor on the x-axis and the moderator value in an interaction are +\item{swap.pred}{Logical, if \code{TRUE}, the predictor on the x-axis and the moderator value in an interaction are swapped. For \code{type = "eff"}, the first interaction term is used as moderator and the second term -is plotted at the x-axis. For \code{type = "cond"}, the interaction's predictor with less unique values is -printed along the x-axis. Default is \code{FALSE}, so the second predictor in an interaction, respectively +is plotted at the x-axis. For \code{type = "cond"}, the interaction's predictor with less unique values is +printed along the x-axis. Default is \code{FALSE}, so the second predictor in an interaction, respectively the predictor with more unique values is printed along the x-axis.} -\item{plevel}{indicates at which p-value an interaction term is considered as \emph{significant}, +\item{plevel}{Numeric, indicates at which p-value an interaction term is considered as \emph{significant}, i.e. at which p-level an interaction term will be considered for plotting. Default is 0.1 (10 percent), hence, non-significant interactions are excluded by default. This argument does not apply to \code{type = "eff"}.} -\item{diff}{if \code{FALSE} (default), the minimum and maximum interaction effects of the moderating variable +\item{diff}{Logical, if \code{FALSE} (default), the minimum and maximum interaction effects of the moderating variable is shown (one line each). if \code{TRUE}, only the difference between minimum and maximum interaction effect is shown (single line). Only applies to \code{type = "cond"}.} -\item{title}{default title used for the plots. Should be a character vector +\item{title}{Default title used for the plots. Should be a character vector of same length as interaction plots to be plotted. Default value is \code{NULL}, which means that each plot's title includes the dependent variable as well as the names of the interaction terms.} -\item{axis.title}{a default title used for the x-axis. Should be a character vector +\item{axis.title}{Default title used for the x-axis. Should be a character vector of same length as interaction plots to be plotted. Default value is \code{NULL}, which means that each plot's x-axis uses the predictor's name as title.} -\item{axis.labels}{character vector with value labels of the interaction, used +\item{axis.labels}{Character vector with value labels of the interaction, used to label the x-axis. Only applies to \code{type = "emm"}.} -\item{legend.title}{title of the plot's legend. A character vector of same length as +\item{legend.title}{Title of the plot's legend. A character vector of same length as amount of interaction plots to be plotted (i.e. one vector element for each plot's legend title).} -\item{legend.labels}{labels for the guide/legend. Either a character vector of same length as +\item{legend.labels}{Labels for the guide/legend. Either a character vector of same length as amount of legend labels of the plot, or a \code{list} of character vectors, if more than one interaction plot is plotted (i.e. one vector of legend labels for each interaction plot). -Default is \code{NULL}, so the name of the predictor with min/max-effect is used +Default is \code{NULL}, so the name of the predictor with min/max-effect is used as legend label.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{geom.colors}{vector of color values or name of a valid color brewer palette. -If not a color brewer palette name, \code{geom.colors} must be of same +\item{geom.colors}{Vector of color values or name of a valid color brewer palette. +If not a color brewer palette name, \code{geom.colors} must be of same length as moderator values used in the plot (see \code{mdrt.values}). See also 'Details' in \code{\link{sjp.grpfrq}}.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{fill.color}{fill color of the shaded area between the minimum and maximum lines. Default is \code{"grey"}. +\item{fill.color}{Fill color of the shaded area between the minimum and maximum lines. Default is \code{"grey"}. Either set \code{fill.color} to \code{NULL} or use 0 for \code{fill.alpha} if you want to hide the shaded area.} -\item{fill.alpha}{alpha value (transparancy) of the shaded area between the minimum and maximum lines. Default is 0.4. +\item{fill.alpha}{Alpha value (transparancy) of the shaded area between the minimum and maximum lines. Default is 0.4. Use either 0 or set \code{fill.color} to \code{NULL} if you want to hide the shaded area.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} -\item{jitter.ci}{logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +\item{jitter.ci}{Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence bands are displayed as error bars, adds jittering to lines and error bars to avoid overlapping.} @@ -128,32 +128,32 @@ to avoid overlapping.} F-tests with Kenward-Roger approximation for the df. Caution: Computation may take very long time for large samples!} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} -\item{xlim}{numeric vector of length two, defining lower and upper axis limits -of the x scale. By default, this argument is set to \code{NULL}, i.e. the +\item{xlim}{Numeric vector of length two, defining lower and upper axis limits +of the x scale. By default, this argument is set to \code{NULL}, i.e. the x-axis fits to the required range of the data.} \item{ylim}{numeric vector of length two, defining lower and upper axis limits -of the y scale. By default, this argument is set to \code{NULL}, i.e. the +of the y scale. By default, this argument is set to \code{NULL}, i.e. the y-axis fits to the required range of the data.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} -\item{...}{other arguments passed down to further functions. Currently, following +\item{...}{Other arguments passed down to further functions. Currently, following arguments are supported: \describe{ \item{\code{?effects::effect}}{ @@ -170,7 +170,7 @@ arguments are supported: as well as the data frames that were used for setting up the ggplot-objects (\code{data.list}). } \description{ -Plot regression (predicted values) or probability lines (predicted probabilities) of +Plot regression (predicted values) or probability lines (predicted probabilities) of significant interaction terms to better understand effects of moderations in regression models. This function accepts following fitted model classes: \itemize{ @@ -184,7 +184,7 @@ Plot regression (predicted values) or probability lines (predicted probabilities \item panel data estimators (\code{\link[plm]{plm}}) } Note that beside interaction terms, also the single predictors of each interaction (main effects) - must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, + must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, but \code{lm(dep ~ pred1:pred2)} won't! } \details{ @@ -195,23 +195,23 @@ Plot regression (predicted values) or probability lines (predicted probabilities You can pass further arguments down to \code{allEffects} for flexible function call via the \code{...}-argument. } - \item{\code{type = "cond"}}{plots the effective \emph{change} or \emph{impact} - (conditional effect) on a dependent variable of a moderation effect, as - described by Grace-Martin, i.e. the difference of the moderation effect on the - dependent variable in \emph{presence} and \emph{absence} of the moderating effect + \item{\code{type = "cond"}}{plots the effective \emph{change} or \emph{impact} + (conditional effect) on a dependent variable of a moderation effect, as + described by Grace-Martin, i.e. the difference of the moderation effect on the + dependent variable in \emph{presence} and \emph{absence} of the moderating effect (\emph{simple slope} plot or \emph{conditional effect}, see Hayes 2012). All remaining predictors are set to zero (i.e. ignored and not adjusted for). - Hence, this plot type may be used especially for \emph{binary or dummy coded} + Hence, this plot type may be used especially for \emph{binary or dummy coded} moderator values (see also Esarey and Summer 2015). This type \emph{does not} show the overall effect (marginal mean, i.e. adjusted - for all other predictors and covariates) of interactions on the result of Y. Use - \code{type = "eff"} for effect displays similar to the \code{\link[effects]{effect}}-function + for all other predictors and covariates) of interactions on the result of Y. Use + \code{type = "eff"} for effect displays similar to the \code{\link[effects]{effect}}-function from the \pkg{effects}-package. } \item{\code{type = "emm"}}{plots the estimated marginal means of repeated measures designs, - like two-way repeated measures AN(C)OVA. In detail, this type plots estimated marginal means + like two-way repeated measures AN(C)OVA. In detail, this type plots estimated marginal means (also called \emph{least square means} or \emph{marginal means}) of (significant) interaction terms. - The fitted models may be linear (mixed effects) + The fitted models may be linear (mixed effects) models of class \code{\link{lm}} or \code{\link[lme4]{merMod}}. This function may be used, for example, to plot differences in interventions between control and treatment groups over multiple time points. } @@ -226,7 +226,7 @@ Plot regression (predicted values) or probability lines (predicted probabilities } \note{ Note that beside interaction terms, also the single predictors of each interaction (main effects) - must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, + must be included in the fitted model as well. Thus, \code{lm(dep ~ pred1 * pred2)} will work, but \code{lm(dep ~ pred1:pred2)} won't! \cr \cr For \code{type = "emm"}, all interaction terms have to be factors. Furthermore, for \code{type = "eff"}, predictors of interactions that are introduced first into the model @@ -239,7 +239,7 @@ Note that beside interaction terms, also the single predictors of each interacti # fit "dummy" model. Note that moderator should enter # first the model, followed by predictor. Else, use -# argument "swap.pred" to change predictor on +# argument "swap.pred" to change predictor on # x-axis with moderator fit <- lm(weight ~ Diet * Time, data = ChickWeight) @@ -266,8 +266,8 @@ mydf$sex <- relevel(factor(mydf$sex), ref = "2") fit <- lm(usage ~ .*., data = mydf) summary(fit) -# plot interactions. note that type = "cond" only considers -# significant interactions by default. use "plevel" to +# plot interactions. note that type = "cond" only considers +# significant interactions by default. use "plevel" to # adjust p-level sensivity sjp.int(fit, type = "cond") @@ -300,7 +300,7 @@ fit <- glm(y ~ sex * barthel, data = mydf, family = binomial(link = "logit")) # plot interaction, increase p-level sensivity sjp.int(fit, type = "eff", legend.labels = get_labels(efc$c161sex), plevel = 0.1) sjp.int(fit, type = "cond", legend.labels = get_labels(efc$c161sex), plevel = 0.1) - + \dontrun{ # ------------------------------- # Plot estimated marginal means diff --git a/man/sjp.likert.Rd b/man/sjp.likert.Rd index b6ccb977..8957267f 100755 --- a/man/sjp.likert.Rd +++ b/man/sjp.likert.Rd @@ -16,7 +16,7 @@ sjp.likert(items, title = NULL, legend.title = NULL, legend.labels = NULL, expand.grid = TRUE, digits = 1, coord.flip = TRUE, prnt.plot = TRUE) } \arguments{ -\item{items}{\code{data.frame} with each column representing one item.} +\item{items}{Data frame, with each column representing one item.} \item{title}{character vector, used as plot title. Depending on plot type and function, will be set automatically. If \code{title = ""}, no title is printed. @@ -33,7 +33,7 @@ for the x-axis and y-axis.} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{catcount}{optional, amount of categories of \code{items} (e.g. \emph{"strongly disagree", +\item{catcount}{Optional, amount of categories of \code{items} (e.g. \emph{"strongly disagree", "disagree", "agree"} and \emph{"strongly agree"} would be \code{catcount = 4}). Note that this argument only applies to "valid" answers, i.e. if you have an additional neutral category (see \code{cat.neutral}) like \emph{"don't know"}, @@ -41,12 +41,12 @@ this won't count for \code{catcount} (e.g. "strongly disagree", "disagree", "agree", "strongly agree" and neutral category "don't know" would still mean that \code{catcount = 4}). See 'Note'.} -\item{cat.neutral}{if there's a neutral category (like "don't know" etc.), specify +\item{cat.neutral}{If there's a neutral category (like "don't know" etc.), specify the index number (value) for this category. Else, set \code{cat.neutral = NULL} (default). The proportions of neutral category answers are plotted as grey bars on the left side of the figure.} -\item{sort.frq}{indicates whether the items of \code{items} should be ordered by +\item{sort.frq}{Indicates whether the items of \code{items} should be ordered by total sum of positive or negative answers. \describe{ \item{\code{"pos.asc"}}{to order ascending by sum of positive answers} @@ -56,40 +56,40 @@ total sum of positive or negative answers. \item{\code{NULL}}{(default) for no sorting} }} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{title.wtd.suffix}{suffix (as string) for the title, if \code{weight.by} is specified, -e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +\item{title.wtd.suffix}{Suffix (as string) for the title, if \code{weight.by} is specified, +e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so title will not have a suffix when cases are weighted.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} -\item{cat.neutral.color}{color of the neutral category, if plotted (see \code{cat.neutral}).} +\item{cat.neutral.color}{Color of the neutral category, if plotted (see \code{cat.neutral}).} -\item{intercept.line.color}{color of the vertical intercept line that divides positive and negative values.} +\item{intercept.line.color}{Color of the vertical intercept line that divides positive and negative values.} -\item{reverse.colors}{logical, if \code{TRUE}, the color scale from \code{geom.colors} will be reversed, +\item{reverse.colors}{Logical, if \code{TRUE}, the color scale from \code{geom.colors} will be reversed, so positive and negative values switch colors.} -\item{values}{determines style and position of percentage value labels on the bars: +\item{values}{Determines style and position of percentage value labels on the bars: \describe{ \item{\code{"show"}}{(default) shows percentage value labels in the middle of each category bar} \item{\code{"hide"}}{hides the value labels, so no percentage values on the bars are printed} @@ -103,9 +103,9 @@ group or category to the labels.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.prc.sign}{logical, if \code{TRUE}, \%-signs for value labels are shown.} +\item{show.prc.sign}{Logical, if \code{TRUE}, \%-signs for value labels are shown.} -\item{grid.range}{numeric, limits of the x-axis-range, as proportion of 100. +\item{grid.range}{Numeric, limits of the x-axis-range, as proportion of 100. Default is 1, so the x-scale ranges from zero to 100\% on both sides from the center. You can use values beyond 1 (100\%) in case bar labels are not printed because they exceed the axis range. @@ -113,13 +113,13 @@ E.g. \code{grid.range = 1.4} will set the axis from -140 to +140\%, however, onl (valid) axis labels from -100 to +100\% are printed. Neutral categories are adjusted to the most left limit.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{expand.grid}{logical, if \code{TRUE}, the plot grid is expanded, i.e. there is a small margin between axes and plotting region. Default is \code{FALSE}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} @@ -146,27 +146,6 @@ Note that only even numbers of categories are possible to plot, so the "positive with the \code{catcount}-argument. } \examples{ -# prepare data for 4-category likert scale, with neutral category 5 items -Q1 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.2, .3, .1, .4))) -Q2 <- as.factor(sample(1:5, 500, replace = TRUE, prob = c(.5, .25, .12, .09, .03))) -Q3 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.25, .1, .4, .25))) -Q4 <- as.factor(sample(1:5, 500, replace = TRUE, prob = c(.1, .3, .38, .1, .12))) -Q5 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(.35, .25, .15, .25))) - -likert_4 <- data.frame(Q1, Q2, Q3, Q4, Q5) - -# create labels -levels_4 <- c("Strongly agree", "Agree", "Disagree", - "Strongly Disagree", "Don't know") - -# create item labels -items <- c("Q1", "Q2", "Q3", "Q4", "Q5") - -# plot 4-category-likert-scale, no sorting -sjp.likert(likert_4, cat.neutral = 5, legend.labels = levels_4, - axis.labels = items, grid.range = 1.2, expand.grid = FALSE, - values = "sum.outside", show.prc.sign = TRUE) - # Data from the EUROFAMCARE sample dataset library(dplyr) library(sjmisc) @@ -175,6 +154,14 @@ data(efc) # variable name, and then plot that subset as likert-plot efc[, find_var(efc, "cop")] \%>\% sjp.likert() +sjp.likert( + find_var(efc, "cop", as.df = TRUE), + grid.range = 1.2, + expand.grid = FALSE, + values = "sum.outside", + show.prc.sign = TRUE +) + } \seealso{ \href{http://www.strengejacke.de/sjPlot/sjp.likert/}{sjPlot manual: sjp.likert} diff --git a/man/sjp.lm.Rd b/man/sjp.lm.Rd index 410ea591..55c9337e 100755 --- a/man/sjp.lm.Rd +++ b/man/sjp.lm.Rd @@ -18,9 +18,9 @@ sjp.lm(fit, type = "lm", vars = NULL, group.estimates = NULL, complete.dgns = FALSE, prnt.plot = TRUE, ...) } \arguments{ -\item{fit}{fitted linear regression model (of class \code{\link{lm}}, \code{\link[nlme]{gls}} or \code{plm}).} +\item{fit}{Fitted linear regression model (of class \code{\link{lm}}, \code{\link[nlme]{gls}} or \code{plm}).} -\item{type}{type of plot. Use one of following: +\item{type}{Type of plot. Use one of following: \describe{ \item{\code{"lm"}}{(default) for forest-plot like plot of estimates. If the fitted model only contains one predictor, intercept and slope are plotted.} \item{\code{"std"}}{for forest-plot like plot of standardized beta values. If the fitted model only contains one predictor, intercept and slope are plotted.} @@ -34,21 +34,21 @@ sjp.lm(fit, type = "lm", vars = NULL, group.estimates = NULL, \item{\code{"vif"}}{to plot Variance Inflation Factors.} }} -\item{vars}{numeric vector with column indices of selected variables or a character vector with +\item{vars}{Numeric vector with column indices of selected variables or a character vector with variable names of selected variables from the fitted model, which should be used to plot - depending on \code{type} - estimates, fixed effects slopes or predicted values (mean, probabilities, incidents rates, ...). See 'Examples'.} -\item{group.estimates}{numeric or character vector, indicating a group identifier for +\item{group.estimates}{Numeric or character vector, indicating a group identifier for each estimate. Dots and confidence intervals of estimates are coloured according to their group association. See 'Examples'.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{sort.est}{logical, determines whether estimates should be sorted according to their values. +\item{sort.est}{Logical, determines whether estimates should be sorted according to their values. If \code{group.estimates} is \emph{not} \code{NULL}, estimates are sorted according to their group assignment.} @@ -61,29 +61,32 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{resp.label}{name of dependent variable, as string. Only +\item{resp.label}{Name of dependent variable, as string. Only used if fitted model has only one predictor and \code{type = "lm"}.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector @@ -92,25 +95,25 @@ of same length as groups. See 'Examples'.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may also be a list of vectors of length 2, defining axis limits for each plot (only if non-faceted).} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and @@ -124,48 +127,48 @@ will be plotted. Default is \code{FALSE}. Only applies, if \code{show.loess = TR (and for \code{\link{sjp.lmer}}, only applies if \code{type = "fe.slope"} or \code{type = "fe.resid"}).} -\item{show.summary}{logical, if \code{TRUE}, a summary with model statistics +\item{show.summary}{Logical, if \code{TRUE}, a summary with model statistics is added to the plot.} -\item{show.scatter}{logical, if \code{TRUE} (default), adds a scatter plot of +\item{show.scatter}{Logical, if \code{TRUE} (default), adds a scatter plot of data points to the plot. Only applies for slope-type or predictions plots. For most plot types, dots are jittered to avoid overplotting, hence the points don't reflect exact values in the data.} -\item{point.alpha}{alpha value of point-geoms in the scatter plots. Only applies, +\item{point.alpha}{Alpha value of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{point.color}{color of of point-geoms in the scatter plots. Only applies, +\item{point.color}{Color of of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{jitter.ci}{logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +\item{jitter.ci}{Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence bands are displayed as error bars, adds jittering to lines and error bars to avoid overlapping.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} -\item{complete.dgns}{logical, if \code{TRUE}, additional tests are performed. Default is \code{FALSE} +\item{complete.dgns}{Logical, if \code{TRUE}, additional tests are performed. Default is \code{FALSE} Only applies if \code{type = "ma"}.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} -\item{...}{other arguments passed down to further functions. Currently, following +\item{...}{Other arguments passed down to further functions. Currently, following arguments are supported: \describe{ \item{\code{?effects::effect}}{ diff --git a/man/sjp.lmer.Rd b/man/sjp.lmer.Rd index 780e434a..fcc943ab 100755 --- a/man/sjp.lmer.Rd +++ b/man/sjp.lmer.Rd @@ -40,34 +40,34 @@ sjp.lmer(fit, type = "re", vars = NULL, ri.nr = NULL, \item{\code{"ma"}}{to check model assumptions. Note that no further arguments except \code{fit} are relevant for this option. All other arguments are ignored.} }} -\item{vars}{numeric vector with column indices of selected variables or a character vector with +\item{vars}{Numeric vector with column indices of selected variables or a character vector with variable names of selected variables from the fitted model, which should be used to plot - depending on \code{type} - estimates, fixed effects slopes or predicted values (mean, probabilities, incidents rates, ...). See 'Examples'.} -\item{ri.nr}{numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, +\item{ri.nr}{Numeric vector. If \code{type = "re"} or \code{type = "ri.slope"}, and fitted model has more than one random intercept, \code{ri.nr} indicates which random effects of which random intercept (or: which list elements of \code{\link[lme4]{ranef}}) will be plotted. Default is \code{NULL}, so all random effects will be plotted.} -\item{group.estimates}{numeric or character vector, indicating a group identifier for +\item{group.estimates}{Numeric or character vector, indicating a group identifier for each estimate. Dots and confidence intervals of estimates are coloured according to their group association. See 'Examples'.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{emph.grp}{numeric vector with index numbers of grouping levels (from random effect). +\item{emph.grp}{Numeric vector with index numbers of grouping levels (from random effect). If \code{type = "ri.slope"} and \code{facet.grid = FALSE}, an integrated plot of predicted probabilities of fixed effects resp. fixed effects slopes for each grouping level is plotted. To better find certain groups, use this argument to emphasize these groups in the plot. See 'Examples'.} -\item{sample.n}{numeric vector. only applies, if \code{type = "rs.ri"}. If +\item{sample.n}{Numeric vector. only applies, if \code{type = "rs.ri"}. If plot has many random intercepts (grouping levels), overplotting of regression lines may occur. In this case, consider random sampling of grouping levels. If \code{sample.n} is of length 1, a random sample @@ -81,7 +81,7 @@ random effects for plotting (useful when ecomparing multiple models).} specified, if \code{type = "poly"}, in order to plot marginal effects for polynomial terms. See 'Examples'.} -\item{sort.est}{determines in which way estimates are sorted in the plot: +\item{sort.est}{Determines in which way estimates are sorted in the plot: \itemize{ \item If \code{NULL} (default), no sorting is done and estimates are sorted in order of model coefficients. \item If \code{sort.est = "sort.all"}, estimates are re-sorted for each coefficient (only applies if \code{type = "re"} and \code{facet.grid = FALSE}), i.e. the estimates of the random effects for each predictor are sorted and plotted to an own plot. @@ -90,30 +90,33 @@ for polynomial terms. See 'Examples'.} } See 'Examples'.} -\item{title}{character vector with one or more labels that are used as plot title.} +\item{title}{Character vector with one or more labels that are used as plot title.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} -\item{axis.labels}{character vector with labels for the model terms, used as axis labels. +\item{axis.labels}{Character vector with labels for the model terms, used as axis labels. For mixed models, should either be vector of fixed effects variable labels (if \code{type = "fe"} or \code{type = "fe.std"}) or a vector of group (value) labels from the random intercept's categories (if \code{type = "re"}).} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector @@ -121,10 +124,10 @@ of same length as groups. See 'Examples'.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and @@ -138,65 +141,65 @@ will be plotted. Default is \code{FALSE}. Only applies, if \code{show.loess = TR (and for \code{\link{sjp.lmer}}, only applies if \code{type = "fe.slope"} or \code{type = "fe.resid"}).} -\item{show.intercept}{logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +\item{show.intercept}{Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential transformation of estimates, the intercept in some cases can not be calculated, thus the function call is interrupted and no plot printed.} -\item{string.interc}{string, axis label of intercept estimate. Only applies, +\item{string.interc}{String, axis label of intercept estimate. Only applies, if \code{show.intercept = TRUE} and \code{axis.labels} is not \code{NULL}.} \item{p.kr}{logical, if \code{TRUE}, p-value estimation is based on conditional F-tests with Kenward-Roger approximation for the df. Caution: Computation may take very long time for large samples!} -\item{show.scatter}{logical, if \code{TRUE} (default), adds a scatter plot of +\item{show.scatter}{Logical, if \code{TRUE} (default), adds a scatter plot of data points to the plot. Only applies for slope-type or predictions plots. For most plot types, dots are jittered to avoid overplotting, hence the points don't reflect exact values in the data.} -\item{point.alpha}{alpha value of point-geoms in the scatter plots. Only applies, +\item{point.alpha}{Alpha value of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{point.color}{color of of point-geoms in the scatter plots. Only applies, +\item{point.color}{Color of of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{jitter.ci}{logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence +\item{jitter.ci}{Logical, if \code{TRUE} and \code{show.ci = TRUE} and confidence bands are displayed as error bars, adds jittering to lines and error bars to avoid overlapping.} -\item{fade.ns}{if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} +\item{fade.ns}{Logical, if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may also be a list of vectors of length 2, defining axis limits for each plot (only if non-faceted).} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} -\item{free.scale}{if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid +\item{free.scale}{Logical, if \code{TRUE} and \code{facet.grid = TRUE}, each facet grid gets its own fitted scale. If \code{free.scale = FALSE}, each facet in the grid has the same scale range.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} -\item{...}{other arguments passed down to further functions. Currently, following +\item{...}{Other arguments passed down to further functions. Currently, following arguments are supported: \describe{ \item{\code{?effects::effect}}{ diff --git a/man/sjp.lmm.Rd b/man/sjp.lmm.Rd index 0bac8c72..8bd3a034 100755 --- a/man/sjp.lmm.Rd +++ b/man/sjp.lmm.Rd @@ -27,7 +27,7 @@ each model with comma. See 'Examples'.} \item{\code{"std2"}}{for forest-plot like plot of standardized beta values, however, standardization is done by rescaling estimates by dividing them by two sd (see 'Details' in \code{\link{sjp.lm}}).} }} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} @@ -37,10 +37,10 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{legend.title}{character vector, used as title for the plot legend. Note that +\item{legend.title}{Character vector, used as title for the plot legend. Note that only some plot types have legends (e.g. \code{type = "pred"} or when grouping estimates with \code{group.estimates}).} @@ -50,15 +50,18 @@ indicates the p-values. Default is \code{"p-level"}. Only applies if \code{p.sha \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{axis.lim}{numeric vector of length 2, defining the range of the plot axis. +\item{axis.lim}{Numeric vector of length 2, defining the range of the plot axis. Depending on plot type, may effect either x- or y-axis, or both. For multiple plot outputs (e.g., from \code{type = "eff"} or \code{type = "slope"} in \code{\link{sjp.glm}}), \code{axis.lim} may @@ -68,23 +71,23 @@ plot (only if non-faceted).} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.spacing}{spacing between the dots and error bars of the plotted fitted models. Default is 0.3.} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector @@ -95,12 +98,12 @@ of same length as groups. See 'Examples'.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.intercept}{logical, if \code{TRUE}, the intercept of the fitted model is also plotted. +\item{show.intercept}{Logical, if \code{TRUE}, the intercept of the fitted model is also plotted. Default is \code{FALSE}. For \code{glm}'s, please note that due to exponential transformation of estimates, the intercept in some cases can not be calculated, thus the function call is interrupted and no plot printed.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} \item{fade.ns}{if \code{TRUE}, non significant estimates will be printed in slightly faded colors.} @@ -112,16 +115,16 @@ legend is plotted. Default is \code{FALSE}.} F-tests with Kenward-Roger approximation for the df. Caution: Computation may take very long time for large samples!} -\item{vline.type}{linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} +\item{vline.type}{Linetype of the vertical "zero point" line. Default is \code{2} (dashed line).} -\item{vline.color}{color of the vertical "zero point" line. Default value is \code{"grey70"}.} +\item{vline.color}{Color of the vertical "zero point" line. Default value is \code{"grey70"}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} diff --git a/man/sjp.pca.Rd b/man/sjp.pca.Rd index b192660c..f775c657 100755 --- a/man/sjp.pca.Rd +++ b/man/sjp.pca.Rd @@ -11,18 +11,18 @@ sjp.pca(data, rotation = c("varimax", "oblimin"), nmbr.fctr = NULL, show.values = TRUE, show.cronb = TRUE, prnt.plot = TRUE) } \arguments{ -\item{data}{\code{data.frame} that should be used to compute a PCA, or a \code{\link{prcomp}} object.} +\item{data}{A data frame that should be used to compute a PCA, or a \code{\link{prcomp}} object.} -\item{rotation}{rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation +\item{rotation}{Rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation or \code{"oblimin"} for oblique transformation.} -\item{nmbr.fctr}{number of factors used for calculating the varimax +\item{nmbr.fctr}{Number of factors used for calculating the varimax rotation. By default, this value is \code{NULL} and the amount of factors is calculated according to the Kaiser-criteria.} -\item{fctr.load.tlrn}{specifies the minimum difference a variable needs to have between +\item{fctr.load.tlrn}{Specifies the minimum difference a variable needs to have between factor loadings (components) in order to indicate a clear loading on just one factor and not -diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading +diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading on 3 possible factors can not be clearly assigned to just one factor and thus would be removed from the principal component analysis. By default, the minimum difference of loading values between the highest and 2nd highest factor should be 0.1} @@ -30,7 +30,7 @@ between the highest and 2nd highest factor should be 0.1} \item{plot.eigen}{If \code{TRUE}, a plot showing the Eigenvalues according to the Kaiser criteria is plotted to determine the number of factors.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} \item{title}{character vector, used as plot title. Depending on plot type and function, will be set automatically. If \code{title = ""}, no title is printed. @@ -40,12 +40,12 @@ to define titles for each sub-plot or facet.} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{type}{Plot type resp. geom type. May be one of following: \code{"circle"} or \code{"tile"} +\item{type}{Plot type resp. geom type. May be one of following: \code{"circle"} or \code{"tile"} circular or tiled geoms, or \code{"bar"} for a bar plot. You may use initial letter only for this argument.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} @@ -53,12 +53,12 @@ need smaller values than dot sizes.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} \item{show.values}{logical, whether values should be plotted or not.} -\item{show.cronb}{logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, +\item{show.cronb}{Logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, i.e. all variables with the highest loading for a factor are taken for the reliability test. The result is an alpha value for each factor dimension. Only applies when \code{data} is a data frame and no \code{\link{prcomp}} object.} @@ -69,7 +69,7 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v \value{ (Invisibly) returns a \code{\link{structure}} with \itemize{ - \item the varimax-rotated factor loading matrix (\code{varim}) + \item the rotated factor loading matrix (\code{varim}) \item the column indices of removed variables (for more details see next list item) (\code{removed.colindex}) \item an updated data frame containing all factors that have a clear loading on a specific scale in case \code{data} was a data frame (See argument \code{fctr.load.tlrn} for more details) (\code{removed.df}) \item the \code{factor.index}, i.e. the column index of each variable with the highest factor loading for each factor, @@ -78,68 +78,35 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v } } \description{ -Performes a principle component analysis on a data frame or matrix (with - varimax rotation) and plots the factor solution as ellipses or tiles. \cr \cr - In case a data frame is used as argument, the cronbach's alpha value for - each factor scale will be calculated, i.e. all variables with the highest - loading for a factor are taken for the reliability test. The result is +Performs a principle component analysis on a data frame or matrix (with + varimax or oblimin rotation) and plots the factor solution as ellipses or tiles. \cr \cr + In case a data frame is used as argument, the cronbach's alpha value for + each factor scale will be calculated, i.e. all variables with the highest + loading for a factor are taken for the reliability test. The result is an alpha value for each factor dimension. } -\note{ -This PCA uses the \code{\link{prcomp}} function and the \code{\link{varimax}} rotation. -} \examples{ -# randomly create data frame with 7 items, each consisting of 4 categories -likert_4 <- data.frame( - sample(1:4, 500, replace = TRUE, prob = c(0.2, 0.3, 0.1, 0.4)), - sample(1:4, 500, replace = TRUE, prob = c(0.5, 0.25, 0.15, 0.1)), - sample(1:4, 500, replace = TRUE, prob = c(0.4, 0.15, 0.25, 0.2)), - sample(1:4, 500, replace = TRUE, prob = c(0.25, 0.1, 0.4, 0.25)), - sample(1:4, 500, replace = TRUE, prob = c(0.1, 0.4, 0.4, 0.1)), - sample(1:4, 500, replace = TRUE), - sample(1:4, 500, replace = TRUE, prob = c(0.35, 0.25, 0.15, 0.25)) -) - -# Create variable labels -colnames(likert_4) <- c("V1", "V2", "V3", "V4", "V5", "V6", "V7") - -# plot results from PCA as square-tiled "heatmap" -sjp.pca(likert_4, type = "tile") - -# plot results from PCA as bars -sjp.pca(likert_4, type = "bar") - -# manually compute PCA -pca <- prcomp(na.omit(likert_4), retx = TRUE, center = TRUE, scale. = TRUE) -# plot results from PCA as circles, including Eigenvalue-diagnostic. -# note that this plot does not compute the Cronbach's Alpha -sjp.pca(pca, plot.eigen = TRUE, type = "circle", geom.size = 10) - -# ------------------------------- -# Data from the EUROFAMCARE sample dataset -# ------------------------------- library(sjmisc) data(efc) - -# retrieve variable and value labels -varlabs <- get_label(efc) - # recveive first item of COPE-index scale start <- which(colnames(efc) == "c82cop1") # recveive last item of COPE-index scale end <- which(colnames(efc) == "c90cop9") - -# create data frame with COPE-index scale -mydf <- data.frame(efc[, c(start:end)]) -colnames(mydf) <- varlabs[c(start:end)] - -sjp.pca(mydf) -sjp.pca(mydf, type = "tile") - -# ------------------------------- -# auto-detection of labels -# ------------------------------- -sjp.pca(efc[, c(start:end)], type = "circle", geom.size = 10) + +# manually compute PCA +pca <- prcomp( + na.omit(efc[, start:end]), + retx = TRUE, + center = TRUE, + scale. = TRUE +) +# plot results from PCA as circles, including Eigenvalue-diagnostic. +# note that this plot does not compute the Cronbach's Alpha +sjp.pca(pca, plot.eigen = TRUE, type = "circle", geom.size = 10) + +# use data frame as argument, let sjp.pca() compute PCA +sjp.pca(efc[, start:end]) +sjp.pca(efc[, start:end], type = "tile") } diff --git a/man/sjp.poly.Rd b/man/sjp.poly.Rd index f218e0df..48c17f74 100755 --- a/man/sjp.poly.Rd +++ b/man/sjp.poly.Rd @@ -11,72 +11,75 @@ sjp.poly(x, poly.term, poly.degree, poly.scale = FALSE, fun = NULL, loess.color = "#808080", prnt.plot = TRUE) } \arguments{ -\item{x}{a vector, representing the response variable of a linear (mixed) model; or +\item{x}{A vector, representing the response variable of a linear (mixed) model; or a linear (mixed) model as returned by \code{\link{lm}} or \code{\link[lme4]{lmer}}.} -\item{poly.term}{if \code{x} is a vector, \code{poly.term} should also be a vector, representing +\item{poly.term}{If \code{x} is a vector, \code{poly.term} should also be a vector, representing the polynomial term (independent variabl) in the model; if \code{x} is a fitted model, \code{poly.term} should be the polynomial term's name as character string. See 'Examples'.} -\item{poly.degree}{numeric, or numeric vector, indicating the degree of the polynomial. +\item{poly.degree}{Numeric, or numeric vector, indicating the degree of the polynomial. If \code{poly.degree} is a numeric vector, multiple polynomial curves for each degree are plotted. See 'Examples'.} -\item{poly.scale}{logical, if \code{TRUE}, \code{poly.term} will be scaled before +\item{poly.scale}{Logical, if \code{TRUE}, \code{poly.term} will be scaled before linear regression is computed. Default is \code{FALSE}. Scaling the polynomial term may have an impact on the resulting p-values.} -\item{fun}{linear function when modelling polynomial terms. Use \code{fun = "lm"} +\item{fun}{Linear function when modelling polynomial terms. Use \code{fun = "lm"} for linear models, or \code{fun = "glm"} for generalized linear models. When \code{x} is not a vector, but a fitted model object, the function is detected automatically. If \code{x} is a vector, \code{fun} defaults to \code{"lm"}.} -\item{axis.title}{character vector of length one or two (depending on +\item{axis.title}{Character vector of length one or two (depending on the plot function and type), used as title(s) for the x and y axis. If not specified, a default labelling is chosen. To set multiple axis titles (e.g. with \code{type = "eff"} for many predictors), \code{axis.title} must be a character vector of same length of plots that are printed. In this case, each plot gets an own axis title -(applying, for instance, to the y-axis for \code{type = "eff"}).} +(applying, for instance, to the y-axis for \code{type = "eff"}). +\strong{Note:} Some plot types do not support this argument. In such +cases, use the return value and add axis titles manually with +\code{\link[ggplot2]{labs}}, e.g.: \code{$plot.list[[1]] + labs(x = ...)}} -\item{geom.colors}{user defined color palette for geoms. If \code{group.estimates} +\item{geom.colors}{User defined color palette for geoms. If \code{group.estimates} is \emph{not} specified, must either be vector with two color values or a specific color palette code (see 'Details' in \code{\link{sjp.grpfrq}}). Else, if \code{group.estimates} is specified, \code{geom.colors} must be a vector of same length as groups. See 'Examples'.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{show.loess}{If \code{TRUE}, an additional loess-smoothed line is plotted.} +\item{show.loess}{Logical, if \code{TRUE}, an additional loess-smoothed line is plotted.} -\item{show.loess.ci}{If \code{TRUE}, a confidence region for the loess-smoothed line +\item{show.loess.ci}{Logical, if \code{TRUE}, a confidence region for the loess-smoothed line will be plotted.} -\item{show.p}{logical, if \code{TRUE} (default), p-values for polynomial terms are +\item{show.p}{Logical, if \code{TRUE} (default), p-values for polynomial terms are printed to the console.} -\item{show.scatter}{logical, if \code{TRUE} (default), adds a scatter plot of +\item{show.scatter}{Logical, if \code{TRUE} (default), adds a scatter plot of data points to the plot. Only applies for slope-type or predictions plots. For most plot types, dots are jittered to avoid overplotting, hence the points don't reflect exact values in the data.} -\item{point.alpha}{alpha value of point-geoms in the scatter plots. Only applies, +\item{point.alpha}{Alpha value of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{point.color}{color of of point-geoms in the scatter plots. Only applies, +\item{point.color}{Color of of point-geoms in the scatter plots. Only applies, if \code{show.scatter = TRUE}.} -\item{loess.color}{color of the loess-smoothed line. Only applies, if \code{show.loess = TRUE}.} +\item{loess.color}{Color of the loess-smoothed line. Only applies, if \code{show.loess = TRUE}.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't want to plot any graphs. In either case, the ggplot-object will be returned as value.} } \value{ -(insisibily) returns +(Insisibily) returns \describe{ \item{\code{plot}}{the ggplot-object with the complete plot} \item{\code{df}}{the data frame that was used for setting up the ggplot-object} @@ -94,10 +97,10 @@ This function plots a scatter plot of a term \code{poly.term} For each polynomial degree, a simple linear regression on \code{x} (resp. the extracted response, if \code{x} is a fitted model) is performed, where only the polynomial term \code{poly.term} is included as independent variable. - Thus, \code{lm(y ~ x + I(x^2) + ... + I(x^i))} is repeatedly computed + Thus, \code{lm(y ~ x + I(x^2) + ... + I(x^i))} is repeatedly computed for all values in \code{poly.degree}, and the predicted values of the reponse are plotted against the raw values of \code{poly.term}. - If \code{x} is a fitted model, other covariates are ignored when + If \code{x} is a fitted model, other covariates are ignored when finding the best fitting polynomial. \cr \cr This function evaluates raw polynomials, \emph{not orthogonal} polynomials. Polynomials are computed using the \code{\link{poly}} function, diff --git a/man/sjp.resid.Rd b/man/sjp.resid.Rd index e0785677..bc691279 100755 --- a/man/sjp.resid.Rd +++ b/man/sjp.resid.Rd @@ -8,27 +8,27 @@ sjp.resid(fit, geom.size = 2, remove.estimates = NULL, show.lines = TRUE, show.resid = TRUE, show.pred = TRUE, show.ci = F, prnt.plot = TRUE) } \arguments{ -\item{fit}{fitted linear (mixed) regression model (including objects of class +\item{fit}{Fitted linear (mixed) regression model (including objects of class \code{\link[nlme]{gls}} or \code{plm}).} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} -\item{remove.estimates}{character vector with coefficient names that indicate +\item{remove.estimates}{Character vector with coefficient names that indicate which estimates should be removed from the plot. \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{show.lines}{logical, if \code{TRUE}, a line connecting predicted and +\item{show.lines}{Logical, if \code{TRUE}, a line connecting predicted and residual values is plotted. Set this argument to \code{FALSE}, if plot-building is too time consuming.} -\item{show.resid}{logical, if \code{TRUE}, residual values are plotted.} +\item{show.resid}{Logical, if \code{TRUE}, residual values are plotted.} -\item{show.pred}{logical, if \code{TRUE}, predicted values are plotted.} +\item{show.pred}{Logical, if \code{TRUE}, predicted values are plotted.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't @@ -42,8 +42,8 @@ want to plot any graphs. In either case, the ggplot-object will be returned as v \description{ This function plots observed and predicted values of the response of linear (mixed) models for each coefficient and highlights the - observed values according to their distance (residuals) to the - predicted values. This allows to investigate how well actual and + observed values according to their distance (residuals) to the + predicted values. This allows to investigate how well actual and predicted values of the outcome fit across the predictor variables. } \note{ diff --git a/man/sjp.scatter.Rd b/man/sjp.scatter.Rd index 480afeec..baa3bc26 100755 --- a/man/sjp.scatter.Rd +++ b/man/sjp.scatter.Rd @@ -15,15 +15,15 @@ sjp.scatter(x = NULL, y = NULL, grp = NULL, title = "", facet.grid = FALSE, prnt.plot = TRUE) } \arguments{ -\item{x}{vector indicating the x positions. If not specified (i.e. if +\item{x}{Vector indicating the x positions. If not specified (i.e. if \code{NULL}), a range from 1 to length of \code{y} is used to spread the dots along the x axis.} -\item{y}{vector indicating the y positions. If not specified (i.e. if +\item{y}{Vector indicating the y positions. If not specified (i.e. if \code{NULL}), a range from 1 to length of \code{x} is used to spread the dots along the y axis.} -\item{grp}{grouping variable. If not \code{NULL}, the scatter plot will be grouped. See +\item{grp}{Grouping variable. If not \code{NULL}, the scatter plot will be grouped. See 'Examples'. Default is \code{NULL}, i.e. not grouping is done.} \item{title}{character vector, used as plot title. Depending on plot type and function, @@ -35,8 +35,8 @@ to define titles for each sub-plot or facet.} \item{legend.labels}{character vector with labels for the guide/legend.} -\item{dot.labels}{character vector with names for each coordinate pair given -by \code{x} and \code{y}, so text labels are added to the plot. +\item{dot.labels}{Character vector with names for each coordinate pair given +by \code{x} and \code{y}, so text labels are added to the plot. Must be of same length as \code{x} and \code{y}. If \code{dot.labels} has a different length, data points will be trimmed to match \code{dot.labels}. If \code{dot.labels = NULL} (default), @@ -48,14 +48,14 @@ for the x-axis and y-axis.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{label.size}{Size of text labels if argument \code{dot.labels} is used.} @@ -65,47 +65,47 @@ need smaller values than dot sizes.} \item{show.axis.values}{logical, whether category, count or percentage values for the axis should be printed or not.} -\item{fit.line.grps}{logical, if \code{TRUE}, a fitted line for each group +\item{fit.line.grps}{Logical, if \code{TRUE}, a fitted line for each group is drawn. See \code{fitmethod} to change the fit method of the fitted lines.} -\item{fit.line}{logical, if \code{TRUE}, a fitted line for the overall +\item{fit.line}{Logical, if \code{TRUE}, a fitted line for the overall scatterplot is drawn. See \code{fitmethod} to change the fit method of the fitted line.} -\item{show.ci}{logical, if \code{TRUE}, depending on \code{type}, a confidence +\item{show.ci}{Logical, if \code{TRUE}, depending on \code{type}, a confidence interval or region is added to the plot.} \item{fitmethod}{By default, a linear method (\code{"lm"}) is used for fitting the fit lines. Possible values are for instance \code{"lm"}, \code{"glm"}, \code{"loess"} or \code{"auto"}.} -\item{jitter.dots}{logical, if \code{TRUE}, points will be jittered (to avoid overplotting).} +\item{jitter.dots}{Logical, if \code{TRUE}, points will be jittered (to avoid overplotting).} -\item{emph.dots}{logical, if \code{TRUE}, overlapping points at same coordinates +\item{emph.dots}{Logical, if \code{TRUE}, overlapping points at same coordinates will be becomme larger, so point size indicates amount of overlapping.} -\item{auto.jitter}{logical, if \code{TRUE}, points will be jittered according +\item{auto.jitter}{Logical, if \code{TRUE}, points will be jittered according to an overlap-estimation. A matrix of \code{x} and \code{y} values is created and the amount of cells (indicating a unique point position) is calculated. If more than 15\% (see \code{jitter.ratio}) of the approximated amount of unique point coordinates seem to overlap, they are automatically jittered.} -\item{jitter.ratio}{ratio of tolerated overlapping (see \code{auto.jitter}). +\item{jitter.ratio}{Ratio of tolerated overlapping (see \code{auto.jitter}). If approximated amount of overlapping points exceed this ratio, they are automatically jittered. Default is 0.15. Valid values range between 0 and 1.} -\item{show.rug}{logical, if \code{TRUE}, a marginal rug plot is displayed +\item{show.rug}{Logical, if \code{TRUE}, a marginal rug plot is displayed in the graph.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots -in a grid of an integrated single plot. This argument calls +\item{facet.grid}{\code{TRUE} to arrange the lay out of of multiple plots +in a grid of an integrated single plot. This argument calls \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} -to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects +to arrange plots. Use \code{\link{plot_grid}} to plot multiple plot-objects as an arranged grid with \code{\link[gridExtra]{grid.arrange}}.} \item{prnt.plot}{logical, if \code{TRUE} (default), plots the results as graph. Use \code{FALSE} if you don't @@ -154,12 +154,12 @@ fit <- lm(neg_c_7 ~ quol_5, data = efc) sjp.scatter(y = fit$residuals, fit.line = TRUE) # "hide" axis titles -sjp.scatter(efc$c160age, efc$e17age, efc$e42dep, title = "", +sjp.scatter(efc$c160age, efc$e17age, efc$e42dep, title = "", axis.titles = c("", "")) # plot text labels pl <- c(1:10) -for (i in 1:10) +for (i in 1:10) pl[i] <- paste(sample(c(0:9, letters, LETTERS), 8, replace = TRUE), collapse = "") sjp.scatter(runif(10), runif(10), dot.labels = pl) diff --git a/man/sjp.setTheme.Rd b/man/sjp.setTheme.Rd index 4d1e5ac4..af22e920 100755 --- a/man/sjp.setTheme.Rd +++ b/man/sjp.setTheme.Rd @@ -37,7 +37,7 @@ metrics from \code{theme_gray()} are used. See 'Details'.} \item{theme.font}{base font family for the plot.} -\item{title.color}{color of plot title. Default is \code{"black"}.} +\item{title.color}{Color of plot title. Default is \code{"black"}.} \item{title.size}{size of plot title. Default is 1.3.} @@ -46,7 +46,7 @@ metrics from \code{theme_gray()} are used. See 'Details'.} \item{title.vjust}{numeric, vertical adjustment for plot title.} -\item{geom.outline.color}{color of geom outline. Only applies, if \code{geom.outline.size} +\item{geom.outline.color}{Color of geom outline. Only applies, if \code{geom.outline.size} is larger than 0.} \item{geom.outline.size}{size of bar outlines. Default is 0.1. Use @@ -55,7 +55,7 @@ size of \code{0} to remove geom outline.} \item{geom.boxoutline.size}{size of outlines and median bar especially for boxplots. Default is 0.5. Use size of \code{0} to remove boxplot outline.} -\item{geom.boxoutline.color}{color of outlines and median bar especially for boxplots. +\item{geom.boxoutline.color}{Color of outlines and median bar especially for boxplots. Only applies, if \code{geom.boxoutline.size} is larger than 0.} \item{geom.alpha}{specifies the transparancy (alpha value) of geoms} @@ -66,7 +66,7 @@ Only applies, if \code{geom.boxoutline.size} is larger than 0.} \item{geom.errorbar.linetype}{linetype of error bars. Default is \code{1} (solid line).} -\item{geom.label.color}{color of geom's value and annotation labels} +\item{geom.label.color}{Color of geom's value and annotation labels} \item{geom.label.size}{size of geom's value and annotation labels} @@ -74,7 +74,7 @@ Only applies, if \code{geom.boxoutline.size} is larger than 0.} \item{geom.label.angle}{angle of geom's value and annotation labels} -\item{axis.title.color}{color of x- and y-axis title labels} +\item{axis.title.color}{Color of x- and y-axis title labels} \item{axis.title.size}{size of x- and y-axis title labels} @@ -88,20 +88,20 @@ Only applies, if \code{geom.boxoutline.size} is larger than 0.} \item{axis.angle}{angle for x- and y-axis labels. If set, overrides both \code{axis.angle.x} and \code{axis.angle.y}} -\item{axis.textcolor.x}{color for x-axis labels. If not specified, a default dark gray +\item{axis.textcolor.x}{Color for x-axis labels. If not specified, a default dark gray color palette will be used for the labels.} -\item{axis.textcolor.y}{color for y-axis labels. If not specified, a default dark gray +\item{axis.textcolor.y}{Color for y-axis labels. If not specified, a default dark gray color palette will be used for the labels.} -\item{axis.textcolor}{color for both x- and y-axis labels. +\item{axis.textcolor}{Color for both x- and y-axis labels. If set, overrides both \code{axis.textcolor.x} and \code{axis.textcolor.y}} -\item{axis.linecolor.x}{color of x-axis border} +\item{axis.linecolor.x}{Color of x-axis border} -\item{axis.linecolor.y}{color of y-axis border} +\item{axis.linecolor.y}{Color of y-axis border} -\item{axis.linecolor}{color for both x- and y-axis borders. +\item{axis.linecolor}{Color for both x- and y-axis borders. If set, overrides both \code{axis.linecolor.x} and \code{axis.linecolor.y}.} \item{axis.line.size}{size (thickness) of axis lines. Only affected, if \code{axis.linecolor} @@ -116,7 +116,7 @@ If set, overrides both \code{axis.textsize.x} and \code{axis.textsize.y}.} \item{axis.tickslen}{length of axis tick marks} -\item{axis.tickscol}{color of axis tick marks} +\item{axis.tickscol}{Color of axis tick marks} \item{axis.ticksmar}{margin between axis labels and tick marks} @@ -124,33 +124,33 @@ If set, overrides both \code{axis.textsize.x} and \code{axis.textsize.y}.} \item{axis.ticksize.y}{size of tick marks at y-axis.} -\item{panel.backcol}{color of the diagram's background} +\item{panel.backcol}{Color of the diagram's background} -\item{panel.bordercol}{color of whole diagram border (panel border)} +\item{panel.bordercol}{Color of whole diagram border (panel border)} -\item{panel.col}{color of both diagram's border and background. +\item{panel.col}{Color of both diagram's border and background. If set, overrides both \code{panel.bordercol} and \code{panel.backcol}.} -\item{panel.major.gridcol}{color of the major grid lines of the diagram background} +\item{panel.major.gridcol}{Color of the major grid lines of the diagram background} -\item{panel.minor.gridcol}{color of the minor grid lines of the diagram background} +\item{panel.minor.gridcol}{Color of the minor grid lines of the diagram background} -\item{panel.gridcol}{color for both minor and major grid lines of the diagram background. +\item{panel.gridcol}{Color for both minor and major grid lines of the diagram background. If set, overrides both \code{panel.major.gridcol} and \code{panel.minor.gridcol}.} -\item{panel.gridcol.x}{see \code{panel.gridcol}.} +\item{panel.gridcol.x}{See \code{panel.gridcol}.} -\item{panel.gridcol.y}{see \code{panel.gridcol}.} +\item{panel.gridcol.y}{See \code{panel.gridcol}.} \item{panel.major.linetype}{line type for major grid lines} \item{panel.minor.linetype}{line type for minor grid lines} -\item{plot.backcol}{color of the plot's background} +\item{plot.backcol}{Color of the plot's background} -\item{plot.bordercol}{color of whole plot's border (panel border)} +\item{plot.bordercol}{Color of whole plot's border (panel border)} -\item{plot.col}{color of both plot's region border and background. +\item{plot.col}{Color of both plot's region border and background. If set, overrides both \code{plot.backcol} and \code{plot.bordercol}.} \item{plot.margins}{numeric vector of length 4, indicating the top, right, @@ -182,23 +182,23 @@ legend justification is set according to legend position.} \item{legend.size}{text size of the legend. Default is 1. Relative size, so recommended values are from 0.3 to 2.5} -\item{legend.color}{color of the legend labels} +\item{legend.color}{Color of the legend labels} \item{legend.title.size}{text size of the legend title} -\item{legend.title.color}{color of the legend title} +\item{legend.title.color}{Color of the legend title} \item{legend.title.face}{font face of the legend title. By default, \code{"bold"} face is used.} \item{legend.backgroundcol}{fill color of the legend's background. Default is \code{"white"}, so no visible background is drawn.} -\item{legend.bordercol}{color of the legend's border. Default is \code{"white"}, so no visible border is drawn.} +\item{legend.bordercol}{Color of the legend's border. Default is \code{"white"}, so no visible border is drawn.} \item{legend.item.size}{size of legend's item (legend key), in centimetres.} \item{legend.item.backcol}{fill color of the legend's item-background. Default is \code{"grey90"}.} -\item{legend.item.bordercol}{color of the legend's item-border. Default is \code{"white"}.} +\item{legend.item.bordercol}{Color of the legend's item-border. Default is \code{"white"}.} } \value{ The customized theme object, or \code{NULL}, if a ggplot-theme was used. diff --git a/man/sjp.stackfrq.Rd b/man/sjp.stackfrq.Rd index 274e92ec..704f9a15 100755 --- a/man/sjp.stackfrq.Rd +++ b/man/sjp.stackfrq.Rd @@ -14,7 +14,7 @@ sjp.stackfrq(items, title = NULL, legend.title = NULL, prnt.plot = TRUE) } \arguments{ -\item{items}{\code{data.frame} with each column representing one item.} +\item{items}{Data frame, with each column representing one item.} \item{title}{character vector, used as plot title. Depending on plot type and function, will be set automatically. If \code{title = ""}, no title is printed. @@ -31,11 +31,11 @@ for the x-axis and y-axis.} \item{axis.labels}{character vector with labels used as axis labels. Optional argument, since in most cases, axis labels are set automatically.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{sort.frq}{indicates whether the \code{items} should be ordered by +\item{sort.frq}{Indicates whether the \code{items} should be ordered by by highest count of first or last category of \code{items}. \describe{ \item{\code{"first.asc"}}{to order ascending by lowest count of first category,} @@ -48,17 +48,17 @@ by highest count of first or last category of \code{items}. \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} @@ -68,23 +68,23 @@ need smaller values than dot sizes.} \item{show.n}{logical, if \code{TRUE}, adds total number of cases for each group or category to the labels.} -\item{show.prc}{If \code{TRUE} (default), the percentage values at the x-axis are shown.} +\item{show.prc}{Logical, if \code{TRUE} (default), the percentage values at the x-axis are shown.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{expand.grid}{logical, if \code{TRUE}, the plot grid is expanded, i.e. there is a small margin between axes and plotting region. Default is \code{FALSE}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{vjust}{character vector, indicating the vertical position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{vjust}{character vector, indicating the vertical position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} @@ -105,25 +105,7 @@ Plot items (variables) of a scale as stacked proportional bars. This Thanks to \href{http://www.clas.ufl.edu/users/forrest/}{Forrest Stevens} for bug fixes. } \examples{ -# random data for 4-category likert scale, 5 items -Q1 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.2, 0.3, 0.1, 0.4))) -Q2 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.5, 0.25, 0.15, 0.1))) -Q3 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.25, 0.1, 0.4, 0.25))) -Q4 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.1, 0.4, 0.4, 0.1))) -Q5 <- as.factor(sample(1:4, 500, replace = TRUE, prob = c(0.35, 0.25, 0.15, 0.25))) - -likert_4 <- data.frame(Q1, Q2, Q3, Q4, Q5) - -# create labels -levels_4 <- c("Independent", "Slightly dependent", - "Dependent", "Severely dependent") - -# plot stacked frequencies of 5 (ordered) item-scales -sjp.stackfrq(likert_4, legend.labels = levels_4) - -# ------------------------------- # Data from the EUROFAMCARE sample dataset -# ------------------------------- library(sjmisc) data(efc) # recveive first item of COPE-index scale @@ -131,7 +113,7 @@ start <- which(colnames(efc) == "c82cop1") # recveive first item of COPE-index scale end <- which(colnames(efc) == "c90cop9") # auto-detection of labels -sjp.stackfrq(efc[, c(start:end)]) +sjp.stackfrq(efc[, start:end]) } diff --git a/man/sjp.xtab.Rd b/man/sjp.xtab.Rd index 204d7215..6cc7e893 100755 --- a/man/sjp.xtab.Rd +++ b/man/sjp.xtab.Rd @@ -18,20 +18,20 @@ sjp.xtab(x, grp, type = c("bar", "line"), margin = c("col", "cell", "row"), coord.flip = FALSE, prnt.plot = TRUE) } \arguments{ -\item{x}{a vector of values (variable) describing the bars which make up the plot.} +\item{x}{A vector of values (variable) describing the bars which make up the plot.} -\item{grp}{grouping variable of same length as \code{x}, where \code{x} +\item{grp}{Grouping variable of same length as \code{x}, where \code{x} is grouped into the categories represented by \code{grp}.} -\item{type}{plot type. may be either \code{"bar"} (default) for bar charts, +\item{type}{Plot type. may be either \code{"bar"} (default) for bar charts, or \code{"line"} for line diagram.} -\item{margin}{indicates which data of the proportional table should be plotted. Use \code{"row"} for +\item{margin}{Indicates which data of the proportional table should be plotted. Use \code{"row"} for calculating row percentages, \code{"col"} for column percentages and \code{"cell"} for cell percentages. If \code{margin = "col"}, an additional bar with the total sum of each column can be added to the plot (see \code{show.total}).} -\item{bar.pos}{indicates whether bars should be positioned side-by-side (default), +\item{bar.pos}{Indicates whether bars should be positioned side-by-side (default), or stacked (\code{bar.pos = "stack"}). May be abbreviated.} \item{title}{character vector, used as plot title. Depending on plot type and function, @@ -39,8 +39,8 @@ will be set automatically. If \code{title = ""}, no title is printed. For effect-plots, may also be a character vector of length > 1, to define titles for each sub-plot or facet.} -\item{title.wtd.suffix}{suffix (as string) for the title, if \code{weight.by} is specified, -e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +\item{title.wtd.suffix}{Suffix (as string) for the title, if \code{weight.by} is specified, +e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so title will not have a suffix when cases are weighted.} \item{axis.titles}{character vector of length one or two, defining the title(s) @@ -53,11 +53,11 @@ argument, since in most cases, axis labels are set automatically.} \item{legend.labels}{character vector with labels for the guide/legend.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{rev.order}{logical, if \code{TRUE}, order of categories (groups) is reversed.} +\item{rev.order}{Logical, if \code{TRUE}, order of categories (groups) is reversed.} \item{show.values}{logical, whether values should be plotted or not.} @@ -67,74 +67,74 @@ group or category to the labels.} \item{show.prc}{logical, if \code{TRUE} (default), percentage values are plotted to each bar If \code{FALSE}, percentage values are removed.} -\item{show.total}{when \code{margin = "col"}, an additional bar -with the sum within each category and it's percentages will be added +\item{show.total}{When \code{margin = "col"}, an additional bar +with the sum within each category and it's percentages will be added to each category.} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} -\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared -statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. -is shown. If a cell contains expected values lower than five (or lower than 10 -if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is -computed instead of chi-squared test. If the table's matrix is larger +\item{show.summary}{logical, if \code{TRUE} (default), a summary with chi-squared +statistics (see \code{\link{chisq.test}}), Cramer's V or Phi-value etc. +is shown. If a cell contains expected values lower than five (or lower than 10 +if df is 1), the Fisher's excact test (see \code{\link{fisher.test}}) is +computed instead of chi-squared test. If the table's matrix is larger than 2x2, Fisher's excact test with Monte Carlo simulation is computed.} -\item{summary.pos}{position of the model summary which is printed when \code{show.summary} -is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. +\item{summary.pos}{position of the model summary which is printed when \code{show.summary} +is \code{TRUE}. Default is \code{"r"}, i.e. it's printed to the upper right corner. Use \code{"l"} for upper left corner.} -\item{string.total}{string for the legend label when a total-column is added. Only applies +\item{string.total}{String for the legend label when a total-column is added. Only applies if \code{show.total = TRUE}. Default is \code{"Total"}.} \item{wrap.title}{numeric, determines how many chars of the plot title are displayed in one line and when a line break is inserted.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{wrap.legend.title}{numeric, determines how many chars of the legend's title +\item{wrap.legend.title}{numeric, determines how many chars of the legend's title are displayed in one line and when a line break is inserted.} -\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are +\item{wrap.legend.labels}{numeric, determines how many chars of the legend labels are displayed in one line and when a line break is inserted.} -\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, -depending on plot type and function). Note that bar and bin widths mostly +\item{geom.size}{size resp. width of the geoms (bar width, line thickness or point size, +depending on plot type and function). Note that bar and bin widths mostly need smaller values than dot sizes.} \item{geom.spacing}{the spacing between geoms (i.e. bar spacing)} \item{geom.colors}{user defined color for geoms. See 'Details' in \code{\link{sjp.grpfrq}}.} -\item{dot.size}{dot size, only applies, when argument \code{type = "line"}.} +\item{dot.size}{Dot size, only applies, when argument \code{type = "line"}.} \item{smooth.lines}{prints a smooth line curve. Only applies, when argument \code{type = "line"}.} -\item{grid.breaks}{numeric; sets the distance between breaks for the axis, +\item{grid.breaks}{numeric; sets the distance between breaks for the axis, i.e. at every \code{grid.breaks}'th position a major grid is being printed.} \item{expand.grid}{logical, if \code{TRUE}, the plot grid is expanded, i.e. there is a small margin between axes and plotting region. Default is \code{FALSE}.} \item{ylim}{numeric vector of length two, defining lower and upper axis limits -of the y scale. By default, this argument is set to \code{NULL}, i.e. the +of the y scale. By default, this argument is set to \code{NULL}, i.e. the y-axis fits to the required range of the data.} -\item{vjust}{character vector, indicating the vertical position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{vjust}{character vector, indicating the vertical position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} -\item{hjust}{character vector, indicating the horizontal position of value -labels. Allowed are same values as for \code{vjust} aesthetics from +\item{hjust}{character vector, indicating the horizontal position of value +labels. Allowed are same values as for \code{vjust} aesthetics from \code{ggplot2}: "left", "center", "right", "bottom", "middle", "top" and -new options like "inward" and "outward", which align text towards and +new options like "inward" and "outward", which align text towards and away from the center of the plot respectively.} -\item{y.offset}{numeric, offset for text labels when their alignment is adjusted +\item{y.offset}{numeric, offset for text labels when their alignment is adjusted to the top/bottom of the geom (see \code{hjust} and \code{vjust}).} \item{coord.flip}{logical, if \code{TRUE}, the x and y axis are swapped.} @@ -164,7 +164,7 @@ sjp.xtab(x, grp, axis.labels = c("low", "mid", "high"), # plot "cross tablulation" of x and grp # as stacked proportional bars -sjp.xtab(x, grp, margin = "row", bar.pos = "stack", +sjp.xtab(x, grp, margin = "row", bar.pos = "stack", show.summary = TRUE, coord.flip = TRUE) # example with vertical labels @@ -183,11 +183,11 @@ efc.var <- get_label(efc) sjp.xtab(efc$e42dep, efc$e16sex, title = efc.var['e42dep'], axis.labels = efc.val[['e42dep']], legend.title = efc.var['e16sex'], legend.labels = efc.val[['e16sex']]) - + sjp.xtab(efc$e16sex, efc$e42dep, title = efc.var['e16sex'], axis.labels = efc.val[['e16sex']], legend.title = efc.var['e42dep'], legend.labels = efc.val[['e42dep']]) - + # ------------------------------- # auto-detection of labels works here # so no need to specify labels. For diff --git a/man/sjt.corr.Rd b/man/sjt.corr.Rd index f7c81091..be3b6dd8 100755 --- a/man/sjt.corr.Rd +++ b/man/sjt.corr.Rd @@ -12,35 +12,35 @@ sjt.corr(data, na.deletion = c("listwise", "pairwise"), use.viewer = TRUE, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{data}{variables which frequencies should be printed as table. Either use a single variable -(vector) or a data frame where each column represents a variable (see 'Examples').} +\item{data}{A vector or a data frame, for which frequencies should be printed +as table.} -\item{na.deletion}{indicates how missing values are treated. May be either +\item{na.deletion}{Indicates how missing values are treated. May be either \code{"listwise"} (default) or \code{"pairwise"}. May be abbreviated.} -\item{corr.method}{indicates the correlation computation method. May be one of +\item{corr.method}{Indicates the correlation computation method. May be one of \code{"spearman"} (default), \code{"pearson"} or \code{"kendall"}. May be abbreviated.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{var.labels}{character vector with variable names, which will be used +\item{var.labels}{Character vector with variable names, which will be used to label variables in the output.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{show.p}{logical, adds significance levels to values, or value and +\item{show.p}{Logical, adds significance levels to values, or value and variable labels.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} -\item{fade.ns}{logical, if \code{TRUE} (default), non-significant correlation-values +\item{fade.ns}{Logical, if \code{TRUE} (default), non-significant correlation-values appear faded (by using a lighter grey text color). See 'Note'.} -\item{val.rm}{specify a number between 0 and 1 to suppress the output of correlation values +\item{val.rm}{Specify a number between 0 and 1 to suppress the output of correlation values that are smaller than \code{val.rm}. The absolute correlation values are used, so a correlation value of \code{-.5} would be greater than \code{val.rm = .4} and thus not be omitted. By default, this argument is \code{NULL}, hence all values are shown in the table. @@ -49,40 +49,40 @@ the HTML table, but made "invisible" with white foreground color. You can use th argument (\code{"css.valueremove"}) to change color and appearance of those correlation value that are smaller than the limit specified by \code{val.rm}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{triangle}{indicates whether only the upper right (use \code{"upper"}), lower left (use \code{"lower"}) +\item{triangle}{Indicates whether only the upper right (use \code{"upper"}), lower left (use \code{"lower"}) or both (use \code{"both"}) triangles of the correlation table is filled with values. Default is \code{"both"}. You can specifiy the inital letter only.} -\item{string.diag}{a vector with string values of the same length as \code{ncol(data)} (number of +\item{string.diag}{A vector with string values of the same length as \code{ncol(data)} (number of correlated items) that can be used to display content in the diagonal cells where row and column item are identical (i.e. the "self-correlation"). By defauilt, this argument is \code{NULL} and the diagnal cells are empty.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.df.Rd b/man/sjt.df.Rd index ca7dcfea..04746aad 100755 --- a/man/sjt.df.Rd +++ b/man/sjt.df.Rd @@ -18,7 +18,7 @@ sjt.df(mydf, describe = TRUE, altr.row.col = FALSE, sort.col = NULL, The description is retrieved from the \code{\link[psych]{describe}} function. If \code{describe = FALSE}, the data frame's content (values) is shown.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} \item{sort.col}{indicates a column, either by column name or by column index number, @@ -30,7 +30,7 @@ is printed with no specific order. See 'Examples'.} data frame is ordered according to the specified column in an ascending order. Use \code{FALSE} to apply descending order. See 'Examples'.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} \item{repeat.header}{logical, if \code{TRUE}, the header row will also be added at the bottom at the table. This might be helpful, if you have longer tables and want to see the column names at the end of the table as well.} @@ -56,29 +56,29 @@ thousands decimals before (hence big) the decimal point} \item{hide.progress}{logical, if \code{TRUE}, the progress bar that is displayed when creating the output is hidden. Default in \code{FALSE}, hence the bar is visible.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} diff --git a/man/sjt.frq.Rd b/man/sjt.frq.Rd index 18e5c213..03006921 100755 --- a/man/sjt.frq.Rd +++ b/man/sjt.frq.Rd @@ -16,63 +16,63 @@ sjt.frq(data, weight.by = NULL, title.wtd.suffix = " (weighted)", use.viewer = TRUE, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{data}{variables which frequencies should be printed as table. Either use a single variable -(vector) or a data frame where each column represents a variable (see 'Examples').} +\item{data}{A vector or a data frame, for which frequencies should be printed +as table.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{title.wtd.suffix}{suffix (as string) for the title, if \code{weight.by} is specified, -e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so +\item{title.wtd.suffix}{Suffix (as string) for the title, if \code{weight.by} is specified, +e.g. \code{title.wtd.suffix=" (weighted)"}. Default is \code{NULL}, so title will not have a suffix when cases are weighted.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{value.labels}{character vector (or \code{list} of character vectors) +\item{value.labels}{Character vector (or \code{list} of character vectors) with value labels of the supplied variables, which will be used to label variable values in the output.} -\item{sort.frq}{Determines whether categories should be sorted -according to their frequencies or not. Default is \code{"none"}, so +\item{sort.frq}{Determines whether categories should be sorted +according to their frequencies or not. Default is \code{"none"}, so categories are not sorted by frequency. Use \code{"asc"} or \code{"desc"} for sorting categories ascending or descending order.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} -\item{string.val}{label for the very first table column containing the values (see +\item{string.val}{Character label for the very first table column containing the values (see \code{value.labels}).} -\item{string.cnt}{label for the first table data column containing the counts. Default is \code{"N"}.} +\item{string.cnt}{Character label for the first table data column containing the counts. Default is \code{"N"}.} -\item{string.prc}{label for the second table data column containing the raw percentages. Default is \code{"raw \%"}.} +\item{string.prc}{Character label for the second table data column containing the raw percentages. Default is \code{"raw \%"}.} -\item{string.vprc}{String label for the third data table column containing the valid percentages, i.e. the +\item{string.vprc}{Character label for the third data table column containing the valid percentages, i.e. the count percentage value exluding possible missing values.} -\item{string.cprc}{String label for the last table data column containing the cumulative percentages.} +\item{string.cprc}{Character label for the last table data column containing the cumulative percentages.} -\item{string.na}{String label for the last table data row containing missing values.} +\item{string.na}{Character label for the last table data row containing missing values.} -\item{emph.md}{If \code{TRUE}, the table row indicating the median value will +\item{emph.md}{Logical, if \code{TRUE}, the table row indicating the median value will be emphasized.} -\item{emph.quart}{If \code{TRUE}, the table row indicating the lower and upper quartiles will +\item{emph.quart}{Logical, if \code{TRUE}, the table row indicating the lower and upper quartiles will be emphasized.} -\item{show.summary}{If \code{TRUE} (default), a summary row with total and valid N as well as mean and +\item{show.summary}{Logical, if \code{TRUE} (default), a summary row with total and valid N as well as mean and standard deviation is shown.} -\item{show.skew}{If \code{TRUE}, the variable's skewness is added to the summary. +\item{show.skew}{Logical, if \code{TRUE}, the variable's skewness is added to the summary. The skewness is retrieved from the \code{\link[psych]{describe}}-function of the \pkg{psych}-package and indicated by a lower case Greek gamma.} -\item{show.kurtosis}{If \code{TRUE}, the variable's kurtosis is added to the summary. +\item{show.kurtosis}{Logical, if \code{TRUE}, the variable's kurtosis is added to the summary. The kurtosis is retrieved from the \code{\link[psych]{describe}}-function of the \pkg{psych}-package and indicated by a lower case Greek omega.} -\item{skip.zero}{If \code{TRUE}, rows with only zero-values are not printed +\item{skip.zero}{Logical, if \code{TRUE}, rows with only zero-values are not printed (e.g. if a variable has values or levels 1 to 8, and levels / values 4 to 6 have no counts, these values would not be printed in the table). Use \code{FALSE} to print also zero-values, or use \code{"auto"} (default) @@ -80,50 +80,50 @@ to detect whether it makes sense or not to print zero-values (e.g., a variable "age" with values from 10 to 100, where at least 25 percent of all possible values have no counts, zero-values would be skipped automatically).} -\item{ignore.strings}{If \code{TRUE} (default), character vectors / string variables will be removed from +\item{ignore.strings}{Logical, if \code{TRUE} (default), character vectors / string variables will be removed from \code{data} before frequency tables are computed.} -\item{auto.group}{numeric value, indicating the minimum amount of unique values -in the count variable, at which automatic grouping into smaller units -is done (see \code{\link[sjmisc]{group_var}}). Default value for +\item{auto.group}{numeric value, indicating the minimum amount of unique values +in the count variable, at which automatic grouping into smaller units +is done (see \code{\link[sjmisc]{group_var}}). Default value for \code{auto.group} is \code{NULL}, i.e. auto-grouping is off. See \code{\link[sjmisc]{group_var}} for examples on grouping.} -\item{auto.grp.strings}{if \code{TRUE} (default), string values in character +\item{auto.grp.strings}{Logical, if \code{TRUE} (default), string values in character vectors (string variables) are automatically grouped based on their similarity. The similarity is estimated with the \pkg{stringdist}-package. You can specify a distance-measure via \code{max.string.dist} argument. This argument only applies if \code{ignore.strings} is \code{FALSE}.} -\item{max.string.dist}{the allowed distance of string values in a character vector, which indicates +\item{max.string.dist}{Numeric, the allowed distance of string values in a character vector, which indicates when two string values are merged because they are considered as close enough. See \code{auto.grp.strings}.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } @@ -141,7 +141,7 @@ Invisibly returns Shows (multiple) frequency tables as HTML file, or saves them as file. } \details{ -\bold{How does the \code{CSS}-argument work?} +\bold{How do I use \code{CSS}-argument?} \cr \cr With the \code{CSS}-argument, the visual appearance of the tables can be modified. To get an overview of all style-sheet-classnames @@ -164,7 +164,7 @@ Shows (multiple) frequency tables as HTML file, or saves them as file. See further examples in \href{../doc/sjtbasic.html}{this package-vignette}. } \note{ -The HTML tables can either be saved as file and manually opened (specify argument \code{file}) or +The HTML tables can either be saved as file and manually opened (use argument \code{file}) or they can be saved as temporary files and will be displayed in the RStudio Viewer pane (if working with RStudio) or opened with the default web browser. Displaying resp. opening a temporary file is the default behaviour (i.e. \code{file = NULL}). diff --git a/man/sjt.glm.Rd b/man/sjt.glm.Rd index 954cbbca..9f213ebd 100755 --- a/man/sjt.glm.Rd +++ b/man/sjt.glm.Rd @@ -23,19 +23,19 @@ sjt.glm(..., pred.labels = NULL, depvar.labels = NULL, remove.spaces = TRUE) } \arguments{ -\item{...}{one or more fitted generalized linear (mixed) models.} +\item{...}{One or more fitted generalized linear (mixed) models.} -\item{pred.labels}{character vector with labels of predictor variables. +\item{pred.labels}{Character vector with labels of predictor variables. If not \code{NULL}, \code{pred.labels} will be used in the first table column with the predictors' names. If \code{NULL}, variable labels are set based on label attributes (see \code{\link[sjmisc]{get_label}}). If \code{pred.labels = ""}, column names (vector names) are used as predictor labels. See 'Examples'.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{remove.estimates}{numeric vector with indices (order equals to row index of \code{coef(fit)}) +\item{remove.estimates}{Numeric vector with indices (order equals to row index of \code{coef(fit)}) or character vector with coefficient names that indicate which estimates should be removed from the table output. The first estimate is the intercept, followed by the model predictors. \emph{The intercept cannot be removed from the table output!} \code{remove.estimates = c(2:4)} @@ -43,161 +43,161 @@ would remove the 2nd to the 4th estimate (1st to 3rd predictor after intercept) \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{group.pred}{logical, if \code{TRUE} (default), automatically groups table rows with +\item{group.pred}{Logical, if \code{TRUE} (default), automatically groups table rows with factor levels of same factor, i.e. predictors of type \code{\link{factor}} will be grouped, if the factor has more than two levels. Grouping means that a separate headline row is inserted to the table just before the predictor values.} -\item{exp.coef}{logical, if \code{TRUE} (default), regression coefficients and +\item{exp.coef}{Logical, if \code{TRUE} (default), regression coefficients and confidence intervals are exponentiated. Use \code{FALSE} for non-exponentiated coefficients (log-odds) as provided by the \code{\link{summary}} function.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} -\item{emph.p}{logical, if \code{TRUE}, significant p-values are shown bold faced.} +\item{emph.p}{Logical, if \code{TRUE}, significant p-values are shown bold faced.} \item{p.zero}{logical, if \code{TRUE}, p-values have a leading 0 before the period (e.g. \emph{0.002}), else p-values start with a period and without a zero (e.g. \emph{.002}).} -\item{robust}{logical, if \code{TRUE}, robust standard errors and confidence +\item{robust}{Logical, if \code{TRUE}, robust standard errors and confidence intervals will be reported. Computation of robust standard errors is based on the \code{\link[sjstats]{robust}}-function in the \pkg{sjstats}-package.} -\item{separate.ci.col}{if \code{TRUE}, the CI values are shown in a separate table column. +\item{separate.ci.col}{Logical, if \code{TRUE}, the CI values are shown in a separate table column. Default is \code{FALSE}.} -\item{newline.ci}{logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break +\item{newline.ci}{Logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break between estimate and CI values. If \code{FALSE}, CI values are printed in the same line as estimate values.} -\item{show.ci}{logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use +\item{show.ci}{Logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use \code{FALSE} to omit the CI in the table.} -\item{show.se}{logical, if \code{TRUE}, the standard errors are also printed. +\item{show.se}{Logical, if \code{TRUE}, the standard errors are also printed. Default is \code{FALSE}.} -\item{show.header}{logical, if \code{TRUE}, the header strings \code{string.pred} +\item{show.header}{Logical, if \code{TRUE}, the header strings \code{string.pred} and \code{string.dv} are shown. By default, they're hidden.} -\item{show.col.header}{logical, if \code{TRUE} (default), the table data columns have a headline with +\item{show.col.header}{Logical, if \code{TRUE} (default), the table data columns have a headline with abbreviations for estimates, std. beta-values, confidence interval and p-values.} -\item{show.r2}{logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed +\item{show.r2}{Logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed in the model summary. R2cs is the Cox-Snell-pseudo R-squared value, R2n is Nagelkerke's pseudo R-squared value and \code{D} is Tjur's Coefficient of Discrimination (see \code{\link[sjstats]{cod}}).} -\item{show.icc}{logical, if \code{TRUE}, the intra-class-correlation for each +\item{show.icc}{Logical, if \code{TRUE}, the intra-class-correlation for each model is printed in the model summary. Only applies to mixed models.} -\item{show.re.var}{logical, if \code{TRUE}, the variance parameters for the random +\item{show.re.var}{Logical, if \code{TRUE}, the variance parameters for the random effects for each model are printed in the model summary. Only applies to mixed models. For details output, see 'Note' in \code{\link[sjstats]{icc}}.} -\item{show.loglik}{logical, if \code{TRUE}, the Log-Likelihood for each model is printed +\item{show.loglik}{Logical, if \code{TRUE}, the Log-Likelihood for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aic}{logical, if \code{TRUE}, the AIC value for each model is printed +\item{show.aic}{Logical, if \code{TRUE}, the AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aicc}{logical, if \code{TRUE}, the second-order AIC value for each model +\item{show.aicc}{Logical, if \code{TRUE}, the second-order AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.dev}{logical, if \code{TRUE}, the deviance for each model +\item{show.dev}{Logical, if \code{TRUE}, the deviance for each model is printed in the model summary.} -\item{show.hoslem}{logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is +\item{show.hoslem}{Logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is performed. A well-fitting model shows no significant difference between the model and the observed data, i.e. the reported p-values should be greater than 0.05.} -\item{show.family}{logical, if \code{TRUE}, the family object and link function for each fitted model +\item{show.family}{Logical, if \code{TRUE}, the family object and link function for each fitted model are printed. Can be used in case you want to compare models with different link functions and same predictors and response, to decide which model fits best. See \code{\link{family}} for more details. It is recommended to inspect the model \code{\link{AIC}} (see \code{show.aic}) to get a decision help for which model to choose.} -\item{show.chi2}{logical, if \code{TRUE}, the p-value of the chi-squared value for each +\item{show.chi2}{Logical, if \code{TRUE}, the p-value of the chi-squared value for each model's residual deviance against the null deviance is printed in the model summary. Default is \code{FALSE}. A well-fitting model with predictors should significantly differ from the null-model (without predictors), thus, a p-value less than 0.05 indicates a good model-fit.} -\item{string.pred}{character vector,used as headline for the predictor column. +\item{string.pred}{Character vector,used as headline for the predictor column. Default is \code{"Predictors"}.} -\item{string.dv}{character vector, used as headline for the +\item{string.dv}{Character vector, used as headline for the dependent variable columns. Default is \code{"Dependent Variables"}.} -\item{string.interc}{character vector, used as headline for the Intercept row. +\item{string.interc}{Character vector, used as headline for the Intercept row. Default is \code{"Intercept"}.} \item{string.obs}{character vector, used in the summary row for the count of observation (cases). Default is \code{"Observations"}.} -\item{string.est}{character vector, used for the column heading of estimates.} +\item{string.est}{Character vector, used for the column heading of estimates.} -\item{string.ci}{character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} +\item{string.ci}{Character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} -\item{string.se}{character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} +\item{string.se}{Character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} -\item{string.p}{character vector, used for the column heading of p values. Default is \code{"p"}.} +\item{string.p}{Character vector, used for the column heading of p values. Default is \code{"p"}.} -\item{ci.hyphen}{character vector, indicating the hyphen for confidence interval range. +\item{ci.hyphen}{Character vector, indicating the hyphen for confidence interval range. May be an HTML entity. See 'Examples'.} -\item{digits.est}{amount of decimals for estimates} +\item{digits.est}{Amount of decimals for estimates} -\item{digits.p}{amount of decimals for p-values} +\item{digits.p}{Amount of decimals for p-values} -\item{digits.ci}{amount of decimals for confidence intervals} +\item{digits.ci}{Amount of decimals for confidence intervals} -\item{digits.se}{amount of decimals for standard error} +\item{digits.se}{Amount of decimals for standard error} -\item{digits.summary}{amount of decimals for values in model summary} +\item{digits.summary}{Amount of decimals for values in model summary} -\item{cell.spacing}{numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is +\item{cell.spacing}{Numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is suitable for viewing the table. Decrease this value (0.05 to 0.1) if you want to import the table into Office documents. This is a convenient argument for the \code{CSS} argument for changing cell spacing, which would be: \code{CSS = list(css.thead = "padding:0.2cm;", css.tdata = "padding:0.2cm;")}.} -\item{cell.gpr.indent}{indent for table rows with grouped factor predictors. Only applies +\item{cell.gpr.indent}{Indent for table rows with grouped factor predictors. Only applies if \code{group.pred = TRUE}.} -\item{sep.column}{logical, if \code{TRUE}, an empty table column is added after +\item{sep.column}{Logical, if \code{TRUE}, an empty table column is added after each model column, to add margins between model columns. By default, this column will be added to the output; however, when copying tables to office applications, it might be helpful not to add this separator column when modifying the table layout.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.glmer.Rd b/man/sjt.glmer.Rd index 84625c63..f236301a 100755 --- a/man/sjt.glmer.Rd +++ b/man/sjt.glmer.Rd @@ -22,19 +22,19 @@ sjt.glmer(..., pred.labels = NULL, depvar.labels = NULL, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{...}{one or more fitted generalized linear (mixed) models.} +\item{...}{One or more fitted generalized linear (mixed) models.} -\item{pred.labels}{character vector with labels of predictor variables. +\item{pred.labels}{Character vector with labels of predictor variables. If not \code{NULL}, \code{pred.labels} will be used in the first table column with the predictors' names. If \code{NULL}, variable labels are set based on label attributes (see \code{\link[sjmisc]{get_label}}). If \code{pred.labels = ""}, column names (vector names) are used as predictor labels. See 'Examples'.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{remove.estimates}{numeric vector with indices (order equals to row index of \code{coef(fit)}) +\item{remove.estimates}{Numeric vector with indices (order equals to row index of \code{coef(fit)}) or character vector with coefficient names that indicate which estimates should be removed from the table output. The first estimate is the intercept, followed by the model predictors. \emph{The intercept cannot be removed from the table output!} \code{remove.estimates = c(2:4)} @@ -42,149 +42,149 @@ would remove the 2nd to the 4th estimate (1st to 3rd predictor after intercept) \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{group.pred}{logical, if \code{TRUE} (default), automatically groups table rows with +\item{group.pred}{Logical, if \code{TRUE} (default), automatically groups table rows with factor levels of same factor, i.e. predictors of type \code{\link{factor}} will be grouped, if the factor has more than two levels. Grouping means that a separate headline row is inserted to the table just before the predictor values.} -\item{exp.coef}{logical, if \code{TRUE} (default), regression coefficients and +\item{exp.coef}{Logical, if \code{TRUE} (default), regression coefficients and confidence intervals are exponentiated. Use \code{FALSE} for non-exponentiated coefficients (log-odds) as provided by the \code{\link{summary}} function.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} -\item{emph.p}{logical, if \code{TRUE}, significant p-values are shown bold faced.} +\item{emph.p}{Logical, if \code{TRUE}, significant p-values are shown bold faced.} \item{p.zero}{logical, if \code{TRUE}, p-values have a leading 0 before the period (e.g. \emph{0.002}), else p-values start with a period and without a zero (e.g. \emph{.002}).} -\item{separate.ci.col}{if \code{TRUE}, the CI values are shown in a separate table column. +\item{separate.ci.col}{Logical, if \code{TRUE}, the CI values are shown in a separate table column. Default is \code{FALSE}.} -\item{newline.ci}{logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break +\item{newline.ci}{Logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break between estimate and CI values. If \code{FALSE}, CI values are printed in the same line as estimate values.} -\item{show.ci}{logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use +\item{show.ci}{Logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use \code{FALSE} to omit the CI in the table.} -\item{show.se}{logical, if \code{TRUE}, the standard errors are also printed. +\item{show.se}{Logical, if \code{TRUE}, the standard errors are also printed. Default is \code{FALSE}.} -\item{show.header}{logical, if \code{TRUE}, the header strings \code{string.pred} +\item{show.header}{Logical, if \code{TRUE}, the header strings \code{string.pred} and \code{string.dv} are shown. By default, they're hidden.} -\item{show.col.header}{logical, if \code{TRUE} (default), the table data columns have a headline with +\item{show.col.header}{Logical, if \code{TRUE} (default), the table data columns have a headline with abbreviations for estimates, std. beta-values, confidence interval and p-values.} -\item{show.r2}{logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed +\item{show.r2}{Logical, if \code{TRUE} (default), the pseudo R2 values for each model are printed in the model summary. R2cs is the Cox-Snell-pseudo R-squared value, R2n is Nagelkerke's pseudo R-squared value and \code{D} is Tjur's Coefficient of Discrimination (see \code{\link[sjstats]{cod}}).} -\item{show.icc}{logical, if \code{TRUE}, the intra-class-correlation for each +\item{show.icc}{Logical, if \code{TRUE}, the intra-class-correlation for each model is printed in the model summary. Only applies to mixed models.} -\item{show.re.var}{logical, if \code{TRUE}, the variance parameters for the random +\item{show.re.var}{Logical, if \code{TRUE}, the variance parameters for the random effects for each model are printed in the model summary. Only applies to mixed models. For details output, see 'Note' in \code{\link[sjstats]{icc}}.} -\item{show.loglik}{logical, if \code{TRUE}, the Log-Likelihood for each model is printed +\item{show.loglik}{Logical, if \code{TRUE}, the Log-Likelihood for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aic}{logical, if \code{TRUE}, the AIC value for each model is printed +\item{show.aic}{Logical, if \code{TRUE}, the AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aicc}{logical, if \code{TRUE}, the second-order AIC value for each model +\item{show.aicc}{Logical, if \code{TRUE}, the second-order AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.dev}{logical, if \code{TRUE}, the deviance for each model +\item{show.dev}{Logical, if \code{TRUE}, the deviance for each model is printed in the model summary.} -\item{show.hoslem}{logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is +\item{show.hoslem}{Logical, if \code{TRUE}, a Hosmer-Lemeshow-Goodness-of-fit-test is performed. A well-fitting model shows no significant difference between the model and the observed data, i.e. the reported p-values should be greater than 0.05.} -\item{show.family}{logical, if \code{TRUE}, the family object and link function for each fitted model +\item{show.family}{Logical, if \code{TRUE}, the family object and link function for each fitted model are printed. Can be used in case you want to compare models with different link functions and same predictors and response, to decide which model fits best. See \code{\link{family}} for more details. It is recommended to inspect the model \code{\link{AIC}} (see \code{show.aic}) to get a decision help for which model to choose.} -\item{string.pred}{character vector,used as headline for the predictor column. +\item{string.pred}{Character vector,used as headline for the predictor column. Default is \code{"Predictors"}.} -\item{string.dv}{character vector, used as headline for the +\item{string.dv}{Character vector, used as headline for the dependent variable columns. Default is \code{"Dependent Variables"}.} -\item{string.interc}{character vector, used as headline for the Intercept row. +\item{string.interc}{Character vector, used as headline for the Intercept row. Default is \code{"Intercept"}.} \item{string.obs}{character vector, used in the summary row for the count of observation (cases). Default is \code{"Observations"}.} -\item{string.est}{character vector, used for the column heading of estimates.} +\item{string.est}{Character vector, used for the column heading of estimates.} -\item{string.ci}{character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} +\item{string.ci}{Character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} -\item{string.se}{character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} +\item{string.se}{Character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} -\item{string.p}{character vector, used for the column heading of p values. Default is \code{"p"}.} +\item{string.p}{Character vector, used for the column heading of p values. Default is \code{"p"}.} -\item{ci.hyphen}{character vector, indicating the hyphen for confidence interval range. +\item{ci.hyphen}{Character vector, indicating the hyphen for confidence interval range. May be an HTML entity. See 'Examples'.} -\item{digits.est}{amount of decimals for estimates} +\item{digits.est}{Amount of decimals for estimates} -\item{digits.p}{amount of decimals for p-values} +\item{digits.p}{Amount of decimals for p-values} -\item{digits.ci}{amount of decimals for confidence intervals} +\item{digits.ci}{Amount of decimals for confidence intervals} -\item{digits.se}{amount of decimals for standard error} +\item{digits.se}{Amount of decimals for standard error} -\item{digits.summary}{amount of decimals for values in model summary} +\item{digits.summary}{Amount of decimals for values in model summary} -\item{cell.spacing}{numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is +\item{cell.spacing}{Numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is suitable for viewing the table. Decrease this value (0.05 to 0.1) if you want to import the table into Office documents. This is a convenient argument for the \code{CSS} argument for changing cell spacing, which would be: \code{CSS = list(css.thead = "padding:0.2cm;", css.tdata = "padding:0.2cm;")}.} -\item{cell.gpr.indent}{indent for table rows with grouped factor predictors. Only applies +\item{cell.gpr.indent}{Indent for table rows with grouped factor predictors. Only applies if \code{group.pred = TRUE}.} -\item{sep.column}{logical, if \code{TRUE}, an empty table column is added after +\item{sep.column}{Logical, if \code{TRUE}, an empty table column is added after each model column, to add margins between model columns. By default, this column will be added to the output; however, when copying tables to office applications, it might be helpful not to add this separator column when modifying the table layout.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.grpmean.Rd b/man/sjt.grpmean.Rd index 7a85a31e..71f33430 100755 --- a/man/sjt.grpmean.Rd +++ b/man/sjt.grpmean.Rd @@ -10,46 +10,46 @@ sjt.grpmean(var.cnt, var.grp, weight.by = NULL, value.labels = NULL, remove.spaces = TRUE) } \arguments{ -\item{var.cnt}{vector of counts, for which frequencies or means will be plotted or printed.} +\item{var.cnt}{Vector of counts, for which frequencies or means will be plotted or printed.} -\item{var.grp}{factor with the cross-classifying variable, where \code{var.cnt} +\item{var.grp}{Factor with the cross-classifying variable, where \code{var.cnt} is grouped into the categories represented by \code{var.grp}.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{value.labels}{character vector (or \code{list} of character vectors) +\item{value.labels}{Character vector (or \code{list} of character vectors) with value labels of the supplied variables, which will be used to label variable values in the output.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{digits.summary}{amount of digits for summary statistics (Anova).} +\item{digits.summary}{Amount of digits for summary statistics (Anova).} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.itemanalysis.Rd b/man/sjt.itemanalysis.Rd index 75b57bd1..a36622e4 100755 --- a/man/sjt.itemanalysis.Rd +++ b/man/sjt.itemanalysis.Rd @@ -12,28 +12,28 @@ sjt.itemanalysis(df, factor.groups = NULL, factor.groups.titles = "auto", remove.spaces = TRUE) } \arguments{ -\item{df}{data frame with items} +\item{df}{A data frame with items.} -\item{factor.groups}{if not \code{NULL}, \code{df} will be splitted into sub-groups, -where the item analysis is carried out for each of these groups. Must be a vector of same +\item{factor.groups}{If not \code{NULL}, \code{df} will be splitted into sub-groups, +where the item analysis is carried out for each of these groups. Must be a vector of same length as \code{ncol(df)}, where each item in this vector represents the group number of the related columns of \code{df}. See 'Examples'.} -\item{factor.groups.titles}{titles for each factor group that will be used as table caption for each +\item{factor.groups.titles}{Titles for each factor group that will be used as table caption for each component-table. Must be a character vector of same length as \code{length(unique(factor.groups))}. Default is \code{"auto"}, which means that each table has a standard caption \emph{Component x}. Use \code{NULL} to suppress table captions.} -\item{scale}{logical, if \code{TRUE}, the data frame's vectors will be scaled when calculating the -Cronbach's Alpha value (see \code{\link[sjstats]{reliab_test}}). Recommended, when +\item{scale}{Logical, if \code{TRUE}, the data frame's vectors will be scaled when calculating the +Cronbach's Alpha value (see \code{\link[sjstats]{reliab_test}}). Recommended, when the variables have different measures / scales.} -\item{min.valid.rowmean}{minimum amount of valid values to compute row means for index scores. +\item{min.valid.rowmean}{Minimum amount of valid values to compute row means for index scores. Default is 2, i.e. the return values \code{index.scores} and \code{df.index.scores} are computed for those items that have at least \code{min.valid.rowmean} per case (observation, or technically, row). See \code{mean_n} for details.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} \item{sort.col}{indicates a column, either by column name or by column index number, @@ -45,13 +45,13 @@ is printed with no specific order. See 'Examples'.} data frame is ordered according to the specified column in an ascending order. Use \code{FALSE} to apply descending order. See 'Examples'.} -\item{show.shapiro}{logical, if \code{TRUE}, a Shapiro-Wilk normality test is computed for each item. +\item{show.shapiro}{Logical, if \code{TRUE}, a Shapiro-Wilk normality test is computed for each item. See \code{\link{shapiro.test}} for details.} -\item{show.kurtosis}{logical, if \code{TRUE}, the kurtosis for each item will also be shown (see \code{\link[psych]{kurtosi}} +\item{show.kurtosis}{Logical, if \code{TRUE}, the kurtosis for each item will also be shown (see \code{\link[psych]{kurtosi}} and \code{\link[psych]{describe}} in the \code{psych}-package for more details.} -\item{show.corr.matrix}{logical, if \code{TRUE} (default), a correlation matrix of each component's +\item{show.corr.matrix}{Logical, if \code{TRUE} (default), a correlation matrix of each component's index score is shown. Only applies if \code{factor.groups} is not \code{NULL} and \code{df} has more than one group. First, for each case (df's row), the sum of all variables (df's columns) is scaled (using the \code{\link{scale}}-function) and represents a "total score" for @@ -59,29 +59,29 @@ each component (a component is represented by each group of \code{factor.groups} After that, each case (df's row) has a scales sum score for each component. Finally, a correlation of these "scale sum scores" is computed.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } @@ -97,14 +97,14 @@ Invisibly returns \item \code{knitr}: html-table of all complete output with inline-css for use with knitr \item \code{complete.page}: Complete html-output. } - If \code{factor.groups} was \code{NULL}, each list contains only one elment, since just one - table is printed for the complete scale indicated by \code{df}. If \code{factor.groups} + If \code{factor.groups = NULL}, each list contains only one elment, since just one + table is printed for the complete scale indicated by \code{df}. If \code{factor.groups} is a vector of group-index-values, the lists contain elements for each sub-group. } \description{ This function performs an item analysis with certain statistics that are useful for scale or index development. The resulting tables are shown in the - viewer pane resp. webbrowser or can be saved as file. Following statistics are + viewer pane resp. webbrowser or can be saved as file. Following statistics are computed for each item of a data frame: \itemize{ \item percentage of missing values @@ -161,12 +161,12 @@ sjt.itemanalysis(mydf) # auto-detection of labels sjt.itemanalysis(efc[, c(start:end)]) - + # Compute PCA on Cope-Index, and perform a # item analysis for each extracted factor. factor.groups <- sjt.pca(mydf, no.output = TRUE)$factor.index sjt.itemanalysis(mydf, factor.groups)} - + } \references{ \itemize{ diff --git a/man/sjt.lm.Rd b/man/sjt.lm.Rd index f4f26c83..3bdcc08a 100755 --- a/man/sjt.lm.Rd +++ b/man/sjt.lm.Rd @@ -22,19 +22,19 @@ sjt.lm(..., pred.labels = NULL, depvar.labels = NULL, use.viewer = TRUE, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{...}{one or more fitted linear (mixed) models.} +\item{...}{One or more fitted linear (mixed) models.} -\item{pred.labels}{character vector with labels of predictor variables. +\item{pred.labels}{Character vector with labels of predictor variables. If not \code{NULL}, \code{pred.labels} will be used in the first table column with the predictors' names. If \code{NULL}, variable labels are set based on label attributes (see \code{\link[sjmisc]{get_label}}). If \code{pred.labels = ""}, column names (vector names) are used as predictor labels. See 'Examples'.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{remove.estimates}{numeric vector with indices (order equals to row index of \code{coef(fit)}) +\item{remove.estimates}{Numeric vector with indices (order equals to row index of \code{coef(fit)}) or character vector with coefficient names that indicate which estimates should be removed from the table output. The first estimate is the intercept, followed by the model predictors. \emph{The intercept cannot be removed from the table output!} \code{remove.estimates = c(2:4)} @@ -42,15 +42,15 @@ would remove the 2nd to the 4th estimate (1st to 3rd predictor after intercept) \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{group.pred}{logical, if \code{TRUE} (default), automatically groups table rows with +\item{group.pred}{Logical, if \code{TRUE} (default), automatically groups table rows with factor levels of same factor, i.e. predictors of type \code{\link{factor}} will be grouped, if the factor has more than two levels. Grouping means that a separate headline row is inserted to the table just before the predictor values.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} -\item{emph.p}{logical, if \code{TRUE}, significant p-values are shown bold faced.} +\item{emph.p}{Logical, if \code{TRUE}, significant p-values are shown bold faced.} \item{p.zero}{logical, if \code{TRUE}, p-values have a leading 0 before the period (e.g. \emph{0.002}), else p-values start with a period and @@ -60,137 +60,137 @@ without a zero (e.g. \emph{.002}).} F-tests with Kenward-Roger approximation for the df. Caution: Computation may take very long time for large samples!} -\item{robust}{logical, if \code{TRUE}, robust standard errors and confidence +\item{robust}{Logical, if \code{TRUE}, robust standard errors and confidence intervals will be reported. Computation of robust standard errors is based on the \code{\link[sjstats]{robust}}-function in the \pkg{sjstats}-package.} -\item{separate.ci.col}{if \code{TRUE}, the CI values are shown in a separate table column. +\item{separate.ci.col}{Logical, if \code{TRUE}, the CI values are shown in a separate table column. Default is \code{FALSE}.} -\item{newline.ci}{logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break +\item{newline.ci}{Logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break between estimate and CI values. If \code{FALSE}, CI values are printed in the same line as estimate values.} -\item{show.est}{logical, if \code{TRUE} (default), the estimates are printed.} +\item{show.est}{Logical, if \code{TRUE} (default), the estimates are printed.} -\item{show.std}{indicates whether standardized beta-coefficients should +\item{show.std}{Indicates whether standardized beta-coefficients should also printed, and if yes, which type of standardization is done. See 'Details'.} -\item{show.ci}{logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use +\item{show.ci}{Logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use \code{FALSE} to omit the CI in the table.} -\item{show.se}{logical, if \code{TRUE}, the standard errors are also printed. +\item{show.se}{Logical, if \code{TRUE}, the standard errors are also printed. Default is \code{FALSE}.} -\item{show.header}{logical, if \code{TRUE}, the header strings \code{string.pred} +\item{show.header}{Logical, if \code{TRUE}, the header strings \code{string.pred} and \code{string.dv} are shown. By default, they're hidden.} -\item{show.col.header}{logical, if \code{TRUE} (default), the table data columns have a headline with +\item{show.col.header}{Logical, if \code{TRUE} (default), the table data columns have a headline with abbreviations for estimates, std. beta-values, confidence interval and p-values.} -\item{show.r2}{logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed +\item{show.r2}{Logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed in the model summary. For linear mixed models, the R2 and Omega-squared values are printed (see \code{\link[sjstats]{r2}} for details).} -\item{show.icc}{logical, if \code{TRUE}, the intra-class-correlation for each +\item{show.icc}{Logical, if \code{TRUE}, the intra-class-correlation for each model is printed in the model summary. Only applies to mixed models.} -\item{show.re.var}{logical, if \code{TRUE}, the variance parameters for the random +\item{show.re.var}{Logical, if \code{TRUE}, the variance parameters for the random effects for each model are printed in the model summary. Only applies to mixed models. For details output, see 'Note' in \code{\link[sjstats]{icc}}.} -\item{show.fstat}{If \code{TRUE}, the F-statistics for each model is printed +\item{show.fstat}{Logical, if \code{TRUE}, the F-statistics for each model is printed in the model summary. Default is \code{FALSE}. This argument does not apply to \code{\link{sjt.lmer}}.} -\item{show.aic}{logical, if \code{TRUE}, the AIC value for each model is printed +\item{show.aic}{Logical, if \code{TRUE}, the AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aicc}{logical, if \code{TRUE}, the second-order AIC value for each model +\item{show.aicc}{Logical, if \code{TRUE}, the second-order AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.dev}{logical, if \code{TRUE}, the deviance for each model +\item{show.dev}{Logical, if \code{TRUE}, the deviance for each model is printed in the model summary.} -\item{string.pred}{character vector,used as headline for the predictor column. +\item{string.pred}{Character vector,used as headline for the predictor column. Default is \code{"Predictors"}.} -\item{string.dv}{character vector, used as headline for the +\item{string.dv}{Character vector, used as headline for the dependent variable columns. Default is \code{"Dependent Variables"}.} -\item{string.interc}{character vector, used as headline for the Intercept row. +\item{string.interc}{Character vector, used as headline for the Intercept row. Default is \code{"Intercept"}.} \item{string.obs}{character vector, used in the summary row for the count of observation (cases). Default is \code{"Observations"}.} -\item{string.est}{character vector, used for the column heading of estimates.} +\item{string.est}{Character vector, used for the column heading of estimates.} -\item{string.std}{character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}.} +\item{string.std}{Character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}.} -\item{string.ci}{character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} +\item{string.ci}{Character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} -\item{string.se}{character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} +\item{string.se}{Character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} -\item{string.p}{character vector, used for the column heading of p values. Default is \code{"p"}.} +\item{string.p}{Character vector, used for the column heading of p values. Default is \code{"p"}.} -\item{ci.hyphen}{character vector, indicating the hyphen for confidence interval range. +\item{ci.hyphen}{Character vector, indicating the hyphen for confidence interval range. May be an HTML entity. See 'Examples'.} \item{minus.sign}{string, indicating the minus sign for negative numbers. May be an HTML entity. See 'Examples'.} -\item{digits.est}{amount of decimals for estimates} +\item{digits.est}{Amount of decimals for estimates} -\item{digits.std}{amount of decimals for standardized beta} +\item{digits.std}{Amount of decimals for standardized beta} -\item{digits.p}{amount of decimals for p-values} +\item{digits.p}{Amount of decimals for p-values} -\item{digits.ci}{amount of decimals for confidence intervals} +\item{digits.ci}{Amount of decimals for confidence intervals} -\item{digits.se}{amount of decimals for standard error} +\item{digits.se}{Amount of decimals for standard error} -\item{digits.summary}{amount of decimals for values in model summary} +\item{digits.summary}{Amount of decimals for values in model summary} -\item{cell.spacing}{numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is +\item{cell.spacing}{Numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is suitable for viewing the table. Decrease this value (0.05 to 0.1) if you want to import the table into Office documents. This is a convenient argument for the \code{CSS} argument for changing cell spacing, which would be: \code{CSS = list(css.thead = "padding:0.2cm;", css.tdata = "padding:0.2cm;")}.} -\item{cell.gpr.indent}{indent for table rows with grouped factor predictors. Only applies +\item{cell.gpr.indent}{Indent for table rows with grouped factor predictors. Only applies if \code{group.pred = TRUE}.} -\item{sep.column}{logical, if \code{TRUE}, an empty table column is added after +\item{sep.column}{Logical, if \code{TRUE}, an empty table column is added after each model column, to add margins between model columns. By default, this column will be added to the output; however, when copying tables to office applications, it might be helpful not to add this separator column when modifying the table layout.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.lmer.Rd b/man/sjt.lmer.Rd index e513bbda..1b46f3e7 100755 --- a/man/sjt.lmer.Rd +++ b/man/sjt.lmer.Rd @@ -22,19 +22,19 @@ sjt.lmer(..., pred.labels = NULL, depvar.labels = NULL, use.viewer = TRUE, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{...}{one or more fitted linear (mixed) models.} +\item{...}{One or more fitted linear (mixed) models.} -\item{pred.labels}{character vector with labels of predictor variables. +\item{pred.labels}{Character vector with labels of predictor variables. If not \code{NULL}, \code{pred.labels} will be used in the first table column with the predictors' names. If \code{NULL}, variable labels are set based on label attributes (see \code{\link[sjmisc]{get_label}}). If \code{pred.labels = ""}, column names (vector names) are used as predictor labels. See 'Examples'.} -\item{depvar.labels}{character vector with labels of dependent +\item{depvar.labels}{Character vector with labels of dependent variables of all fitted models. See 'Examples'.} -\item{remove.estimates}{numeric vector with indices (order equals to row index of \code{coef(fit)}) +\item{remove.estimates}{Numeric vector with indices (order equals to row index of \code{coef(fit)}) or character vector with coefficient names that indicate which estimates should be removed from the table output. The first estimate is the intercept, followed by the model predictors. \emph{The intercept cannot be removed from the table output!} \code{remove.estimates = c(2:4)} @@ -42,15 +42,15 @@ would remove the 2nd to the 4th estimate (1st to 3rd predictor after intercept) \code{remove.estimates = "est_name"} would remove the estimate \emph{est_name}. Default is \code{NULL}, i.e. all estimates are printed.} -\item{group.pred}{logical, if \code{TRUE} (default), automatically groups table rows with +\item{group.pred}{Logical, if \code{TRUE} (default), automatically groups table rows with factor levels of same factor, i.e. predictors of type \code{\link{factor}} will be grouped, if the factor has more than two levels. Grouping means that a separate headline row is inserted to the table just before the predictor values.} -\item{p.numeric}{logical, if \code{TRUE}, the p-values are printed +\item{p.numeric}{Logical, if \code{TRUE}, the p-values are printed as numbers. If \code{FALSE} (default), asterisks are used.} -\item{emph.p}{logical, if \code{TRUE}, significant p-values are shown bold faced.} +\item{emph.p}{Logical, if \code{TRUE}, significant p-values are shown bold faced.} \item{p.zero}{logical, if \code{TRUE}, p-values have a leading 0 before the period (e.g. \emph{0.002}), else p-values start with a period and @@ -60,132 +60,132 @@ without a zero (e.g. \emph{.002}).} F-tests with Kenward-Roger approximation for the df. Caution: Computation may take very long time for large samples!} -\item{separate.ci.col}{if \code{TRUE}, the CI values are shown in a separate table column. +\item{separate.ci.col}{Logical, if \code{TRUE}, the CI values are shown in a separate table column. Default is \code{FALSE}.} -\item{newline.ci}{logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break +\item{newline.ci}{Logical, if \code{TRUE} and \code{separate.ci.col = FALSE}, inserts a line break between estimate and CI values. If \code{FALSE}, CI values are printed in the same line as estimate values.} -\item{show.est}{logical, if \code{TRUE} (default), the estimates are printed.} +\item{show.est}{Logical, if \code{TRUE} (default), the estimates are printed.} -\item{show.std}{indicates whether standardized beta-coefficients should +\item{show.std}{Indicates whether standardized beta-coefficients should also printed, and if yes, which type of standardization is done. See 'Details'.} -\item{show.ci}{logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use +\item{show.ci}{Logical, if \code{TRUE} (default), the confidence intervall is also printed to the table. Use \code{FALSE} to omit the CI in the table.} -\item{show.se}{logical, if \code{TRUE}, the standard errors are also printed. +\item{show.se}{Logical, if \code{TRUE}, the standard errors are also printed. Default is \code{FALSE}.} -\item{show.header}{logical, if \code{TRUE}, the header strings \code{string.pred} +\item{show.header}{Logical, if \code{TRUE}, the header strings \code{string.pred} and \code{string.dv} are shown. By default, they're hidden.} -\item{show.col.header}{logical, if \code{TRUE} (default), the table data columns have a headline with +\item{show.col.header}{Logical, if \code{TRUE} (default), the table data columns have a headline with abbreviations for estimates, std. beta-values, confidence interval and p-values.} -\item{show.r2}{logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed +\item{show.r2}{Logical, if \code{TRUE} (default), the R2 and adjusted R2 values for each model are printed in the model summary. For linear mixed models, the R2 and Omega-squared values are printed (see \code{\link[sjstats]{r2}} for details).} -\item{show.icc}{logical, if \code{TRUE}, the intra-class-correlation for each +\item{show.icc}{Logical, if \code{TRUE}, the intra-class-correlation for each model is printed in the model summary. Only applies to mixed models.} -\item{show.re.var}{logical, if \code{TRUE}, the variance parameters for the random +\item{show.re.var}{Logical, if \code{TRUE}, the variance parameters for the random effects for each model are printed in the model summary. Only applies to mixed models. For details output, see 'Note' in \code{\link[sjstats]{icc}}.} -\item{show.fstat}{If \code{TRUE}, the F-statistics for each model is printed +\item{show.fstat}{Logical, if \code{TRUE}, the F-statistics for each model is printed in the model summary. Default is \code{FALSE}. This argument does not apply to \code{\link{sjt.lmer}}.} -\item{show.aic}{logical, if \code{TRUE}, the AIC value for each model is printed +\item{show.aic}{Logical, if \code{TRUE}, the AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.aicc}{logical, if \code{TRUE}, the second-order AIC value for each model +\item{show.aicc}{Logical, if \code{TRUE}, the second-order AIC value for each model is printed in the model summary. Default is \code{FALSE}.} -\item{show.dev}{logical, if \code{TRUE}, the deviance for each model +\item{show.dev}{Logical, if \code{TRUE}, the deviance for each model is printed in the model summary.} -\item{string.pred}{character vector,used as headline for the predictor column. +\item{string.pred}{Character vector,used as headline for the predictor column. Default is \code{"Predictors"}.} -\item{string.dv}{character vector, used as headline for the +\item{string.dv}{Character vector, used as headline for the dependent variable columns. Default is \code{"Dependent Variables"}.} -\item{string.interc}{character vector, used as headline for the Intercept row. +\item{string.interc}{Character vector, used as headline for the Intercept row. Default is \code{"Intercept"}.} \item{string.obs}{character vector, used in the summary row for the count of observation (cases). Default is \code{"Observations"}.} -\item{string.est}{character vector, used for the column heading of estimates.} +\item{string.est}{Character vector, used for the column heading of estimates.} -\item{string.std}{character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}.} +\item{string.std}{Character vector, used for the column heading of standardized beta coefficients. Default is \code{"std. Beta"}.} -\item{string.ci}{character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} +\item{string.ci}{Character vector, used for the column heading of confidence interval values. Default is \code{"CI"}.} -\item{string.se}{character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} +\item{string.se}{Character vector, used for the column heading of standard error values. Default is \code{"std. Error"}.} -\item{string.p}{character vector, used for the column heading of p values. Default is \code{"p"}.} +\item{string.p}{Character vector, used for the column heading of p values. Default is \code{"p"}.} -\item{ci.hyphen}{character vector, indicating the hyphen for confidence interval range. +\item{ci.hyphen}{Character vector, indicating the hyphen for confidence interval range. May be an HTML entity. See 'Examples'.} \item{minus.sign}{string, indicating the minus sign for negative numbers. May be an HTML entity. See 'Examples'.} -\item{digits.est}{amount of decimals for estimates} +\item{digits.est}{Amount of decimals for estimates} -\item{digits.std}{amount of decimals for standardized beta} +\item{digits.std}{Amount of decimals for standardized beta} -\item{digits.p}{amount of decimals for p-values} +\item{digits.p}{Amount of decimals for p-values} -\item{digits.ci}{amount of decimals for confidence intervals} +\item{digits.ci}{Amount of decimals for confidence intervals} -\item{digits.se}{amount of decimals for standard error} +\item{digits.se}{Amount of decimals for standard error} -\item{digits.summary}{amount of decimals for values in model summary} +\item{digits.summary}{Amount of decimals for values in model summary} -\item{cell.spacing}{numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is +\item{cell.spacing}{Numeric, inner padding of table cells. By default, this value is 0.2 (unit is cm), which is suitable for viewing the table. Decrease this value (0.05 to 0.1) if you want to import the table into Office documents. This is a convenient argument for the \code{CSS} argument for changing cell spacing, which would be: \code{CSS = list(css.thead = "padding:0.2cm;", css.tdata = "padding:0.2cm;")}.} -\item{cell.gpr.indent}{indent for table rows with grouped factor predictors. Only applies +\item{cell.gpr.indent}{Indent for table rows with grouped factor predictors. Only applies if \code{group.pred = TRUE}.} -\item{sep.column}{logical, if \code{TRUE}, an empty table column is added after +\item{sep.column}{Logical, if \code{TRUE}, an empty table column is added after each model column, to add margins between model columns. By default, this column will be added to the output; however, when copying tables to office applications, it might be helpful not to add this separator column when modifying the table layout.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } @@ -253,7 +253,7 @@ data(efc) efc$grp = as.factor(efc$e15relat) levels(x = efc$grp) <- get_labels(efc$e15relat) efc$care.level <- sjmisc::rec(efc$n4pstu, - rec = "0=0;1=1;2=2;3:4=3", + recodes = "0=0;1=1;2=2;3:4=3", as.num = FALSE) levels(x = efc$care.level) <- c("none", "I", "II", "III") diff --git a/man/sjt.mwu.Rd b/man/sjt.mwu.Rd index 4141bdfd..4d090afa 100755 --- a/man/sjt.mwu.Rd +++ b/man/sjt.mwu.Rd @@ -9,36 +9,36 @@ sjt.mwu(x, title = NULL, altr.row.col = TRUE, CSS = NULL, remove.spaces = TRUE) } \arguments{ -\item{x}{results of a Mann-Whitney-U test, provided by \code{\link[sjstats]{mwu}}. See 'Examples'.} +\item{x}{Results of a Mann-Whitney-U test, provided by \code{\link[sjstats]{mwu}}. See 'Examples'.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.pca.Rd b/man/sjt.pca.Rd index 81db541d..a0f71cbc 100755 --- a/man/sjt.pca.Rd +++ b/man/sjt.pca.Rd @@ -14,75 +14,75 @@ sjt.pca(data, rotation = c("varimax", "oblimin"), nmbr.fctr = NULL, remove.spaces = TRUE) } \arguments{ -\item{data}{\code{data.frame} that should be used to compute a PCA, or a \code{\link{prcomp}} object.} +\item{data}{A data frame that should be used to compute a PCA, or a \code{\link{prcomp}} object.} -\item{rotation}{rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation +\item{rotation}{Rotation of the factor loadings. May be \code{"varimax"} for orthogonal rotation or \code{"oblimin"} for oblique transformation.} -\item{nmbr.fctr}{number of factors used for calculating the varimax +\item{nmbr.fctr}{Number of factors used for calculating the varimax rotation. By default, this value is \code{NULL} and the amount of factors is calculated according to the Kaiser-criteria.} -\item{fctr.load.tlrn}{specifies the minimum difference a variable needs to have between +\item{fctr.load.tlrn}{Specifies the minimum difference a variable needs to have between factor loadings (components) in order to indicate a clear loading on just one factor and not -diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading +diffusing over all factors. For instance, a variable with 0.8, 0.82 and 0.84 factor loading on 3 possible factors can not be clearly assigned to just one factor and thus would be removed from the principal component analysis. By default, the minimum difference of loading values between the highest and 2nd highest factor should be 0.1} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{var.labels}{character vector with variable names, which will be used +\item{var.labels}{Character vector with variable names, which will be used to label variables in the output.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{show.cronb}{logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, +\item{show.cronb}{Logical, if \code{TRUE} (default), the cronbach's alpha value for each factor scale will be calculated, i.e. all variables with the highest loading for a factor are taken for the reliability test. The result is an alpha value for each factor dimension. Only applies when \code{data} is a data frame and no \code{\link{prcomp}} object.} -\item{show.msa}{logical, if \code{TRUE}, shows an additional column with the measure of sampling adequacy according +\item{show.msa}{Logical, if \code{TRUE}, shows an additional column with the measure of sampling adequacy according dor each component.} -\item{show.var}{logical, if \code{TRUE}, the proportions of variances for each component as well as cumulative +\item{show.var}{Logical, if \code{TRUE}, the proportions of variances for each component as well as cumulative variance are shown in the table footer.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} -\item{string.pov}{string for the table row that contains the proportions of variances. By default, +\item{string.pov}{String for the table row that contains the proportions of variances. By default, \emph{"Proportion of Variance"} will be used.} -\item{string.cpov}{string for the table row that contains the cumulative variances. By default, +\item{string.cpov}{String for the table row that contains the cumulative variances. By default, \emph{"Cumulative Proportion"} will be used.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } @@ -99,9 +99,9 @@ Invisibly returns for further use. } \description{ -Performes a principle component analysis on a data frame or matrix - (with varimax rotation) and displays the factor solution as HTML - table, or saves them as file. \cr \cr In case a data frame is used as +Performes a principle component analysis on a data frame or matrix + (with varimax or oblimin rotation) and displays the factor solution as HTML + table, or saves them as file. \cr \cr In case a data frame is used as parameter, the Cronbach's Alpha value for each factor scale will be calculated, i.e. all variables with the highest loading for a factor are taken for the reliability test. The result is an alpha value for each factor dimension. @@ -111,8 +111,6 @@ See 'Details' in \code{\link{sjt.frq}}. } \note{ See 'Notes' in \code{\link{sjt.frq}}. - This PCA uses the \code{\link{prcomp}} function and - the \code{\link{varimax}} rotation. } \examples{ \dontrun{ @@ -120,20 +118,10 @@ See 'Notes' in \code{\link{sjt.frq}}. library(sjmisc) data(efc) -# retrieve variable and value labels -varlabs <- get_label(efc) - # recveive first item of COPE-index scale start <- which(colnames(efc) == "c82cop1") # recveive last item of COPE-index scale end <- which(colnames(efc) == "c90cop9") - -# create data frame with COPE-index scale -mydf <- as.data.frame(efc[, c(start:end)]) -colnames(mydf) <- varlabs[c(start:end)] - -sjt.pca(mydf) - # auto-detection of labels sjt.pca(efc[, c(start:end)])} diff --git a/man/sjt.stackfrq.Rd b/man/sjt.stackfrq.Rd index 4500f9f4..aaac1b81 100755 --- a/man/sjt.stackfrq.Rd +++ b/man/sjt.stackfrq.Rd @@ -13,22 +13,22 @@ sjt.stackfrq(items, weight.by = NULL, title = NULL, var.labels = NULL, no.output = FALSE, remove.spaces = TRUE) } \arguments{ -\item{items}{\code{data.frame} with each column representing one item.} +\item{items}{Data frame, with each column representing one item.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{var.labels}{character vector with variable names, which will be used +\item{var.labels}{Character vector with variable names, which will be used to label variables in the output.} -\item{value.labels}{character vector (or \code{list} of character vectors) +\item{value.labels}{Character vector (or \code{list} of character vectors) with value labels of the supplied variables, which will be used to label variable values in the output.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} \item{sort.frq}{logical, indicates whether the \code{items} should be ordered by @@ -41,10 +41,10 @@ by highest count of first or last category of \code{items}. \item or \code{NULL} (default) for no sorting. }} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} \item{string.total}{label for the total N column.} @@ -63,36 +63,36 @@ are added to the output.} The skewness is retrieved from the \code{\link[psych]{describe}}-function of the \pkg{psych}-package.} -\item{show.kurtosis}{If \code{TRUE}, the variable's kurtosis is added to the summary. +\item{show.kurtosis}{Logical, if \code{TRUE}, the variable's kurtosis is added to the summary. The kurtosis is retrieved from the \code{\link[psych]{describe}}-function of the \pkg{psych}-package and indicated by a lower case Greek omega.} \item{digits.stats}{amount of digits for rounding the skewness and kurtosis valuess. Default is 2, i.e. skewness and kurtosis values have 2 digits after decimal point.} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } diff --git a/man/sjt.xtab.Rd b/man/sjt.xtab.Rd index ebc97b72..391c00c7 100755 --- a/man/sjt.xtab.Rd +++ b/man/sjt.xtab.Rd @@ -17,35 +17,35 @@ sjt.xtab(var.row, var.col, weight.by = NULL, title = NULL, use.viewer = TRUE, no.output = FALSE, remove.spaces = TRUE, ...) } \arguments{ -\item{var.row}{variable that should be displayed in the table rows.} +\item{var.row}{Variable that should be displayed in the table rows.} -\item{var.col}{variable that should be displayed in the table columns.} +\item{var.col}{Cariable that should be displayed in the table columns.} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{title}{table caption, as character vector.} +\item{title}{Table caption, as character vector.} -\item{var.labels}{character vector with variable names, which will be used +\item{var.labels}{Character vector with variable names, which will be used to label variables in the output.} -\item{value.labels}{character vector (or \code{list} of character vectors) +\item{value.labels}{Character vector (or \code{list} of character vectors) with value labels of the supplied variables, which will be used to label variable values in the output.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} -\item{show.obs}{logical, if \code{TRUE}, observed values are shown} +\item{show.obs}{Logical, if \code{TRUE}, observed values are shown} -\item{show.cell.prc}{logical, if \code{TRUE}, cell percentage values are shown} +\item{show.cell.prc}{Logical, if \code{TRUE}, cell percentage values are shown} -\item{show.row.prc}{logical, if \code{TRUE}, row percentage values are shown} +\item{show.row.prc}{Logical, if \code{TRUE}, row percentage values are shown} -\item{show.col.prc}{logical, if \code{TRUE}, column percentage values are shown} +\item{show.col.prc}{Logical, if \code{TRUE}, column percentage values are shown} -\item{show.exp}{logical, if \code{TRUE}, expected values are also shown} +\item{show.exp}{Logical, if \code{TRUE}, expected values are also shown} \item{show.legend}{logical, if \code{TRUE}, and depending on plot type and function, a legend is added to the plot.} @@ -53,7 +53,7 @@ function, a legend is added to the plot.} \item{show.na}{logical, if \code{TRUE}, \code{\link{NA}}'s (missing values) are added to the output.} -\item{show.summary}{logical, if \code{TRUE}, a summary row with +\item{show.summary}{Logical, if \code{TRUE}, a summary row with chi-squared statistics, degrees of freedom and Cramer's V or Phi coefficient and p-value for the chi-squared statistics.} @@ -61,9 +61,9 @@ coefficient and p-value for the chi-squared statistics.} be one of \code{"auto"}, \code{"cramer"}, \code{"phi"}, \code{"spearman"}, \code{"kendall"} or \code{"pearson"}. See 'Details'.} -\item{string.total}{label for the total column / row header} +\item{string.total}{Character label for the total column / row header} -\item{digits}{numeric, amount of digits after decimal point when rounding estimates and values.} +\item{digits}{Numeric, amount of digits after decimal point when rounding estimates and values.} \item{tdcol.n}{Color for highlighting count (observed) values in table cells. Default is black.} @@ -75,10 +75,10 @@ be one of \code{"auto"}, \code{"cramer"}, \code{"phi"}, \code{"spearman"}, \item{tdcol.col}{Color for highlighting column percentage values in table cells. Default is green.} -\item{emph.total}{logical, if \code{TRUE}, the total column and row will be emphasized with a +\item{emph.total}{Logical, if \code{TRUE}, the total column and row will be emphasized with a different background color. See \code{emph.color}.} -\item{emph.color}{logical, if \code{emph.total = TRUE}, this color value will be used +\item{emph.color}{Logical, if \code{emph.total = TRUE}, this color value will be used for painting the background of the total column and row. Default is a light grey.} \item{prc.sign}{The percentage sign that is printed in the table cells, in HTML-format. @@ -88,29 +88,29 @@ the percentage value.} \item{hundret}{Default value that indicates the 100-percent column-sums (since rounding values may lead to non-exact results). Default is \code{"100.0"}.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} diff --git a/man/view_df.Rd b/man/view_df.Rd index 47c41c74..46d82b64 100755 --- a/man/view_df.Rd +++ b/man/view_df.Rd @@ -13,74 +13,74 @@ view_df(x, weight.by = NULL, altr.row.col = TRUE, show.id = TRUE, remove.spaces = TRUE) } \arguments{ -\item{x}{\code{data.frame}, imported by \code{\link[sjmisc]{read_spss}}, +\item{x}{A (labelled) data frame, imported by \code{\link[sjmisc]{read_spss}}, \code{\link[sjmisc]{read_sas}} or \code{\link[sjmisc]{read_stata}} function, or any similar labelled data frame (see \code{\link[sjmisc]{set_label}} and \code{\link[sjmisc]{set_labels}}).} -\item{weight.by}{weight factor that will be applied to weight all cases. -Must be a vector of same length as the input vector. Default is +\item{weight.by}{Vector of weights that will be applied to weight all cases. +Must be a vector of same length as the input vector. Default is \code{NULL}, so no weights are used.} -\item{altr.row.col}{logical, if \code{TRUE}, alternating rows are highlighted with a light gray +\item{altr.row.col}{Logical, if \code{TRUE}, alternating rows are highlighted with a light gray background color.} -\item{show.id}{logical, if \code{TRUE} (default), the variable ID is shown in the first column.} +\item{show.id}{Logical, if \code{TRUE} (default), the variable ID is shown in the first column.} \item{show.type}{logical, if \code{TRUE}, the variable type is shown in a separate row respectively column.} -\item{show.values}{logical, if \code{TRUE} (default), the variable values are shown as additional column.} +\item{show.values}{Logical, if \code{TRUE} (default), the variable values are shown as additional column.} -\item{show.labels}{logical, if \code{TRUE} (default), the value labels are shown as additional column.} +\item{show.labels}{Logical, if \code{TRUE} (default), the value labels are shown as additional column.} -\item{show.frq}{logical, if \code{TRUE}, an additional column with frequencies for each variable is shown.} +\item{show.frq}{Logical, if \code{TRUE}, an additional column with frequencies for each variable is shown.} -\item{show.prc}{logical, if \code{TRUE}, an additional column with percentage of frequencies for each variable is shown.} +\item{show.prc}{Logical, if \code{TRUE}, an additional column with percentage of frequencies for each variable is shown.} -\item{show.wtd.frq}{logical, if \code{TRUE}, an additional column with weighted +\item{show.wtd.frq}{Logical, if \code{TRUE}, an additional column with weighted frequencies for each variable is shown. Weights strem from \code{weight.by}.} -\item{show.wtd.prc}{logical, if \code{TRUE}, an additional column with weighted +\item{show.wtd.prc}{Logical, if \code{TRUE}, an additional column with weighted percentage of frequencies for each variable is shown. Weights strem from \code{weight.by}.} \item{show.na}{logical, if \code{TRUE}, \code{\link{NA}}'s (missing values) are added to the output.} -\item{sort.by.name}{logical, if \code{TRUE}, rows are sorted according to the variable +\item{sort.by.name}{Logical, if \code{TRUE}, rows are sorted according to the variable names. By default, rows (variables) are ordered according to their order in the data frame.} -\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis +\item{wrap.labels}{numeric, determines how many chars of the value, variable or axis labels are displayed in one line and when a line break is inserted.} \item{hide.progress}{logical, if \code{TRUE}, the progress bar that is displayed when creating the output is hidden. Default in \code{FALSE}, hence the bar is visible.} -\item{CSS}{\code{\link{list}}-object with user-defined style-sheet-definitions, according to the +\item{CSS}{A \code{\link{list}} with user-defined style-sheet-definitions, according to the \href{http://www.w3.org/Style/CSS/}{official CSS syntax}. For more details, see \href{../doc/sjtbasic.html}{this package-vignette}, or 'Details' in \code{\link{sjt.frq}}.} -\item{encoding}{string, indicating the charset encoding used for variable and +\item{encoding}{String, indicating the charset encoding used for variable and value labels. Default is \code{NULL}, so encoding will be auto-detected depending on your platform (e.g., \code{"UTF-8"} for Unix and \code{"Windows-1252"} for Windows OS). Change encoding if specific chars are not properly displayed (e.g. German umlauts).} -\item{file}{destination file, if the output should be saved as file. +\item{file}{Destination file, if the output should be saved as file. If \code{NULL} (default), the output will be saved as temporary file and openend either in the IDE's viewer pane or the default web browser.} -\item{use.viewer}{If \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If +\item{use.viewer}{Logical, if \code{TRUE}, the HTML table is shown in the IDE's viewer pane. If \code{FALSE} or no viewer available, the HTML table is opened in a web browser.} -\item{no.output}{logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in +\item{no.output}{Logical, if \code{TRUE}, the html-output is neither opened in a browser nor shown in the viewer pane and not even saved to file. This option is useful when the html output should be used in \code{knitr} documents. The html output can be accessed via the return value.} -\item{remove.spaces}{logical, if \code{TRUE}, leading spaces are removed from all lines in the final string +\item{remove.spaces}{Logical, if \code{TRUE}, leading spaces are removed from all lines in the final string that contains the html-data. Use this, if you want to remove parantheses for html-tags. The html-source may look less pretty, but it may help when exporting html-tables to office tools.} } @@ -97,10 +97,9 @@ Invisibly returns \description{ Save (or show) content of an imported SPSS, SAS or Stata data file, or any similar labelled \code{data.frame}, as HTML table. - Similar to the SPSS variable view. This quick overview shows - variable ID numner, name, label, type and associated - value labels. The result can be considered as "codeplan" of - the data frame. + This quick overview shows variable ID number, name, label, + type and associated value labels. The result can be + considered as "codeplan" of the data frame. } \details{ See 'Details' in \code{\link{sjt.frq}}. @@ -123,9 +122,7 @@ view_df(efc, show.values = FALSE, show.labels = FALSE) # view variables including variable typed, orderd by name view_df(efc, sort.by.name = TRUE, show.type = TRUE) -# ---------------------------------------------------------------- # User defined style sheet -# ---------------------------------------------------------------- view_df(efc, CSS = list(css.table = "border: 2px solid;", css.tdata = "border: 1px solid;",