---
title: "The meanings of flags and codes"
author: "Steffi LaZerte"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{flags}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE, message = FALSE}
library(weathercan)
library(dplyr)
library(tidyr)
```


## What are flags/codes

The data output of the `weather_dl()` function include corresponding `_flag` columns for each data column. These columns are used by ECCC to add notes regarding measurements. 

Similarly, the data output of the `normals_dl()` function include corresponding `_code` columns. These columns are used by ECCC to add notes regarding the amount of data used to calculate the normals.


### Flags
In the `weather_dl()` function if `format = TRUE` (the default), data corresponding to flags `M`, `NA`, `[empty]` and `L` are all replaced with `NA`.

For example, a sample of unformatted data from Magog station in Quebec looks like:

```{r, echo = FALSE}
options(width = 100)
w <- weather_dl(station_id = 5401, start =  "2017-01-01", 
                interval = "month", format = FALSE)

dplyr::select(w, station_name, `Date/Time`, 
              `Total Precip (mm)`, `Total Precip Flag`,
              `Snow Grnd Last Day (cm)`, `Snow Grnd Last Day Flag`) %>% 
  tail(n = 12)
```

In this output, you can see two flags: `^` in `Total Precip` and `M` in `Snow Grnd Last Day`

This same sample, formatted looks like:

```{r, echo = FALSE}
weather_dl(station_id = 5401, start =  "2017-01-01", interval = "month") %>%
  dplyr::select(date, total_precip, total_precip_flag, snow_grnd_last_day, snow_grnd_last_day_flag) %>%
  tail(n = 12)
```

As you can see, we still have the two flags, but the missing data flag (`M`) is now replaced with NA. The other flag `^` is not, as it indicates that "The value displayed is based on incomplete data" (see below).

### Flags - Weather Data

The flags index can be accessed through the built in data frame: `flags`

```{r, echo = FALSE}
knitr::kable(flags)
```

### Codes
In the `normals_dl`() function, codes are associated with each variable:

```{r, echo = FALSE}
n <- normals_dl(climate_ids = "5010480") %>%
  unnest(normals)
select(n, period, contains("temp_daily"))
```

For example, here, the code indicates that these temperature variables meet the WMO '3 and 5 rule' (no more than 3 consecutive and no more than 5 total missing for either temperature or precipitation).                                                                   


### Codes - Climate Normals

The codes index for climate normals can be accessed through the built-in data frame: `codes`

```{r, echo = FALSE}
knitr::kable(codes)
```
