Package 'multiCA'

Multinomial Cochran-Armitage Trend Test

Description

Implements a generalization of the Cochran-Armitage trend test to multinomial data. In addition to an overall test, multiple testing adjusted p-values for trend in individual outcomes and power calculation is available.

Details

The DESCRIPTION file:

Package:	multiCA
Type:	Package
Title:	Multinomial Cochran-Armitage Trend Test
Version:	1.1
Date:	2017-08-07
Author:	Aniko Szabo
Depends:	R(>= 2.10)
Imports:	bitops, multcomp
Maintainer:	Aniko Szabo <[email protected]>
Description:	Implements a generalization of the Cochran-Armitage trend test to multinomial data. In addition to an overall test, multiple testing adjusted p-values for trend in individual outcomes and power calculation is available.
License:	GPL (>=2)
RoxygenNote:	7.1.1
Suggests:	testthat
URL:	https://github.com/anikoszabo/multiCA
BugReports:	https://github.com/anikoszabo/multiCA/issues
Repository:	https://anikoszabo.r-universe.dev
RemoteUrl:	https://github.com/anikoszabo/multica
RemoteRef:	HEAD
RemoteSha:	6490c97eb817eae2712e1cd7cfaf79950f6ee9d4

Index of help topics:

cnonct                  Non-centrality parameter for chi-square
                        distribution
multiCA-package         Multinomial Cochran-Armitage Trend Test
multiCA.test            Multinomial Cochran-Armitage trend test
power.multiCA.test      Power calculations for the multinomial
                        Cochran-Armitage trend test
stroke                  Stroke types over time

The main functionality is implemented in the multiCA.test function. The power.multiCA.test function can be used for power and sample size calculation.

Author(s)

Aniko Szabo

Maintainer: Aniko Szabo <[email protected]>

References

Szabo, A. (2016) Test for trend with a multinomial outcome.

---

Non-centrality parameter for chi-square distribution

Description

Calculates the non-centrality parameter for a chi-square distribution for a given quantile. This is often needed for sample size calculation for chi-square based tests.

Usage

cnonct(x, p, df)

Arguments

x	a numeric value at which the distribution was evaluated
p	a numeric value giving the cumulative probability at x
df	an integer giving the degrees of freedom of the chi-square variable

Details

The function is modeled after the SAS function CNONCT. If p is larger than the cumulative probability of the central chi-square distribution at x, then there is no solution and NA is returned.

Examples

(ncp <- cnonct(qchisq(0.95, df=10), 0.8, df=10))
## check
pchisq(qchisq(0.95, df=10), df=10, ncp=ncp)  ## 0.8

---

Multinomial Cochran-Armitage trend test

Description

The multiCA.test function performs a multinomial generalization of the Cochran-Armitage trend test.

Usage

multiCA.test(x, ...)

## Default S3 method:
multiCA.test(
  x,
  scores = 1:ncol(x),
  outcomes = 1:nrow(x),
  p.adjust.method = c("none", "closed.set", "Holm-Shaffer", "single-step", "Westfall"),
  ...
)

## S3 method for class 'formula'
multiCA.test(formula, data, subset, na.action, weights, ...)

Arguments

x	a two-dimensional matrix of event counts with the outcomes as rows and ordered groups as columns.
...	other arguments
scores	non-decreaseing numeric vector of the same length as the number of ordered groups. Defaults to linearly increasing values
outcomes	integer or character vector defining the set of outcomes (by row index or row name) over which the trend should be tested. Defaults to all outcomes.
p.adjust.method	character string defining the correction method for individual outcome p-values. Defaults to "closed.set" when length(outcomes)<=3, and "Holm-Shaffer" otherwise.
formula	a formula of the form outcome ~ group where outcome is a factor representing the cateogrical outcome and group is the grouping variable over which the trend is tested.
data	an optional matrix or data frame containing the variables in the formula formula. By default the variables are taken from environment(formula).
subset	an optional vector specifying a subset of observations to be used.
na.action	a function which indicates what should happen when the data contain NAs. Defaults to getOption("na.action").
weights	an integer-valued variable representing the number of times each outcome - group combination was observed.

Value

a list with two components

overall	an object of class "htest" with the results of the overall test
individual	a vector with adjusted p-values for individual outcomes

Author(s)

Aniko Szabo

References

Szabo, A. (2016) Test for trend with a multinomial outcome.

Examples

data(stroke)
## using formula interface
multiCA.test(Type ~ Year, weights=Freq, data=stroke)

##using Westfall's multiple testing adjustment
multiCA.test(Type ~ Year, weights=Freq, data=stroke, p.adjust.method="Westfall")

## using matrix interface and testing only the first 3 outcomes
strk.mat <- xtabs(Freq ~ Type + Year, data=stroke)
multiCA.test(strk.mat, outcomes=1:3)

---

Power calculations for the multinomial Cochran-Armitage trend test

Description

Given the probabilities of outcomes, compute the power of the overall multinomial Cochran-Armitage trend test or determine the sample size to obtain a target power.

Usage

power.multiCA.test(
  N = NULL,
  power = NULL,
  pmatrix = NULL,
  p.ave = NULL,
  p.start = NULL,
  p.end = NULL,
  slopes = NULL,
  scores = 1:G,
  n.prop = rep(1, G),
  G = length(p.ave),
  sig.level = 0.05
)

Arguments

N	integer, the total sample size of the study. If NULL then power needs to be specified.
power	target power. If NULL then N needs to be specified.
pmatrix	numeric matrix of hypothesized outcome probabilities in each group, with the outcomes as rows and ordered groups as columns. The columns should add up to 1.
p.ave	numeric vector of average probability of each outcome over the groups weighted by n.prop.
p.start, p.end	numeric vectors of the probability of each outcome for the first / last ordered group
slopes	numeric vector of the hypothesized slope of each outcome when regressed against the column scores with weights n.prop
scores	non-decreasing numeric vector of the same length as the number of ordered groups giving the trend test scores. Defaults to linearly increasing values.
n.prop	numeric vector describing relative sample sizes of the ordered groups. Will be normalized to sum to 1. Defaults to equal sample sizes.
G	integer, number of ordered groups
sig.level	significance level

Details

The distribution of the outcomes can be specified in two ways:

1. the full matrix of outcome probabilities pmatrix can be specified, or

2. exactly two of the parameters p.ave, slopes, p.start, and p.end can be specified. In this case the full matrix of outcome probabilites will be inferred assuming linearity within each outcome.

Value

object of class "power.htest"

Examples

power.multiCA.test(power=0.8, p.start=c(0.1,0.2,0.3,0.4), p.end=c(0.4, 0.3, 0.2, 0.1), 
                     G=5, n.prop=c(3,2,1,2,3))

## Power of stroke study with 100 subjects per year and observed trends
data(stroke)
strk.mat <- xtabs(Freq ~ Type + Year, data=stroke)
power.multiCA.test(N=900, pmatrix=prop.table(strk.mat, margin=2))

---

Stroke types over time

Description

Nakajima et al. (2014) collected information on stroke patients over a 9-year period. For each patient, the type of stroke was classified into one of 5 categories by etiology.

Usage

data("stroke")

Format

A data frame with 45 observations on the following 3 variables.

Type

a factor with levels Small vessel occlusion, Large artery atherosclerosis, Cardioembolism, Other determined aetiology, and Undetermined aetiology giving the etiology of the stroke

Year

a numeric vector with the year of the observation

Freq

a numeric vector with the number of patients with a stroke of the given etiology that year

Source

Nakajima, M., Y. Inatomi, T. Yonehara, Y. Hashimoto, T. Hirano, and Y. Ando (2014). Temporal trends in oral intake ability 3 months after acute ischaemic stroke: analysis of a single-centre database from 2003 to 2011. J Rehabil Med 46 (3), 200–205.

Examples

data(stroke)
xtabs(Freq ~ Type + Year, data=stroke)

strk.props <- prop.table(xtabs(Freq ~ Year+Type, data=stroke), margin=1)
matplot(strk.props, type="l")

---