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

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

The package `clockplot` is used to generate clock charts showing event times 
on a 24-hour clock. Additionally it helps you make a day chart, week chart, 
or month chart, or plan events in those periods.

The main focus is on the `clock_chart*()` functions. These allow you to plot event times on a 24-hour clock. 

<!--
<span style = "color:Orange;">⚠</span> The plots shown here may not produce the
expected output due to the behavior of Rmarkdown. To see the actual appearance,
[visit this link](https://github.com/mahmudstat/clockplot) or run the codes given. 
-->

## Getting started

After installing the package, load it to use the available functions. 

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

## Types of Charts

The clockpolot offers three types of plot

1. Clock charts
2. Cyclic charts
3. Period planner

The first type shows event times on a 24 hour clock. The times can be 
arbitrary in the formats `HH:MM:SS`, `HH:MM` or even `H:M` (such as `9:3`),
and not necessarily specific hours at all. 


The second type allows you to show values during a certain duration (day, week, month, and year). There is a generic function `cyclic_chart()` for arbitrary period, while
there charts specially made for specific period (day, week, year etc.)

Finally, the third one can help you make a plan in a certain period (day, week, month, and year), presenting tasks against period. 

## Clock Charts

Below is a summary of each `clock_chart*()` function use case. 

|    **function**   | **Purpose**                                                                                                           |
|:-----------------:|-----------------------------------------------------------------------------------------------------------------------|
|   `clock_chart()`   | To plot a basic clock chart, showing event times on clock, and to optionally choose a color for the hands             |
| `clock_chart_col()` | To color the plot by a quantitative variable, and optionally to change size of points by the same or another variable |
| `clock_chart_qnt()` | To modify the length of the hands by a quantitative variable, along with all the options of  `clock_chart_col()`      |
|  `clock_chart_qlt`  | To use a qualitative variable as the criteria                                                                         |

Now Let's see each in greater detail

The examples use built-in data sets. The allowed time formats for these family
of charts are `HH:MM:SS`, `HH:MM` or even `H:M` (such as `12;30:09` or `9:3`). 

### Basic Clock Chart

This is the simplest clock chart; the hands are
neither colored nor length modified by a criteria. 

We are going to use the `smsclock` data set. Let us take a look on it. 

```{r}
head(smsclock)
```

The necessary code to produce a chart is simply the following:

```{r eval=FALSE}
clock_chart(smsclock, time, Col = "green")
```

The code produces a `ggplot2` object, so we can add (`+`) extra components 
to make it more informative. 


```{r clock-chart, fig.align = 'center', fig.height=6, fig.width=6}
p1 <- clock_chart(smsclock, time, Col = "green")
p1 + ggplot2::labs(title = "SMS Receiving Times")
```

The chart shows when the messages are sent. The largest break is seen during 
the night time (approximately 11 PM to 6 AM). Only one (01) message is received
from 2:30 PM to 4:30 PM. Other than a few intermissions which are worth around
30 minutes, messages are received round the clock. 

### Colored Clock Chart

In the previous chart, we colored the hands by an arbitrary color. We may want
to color it by a `numeric` variable. `clock_chart_col()` exactly does this. 

We may use `bdquake` data set for this. 

```{r}
head(bdquake)
```

The code without added components. 

```{r eval=FALSE}
clock_chart_col(bdquake, time = hms, crit = mag)
```

Let us modify it.

```{r clock-chart-col, fig.align = 'center', fig.height=6, fig.width=6}
p <- clock_chart_col(bdquake, time = hms, crit = mag)
p + ggplot2::labs(size = "Magnitude", title = "Earthquakes in Bangladesh since 2023")
```

It would be great if we could modify the length of the hands as well. We see 
that in the next chart. 

### Chart with Modified and Colored Hands

We now use `clock_chart_qnt()`. We color the chart magnitude and change 
length by the depth of the earthquake hypocenter.

```{r eval=FALSE}
clock_chart_qnt(
  data = bdquake, time = hms, len = depth,
  Col = mag, high = "red", low = "blue"
)
```

The `high` and `low` color names can be vice versa or other colors, depending on the context. To use a single color for all lines, use same value for `high` and `low`

**The custom plot**

```{r clock-chart-qnt, fig.align = 'center', fig.height=6, fig.width=6}
p1 <- clock_chart_qnt(
  data = bdquake, time = hms, len = depth,
  Col = mag, high = "red", low = "blue"
)
p1 + ggplot2::labs(
  color = "Depth", size = "Magnitude",
  title = "Earthquakes in Bangladesh since 2023"
)
```

If you do not have two variables for `len` and `Col`, use one single variable 
for both options. 

As is evident from the chart, the size of the points represents the magnitude 
of the earthquakes, while the color and the length of the hands stand for 
depth of the earthquakes. 

The plot shows that the quakes are roughly randomly distributed with respect 
to time. Most earthquakes occurred between around 1 PM to around 5 PM. Two 
of the biggest gaps can be seen between 5 PM to 9 PM (a gap amounting to 4 
hours) and 10 PM to quarter after 2 AM (almost 4.25 hours). 

If we want a single variable to determine color and length, we can use the 
following method to properly show the legend. The plot code is shown
as a comment. To see the result, uncomment and run. 

```{r, eval=FALSE}
labs(size = "TITLE", color = "")
# clock_chart_qnt(acdt, time = Time, len = Temperature.F., Col = Temperature.F.)+labs(size = "Temperature", color = "")
```

#### US Accidents plot

The data is taken from 
[Kaggle](https://www.kaggle.com/datasets/sobhanmoosavi/us-accidents)
and a small part (100 rows) extracted. To see the modified data, visit 
[this link](https://raw.githubusercontent.com/mahmudstat/open-analysis/main/data/usacc.csv). 

```{r, clock-chart-acdt, fig.align = 'center', fig.height=6, fig.width=6}
acdt <- read.csv("https://raw.githubusercontent.com/mahmudstat/open-analysis/main/data/usacc.csv")
clock_chart_qnt(acdt, time = Time, len = Humidity..., Col = Temperature.F.) +
  ggplot2::labs(size = "Humidity", color = "Temperature")
```

<!--

### Modified Length

Although there is another function `clock_chart_len()` to modify length of the
clock hands, this is rarely useful. Here you can use a variable to modify the
length by and an argument `Col` to choose a specific color for the hands. 

```{r eval=FALSE, clock-chart-len, fig.align = 'center', fig.height=6, fig.width=6}
p1 <- clock_chart_len(data = bdquake, time = hms, crit = depth)
p1 + ggplot2::labs(title = "Earthquakes in Bangladesh since 2023")
```


#### Choosing between `clock_chart_len()` and `clock_chart_qnt()`

If we have a column which represents length, distance, or an amount, or 
something similar, we may go ahead and use `clock_chart_qnt()`, otherwise, when
the length does not meaningfully present a variable, we can confine ourselves
to `clock_chart_len()`. 
-->

### Qualitative variable

Here we use the built-in `smsclock` data set. 

```{r}
head(smsclock, 4)
```

Now let us plot times with respect to message title. 

```{r clock-chart-qlt, fig.align = 'center', fig.height=6, fig.width=6}
clock_chart_qlt(smsclock, time = time, crit = Title) +
  ggplot2::labs(color = "Sender", title = "SMS's Received throughout the Day")
```

This makes it convenient to see which types of messages were sent when. Certain 
types of messages, such as Supper_Offer, are always sent around the same time 
(4:30 PM to 6 PM). 
Other messages are spread throughout the day. Between 11 PM and 6 AM, no 
messages are received. 

We can also make use of the `facet_wrap()` function from the `ggplot2` package.

We can use the following to see the visual relationship between message 
Sender and the Day of the week. 

```{r eval=FALSE}
clock_chart_qlt(smsclock, time = time, crit = sender) + facet_wrap(~day)
```

Or we may be interested to see the association between message title and the 
time when they are sent. 

```{r eval=FALSE}
clock_chart_qlt(smsclock, time = time, crit = sender) + facet_wrap(~Title)
```

**Instructions from the beginning which args to use in labs.**

## Other Charts

#### Cyclic Chart

```{r, cyclic-chart, fig.align = 'center', fig.height=6, fig.width=6}
Col <- c("#0040ff", "#00bfff", "#8000ff")
cyclic_chart(bdtemp,
  Period = Month, Value = Temperature,
  crit = City, ColV = Col
)
```

Or we can also make day or week charts. 

```{r, dayc, fig.align = 'center', fig.height=6, fig.width=6}
value <- sample(15:30, 24, replace = TRUE)
day_chart(hvalue = value, high = "blue", low = "yellow", width = 0.8)
```

To see all the available functions, run `getNamespaceExports("clockplot")` and then use `?function_name` to know more about it and see and run examples. If you are connected to the internet, [you may visit](https://github.com/mahmudstat/clockplot) the repository and follow the website linked to see all the available functions (`Reference` menu)