clockplot

In clockplot: Plot Event Times on a 24-Hour Clock

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.

Getting started

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

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.

head(smsclock)

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

clock_chart(smsclock, time, Col = "green")

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

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.

head(bdquake)

The code without added components.

clock_chart_col(bdquake, time = hms, crit = mag)

Let us modify it.

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.

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

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.

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 and a small part (100 rows) extracted. To see the modified data, visit this link.

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")

Qualitative variable

Here we use the built-in smsclock data set.

head(smsclock, 4)

Now let us plot times with respect to message title.

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.

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.

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

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.

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 the repository and follow the website linked to see all the available functions (Reference menu)

clockplot documentation built on Sept. 14, 2025, 1:07 a.m.