Tierpsy Tracker

Multi-Worm Behaviour Tracker

This project is maintained by ver228

Output Files

The following output files are produced by Tierpsy Tracker during the analysis steps. The basename prefix in each of the files refers to the original video name without the extension. For example, if the video file is named as myfile.avi, the files will look like myfile.hdf5, myfile_subsample.avi myfile_skeletons.hdf5, myfile_features.hdf5, myfile_intensities.hdf5.


Contains the compressed hdf5 video data.


Shape (tot_images, im_high, im_width)

Compressed array with the masked images.

Additionally, this dataset will store as attributes the following information:


Shape (tot_images/save_full_interval, im_high, im_width)

Frame without mask saved every save_full_interval frames. By default the interval is adjusted to be saved every 5 min. This field can be useful to identify changes in the background that are lost in /mask e.g. food depletion or contrast lost due to water condensation.


Shape (tot_images,)

Mean intensity of a given frame. It is useful in optogenetic experiments to identify when the light is turned on.

/timestamp/time timestamp/raw

Timestamp extracted from the video if the is_extract_metadata flag set to true. If this fields exists and are valid (there are not nan values and they increase monotonically), they will be used to calculate the fps used in subsequent parts of the analysis. The extraction of the timestamp can be a slow process since it uses ffprobe to read the whole video. If you believe that your video does not have a significative number of dropped frames and you know the frame rate, or simply realise that ffprobe cannot extract the timestamp correctly, I recommend to set is_extract_metadata to false.


Low time and spatial resolution avi video generated using the data in /mask.


Contains the results of the tracking and skeletonization steps.


Table where the first results of TRAJ_CREATE and TRAJ_JOIN. Do not use this table in further analysis, use instead /trajectories_data.


Table containing the data of the trajectories used in the analysis and displayed by the Tierpsy Tracker Viewer. Each row should have a unique pair of worm_index_joined and frame_number keys corresponding to each of the particles identified in each video frame. Additionally, this dataset will store the same attributes described in /mask:


/skeleton /contour_side1 /contour_side2

Shape (tot_valid_skel, n_segments, x-y coordinate)

Normalized coordinates (same number of points) for the skeletons and the contour in each side of the worm. The head should correspond to the first index and the tail to the last.


Shape (tot_valid_skel, n_segments)

Contour width along the skeleton.


Shape (tot_valid_skel)

Contour width of the midbody. Used to calculate the intensity maps in INT_PROFILE.

/contour_side1_length /contour_side2_length /skeleton_length

Shape (tot_valid_skel)

Contours and skeleton length in pixels before normalization and smoothing. This value is likely to be larger than the length caculated in FEAT_CREATE due to the noiser contours and probably should be deprecated.


Shape (tot_valid_skel) Area in pixels of the binary image used to calculate the skeletons. Probably should be deprecated.


Internal. Table with the skeleton switched in INT_SKE_ORIENT.

/timestamp/raw /timestamp/time

Same as in basename.hdf5.


Shape (tot_points, x-y coordinate) Optional see (FOOD_CNT).



Same as /trajectories_data but only containing rows where has_skeleton is true.


Shape (tot_valid_skel, n_length, n_width)

Intensity maps of the straigten worms described in INT_PROFILE. Each index in the first dimension correspond to the same row in /trajectories_data_valid. Note that the data type is float16. Cast this data to float32 or float64 before doing any operation to avoid overflows.


Shape (tot_valid_skel, n_length)

Averaged intensity along the skeleton. Calculated in INT_PROFILE and used by INT_SKE_ORIENT. The data is organized as in /straighten_worm_intensity.

basename_features.hdf5 (OpenWorm Analysis Toolbox)

This file contains the results of FEAT_CREATE. For a more detailed information of the features see the supplementary information of Yemini et al.


Contour and skeleton coordinates after smoothing. Each index in the first dimension correspond to a row in /features_timeseries.


Table containing the features that can be represented as timeseries. Each row corresponds to a single (worm_index, timestamp) pair. Additionally, this dataset will store the same attributes described in /mask


Each time frame can be labeled according to any of the following events definitions (modified from the Supplementary Material of Yemini et al.:

For each of the event each of the following features are calculated:


Set of features calculated by subdividing and reducing the features in /features_timeseries and the /features_events/worm_* .

The subdivisions can be done by movement type or/and by signed data. A feature was subdivided when the corresponding subfix is in its name. If a feature name does not contain any subdivision subfix then the reduction was applied on all the original data.

The movement subdivision are only valid for features in /features_timeseries and are:

The signed data subdivision are only applied to data where the sign have meaning, e.g. midbody_speed or midbody_bend_mean and not in features like area or length. The signed data subdivisions are:

The reduction can be done by any of the following operations on a given subdivision. The data is saved in the corresponding table name.

Finally, there are some tables that have the subfix _split. For this tables long trajectories are splitted in shorter ones of at most split_traj_time seconds before calculating the features. This is done as an attempt to balance uneven track sizes. Otherwise a trajectory that was followed for the whole duration of the video will be counted as a single feature vector, while a trajectory that was lost and found several times will be counted as many feature vectors. This is because each time a worm is lost it would be assigned a new id when it is found again.

basename_featuresN.hdf5 (Tierpsy Features)

/trajectories_data (basename_featuresN)

Same as /trajectories_data but using the video timestamp to drop duplicated or interpolate missing frames. The columns plate_worm_id, is_good_skel, has_skeleton, int_map_id are removed and the following columns are added:

/blob_features (basename_featuresN)

Same as /blob_features in basename_skeletons.hdf5.

/food_cnt_coord (basename_featuresN)

Same as /food_cnt_coord in basename_skeletons.hdf5.


Contour and skeleton coordinates after smoothing. This table is linked to /trajectories_data by the column skeleton_id. An skeleton_id value of -1 means that that that specific time point was not skeletonized.


Time Series Features:

body_part1 body_part2
body head_tip
body neck
body hips
body tail_tip
neck head_tip
head_base head_tip
hips tail_tip
tail_base tail_tip

Time derivatives:

Event flags vectors:

Auxiliar columns:


This table contains the plate average for each corresponding feature stat according to the transformations explained here.

postfix meaning
10th 10th percentil
50th 50th percentil
90th 90th percentil
IQR interquantile distance between the 25th to 75th percentile
norm data normalized by the skeleton length
abs use the absolute value a ventral/dorsal signed feature
w_forward only the points when the worm is going forwards
w_backward only the points when the worm is going barwards
w_paused only the points when the worm is paused