Use Scripts to Export Data from Datavyu

Use Scripts to Export Data from Datavyu

Export Methods

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.

../../_images/frame-by-frame.png

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

../../_images/sample-nested-data.png

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.

  1. 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 out:

    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')
    
  2. Retrieve the columns you want to output from the spreadsheet, and assign them to RColumn objects:

    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")
    
  3. Set up a series of for loops 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
    
  4. Write an if clause that checks if cells are nested. In plain English, this if statement checks if the onset of the foot cell (fcell) occurs after the onset of the trial cell (tcell) and that the offset of the fcell occurs before the offset of the tcell. Or, in even plainer English, that the fcell occurs during the length of the tcell.

    If the clauses are met, write the cells’ codes to the out file, 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
    
  5. If the if clause is met, write the cells’ codes to the out file, 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 (icell, tcell, and fcell), we use the format cellName.codeName. To access the “idnum” code in the “id” column, then, we’d request icell.idnum.

    Since the script is outputting strings, we also need to convert the onset, offset, and ordinals from the integer format to the string format, using to_s.

    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.