---
title: "simtimer"
author: "Adrian Stämpfli and Michael Schmid, IMS-FHS"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{simtimer}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE, message=FALSE, results='hide'}
knitr::opts_chunk$set(echo = TRUE)
knitr::opts_chunk$set(message = FALSE)
# knitr::opts_chunk$set(results = 'hide')
```

<!-- Code for adding footnotes: footnotes^[This is a footnote.] -->

simtimer is a little R package designed to simplify (and speeding up) calculating time intervals in discrete event simulations. 

Discrete event simulations is a simulation paradigm that is based on the evaluation of events taking place in a time-specific order. Therefore a discrete event simulation calculates many time intervals. simtimer handles dates and times as integers. This makes working with time intervals as easy (and as fast) as subtracting integers.

simtimer uses an `origin_date` and calculates all dates and times referring to that `origin_date`. 
  
The applications of simtimer are discrete event simulations representing a timerange of several minutes to years. For such problems, the time dimension might preferably be represented as a relative timescale (integer) than a series of `date_time` objects (POSIXt). simtimer is a basic tool to transform `date_times` to a relative timescale in seconds (`sim_datetime`) and vice versa. Additionally simtimer allows to extract elements of a `sim_datetime` such as time, weekday and date.  

```{r, echo = F, out.width = "690px"}
knitr::include_graphics("comparison_simtimer_vs_regular_time.jpg")
```


## Basic transformation

For the transformation into the relative timescale (`date_time` -> `sim_datetime`) use the corresponding function `as.sim_datetime()`. This function expects an `origin_date` of choice to be predefined. This `origin_date` should be earlier in time than the following `date_time`-elements.

```{r}
library(simtimer)
origin_date <- as.POSIXct("2017-01-01 00:00:00", tz = "UTC")
my_datetime <- c(as.POSIXct("2017-01-01 02:00:00", tz = "UTC"), 
                 as.POSIXct("2017-02-27 20:53:20", tz = "UTC"),
                 as.POSIXct("2017-08-20 11:33:20", tz = "UTC"),
                 as.POSIXct("2018-01-06 08:53:20", tz = "UTC"))
my_sim_datetime <- as.sim_datetime(my_datetime, origin_date)
my_sim_datetime
class(my_sim_datetime)
```

All remaining functions of simtimer take a `sim_datetime` as argument.  

For the opposite transformation (`sim_datetime` -> `date_time`) use the corresponding function `as.datetime()` with the same `origin_date`.
```{r}
as.datetime(my_sim_datetime, origin_date)
```


## Extracting the time (in seconds)

You can extract the time (in seconds) of a `sim_datetime` element by using the function `sim_time()`. It returns how many seconds have past since the last "beginning of a day" depending on the time-part of your `origin_date` ("00:00:00" is recommended).
```{r}
sim_time(my_sim_datetime)
```


## Extracting the weekday

You can extract the weekday of a `sim_datetime` elemet by using the function `sim_wday()`. It returns the weekday of your `sim_datetime`.
```{r}
sim_wday(my_sim_datetime, origin_date)
```


## Extracting the date

In order to count the days that have passed since the beginning (your `origin_date`) use 
`sim_date()`. To be more precise - the function returns the number of `24*60*60`-intervals 
that have passed since your `origin_date`.   

```{r}
sim_date(my_sim_datetime)
```