---
title: "Migration guide: 'cdm' -> 'dm'"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Technical: Migration guide: 'cdm' -> 'dm'}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---


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

This vignette describes which changes are necessary to adapt your code when updating the {dm} package version from a version `0.0.5` or lower to `0.0.6` or higher.

## Changes required when updating from version `0.0.5` to `0.0.6`

### Replace `cdm` with `dm`

During this update the prevalent prefix `cdm` was discarded in favor of `dm`.
The old prefix would still do its job, but a warning message would be issued each time a function beginning with `cdm` was being used, informing that the function is soft-deprecated and suggesting the use of its newer version.

If you have a script which is based on an older {dm} version, it should still work with the newer version, albeit complaining each time an outdated function is being used.
This can be repaired by:

1. either going through the script step by step, testing the output of each line of code and use the new function names provided in the generated warnings to update the function calls.
1. or just by replacing all occurrences of `cdm` by `dm` in this script. This can e.g. be done in RStudio using "Find" or in the terminal using `sed -e 's/cdm/dm/g' path-to-file` on Windows or `sed -i '' -e 's/cdm/dm/g' path-to-file` on a Mac. If the script errors after this step, you will need to check where exactly the error happens and manually repair the damage.

### Be careful with methods for `dm`: `tbl`, `[[`, `$`

Furthermore, you need to pay attention if you used one of `tbl.dm()`, `[[.dm()`, `$.dm()`.
During the same update the implementation for those methods changed as well, and here you don't get the convenient warning messages.
The change was, that before the update, the mentioned methods would return the table after "filtering" it to just contain the rows with values that relate via foreign key relations to other tables that were filtered earlier.
After the update just the table as is would be returned.
If you want to retain the former behavior, you need to replace each of the methods with the function `dm_apply_filters_to_tbl()`, which was made available with the update.

The methods are of course not to be avoided in general, if no filters are set anyway the result will not change after the update.

Here a short example for the different cases:

Formerly you would access the "filtered" tables using the following syntax:

```{r}
library(dm)
flights_dm <- dm_nycflights13()
tbl(flights_dm, "airports")
flights_dm$planes
flights_dm[["weather"]]
```

After the update the same result is achieved by this type of function call:

```{r}
dm_apply_filters_to_tbl(flights_dm, airlines)
```