YSMR

Bacterial video tracking and analysis

Installation

Dependencies

Python 3.5 or higher

Packages:

• Matplotlib
• Numpy
• openCV v3 or v4; v2 untested (opencv-python or opencv-contrib-python)
• Pandas
• Scipy
• Seaborn

Optional:

• XlsxWriter

Files in this package:

• ysmr/
  • __init__.py
    • empty
  • __version__.py
    • version file
  • gsff.py
    • the gaussian-sum finite impulse response filter used by YSMR
  • helper_file.py
    • contains various functions used throughout YSMR
  • main.py
    • File with main functions of YSMR, namely ysmr() and analyse()
  • plot_functions.py
    • plotting functions which are used to create graphs
  • track_eval.py
    • tracking, selection, and evaluation functions of YSMR
  • tracker.py
    • the tracker used by YSMR
• .gitignore
  • Gitignore file
• LICENSE
  • The license under which YSMR is published
• README.md
  • this file
• YSMR.py
  • the file which starts YSMR

Usage

When first executed, ysmr() will set up a tracking.ini file, which it will then open and stop executing. We advise that you test the program afterwards with an example video to check basic functionality. Afterwards, you should go through the tracking.ini file and update the values for 'pixel per micrometre', 'frames per second', 'frame width', 'frame height' and 'rod shaped bacteria' before using it with your own video files. You will then see if further tweaks are needed.

For initial setup, we recommend to enable both the the 'debugging' and 'display video analysis' options and having a look at the various displayed conversion steps during tracking. This helps choosing better values for both 'threshold offset for detection' and 'adaptive double threshold'.

We strongly recommend asserting the validity of the generated results by generating some values by other means and directly comparing them to the ones generated by YSMR during initial setup. Other means could include tracking manually or using other tracking programs. Using the 'save video'

Explanation of tracking.ini file

Explanation of each setting in the tracking.ini file and the initial default setting. The tracking.ini file will be newly generated when missing or if it cannot be loaded correctly. The location of the file is assumed to be in the folder in which a script using ysmr() is executed, but ysmr() can take the location of the tracking.ini file as an optional argument.

BASIC RECORDING SETTINGS

• pixel per micrometre : 1.41888781
  • The ratio between pixels and micrometres in the video file.
  • Accepts a floating point number.
• frames per second : 30.0
  • The frames per second (fps) of the video file. Fallback value for when no fps is provided, for example when analysing .csv files directly.
  • Automatic fps detection can be disabled under 'advanced video settings': 'force tracking.ini fps settings'.
  • Accepts a floating point number.
• frame height : 922
  • The height of a frame in pixel. Fallback value for when no height dimension is provided, for example when analysing .csv files directly.
  • Accepts an integer value.
• frame width : 1228
  • The width of a frame in pixel. Fallback value for when no width dimension is provided, for example when analysing .csv files directly.
  • Accepts an integer value.
• white bacteria on dark background : True
  • If bacteria are displayed as white signals against a darker background, use 'True'. If the bacteria are darker than the average background, use 'False'.
  • Accepts 'True' or 'False'.
• rod shaped bacteria : True
  • If bacteria are rod shaped, use 'True'. If the bacteria are coccoidal, set it to 'False'. This is a convenience boolean switch between two presets for length/width ratios.
  • Further width and height adjustments are available at 'advanced track data analyses settings'.
  • Accepts 'True' or 'False'.
• threshold offset for detection : 5
  • Changes the grey value threshold which differentiates between bacteria and background. Decrease value if bacteria are small and/or are not detected. Increase value if background signals are detected as bacteria.
  • Accepts an integer value.

BASIC TRACK DATA ANALYSIS SETTINGS

• minimal length in seconds : 20.0
  • Minimum time threshold for track analysis. All tracks shorter than this will be discarded. If set to 0, all tracks will be accepted.
  • Accepts a floating point number.
• limit track length to x seconds : 20.0
  • Setting the value to 0 will disable the truncation.
  • Maximum time for track analysis. All tracks longer than this will be truncated to the set time. If advanced track data analysis settings: 'track length exactly' is set to False (default) and the truncated track is not as long as the specified time due to holes in measurement, the nearest time point below the limit will be used instead. If ' track length exactly' is set to True, tracks that are shorter than the time specified after truncation will be discarded.
  • Accepts a floating point number.
• minimal angle in degrees for turning point : 30.0
  • Minimal change in angle (0° to 360°) between two positions in order to be declared a turning point.
  • The difference in frames between the two comparison points are defined under 'advanced track data analysis settings': 'compare angle between n frames'.
  • Accepts a floating point number.
• extreme area outliers lower end in px*px : 2
  • Lower limit for area in pixel^2 which is not considered as bacteria. Tracks with an average area below this value will be discarded entirely in an initial step.
  • Accepts an integer value.
• extreme area outliers upper end in px*px : 50
  • Upper limit for area in pixel^2 which is not considered as bacteria. Tracks with an average area above this value will be discarded entirely in an initial step.
  • Accepts an integer value.

DISPLAY SETTINGS

• user input : True
  • When set to True, after file selection and before starting with the analysis a command line prompt will wait for confirmation (y/n) to proceed, so that the user has time to review the selected files. If set to False, the process will proceed immediately.
  • Accepts 'True' or 'False'.
• select files : True
  • When set to True, the user will be prompted to select files in a folder which will be used for analysis. When set to False, the path specified under test settings: 'path to test video' will be used. In any case, if ysmr() is called with file(s) as an optional argument, these will be used.
  • Accepts 'True' or 'False'.
• display video analysis : True
  • When set to True, the video analysis process will be displayed in a window.
  • When 'test settings': 'debugging' is set to true, will also display additional conversion steps.
  • Accepts 'True' or 'False'.
• save video : False
  • When set to True, selected tracks will be annotated in the original video.
  • This can only be performed when ysmr() starts out with a video file and not with an already processed .csv file.
  • Legend:
    • Green: motile bacteria
    • White: calculated turning point
    • Orange: immotile bacteria
  • Accepts 'True' or 'False'.

RESULTS SETTINGS

• rename previous result .csv : False
  • When set to True, previously generated tracking result .csv files with the same name as newly generated files will be renamed (i.e. nice_video.avi_list.csv to nice_video.avi_list191224133700.csv). When set to False, previous tracking result .csv files with the same name will be overwritten.
  • Accepts 'True' or 'False'.
• delete .csv file after analysis : False
  • When set to True, tracking result .csv files will be deleted after completion of analysis.
  • Accepts 'True' or 'False'.
• store processed .csv file : True
  • When set to True, processed tracking result .csv files containing selected tracks will be saved in result folder after analysis.
• store generated statistical .csv file : True
  • When set to True, generated .csv files containing general track statistics will be saved in result folder after analysis.
  • Accepts 'True' or 'False'.
• store final analysed .csv file : True
  • When set to True, processed tracking result .csv files containing selected tracks with calculated additional information will be saved in result folder after analysis.
  • Accepts 'True' or 'False'.
• split results by (turn points / distance / speed / time / displacement / perc. motile) : perc. motile
  • By which sub-category the generated violin plots should be split. The total will always be displayed.
  • Accepts 'turn points', 'distance', 'speed', 'time', 'displacement', and 'perc. motile'.
• split violin plots on : 0.0, 20.0, 40.0, 60.0, 80.0, 100.1
  • Values at which the selected category is split.
  • Lower value is inclusive, upper value is exclusive.
  • Accepts floating point numbers separated by a ','.
• save large plots : True
  • When set to True a plot with an overview of the position of the tracked bacteria throughout the video will be generated.
  • Accepts 'True' or 'False'.
• save rose plot : True
  • When set to True a graph in which the starting position of all tracks is set to (0,0) will be generated.
• save time violin plot : True
  • When set to True a violin plot of the track times will be generated.
  • Accepts 'True' or 'False'.
• save acr violin plot : True
  • When set to True a violin plot of the tracks arc-chord ratio will be generated.
  • Accepts 'True' or 'False'.
• save length violin plot : True
  • When set to True a violin plot of the tracks length will be generated.
  • Accepts 'True' or 'False'.
• save turning point violin plot : True
  • When set to True a violin plot of the tracks turning points will be generated.
  • Accepts 'True' or 'False'.
• save speed violin plot : True
  • When set to True a violin plot of the tracks average speed will be generated.
  • Accepts 'True' or 'False'.
• save angle distribution plot / bins: 36
  • Setting the value to 0 will disable the angle distribution plot.
  • When set to True, a histogram with the specified bins of all degrees of direction of travel will be generated.
  • Accepts 'True' or 'False'.
• save displacement violin plot : True
  • When set to true a violin plot of the maximal distance between all measured positions of each bacterium will be generated.
  • Accepts 'True' or 'False'.
• save percent motile plot : True
  • When set to true a violin plot of the percentage of time where the bacterium was motile will be generated.
  • Accepts 'True' or 'False'.
• collate results csv to xlsx: True
  • When set to true, tries to collate all files ending in _statistics.csv in the generated results folder into one .xlsx file.
  • Requires the optional xlsxwriter package.
  • Accepts 'True' or 'False'.

PLOT Y-AXIS LIMIT

• Minimal and maximal values for y-axis on plots.
  • When a limit is given, the y-axis minimal and maximal values are fixed.
  • When set to 'False', limits will be chosen based on values in the graph.
  • Accepts a floating point number or 'False'.
  • Example values:
    • turning point violin plot min : 0.0
    • turning point violin plot max : 1.7
    • length violin plot min : 0.0
    • length violin plot max : 250.0
    • speed violin plot min : 0.0
    • speed violin plot max : 20.0
    • time violin plot min : 0.0
    • time violin plot max : False
    • displacement violin plot min : 0.0
    • displacement violin plot max : 220.0
    • percent motile plot min : 0.0
    • percent motile plot max : 100.0
    • acr violin plot min : 0.0
    • acr violin plot max : 1.0

LOGGING SETTINGS

• log to file : True
  • When set to True, the logging output will be saved to a file.
  • Accepts 'True' or 'False'.
• log file path : ./logfile.log
  • The log-file save path.
  • Accepts text string.
• shorten displayed logging output : False
  • When set to True, the console logging output will be shortened to 'Time level-name PID message'
  • Accepts 'True' or 'False'.
• shorten logfile logging output : False
  • When set to True, the logfile logging output will be shortened to 'Time level-name PID message'
  • Accepts 'True' or 'False'.
• set logging level (debug/info/warning/critical) : debug
  • Set the logging level. Fallback value is 'debug'.
  • Accepts 'debug', 'info', 'warning', 'critical'.
• verbose : False
  • When set to True the log-level is set to debug and additional debug messages will be logged.
  • Accepts 'True' or 'False'.

ADVANCED VIDEO SETTINGS

• include luminosity in tracking calculation : False
  • When set to True, in addition to the x- and y-position of the bacteria, luminosity will be used as an additional dimension for tracking.
  • Accepts 'True' or 'False'.
• color filter : COLOR_BGR2GRAY
  • The colour filter conversion used by openCV. Should convert to a grey-scale image.
  • Accepts text string of openCV conversion flag or corresponding integer value.
• minimal frame count : 600
  • Minimal frame count of video files. Files with a shorter frame count will be skipped.
  • Accepts an integer value.
• stop evaluation on error : True
  • When set to True, if a presumed file reading error is encountered during video analysis, evaluation of the generated tracking result .csv file will be skipped.
  • Accepts 'True' or 'False'.
• list save length interval : 10000
  • Minimal length of tracking result object list before it will be stored on disc.
  • Accepts an integer value.
• save video file extension : .mp4
  • Specifies the file extension used when 'save video' is set to True.
  • Accepts a string.
• save video fourcc codec : mp4v
  • Specifies the four character code video codec used when 'save video' is set to True.
  • Possible codecs can be looked up at: http://www.fourcc.org/codecs.php
  • Accepts a string.
• adaptive double threshold : 2.0
  • Sets the higher threshold offset which is used for double adaptive thresholding.
  • The second adaptive threshold generates smaller thresholded areas. Areas of the original adaptive threshold which contain such smaller areas are kept, all others are discarded.
  • Setting 'debugging' and 'display video analysis' to True displays this intermediary step in an additional frame.
  • A positive value specifies the added offset for the second adaptive threshold.
  • Setting the value to 0 enables simple adaptive thresholding instead.
  • A negative value will instead disable adaptive thresholding and use simple grey mean value thresholding instead.
  • Accepts a floating point number.

ADVANCED TRACK DATA ANALYSIS SETTINGS

• maximal consecutive holes : 5
  • Maximal consecutively missing values in track. If a gap in measurements greater than specified is encountered, the track will be split at the gap and the parts re-analysed.
  • Accepts an integer value.
• maximal empty frames in % : 5.0
  • Maximal total percentage of gaps.
  • Accepts a floating point number.
• percent quantiles excluded area : 10.0
  • Setting the value to 0 will disable exclusion.
  • When a value other than 0 is given, the upper and lower quantile (i.e. here 10 % and 90 %) of average track area will be excluded.
  • Accepts a positive floating point number.
• try to omit motility outliers : True
  • When set to True, tracks will be split on distance values above the outer fence (3 * IQR plus the 75% quartile) of each track, as long as the total number of such events is below the threshold specified under 'stop excluding motility outliers if total count above percent'.
  • Accepts 'True' or 'False'.
• stop excluding motility outliers if total count above percent : 5.0
  • The limit for 'try to omit motility outliers'. If the percentage of calculated motility outliers compared to all data points surpasses the given percentage, 'try to omit motility outliers' will be retroactively disabled.
  • Accepts a floating point number.
• exclude measurement when above x times average area : 1.5
  • Setting the value to 0 will disable exclusion.
  • Data points with area measurements above x times the average area of the track will be discarded.
  • Accepts a floating point number.
• rod average width/height ratio min. : 0.125
  • Lower limit average width to height ratio when basic recording settings: 'rod shaped bacteria' is set to True. Example: the default value is equal to a ratio of 1:8.
  • Accepts a floating point number.
• rod average width/height ratio max. : 0.67
  • Upper limit average width to height ratio when basic recording settings: 'rod shaped bacteria' is set to True. Example: the default value is equal to a ratio of ~1:1.5.
  • Accepts a floating point number.
• coccoid average width/height ratio min. : 0.8
  • Lower limit average width to height ratio when basic recording settings: 'rod shaped bacteria' is set to False. Example: the default value is equal to a ratio of 1:1.25.
  • Accepts a floating point number.
• coccoid average width/height ratio max. : 1.0
  • Upper limit average width to height ratio when basic recording settings: 'rod shaped bacteria' is set to False. Example: the default value is equal to a ratio of 1:1.
  • Accepts a floating point number.
• percent of screen edges to exclude : 5.0
  • Setting the value to 0 will disable exclusion.
  • Exclude tracks if their average x- or y-position is within specified percent of the screen edges.
  • Accepts a floating point number.
• maximal recursion depth : 960
  • Setting the value to 0 will disable recursion.
  • Tracks will be split on erroneous data (advanced track data analysis settings: 'maximal consecutive holes' or 'try to omit motility outliers') and parts recursively analysed until the specified depth is reached.
  • Accepts an integer value.
• limit track length exactly : False
  • See basic track data analysis settings: 'limit track length to x seconds'.
  • When set to False and the truncated track is not as long as the specified time in 'limit track length to x seconds' due to holes in measurement, the nearest time point below the limit will be used instead. When set to True, tracks that are shorter than the time specified in 'limit track length to x seconds' after truncation will be discarded.
  • Accepts 'True' or 'False'.
• compare angle between n frames : 10
  • See basic track data analysis settings: 'minimal angle in degrees for turning point'
  • Difference in frames between which position of bacteria and corresponding angle will be measured.
  • Time difference (measured in frames) between bacterial position in between which angle is measured.
  • Accepts an integer value.
• force tracking.ini fps settings : False
  • When set to true, uses the fps value provided in the tracking.ini file, instead of attempting to read it from the video file.
  • Accepts 'True' or 'False'.

GAUSSIAN-SUM FIR FILTER SETTINGS

• disable gsff : False
  • Whether to use the gaussian-sum finite impulse response filter.
  • For details and origin of the GSFF see Pak JM. Gaussian Sum FIR Filtering for 2D Target Tracking. DOI: 10.1007/s12555-018-0938-4
  • Accepts 'True' or 'False'.
• number of LSFFs: 3

  • How many least-square finite impulse response filters to use.

  • Horizons for the filters are calculated in the following way:

    • stepsize = (maximum_horizon_size - minimum_horizon_size ) / number_of_LSFFs
    • [lower_end + stepsize * i for i in range(1, number_of_lsffs + 1)]

  • Example for default values:

    • stepsize = (30 - 0) / 3 = 10
    • filter_horizons = [0 + 10 * 1, 0 + 10 * 2, 0 + 10 * 3] = [10, 20, 30]

  • Accepts a positive integer value larger than 1.

• minimum horizon size: 0
  • Lower end of frames for least-square finite impulse response filter.
  • This value will not be included as a horizon size.
  • See 'number of LSFFs' for explanation and examples.
  • Accepts a positive integer value larger than 0.
• maximum horizon size: 30
  • Longest horizon size in frames for least-square finite impulse response filter.
  • If set to 'False', will use current fps value instead.
  • See 'number of LSFFs' for explanation and examples.
  • Accepts a positive integer value larger than 1 or 'False'.

HOUSEKEEPING

• previous directory : ./
  • When selecting files, the last specified folder will be used as starting point.
  • This is updated automatically.
  • Fallback value is './'.
• shut down after analysis : False
  • Attempt to shut down the OS after analysis has finished.
  • Accepts 'True' or 'False'.

TEST SETTINGS

• debugging : False
  • When set to True, this will directly start with the analysis of the specified test video file. When display settings: 'display video analysis' is set to True, it will additionally display the thresholding steps of the analysed video file.
  • Accepts 'True' or 'False'.
• path to test video : Q:/test_video.avi
  • Accepts text string.

Citation

@article{Schwanbeck2020,
abstract = {BACKGROUND Motility in bacteria forms the basis for taxis and is in some pathogenic bacteria important for virulence. Video tracking of motile bacteria allows the monitoring of bacterial swimming behaviour and taxis on the level of individual cells, which is a prerequisite to study the underlying molecular mechanisms. RESULTS The open-source python program YSMR (Your Software for Motility Recognition) was designed to simultaneously track a large number of bacterial cells on standard computers from video files in various formats. In order to cope with the high number of tracked objects, we use a simple detection and tracking approach based on grey-value and position, followed by stringent selection against suspicious data points. The generated data can be used for statistical analyses either directly with YSMR or with external programs. CONCLUSION In contrast to existing video tracking software, which either requires expensive computer hardware or only tracks a limited number of bacteria for a few seconds, YSMR is an open-source program which allows the 2-D tracking of several hundred objects over at least 5 minutes on standard computer hardware. The code is freely available at https://github.com/schwanbeck/YSMR.},
author = {Schwanbeck, Julian and Oehmig, Ines and Dretzke, Jer{\^{o}}me and Zautner, Andreas E and Gro{\ss}, Uwe and Bohne, Wolfgang},
doi = {10.1186/s12859-020-3495-9},
issn = {1471-2105},
journal = {BMC Bioinformatics},
keywords = {2D object tracking,Bacterial motility,Multi-object tracking,Open-source software,Python,Video microscopy,Video tracking,openCV},
month = {apr},
number = {1},
pages = {166},
pmid = {32349658},
publisher = {BMC Bioinformatics},
title = {{YSMR: a video tracking and analysis program for bacterial motility.}},
url = {https://bmcbioinformatics.biomedcentral.com/articles/10.1186/s12859-020-3495-9 http://www.ncbi.nlm.nih.gov/pubmed/32349658},
volume = {21},
year = {2020}
}

Acknowledgements

We would like to thank Prof. Burkhard Morgenstern for reading the manuscript and supporting the project. We would like to thank Avril von Hoyningen-Huene for proofreading and providing corrections for the manuscript. The original tracker.py was taken with permission from Adrian Rosebrock (adrian@pyimagesearch.com) from https://www.pyimagesearch.com/2018/07/23/simple-object-tracking-with-opencv/