Skip to contents

Summary statistics for a single numeric variable, possibly separated by the levels of a factor variable or variables. This function is very similar to summary for a numeric variable.

Usage

Summarize(object, ...)

# S3 method for default
Summarize(
  object,
  digits = getOption("digits"),
  na.rm = TRUE,
  exclude = NULL,
  nvalid = c("different", "always", "never"),
  percZero = c("different", "always", "never"),
  ...
)

# S3 method for formula
Summarize(
  object,
  data = NULL,
  digits = getOption("digits"),
  na.rm = TRUE,
  exclude = NULL,
  nvalid = c("different", "always", "never"),
  percZero = c("different", "always", "never"),
  ...
)

Arguments

object

A vector of numeric data.

...

Not implemented.

digits

A single numeric that indicates the number of decimals to round the numeric summaries.

na.rm

A logical that indicates whether numeric missing values (NA) should be removed (=TRUE, default) or not.

exclude

A string that contains the level that should be excluded from a factor variable.

nvalid

A string that indicates how the “validn” result will be handled. If "always" then “validn” will always be shown and if "never" then “validn” will never be shown. However, if "different" (DEFAULT), then “validn” will only be shown if it differs from “n” (or if at least one group differs from “n” when summarized by multiple groups).

percZero

A string that indicates how the “percZero” result will be handled. If "always" then “percZero” will always be shown and if "never" then “percZero” will never be shown. However, if "different" (DEFAULT), then “percZero” will only be shown if it is greater than zero (or if at least one group is greater than zero when summarized by multiple groups).

data

A data.frame that contains the variables in formula.

Value

A named vector or data frame (when a quantitative variable is separated by one or two factor variables) of summary statistics for numeric data.

Details

This function is primarily used with formulas of the following types (where quant and factor generically represent quantitative/numeric and factor variables, respectively):

FormulaDescription of Summary
~quantNumerical summaries (see below) of quant.
quant~factorSummaries of quant separated by levels in factor.
quant~factor1*factor2Summaries of quant separated by the combined levels in factor1 and factor2.

Numerical summaries include all results from summary (min, Q1, mean, median, Q3, and max) and the sample size, valid sample size (sample size minus number of NAs), and standard deviation (i.e., sd). NA values are removed from the calculations with na.rm=TRUE (the DEFAULT). The number of digits in the returned results are controlled with digits=.

Note

Students often need to examine basic statistics of a quantitative variable separated for different levels of a categorical variable. These results may be obtained with tapply, by, or aggregate (or with functions in other packages), but the use of these functions is not obvious to newbie students or return results in a format that is not obvious to newbie students. Thus, the formula method to Summarize allows newbie students to use a common notation (i.e., formula) to easily compute summary statistics for a quantitative variable separated by the levels of a factor.

See also

See summary for related one dimensional functionality. See tapply, summaryBy in doBy, describe in psych, describe in prettyR, and basicStats in fBasics for similar “by” functionality.

Author

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## Create a data.frame of "data"
n <- 102
d <- data.frame(y=c(0,0,NA,NA,NA,runif(n-5)),
                w=sample(7:9,n,replace=TRUE),
                v=sample(0:2,n,replace=TRUE),
                g1=factor(sample(c("A","B","C",NA),n,replace=TRUE)),
                g2=factor(sample(c("male","female","UNKNOWN"),n,replace=TRUE)),
                g3=sample(c("a","b","c","d"),n,replace=TRUE),
                stringsAsFactors=FALSE)

# typical output of summary() for a numeric variable
summary(d$y)   
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.    NA's 
#>  0.0000  0.2667  0.5156  0.5131  0.7794  0.9975       3 

# this function           
Summarize(d$y,digits=3)
#>        n   nvalid     mean       sd      min       Q1   median       Q3 
#>  102.000   99.000    0.513    0.314    0.000    0.267    0.516    0.779 
#>      max percZero 
#>    0.998    2.020 
Summarize(~y,data=d,digits=3)
#>        n   nvalid     mean       sd      min       Q1   median       Q3 
#>  102.000   99.000    0.513    0.314    0.000    0.267    0.516    0.779 
#>      max percZero 
#>    0.998    2.020 
Summarize(y~1,data=d,digits=3)
#>        n   nvalid     mean       sd      min       Q1   median       Q3 
#>  102.000   99.000    0.513    0.314    0.000    0.267    0.516    0.779 
#>      max percZero 
#>    0.998    2.020 

# note that nvalid is not shown if there are no NAs and
#   percZero is not shown if there are no zeros
Summarize(~w,data=d,digits=3)
#>       n    mean      sd     min      Q1  median      Q3     max 
#> 102.000   7.804   0.809   7.000   7.000   8.000   8.000   9.000 
Summarize(~v,data=d,digits=3)
#>        n     mean       sd      min       Q1   median       Q3      max 
#>  102.000    0.980    0.856    0.000    0.000    1.000    2.000    2.000 
#> percZero 
#>   37.255 

# note that the nvalid and percZero results can be forced to be shown
Summarize(~w,data=d,digits=3,nvalid="always",percZero="always")
#>        n   nvalid     mean       sd      min       Q1   median       Q3 
#>  102.000  102.000    7.804    0.809    7.000    7.000    8.000    8.000 
#>      max percZero 
#>    9.000    0.000 

## Numeric vector by levels of a factor variable
Summarize(y~g1,data=d,digits=3)
#>   g1  n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1  A 21     21 0.513 0.337 0.000 0.254  0.535 0.854 0.974    4.762
#> 2  B 27     25 0.530 0.323 0.000 0.259  0.528 0.808 0.963    4.000
#> 3  C 27     26 0.516 0.286 0.023 0.302  0.441 0.754 0.998    0.000
Summarize(y~g2,data=d,digits=3)
#>        g2  n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1 UNKNOWN 35     35 0.538 0.284 0.000 0.376  0.516 0.766 0.988    2.857
#> 2  female 37     34 0.519 0.336 0.000 0.240  0.521 0.838 0.998    2.941
#> 3    male 30     30 0.478 0.329 0.003 0.189  0.515 0.755 0.963    0.000
Summarize(y~g2,data=d,digits=3,exclude="UNKNOWN")
#>       g2  n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1 female 37     34 0.519 0.336 0.000 0.240  0.521 0.838 0.998    2.941
#> 2   male 30     30 0.478 0.329 0.003 0.189  0.515 0.755 0.963    0.000

## Numeric vector by levels of two factor variables
Summarize(y~g1+g2,data=d,digits=3)
#>   g1      g2  n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1  A UNKNOWN  6      6 0.542 0.342 0.124 0.323  0.467 0.843 0.953    0.000
#> 2  B UNKNOWN 10     10 0.616 0.298 0.000 0.475  0.582 0.894 0.947   10.000
#> 3  C UNKNOWN 11     11 0.481 0.273 0.027 0.359  0.416 0.651 0.988    0.000
#> 4  A  female  9      9 0.540 0.364 0.000 0.274  0.666 0.854 0.974   11.111
#> 5  B  female  8      6 0.537 0.330 0.099 0.295  0.572 0.756 0.958    0.000
#> 6  C  female  8      7 0.500 0.370 0.023 0.238  0.421 0.791 0.998    0.000
#> 7  A    male  6      6 0.444 0.344 0.017 0.213  0.394 0.708 0.894    0.000
#> 8  B    male  9      9 0.429 0.354 0.003 0.147  0.280 0.709 0.963    0.000
#> 9  C    male  8      8 0.578 0.248 0.186 0.360  0.720 0.746 0.819    0.000
Summarize(y~g1+g2,data=d,digits=3,exclude="UNKNOWN")
#>   g1     g2 n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1  A female 9      9 0.540 0.364 0.000 0.274  0.666 0.854 0.974   11.111
#> 2  B female 8      6 0.537 0.330 0.099 0.295  0.572 0.756 0.958    0.000
#> 3  C female 8      7 0.500 0.370 0.023 0.238  0.421 0.791 0.998    0.000
#> 4  A   male 6      6 0.444 0.344 0.017 0.213  0.394 0.708 0.894    0.000
#> 5  B   male 9      9 0.429 0.354 0.003 0.147  0.280 0.709 0.963    0.000
#> 6  C   male 8      8 0.578 0.248 0.186 0.360  0.720 0.746 0.819    0.000

## What happens if RHS of formula is not a factor
Summarize(y~w,data=d,digits=3)
#>   w  n nvalid  mean    sd   min    Q1 median    Q3   max percZero
#> 1 7 45     44 0.585 0.323 0.000 0.320  0.707 0.879 0.974    2.273
#> 2 8 32     32 0.461 0.319 0.000 0.196  0.403 0.677 0.998    3.125
#> 3 9 25     23 0.448 0.271 0.003 0.295  0.421 0.635 0.953    0.000

## Summarizing multiple variables in a data.frame (must reduce to numerics)
lapply(as.list(d[,1:3]),Summarize,digits=4)
#> $y
#>        n   nvalid     mean       sd      min       Q1   median       Q3 
#> 102.0000  99.0000   0.5131   0.3142   0.0000   0.2667   0.5156   0.7794 
#>      max percZero 
#>   0.9975   2.0202 
#> 
#> $w
#>        n     mean       sd      min       Q1   median       Q3      max 
#> 102.0000   7.8039   0.8089   7.0000   7.0000   8.0000   8.0000   9.0000 
#> 
#> $v
#>        n     mean       sd      min       Q1   median       Q3      max 
#> 102.0000   0.9804   0.8557   0.0000   0.0000   1.0000   2.0000   2.0000 
#> percZero 
#>  37.2549 
#>