---
title: "timeR Quick Start"
author: "Yifu Yan"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{timeR Quick Start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`timeR` package creates a R6 class, which allows you to create a timer object
to easily time your codes. Meanwhile, all records are saved to a data frame, so it's easy to retrieve all the records for later use.

Timing codes is not difficult but can be very tedious. With `timeR`, you can save your energy on timing and put more effort on 
your analysis. You can use `timeR` to timing training time for machine learning models, record speed for requests hen running web-scraping codes or other situations that you need to keep records of time.

# Basic Usage

```{r}
library(timeR)
# Create a timer object(precision default to s)
my_timer <- createTimer()

# start timing for an event
my_timer$start("event one")

#start timing for another event
my_timer$start("event two")

# stop timing for the events
my_timer$stop("event one")
my_timer$stop("event two", comment = "my comment") # comment is optional

# retrieve the table for all recordings
getTimer(my_timer)


# or create a timer object and setting verbose to false
my_timer2 <- createTimer(verbose = F)

# toggle on/off verbose
my_timer$toggleVerbose()

# warnings will still be shown when verbose is turned off
my_timer$stop("event one")


```


# Comparison

Let's compare the workflow with and without `timeR` in the following scenario.

Our goal is to keep records of two events: **event 1** and **event 2**.  
We need to keep records of starting and stopping time for both events as well as calculate
the time difference between them. Also, we want to save those information to a data frame for later analysis.

## Timing Codes With `timeR`

```{r}
#initialize a timer object named mytimer: s, ms, us can be used as precision
mytimer <- createTimer(precision = "us")

# event 1
mytimer$start("event 1")
# do something here
Sys.sleep(1)
mytimer$stop("event 1")

#event 2
mytimer$start("event 2")
# do something here
Sys.sleep(1)
mytimer$stop("event 2",comment = "custom comment")

# print records
getTimer(mytimer)

# get attributes for selected events
mytimer$getStartTime("event 1")
mytimer$getStopTime("event 1")
mytimer$getTimeElapsed("event 1")
mytimer$getComment("event 1")
mytimer$getEvent("event 1")
```


## Timing Codes Conventionally

```{r}
#initalize a dataframe to store the information
timer_df = data.frame(matrix(ncol = 5, nrow = 0))
colnames(timer_df) <- c("event","start","end","timeElapsed","comment")
#event 1
t1 <- Sys.time()
# do something here
Sys.sleep(1)
t2 <- Sys.time()

timer_df <- rbind(timer_df,
                  data.frame(start = t1, 
                             end = t2, 
                             event = "event 1",
                             timeElapsed = t2-t1,
                             comment=NA))

#event 2
t1 <- Sys.time()
# do something here
Sys.sleep(1)
t2 <- Sys.time()

timer_df <- rbind(timer_df,
                  data.frame(start = t1, 
                             end = t2, 
                             event = "event 2",
                             timeElapsed = t2-t1,
                             comment = "custom comment"))

# print records
timer_df
```