---
title: "The print method for class ranktable"
author: "R. K. S. Hankin"
output: bookdown::html_document2
bibliography: hyper2.bib  # copy vignettes/hyper2.bib to inst/
---


```{r setup, include=FALSE}
set.seed(0)
knitr::opts_chunk$set(echo = TRUE)
library("hyper2")
library("magrittr")
options("digits" = 5)
```

```{r out.width='20%', out.extra='style="float:right; padding:10px"',echo=FALSE}
knitr::include_graphics(system.file("help/figures/hyper2.png", package = "hyper2"))
```

To cite the `hyper2` package in publications, please use @hankin2017_rmd.
Rank tables can be confusing.  The package includes a range of
functionality for dealing with them, including a bespoke print method.
Here, I discuss two cases: firstly, a tiny toy example, and secondly
the volvo ocean racing dataset.


# Toy dataset

```{r makeatoy}
OT <- cbind(1:5,c(1,5,2:4))
rownames(OT) <- letters[seq_len(nrow(OT))]
colnames(OT) <- c("J1","J2")
OT
```

Object `OT` is a straightforward order table, just like
`skating_table` but smaller and simpler.  We have two columns, one for
each judge (named `J1` and`J2`), and five competitors, `a` through
`e`.  The first row refers to competitor `a`; both judges put
competitor `a` first.  The second row shows that `J1` put `b` second
and `J2` put competitor `b` fifth.  If instead we ask who was placed
third by each judge, this is not directly given; but by looking for
`3` in the table we see that `J1` put `c` third and `J2` put `d`
third.  To answer this and similar questions directly, we can coerce
order table `OT` to a rank table `RT`:

```{r useordertorank}
RT <- ordertable_to_ranktable(OT)
RT
```

Object `RT` gives the same information as `OT` but in a different
form.  Note that above we see the print method in action, which uses
`ranktable_to_printable_object()`.  Here the _rows_ correspond to the
two judges.  Each row is a rank vector.  Column headings refer to
placings (`c1` is supposed to be read "came first", `c2` "came second"
etc).  Looking at the fifth column (`c5`) we see that `J1` and `J2`
placed `e` and `b` fifth respectively.

Note that it is possible to view object `RT` directly by removing
class `ranktable`:

```{r viewdirect}
class(RT)
class(RT) <- "matrix"  # removes "ranktable" from class list
RT
```

Note carefully that the second row of `RT` (which corresponds to the
second judge) does *not* match the second column of `OT`.  The way to
read the second row of `RT` is as follows.  We see the entries `1 3 4
5 2` indicating that the first choice was competitor 1 [viz `a`], the
second choice was competitor 3 [viz `c`], the third choice was
competitor 4 [viz `d`], fourth choice was competitor 5 [`e`] and fifth
choice was competitor 2 [`b`].  So the rows are *ranks* (see the
discussion in `rrank.Rd`).  But it is very tempting to read the second
row of `RT` as "judge 2 placed competitor `b` in third place", which
is wrong because this is interpreting the row as an *order*.  This is
why the print method is there.


# Volvo ocean racing dataset

(See `volvo.Rd` for more details).

```{r showvolvotable}
volvo_table
```

Thus we see from the first column that in leg 1, AbuDabhi came first,
Brunel third, and so on.  From the first row we see that AbuDhabi came
first in leg 1, third in leg 2, second in leg 3, and so on.  Suppose
we wish to know who came first in each leg:

```{r nowusewikitorank}
x <- wikitable_to_ranktable(volvo_table)
x
```

And we see from the first column that AbuDhabi came first in leg 1,
Brunel came first in leg 2, Dongfeng came first in leg 3, and so on.
The second column shows who came second in each leg.  Now suppose we
are interested in only the first, second and third-placed teams:


```{r just3}
x[,1:3]
```

The above shows that the extraction method for `ranktable` objects is
not yet written; maybe one day I will get round to implementing
`[.ranktable()` (right now I am not 100% sure that this is a good
idea).  Note that simply restoring the `ranktable` class can be
misleading:

```{r nowmakerank3}
xx <- x[,1:3]
xx
class(xx) <- "ranktable"
xx
```

In the above, `NA`s are introduced because a `ranktable` object uses
the column names to store names of the competitors, and of course
extracting the first three columns means keeping only the first three
column names.  Observe that extraction after passing to
`ranktable_to_printable_object()` works nicely:


```{r showprintableobject}
ranktable_to_printable_object(x)[,1:3]
```


## References {-}