Reading-in-CWA-files

Here we will show a simple example of converting and reading in Continuous Wave Accelerometer (CWA) data files (https://axivity.com/userguides/ax3/using/). First, let’s load up the package.

library(read.cwa)

Converting to a CSV

We will use a file embedded in the package:

file = system.file("extdata", "ax3_testfile.cwa.gz", package = "read.cwa")
file = R.utils::gunzip(file, destname = tempfile(fileext = ".cwa"), 
                       remove = FALSE, overwrite = TRUE)

To show how the package uses the C code from https://github.com/digitalinteraction/openmovement/tree/master/Software/AX3/cwa-convert/c to do the underlying CWA to CSV conversion. The convert_cwa function will run to create a CSV file

csv_file = convert_cwa(file, verbose = FALSE)
csv_file
#> $file
#> [1] "/var/folders/1s/wrtqcpxn685_zk570bnx9_rr0000gr/T//RtmpkDmgUn/file145e97eff697a.csv"
#> 
#> $header
#> $header$uniqueSerialCode
#> [1] 39434
#> 
#> $header$frequency
#> [1] 100
#> 
#> $header$start
#> [1] "2019-02-26 10:55:06 UTC"
#> 
#> $header$device
#> [1] "Axivity"
#> 
#> $header$firmwareVersion
#> [1] 44
#> 
#> $header$blocks
#> [1] 145
#> 
#> $header$accrange
#> [1] 8
#> 
#> $header$hardwareType
#> [1] "AX3"

We see the output is a list, with the first element being the file element, which is the CSV output file. The header slot, if the GGIR package is available, will be header information from the file. The C code does not output all the header elements, so GGIR was used.

If we look at the head of the CSV file, we see it has data only:

readLines(csv_file$file, 3)
#> [1] "2019-02-26 10:55:06.000,0.328125,0.984375,0.203125"  
#> [2] "2019-02-26 10:55:06.010,0.828125,-0.359375,-0.375000"
#> [3] "2019-02-26 10:55:06.019,0.875000,-0.390625,-0.390625"

This CSV can be read in using read_cwa_csv:

df = read_cwa_csv(csv_file$file)
head(df)
#> # A tibble: 6 x 4
#>   time                    X      Y      Z
#>   <dttm>              <dbl>  <dbl>  <dbl>
#> 1 2019-02-26 10:55:06 0.328  0.984  0.203
#> 2 2019-02-26 10:55:06 0.828 -0.359 -0.375
#> 3 2019-02-26 10:55:06 0.875 -0.391 -0.391
#> 4 2019-02-26 10:55:06 0.891 -0.391 -0.391
#> 5 2019-02-26 10:55:06 0.891 -0.375 -0.391
#> 6 2019-02-26 10:55:06 0.875 -0.359 -0.375

which will give you the output data.frame.

attr(df, "header")
#> NULL

Converting to a Data Frame

The process for converting a CWA to a data.frame is essentially the 2 processes above wrapped into the read_cwa function:

out = read_cwa(file, verbose = FALSE)
out
#> $data
#> # A tibble: 17,400 x 4
#>    time                    X      Y      Z
#>    <dttm>              <dbl>  <dbl>  <dbl>
#>  1 2019-02-26 10:55:06 0.328  0.984  0.203
#>  2 2019-02-26 10:55:06 0.828 -0.359 -0.375
#>  3 2019-02-26 10:55:06 0.875 -0.391 -0.391
#>  4 2019-02-26 10:55:06 0.891 -0.391 -0.391
#>  5 2019-02-26 10:55:06 0.891 -0.375 -0.391
#>  6 2019-02-26 10:55:06 0.875 -0.359 -0.375
#>  7 2019-02-26 10:55:06 0.875 -0.359 -0.391
#>  8 2019-02-26 10:55:06 0.875 -0.359 -0.406
#>  9 2019-02-26 10:55:06 0.875 -0.359 -0.406
#> 10 2019-02-26 10:55:06 0.891 -0.344 -0.406
#> # … with 17,390 more rows
#> 
#> $header
#> $header$uniqueSerialCode
#> [1] 39434
#> 
#> $header$frequency
#> [1] 100
#> 
#> $header$start
#> [1] "2019-02-26 10:55:06 UTC"
#> 
#> $header$device
#> [1] "Axivity"
#> 
#> $header$firmwareVersion
#> [1] 44
#> 
#> $header$blocks
#> [1] 145
#> 
#> $header$accrange
#> [1] 8
#> 
#> $header$hardwareType
#> [1] "AX3"
#> 
#> 
#> attr(,"class")
#> [1] "AccData"

If the header is not available, you can do a quick estimation of the sampling frequency based on the differences between times:

diffs = as.numeric(diff(out$data$time))
diffs = as.numeric(names(which.max(table(diffs))))
estimated_freq = round(1/diffs, 3)
estimated_freq
#> [1] 100

which should match up when you have the header information:

out$header$frequency
#> [1] 100

Reading in Other Data

By default, for all functions, the xyz_only = TRUE, which indicates only the time and X/Y/Z acceleration parameters will be reported. If xyz_only = FALSE, then all data available from this extracted code will be retrieved from the data file:

out = read_cwa(file, xyz_only = FALSE, verbose = FALSE)
out$data
#> # A tibble: 17,400 x 11
#>    time                    X      Y      Z light temperature battery
#>    <dttm>              <dbl>  <dbl>  <dbl> <dbl>       <dbl>   <dbl>
#>  1 2019-02-26 10:55:06 0.328  0.984  0.203   283         258     190
#>  2 2019-02-26 10:55:06 0.828 -0.359 -0.375   283         258     190
#>  3 2019-02-26 10:55:06 0.875 -0.391 -0.391   283         258     190
#>  4 2019-02-26 10:55:06 0.891 -0.391 -0.391   283         258     190
#>  5 2019-02-26 10:55:06 0.891 -0.375 -0.391   283         258     190
#>  6 2019-02-26 10:55:06 0.875 -0.359 -0.375   283         258     190
#>  7 2019-02-26 10:55:06 0.875 -0.359 -0.391   283         258     190
#>  8 2019-02-26 10:55:06 0.875 -0.359 -0.406   283         258     190
#>  9 2019-02-26 10:55:06 0.875 -0.359 -0.406   283         258     190
#> 10 2019-02-26 10:55:06 0.891 -0.344 -0.406   283         258     190
#> # … with 17,390 more rows, and 4 more variables: battery_voltage <dbl>,
#> #   battery_percentage <dbl>, battery_relative <dbl>, events <chr>

where we see the following columns output:

colnames(out$data)
#>  [1] "time"               "X"                  "Y"                 
#>  [4] "Z"                  "light"              "temperature"       
#>  [7] "battery"            "battery_voltage"    "battery_percentage"
#> [10] "battery_relative"   "events"