Use Scripts to Export Data from Datavyu¶
Datavyu supports numerous data export methods. The Export Data from Datavyu section of the software guide tutorials demonstrates how to export data to a basic .csv file using the Export File function. The Ruby scripting API offers users more flexibility in specifying different output file formats for exporting data. This section covers two scripting approaches:
- A straight frame-by-frame dump detailing all observations associated with each frame.
- A nested export, which loops through each column and nests cells appropriately.
If you wish to export data from multiple files, refer to the Batch Operations on Multiple Files tutorial for guidance on operations that involve multiple files.
Method : Frame-by-Frame Export¶
A frame-by-frame export prints a row for every video frame in the spreadsheet and looks across every column and code and writes the values for that frame. This method is particularly useful for free-form coding projects that contain multiple columns that do not nest in time. Using a frame-by-frame export makes it easy to import your data into other software packages (e.g., Excel, SPSS, R).
Datavyu includes a script that performs frame-by-frame export on any file automatically. By default, the script “Export Data by Frame” will appear in the “favorites” folder in Datavyu. To test the script, open the sample spreadsheet in Datavyu. Once the spreadsheet has loaded, select the Script menu and then select “Favorites/Export Data by Frame.rb”. That’s it! The script will output a .csv file to your desktop called “framebyframe_export.csv” that contains all of the data from the spreadsheet that can be opened in the statistical package of your choice.
If you would like to export multiple files frame-by-frame, there is a script included for that as well (“Export Data by Frame – Multiple.rb”). Simply create a folder on your desktop called “datavyu_files” and place the files you want to export in that folder. Please note that the files should contain the same columns and codes to export correctly.
These scripts will work on a variety of files and may fit many users’ needs. However, if you want to tailor the scripts for your own purposes (e.g., changing the output file, input folder, or delimiter), you can find the script files in your Datavyu installation folder under the “Favorites” folder.
Method : Nested Export¶
A nested export exports data based on the nesting of cells. This is most useful for spreadsheets whose cells group together. For instance, the following spreadsheet example has three columns: “id”, “trial”, and “foot”. “id” is a participant ID, which might include codes that describe the participant’s individual id code, gender, age, etc. “trial” is a column that marks each trial that occurred and “foot” is a column representing observations recorded during each trial.
The cells, then, group together with an “id” cell covering the length of all trials. There are two trials in the example that occur within the time limits of the “id” cell and there are several”foot” cells that occur within the time limits of each trial.
To export data from this style of spreadsheet, we will use a series of loops, exporting a row of tab-separated values for each cell in the “foot” column. Each row will include the “id” and “trial” data that the “foot” cell nests beside. This spreadsheet has only one “id” cell, since all of the data in that spreadsheet is for a single participant.
Set up the script, and then define where you are going to output the file to. You need to define the location of the file (in this case, the Desktop, defined by
out_file), and create a Ruby object to hold the new file’s data as it outputs it, which we’ll call
require 'Datavyu_API.rb' begin # Defines the location of the file that we're going to be outputting # the spreadsheet data to - the file name is DataOutput.txt # and is located on the Desktop. out_file = File.expand_path("~/Desktop/DataOutput.txt") # Creates the file, and assigns write permissions so that the system # can write to it ('w') out = File.new(out_file,'w')
Retrieve the columns you want to output from the spreadsheet, and assign them to
require 'Datavyu_API.rb' begin out_file = File.expand_path("~/Desktop/DataOutput.txt") out = File.new(out_file,'w') # Retrieve the "id", "trial" and "foot" columns from the spreadsheet # and assign them to RColumn objects id = getColumn("id") trial = getColumn("trial") foot = getColumn("foot")
Set up a series of
forloops that we will use to iterate over each cell in the columns we’re interested in.
require 'Datavyu_API.rb' begin out_file = File.expand_path("~/Desktop/DataOutput.txt") out = File.new(out_file,'w') id = getColumn("id") trial = getColumn("trial") foot = getColumn("foot") # Set up a series of nested for loops, following the nesting # of the cells: "id", then "trial", then "foot". # # This will iterate through every "cell" # in id, every cell in "trial", and every cell in "foot". # # idcell, tcell, and fcell are temporary Ruby variables # that hold the data for a cell as the cell is iterated over. for idcell in id.cells for tcell in trial.cells for fcell in foot.cells
ifclause that checks if cells are nested. In plain English, this
ifstatement checks if the onset of the
fcell) occurs after the onset of the
tcell) and that the offset of the
fcelloccurs before the offset of the
tcell. Or, in even plainer English, that the
fcelloccurs during the length of the
If the clauses are met, write the cells’ codes to the
outfile, separated by tabs.
require 'Datavyu_API.rb' begin out_file = File.expand_path("~/Desktop/DataOutput.txt") out = File.new(out_file,'w') id = getColumn("id") trial = getColumn("trial") foot = getColumn("foot") for idcell in id.cells for tcell in trial.cells for fcell in foot.cells # Set up if statement that checks for cell encapsulation if lcell.onset >= tcell.onset && lcell.offset <= tcell.offset
ifclause is met, write the cells’ codes to the
outfile, separated by tabs.
As a refresher, cells have a series of codes: onset, offset, and ordinal by default, as well as any user-specified codes. To access the codes in one of our temporary Ruby variables (
fcell), we use the format
cellName.codeName. To access the “idnum” code in the “id” column, then, we’d request
require 'Datavyu_API.rb' begin out_file = File.expand_path("~/Desktop/DataOutput.txt") out = File.new(out_file,'w') id = getColumn("id") trial = getColumn("trial") foot = getColumn("foot") for idcell in id.cells for tcell in trial.cells for fcell in foot.cells if fcell.onset >= tcell.onset && fcell.offset <= tcell.offset # Write the cells' codes to the output file, separated by tabs - the "\t" # You must include a newline indicated, "\n" so that the next cells' codes # will be output on a new line, giving them their own row. out.write(idcell.idnum + "\t" + tcell.onset.to_s + "\t" + tcell.offset.to_s + "\t" + tcell.trial + "\t" + fcell.ordinal.to_s + "\t" + fcell.onset.to_s + "\t" + fcell.offset.to_s + "\t" + fcell.side + "\n") # End the if clause, and the for loops, as well as the script end end end end end
Video Example of Running an Export Script¶
This video displays a user running a script to export data in a specific way. This export script exports all of the columns of one spreadsheet into an excel file. Datavyu’s built in export displays one excel cell as one cell on the spreadsheet. This specific script repeats all the participant information such as the id number, test date, birthdate, and sex, for all of the data making it more useful when you import into a statistical analysis program.