ContingencyTests            package:coin            R Documentation

_I_n_d_e_p_e_n_d_e_n_c_e _i_n _T_h_r_e_e-_W_a_y _C_o_n_t_i_n_g_e_n_c_y _T_a_b_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Testing the independence of two possibly ordered factors,
     eventually stratified by a third factor.

_U_s_a_g_e:

     ## S3 method for class 'formula':
     cmh_test(formula, data, subset = NULL, weights = NULL, ...)
     ## S3 method for class 'table':
     cmh_test(object, distribution = c("asymptotic", "approximate"), ...)
     ## S3 method for class 'IndependenceProblem':
     cmh_test(object, distribution = c("asymptotic", "approximate"), ...)

     ## S3 method for class 'formula':
     chisq_test(formula, data, subset = NULL, weights = NULL, ...)
     ## S3 method for class 'table':
     chisq_test(object, distribution = c("asymptotic", "approximate"), ...)
     ## S3 method for class 'IndependenceProblem':
     chisq_test(object, distribution = c("asymptotic", "approximate"), ...)

     ## S3 method for class 'formula':
     lbl_test(formula, data, subset = NULL, weights = NULL, ...)
     ## S3 method for class 'table':
     lbl_test(object, distribution = c("asymptotic", "approximate"), ...)
     ## S3 method for class 'IndependenceProblem':
     lbl_test(object, distribution = c("asymptotic", "approximate"), ...)

_A_r_g_u_m_e_n_t_s:

 formula: a formula of the form 'y ~ x | block' where 'y' and 'x' are
          factors (possibly ordered) and 'block' is an optional factor
          for stratification.

    data: an optional data frame containing the variables in the model
          formula.

  subset: an optional vector specifying a subset of observations to be
          used.

 weights: an optional formula of the form '~ w' defining integer valued
          weights for the observations.

  object: an object inheriting from class '"IndependenceProblem"' or an
          object of class 'table'.

distribution: a character, the null distribution of the test statistic
          can be approximated by its asymptotic distribution
          ('"asymptotic"')  or via Monte-Carlo resampling
          ('"approximate"'). Alternatively, the functions 
          'approximate' or 'asymptotic' can be used to specify how the
          exact conditional distribution of the test statistic should
          be calculated or approximated.

     ...: further arguments to be passed to or from methods.

_D_e_t_a_i_l_s:

     The null hypothesis of the independence of 'y' and 'x' is tested,
     'block' defines an optional factor for stratification. 
     'chisq_test' implements Pearson's chi-squared test,  'cmh_test'
     the Cochran-Mantel-Haenzsel test and 'lbl_test' the
     linear-by-linear association test for ordered data.

     In case either 'x' or 'y' are ordered factors, the corresponding
     linear-by-linear association test is performed by all the
     procedures. 'lbl_test' coerces factors to class 'ordered' under
     any circumstances. The default scores are '1:nlevels(x)' and 
     '1:nlevels(y)', respectively. The default scores can be changed 
     via the 'scores' argument (see 'independence_test'),  for example
     'scores = list(y = 1:3, x = c(1, 4, 6))' first triggers a coercion
     to class 'ordered' of both variables and attaches the list
     elements as scores to the corresponding factors. The length of a
     score vector needs  to be equal the number of levels of the factor
     of interest.

     The authoritative source for details on the documented test
     procedures is Agresti (2002).

_V_a_l_u_e:

     An object inheriting from class 'IndependenceTest-class' with
     methods 'show', 'statistic', 'expectation',  'covariance' and
     'pvalue'. The null distribution  can be inspected by 'pperm',
     'dperm', 'qperm' and 'support' methods.

_R_e_f_e_r_e_n_c_e_s:

     Alan Agresti (2002), _Categorical Data Analysis_. Hoboken, New
     Jersey: John Wiley & Sons.

_E_x_a_m_p_l_e_s:

     data(jobsatisfaction, package = "coin")

     ### for females only
     chisq_test(as.table(jobsatisfaction[,,"Female"]), 
         distribution = approximate(B = 9999))

     ### both Income and Job.Satisfaction unordered
     cmh_test(jobsatisfaction)

     ### both Income and Job.Satisfaction ordered, default scores
     lbl_test(jobsatisfaction)

     ### both Income and Job.Satisfaction ordered, alternative scores
     lbl_test(jobsatisfaction, scores = list(Job.Satisfaction = c(1, 3, 4, 5),
                                             Income = c(3, 10, 20, 35)))

     ### the same, null distribution approximated
     cmh_test(jobsatisfaction, scores = list(Job.Satisfaction = c(1, 3, 4, 5),
                                             Income = c(3, 10, 20, 35)),
              distribution = approximate(B = 10000))

