---
title: "General Data Transforms With cdata"
author: "John Mount, Nina Zumel"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{General Data Transforms With cdata}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

One of the design goals of the [`cdata`](https://github.com/WinVector/cdata) [`R`](https://www.r-project.org) package
is that data occurs in records, and records may be a pattern of cells in a groups of rows.

The allows `cdata` to support very powerful and arbitrary record transforms in one or two steps.  Using "row records" (that is records that are exactly one row) as an intermediate lets us take just about any record shape to just about any record shape: first convert to row-records, then re-block the data into arbitrary record shapes (please see [here](https://winvector.github.io/cdata/articles/blocksrecs.html) and [here](https://winvector.github.io/cdata/articles/design.html) for the concepts).

But as with all general ideas, it is much easier to see what we mean by the above with a concrete example.  Let's consider the following artificial (but simple) example.  Suppose we have the following data.

```{r}
library("cdata")

data <- wrapr::build_frame(
   "record_id"  , "row" , "col1", "col2", "col3" |
     1          , "row1", 1     , 2     , 3      |
     1          , "row2", 4     , 5     , 6      |
     1          , "row3", 7     , 8     , 9      |
     2          , "row1", 11    , 12    , 13     |
     2          , "row2", 14    , 15    , 16     |
     2          , "row3", 17    , 18    , 19     )

knitr::kable(data)
```

In the above the records are the triples of rows with matching `record_id` and the different rows within the record
are identified by the value in the `row` column.  So The data items are named by the triplet `record_id`, `row` and renaming column name (`col1`, `col2`, or `col2`).  This sort of naming of values is essentially [Codd's "guaranteed access rule"](https://en.wikipedia.org/wiki/Codd%27s_12_rules).

Suppose we want to transpose each of the records- swapping the row and column notions.  With `cdata` this is easy.  First you design a transform to flatten each complex record into a single wide row (using the design steps taught [here](https://winvector.github.io/cdata/articles/design.html)).  Essentially that is just specifying the following control variables.  We define how to identify records (the key columns) and the structure of the records (giving the interior of the record arbitrary names we will re-use later).

```{r}
recordKeys = 'record_id'

incoming_shape <- wrapr::qchar_frame(
   "row"   , "col1", "col2", "col3" |
     "row1", v11   , v12   , v13    |
     "row2", v21   , v22   , v23    |
     "row3", v31   , v32   , v33    )
```

And we specify (using the same principles) the desired final record shape, re-using the interior names from the first step to show where values are to be mapped.

```{r}
outgoing_shape <- wrapr::qchar_frame(
   "column_label"  , "c_row1", "c_row2", "c_row3" |
     "rec_col1"    , v11     , v21     , v31      |
     "rec_col2"    , v12     , v22     , v32      |
     "rec_col3"    , v13     , v23     , v33      )
```

Once you have done this you specify the overall transform by building a layout specifying the incoming and outgoing record shapes.

```{r}
layout <- layout_specification(
  incoming_shape = incoming_shape,
  outgoing_shape = outgoing_shape,
  recordKeys = recordKeys)

print(layout)
```

This layout specification or controller can then perform the transform.

```{r}
data %.>%
  layout %.>%
  knitr::kable(.)
```

And the transform is done, each record has been transposed.  

The principle is "draw a picture."  First we draw a picture of the block record structure we have, and then we draw a picture of the block record structure we want. 

As you have seen, we have complete freedom to re-name columns and record-piece labels (the labels that tell us which portion of a block-record each row fits into).

If you don't want to use pipe notation, you can use the method `layout_by()` (which takes a layout specification as an argument) or the method `convert_records()` (which takes the components of the transform specification as separate arguments).

```{r}
lr <- layout_by(layout, data)
knitr::kable(lr)

cr <- convert_records(
  data,
  keyColumns = recordKeys,
  incoming_shape = incoming_shape,
  outgoing_shape = outgoing_shape)

knitr::kable(cr)
```

A nifty bonus is: if the transformation is "faithful" (preserves enough cells and labels), then it is invertible and in fact easy to invert (by the `t()` transpose/adjoint function).

```{r}
inv_layout <- t(layout)

print(inv_layout)

data %.>%
  layout %.>%
  inv_layout %.>%
  knitr::kable(.)
```


Also these conversions can also be translated into [`rquery`](https://github.com/WinVector/rquery) operators, and therefore saved to be run either in memory or directly on a database.

```{r}
table_desciption <- rquery::local_td(data)
ops <- table_desciption %.>%
  layout

cat(format(ops))

rquery::column_names(ops) 

if(requireNamespace("DBI", quietly = TRUE) &&
   requireNamespace("RSQLite", quietly = TRUE)) {
  raw_connection <- DBI::dbConnect(RSQLite::SQLite(), 
                                   ":memory:")
  RSQLite::initExtension(raw_connection)
  db <- rquery::rquery_db_info(
    connection = raw_connection,
    is_dbi = TRUE,
    connection_options = rquery::rq_connection_tests(raw_connection))
  
  db_td <- rquery::rq_copy_to(db, "data", data)
  
  ops %.>% 
    db %.>% 
    knitr::kable(.) %.>%
    print(.)
  
  DBI::dbDisconnect(raw_connection)
}
```

And that is some of the generality of `cdata` transforms.


