Package {actiplot}

Type: Package
Title: Plotting Minute-Level Activity Data
Version: 0.1.0
Description: Provides 'ggplot2' plots for minute-level activity data, including step counts and activity counts. Time series can be displayed over the full recording period or aligned by time of day and faceted into one row per date. Includes example activity data described by Chadwell et al. (2019) <doi:10.1038/s41597-019-0211-6>.
License: GPL-3
Depends: R (≥ 3.5)
Suggests: testthat (≥ 3.0.0), covr, knitr, rmarkdown, dplyr, vdiffr
Encoding: UTF-8
LazyData: true
Config/roxygen2/version: 8.0.0
URL: https://github.com/jhuwit/actiplot, https://jhuwit.github.io/actiplot/
BugReports: https://github.com/jhuwit/actiplot/issues
Imports: actibase (≥ 0.6.0), ggplot2, hms, rlang
Config/testthat/edition: 3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-10-07 03:32:09 UTC; johnmuschelli
Author: John Muschelli ORCID iD [aut, cre]
Maintainer: John Muschelli <muschellij2@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-16 13:20:32 UTC

actiplot: Plotting Minute-Level Activity Data

Description

Provides 'ggplot2' plots for minute-level activity data, including step counts and activity counts. Time series can be displayed over the full recording period or aligned by time of day and faceted into one row per date. Includes example activity data described by Chadwell et al. (2019) doi:10.1038/s41597-019-0211-6.

Author(s)

Maintainer: John Muschelli muschellij2@gmail.com (ORCID)

Authors:

See Also

Useful links:

Minute-level accelerometer counts

Description

A seven-day example of minute-level accelerometer data. It contains a timestamp, counts for each accelerometer axis, vector-magnitude counts, log-transformed counts, and a wear indicator. The data are suitable for the examples in acti_plot_time(), acti_plot_day(), and acti_plot_heatmap().

Usage

acti_minute_data

Format

A tibble with 10,080 rows and 7 variables:

time

Timestamp of the minute, as POSIXct.

axis1, axis2, axis3

Axis-specific activity counts.

counts

Vector-magnitude activity counts.

counts_log10

Log10-transformed vector-magnitude counts.

wear

Whether the minute was classified as wear time.

Details

The original study recorded seven days of wrist-worn ActiGraph activity from 20 myoelectric prosthesis users and 20 anatomically intact adults. This package data object is a processed minute-level recording drawn from that collection.

Source

The Figshare collection from Chadwell (2019) https://doi.org/10.6084/m9.figshare.c.4457855.

References

Chadwell, A., Kenney, L., Granat, M., Thies, S., Galpin, A., & Head, J. (2019). Upper limb activity of twenty myoelectric prosthesis users and twenty healthy anatomically intact adults. Scientific Data, 6, 199. https://doi.org/10.1038/s41597-019-0211-6

Plot an activity actogram

Description

Displays minute-level activity as a date-by-time heat map using actibase day indexing and time-of-day conversion.

Usage

acti_plot_actogram(data, value, time = time, breaks = "4 hours", ...)

Arguments

data

Minute-level activity data.

value

Activity column, supplied unquoted or as a string.

time

Timestamp column.

breaks

Time-of-day axis break interval.

...

Arguments passed to ggplot2::geom_tile().

Value

A ggplot object.

Plot a minute-of-day activity profile

Description

Plot a minute-of-day activity profile

Usage

acti_plot_minute_profile(
  data,
  value,
  time = time,
  summary = c("mean", "median"),
  ...
)

Arguments

data

Minute-level activity data.

value

Activity column, supplied unquoted or as a string.

time

Timestamp column.

summary

Either "mean" or "median".

...

Arguments passed to ggplot2::geom_tile().

Value

A ggplot object.

Plot minute-level activity over time

Description

acti_plot_time() draws a time-series plot for a minute-level activity measure, such as steps or activity counts. acti_plot_day() aligns the data by time of day and places each date in its own facet row. acti_plot_heatmap() provides the same date-by-time layout as a heat map.

Usage

acti_plot_time(
  data,
  value,
  time = time,
  breaks = NULL,
  connector = c("linear", "step", "line"),
  x_axis = c("default", "12 hours", "midnight"),
  ...
)

acti_plot_day(
  data,
  value,
  time = time,
  breaks = "4 hours",
  connector = c("linear", "step", "line"),
  facet = c("date", "month-day", "day"),
  ...
)

acti_plot_heatmap(data, value, time = time, breaks = "4 hours", ...)

Arguments

data

A data frame containing a timestamp and an activity measure.

value

The activity-measure column, supplied unquoted or as a string. For example, steps or "counts".

time

The timestamp column, supplied unquoted or as a string. It is time by default.

breaks

A single duration such as "1 hour", "4 hours", or "15 mins". It controls x-axis spacing. Use NULL for ggplot2's default on the full-time plot or no specified breaks on aligned plots.

connector

Should a geom_step (step) or geom_line (linear/line) be used to connect points?

x_axis

The x-axis labelling scheme for acti_plot_time(). Use "default" to use breaks or ggplot2's default; "12 hours" to show a date and 12-hour clock label every 12 hours; or "midnight" to label each date only at midnight. The latter two options set their own breaks.

...

Additional arguments passed to the primary geom.

facet

The facet labels for acti_plot_day(): "date" for the full date, "month-day" for a date without the year, or "day" for days since the first recording day (as calculated by actibase::acti_separate_times()).

Details

Data are prepared with actibase::acti_separate_times(), which recognizes the timestamp conventions used by activerse packages and adds date and time-of-day variables.

Value

A ggplot object.

Examples

# The first two hours of the packaged minute-level data.
activity <- acti_minute_data[seq_len(120), ]

acti_plot_time(activity, counts, breaks = "1 hour")
acti_plot_time(acti_minute_data, counts, x_axis = "12 hours")
acti_plot_time(acti_minute_data, counts, x_axis = "midnight")
acti_plot_day(activity, "counts", breaks = "1 hour")
acti_plot_heatmap(activity, counts, breaks = "1 hour")

Add activity marks along a datetime axis

Description

Add activity marks along a datetime axis

Usage

geom_activity_rug(data, time = "time", ...)

Arguments

data

Data containing a timestamp column.

time

Timestamp column name.

...

Arguments passed to ggplot2::geom_rug().

Value

A ggplot2 layer.

Add conventional daily boundaries

Description

Add conventional daily boundaries

Usage

geom_day_boundary(boundary = c("midnight", "noon"), ...)

Arguments

boundary

One of midnight or noon.

...

Arguments passed to geom_time_vline().

Value

A ggplot2 layer.

Add timestamped episode intervals

Description

Draws one or more timestamped intervals behind an activity trace. The input data must contain POSIXct start and end columns. This is the common layer underpinning sleep, wear, and activity-bout annotations.

Usage

geom_episode(data, start = "start", end = "end", ...)

Arguments

data

An interval data frame.

start, end

Names of POSIXct start and end columns.

...

Arguments passed to ggplot2::geom_rect().

Value

A ggplot2 layer.

Add sleep-window intervals

Description

Add sleep-window intervals

Usage

geom_sleep_window(data, start = "start", end = "end", ...)

Arguments

data

An interval data frame.

start, end

Names of POSIXct start and end columns.

...

Arguments passed to ggplot2::geom_rect().

Value

A ggplot2 layer.

Highlight activity observations beyond a threshold

Description

Adds translucent vertical bands for timestamped observations above or below a threshold. It intentionally does not merge observations into bouts; use an explicit interval table with geom_episode() when episode definitions matter.

Usage

geom_threshold_band(
  data,
  value,
  threshold,
  direction = c("above", "below"),
  time = "time",
  ...
)

Arguments

data

A data frame with timestamp and numeric activity columns.

value

Numeric activity column name.

threshold

Numeric threshold.

direction

Whether to highlight values above or below the threshold.

time

Timestamp column name.

...

Arguments passed to ggplot2::geom_rect().

Value

A ggplot2 layer.

Add a time-aware vertical reference line

Description

A convenience layer for ggplot2::geom_vline() that converts time inputs to actiplot time scales. A time of day such as "12:00" is drawn in every daily facet. A complete date-time is drawn at that instant on a full-time plot and only on its matching date facet in an aligned day plot.

Usage

geom_time_vline(xintercept, timezone = NULL, check_timezone = FALSE, ...)

Arguments

xintercept

A POSIXct date-time, an ISO-like date-time character string, or a time-of-day character string such as "08:30".

timezone

Time zone used to parse date-time character values. The timestamp time zone in the plot data is used when NULL.

check_timezone

If TRUE, date-time character values require an explicit timezone.

...

Arguments passed to ggplot2::geom_vline().

Value

A ggplot2 layer.

Examples

acti_plot_day(acti_minute_data, counts) +
  geom_time_vline("12:00", linetype = "dashed")

acti_plot_time(acti_minute_data, counts) +
  geom_time_vline("2017-06-05 09:30:00", timezone = "GMT")

Add wear intervals

Description

Add wear intervals

Usage

geom_wear(data, start = "start", end = "end", ...)

Arguments

data

An interval data frame.

start, end

Names of POSIXct start and end columns.

...

Arguments passed to ggplot2::geom_rect().

Value

A ggplot2 layer.