Package {descstat}

descstat: a toolbox for descriptive statistics

Description

Descriptive statistics consist on presenting the distribution of series for a sample in tables (frequency table for one series, contingency tables for two series), ploting this distribution and computing some statistics that summarise it. descstat provides a complete toolbox to perform this tasks. It has been writen using the tidyverse conventions, especially the selection of series using their unquoted names and the use of the pipe operator.

The bin class

The bin function takes a series as input that can either:

• a continouis variable,

• a categorical series,

• an integer series,

• a continuous bin series

and returns an object of class bin. The bin function is particularly usefull for continuous series. It enables:

• creating bins from numerical values, which is performed by the base::cut function which turns a numerical series to a bin,

• coercing bins to numerical values, eg getting from the ⁠[10,20)⁠ bin the lower bound (10), the upper bound (20), the center (15) or whatever other value of the bin,

• reducing the number of bins by merging some of them (for example ⁠[0,10)⁠, ⁠[10, 20)⁠, ⁠[20,30)⁠, ⁠[30,Inf)⁠ to ⁠[0,20)⁠, ⁠[20,Inf)⁠

The last task is performed using the as_numeric function. Coercing bins to their center values is the basis of the computation of descripting statistics for bins.

Frequency and contingency tables

The freq_table and cont_table are based on the dplyr::count function but offer a much richer interface and performs easily usual operations which are tedious to obtain with dplyr::count or base::table functions. This includes:

• adding a total,

• for frequency tables, computing other kind of frequencies than the counts, for example relative frequencies, percentage, cummulative frequencies, etc.,

• for contingency tables, computing easily the joint, marginal and conditional distributions,

• printing easily the contingency table as a double entry table.

Plotting the distribution

descstat uses the tinyplot package to provide classic plots for univariate or bivariate distributions. This includes histogram, frequency plot, pie chart, cummulative plot and Lorenz curve. More precisely, type_dsc_### functions are provided and the relevant plot is obtained using ⁠tinyplot(..., type = type_dsc_###)⁠.

Descriptive statistics

A full set of statistical functions (of central tendency, dispersion, shape, concentration and covariation) are provided and can be applied directly on objects of class freq_table or cont_table. Some of them are methods of generics defined by the base or stats package, some other are defined as methods for generics function provided by the descstat function when the corresponding R function is not generic. For example,

• mean is generic, so that we wrote a mean.freq_table method to compute directly the mean of a series from a frequency table.

• var is not generic, so that we provide the variance generic and a method for freq_table objects.

Author(s)

Maintainer: Yves Croissant yves.croissant@univ-reunion.fr

See Also

Useful links:

• https://www.r-project.org

Bin series

Description

A new class called bin is provided ; a bin is a series that contain a relatively few distinct values, that can be used to compute a frequency table. The input series can be either :

• an integer series,

• a contbin series (a series that contain values as ⁠[20, 40)⁠,

• a categorical series,

• a continuous numerical series.

The as_numeric function is relevant for numerical bins. It converts a numerical bin (an interval) to a value of the underlying variable defined by its relative position (from 0 lower bound to 1 upper bound in the bin). Specific arguments are provided for the first and the last bins

Usage

bin(
  x,
  breaks = NULL,
  max = NULL,
  levels = NULL,
  right = TRUE,
  xlast = NULL,
  wlast = NULL,
  xfirst = NULL
)

as_numeric(x, pos = 0, xfirst = NULL, xlast = NULL, wlast = NULL)

## S3 method for class 'bin'
cut(x, ..., breaks = NULL)

## S3 method for class 'character'
cut(x, ..., breaks = NULL)

## S3 method for class 'factor'
cut(x, ..., breaks = NULL)

Arguments

Details

The bin function takes a series as input and returns a series of class bin. It has a type attribute that can be either equal to integer, contbin or categorical, and performs the following tasks:

• for categorical series, the levels can be defined, renamed and collapsed using the level argument, - for integer series, a >= J series can be computed by setting the max argument to J, so that all the values greater or equal than J are collapsed and the J, J+1, J+2, ... values are replaced by the mean of the values greater or equal than J, - numerical bin series are kept as is, or the number of classes can be reduced using the breaks argument, - continuous numerical series are transfomed in numerical bin series, using the breaks argument (if NULL, the breaks are automatically computed) and the right argument can be set to TRUE (the intervals are closed on the right, the default), or to FALSE (the intervals are closed on the left).

Value

a series of class bin with a 'type attribute

Author(s)

Yves Croissant

Examples

# get a few values of the `size` series of the `wages` data set
z <- head(wages$size, 10)
bin(z)
# reduce the number of bins
bin(z, breaks = c(20, 50, 100))
# set the right value of the last interval to 50
bin(z, breaks = 50)
# the `children` series of the `rgp` data set
z <- rgp$children
bin(z) |> head(20)
# set a >= 3 cathegory
bin(z, max = 3) |> head(20)
# the `sector` series of the `wages` data set contains a factor
# with levels `industry`, `building`, `business`, `services` and
# `administration`
z <- head(wages$sector)
bin(z)
# change the order of the levels:
bin(z, levels = c("business", "services", "administration", "building", "industry"))
# rename some levels
bin(z, levels = c("business", "services", government = "administration",
                  construction = "building", "industry"))
# collapse some levels
bin(z, levels = list(blue = c("building", "industry"),
                     white = c("business", "services"),
                     government = "administration"))
z <- head(wages$size, 10)
# coerce to a numeric using the center of the bins
as_numeric(z, pos = 0.5)
# special values for the center of the first and of the last bin
as_numeric(z, pos = 0.5, xfirst = 5, xlast = 400)
# same, but indicating that the width of the last class should be
# twice the one of the before last
as_numeric(z, pos = 0.5, xfirst = 5, wlast = 2)

Functions to compute statistics on bivariate distributions

Description

These functions are intended to compute from a cont_table objects covariation statistics, ie the covariance, the correlation coefficient, variance decomposition and regression line.

Usage

covariance(data, ...)

correlation(data, ...)

## S3 method for class 'cont_table'
covariance(data, ...)

## S3 method for class 'cont_table'
correlation(data, ...)

## S3 method for class 'cont_table'
anova(object, x, ...)

## S3 method for class 'anova.cont_table'
summary(object, ...)

regline(formula, data)

Arguments

Value

a numeric or a tibble

Author(s)

Yves Croissant

Examples

# the covariance and the linear correlation coefficient are
# computed using only the `cont_table`
# First reduce the number of bins
wages2 <- wages
wages2$size <- cut(wages2$size, breaks = c(20, 50, 100))
wages2$wage <- cut(wages$wage, breaks = c(10, 30, 50))
wages2 |> cont_table(wage, size) |> covariance()
wages2 |> cont_table(wage, size) |> correlation()
# For the analyse of variance, one of the two series should be
# indicated
wages2 |> cont_table(wage, size) |> anova(wage)
wages2 |> cont_table(wage, size) |> anova(wage) |> summary()
# For the regression line, a formula should be provided
wages2 |> cont_table(wage, size) |> regline(formula = wage ~ size)

Contingency table

Description

A contingency table returns the counts of all the combinations of the modalities of two series in a table for which every modality of the first series is a row and every modality of the second series is a column. The joint, marginal and conditional functions compute these three distributions from the contingency table (by indicating one series for the last two).

Usage

cont_table(
  data,
  x1,
  x2,
  weights = NULL,
  freq = NULL,
  total = FALSE,
  xfirst1 = NULL,
  xlast1 = NULL,
  wlast1 = NULL,
  xfirst2 = NULL,
  xlast2 = NULL,
  wlast2 = NULL,
  breaks1 = NULL,
  breaks2 = NULL,
  max1 = NULL,
  max2 = NULL,
  right1 = NULL,
  right2 = NULL,
  levels1 = NULL,
  levels2 = NULL
)

joint(data)

conditional(data, x = NULL, x_is_char = FALSE)

marginal(data, x = NULL, f = "f", vals = NULL, x_is_char = FALSE)

wide(x)

Arguments

Details

cont_table actually returns a tibble in "long format", as the dplyr::count table does. As the returned object is of class cont_table, this is the format and print methods that turns the tibble in a wide format before printing.

The conditional and joint functions return a cont_table object, as the marginal function returns a freq_table object.

Value

a tibble

Author(s)

Yves Croissant

Examples

# get a contingency table containing education and sex
cont_table(employment, education, sex)
# instead of counts, sum the weights
cont_table(employment, education, sex, weights = weights)
# get the joint distribution and the conditional and marginal
# distribution of sex
cont_table(employment, education, sex) |> joint()
cont_table(employment, education, sex) |> marginal(sex)
cont_table(employment, education, sex) |> conditional(sex)
cont_table(employment, education, sex) |> joint() |> wide()

French employment survey

Description

The employment survey gives information about characteristics of a sample of individuals (employed/unemployed, part/full time job, education, etc.).

Format

a tibble containing

• activity : a factor with levels occupied, unemployed and inactive,

• time : job time a factor with levels part, full and unknown,

• education : level of education,

• age : age in years,

• sex : one of male or female,

• household : kind of household, single, monop (mono-parental family), couple (couple without children), family (couple with families) and other,

• weights : weights to mimic the population.

Source

Employment survey 2018, INSEE's website.

Frequency table

Description

Compute the frequency table of a categorical or a numerical series.

Usage

freq_table(
  data,
  x,
  f = "n",
  vals = NULL,
  breaks = NULL,
  max = NULL,
  levels = NULL,
  right = TRUE,
  weights = NULL,
  xfirst = NULL,
  xlast = NULL,
  wlast = NULL,
  total = FALSE,
  freq = NULL,
  mass = NULL,
  center = NULL,
  numeric = TRUE,
  print = FALSE,
  x_is_char = FALSE
)

Arguments

Value

a tibble containing the specified values of vals and f.

Author(s)

Yves Croissant

Examples

# in table padova, price is a numeric variable, a vector of breaks should be provided
padova |> freq_table(price,
                      breaks = c(50, 100, 150, 200, 250, 300, 350, 400),
                      right = TRUE)
# return relative frequencies and densities, and the center value
# of the series and the width of the bin
padova |> freq_table(price,
                      breaks = c(50, 100, 150, 200, 250, 300, 350, 400),
                      right = TRUE, f = "fd", vals = "xa")
# in table wages, wage is a factor that represents the classes
wages |> freq_table(wage, "d")
# a breaks argument is provided to reduce the number of classes
wages |> freq_table(wage, breaks = c(10, 20, 30, 40, 50))
# a total argument add a total to the frequency table
wages |> freq_table(wage, breaks = c(10, 20, 30, 40, 50), total = TRUE)
# ìncome is already a frequency table, the freq argument
# is mandatory
income |> freq_table(inc_class, freq = number)
# the mass argument can be indicated if one column contains the
# mass of the series in each bin. In this case, the center of the
# class are exactly the mean of the series in each bin
income |> freq_table(inc_class, freq = number, mass = tot_inc)
# reducing the number of classes
income |> freq_table(inc_class, freq = number, mass = tot_inc,
                     breaks = c(10, 20, 50, 100, 1000))
# rgp contains a children series which indicates the number of
# children of the households
rgp |> freq_table(children)
# a max argument can be indicated to merge the unusual high
# values of number of childre
rgp |> freq_table(children, max = 4)
# employment is a non random survey, there is a weights series
# that can be used to compute the frequency table according to the
# sum of weights and not to counts
employment |> freq_table(education)
employment |> freq_table(education, weights = weights)

Income of French households

Description

Bins of income classes, number of households and mass of income.

Format

a tibble containing :

• bin: bin of income,

• number: number of households in the bin,

• income: mass of income in the bin.

Source

Impot sur le revenu par commune (IRCOM) DGI's website.

Housing prices in Padova

Description

This data set documents characteristics (including the prices) of a sample of housings in Padova.

Format

a tibble containing

• zone : one of the 12 zones of Padova,

• condition : new for new housings, ordinary or good for old ones,

• house : dummy for houses,

• floor : floor,

• rooms : number of rooms,

• bathrooms : number of bathrooms,

• parking : dummy for parkings,

• energy : energy cathegory for the house (A for the best, G for the worst),

• area : area of the house in square meters,

• price : price of the house in thousands of euros.

Source

Data in Brief's website, doi:10.1016/j.dib.2015.11.027.

References

Bonifaci P, Copiello S (2015). "Real estate market and building energy performance: Data for a mass appraisal approach." Data in Brief, 5, 1060-1065. ISSN 2352-3409.

Extract of the French census

Description

This extract of the French census gives information about a sample of French households.

Format

a tibble containing :

• cars : number of cars,

• rooms : number of rooms of the housing,

• children : number of children,

• type : type of household ; couple or monop (for mono-parental families),

Source

INSEE's website.

tinyplot types

Description

tinyplot types for frequency tables

Usage

type_pie(
  position = NULL,
  edges = 200,
  hole = 0,
  radius = 1,
  init.angle = 0,
  f = c("none", "n", "f", "p"),
  digits = 2,
  pal = "Set2"
)

type_lorenz()

type_freqpoly(breaks = NULL)

type_histo(wlast = 2, breaks = NULL)

type_cumul(expand = 0.1, geom = NULL, breaks = NULL, max = NULL)

type_cont.table(size = c(1, 2))

type_anova(level = 0.95, length = 0.1, expand = 0.05)

Arguments

Value

invisible, used for its side effects

Author(s)

Yves Croissant

Functions to compute statistics on univariate distributions

Description

descstat provide functions to compute statistics on an univariate distribution. This includes central tendency, dispersion, shape and concentration.

Usage

variance(x, ...)

gmean(x, r = 1, ...)

gini(x, ...)

stdev(x, ...)

madev(x, ...)

modval(x, ...)

medial(x, ...)

kurtosis(x, ...)

skewness(x, ...)

## Default S3 method:
variance(x, w = NULL, ...)

## Default S3 method:
gmean(x, r = 1, ...)

## Default S3 method:
stdev(x, w = NULL, ...)

## Default S3 method:
madev(x, w = NULL, center = c("median", "mean"), ...)

## Default S3 method:
skewness(x, ...)

## Default S3 method:
kurtosis(x, ...)

## S3 method for class 'freq_table'
mean(x, ...)

## S3 method for class 'freq_table'
gmean(x, r = 1, ...)

## S3 method for class 'freq_table'
variance(x, ...)

## S3 method for class 'freq_table'
stdev(x, ...)

## S3 method for class 'freq_table'
skewness(x, ...)

## S3 method for class 'freq_table'
kurtosis(x, ...)

## S3 method for class 'freq_table'
madev(x, center = c("median", "mean"), ...)

## S3 method for class 'freq_table'
modval(x, ...)

## S3 method for class 'freq_table'
quantile(x, y = c("value", "mass"), probs = c(0.25, 0.5, 0.75), ...)

## S3 method for class 'freq_table'
median(x, ..., y = c("value", "mass"))

## S3 method for class 'freq_table'
medial(x, ...)

## S3 method for class 'freq_table'
gini(x, ...)

## S3 method for class 'cont_table'
modval(x, ...)

## S3 method for class 'cont_table'
gini(x, ...)

## S3 method for class 'cont_table'
skewness(x, ...)

## S3 method for class 'cont_table'
kurtosis(x, ...)

## S3 method for class 'cont_table'
madev(x, center = c("median", "mean"), ...)

## S3 method for class 'cont_table'
mean(x, ...)

## S3 method for class 'cont_table'
variance(x, ...)

## S3 method for class 'cont_table'
stdev(x, ...)

Arguments

Details

The following functions are provided:

• central tendency: mean, median, medial, modval (for the mode),

• dispersion: variance, stdev, maddev (for mean absolute deviation) and quantile,

• shape: skewness and kurtosis,

• concentration: gini.

When a generic function exists in base R (or in the stats package), methods are provided for freq_table or cont_table, this is a case for mean, median and quantile. When a function exists, but is not generic, we provide a generic and relevant methods using different names (stdev, variance and madev instead respectively of sd, var and mad). Finally some function don't exist in base R and recommended packages, we therefore provide a modval function to compute the mode, gini for the Gini concentration index, skewness and kurtosis for Fisher's shape statistics and gmean for generalized means (which include the geometric, the quadratic and the harmonic means).

madev has a center argument which indicates whether the deviations should be computed respective to the mean or to the median.

gmean has a r argument: values of -1, 0, 1 and 2 lead respectively to the harmonic, geometric, arithmetic and quadratic means.

Value

a numeric or a tibble.

Author(s)

Yves Croissant

Examples

z <- wages |> freq_table(wage)
z |> median()
# the medial is the 0.5 quantile of the mass of the distribution
z |> medial()
# the modval function returns the mode, it is a one line tibble
z |> modval()
z |> quantile(probs = c(0.25, 0.5, 0.75))
# quantiles can compute for the frequency (the default) or the mass
# of the series
z |> quantile(y = "mass", probs = c(0.25, 0.5, 0.75))

DADS survey

Description

The DADS survey (Declaration Annuelle des Données Sociales) provides characteristics of wage earners (wages in class, number of working hours, etc.).

Format

a tibble containing

• sector : activity sector, industry, building, business, services and administration,

• age : the age in years,

• hours : annual number of hours worked,

• sex : sex of the wage earner, male or female,

• wage : class of yearly wages, in thousands of euros,

• size : class of working force size of the firm.

Source

DADS survey 2015, INSEE's website.