Learn R Programming
DiscreteTests (version 0.3.0)

DiscreteTestResults: Discrete Test Results Class

Description

This is the class used by the statistical test functions of this package for returning not only p-values, but also the supports of their distributions and the parameters of the respective tests. Objects of this class are obtained by setting the simple.output parameter of a test function to FALSE (the default). All data members of this class are private to avoid inconsistencies by deliberate or inadvertent changes by the user. However, the results can be read by public methods.

Arguments

Methods

Method new()

Creates a new DiscreteTestResults object.

Usage

DiscreteTestResults$new(
  test_name,
  inputs,
  statistics,
  p_values,
  pvalue_supports,
  support_indices,
  data_name
)

Arguments

test_name

single character string with the name of the test(s).

inputs

named list of exactly four named elements containing the observations, test parameters and hypothesised null values as data frames or lists; the names of these list fields must be observations, parameters, nullvalues and computation. See details for further information about the requirements for these fields.

statistics

data frame containing the tests' statistics; NULL is allowed and recommended, e.g. if the observed values themselves are the statistics.

p_values

numeric vector of the p-values calculated by each hypothesis test.

pvalue_supports

list of unique numeric vectors containing all p-values that are observable under the respective hypothesis; each value of p_values must occur in its respective p-value support.

support_indices

list of numeric vectors containing the test indices that indicates to which individual testing scenario each unique parameter set and each unique support belongs.

data_name

single character string with the name of the variable that contains the observed data.

Details

The fields of the inputs have the following requirements:

$observations

data frame or list of vectors that comprises of the observed data; if it is a matrix, it must be converted to a data frame; must not be NULL, only numerical and character values are allowed.

$nullvalues

data frame that holds the hypothesised values of the tests, e.g. the rate parameters for Poisson tests; must not be NULL, only numerical values are allowed.

$parameters

data frame that may contain additional parameters of each test (e.g. numbers of Bernoulli trials for binomial tests). Only numerical, character or logical values are permitted; NULL is allowed, too, e.g. if there are no additional parameters.

$computation

data frame that consists of details about the p-value computation, e.g. if they were calculated exactly, the used distribution etc. It must include mandatory columns named exact, alternative and distribution. Any additional information may be added, like the marginals for Fisher's exact test etc., but only numerical, character or logical values are allowed.

All data frames must have the same number of rows. Their column names are used by the print() method for producing text output, therefore they should be informative, i.e. short and (if necessary) non-syntactic, like e.g. `number of success`.

The mandatory column exact of the data frame computation must be logical, while the values of alternative must be one of "greater", "less", "two.sided", "minlike", "blaker", "absdist" or "central". The distribution column must hold character strings that identify the distribution under the null hypothesis, e.g. "normal". All the columns of this data frame are used by the print() method, so their names should also be informative and (if necessary) non-syntactic.

Method get_pvalues()

Returns the computed p-values.

Usage

DiscreteTestResults$get_pvalues(named = TRUE)

Arguments

named

single logical value that indicates whether the vector is to be returned as a named vector (if names are present)

Returns

A numeric vector of the p-values of all null hypotheses.

Method get_inputs()

Return the list of the test inputs.

Usage

DiscreteTestResults$get_inputs(unique = FALSE)

Arguments

unique

single logical value that indicates whether only unique combinations of parameter sets and null values are to be returned. If unique = FALSE (the default), the returned data frames may contain duplicate sets.

Returns

A list of four elements. The first one contains a data frame with the observations for each tested null hypothesis, while the second is another data frame with additional parameters (if any, e.g. n in case of a binomial test) that were passed to the respective test's function. The third list field holds the hypothesised null values (e.g. p for binomial tests). The last list element contains computational details, e.g. test alternatives, the used distribution etc. If unique = TRUE, only unique combinations of parameters, null values and computation specifics are returned, but observations remain unchanged (i.e. they are never unique).

Method get_statistics()

Returns the test statistics.

Usage

DiscreteTestResults$get_statistics()

Returns

A numeric data.frame with one column containing the test statistics.

Method get_pvalue_supports()

Returns the p-value supports, i.e. all observable p-values under the respective null hypothesis of each test.

Usage

DiscreteTestResults$get_pvalue_supports(unique = FALSE)

Arguments

unique

single logical value that indicates whether only unique p-value supports are to be returned. If unique = FALSE (the default), the returned supports may be duplicated.

Returns

A list of numeric vectors containing the supports of the p-value null distributions.

Method get_support_indices()

Returns the indices that indicate to which tested null hypothesis each unique support belongs.

Usage

DiscreteTestResults$get_support_indices()

Returns

A list of numeric vectors. Each one contains the indices of the null hypotheses to which the respective support and/or unique parameter set belongs.

Method print()

Prints the computed p-values.

Usage

DiscreteTestResults$print(
  inputs = TRUE,
  pvalue_details = TRUE,
  supports = FALSE,
  test_idx = NULL,
  limit = 10,
  ...
)

Arguments

inputs

single logical value that indicates if the input values (i.e. observations, statistics and parameters) are to be printed; defaults to TRUE.

pvalue_details

single logical value that indicates if details about the p-value computation are to be printed; defaults to TRUE.

supports

single logical value that indicates if the p-value supports are to be printed; defaults to FALSE.

test_idx

integer vector giving the indices of the tests whose results are to be printed; if NULL (the default), results of every test up to the index specified by limit (see below) are printed.

limit

single integer that indicates the maximum number of test results to be printed; if limit = 0, results of every test are printed; ignored if test_idx is not set to NULL

...

further arguments passed to print.default().

Returns

Prints a summary of the tested null hypotheses. The object itself is invisibly returned.

Method clone()

The objects of this class are cloneable with this method.

Usage

DiscreteTestResults$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

Run this code
## one-sided binomial test
#  parameters
x <- 2:4
n <- 5
p <- 0.4
m <- length(x)
#  support (same for all three tests) and p-values
support <- sapply(0:n, function(k) binom.test(k, n, p, "greater")$p.value)
pv <- support[x + 1]
#  DiscreteTestResults object
res <- DiscreteTestResults$new(
  # string with name of the test
  test_name = "Exact binomial test",
  # list of data frames
  inputs = list(
    observations = data.frame(
      `number of successes` = x,
      # no name check of column header to have a speaking name for 'print'
      check.names = FALSE
    ),
    parameters = data.frame(
      # parameter 'n', needs to be replicated to length of 'x'
      `number of trials` = rep(n, m),
      # no name check of column header to have a speaking name for 'print'
      check.names = FALSE
    ),
    nullvalues = data.frame(
      # here: only one null value, 'p'; needs to be replicated to length of 'x'
      `probability of success` = rep(p, m),
      # no name check of column header to have a speaking name for 'print'
      check.names = FALSE
    ),
    computation = data.frame(
      # mandatory parameter 'alternative', needs to be replicated to the length of 'x'
      alternative = rep("greater", m),
      # mandatory exactness information, replicated to the length of 'alternative'
      exact = rep(TRUE, m),
      # mandatory distribution information, replicated to the length of 'alternative'
      distribution = rep("binomial", m)
    )
  ),
  # test statistics (not needed, since observation itself is the statistic)
  statistics = NULL,
  # numerical vector of p-values
  p_values = pv,
  # list of supports (here: only one support); values must be sorted and unique
  pvalue_supports = list(unique(sort(support))),
  # list of indices that indicate which p-value/hypothesis each support belongs to
  support_indices = list(1:m),
  # name of input data variables
  data_name = "x, n and p"
)

#  print results without supports
print(res)
#  print results with supports
print(res, supports = TRUE)

Run the code above in your browser using DataLab