---
title: "tableMatrix package"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r, echo = FALSE}
library(tableMatrix)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path='man/figures/README-'
)
```
#Overview

tableMatrix package provides two classes extending data.table class. Simple `tableList` class wraps data.table and any additional structures together. More complex `tableMatrix` class combines strengths of data.table and matrix.

##Installation
From CRAN:
```{r eval=FALSE}
install.packages("tableMatrix")
```
From github:
```{r eval=FALSE}
# install.packages("devtools")
devtools::install_github("InferenceTechnologies/tableMatrix")
```

##tableList class

###Motivation
Goal is to wrap data.table class and other structures together and preserve data.table behaviour.

###Example
Combine data and linear model into one object.

```{r}
data(chickwts)
 
# Bundle chickwts data.frame together with a linear model
TL <- tableList(chickwts, lm(weight~feed, chickwts))

# tableList behaves like a data.table  
mean(TL[feed=="casein", weight])

# Aid part of the tableList object carries the linear model
aid(TL)
```

##tableMatrix class

###Motivation
Let's have a dataset with the following structure: first set of columns of varying types is intented as meta data, second set of columns of the same type is intended as main data. `tableMatrix` stores meta data as a data.table and main data as a matrix. It also keeps track of dimensions of main data, thus allowing to combine rows of varying lengths into one object. As in tableList, tableMatrix can carry any additional aid data. 

###Example
Working with bitmaps of different sizes. Datasets `images8By8` and `images10By10` contain 8x8 and 10x10 images in the form of vectors. For each row first three columns represent image meta data, remaining columns represent the image itself. For more information see `?images8By8`.

```{r}
# Load datasets
data(images8By8)
data(images10By10)

# Create a signle tableMatrix object from both datasets
# First 3 columns used as meta data, the rest as main data with corresponding dimensions
TM <- tableMatrix(list(images8By8, images10By10),
list(1:3, 1:3), list(c(4:ncol(images8By8)),c(4:ncol(images10By10))), list(c(8,8), c(10,10)))

# Default print displays the table (meta data) part
TM

# Number of matrices stored in the matrix (main data) part
length(mat(TM))

# Dimensions of the matrix part
matDim(TM)

# Aid part is empty
aid(TM)


# Image data for first row
img <- getRow(TM, 1)

# Restoring dimensions of the image
dim(img) <- getRowDim(TM, 1)

# Visualising the image
image(img, axes=F)
```

Let's create a heat map
```{r}
# Subsetting via bracket passed to the table (meta data) part
# We choose first matrix type, down direction
TM1down <- TM[.(1)][direction=="down"]

# One matrix in the matrix part of TM1down
length(mat(TM1down))

# One dimension row
matDim(TM1down)

# Heatmap
imgHeat <- colMeans(mat(TM1down, 1))

# Restoring dimensions of the heatmap
dim(imgHeat) <- getRowDim(TM1down, 1)

# Visualising heatmap
image(imgHeat, axes=F)
```