Example files can be found here. The zip file contains a multiworm video recorded using a high resolution fixed camera and a single worm video recorded using the WT2.0.
You can analyze the videos using the Batch Processing Multiple Files App. The videos require different analysis parameters since they belong to different setups, therefore they cannot be processed together.
For the multiworm video the Parameters File must be set to MULTIWORM_OPENWORM.json and the File Pattern to Include as *.mov as shown below:
For the multiworm video the Parameters File must be set to WT2_clockwise.json and the File Pattern to Include as *.avi as shown below:
The processing times for in MacBook Pro (15-inch, 2017) were 04:31 minutes for the multiworm video and 11:43 minutes for the singleworm video.
Follow the installation instuctions and open a terminal or an Anaconda prompt (Windows) and type:
tierpsy_guiThe main widget should look like the one below:
The purpose of this widget is to setup the parameters used for Batch Processing Multiple Files. The interface is designed to help select the parameters that determine how videos are segmented and compressed. When imaging conditions such as lighting or magnification are changed, these parameters will need to be updated for good performance.
The most commonly adjusted parameter is the Threshold. If you have dark worms on a light background, Is Light Background? should be checked. In this case, pixels that are darker than the threshold value will be included in the mask. The selected value should be low enough to exclude as much background as possible without losing any part of the animals to be tracked. Below there is an example on how to do this.
If the objects to track are lighter than the background (e.g. if you are tracking fluorescent objects or using dark field illumination), un-check Is Light Background?. In this case, pixels that are above the threshold value will be included in the mask.
In some cases, even after adjusting the threshold there still remain large regions of background. If the tracked objects significatively change position during the movie you can enable the background subtraction as shown below. This method will consider anything that does not change within the specified frame range as background. However, if any of your animals are immobile during the entire frame range will be lost.
Other important parameters to set are:
Frame per Second(fps) is the frame rate of your video. An important value since it is used to calculate several other parameters. IfExtract Timestampis set totrue, the software will try to extract the frame rate from the video timestamp. However, keep in mind that it is not always possible to recover the correct timestamp, and therefore it is recommended that you provide the value here.Frames to Averageis used to calculate the background mask. This value can significantly speed up the compression step. However, it will not work if the particles are highly motile. Use the buttonsPlayandNext Chunkto see how a selected value affects the mask. Note that the average is used only for the background mask, the foreground regions are kept intact for each individual frame.Microns per Pixel. This value is only used to in the steps to calculate the final features](EXPLANATION.md). If this value is set to be less than zero the features results will be in pixels instead of micrometers.Analysis Type. The selected analysis type will determine the series of steps executed by the program according to the table below:
| Extension | Description |
|---|---|
| BASE* | No features, only steps up to the skeleton orientation |
| TIERPSY* | Add the steps for the tierpsy features calculation. |
| OPENWORM* | Add the steps for the openworm features calculation. |
| *WT2 | Add the necessary steps to analyze videos recorded using the WormTracker 2.0. |
| *SINGLE | Same steps as BASE but the trajectories will be joined with the assumption that there is only a single worm in the video. |
| *AEX | Add the steps to filter worms and obtain the food contour using deep learning models. This models might only work from data from the Behavioural Genomics Laboratory. |
You can access further parameters by clicking Edit More Parameters. The explanation of each parameter can be found by using the contextual help. It is not always trivial to effectively adjust these other parameters, but if you believe you need too, I recommend using a small video (~100 frames) for testing.
When you are satisfied with the selected parameters select a file name and press Save Parameters. The parameters will be saved as a JSON file that can be used in Batch Processing Multiple Files. If you need to further modify a parameter you can either use a text editor to change the JSON file directly or reload the file by dragging it into the Set Parameters widget.
This widget is used to execute all steps of tracking and feature extraction on each of the files on a given directory. The program allows a degree of parallelization by analyzing multiple files at the same time. The number of processes to run in parallel (Maximum Number of Processes) should not exceed the number of processor cores available on your machine to avoid slowing down the analysis.
Tierpsy Tracker will analyse of the video files that are present in Original Video Dir including sub-directories. Particular files are included if their names match the File Pattern to Include, but do not match the File Pattern to Exclude.
- The patterns can use Unix shell-style wildcards.
- In order to distinguish the output files that are saved during processing, any file that ends with any of the reserved suffixes will be ignored.
- To analyze a single file set
File Pattern to Includeto the entire file name. - If the
Analysis Start Pointis set to a step afterCOMPRESStheOriginal Videos Diris ignored and theMasked Videos Diris used instead.
Alternatively, one can create a text file with the list of files to be analysed (one file per line). The path to this file can then be set in Individual File List.
Parameters files created using the Set Parameters widget can be select in the Parameter Files box. You can also select some previously created files using the drop-down list. If no file is selected the default values will be used.
You can analyse videos created by the Worm Tracker 2.0 by selecting the parameters files WT2_clockwise.json or
WT2_anticlockwise.json. Use the former if the ventral side in the videos is located in the clockwise direction from the worm head, and the later if it is in the anticlockwise direction. To select a subset of files with a particular orientation you can save each subset in a different root directory or include the orientation information in the file name and use use the Pattern include option . If you need to fine-tune the parameters you can edit the .json files either with a text editor or with Set Parameters.
Note that each of the video files .avi must have an additional pair of files with the extensions .info.xml and .log.csv. Additionally, keep in mind that if the stage aligment step fails, an error will be risen and the analysis of that video will be stopped. If you do not want to see the error messages untick the option Print debug information.
Tierpsy Tracker will determine which analysis steps have already been completed for the selected files and will only execute the analysis from the last completed step. Files that were completed or do not satisfy the next step requirements will be ignored.
-
To see only a summary of the files to be analysed without starting the analysis tick
Only Display Progress Summary. -
You can start or end the analysis at specific points by using the
Analysis Start PointandAnalysis End Pointdrop-down menus. -
If you want to re-analyse a file from an earlier step, delete or rename the output files that were created during the previous run. If you only want to overwrite a particular step, you have to delete the corresponding step in the
/provenance_trackingnode in the corresponding file.
The masked videos created in the compression step are stored in Masked Videos Dir. The rest of the tracker results are stored in Tracking Results Dir. In both cases the subdirectory tree structure in Original Videos Dir is recreated.
The reason for creating the parallel directory structure is to make it easy to delete the analysis outputs to re-run with different parameter values. It also makes it easy to delete the original videos to save space once you've arrived at good parameter values. If you prefer to have the output files in the same directory as the original videos you can set Masked Videos Dir and Tracking Results Dir to the same value.
By default, Tierpsy Tracker creates files in the Temporary Dir and only moves them to the Masked Videos Dir or the Tracking Results Dir when the analysis has finished. The reasons to use a temporary directory are:
- Protect files from corruption due to an unexpected termination (crashes). HDF5 is particularly prone to get corrupted if a file was opened in write mode and not closed properly.
- Deal with unreliable connections. If you are using remote disks it is possible that the connection between the analysis computer and the data would be interrupted. A solution is to copy the required files locally before starting the analysis and copy the modified files back once is finished.
Some extra options:
-
By default the original videos are not copied to the temporary directory for compression. These files can be quite large and since they would be read-only they do not require protection from corruption. If you want copy the videos, tick
Copy Raw Videos to Temp Dirbox. -
In some cases the analysis will not finished correctly because some steps were not executed. If you still want to copy the files produced by the remaining steps to the final location tick the
Copy Unifnished Analysisbox.
The same functions are accesible using the command line. You can see the available option by typing in the main tierpsy directory:
python cmd_scripts/processMultipleFiles.py -h
This widget is used to visualize the tracking results. You can move to a specific frame, zoom in/out, select specific trajectories, and visualize the skeletons overlayed on the compressed video, the trajectory paths or saved unmasked frames. See below for an example on how to use it.
You can manually correct the trajectories as shown below. Label the trajectories you would like to include in the summary as WORM (green box). You can use the the w key as shortcut. Trajectories with any other label will be ignored.
If you want to use Tierpsy Features you can use Features Summary app by ticking the Is Manually Edited? box, selecting tierpsy as Features Type and re-runing the analysis. Make sure the file you edited in the viewer (Select Skeletons File, near the bottom of the app) has the extension _featuresN.hdf5. This is the default but an incomplete analysis might load the wrong extension.
If you want to use OpenWorm features the process is more complicated and might be deprecated in the feature. First you must select a file with the _skeletons.hdf5 extension in the viewer Select Skeletons File menu, before doing the manually editing of the trajectories. The software will try to select a file with _features.hdf5 or _featuresN.hdf5 extension by default. These file will not work with the OpenWorm pipeline. When you finish the editing, open the Set Parameters App and select OPENWORM_MANUAL as Analysis Type and save the parameters file. Alternatively you can open any parameters file with a text editor, and change the analysis_type field to OPENWORM_MANUAL. Then open the Batch Processing Multiple Files app and select any parameters file with OPENWORM_MANUAL analysis type and and re-run the analysis. FEAT_MANUAL_CREATE should be the only option in the Analysis Start Point drop menu. This will execute the step FEAT_MANUAL_CREATE, and create a file with the extension basename_feat_manual.hdf5 with the same contents as basename_features.hdf5 but with the manually joined indexes. You can then run the analysis ticking the Is Manually Edited? box and selecting openworm as Feature Type.
W : label selected box as Single Worm.
C : label selected box as Worm Cluster.
B : label selected box as Bad.
U : label selected box as Undefined.
J : Join both trajectories in the zoomed windows.
S : Split the selected trajectory at the current time frame.
Up key : select the top zoomed window.
Down key : select the bottom zoomed window.
[ : Move the the begining of the selected trajectory.
] : Move the the end of the selected trajectory.
+ : Zoom out the main window.
- : Zoom in the main window.
> : Duplicated the frame step size.
< : Half the frame step size.
Left key : Increse the frame by step size.
Right key : Decrease the frame by step size.
The extracted features are store in the files that end with featuresN.hdf5 if the tierpsy feature route was selected or in features.hdf5 if the openworm route was selected. You can visualize the features in different ways as shown below:
From the plotting window can either save the plots or export the data of individual features/trajectories into csv files. If you would like to compare the data of multiple experiments we strongly recommed you to use the Features Summary app. If you would like to work directly with the timeseries data we recommend you to use read the data using a scripting language like python using the packages pandas and pytables, or MATLAB following the examples in the tierpsy_tools repository.
Root Directory: Directory containing the previously calculated features files.Feature Type: Select between the features calculated using the OpenWorm Analysis Toolbox or Tierpsy Features.Use manually edited features?Tick if you want to collect data from manually edited trajectories. Only trajectories labelled as either worm or worm cluster would be used.Summary Type: Select what data is going to be collected from a video. Either a summary for each trajectory available (trajectory), a summary pooling all the data per video (plate), or multiple random subsamplings per video (plate_augmented).
The files will be located by doing a recursive search for matching the extension according to the table below.
| Feature Type | Is Manually Edited? | File Extension |
|---|---|---|
| tierpsy | Ticked | featuresN.hdf5 |
| tierpsy | Unticked | featuresN.hdf5 |
| openworm | Ticked | feat_manual.hdf5 |
| openworm | Unticked | features.hdf5 |
The results are saved into two separated .csv file located in the root directory. The first file, filenames_FEATURETYPE_SUMMARY_DATE.csv, contains the names of all the files found in the root directory. The is_good column is set to True if the file is valid and used in the summary. The second file, features_FEATURETYPE_SUMMARY_DATE.csv, contains the corresponding features summarized as described in the output files section. The two result files can be joined using the file_id column.