---
title: "Helper Functions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Helper Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(dht)
```

## Welcome users to DeGAUSS

```{r}
greeting(
  geomarker_name = "roads",
  version = "0.1",
  description = "calculates proximity and length of nearby major roadways"
)
```

(Here we supplied values to use in the greeting, but from inside a DeGAUSS container these will be automatically picked up based on the [environment variables that capture metadata](./degauss-metadata-specification.html) using just `dht::greeting()`.)

## Read in geocoded data

```{r}
(d <- read_lat_lon_csv('../tests/testthat/my_address_file_geocoded.csv',
sf = T, project_to_crs = 5072))
```

Returns a list with two elements -- the raw data and tibble nested on row (to prevent calculations with duplicate lat/lon).

## Check that required columns are present

```{r}
check_for_column(d, 'lat', d$lat)
```

Nothing is returned if the column is present.
An error is thrown if the column is not present.

```{r error=T}
check_for_column(d, "nope", d$lat)
```

## Check for column type

```{r}
check_for_column(d, 'lat', d$lat, 'numeric')
```

Again, nothing is returned if the column type matches the desired type.
A warning is displayed if the column type does not match the desired type.

```{r}
check_for_column(d, 'lat', d$lat, 'character')
```

## Check that dates are read in correctly/reformat dates

```{r}
check_dates(c('1/1/21', '1/2/21', '1/3/21'))
```

If dates are in slash (1/1/21) or ISO (2021-01-01) format, they are returned in ISO format. 
If dates are in another format, a helpful error message is generated.

```{r error=T}
check_dates(c('1/1/2021', '1/2/2021', '1/3/2021'))
```

## Write geomarker output file

Unnests the tibble created with `read_lat_lon_csv()` and merges back to raw data, then writes the output csv with container name and version appended to filename. 

```{r, eval = F}
write_geomarker_file(d = d, 
                     raw_data = d, 
                     filename = 'tests/my_address_file_geocoded.csv', 
                     geomarker_name = 'roads', 
                     version = '0.1')
```

From inside of a DeGAUSS container, where the [environment variables that capture metadata](./degauss-metadata-specification.html) are available, this can be accomplished with just:

```{r, eval = F}
write_geomarker_file(d = d, raw_data = d, filename = opt$filename)
```