R6 Class representing a plausibility function

A plausibility function is...

Public fields

nparams

An integer specifying the number of parameters to be inferred. Default is 1L.

nperms

An integer specifying the number of permutations to be sampled. Default is 1000L.

nperms_max

An integer specifying the total number of distinct permutations that can be made given the sample sizes.

alternative

A string specifying the type of alternative hypothesis. Choices are "two_tail", "left_tail" and "right_tail. Defaults to "two_tail".

aggregator

A string specifying which function should be used to aggregate test statistic values when non-parametric combination is used (i.e. when multiple test statistics are used). Choices are "tippett" and "fisher for now. Defaults to "tippett".

pvalue_formula

A string specifying which formula to use for computing the permutation p-value. Choices are either probability (default) or estimator. The former provides p-values that lead to exact hypothesis tests while the latter provides an unbiased estimate of the traditional p-value.

max_conf_level

A numeric value specifying the maximum confidence level that we aim to achieve for the confidence regions. This is used to compute bounds on each parameter of interest in order to fit a Kriging model that approximates the expensive plausibility function on a hypercube. Defaults to 0.99.

point_estimate

A numeric vector providing point estimates for the parameters of interest.

parameters

A list of functions of class param produced via new_quant_param that stores the parameters to be inferred along with important properties such as their name, range, etc. Defaults to NULL.

grid

A tibble storing evaluations of the plausibility function on a regular centered grid of the parameter space. Defaults to NULL.

Methods

Public methods

• PlausibilityFunction$new()

• PlausibilityFunction$set_nperms()

• PlausibilityFunction$set_nperms_max()

• PlausibilityFunction$set_alternative()

• PlausibilityFunction$set_aggregator()

• PlausibilityFunction$set_pvalue_formula()

• PlausibilityFunction$get_value()

• PlausibilityFunction$set_max_conf_level()

• PlausibilityFunction$set_point_estimate()

• PlausibilityFunction$set_parameter_bounds()

• PlausibilityFunction$set_grid()

• PlausibilityFunction$evaluate_grid()

• PlausibilityFunction$clone()

---

Method new()

Create a new plausibility function object.

Usage

PlausibilityFunction$new(
  null_spec,
  stat_functions,
  stat_assignments,
  ...,
  seed = NULL
)

Arguments

null_spec

A function or an R object coercible into a function (via rlang::as_function()). For one-sample problems, it should transform the x sample (provided as first argument) using the parameters (as second argument) to make its distribution centered symmetric. For two-sample problems, it should transform the y sample (provided as first argument) using the parameters (as second argument) to make it exchangeable with the x sample under a null hypothesis.

stat_functions

A vector or list of functions (or R objects coercible into functions via rlang::as_function()) specifying the whole set of test statistics that should be used.

stat_assignments

A named list of integer vectors specifying which test statistic should be associated with each parameter. The length of this list should match the number of parameters under investigation and is thus used to set it. Each element of the list should be named after the parameter it identifies.

...

Vectors, matrices or lists providing the observed samples.

seed

A numeric value specifying the seed to be used. Defaults to NULL in which case seed = 1234 is used and the user is informed of this setting.

Returns

A new PlausibilityFunction object.

---

Method set_nperms()

Change the value of the nperms field.

Usage

PlausibilityFunction$set_nperms(val)

Arguments

val

New value for the number of permutations to be sampled.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$nperms
pf$set_nperms(10000)
pf$nperms

---

Method set_nperms_max()

Change the value of the nperms_max field.

Usage

PlausibilityFunction$set_nperms_max(val)

Arguments

val

New value for the total number of of possible distinct permutations.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$nperms_max
pf$set_nperms_max(10000)
pf$nperms_max

---

Method set_alternative()

Change the value of the alternative field.

Usage

PlausibilityFunction$set_alternative(val)

Arguments

val

New value for the type of alternative hypothesis.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$alternative
pf$set_alternative("right_tail")
pf$alternative

---

Method set_aggregator()

Change the value of the aggregator field.

Usage

PlausibilityFunction$set_aggregator(val)

Arguments

val

New value for the string specifying which function should be used to aggregate test statistic values when non-parametric combination is used (i.e. when multiple test statistics are used).

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$aggregator
pf$set_aggregator("fisher")
pf$aggregator

---

Method set_pvalue_formula()

Change the value of the pvalue_formula field.

Usage

PlausibilityFunction$set_pvalue_formula(val)

Arguments

val

New value for the string specifying which formula should be used to compute the permutation p-value.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$pvalue_formula
pf$set_pvalue_formula("estimate")
pf$pvalue_formula

---

Method get_value()

Computes an indicator of the plausibility of specific values for the parameters of interest in the form of a p-value of an hypothesis test against these values.

Usage

PlausibilityFunction$get_value(
  parameters,
  keep_null_distribution = FALSE,
  keep_permutations = FALSE,
  ...
)

Arguments

parameters

A vector whose length should match the nparams field providing specific values of the parameters of interest for assessment of their plausibility in the form of a p-value of the corresponding hypothesis test.

keep_null_distribution

A boolean specifying whether the empirical permutation null distribution should be returned as well. Defaults to FALSE.

keep_permutations

A boolean specifying whether the list of sampled permutations used to compute the empirical permutation null distribution should be returned as well. Defaults to FALSE.

...

Extra parameters specific to some statistics.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$set_nperms(50)
pf$get_value(2)

---

Method set_max_conf_level()

Change the value of the max_conf_level field.

Usage

PlausibilityFunction$set_max_conf_level(val)

Arguments

val

New value for the maximum confidence level that we aim to achieve for the confidence regions.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$max_conf_level
pf$set_max_conf_level(0.999)
pf$max_conf_level

---

Method set_point_estimate()

Change the value of the point_estimate field.

Usage

PlausibilityFunction$set_point_estimate(
  point_estimate = NULL,
  lower_bound = -10,
  upper_bound = 10,
  ncores = 1L,
  estimate = FALSE,
  overwrite = FALSE
)

Arguments

point_estimate

A numeric vector providing rough point estimates for the parameters under investigation.

lower_bound

A scalar or numeric vector specifying the lower bounds for each parameter under investigation. If it is a scalar, the value is used as lower bound for all parameters. Defaults to -10.

upper_bound

A scalar or numeric vector specifying the lower bounds for each parameter under investigation. If it is a scalar, the value is used as lower bound for all parameters. Defaults to 10.

ncores

An integer specifying the number of cores to use for maximizing the plausibility function to get a point estimate of the parameters. Defaults to 1L.

estimate

A boolean specifying whether the rough point estimate provided by val should serve as initial point for maximizing the plausibility function (estimate = TRUE) or as final point estimate for the parameters (estimate = FALSE). Defaults to FALSE.

overwrite

A boolean specifying whether to force the computation if it has already been set. Defaults to FALSE.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$point_estimate
pf$set_point_estimate(mean(y) - mean(x))
pf$point_estimate

---

Method set_parameter_bounds()

Change the value of the parameters field.

Updates the range of the parameters under investigation.

Usage

PlausibilityFunction$set_parameter_bounds(point_estimate, conf_level)

Arguments

point_estimate

A numeric vector providing a point estimate for each parameter under investigation. If no estimator is known by the user, (s)he can resort to the $set_point_estimate() method to get a point estimate by maximizing the plausibility function.

conf_level

A numeric value specifying the confidence level to be used for setting parameter bounds. It should be in (0,1).

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$set_nperms(50)
pf$set_point_estimate(point_estimate = mean(y) - mean(x))
pf$parameters
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
pf$parameters

---

Method set_grid()

Computes a tibble storing a regular centered grid of the parameter space.

Usage

PlausibilityFunction$set_grid(parameters, npoints = 20L)

Arguments

parameters

A list of new_quant_param objects containing information about the parameters under investigation. It should contain the fields point_estimate and range.

npoints

An integer specifying the number of points to discretize each dimension. Defaults to 20L.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$set_nperms(50)
pf$set_point_estimate(mean(y) - mean(x))
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
pf$set_grid(
  parameters = pf$parameters,
  npoints = 2L
)

---

Method evaluate_grid()

Updates the grid field with a pvalue column storing evaluations of the plausibility function on the regular centered grid of the parameter space.

Usage

PlausibilityFunction$evaluate_grid(grid, ncores = 1L)

Arguments

grid

A tibble storing a grid that spans the space of parameters under investigation.

ncores

An integer specifying the number of cores to run evaluations in parallel. Defaults to 1L.

Examples

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
pf$set_nperms(50)
pf$set_point_estimate(mean(y) - mean(x))
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
pf$set_grid(
  parameters = pf$parameters,
  npoints = 2L
)
pf$evaluate_grid(grid = pf$grid)

---

Method clone()

The objects of this class are cloneable with this method.

Usage

PlausibilityFunction$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

## ------------------------------------------------
## Method `PlausibilityFunction$set_nperms`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$nperms
#> [1] 1000
pf$set_nperms(10000)
pf$nperms
#> [1] 10000

## ------------------------------------------------
## Method `PlausibilityFunction$set_nperms_max`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$nperms_max
#> NULL
pf$set_nperms_max(10000)
pf$nperms_max
#> [1] 10000

## ------------------------------------------------
## Method `PlausibilityFunction$set_alternative`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$alternative
#> [1] "two_tail"
pf$set_alternative("right_tail")
pf$alternative
#> [1] "right_tail"

## ------------------------------------------------
## Method `PlausibilityFunction$set_aggregator`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$aggregator
#> [1] "tippett"
pf$set_aggregator("fisher")
pf$aggregator
#> [1] "fisher"

## ------------------------------------------------
## Method `PlausibilityFunction$set_pvalue_formula`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$pvalue_formula
#> [1] "exact"
pf$set_pvalue_formula("estimate")
pf$pvalue_formula
#> [1] "estimate"

## ------------------------------------------------
## Method `PlausibilityFunction$get_value`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {purrr::map(y, ~ .x - parameters[1])}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$set_nperms(50)
pf$get_value(2)
#> [1] 0.3137228

## ------------------------------------------------
## Method `PlausibilityFunction$set_max_conf_level`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$max_conf_level
#> [1] 0.99
pf$set_max_conf_level(0.999)
pf$max_conf_level
#> [1] 0.999

## ------------------------------------------------
## Method `PlausibilityFunction$set_point_estimate`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$point_estimate
#> mean 
#>   NA 
pf$set_point_estimate(mean(y) - mean(x))
#> ! The input point estimate vector is not named. The names provided via the `stat_assignments` list will be used instead.
pf$point_estimate
#>      mean 
#> 0.9466384 

## ------------------------------------------------
## Method `PlausibilityFunction$set_parameter_bounds`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$set_nperms(50)
pf$set_point_estimate(point_estimate = mean(y) - mean(x))
#> ! The input point estimate vector is not named. The names provided via the `stat_assignments` list will be used instead.
pf$parameters
#> $mean
#> Mean (quantitative)
#> Range: [?, ?]
#> Point estimate: 2.39
#> 
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
#> ℹ Setting new maximum confidence level in field `$max_conf_level`.
#> ℹ Computing a confidence interval with confidence level 0.8 for parameter mean...
pf$parameters
#> $mean
#> Mean (quantitative)
#> Range: [1.61, 2.96]
#> Point estimate: 2.39
#> 

## ------------------------------------------------
## Method `PlausibilityFunction$set_grid`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$set_nperms(50)
pf$set_point_estimate(mean(y) - mean(x))
#> ! The input point estimate vector is not named. The names provided via the `stat_assignments` list will be used instead.
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
#> ℹ Setting new maximum confidence level in field `$max_conf_level`.
#> ℹ Computing a confidence interval with confidence level 0.8 for parameter mean...
pf$set_grid(
  parameters = pf$parameters,
  npoints = 2L
)
#> ℹ Setting new grid size in field `$npoints`.

## ------------------------------------------------
## Method `PlausibilityFunction$evaluate_grid`
## ------------------------------------------------

x <- rnorm(10)
y <- rnorm(10, mean = 2)
null_spec <- function(y, parameters) {
  purrr::map(y, ~ .x - parameters[1])
}
stat_functions <- list(stat_t)
stat_assignments <- list(mean = 1)
pf <- PlausibilityFunction$new(
  null_spec = null_spec,
  stat_functions = stat_functions,
  stat_assignments = stat_assignments,
  x, y
)
#> ! Setting the seed for sampling permutations is mandatory for obtaining a continuous p-value function. Using `seed = 1234`.
pf$set_nperms(50)
pf$set_point_estimate(mean(y) - mean(x))
#> ! The input point estimate vector is not named. The names provided via the `stat_assignments` list will be used instead.
pf$set_parameter_bounds(
  point_estimate = pf$point_estimate,
  conf_level = 0.8
)
#> ℹ Setting new maximum confidence level in field `$max_conf_level`.
#> ℹ Computing a confidence interval with confidence level 0.8 for parameter mean...
pf$set_grid(
  parameters = pf$parameters,
  npoints = 2L
)
#> ℹ Setting new grid size in field `$npoints`.
pf$evaluate_grid(grid = pf$grid)