Package {XOMultinom}

XOMultinom: Exact distributions of ordered multinomial counts

Description

The XOMultinom package provides functions for computing exact distributions of selected functions of ordered multinomial counts, including the maximum, minimum, range, and sums of order statistics.

Main functions include:

• dmaxmultinom(), pmaxmultinom(), qmaxmultinom(), rmaxmultinom()

• dminmultinom(), pminmultinom(), qminmultinom(), rminmultinom()

• drangemultinom(), prangemultinom(), qrangemultinom(), rrangemultinom()

• dJlargemultinom(), pJlargemultinom(), qJlargemultinom(), rJlargemultinom()

Author(s)

Maintainer: Sergio Venturini sergio.venturini@unicatt.it

Authors:

• Sergio Venturini sergio.venturini@unicatt.it

Other contributors:

• Marco Bonetti marco.bonetti@unibocconi.it [contributor]

See Also

Useful links:

• https://github.com/sergioventurini/XOMultinom

• Report bugs at https://github.com/sergioventurini/XOMultinom/issues

Coerce an xomultinom_dist object to a data frame

Description

Converts the evaluation points and probability values stored in an xomultinom_dist object into a tidy data.frame suitable for further manipulation or export.

Usage

## S3 method for class 'xomultinom_dist'
as.data.frame(x, ...)

Arguments

Value

A data.frame with columns x (evaluation points) and either pmf or cdf (probability values). If the object was computed on the log scale the column is named log_pmf or log_cdf accordingly.

Examples

k <- 5; n <- 40
obj <- dmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))
head(as.data.frame(obj))

Coerce an xomultinom_size object to a data frame

Description

Converts the sample size results stored in an xomultinom_size object into a single tidy data.frame with columns for m, the probability perturbation, and the required sample size.

Usage

## S3 method for class 'xomultinom_size'
as.data.frame(x, ...)

Arguments

Value

A data.frame with columns m (integer number of categories), change (probability perturbation), and n_required (required sample size).

Examples

sz <- maxmin_multinom_size(
  m_seq = c(5, 10), change_seq = c(0.10, 0.15, 0.20),
  power = 0.80, alpha = 0.05, type = "max"
)
as.data.frame(sz)

ggplot2-based plot for xomultinom_dist objects

Description

Produces a ggplot2 plot of the exact distribution stored in an xomultinom_dist object. PMFs are displayed as lollipop (spike) charts; CDFs are displayed as step functions. An optional normal approximation overlay can be added for diagnostic comparison.

Usage

## S3 method for class 'xomultinom_dist'
autoplot(
  object,
  add_approx = FALSE,
  colour = "#2166ac",
  approx_colour = "#d6604d",
  title = NULL,
  ...
)

Arguments

Details

For multi-panel layouts use patchwork or gridExtra to combine multiple autoplot() outputs. For base R par(mfrow = ...) compatibility use plot.xomultinom_dist instead.

Value

Invisibly returns the ggplot object.

See Also

plot.xomultinom_dist for a base R alternative compatible with par(mfrow = ...).

Examples

k <- 5; n <- 40
obj <- dmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))
autoplot(obj)
autoplot(obj, add_approx = TRUE)

ggplot2-based plot for xomultinom_size objects

Description

Produces a ggplot2 line chart of the required sample size as a function of the probability perturbation, with one line per value of m (number of categories).

Usage

## S3 method for class 'xomultinom_size'
autoplot(object, log_scale = FALSE, title = NULL, ...)

Arguments

Details

For multi-panel layouts use patchwork or gridExtra to combine multiple autoplot() outputs. For base R par(mfrow = ...) compatibility use plot.xomultinom_size instead.

Value

Invisibly returns the ggplot object.

See Also

plot.xomultinom_size for a base R alternative compatible with par(mfrow = ...).

Examples

sz_max <- maxmin_multinom_size(
  m_seq = c(5, 10, 20), change_seq = seq(0.10, 0.30, by = 0.05),
  power = 0.80, alpha = 0.05, type = "max"
)
autoplot(sz_max)
autoplot(sz_max, log_scale = TRUE)

PMF of the sum of J largest order statistics for a multinomial distribution

Description

Computes the probability mass function of the sum of J largest order statistics for a multinomial random vector with equal cell probabilities.

Usage

dJlargemultinom(x, size, prob, J = 2, log = FALSE, verbose = TRUE)

Arguments

Details

The function only implements the equiprobable case.

Value

An object of class xomultinom_dist with fields x, values (containing P(S_J = x), S_J = \sum_{j=1}^J N_{\langle j\rangle}, or log-probabilities if log = TRUE), stat = "J_largest", type = "pmf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

See Also

dmaxmultinom for the PMF of the maximum, dminmultinom for the PMF of the minimum, and drangemultinom for the PMF of the range.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
J <- 3
xseq <- 0:n

pmflarge <- dJlargemultinom(x = xseq, size = n, prob = probs, J = J)
plot(pmflarge)

Utility function.

Description

This is an auxiliary function to compute the probability values from an decrement with respect to the case of equiprobability.

Usage

decr_2_pmin(m, decr)

Arguments

Value

A numeric matrix.

Author(s)

Sergio Venturini sergio.venturini@unicatt.it

References

Bonetti, M., Cirillo, P., Ogay, A. (2019), "Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics", Royal Society Open Science, 6: 190198, doi:10.1098/rsos.190198.

See Also

pmin_2_decr for the opposite calculation.

Examples

m <- 3:50
decr <- seq(0, 1, 0.01)
pmin <- decr_2_pmin(m, decr)
summary(as.numeric(pmin))

PMF of the maximum for a multinomial distribution

Description

Computes the probability mass function of the maximum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

dmaxmultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(\max(N_1, \ldots, N_m) = x), or log-probabilities if log = TRUE), stat = "max", type = "pmf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pmaxmultinom for the CDF of the maximum, dminmultinom for the PMF of the minimum, and drangemultinom for the PMF of the range.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

pmfmax <- dmaxmultinom(x = xseq, size = n, prob = probs)
plot(pmfmax)

PMF of the minimum for a multinomial distribution

Description

Computes the probability mass function of the minimum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

dminmultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(\min(N_1, \ldots, N_m) = x), or log-probabilities if log = TRUE), stat = "min", type = "pmf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pminmultinom for the CDF of the minimum, dmaxmultinom for the PMF of the maximum, and drangemultinom for the PMF of the range.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

pmfmin <- dminmultinom(x = xseq, size = n, prob = probs)
plot(pmfmin)

PMF of the range for a multinomial distribution

Description

Computes the probability mass function of the range R = \max(N_1, \ldots, N_m) - \min(N_1, \ldots, N_m) for a multinomial random vector with arbitrary cell probabilities.

Usage

drangemultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(R = x), or log-probabilities if log = TRUE), stat = "range", type = "pmf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

prangemultinom for the CDF of the range, dmaxmultinom for the PMF of the maximum, and dminmultinom for the PMF of the minimum.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

pmfrange <- drangemultinom(x = xseq, size = n, prob = probs)
plot(pmfrange)

Randomization probability for max/min multinomial tests

Description

Computes the randomization probability \gamma associated with a critical value k_\alpha for tests based on the maximum or minimum of a multinomial random vector.

Usage

find_gamma_prob(probs, n, alpha = 0.05, k_alpha, type)

Arguments

Value

Numeric value representing the randomization probability. Returns NA if not defined.

Critical value for max/min multinomial tests

Description

Computes the critical value k_\alpha for hypothesis tests based on the maximum or minimum of a multinomial random vector.

Usage

find_k_alpha(probs, n, alpha = 0.05, type)

Arguments

Value

Integer critical value k_\alpha. Returns NA if no valid rejection region exists.

Critical value and randomization probability for max/min tests

Description

Computes the critical value k_\alpha and the corresponding randomization probability \gamma for hypothesis tests based on the maximum or minimum of a multinomial random vector under the null hypothesis of equiprobable categories.

Usage

find_k_gamma(probs, n, alpha = 0.05, type)

Arguments

Details

The function determines the rejection region for tests based on the maximum or minimum cell count. When the test is not exact, a randomized decision rule is constructed via \gamma.

Value

A list with components:

Utility function.

Description

This is an auxiliary function to compute the probability values from an increment with respect to the case of equiprobability.

Usage

incr_2_pmax(m, incr)

Arguments

Value

A numeric matrix.

Author(s)

Sergio Venturini sergio.venturini@unicatt.it

References

Bonetti, M., Cirillo, P., Ogay, A. (2019), "Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics", Royal Society Open Science, 6: 190198, doi:10.1098/rsos.190198.

See Also

pmax_2_incr for the opposite calculation.

Examples

m <- 3:50
incr <- seq(0, 1, 0.01)
pmax <- incr_2_pmax(m, incr)
summary(as.numeric(pmax))

Data: Leukaemia cases

Description

This is a well-known epidemiological dataset of diagnosed leukaemia cases over eight counties in upstate New York. These data originated from the New York State Cancer Registry, and were gathered during the 5-year period 1978-1982, with a total of 584 individuals diagnosed with leukaemia over a population of approximately 1 million people. The original data contain spatial information about registered events split into 790 census tracts.

Usage

data(leukaemia)

Format

A data frame with 790 observations and the following 5 variables:

• ID (int): 10 character long identification number for a cell or census district in the study area

• x (num): x-coordinate of the geographic centroid of each cell

• y (num): y-coordinate of the geographic centroid of each cell

• pop (int): 1980 U.S. Census population count for each cell

• cases (num): incident cases of leukemia (all types) occurring between 1978 and 1982 in each cell; fractional values can occur due to partially missing data

Source

The data set has been downloaded from https://www.stats.ox.ac.uk/pub/datasets/csb/.

References

Lange, N., Ryan, L., Billard, L., Brillinger, D., Conquest, L., Greenhouse, J. (1994), "Case Studies in Biometry", Hoboken, NJ: Wiley & Sons.

MAINSAIL trial: comparator-arm data with Halabi 2014 risk scores

Description

Baseline characteristics and Halabi (2014) prognostic linear predictor for the 520 patients randomised to the comparator arm (docetaxel plus prednisone) of the MAINSAIL trial (NCT00988208), a phase III study in metastatic castration-resistant prostate cancer (mCRPC). The dataset is used in XOMultinom to illustrate the sequential recalibration-alarm procedure described in Section~5.2 of the package paper.

Usage

mainsail

Format

A data frame with 520 rows and 21 variables:

RPT

Character. Zero-padded patient identifier (e.g.\ "00468").

ENROLLDAY

Numeric. Randomisation day on the study-day scale (day 0 = study start). Ranges from -265 to 353; used to derive entry_order.

entry_order

Integer. Patient's rank by ascending ENROLLDAY, from 1 (earliest randomised) to 520 (latest). Ties in ENROLLDAY are broken arbitrarily.

ecog

Numeric. Eastern Cooperative Oncology Group (ECOG) performance status at baseline: 0 (fully active), 1 (restricted in strenuous activity), or 2 (ambulatory, capable of self-care only).

disease_site

Character. Halabi (2014) disease-site classification: "ln_only" (lymph-node involvement only, n = 89) or "visceral" (any liver or lung metastasis, n = 350). NA for 81 patients for whom disease site could not be determined from the available tumour-assessment records; all such patients have has_bone = 0.

has_ln

Integer. Binary indicator: 1 if lymph-node metastases were recorded at the screening visit, 0 otherwise.

has_bone

Integer. Binary indicator: 1 if bone metastases were recorded at the screening visit, 0 otherwise.

has_visceral

Integer. Binary indicator: 1 if visceral (liver or lung) metastases were recorded at the screening visit, 0 otherwise.

opioid

Integer. Binary indicator: 1 if the patient was receiving opioid analgesics (ATC code N02A*) at the time of randomisation, 0 otherwise.

ldh

Numeric. Lactate dehydrogenase (LDH) at baseline, in U/L. Missing for 8 patients.

ldh_uln

Numeric. Upper limit of normal for LDH as recorded in the trial laboratory data. Constant at 250 U/L for all patients in this dataset.

ldh_gt_uln

Integer. Binary indicator: 1 if ldh > ldh_uln, 0 otherwise. Complete for all 520 patients (missing ldh values were treated as not exceeding the ULN).

albumin

Numeric. Serum albumin at baseline, in g/dL. Missing for 5 patients.

hgb

Numeric. Haemoglobin at baseline, in g/dL. Missing for 16 patients.

psa

Numeric. Prostate-specific antigen (PSA) at baseline, in ng/mL. Missing for 6 patients.

alp

Numeric. Alkaline phosphatase (ALP) at baseline, in U/L. Missing for 8 patients.

ln_psa

Numeric. Natural logarithm of psa. Missing for the same 6 patients as psa.

ln_alp

Numeric. Natural logarithm of alp. Missing for the same 8 patients as alp.

halabi2014_lp

Numeric. Halabi (2014) linear predictor computed by strict listwise deletion: NA for any patient missing at least one of the ten model covariates (99 patients). Identical to halabi2014_lp_raw for the 421 complete cases.

halabi2014_lp_raw

Numeric. Halabi (2014) linear predictor computed under partial listwise deletion: available for the 498 patients with complete laboratory values, regardless of disease_site availability. For the 77 patients with missing disease_site but complete labs, both disease-site indicators are set to zero (equivalent to assigning the lymph-node-only reference category). NA for the 22 patients missing at least one laboratory value.

halabi2014_lp_imputed

Numeric. Halabi (2014) linear predictor after single imputation: complete for all 520 patients. Continuous covariates (albumin, hgb, ln_psa, ln_alp) are imputed at their sample median; disease_site is imputed at its sample mode ("visceral"). Used as the risk score in the sequential recalibration-alarm illustration of Section~5.2.

Details

The MAINSAIL trial randomised 1059 patients with chemotherapy-naive mCRPC to docetaxel/prednisone with or without lenalidomide. Only the 520 patients on the comparator arm are included here. Patient entry order was determined by ENROLLDAY extracted from assignmt.sas7bdat in the Project Data Sphere release; all other covariates were extracted at or closest to the baseline visit. Full details of variable construction are given in Appendix~A of the package paper.

The Halabi (2014) linear predictor is defined as

\eta_i = \boldsymbol{\beta}^\top \mathbf{x}_i,

where the regression coefficients \boldsymbol{\beta} are the log-hazard ratios from Table~2 of Halabi et al.\ (2014); see vignette("recalibration", package = "XOMultinom") for the full specification.

Source

Project Data Sphere, dataset identifier Prostat\_Celgene\_2009\_90 (https://data.projectdatasphere.org/). Access requires registration and acceptance of the Project Data Sphere terms of use.

References

Halabi, S., Lin, C.-Y., Kelly, W.K., Fizazi, K.S., Moul, J.W., Kaplan, E.B., Morris, M.J. and Small, E.J. (2014). Updated prognostic model for predicting overall survival in first-line chemotherapy for patients with metastatic castration-resistant prostate cancer. Journal of Clinical Oncology, 32(7), 671–677. doi:10.1200/JCO.2013.52.3696

Fizazi, K., Higano, C.S., Nelson, J.B., et al.\ (2013). Phase III, randomized, placebo-controlled study of docetaxel in combination with zibotentan in patients with metastatic castration-resistant prostate cancer. Journal of Clinical Oncology, 31(14), 1740–1747. doi:10.1200/JCO.2012.46.4149

Sample size determination for multinomial max/min tests

Description

Computes the required sample size to achieve a target power for hypothesis tests based on the maximum or minimum of a multinomial random vector under deviations from equiprobability.

Usage

maxmin_multinom_size(
  m_seq,
  change_seq,
  power = 0.8,
  alpha = 0.05,
  n_max = 500,
  type,
  verbose = TRUE,
  optmethod = "uniroot",
  extendInt = "upX"
)

Arguments

Details

The function evaluates the sample size needed to detect deviations from equiprobability with a given power, using tests based on either the maximum or minimum multinomial cell count.

Value

A list where each element corresponds to a value of m_seq and contains the required sample sizes for each value in change_seq.

Examples

pow <- 0.8
alpha <- 0.05
m_seq <- 3:8
incr_seq <- seq(0.2, 0.8, 0.1)
res <- maxmin_multinom_size(m_seq, incr_seq, power = pow, alpha = alpha,
                            n_max = 200, type = "max",
                            verbose = TRUE, optmethod = "uniroot")
summary(res)
plot(res)

CDF of the sum of J largest order statistics for a multinomial distribution

Description

Computes the cumulative distribution function of the sum of J largest order statistics for a multinomial random vector with equal cell probabilities.

Usage

pJlargemultinom(x, size, prob, J = 2, log = FALSE, verbose = TRUE)

Arguments

Details

The function only implements the equiprobable case.

Value

An object of class xomultinom_dist with fields x, values (containing P(S_J \le x), S_J = \sum_{j=1}^J N_{\langle j\rangle}, or log-probabilities if log = TRUE), stat = "J_largest", type = "cdf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

See Also

dJlargemultinom for the PMF, qJlargemultinom for quantiles, and rJlargemultinom for random generation.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
J <- 3
xseq <- 0:n

cdflarge <- pJlargemultinom(x = xseq, size = n, prob = probs, J = J)
plot(cdflarge)

Plot method for xomultinom_dist objects

Description

Produces a base R plot of the exact distribution stored in an xomultinom_dist object, compatible with par(mfrow = ...), layout(), and all other base R multi-panel layout mechanisms. PMFs are displayed as spike (needle) charts; CDFs are displayed as step functions. An optional normal approximation overlay can be added for diagnostic comparison.

Usage

## S3 method for class 'xomultinom_dist'
plot(
  x,
  add_approx = FALSE,
  col = "#2166ac",
  approx_col = "#d6604d",
  main = NULL,
  xlab = "x",
  ylab = NULL,
  ...
)

Arguments

Value

Invisibly returns NULL.

See Also

autoplot.xomultinom_dist for a ggplot2-based alternative.

Examples

k <- 5; n <- 40
obj_pmf <- dmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))
obj_cdf <- pmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))

# Compatible with par(mfrow = ...)
op <- par(mfrow = c(1, 2))
plot(obj_pmf)
plot(obj_cdf)
par(op)

Plot method for xomultinom_size objects

Description

Produces a base R line chart of the required sample size as a function of the probability perturbation, with one line per value of m (number of categories), compatible with par(mfrow = ...), layout(), and all other base R multi-panel layout mechanisms.

Usage

## S3 method for class 'xomultinom_size'
plot(
  x,
  log_scale = FALSE,
  col = NULL,
  main = NULL,
  xlab = NULL,
  ylab = "Required n",
  ...
)

Arguments

Value

Invisibly returns NULL.

See Also

autoplot.xomultinom_size for a ggplot2-based alternative.

Examples

sz <- maxmin_multinom_size(
  m_seq = c(5, 10, 20), change_seq = seq(0.10, 0.30, by = 0.05),
  power = 0.80, alpha = 0.05, type = "max"
)

# Compatible with par(mfrow = ...)
op <- par(mfrow = c(1, 2))
plot(sz)
plot(sz, log_scale = TRUE)
par(op)

Utility function.

Description

This is an auxiliary function to compute the increment as the distance from the case of equiprobability.

Usage

pmax_2_incr(m, pmax)

Arguments

Value

A numeric matrix.

Author(s)

Sergio Venturini sergio.venturini@unicatt.it

References

Bonetti, M., Cirillo, P., Ogay, A. (2019), "Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics", Royal Society Open Science, 6: 190198, doi:10.1098/rsos.190198.

See Also

incr_2_pmax for the opposite calculation.

Examples

m <- 3:50
pmax <- seq(0.05, 1, 0.05)
incr <- pmax_2_incr(m, pmax)
summary(as.numeric(incr))

CDF of the maximum for a multinomial distribution

Description

Computes the cumulative distribution function of the maximum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

pmaxmultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(\max(N_1, \ldots, N_m) \le x), or log-probabilities if log = TRUE), stat = "max", type = "cdf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pminmultinom for the CDF of the minimum, dmaxmultinom for the PMF of the maximum, and dminmultinom for the PMF of the minimum.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

cdfmax <- pmaxmultinom(x = xseq, size = n, prob = probs)
plot(cdfmax)

Utility function.

Description

This is an auxiliary function to compute the decrement as the distance from the case of equiprobability.

Usage

pmin_2_decr(m, pmin)

Arguments

Value

A numeric matrix.

Author(s)

Sergio Venturini sergio.venturini@unicatt.it

References

Bonetti, M., Cirillo, P., Ogay, A. (2019), "Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics", Royal Society Open Science, 6: 190198, doi:10.1098/rsos.190198.

See Also

decr_2_pmin for the opposite calculation.

Examples

m <- 3:50
pmin <- seq(0.05, 1, 0.05)
decr <- pmin_2_decr(m, pmin)
summary(as.numeric(decr))

CDF of the minimum for a multinomial distribution

Description

Computes the cumulative distribution function of the minimum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

pminmultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(\min(N_1, \ldots, N_m) \le x), or log-probabilities if log = TRUE), stat = "min", type = "cdf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pmaxmultinom for the CDF of the maximum, dminmultinom for the PMF of the minimum, and drangemultinom for the PMF of the range.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

cdfmin <- pminmultinom(x = xseq, size = n, prob = probs)
plot(cdfmin)

CDF of the range for a multinomial distribution

Description

Computes the cumulative distribution function of the range R = \max(N_1, \ldots, N_m) - \min(N_1, \ldots, N_m) for a multinomial random vector with arbitrary cell probabilities.

Usage

prangemultinom(x, size, prob, log = FALSE, verbose = TRUE)

Arguments

Details

The function first checks whether prob corresponds to the equiprobable case and then applies either the Bonetti et al. (2019) algorithm or the Corrado (2011) algorithm accordingly.

Value

An object of class xomultinom_dist with fields x, values (containing P(R \le x), or log-probabilities if log = TRUE), stat = "range", type = "cdf", size, prob, and log.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

drangemultinom for the PMF of the range, pmaxmultinom for the CDF of the maximum, and pminmultinom for the CDF of the minimum.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)
xseq <- 0:n

cdfrange <- prangemultinom(x = xseq, size = n, prob = probs)
plot(cdfrange)

Print method for xomultinom_dist objects

Description

Displays a compact, human-readable table of evaluation points and the corresponding exact probabilities (or log-probabilities) stored in an xomultinom_dist object.

Usage

## S3 method for class 'xomultinom_dist'
print(x, digits = 4, max_rows = 20, ...)

Arguments

Value

Invisibly returns x.

Examples

k <- 5; n <- 40
obj <- dmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))
print(obj)

Print method for xomultinom_size objects

Description

Displays the required sample sizes as a formatted table, one block per number of categories m.

Usage

## S3 method for class 'xomultinom_size'
print(x, digits = 4, ...)

Arguments

Value

Invisibly returns x.

Examples

sz <- maxmin_multinom_size(
  m_seq = c(5, 10), change_seq = c(0.10, 0.15, 0.20),
  power = 0.80, alpha = 0.05, type = "max"
)
print(sz)

Quantile function of the sum of J largest order statistics for a multinomial distribution

Description

Computes exact quantiles of the distribution of the sum of the J largest order statistics S_J = \sum_{j=1}^{J} N_{\langle j \rangle} of a multinomial random vector with equal cell probabilities, by inverting the exact CDF obtained from pJlargemultinom.

Usage

qJlargemultinom(p, size, prob, J = 2, lower.tail = TRUE, log.p = FALSE)

Arguments

Details

The function obtains the exact CDF over the full support \{0, 1, \ldots, n\} via a single vectorised call to pJlargemultinom. The quantile is then located as the smallest support point whose CDF value meets or exceeds p. Only the equiprobable case is supported, consistent with pJlargemultinom.

Value

Integer vector of the same length as p containing the corresponding exact quantiles of S_J.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

See Also

pJlargemultinom for the CDF, dJlargemultinom for the PMF, rJlargemultinom for random generation.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)

# Median and 95th percentile of S_3
qJlargemultinom(c(0.5, 0.95), size = n, prob = probs, J = 3)

# Upper tail
qJlargemultinom(0.05, size = n, prob = probs, J = 3, lower.tail = FALSE)

Quantile function of the maximum for a multinomial distribution

Description

Computes exact quantiles of the distribution of the maximum cell count of a multinomial random vector with arbitrary cell probabilities, by inverting the exact CDF obtained from pmaxmultinom.

Usage

qmaxmultinom(p, size, prob, lower.tail = TRUE, log.p = FALSE)

Arguments

Details

The function obtains the exact CDF over the full support \{0, 1, \ldots, n\} via a single vectorised call to pmaxmultinom, which dispatches internally to the Bonetti et al. (2019) algorithm for equiprobable prob and to the Corrado (2011) algorithm otherwise. The quantile is then located as the smallest support point whose CDF value meets or exceeds p, an O(n) lookup requiring no root-finding or approximation.

Value

Integer vector of the same length as p containing the corresponding exact quantiles of the multinomial maximum.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pmaxmultinom for the CDF, dmaxmultinom for the PMF, rmaxmultinom for random generation.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)

# Median and 95th percentile
qmaxmultinom(c(0.5, 0.95), size = n, prob = probs)

# Upper tail
qmaxmultinom(0.05, size = n, prob = probs, lower.tail = FALSE)

Quantile function of the minimum for a multinomial distribution

Description

Computes exact quantiles of the distribution of the minimum cell count of a multinomial random vector with arbitrary cell probabilities, by inverting the exact CDF obtained from pminmultinom.

Usage

qminmultinom(p, size, prob, lower.tail = TRUE, log.p = FALSE)

Arguments

Details

The function obtains the exact CDF over the full support \{0, 1, \ldots, n\} via a single vectorised call to pminmultinom, which dispatches internally to the Bonetti et al. (2019) algorithm for equiprobable prob and to the Corrado (2011) algorithm otherwise. The quantile is then located as the smallest support point whose CDF value meets or exceeds p, an O(n) lookup requiring no root-finding or approximation.

Value

Integer vector of the same length as p containing the corresponding exact quantiles of the multinomial minimum.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

pminmultinom for the CDF, dminmultinom for the PMF, rminmultinom for random generation.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)

# Median and 95th percentile
qminmultinom(c(0.5, 0.95), size = n, prob = probs)

# Upper tail
qminmultinom(0.05, size = n, prob = probs, lower.tail = FALSE)

Quantile function of the range for a multinomial distribution

Description

Computes exact quantiles of the distribution of the range R = \max(N_1, \ldots, N_m) - \min(N_1, \ldots, N_m) of a multinomial random vector with arbitrary cell probabilities, by inverting the exact CDF obtained from prangemultinom.

Usage

qrangemultinom(p, size, prob, lower.tail = TRUE, log.p = FALSE)

Arguments

Details

The function obtains the exact CDF over the full support \{0, 1, \ldots, n\} via a single vectorised call to prangemultinom, which dispatches internally to the Bonetti et al. (2019) algorithm for equiprobable prob and to the Corrado (2011) algorithm otherwise. The quantile is then located as the smallest support point whose CDF value meets or exceeds p, an O(n) lookup requiring no root-finding or approximation.

Value

Integer vector of the same length as p containing the corresponding exact quantiles of the multinomial range.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

prangemultinom for the CDF, drangemultinom for the PMF, rrangemultinom for random generation.

Examples

m <- 4
n <- 60
probs <- rep(1 / m, m)

# Median and 95th percentile
qrangemultinom(c(0.5, 0.95), size = n, prob = probs)

# Upper tail
qrangemultinom(0.05, size = n, prob = probs, lower.tail = FALSE)

Random generation from the distribution of the sum of J largest order statistics for a multinomial distribution

Description

Draws independent random samples from the exact distribution of S_J = \sum_{j=1}^{J} N_{\langle j \rangle} for a multinomial random vector with equal cell probabilities.

Usage

rJlargemultinom(n, size, prob, J = 2)

Arguments

Details

The exact PMF over the support \{0, 1, \ldots, \mathtt{size}\} is computed once using dJlargemultinom, and n independent draws are then obtained via sample with those probabilities as weights. Only the equiprobable case is supported, consistent with dJlargemultinom.

Value

Integer vector of length n containing independent draws from the distribution of S_J.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

See Also

dJlargemultinom for the PMF, pJlargemultinom for the CDF, qJlargemultinom for quantiles.

Examples

m <- 4; n <- 60
probs <- rep(1 / m, m)

set.seed(42)
sims <- rJlargemultinom(n = 1000, size = n, prob = probs, J = 3)
hist(sims, breaks = 20, main = "Simulated sums of 3 largest order statistics")

Random generation from a Dirichlet distribution

Description

Generates random samples from a Dirichlet distribution using gamma variates.

Usage

rdirichlet(n, alpha)

Arguments

Details

Each sample is obtained by drawing independent gamma random variables and normalizing them to sum to one. If alpha is a vector, it is recycled across rows.

Value

A numeric matrix with n rows, where each row is a sample from the Dirichlet distribution and sums to 1.

Examples

rdirichlet(5, c(1, 1, 1))
rdirichlet(3, c(2, 5, 3))

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggplot2

autoplot()

Random generation from the distribution of the multinomial maximum

Description

Draws independent random samples from the exact distribution of the maximum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

rmaxmultinom(n, size, prob)

Arguments

Details

The exact PMF over the support \{0, 1, \ldots, \mathtt{size}\} is computed once using dmaxmultinom, and n independent draws are then obtained via sample with those probabilities as weights. The cost is therefore dominated by the single PMF evaluation and is independent of n.

Value

Integer vector of length n containing independent draws from the distribution of \max(N_1, \ldots, N_m).

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

dmaxmultinom for the PMF, pmaxmultinom for the CDF, qmaxmultinom for quantiles.

Examples

m <- 4; n <- 60
probs <- rep(1 / m, m)

set.seed(42)
sims <- rmaxmultinom(n = 1000, size = n, prob = probs)
hist(sims, breaks = 20, main = "Simulated multinomial maxima")

# Check against exact mean
mean(sims)
summary(dmaxmultinom(x = 0:n, size = n, prob = probs))$mean

Random generation from the distribution of the multinomial minimum

Description

Draws independent random samples from the exact distribution of the minimum cell count of a multinomial random vector with arbitrary cell probabilities.

Usage

rminmultinom(n, size, prob)

Arguments

Details

The exact PMF over the support \{0, 1, \ldots, \mathtt{size}\} is computed once using dminmultinom, and n independent draws are then obtained via sample with those probabilities as weights. The cost is therefore dominated by the single PMF evaluation and is independent of n.

Value

Integer vector of length n containing independent draws from the distribution of \min(N_1, \ldots, N_m).

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

dminmultinom for the PMF, pminmultinom for the CDF, qminmultinom for quantiles.

Examples

m <- 4; n <- 60
probs <- rep(1 / m, m)

set.seed(42)
sims <- rminmultinom(n = 1000, size = n, prob = probs)
hist(sims, breaks = 20, main = "Simulated multinomial minima")

Stable rounding function

Description

Rounds numeric values while avoiding floating-point artifacts by applying a small offset before rounding.

Usage

round_exact(x, digits = 0)

Arguments

Details

A small perturbation proportional to the sign of x is added before rounding to mitigate issues due to floating-point representation.

Value

Numeric vector of rounded values.

Examples

round_exact(0.145, 2)
round_exact(c(1.005, -1.005), 2)

Random generation from the distribution of the multinomial range

Description

Draws independent random samples from the exact distribution of the range R = \max(N_1, \ldots, N_m) - \min(N_1, \ldots, N_m) of a multinomial random vector with arbitrary cell probabilities.

Usage

rrangemultinom(n, size, prob)

Arguments

Details

The exact PMF over the support \{0, 1, \ldots, \mathtt{size}\} is computed once using drangemultinom, and n independent draws are then obtained via sample with those probabilities as weights. The cost is therefore dominated by the single PMF evaluation and is independent of n.

Value

Integer vector of length n containing independent draws from the distribution of R.

References

Bonetti, M., Cirillo, P., Ogay, A. (2019). Computing the exact distributions of some functions of the ordered multinomial counts: maximum, minimum, range and sums of order statistics. Royal Society Open Science, 6, 190198. doi:10.1098/rsos.190198

Corrado, C.J. (2011). The exact distribution of the maximum, minimum and the range of Multinomial/Dirichlet and Multivariate Hypergeometric frequencies. Statistical Computing, 21, 349–359. doi:10.1007/s11222-010-9174-3

See Also

drangemultinom for the PMF, prangemultinom for the CDF, qrangemultinom for quantiles.

Examples

m <- 4; n <- 60
probs <- rep(1 / m, m)

set.seed(42)
sims <- rrangemultinom(n = 1000, size = n, prob = probs)
hist(sims, breaks = 20, main = "Simulated multinomial ranges")

Summary method for xomultinom_dist objects

Description

Computes and displays descriptive statistics of the exact distribution stored in an xomultinom_dist object, including the mean, median, mode, standard deviation, effective support, and a central 95\ interval.

Usage

## S3 method for class 'xomultinom_dist'
summary(object, digits = 4, ...)

Arguments

Value

Invisibly returns a named list with components mean, median, mode, sd, var, support, q025, and q975.

Examples

k <- 5; n <- 40
obj <- pmaxmultinom(x = 0:n, size = n, prob = rep(1/k, k))
summary(obj)

Summary method for xomultinom_size objects

Description

Prints a condensed overview of the required sample sizes across all combinations of m and probability perturbations, reporting the range of n for each m.

Usage

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

Arguments

Value

Invisibly returns a named list where each element corresponds to a value of m and contains n_min, n_max, and n_median.

Examples

sz <- maxmin_multinom_size(
  m_seq = c(5, 10), change_seq = c(0.10, 0.15, 0.20),
  power = 0.80, alpha = 0.05, type = "max"
)
summary(sz)