Introduction to Scripting

Introduction to Scripting

This detailed guide describes how to write Ruby scripts to automate tasks in Datavyu and to ensure reliable coding.

Classes, Methods, and Parameters provides an overview of the methods and classes of the Datavyu API. For a more in-depth discussion of each particular method and function, refer to the Reference documentation.

General Principles

Each cell that you create with the Datavyu API has three inherent codes: onset, offset, and ordinal. Each cell also has at least one user-specified code.

onset, offset, and ordinal are all Integers, while the user-specified codes are Strings.

onset and offset are measured in milliseconds from the beginning of the video, starting from 0. For instance, an onset time of 00:02:20 translates to 140000ms.

Since user-specified codes are strings, you must convert any codes that you wish to perform calculations on to a numeric type. This is easily done with Ruby using the to_i method for integers, or the to_f method for floating point numbers.


Create a variable, var1 whose value is “5”. Since the number 5 has quotation marks around it, it is a string.

var1 = "5"

If you print var, you’d see that it is “5”. Create a new variable, var2 from var1 using to_i to convert the “5” to a 5.

var2 = var1.to_i

Print var2 and see that it is a 5 without quotation marks:

print var2


Ruby provides two options for printing to the console: the p command and the puts command. When in doubt, use p, as it prints arrays and lists in a more readable format, rather than mashing them all together like puts does. Try printing a list such as [5, 6, 7, 8, 9] using both p and puts to see the difference.

p [5,6,7,8,9]
puts [5,6,7,8,9]

Basic Script Format


Scripts are very sensitive! When programming, every quotation mark, underscore, period, and slash serve a purpose. You must use the correct syntax or the script will not work.

Code and column names are also case sensitive. If you have a column in a spreadsheet called “trial”, requesting “Trial” will not work.

All code names in Ruby must be lowercase. Codes with uppercases have special meanings.

All Datavyu API scripts must include the following line at the top:

require 'Datavyu_API.rb'

This require statement loads all of the helper functions that enable your scripts to interact with the Datavyu spreadsheet.

In general, the rest of the script code goes between begin and end tags, making the general format as follows:

require 'Datavyu_API.rb'
  # Get the columns that we want to work with

  # Do something to those columns

  # Write any changes to those columns back to the spreadsheet


Anything that comes after a # character on a line in Ruby is a comment, which means it will not execute any specific task. Comments are useful for leaving notes that explain what the code is doing so that when you return to an old script you remember what you’re looking at. The examples in this documentation use comments extensively.

Now that you are grounded in the Datavyu Ruby API mechanics, consider the API Tutorials or Datavyu Ruby API Reference.