# Reading and Manipulating Activity Data

    library(actibase)
    library(actiread)

# Overview

`actibase` is the foundation layer for actigraphy and activity data. It focuses on raw file reading, standardization, calibration, resampling, activity counts, non-wear detection, and transformation bookkeeping.

Higher-level summarization, step-count mapping, and downstream statistical analysis are meant to live in overlay packages that build on top of this core package.

# Reading data

The package ships with a small GT3X file and a small CWA file under `inst/extdata`. We will use those examples here.

    gt3x_file = acti_example_gt3x()
    cwa_file = acti_example_cwa()

    gt3x = acti_read_gt3x(gt3x_file, verbose = FALSE)
    cwa = acti_read_cwa(cwa_file, verbose = FALSE)

    class(gt3x)
    [1] "tbl_df"     "tbl"        "data.frame"
    names(gt3x)
    [1] "time" "X"    "Y"    "Z"
    class(cwa)
    [1] "tbl_df"     "tbl"        "data.frame"
    names(cwa)
    [1] "time"    "x"       "y"       "z"       "temp"    "battery" "light"

The GT3X reader uses `read.gt3x::read.gt3x()` underneath, while the CWA reader uses `GGIRread::readAxivity()`.

If you need to inspect the GT3X metadata separately, `acti_info_gt3x()` parses the header information without returning the full data stream.

    info = acti_info_gt3x(gt3x_file)
    names(info)
     [1] "Serial Number"      "Device Type"        "Firmware"
     [4] "Battery Voltage"    "Sample Rate"        "Start Date"
     [7] "Stop Date"          "Last Sample Time"   "TimeZone"
    [10] "Download Date"      "Board Revision"     "Unexpected Resets"
    [13] "Acceleration Scale" "Acceleration Min"   "Acceleration Max"
    [16] "Subject Name"       "Serial Prefix"

The readers also let you control timezone handling explicitly. Setting `apply_tz = FALSE` keeps the timestamps as stored in the file, and `tz = NULL` disables the final timezone forcing step.

    gt3x_no_tz = acti_read_gt3x(
      gt3x_file,
      tz = NULL,
      apply_tz = FALSE,
      verbose = FALSE,
      fill_zeroes = FALSE
    )

    cwa_no_tz = acti_read_cwa(
      cwa_file,
      tz = NULL,
      apply_tz = FALSE,
      verbose = FALSE
    )

    get_transformations(gt3x_no_tz)
    [1] "acti_read_gt3x:attributes_set" "acti_read_gt3x:data_read"
    get_transformations(cwa_no_tz)
    [1] "acti_read_cwa:data_read_via_readAxivity"

Internally, Axivity files use fixed UTC offsets. The helper that maps those offsets to Olson timezone names is small but useful when you need to reason about the conversion logic:

    tzoffset_to_tz(c("+00:00", "-05:00", "+01:00"))
    [1] "Etc/GMT0"  "Etc/GMT-5" "Etc/GMT+1"

# Standardizing

The baseline package keeps the data in a consistent shape:

    std = acti_standardize_data(gt3x)

    head(std)
    # A tibble: 6 × 4
      time                      X        Y     Z
      <dttm>                <dbl>    <dbl> <dbl>
    1 2019-09-17 18:40:00 0        0.00781 0.996
    2 2019-09-17 18:40:00 0.0156   0       1.01
    3 2019-09-17 18:40:00 0.0195  -0.00781 1.00
    4 2019-09-17 18:40:00 0.0156  -0.0117  1.01
    5 2019-09-17 18:40:00 0.0156  -0.00781 1.01
    6 2019-09-17 18:40:00 0.00781 -0.00781 1.01

# Resampling

You can resample a three-axis signal to a new sampling rate or to specific timestamps:

    resampled = acti_resample(std, sample_rate = 30L)
    get_transformations(resampled)
    [1] "acti_resample:sample_rate_attribute_changed_to_30"
    [2] "acti_resample:linear_resampled_to_30Hz"
    [3] "acti_read_gt3x:attributes_set"
    [4] "acti_fill_zeros:filled_zeros"
    [5] "acti_read_gt3x:data_read"

    same_times = acti_resample_to_time(
      std,
      times = lubridate::floor_date(std$time, unit = "1 second")
    )
    get_transformations(same_times)
    [1] "acti_resample_to_time:resampled_to_specific_times"
    [2] "acti_read_gt3x:attributes_set"
    [3] "acti_fill_zeros:filled_zeros"
    [4] "acti_read_gt3x:data_read"