frab

https://github.com/robinhankin/frab

Repository

README.Rmd

---
title: "The frab package: how to add R tables"
output:
  github_document:
    pandoc_args: --webtex
---



```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
set.seed(0)
```

# 

# Overview

To cite the `frab` package in publications please use Hankin (2023).
The `frab` package allows one to "add" R tables in a natural way.  It
also furnishes an alternative interpretation of named vectors wherein
addition is defined using the (unique) names as the primary key.
Support for multi-dimensional R tables is included.  The underlying
mathematical object is the Free Abelian group.

The package has two S4 classes: `frab` and `sparsetable`. 
Class `frab` is for one-dimensional R tables and is an alternative
implementation of named vectors; class `sparsetable` handles
multi-way R tables in a natural way.

# The package in use

## One-dimensional R tables: class `frab`

Primary
construction function `frab()` takes a named vector and returns a
`frab` object:

```{r use1}
suppressMessages(library("frab"))
p <- c(x=1,b=2,a=2,b=3,c=7,x=-1)
frab(p)
```

Above, we see from the return value that function `frab()` has
reordered the labels of its argument, calculated the value for entry
`b` [as $2+3=5$], determined that the entry for `x` has vanished [the
values cancelling out], and printed the result using a bespoke show
method.  It is useful to think of the input argument as a semi-constructed
and generalized "table" of observations.  Thus 

```{r show input argument}
p
```

Above we see `p` might correspond to a story: "look, we have one `x`, two `b`s,
two `a`s, another three `b`s, seven `c`s...oh hang on that `x` was a mistake I
had better subtract one now".  However, the package's most useful feature is the
overloaded definition of addition:

```{r label=additionoverload}
(x <- rfrab())
(y <- rfrab())
x+y
```

Above we see function `rfrab()` used to generate a random `frab`
object, corresponding to an R table.  It is _possible_ to add `x` and
`y` directly:

```{r showitispossible}
xn <- as.namedvector(x)
yn <- as.namedvector(y)
table(c(rep(names(xn),times=xn),rep(names(yn),times=yn)))
```

but this is extremely inefficient and cannot deal with fractional (or indeed negative) entries.

# Multi-way R tables

Class `sparsetable` deals with multi-way R tables.  Taking three-way R
tables as an example:

```{r showthreewaytable}
(x3 <- rspar())
```

Function `rspar()` returns a random `sparsetable` object.  We see that, of the $3^3=27$
possible entries, only 11 are non-zero.  We may coerce to a regular R table:

```{r coercethreearray}
as.array(x3)
```

In this case it is hardly worth taking advantage of the sparse representation (which is largely inherited from the `spray` package) but a larger example might be

```{r}
rspar(n=4,l=10,d=12)
```

The random `sparsetable` object shown above would require $10^{12}$
floating point numbers in full array form, of which only 4 are
nonzero.  Multi-way R tables may be added in the same way as `frab`
objects:

```{r addtwosparsetables}
y3 <- rspar()
x3+y3
```

## Two-way R tables

Two-way R tables are something of a special case, having their own print method.
By default, two-dimensional `sparsetable` objects are coerced to a matrix before
printing, but otherwise operate in the same way as the multi-dimensional case
discussed above:

```{r addtwotwodimensionalsparsetables}
(x2 <- rspar2())
(y2 <- rspar2())
x2+y2
```

Above, note how the sizes of the coerced matrices are different ($5\times 5$ for `x2`,
$6\times 5$ for `y2`) but the addition method copes, using a bespoke sparse
matrix representation.  Also note that the sum has _six_ columns (corresponding
to six distinct column headings) even though `x2` and `y2` have only five.

# Further information

For more detail, see the package vignette

`vignette("frab")`

## References

* R. K. S. Hankin 2023.  "The free Abelian group in `R`: the `frab`
  package", arXiv, https://arxiv.org/abs/2307.13184.
* R. K. S. Hankin 2022. "Disordered vectors in `R`: introducing the
  `disordR` package", arXiv, https://arxiv.org/abs/2210.03856

Owner

GitHub Events

Packages