README.md

In iamamutt/datavyur: Working with 'Datavyu' Data

datavyur

The goal of datavyur is to …

Installation

You can install the released version of datavyur from CRAN with:

install.packages("datavyur")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("iamamutt/datavyur")

Datavyu data structure

It is important to understand the parts of one or more Datavyu files to understand how to use this R package. The structure is basically organized like so:

• datavyu files
  • column names
    • cells
      • standard fields
      • custom fields

For example, you may have several Datavyu files with multiple “columns” in each file, and in each column exists the standard onset, offset, and ordinal fields and their values, along with custom fields that hold their “codes.”

|datavyu_file1.opf
|- column_name1
|  |- cell
|     |- onset <ts>
|     |- offset <ts>
|     |- ordinal <int>
|     |- custom_code_id1 <code>
|     |- custom_code_id2 <code>
|  |- cell
|     |- onset <ts>
|     |- offset <ts>
|     |- ordinal <int>
|     |- custom_code_id1 <code>
|     |- custom_code_id2 <code>
|  |- ...
|- column_name2
|  |- cell
|     |- onset <ts>
|     |- offset <ts>
|     |- ordinal <int>
|     |- custom_code_id1 <code>
|     |- custom_code_id2 <code>
|  |- ...
|datavyu_file2.opf
|- column_name1
|  |- ...
|- column_name2
|  |- ...
|...

Example

This is a basic example which shows you how to import Datavyu data into R. First, load the package.

# Load the datavyur library to use the functions below
library(datavyur)

Next, point to a directory containing .csv data that has been previously exported using the script datavyu2csv.rb (see the section “Exporting Datavyu .opf files” below). This example uses the internal package data directory for demonstration purposes.

ex_data_dir <- datavyur_internal_data()

The folder ex_data_dir originally contained 3 .opf files that have been split into 6 separate .csv files, one .csv file for each Datavyu file (.opf) and column combination.

Names of .csv files after using the Ruby script datavyu2csv.rb:

#> [1] "childhands__dyad1.csv"  "childhands__dyad2.csv"  "childhands__dyad3.csv" 
#> [4] "parenthands__dyad1.csv" "parenthands__dyad2.csv" "parenthands__dyad3.csv"

Names of the original Datavyu .opf files:

#> [1] "dyad1" "dyad2" "dyad3"

Names of the Datavyu columns found inside the set of exported .csv files:

#> [1] "childhands"  "parenthands"

This information can be obtained by using the function datavyu_search.

datavyu_search(folder=ex_data_dir)

Use the import_datavyu function to import Datavyu columns into R as separate data.frames. Since there are multiple Datavyu columns that need to be imported from ex_data_dir, set as_list=TRUE to import a data.frame for each Datavyu column.

dv_columns <- import_datavyu(folder=ex_data_dir, as_list=TRUE)

You can access each data.frame like so:

child_data <- dv_columns$childhands

The first few rows are shown below.

| file | column | ordinal | onset | offset | hand | look | |:------|:-----------|--------:|-------:|-------:|:------|-----:| | dyad1 | childhands | 1 | 28846 | 157944 | left | NaN | | dyad1 | childhands | 2 | 177790 | 184132 | | 1 | | dyad1 | childhands | 3 | 199152 | 201028 | | 1 | | dyad1 | childhands | 4 | 204120 | 226493 | left | NaN | | dyad1 | childhands | 5 | 236796 | 251476 | right | NaN | | dyad1 | childhands | 6 | 274095 | 315907 | both | 0 |

Horizontal alignment of Datavyu data

main_list <- import_datavyu_to_list()

Aligning data by timestamp

To align data found in the folder ex_data_dir use the function temporal_align.

time_aligned1 <- temporal_align(folder=ex_data_dir, fps=30, columns="childhands")

| file | frame_number | childhands.ordinal | childhands.onset | childhands.offset | childhands.hand | childhands.look | |:------|--------------:|-------------------:|-----------------:|------------------:|:----------------|----------------:| | dyad1 | 866 | 1 | 28846 | 157944 | left | NaN | | dyad1 | 867 | 1 | 28846 | 157944 | left | NaN | | dyad1 | 868 | 1 | 28846 | 157944 | left | NaN | | dyad1 | 869 | 1 | 28846 | 157944 | left | NaN | | dyad1 | 870 | 1 | 28846 | 157944 | left | NaN | | dyad1 | 871 | 1 | 28846 | 157944 | left | NaN |

Aligning by ordinal value

ord_aligned1 <- ordinal_align(folder=ex_data_dir, columns="parenthands")

| file | ordinal | parenthands.onset | parenthands.offset | parenthands.hand | parenthands.look | |:------|--------:|------------------:|-------------------:|:-----------------|-----------------:| | dyad1 | 1 | 96019 | 148073 | | NaN | | dyad1 | 2 | 323576 | 344652 | right | 1 | | dyad1 | 3 | 345184 | 372673 | | 0 | | dyad1 | 4 | 392624 | 393581 | right | NaN | | dyad1 | 5 | 396504 | 435797 | | 1 | | dyad1 | 6 | 489463 | 565105 | both | NaN |

Vertical alignment of Datavyu data

To stack several Datavyu columns’ data vertically, use the function vert_merge_datavyu_list. This will convert all codes to characters so that they’re able to exist in a single column.

vert_data <- vert_merge_datavyu_list(main_list)

| file | column | field | code | ordinal | onset | offset | |:------|:------------|:------|:-----|--------:|--------:|--------:| | dyad1 | childhands | hand | left | 1 | 28846 | 157944 | | dyad1 | childhands | look | | 1 | 28846 | 157944 | | dyad1 | childhands | hand | | 2 | 177790 | 184132 | | dyad1 | childhands | look | 1 | 2 | 177790 | 184132 | | dyad1 | childhands | hand | | 3 | 199152 | 201028 | | dyad1 | childhands | look | 1 | 3 | 199152 | 201028 | | dyad3 | parenthands | hand | | 3 | 1411097 | 1541540 | | dyad3 | parenthands | look | 0 | 3 | 1411097 | 1541540 | | dyad3 | parenthands | hand | | 4 | 1912060 | 2240150 | | dyad3 | parenthands | look | | 4 | 1912060 | 2240150 | | dyad3 | parenthands | hand | | 5 | 2885547 | 3046254 | | dyad3 | parenthands | look | 0 | 5 | 2885547 | 3046254 |

Exporting Datavyu .opf files

Importing R data into Datavyu

iamamutt/datavyur documentation built on Dec. 20, 2021, 5:57 p.m.