TIMEVP: Time Series Visualization and Processing Toolkit

a.k.a. Time is Very imPortant toolkit

by Tian Linger Xu

Instructions for Getting Started with timevp

1. Download the timevp toolkit from the green “code” button on the github page

2. Ensure you have Matlab installed on the computer you are using to run the toolkit. Student and trial downloads of Matlab are available for free on the Mathworks website.

3. Ensure that you have also downloaded the Matlab Image Processing toolbox (if you are launching Matlab for the first time, you can also select this toolbox as an optional additional product install). You can ensure the toolbox is installed by looking for it under the Matlab “Apps” tab.

4. Navigate in the file directory to the location you downloaded the timevp-main folder, and add it to path by right clicking and selecting “Add to Path -> Selected Folders and Subfolders.”

5. Open the timevp-main directory and work through the demo functions to get familiar with the capabilities of the toolkit.

Working Through the Demo Functions

In the timevp-main directory are multiple tutorials that provide examples of 5 functions available in the toolkit, using sample time series data. The data can be viewed in the “yulab_data” folder. As you work through the demos, your output files will be saved to the “timevp_output_files” folder. If you want to check these results to ensure the functions are working correctly, your output files can be compared to sample output files in the “saved_output_autogenerated” folder. Demo files that do not end in a number (extra examples) contain extra documentation that can be used to understand the steps performed in the code. The source code of the functions called by the demo functions can also be viewed in the “timevp_lib” folder.

Demo Functions:

• demo_timevp_visualization: Function used for visualizing time-series data

• demo_timevp_compute_statistics: Used for computing summary statistics about the distribution of events in data such as infant gaze pattern

• demo_timevp_ example_extract_measures: Function used for extracting variable measures during instances of a specified type of event. For example, naming events while a child is looking at a specific object can be isolated

• demo_timevp_example_extract_pairs: extracts pairs of events that fit a specified temporal condition (i.e. naming events and child looks to an object that occur concurrently, or within 3 seconds of each other).

• demo_timevp_temporal_profile: Computes the probabilities of certain behaviors prior, during or after another type of events (i.e. the probability that the infant's looking behavior matches with their manual behavior)

  Running the demo functions should be fairly straightforward. Example files can be run by pressing the Matlab run button, or individual code snippets can be run by highlighting, right-clicking, and selecting “Evaluate Selection in Command Window.” Try to understand what the functions are doing, and how you might apply them to your own data. Once you’ve worked through the demos, you can start using the timevp toolkit with your own data.

Using timevp_lib and making your own code

The data used for processing with timevp should be time series type data saved in csv format. The toolkit supports both “stream” data and “event” data, formatted as follows:

Stream: a stream of time series data. The csv file should contain a N by 2 matrix. N is the length of the time series. Two columns are [timestamp category_value].

e.g.

        344.7000   32.0000
        344.8000   34.0000
        344.9000   34.0000
        345.0000   34.0000
        345.1000   34.0000
        345.2000   34.0000
        345.3000   34.0000
        345.4000   32.0000
        345.5000   32.0000
        345.6000   32.0000

Event: time series events with start time and end time. The csv file should contain a N by 3 matrix. N is the total number of events. Three columns are [onset offset category_value].

e.g.

         69.0280   69.9450     1.0000
         72.5080   73.8050     4.0000
         75.4820   87.1540     1.0000
         91.3940  104.1530     4.0000
         108.3860  111.1130    4.0000
         103.1310  121.1620    1.0000
         122.7510  123.5740    1.0000                     
         150.0210  153.8760    4.0000
         154.0310  155.9760    1.0000

• The data folder should be stored in the timevp-main directory, like the example yulab_data

• The data files should be stored in the following structure:

[subject ID] (parent)

• [variable1].csv
• [variable2].csv
• [variable3].csv ...
• [variableN].csv

To set the data directory to your own data directory and change the sampling rate of the data, open timevp_config_dataset_info.m.These variables are set by simple assignment as follows:

sample_rate = 0.034;
dir_dataset = 'yulab_data';

Desired sampling rate can be calculated by dividing 1 by the Hz of the data collection (i.e. 1/30hz = .034)

If you have any further questions regarding the use of the timevp toolkit, please contact The UT Austin Developmental Intelligence Lab: https://www.la.utexas.edu/users/dil/team.html.