---
title: "Visualizing dm objects"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{Techincal: Visualizing dm objects}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

``````{r setup, include = FALSE}
source("setup/setup.R")
``````

Once you have all your primary keys set and all foreign key relations defined, a graphical representation of your data model offers a condensed view of the tables and the relationships between the tables.
The following functions can be used to visualize the `dm` object:^[The code for the functions in this section is borrowed from the [{datamodelr}](https://github.com/bergant/datamodelr) package.]

1. `dm_draw()`
1. `dm_set_colors()`
1. `dm_get_colors()`
1. `dm_get_available_colors()`

We use the prepared example `dm` object `dm_nycflights13(cycle = TRUE)`:

```{r}
library(dm)
library(dplyr)
flights_dm_w_many_keys <- dm_nycflights13(cycle = TRUE, color = FALSE)
flights_dm_w_many_keys
```

The schema is drawn with `dm_draw()`.

```{r}
dm_draw(flights_dm_w_many_keys)
```

You can use colors to visually group your tables into families to reflect their logical grouping.
The available colors are either hexcoded colors or the standard R color names.
The function `dm_get_available_colors()` forwards to `grDevices::colors()`:

```{r}
dm_get_available_colors()
```

Colors are assigned with `dm_set_colors()` using syntax known in the {tidyverse} as {tidyselect}-syntax, here in the form: `color = table`.
[Select helper functions](https://tidyselect.r-lib.org/reference/language.html) are supported.
The result of `dm_set_colors()` is a `dm` object.
The information about the color is stored together with the rest of the metadata.

```{r}
flights_dm_w_many_keys_and_colors <-
  flights_dm_w_many_keys %>%
  dm_set_colors(
    maroon4 = flights,
    orange = starts_with("air"),
    "#5986C4" = planes
  )
```

Draw the schema with `dm_draw()`.

```{r}
dm_draw(flights_dm_w_many_keys_and_colors)
```

The colors can be queried with `dm_get_colors()`.

```{r}
dm_get_colors(flights_dm_w_many_keys_and_colors)
```

See the documentation for `dm_draw()` for further options.
One important argument is `view_type`.
Besides the default `"keys_only"`, it accepts `"all"` to display all columns, and `"title_only"` to show only the title of the table.

```{r}
flights_dm_w_many_keys_and_colors %>%
  dm_draw(view_type = "title_only")
```

If you would like to visualize only some of the tables, use `dm_select_tbl()` before drawing:

```{r}
flights_dm_w_many_keys_and_colors %>%
  dm_select_tbl(flights, airports, planes) %>%
  dm_draw()
```

Finally, for exporting a drawing to `svg` you could use `DiagrammeRsvg::export_svg()`:

```{r eval = default_eval() && rlang::is_installed("DiagrammeRsvg")}
flights_dm_w_many_keys_and_colors %>%
  dm_select_tbl(flights, airports, planes) %>%
  dm_draw() %>%
  DiagrammeRsvg::export_svg() %>%
  write("flights_dm_w_many_keys_and_color.svg")
```