---
title: "Checking Whether Margins are (Stochastically) Ordered"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Checking Whether Margins are (Stochastically) Ordered}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(ordinalTables)
```

# Checking Whether the Margins are Ordered

For this example, we will use the vision_data.

```{r vision_data}
print(vision_data)
```

   Row Sums = `r rowSums(vision_data)`
Column Sums = `r colSums(vision_data)`


## Testing Marginal Homogeneity

A first test is whether the margins can be considered identical.  There are two tests of marginal homogeneity, Stuart's and Bhapkar's.  These are available as Stuart_marginal_homogeneity() and Bhapkar_marginal_homoogeneity(), and for a r X r table there are r - 1 degrees.  There is also a third test using the Minimum Discriminannt Information statistic, MDIS, Ireland_marginal_homogeneity()

``` {r marginal_homogeneity}
stuart_result <- Stuart_marginal_homogeneity(vision_data)
bhapkar_result <- Bhapkar_marginal_homogeneity(vision_data)
ireland_result <- Ireland_marginal_homogeneity(vision_data)
```

For this data, the first two yield very similar values. Suart is ```r stuart_result$chisq``` and Bhapkar yields `r bhapkar_result$chisq`.

Using the MDIS criterion yields another similar result, `r ireland_result$mdis`, as the MDIS can be interpreted similarly to a chi-square with r - 1 (3) degrees of freedom.

In all 3 cases we reject the hypothesis that the margins are the same.


## Using Cliff's d-test

First, we examine the independent d-test, ignoring the pairing infomation, using Cliff_independent_from_table(vision_data).  

```{r cliff_independent}
cliff_independent <- Cliff_independent_from_table(vision_data)
```

Somewhat surprisingly, there is a non-significant difference, d = `r cliff_independent$d_bar`, with an associated z-score of `r cliff_independent$z_d_bar`.

Next, we do a dependent test.  We can test whether the columns are greated than the rows using Cliff_dependent_compute_from_table()

```{r cliff_tables}
cliff_result <- Cliff_dependent_compute_from_table(vision_data)
```

It is important to use the Cliff_dependent_compute_from_table() version of the test. The similarly named Cliff_compute_from matrix() expects an N X N d-matrix as input.  Calling it with a table yields nonsense results. If for some reason we do want to compute a d-matrix (7477 X 7477 here), use Cliff_dependent_compute_paired_d(). There is a noticeable lag for the computation, although the results are identical.  In cases of tables with 7 or more categories, Cliff_dependent_compute_paired_d() has to be used due to limitations in preparing the library (devtools::install() throws an error that the stack has been exceeded).

Here there are 3 tests.  The first, z_dw `r cliff_result$z_dw`, asks whether the within-person
change is 0.  Here it is significant, indicating that the columns (right eye) are higher than the rows (left eye).  The measure z_dw indicates that slightly more than 2% of the time the right eye will score above, the left, versus the pair having the opposite order. With only 16 cells, the table contains a large number of tied comparisons, which contribute to the denominator but not the numerator of the statistic.  The second, z_db test is a comparison of the groups after removing the diagonal.  That also is significant `r cliff_result$z_db` indicating that right eyes tend to have more acute vision than left eyes.  Third, there is an omnibus test of db + dw, which has a z-score of `r cliff_result$z_db_dw`.


## Clayton's Marginal Location Test

Another test is Clayton's test for marginal ordering: Clayton_marginal_location().  It operates only on the margins of the table, so we call rowSums() and colSums().

```{r clayton}
clayton_result <- Clayton_marginal_location(rowSums(vision_data), colSums(vision_data))
```

The value of the odds-ratios (`r clayton_result$theta_hat` and `r clayton_result$mh_theta_hat`are slightly greater than 1, indicating that columns are higher than rows.  However the associated chi-square statistics are both about 3.5 (`r clayton_result$theta_hat` and `r clayton_result$mh_theta_hat`for the test, with a non-significant p-value of `r clayton_result$p`.  Note that, like the independent Cliff test, the Clayton test does not make use of the pairing of the observations in the table. 


## Agresti's Mann-Whitney Test

We can also check using Agresti's weighted version of the Mann-Whitney test: Agresti_weighted_tau()

```{r agresti }
result <- Agresti_weighted_tau(vision_data)
```

Note that the z-score of `result$z_diff` is similar in size to the Cliff statistic, but the sign is in the opposite direction.


## Agresti's weighted difference: Agresti_w_diff()

```{r agresti_weighted }
w <- c(-3, -1, 1, 3)
agresti_result <- Agresti_w_diff(w, vision_data)
```

The result is again negative and near -3.5, z = `agresti_result$z_diff`.

We can also compare "spread" of the marginal scores:

```{r agresti_weighted_spread}
w <- c(3, 1, 1, 3)
agresti_result_spread <- Agresti_w_diff(w, vision_data)
```

This time the z-statistic of `r agresti_result_spread$z_diff` indicates no significant difference.


## McCullagh's Logistic Model: McCullagh_logistic_model()

The final tests to examine are McCullagh's (1977) logistic model.

```{r mccullagh} 
mccullagh_result <- McCullagh_logistic_model(vision_data)
```

There are two estimators, delta_tilde (`r mccullagh_result$delta_tilde`) and delta_star (`r mccullagh_result$delta_star`), which uses weights analogous to those used in the Mantel-Haenszel common odds ratio. Both are compared to the square root of the variance `r mccullagh_result$var`, which is `r sqrt(mccullagh_result$var)`, giving z-scores of `r mccullagh_result$z_delta_tilde` and `r mccullagh_result$z_delta_star`.


## Conclusions

From these analyses we can:
1) reject the hypothesis of marginal homoogeneity.
2) conclude that columns (vision acuity of right eye) are soomoewhat higher than rows (accuity of left eye)
3) determine that there is important information in the pairing in the data.  The statistics that ignored it were not significant, while analyses that included the information were significant.
