Generate sequential day indices from ISO 8601 timestamps

Description

Converts a vector of ISO 8601 timestamps into sequential day indices (1, 2, 3, …), where each unique calendar date corresponds to a unique integer. This is useful for looping over or summarizing data by day when working with minute-level time series from wearables.

Usage

define_day_indices(ts)

Arguments

Value

An integer vector of the same length as 'ts', where each element gives the index of the day the timestamp belongs to. The first unique date encountered is assigned index '1', the second '2', and so on.

See Also

[as.POSIXct()], [as.Date()]

Examples

ts <- c("2024-06-26T23:45:00+0100",
        "2024-06-27T00:15:00+0100",
        "2024-06-27T14:30:00+0100")
define_day_indices(ts)
# Returns: c(1, 2, 2)

Calculate minutes and steps spent in cadence bands

Description

Splits a minute-based vector of cadence values (steps per minute) into predefined bands and reports both:

• the number of minutes spent in each band

• the number of steps accumulated in each band

Usage

get_cadence_bands(x, bands = c(0, 1, 20, 40, 60, 80, 100, 120, Inf))

Arguments

Value

A list with three elements:

minutes

Named numeric vector with minutes spent in each band.

steps

Named numeric vector with steps accumulated in each band.

names

Character vector of variable names in the format "CAD_band_<lower>_<upper>_spm".

Examples

# Simulate 1 day of cadence values (1440 minutes)
set.seed(123)
cad <- sample(0:150, size = 1440, replace = TRUE)

out <- get_cadence_bands(cad)
out$minutes  # minutes in each band
out$steps    # steps in each band

Calculate cadence peak metrics

Description

Cadence peaks represent the mean steps-per-minute (spm) achieved during the highest-activity minutes of a day. For example, the 30-minute cadence peak is the average cadence across the 30 highest cadence minutes of that day, regardless of whether they occur consecutively.

This function calculates cadence peaks for user-specified intervals and also reports how many of the minutes within each interval contain zero steps (useful for quality checks).

Usage

get_cadence_peaks(x, peaks = c(1, 30, 60))

Arguments

Details

Cadence peaks are calculated by:

1. Sorting all minute-level cadence values in descending order.

2. Selecting the top *n* minutes, where *n* = peak length.

3. Averaging those values to compute the cadence peak.

4. Counting how many of those top *n* minutes contain zero steps.

Value

A list with two elements:

values

Numeric vector with cadence peak values (spm) followed by the corresponding counts of zero-minute values within each peak window.

names

Character vector of variable names corresponding to the 'values', in the format:

• '"CAD_pk<peak>_spm"' for the cadence peak value

• '"CAD_nZeroes_pk<peak>"' for the number of zero minutes

See Also

[get_cadence_bands()]

Examples

# Simulate one day of cadence values (1440 minutes)
set.seed(123)
cad <- sample(0:150, size = 1440, replace = TRUE)

# Calculate 1-min, 30-min, and 60-min cadence peaks
get_cadence_peaks(cad, peaks = c(1, 30, 60))

Check if a directory is a valid GGIR output folder for stepmetrics

Description

Determines whether a given directory corresponds to a valid GGIR output directory that can be used with stepmetrics. Several conditions are checked in sequence:

1. Path exists and is a directory.

2. Directory name begins with '"output_"'.

3. Contains a 'meta/' subfolder.

4. Contains a 'meta/ms2.out/' subfolder (GGIR part 2 milestone data).

5. Contains at least one '*.RData' file in 'ms2.out'.

6. The loaded object IMP$metashort includes a step column (with '"step"' in its name).

If any of these checks fail, the function returns FALSE and issues a warning describing the missing requirement.

Usage

isGGIRoutput(path)

Arguments

Value

Logical scalar. Returns TRUE if the directory appears to be valid GGIR output suitable for stepmetrics, otherwise FALSE.

Note

- A warning is issued if the directory looks like GGIR output but is missing required parts (e.g., part 2 milestone data or step counts in IMP$metashort). - This function loads the first available RData file in meta/ms2.out/ to verify the presence of step counts.

See Also

[step.metrics()]

Examples

## Not run: 
# GGIR output folder
ggir_output_dir = system.file("extdata", "testfiles_GGIR", "output_test", package = "stepmetrics")
isGGIRoutput(ggir_output_dir)

# Non-GGIR directory
isGGIRoutput("C:/mystudy/rawdata/")

## End(Not run)

Read and standardize minute-level step data for one participant

Description

Reads one or more files for a single participant and returns a clean, minute-level data frame with two columns: 'timestamp' and 'steps'. The function auto-detects common file formats and timestamp layouts, fixes ActiGraph CSV headers/metadata when present, and aggregates to a 60-second epoch if input data are recorded at sub-minute resolution.

**Supported input formats**

• CSV: generic CSVs and ActiGraph exports (header lines and delimiters auto-detected; handles date/time split columns).

• AGD: ActiGraph binary files via PhysicalActivity.

• RData: GGIR output (IMP$metashort).

Usage

readFile(path, time_format = c())

Arguments

Details

• CSV handling: The function detects and skips ActiGraph header lines (typically 10), infers the field separator (comma/semicolon), and reconstructs a single timestamp when date and time are stored in separate columns. If no explicit timestamp column exists (rare ActiGraph cases), it reconstructs one from the file metadata (start time + epoch).

• AGD handling: AGD files are read with readActigraph; the recording start and epoch length are obtained from the embedded database and used to build a regular timestamp sequence.

• Step column detection: The column containing step counts is inferred by matching names containing "step" or "value"; if multiple candidates are present, the column with higher variability is chosen.

• Epoch standardization: If the input epoch is shorter than 60 seconds, rows are aggregated by summing steps to 1-minute bins. Epochs longer than 60 seconds are currently unsupported.

Value

A data.frame with two columns:

timestamp

Character vector of ISO-8601 datetimes ("YYYY-MM-DDTHH:MM:SS(+/-)ZZZZ") for CSV/AGD inputs. For GGIR RData inputs, timestamps are carried through as present in IMP$metashort.

steps

Numeric vector of steps per minute. If the source data have sub-minute epochs, values are summed to 60-second bins. Epochs longer than 60 seconds are not supported and trigger an error.

Time zones

For CSV/AGD inputs, timestamps are returned in ISO-8601 with an explicit offset. If time_format is provided, it is passed directly to strptime for parsing; otherwise a set of common formats is attempted.

See Also

step.metrics, get_cadence_bands

Examples

# Fitbit csv
fitbit_csv = system.file("extdata", "testfiles_fitbit",
                         "S001_d1_1min_epoch.csv", package = "stepmetrics")
df <- readFile(fitbit_csv)

# ActiGraph AGD
actigraph_agd = system.file("extdata", "testfiles_agd", "3h30sec.agd", package = "stepmetrics")
df <- readFile(actigraph_agd)

Calculate and export daily and person-level step and cadence metrics

Description

This function processes epoch-level step count files (raw exports or GGIR output) and derives a comprehensive set of **daily** and **person-level** metrics. Metrics include total steps, cadence peaks, time and steps accumulated in predefined cadence bands, and time and steps in moderate, vigorous, and moderate-to-vigorous physical activity (MPA, VPA, MVPA).

The function writes two types of summary CSVs:

• Day-level: One file per participant per day, stored in 'outputdir/daySummary/'.

• Person-level: A single file with aggregated averages across valid days per participant, stored as 'outputdir/personSummary.csv'.

Usage

step.metrics(
  datadir,
  outputdir = "./",
  idloc = "_",
  cadence_bands = c(0, 1, 20, 40, 60, 80, 100, 120, Inf),
  cadence_peaks = c(1, 30, 60),
  cadence_MOD = 100,
  cadence_VIG = 130,
  includedaycrit = 10,
  includeawakecrit = NULL,
  includedaylengthcrit = 23,
  exclude_pk30_0 = TRUE,
  exclude_pk60_0 = TRUE,
  time_format = NULL,
  verbose = TRUE
)

Arguments

Details

For each participant and day, the function computes:

• Total steps per day

• Cadence peak metrics (e.g., peak 1, 30, 60 minutes)

• Minutes and steps in each cadence band

• Minutes in MPA, VPA, and MVPA

• Steps accumulated in MPA, VPA, and MVPA

• Recording duration, valid wear time, and awake time (if GGIR available)

Person-level outputs include plain, weighted (weekday/weekend), and stratified (weekday/weekend separately) averages of all variables.

Value

This function does not return an object. It writes:

• <ID>_DaySum.csv in 'outputdir/daySummary/' with daily metrics.

• personSummary.csv in 'outputdir/' with person-level averages.

Examples

datadir = system.file("extdata", "testfiles_fitbit", package = "stepmetrics")
step.metrics(datadir = datadir, outputdir = tempdir())