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.

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