README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# vikingr

<!-- badges: start -->
<!-- badges: end -->

The goal of `vikingr` - [name etymology](https://en.wikipedia.org/wiki/Vikings#Etymology) - is to provide a way to decode and work with data provided in the [AIS format](https://gpsd.gitlab.io/gpsd/AIVDM.html) from within R. Or rather the primary goal is to use some of the techniques taught at the Raukr 2019 workshop when creating an R package.

Some demo data is bundled into the package that can be used offline as an example dataset. This data was captured from the Visby Harbor during the RaukR summer school 2019. This is a subset of some realistic data from the modern-day viking ships that traffic the Visby harbor in Gotland, Sweden.

## Installation

You can install the development version of `vikingr`from [GitHub](https://github.com/mskyttner/vikingr) with:

```{r install, eval=FALSE}
# install.packages("devtools")
devtools::install_github("mskyttner/vikingr", build_vignettes = TRUE)

# or if devtools is > 2.0
devtools::install_github("mskyttner/vikingr", dependencies = TRUE,
  build = TRUE, build_opts = c("--no-resave-data", "--no-manual"))
```

## Example

This is a basic example which shows typical usage:

```{r example}

suppressPackageStartupMessages(library(dplyr))
library(knitr)
library(vikingr)

# get a few of the encoded messages

log <- read_ais_log(vikingr_example("vikingr-visby-2019-ais"))

# display some encoded messages, but ...
# escape the message which otherwise can appear
# garbled when displayed in the markdown

log_escaped <- 
  log %>% 
  slice(2:5) %>% 
  mutate(message = sprintf("<code>%s</code>", message))

kable(escape = FALSE, log_escaped)

# decode messages and add timestamps from the log

parsed_messages <- read_ais(log$message)

df <-
  parsed_messages %>% 
  left_join(log) %>% 
  select(timestamp, everything())

# display a few decoded messages, escaping the raw message

df_escaped <- 
  df %>% 
  slice(1:5) %>% 
  select(1:5) %>%
  mutate(message = sprintf("<code>%s</code>", message))

kable(df_escaped, escape = FALSE)

# display a few of the parsing issues with readr::problems()

library(readr)

parsing_issues <- 
  problems(parsed_messages) %>% 
  slice(1:5) %>% 
  mutate(actual = sprintf("<code>%s</code>", actual))

kable(parsing_issues, escape = FALSE)

```

Inspect a single record:

```{r}
# these are the details for a single record
record <- 
  df %>% slice(1) %>% t() %>% as.vector() %>% tibble() %>% 
  mutate(field = names(df)) %>% 
  select(field, value = 1)

kable(record)

```

## Improvements

Parsed data for individual records can be checked against results from other parsers or web services that can parse AIS messages. Improvements can be sent as a PR, for details see instructions below.

## Development

[![Get the GitHub CLI Badge](https://img.shields.io/badge/CLI-GitHub%20CLI%20Friendly-blue.svg)](https://hub.github.com)

The [GitHub CLI tool](https://hub.github.com) can be used for reproducible collaboration workflows when collaborating on this (or any other) repo, for whatever reason - such as for convenience and automation support or perhaps because someone is handing out CLI badges and you want one ;). 

Usage example while at the CLI, if you want to add a feature branch that provides command line support for using this R package along with usage examples:

    $ hub clone mskyttner/vikingr
    $ cd vikingr
    
    # create a topic branch
    $ git checkout -b add-cli-support
    
    # make some changes... then ...
    
    $ git commit -m "done with feature"
    
    # It's time to fork the repo!
    $ hub fork --remote-name=origin
    → (forking repo on GitHub...)
    → git remote add origin git@github.com:YOUR_USER/vikingr.git
    
    # push the changes to your new remote
    $ git push origin add-cli-support
    
    # open a pull request for the topic branch you've just pushed
    $ hub pull-request
    → (opens a text editor for your pull request message)