Package 'walkboutr'

Description

This function takes a data frame of activity counts and adds a column of time stamps in POSIXct format. The time stamps start at "2012-04-07 00:00:30" and increase by 30 seconds for each row of the data frame.

Usage

add_date_and_format(counts)

Arguments

Value

a data frame with time stamps added in POSIXct format

Description

Assign Epoch Start Time

Usage

assign_epoch_start_time(gps_data, epoch_length)

Arguments

Details

Selects the closest 30 second increment to assign epoch start time and takes the GPS coordinates associated with the latest time if there are multiple GPS data points in a given 30 second increment. This function returns a data frame of GPS data with a column of epoch times.

Value

A data frame of GPS data with an additional column indicating epoch start time

Description

Collate Arguments This function collates user-provided arguments with pre-defined parameters and constants.

Usage

collate_arguments(..., collated_arguments = NULL)

Arguments

Value

A list of all arguments, including both pre-defined parameters and constants and any user-provided arguments.

Description

List of Constants non_wearing_min_threshold_epochs Number of consecutive epochs with activity counts of 0 that constitute a non_wearing period. min_wearing_hours_per_day Minimum number of hours in a day an individual must wear an accelerometer for the day to be considered complete. min_gps_obs_within_bout Minimum number of GPS observations within a bout for that bout to be considered to have complete GPS data. min_gps_coverage_ratio Minimum ratio of data points with versus without GPS data for the bout to be considered to have complete GPS data. dwellbout_radii_quantile Threshold for outliering GPS data points - any data points above the 95th percentile are outliered. max_dwellbout_radii_ft Maximum radius, in feet, of a bounding circle that would be considered a dwell bout (rather than a potential walk bout). min_dwellbout_obs Minimum number of observations to consider something a potential dwell bout. max_walking_cpe Maxiumum CPE value before the accelerometer is considered to be picking up on an activity other than walking. min_walking_speed_km_h Minimum speed considered walking. max_walking_speed_km_h Maximum speed considered walking.

Usage

constants

Format

An object of class list of length 10.

Description

This function evaluates the completeness of GPS data for each walking bout. For each bout, it checks if the number of valid GPS records (with speed, latitude, and longitude data) is greater than a specified threshold, and if the ratio of valid GPS records to total records is greater than a specified minimum. If both of these conditions are met, the function considers the GPS data for the bout to be complete. The function also calculates the median speed for each bout.

Usage

evaluate_gps_completeness(
  walk_bouts,
  min_gps_obs_within_bout,
  min_gps_coverage_ratio
)

Arguments

Value

A data frame containing information about the GPS completeness and median speed for each bout.

Description

Given accelerometer bout data, this function generates bout categories, which includes dwell bouts, non-walk bouts that are either too slow, too fast, or too vigorous, and bouts with an unknown lack of GPS data.

Usage

generate_bout_category(
  walk_bouts,
  bout_radii,
  gps_completeness,
  max_dwellbout_radii_ft,
  max_walking_cpe,
  min_walking_speed_km_h,
  max_walking_speed_km_h
)

Arguments

Details

The function uses the bout information for walking bouts, bout radii information, and GPS data completeness information to generate the bout categories.

The function first generates dwell bouts by joining the bout radii information and GPS data completeness information on the bout column, and then filters out the rows that have bout values that are missing using the filter function. Then, it calculates the dwell bout values as TRUE if the complete_gps column is TRUE and the bout_radius column is less than max_dwellbout_radii_ft. The resulting data frame only contains the bout and dwell_bout columns. The function then joins the resulting data frame with the walking bout data frame using the bout column. Then, for the non-walk bouts, the function calculates whether they are too vigorous, too slow, or too fast. For the non-walk bouts that are too vigorous, the function calculates the mean activity_counts for each bout, and then sets the non_walk_too_vigorous value as TRUE if the mean activity_counts value is greater than max_walking_cpe. For the non-walk bouts that are too slow or too fast, the function calculates the median speed for each bout, and then sets the non_walk_slow or non_walk_fast value as TRUE if the median speed value is less than min_walking_speed_km_h or greater than max_walking_speed_km_h, respectively. Finally, the function generates a non_walk_incomplete_gps value as TRUE if the complete_gps value is FALSE for the bout. The resulting data frame contains the following columns: bout, dwell_bout (T/F), non_walk_too_vigorous (T/F), non_walk_slow (T/F), non_walk_fast (T/F), non_walk_incomplete_gps (T/F).

Value

a data frame with the following columns: bout, dwell_bout (T/F), non_walk_too_vigorous (T/F), non_walk_slow (T/F), non_walk_fast (T/F), non_walk_incomplete_gps (T/F)

Description

This function generates a plot of accelerometry counts and GPS radius for a specific bout.

Usage

generate_bout_plot(
  accelerometry_counts,
  gps_data,
  bout_number,
  leading_minutes = 8,
  trailing_minutes = 12,
  gps_target_size = 0.25,
  ...,
  collated_arguments = NULL
)

Arguments

Value

A ggplot object representing the bout plot.

Description

This function generates a bounding circle radius for each walking bout identified in the input data. The bounding circle is defined as the smallest circle that fully contains all GPS locations observed during a walking bout.

Usage

generate_bout_radius(walk_bouts, dwellbout_radii_quantile)

Arguments

Value

A data frame containing the bout identifier and the radius of the bounding circle for each walking bout.

Description

Generate a dataset with date-time, speed, and latitude and longitude of someone moving through space on a walk in Seattle

Usage

generate_gps_data(
  start_lat,
  start_long,
  start_time,
  n_epochs = 110,
  time_interval = 30,
  seed = 1234
)

Arguments

Value

A data frame with four columns: "timestamp", "lat", "lon", and "speed".

Description

This function generates a data frame containing GPS data for a walking activity in Seattle, WA on April 7th, 2012. It calls the function generate_gps_data to create a series of GPS locations and speeds. The resulting data frame has columns for time, latitude, longitude, and speed.

Usage

generate_walking_in_seattle_gps_data(start_lat, start_long, start_time)

Arguments

Value

A data frame with columns time, latitude, longitude, speed

Description

Identify Bouts:

Usage

identify_bouts(
  accelerometry_counts,
  maximum_number_consec_inactive_epochs_in_bout,
  active_counts_per_epoch_min,
  minimum_bout_length
)

Arguments

Details

This function partitions the accelerometry data into bouts of activity and non-bouts by first identifying all epochs that are definitely not part of bouts. Then, it uses run length encoding to partition the data into potential bouts and non-bouts, and labels each potential bout as a bout or non-bout based on whether it meets the criteria for bout length and the number of consecutive inactive epochs allowed. Finally, the function adds a new column to the input data frame accelerometry_counts named bout that indicates whether each epoch is part of a bout (1) or not (0).

Value

A data frame with the same columns as the input data frame accelerometry_counts, but with a new column named bout that indicates whether each epoch is part of a bout (in which case it gets a bout number assigned) or not (0)

Description

Identify complete wearing days This function identifies complete days based on accelerometry data by calculating the total number of epochs worn per day and comparing it to the minimum number of wearing epochs per day required to consider a day complete.

Usage

identify_complete_days(
  accelerometry_counts,
  min_wearing_hours_per_day,
  epoch_length,
  local_time_zone
)

Arguments

Value

A data frame containing accelerometer counts, non-wearing epochs, and a binary variable indicating if the day is complete or not.

Description

Identify non-wearing periods: This function identifies non-wearing periods in accelerometry data based on a threshold of consecutive epochs with activity counts of 0.

Usage

identify_non_wearing_periods(
  accelerometry_counts,
  non_wearing_min_threshold_epochs
)

Arguments

Details

Identify periods where the accelerometer is not being worn based on the activity counts and a minimum threshold value.

Value

a data frame with the same columns as the input data frame accelerometry_counts, but with a new column named non_wearing that indicates whether the individual was wearing their accelerometer during a given period.

Description

This function identifies walking bouts in GPS and accelerometry data. It processes the GPS data and accelerometry counts to create walk bouts.

Usage

identify_walk_bouts_in_gps_and_accelerometry_data(
  gps_data,
  accelerometry_counts,
  ...,
  collated_arguments = NULL
)

Arguments

Value

A data frame containing identified walk bouts

Description

This function generates a list of activity epochs with specified minimum active counts per epoch, minimum bout length, maximum number of consecutive inactive epochs in a bout, minimum non-wearing length, and minimum complete day length.

Usage

make_active_period(
  length = 1,
  is_bout = TRUE,
  non_wearing = FALSE,
  complete_day = FALSE
)

Arguments

Value

A list of activity epochs

Description

This function creates a data frame with activity counts for a full day bout. A full day bout is defined as an uninterrupted period of activity with a length of at least min_complete_day. The function calls the make_non_bout_window(), make_smallest_bout_window(), and make_smallest_complete_day_activity() functions to generate the activity counts for the non-bout window, smallest bout window, and smallest complete day activity, respectively.

Usage

make_full_day_bout()

Value

A data frame with activity counts for a full day bout

Description

This function creates a data frame with activity counts for a full day bout. A full day bout is defined as an uninterrupted period of activity with a length of at least min_complete_day. The function calls the make_non_bout_window(), make_smallest_bout_window(), and make_smallest_complete_day_activity() functions to generate the activity counts for the non-bout window, smallest bout window, and smallest complete day activity, respectively.

Usage

make_full_day_bout_without_metadata()

Value

A data frame with activity counts for a full day bout without metadata

Description

This function combines accelerometer and GPS data to create a data frame of walking bouts. It generates a full day of activity with bouts of minimum and non-bout periods, and GPS data for walking in Seattle. The accelerometer data is processed into bouts using the process_accelerometry_counts_into_bouts function. The GPS data is processed into epochs using the process_gps_data_into_gps_epochs function.

Usage

make_full_walk_bout_df()

Value

A data frame of walking bouts with GPS data

Examples

make_full_walk_bout_df()

Description

This function creates an inactive period with a given length.

Usage

make_inactive_period(
  length = 1,
  is_bout = FALSE,
  non_wearing = FALSE,
  complete_day = FALSE
)

Arguments

Value

A data frame with columns activity_counts, bout, non_wearing, and complete_day, where activity_counts is set to 0 for the entire length, and bout, non_wearing, and complete_day are set according to the input values.

Description

This function creates a non-bout window, which is a period of inactivity that is not long enough to be considered as an inactive bout.

Usage

make_non_bout_window(maximum_number_consec_inactive_epochs_in_bout = 3)

Arguments

Value

a data frame with columns "activity_counts", "bout", "non_wearing", "complete_day"

Examples

make_non_bout_window()

Description

Generates a dataset representing the smallest bout, consisting of a sequence of inactive periods followed by the smallest active period.

Usage

make_smallest_bout()

Value

A data frame containing the activity counts and bout information for the smallest bout.

Examples

make_smallest_bout()

Description

This function creates an active period of minimum length defined by the parameter minimum_bout_length.

Usage

make_smallest_bout_window(
  minimum_bout_length = 10,
  is_bout = TRUE,
  non_wearing = FALSE,
  complete_day = FALSE
)

Arguments

Value

A data.frame with columns activity_counts, bout, non_wearing, and complete_day representing the smallest bout window.

Description

This function generates a sequence of accelerometer counts representing the smallest bout with the largest inactive period. The length of the inactive period is determined by the value of maximum_number_consec_inactive_epochs_in_bout variable.

Usage

make_smallest_bout_with_largest_inactive_period(
  maximum_number_consec_inactive_epochs_in_bout = 3
)

Arguments

Value

A data frame with columns activity_counts and time, representing the accelerometer counts and the corresponding time stamps.

Examples

make_smallest_bout_with_largest_inactive_period()

Description

This function creates a dataset consisting of the smallest bout and the smallest non-wearing period. The bout length, non-wearing period length, and epoch length are defined in the global variables: minimum_bout_length, maximum_number_consec_inactive_epochs_in_bout, and min_non_wearing_length, respectively.

Usage

make_smallest_bout_with_smallest_non_wearing_period()

Value

A data frame with columns for activity counts and date-time stamps.

Examples

make_smallest_bout_with_smallest_non_wearing_period()

Description

This function creates the smallest bout window without the metadata columns. It calls the make_smallest_bout function and then removes the columns "non_wearing", "complete_day", and "bout" using dplyr::select.

Usage

make_smallest_bout_without_metadata()

Value

A data frame containing the smallest bout window without metadata.

Examples

make_smallest_bout_without_metadata()

Description

This function generates an activity sequence for a complete day with a minimal activity count.

Usage

make_smallest_complete_day_activity(min_complete_day = 8602)

Arguments

Value

An activity sequence data frame with minimum activity counts for a complete day.

Examples

make_smallest_complete_day_activity()

Description

Create an inactive period that represents the smallest non-wearing window. This function uses the make_inactive_period() function to create the non-wearing window.

Usage

make_smallest_nonwearing_window(min_non_wearing_length = 20 * 2)

Arguments

Value

An inactive period data frame that represents the smallest non-wearing window.

Examples

make_smallest_nonwearing_window()

Description

Given a current location (latitude and longitude), speed, direction (in radians), and time elapsed (in seconds), this function calculates the next latitude and longitude. The calculations are based on the assumption of a constant speed and direction during the elapsed time.

Usage

next_lat_long(latitude, longitude, speed, direction, dt)

Arguments

Value

A numeric vector of length 2 containing the next latitude and longitude in decimal degrees.

Description

Outlier GPS data points This function identifies outlier GPS points for the bout radius calculation from a given set of latitude and longitude coordinates.

Usage

outlier_gps_points(lat_long, dwellbout_radii_quantile)

Arguments

Value

A data frame containing the latitude and longitude coordinates for the non-outlier GPS points.

Description

List of Parameters epoch_length The duration of an epoch in seconds. active_counts_per_epoch_min Minimum accelerometer counts for an epoch to be considered active (vs. inactive). minimum_bout_length Minimum number of epochs for a period of activity to be considered as a potential bout. local_time_zone Local time zone of the data - data come in and are returned in UTC, but local time zone is used to compute complete_days. maximum_number_consec_inactive_epochs_in_bout Number of consecutive epochs that can be labeled as inactive during a bout without ending the bout.

Usage

parameters

Format

An object of class list of length 5.

Description

This function processes accelerometry counts into bouts of activity and returns those bouts as well as flags for whether the individual was wearing their device and if the wearing day can be considered complete

Usage

process_accelerometry_counts_into_bouts(
  accelerometry_counts,
  ...,
  collated_arguments = NULL
)

Arguments

Details

The input schema for the accelerometry data is time and activity_counts.

• time should be a column in date-time format, in the UTC time zone, with no null values.

• activity_counts should be a positive numeric column with no null values.

This function processes accelerometry counts into bouts of activity. The function first validates the input data in the first step. In the second step, the function identifies bouts of activity based on a specified minimum number of active counts per epoch, a maximum number of consecutive inactive epochs allowed within a bout, and a minimum bout length. In the third step, the function identifies non-wearing periods based on a specified threshold of consecutive epochs with 0 activity counts. In the fourth step, the function identifies complete days of wearing the accelerometer based on a specified minimum number of hours of wearing and the epoch length. The returned list includes information about each complete day, including the start and end times of each day, the duration of the day in seconds, the number of epochs, the total number of cpm for the day, and the bouts of activity within the day.

Value

A list of processed data frames containing identified walk bouts, non-wearing periods, and complete days, based on the provided accelerometry counts and processing parameters.

Description

This function processes bouts and GPS epochs into walk bouts. It uses a set of parameters and constants to determine whether an epoch is active or inactive, the minimum number of epochs for a period of activity to be considered as a potential bout, the local time zone of the data, and other relevant information. It takes in two data frames, "bouts" and "gps_epochs", and returns a processed data frame, "walk_bouts", with added columns "bout", "bout_radius", "bout_category", "complete_days", "non_wearing", and "speed".#'

Usage

process_bouts_and_gps_epochs_into_walkbouts(
  bouts,
  gps_epochs,
  ...,
  collated_arguments = NULL
)

Arguments

Details

The function first collates the arguments passed to it with the collate_arguments() function. It then merges "gps_epochs" and "bouts" data frames by "time" column, and orders the resulting data frame by "time". Then, it generates the "bout_radius" using the generate_bout_radius() function, which calculates the radius of a bounding circle that would be considered a dwell bout. Next, the function evaluates the completeness of GPS data using the evaluate_gps_completeness() function, which determines the number of GPS observations within a bout and the ratio of data points with versus without GPS data. Finally, the function generates the "bout_category" using the generate_bout_category() function, which determines whether a bout is a walk bout or a dwell bout, and calculates the complete days, non-wearing periods, and speed. The function categorizes bouts into the following categories:

• dwell bout

• non-walk too vigorous

• non-walk too slow

• non-walk too fast

• unknown lack of gps

NOTE: If there are multiple GPS points associated with a given epoch interval, we use the latest possible GPS data point within that epoch. As such, median walking speed is calculated for only the latest available GPS data point in each epoch.

NOTE: The median speed is calculated using only the GPS data points that remain after GPS data processing. All GPS data points that are outliered for the calculation of a bout radius, are, however, included in the assessment of GPS completeness as they are outliers but are still present GPS data points.

NOTE: Outliered data points are excluded from the radius calculation but are included in subsequent functions that assess GPS completeness. They are also returned from these functions with the original data and all new variables.

Value

a processed data frame, "walk_bouts", with added columns "bout", "bout_radius", "bout_category", "complete_days", "non_wearing", and "speed"#'

Description

The input schema for the accelerometry data is time, latitude, longitude, and speed.

• time should be a column in date-time format, in the UTC time zone, with no null values.

• latitude should be a numeric, non-null latitude coordinate between -90 and 90

• longitude should be a numeric, non-null longitude coordinate between -180 and 180

• speed should be a numeric, non-null value in kilometers per hour

Usage

process_gps_data_into_gps_epochs(gps_data, ..., collated_arguments = NULL)

Arguments

Details

This function processes GPS data into GPS epochs, with each epoch having a duration specified by epoch_length.

Value

A data frame with columns latitude, longitude, time, and speed, where time is now the nearest epoch start time

Description

A function that runs a normal run length encoding and adds some extra variables for use in calculations.

Usage

run_length_encode(x)

Arguments

Value

a data.frame with columns for lengths, values, end, and begin

Description

Summarize walking bouts: This function summarizes walking bouts and calculates the median speed, complete day, non-wearing, bout start, and duration of each bout.

Usage

summarize_walk_bouts(walk_bouts, ..., collated_arguments = NULL)

Arguments

Value

A data frame summarizing identified walk bouts

Description

The input schema for the accelerometry data is time and activity_counts.

• time should be a column in date-time format, in the UTC time zone, with no null values.

• activity_counts should be a positive numeric column with no null values.

Usage

validate_accelerometry_data(accelerometry_counts)

Arguments

Details

This function checks the schema of the accelerometry input data and raises an error if any schema constraints are violated.

The following schema validations are performed on the input data:

• The input data must contain two columns, named time and activity_counts.

• The time column must be in date-time format, in the UTC time zone, with no null values.

• The activity_counts column must be a positive numeric column with no null values.

Value

This function does not return anything. It throws an error if the accelerometry data fails any of the validation checks.

Examples

# Example usage:
data <- data.frame(
  time = seq(
    as.POSIXct("2021-01-01 00:00:00", tz = "UTC"),
    as.POSIXct("2021-01-01 23:59:59", tz = "UTC"),
    by = "5 mins"
  )) %>%
  dplyr::mutate(activity_counts = sample(0:100, length(time), replace = TRUE))
validate_accelerometry_data(data)

Description

This function validates GPS data for required variables, correct variable class, and correct data range.

Usage

validate_gps_data(gps_data)

Arguments

Value

This function does not return anything. It throws an error if the GPS data fails any of the validation checks.