Questions operating Tierpsy

[NeriKafkafi]

Dear all,
We installed Tierpsy 1.5.1 on a Win10 PC, and are interested in using it to analyze our experiments with multiple worms. At this point we are mainly interested with trajectories and speeds, although we plan to look also into skeleton movements in the future. Trying Tierpsy using the comprehensive tutorial, we nonetheless have a few principle questions:

1. There are 13 Analysis Types available in the Set Parameters window, yet only 6 in the table in the HOWTO tutorial. It is not clear which we should use at this point.
2. In the Tierpsy Tracker Viewer, the operation is not entirely clear from the movies and the tutorial. For example, after several manual corrections we still end up with incorrect trajectories and "jumps" when two worms or more pass closely together.
3. It is not clear if we can use the WCON Viewer, or any other software, to view and analyze trajectories and speeds in our result files.
4. In order to explore and analyze trajectories and speeds on our own, we tried to import the HDF5 datasets in either Python (conda packages) or Wolfram Mathematica (which supports HDF5 import). However, in both case we get some issues with NaN values and unsupported bitfield datatype, possibly because of incorrect results due to questions 1 and 2.
   Thanks in advance!

[luigiferiani]

Hi @NeriKafkafi ,

1. Sorry, the documentation is lagging a bit. I'd suggest using the analysis type TIERPSY.
2. The viewer does allow you to 'join' trajectories together. Tierpsy loses identity of worms when they touch/get too close, so in the viewer you can tell that e.g. the worm with ID 10 is the same as the worm with ID 1. This will not retrieve frames in which the worm was not tracked or skeletonised due to two worms touching, so you might still have holes in the trajectory. Is this what you're experiencing?
3. You should be able to use Tierpsy Tracker Viewer to plot the trajectories for a few frames behind the current frame: there is a drop-down menu that is usually set to draw boxes, you can set it to draw trajectories There is no functionality at the moment in Tierpsy to plot all the trajectories. The viewer also allows you to plot the speed (any feature actually): locate the PLOT button in the viewer, select the feature of choice in the drop down menu to its left, and press plot. This will open a new window, where you can choose to plot either the feature for one worm only (the one currently selected in the viewer), all the worms, and to choose between timeseries and histogram plot.
4. opening Tierpsy's results with python or other programs is the right way to try doing all things not supported by Tierpsy :) especially to work on the time series directly. NaN values are to be expected - they usually happen whenever worms were not skeletonised. I am not familiar with unsupported bitfield datatype issue, did this happen with Python or Mathematica? we have no experience with the latter.

As a final note, in case you do not need to analyse the speed over time during your video but are interested in cumulative/summary measurements, that's where you can use get feature summaries to get IQR and 10th, 50th, 90th percentile of the distribution of each of the features measured by Tierpsy (the distribution is either created on a worm-by-worm basis or by pooling all the worms together)

[NeriKafkafi]

Hi @NeriKafkafi ,

1. Sorry, the documentation is lagging a bit. I'd suggest using the analysis type TIERPSY.

Thanks! This helped me with finding a parameter combination that worked up to the Tierpsy Tracker Viewer (see below). The explanation of the optional values for "Analysis Type", "Parameter File", and "File Pattern to Include" is rather confusing in the github "how to use" and "example data".

2. The viewer does allow you to 'join' trajectories together. Tierpsy loses identity of worms when they touch/get too close, so in the viewer you can tell that e.g. the worm with ID 10 is the same as the worm with ID 1. This will not retrieve frames in which the worm was not tracked or skeletonised due to two worms touching, so you might still have holes in the trajectory. Is this what you're experiencing?

Thanks. I was under a false impression that the Viewer was intended to manually resolve also "clusters" of worms touching. The explanation for the Viewer is sketchy but I think I now figured out most of it. I'm still not sure about "joined index"/"manual index", "worm cluster"/"single worm". Also there are two unnamed boxes for numbers to the right of the "FPS display" box. What are those?

3. The viewer also allows you to plot the speed (any feature actually): locate the PLOT button in the viewer, select the feature of choice in the drop down menu to its left, and press plot. This will open a new window, where you can choose to plot either the feature for one worm only (the one currently selected in the viewer), all the worms, and to choose between timeseries and histogram plot.

I opened a PLOT window for the speed, resized it, and at some point clicked "save CSV". At this point the window froze with everything else behind it. I couldn't make it respond or close even using CTRL+ALT+DELETE (the Windows Task Manager). Unfortunately this was before I pressed SAVE so I lost the Viewer joined trajectories. I'll try to reproduce this bug next week.

Neri

[luigiferiani]

Hi @NeriKafkafi,

mostly the viewer can annotate whether there's a cluster or not, or if a tracked object is not a worm but not resolve the issue - only deals with identity of worms.

The two unmarked boxes to the right of the fps display are colour limit values: If you tick the box Color Features the viewer will colour-code the boxes around the worms (or the trajectories behind them) according to the numeric value of the feature selected in the drop down menu. The two unmarked boxes allow you to pin two numeric values to the lower and upper bound of the colormap.

Really sorry the crash made you lose manually annotated data - that is painful. Do let me know if you manage to reproduce the bug: it's something that hasn't happened to us yet.

[asafgat]

Hi @luigiferiani,

1. When we batch multiple files we see the process of batching but the percentage bar is stuck on at zero. we checked and the files are being processed, but when the process is finished it doesn't continue to the next files ( if we set it to batch more files than the computer core ), and if there are less files than the computer core, after it finished processing- the dialogue box stays open forever unless you manually close it.
2. There are a couple of issues with the PLOT option and the csv export-
   -The timeline of each worm changes. we sometimes see Nan when we lose the worm - which is okay and the way it should be - but other times we see jumps in the timeline column. for example it jumps from second 245 straight to second 360.
   -The ending second varies between every worm (even in the same file), every worm has a different second in the last box of the timeline column in the csv file.
   how come not all the worms in a specific file have the same timeline vector? is there a way to change it manually so that the timeline is identical in all worms?
3. There are a lot of features that the 'Get Feature Summary' gives you, but we could not find explanations to what these features mean. for example, what is the difference between 'speed' and 'd_speed'? is there anywhere that we can read the explanation for each and every variable?

Thank you very much,
Asaf

[luigiferiani]

Hi @asafgat,

1. Does this happen also if the option to use a temporary directory is disabled? the temporary directory is useful if you have files that are on a network share, as Tierpsy copies the files, works locally, and updates the results at the end. This makes Tierpsy more robust against instabilities of the network, but it's not necessary if the files reside on the machine that is running Tierpsy. We are aware of issues on Windows platforms with copying the finished files away from the temporary folder and moving on to analyse new videos when the files are local.
2. Because of how Tierpsy work, there is a difference if Tierpsy has not tracked a worm in a certain frame vs if the worm was tracked, but not successfully skeletonised. If a worm was not tracked in a frame, there will be no entry with that id and frame number in the timeseries/trajectories tables. If a worm was tracked, but not skeletonised, there will be NaNs in the features. But the x,y coordinates of the worm, at least as a centroid, should still be there.
   For the jump in timestamp: were the worm ids manually curated to join trajectories that had been unduly split by the tracking algorithm? if a worm is lost at second 245, and then this trajectory is joined with another one (of the same physical worm) that starts at second 360, the result in the csv would be what you describe.
   The ending second for each worm will be the last second in which the worm was tracked, as if the worm is not tracked in the following frames there is no corresponding entry in the tracking table.
3. 'Get Feature Summary' starts from a much smaller number of features that are measured throughout the video, and creates the final set of features programmatically. You can find the explanation of this procedure (and the explanation of how the feature names are formed and what each token mean) here (the part about /feature_stats applies to the summaries as well) and in a more formal way in this paper here (Results 3a, 3b, and the supplementary materials).
   For the particular example you mentioned, d_speed is the time derivative of the speed.

I hope that helped,
Luigi

[asafgat]

Hi @luigiferiani,
Thank you for your quick reply, and sorry for my delay :)

1. Actually, we performed the tracking when the temp directory option was disabled. Should I try to track when it is enabled maybe?...
2. Thanks, this explains a lot.
3. Ok, I found what I was looking for..

Indeed it was very helpful!
Thanks
Asaf

[luigiferiani]

Hi @asafgat,

regarding 1 - I'm afraid you are the first one that reports that happening with the temp directory disabled :(

Could you give me some more details, to see if this can be debugged? mainly

• which version of Tierpsy,
• which OS,
• basic specs of the machine,
• how large are the files at the end of the analysis,
• whether the data are on a local or remote folder,
• what does the progress report show when Tierpsy gets stuck?

Also if that agrees with you I'd be interested to check one of the featuresN.hdf5 files, to see if the analysis really finished or got stuck close to the very end (if you cannot, or prefer not to, share a featuresN.hdf5 file I could give you instructions on what I'd like to check?)

Cheers,
Luigi

[asafgat]

Hi @luigiferiani,

• This is Tierpsy version 1.5.1, windows 10.

• I used 3 different machines with slightly different specs - it happened in all 3.
  for example- one computer specs:
  Intel i7-6700CPU 3.4 GHz with 32 GB (RAM), 64bit.

• The masked videos are between 250 to 700 Mb (most around ~450), the results files (except the 'intensities') range between 40-270MB, the 'intensities' result files are lighter - 3-30MB.

• Because we had to analyze many files, I splitted to many computers and locations, so I think I tried to analyze files that were located on desktop, also some that were located in an external hard drive & some that were in a shared dropbox folder :)

• The dialog box looks like that:

• I do want to mention that my original videos are in avi format, captured by the WormLab MBF Bioscience software.

I don't mind sharing one file - can I send by e-mail?
Thanks,
Asaf