DiscreteTestResults: Discrete Test Results Class

In DiscreteTests: Vectorised Computation of P-Values and Their Supports for Several Discrete Statistical Tests

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.

Methods

Public methods

• DiscreteTestResults$new()

• DiscreteTestResults$get_pvalues()

• DiscreteTestResults$get_inputs()

• DiscreteTestResults$get_pvalue_supports()

• DiscreteTestResults$get_support_indices()

• DiscreteTestResults$print()

• DiscreteTestResults$clone()

---

Method new()

Creates a new DiscreteTestResults object.

Usage

DiscreteTestResults$new(
  test_name,
  inputs,
  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 three elements containing the observations, test parameters and hypothesised null values as data frames; names of these list fields must be observations, nullvalues and parameters. See details for further information about the requirements for these fields.

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 that contains the observed data; if the observed data 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 contains 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 holds the parameter combinations of the null distribution of each test (e.g. numbers of Bernoulli trials for binomial tests, or m, n and k for the hypergeometric distribution used by Fisher's Exact Test, which have to be derived from the observations first); must include a mandatory column named alternative; only numerical and character values are allowed.

Missing values or NULLs are not allowed for any of these fields. 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`.

---

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 three elements. The first one contains a data frame with the observations for each tested null hypothesis, while the second is another data frame with the hypothesised null values (e.g. p for binomial tests). The third list field holds the parameter sets (e.g. n in case of a binomial test). If unique = TRUE, only unique combinations of parameter sets and null values are returned, but observations remain unchanged.

---

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 testing scenario 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,
  pvalues = TRUE,
  supports = FALSE,
  test_idx = NULL,
  limit = 10,
  ...
)

Arguments

inputs

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

pvalues

single logical value that indicates if the resulting p-values 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

## 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),
      # mandatory parameter 'alternative', needs to be replicated to length of 'x'
      alternative = rep("greater", 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
    )
  ),
  # 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)

DiscreteTests documentation built on Oct. 30, 2024, 9:09 a.m.