introduction.Rmd

---
title: "Introduction"
author: "Michael Kuhn"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction to the dict package

The `dict` package exports two functions: `dict()` and `numvecdict()`. The former creates a Python-style dictionary (or hash table) that can take any R object as value, and numbers and strings (and the respective vectors) as keys. The latter behaves like a Python `defaultdict(list)`, but takes only numeric vectors as values.

### Overview of member functions: `dict`

| function                 | description                             |
|--------------------------|-----------------------------------------|
| `d[[key]] <- value`      | assignment   |
| `d[[key]]`               | retrieval, error if key not present  |
| `d$get(key)`             | retrieval, return `NULL` if not present  |
| `d$get(key, "default")`  | retrieval, return second parameter if not present  |
| `d$keys()`               | list of keys |
| `d$values()`             | list of values |
| `d$items()`              | list of items (as a list of lists) |
| `d$length()`             | number of items |

### Overview of member functions: `numvdict`

| function                 | description                             |
|--------------------------|-----------------------------------------|
| `d[[key]] <- value`      | assignment (must be number or numeric vector)   |
| `d[[key]]`               | retrieval, return empty vector if not present  |
| `d$get(key)`             | retrieval, return empty vector if not present  |
| `d$get(key, NA)`         | retrieval, return second parameter if not present  |
| `d$append_number(key, x)`| append a number to an entry (creates a new entry if necessary) |
| `d$append_items(d2)`     | append items from another dictionary |
| `d$each_mean()` (also: `median`, `max`, `min`) | return new dictionary with the mean of each value |
| `d$inplace_mean()` (also: `median`, `max`, `min`) | convert values to their mean for this dictionary |
| `d$keys()`               | list of keys |
| `d$values()`             | list of values |
| `d$items()`              | list of items (as a list of lists) |
| `d$length()`             | number of items |

## Usage examples: `dict`

To get a new, empty dictionary, call the `dict` function, optionally with argumebts for initialization:

```{r}
library(dict)

d <- dict( list("Initial", "keys"), list("Initial", "values") )

d <- dict()
```

You can then assign items using numbers and strings (and vectors of these) as keys:

```{r}
d[[1]] <- "First entry!"
d[[c(2,3)]] <- 5
d[["a string"]] <- list(A = 1, B = 2)
d[[c("A", "B")]] <- function(x) 1+x
```

...and then retrieve them again:

```{r}
d[[c(2,3)]]
f <- d[[c("A", "B")]]
f(41)
```

Accessing a non-existing key leads to an error:

```{r, error=TRUE}
d[["?"]]
```

However, you can use `d$get` to return `NA` or another default value:

```{r}
d$get("?")
d$get("?", "default")
```

You can access the `keys`, `values`, `items`, and `length`:

```{r}
d$keys()
d$values()
d$items()
d$length()
```

## Usage examples: `numvecdict`

To get a new, empty dictionary, call the `numvecdict` function:

```{r}
d <- numvecdict()
```

This dictionary only contains vectors of numbers, which you can assign:

```{r}
d[[1]] <- 1
d[[2]] <- c(2,3)
d[["a string"]] <- 1:10
```

You can append numbers to the lists. If you specify a new key, the entry will be generated automatically:

```{r}
d$append_number(1, 2)
d$append_number(2, 3)
d$append_number("answers", 42)
```

Then, you can retrieve the vectors you stored:

```{r}
d$get(1)
d[[2]]
d[["answers"]]
d[["completely new and never seen key"]]
```

It is possible to add the values of one `numvecdict` to the other:

```{r}
a <- numvecdict()
b <- numvecdict()

a[[1]] <- 1
b[[1]] <- 2
b[[2]] <- 3

a$append_items(b)

a$items()
```

You can extract the means into a new dictionary. The same works for the median, min, and max.

```{r}
mean_d <- d$each_mean()
mean_d$items()
```

It is also possible to replace each value with its mean:

```{r}
d$inplace_mean()
d$items()
```