Supplemental Information TaxisPy: A Python-based Software for the Quantitative Analysis of Bacterial Chemotaxis Miguel Á. Valderrama-Gómez 1 * @ , Rebecca A. Schomer 1 *, Michael A. Savageau 1,2 , Rebecca E. Parales 1 . 1 Department of Microbiology & Molecular Genetics, University of California, Davis, USA 2 Department of Biomedical Engineering, University of California, Davis, USA. * Authors equally contributed to this work. @ Corresponding Author: [email protected]1. Supplementary Tables Table S1. Parameters involved in a quantitative chemotaxis analysis by TaxisPy. Parameters required by the software in each one of its different windows are listed below, as well as a short description and their nominal values. Even though the number of parameters appears to be large, TaxisPy provides intuitive tools designed to guide the selection of specific values. Key parameters are marked by a blue asterisk (*). Tab Parameter Description Nominal Value File Path Indicates location of folder containing frames -- Frames Indicates range of frames to be analyzed 0 - 410 frames for P. putida videos; 0 - 202 frames for E. coli videos. Frames/s Frame rate of video. Corresponds to the ratio between the total number of frames of a video and its duration. 20.3 frames/s Pixels/Micron It is an indication of the resolution of the video camera. Can be determined by taking a snapshot of a scale and counting the number of pixels contained in one micron. 6 pixels/micron Feature Identificati on Diameter* Diameter of an average cell in pixels. It should be an odd integer. 25 pixels Min. Mass* The minimum integrated brightness. This is a crucial parameter for eliminating spurious features. 2000 1
Transcript
Supplemental Information
TaxisPy: A Python-based Software for the Quantitative Analysis of Bacterial Chemotaxis
Miguel Á. Valderrama-Gómez1*@, Rebecca A. Schomer1*, Michael A. Savageau1,2, Rebecca E. Parales1.
1Department of Microbiology & Molecular Genetics, University of California, Davis, USA 2Department of Biomedical Engineering, University of California, Davis, USA.* Authors equally contributed to this work.@ Corresponding Author: [email protected]
1. Supplementary Tables
Table S1. Parameters involved in a quantitative chemotaxis analysis by TaxisPy. Parameters required by the software in each one of its different windows are listed below, as well as a short description and their nominal values. Even though the number of parameters appears to be large, TaxisPy provides intuitive tools designed to guide the selection of specific values. Key parameters are marked by a blue asterisk (*).
Tab Parameter Description Nominal Value
File
Path Indicates location of folder containing frames --
Frames Indicates range of frames to be analyzed0 - 410 frames for P. putida videos; 0 - 202 frames for E. coli videos.
Frames/sFrame rate of video. Corresponds to the ratio between the total number of frames of a video and its duration.
20.3 frames/s
Pixels/Micron
It is an indication of the resolution of the video camera. Can be determined by taking a snapshot of a scale and counting the number of pixels contained in one micron.
6 pixels/micron
Feature Identification
Diameter* Diameter of an average cell in pixels. It should be an odd integer. 25 pixels
Min. Mass*The minimum integrated brightness. This is a crucial parameter for eliminating spurious features.
2000
Invert? The software looks for bright features. Set to true if cells are dark objects. TRUE
Trajectories
Max. Disp. The maximum distance cells can move between frames 25 pixels
Min. # Frms Minimum number of frames for a trajectory to be considered by the software 20 frames
Disp. Thrshld
Minimum length in % that a trajectory should have to be shown. A value of 0% shows all trajectories, while 100% shows the longest trajectory.
0%
1
Tab Parameter Description Nominal Value
Frame Rng Controls the frame range for which trajectories are shown. --
Visualization
Trajectory Trajectory to be shown in a two-dimensional plot and highlighted in the video. Last trajectory
Frame # Controls the frame that is shown 0
Parameter Determination (Analysis of Individual
Trajectories)
Trajectory # Trajectory for which motion analysis is performed Last trajectory
Time Range Time range in which motion analysis is performed
tin – tf. These variables correspond to initial and final time points of the trajectory, respectively.
# Frames Number of subsequent frames used to calculate an average velocity 4 frames
# Smooth Number of times (cycles) that the average velocity is calculated 3 cycles
Acc. ThrhldAcceleration threshold that a trajectory should surpass for the software to identify a tumble. Absolute acceleration values are considered.
10 micron/s/s
Parameter Determination
(Genetic Algorithm)
# Trajectories* Number of trajectories in the training set 10
Trajectory #* ID of a given trajectory within the training set random
# Chng. Dir.* Number of tumbles or changes of direction exhibited by a given trajectory within the training set
0
Tumbling Frequencies # Frames* Number of subsequent frames used to calculate
an average velocity 4 frames
# Smooth* Number of times (cycles) that the average velocity is calculated 3 cycles
Acceleration*Acceleration threshold that a trajectory should surpass for the software to identify a tumble. Absolute acceleration values are considered.
10 micron/s/s
Velocity*Minimum velocity that a cell should exhibit to be considered in the calculation of the tumbling frequency
4 micron/s
Dsplcmt, %*Minimum displacement (in %) that a trajectory should exhibit to be considered in the calculation of the tumbling frequency
10%
Max. Chng Dir*
Maximum number of tumbles that a trajectory can exhibit to be considered in the calculation of the tumbling frequency. Trajectories with a higher number of tumbles are ignored.
10
Frame Rng Frame range for which the tumbling frequency is calculated.
0 - 410 frames for P. putida videos; 0 - 202 frames for E. coli videos.
2
Tab Parameter Description Nominal Value
T. Int. (s)* Time interval used to calculate tumbling frequencies 1 second
Chg. Dir. (1/s) Tumbling frequency used to estimate adaptation time. 0.45 tumbles/second
Table S2. Training sets stemming from control cultures of P. putida. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S7. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
Table S3. Training sets stemming from stimulation experiments of P. putida cultures with 10 µM shikimate. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S7. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
Table S4. Training sets stemming from stimulation experiments of P. putida cultures with 50 µM shikimate. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S7. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
Table S5. Training sets stemming from stimulation experiments of P. putida cultures with 100 µM shikimate. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S7. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
Table S6. Training sets stemming from stimulation experiments of P. putida cultures with 1000 µM shikimate. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S7. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
Table S7. Key parameter values used in the analysis of P. putida stimulation experiments. The condition-specific parameter values listed below –#Frames, #Smooth and Acc. Threshold– were automatically determined using a genetic algorithm and corresponding training sets (Tables S2 to S6). Values for both Tumbling Freq. and Min. Tumbling Freq. were calculated employing those condition-specific parameter values and the tab Tumbling Frequencies of TaxisPy. Tumbling Freq. refers to the cellular tumbling frequency during the first 20 seconds. On the other hand, Min. Tumbling Freq. refers to the minimum cellular tumbling frequency exhibited by the culture during the same period of time. Time intervals of 5 seconds were used to calculate the temporal evolution of the tumbling frequency in that case. Note that columns Nr. Traj. contain the number of trajectories used to calculate either Tumbling Freq. or Min. Tumbling Freq.
Condition Video ID # Frames # Smooth Acc. Threshold Tumbling
Freq.Nr.
Traj.Min. Tumbling
Freq.Nr.
Traj.
ControlCB0 2 4 167 0.46 257 -- --
CB1 3 4 67 0.36 163 -- --
CB2 2 5 100 0.43 222 -- --
10 µMshikimate
shik9 4 3 60 0.26 313 0.24 116
shik10 2 5 103 0.33 119 0.26 48
shik11 2 3 140 0.26 162 0.18 42
50 µMshikimate
shik12 5 4 80 0.07 263 0.07 71
shik13 5 2 103 0.16 151 0.08 38
shik14 2 5 140 0.27 413 0.14 73
100 µMshikimate
shik6 4 4 71 0.07 233 0.06 52
shik7 2 4 160 0.06 142 0.03 35
shik8 5 5 140 0 109 0 23
1000 µMshikimate
shik3 4 3 80 0.13 278 0.04 38
shik4 5 4 60 0.05 133 0.02 46
shik5 3 5 120 0.03 149 0.01 33
8
Table S8. Training sets stemming from control cultures of E. coli. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S11. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
ControlRPMSB_2 @ 1 min RPMSB_3 @ 5 min RPMSB_4 @ 15 min RPMSB_5 @ 20 min
Table S9. Training sets stemming from stimulated cultures of P. putida during the first 10 minutes of adaptation. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S11. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
1 min - 10 MinRPMSB_26 @ 1 min RPMSB_27 @ 5 min RPMSB_42 @ 10 min
Table S10. Training sets stemming from stimulated cultures of P. putida after 15, 20 and 40 minutes of adaptation. Training sets were used to identify optimal values for the acceleration threshold as well as for smoothing parameters –# Frames and # Smooth–, which are reported in Table S11. Training sets for each video were generated using tabs Trajectories and Visualization of TaxisPy.
15 min - 40 MinRPMSB_43 @ 15 min RPMSB_30 @ 20 min RPMSB_45 @ 40 min
Table S11. Key parameter values used in the analysis of the E. coli adaptation experiment. The condition-specific parameter values listed below –#Frames, #Smooth and Acc. Threshold– were automatically determined using a genetic algorithm and corresponding training sets (Tables S9 to S10). Values for Tumbling Freq. were calculated employing those condition-specific parameter values and the Tumbling Frequencies tab of TaxisPy. Tumbling Freq. refers to the cellular tumbling frequency during the first 10 seconds. Column Nr. Traj. contains the number of trajectories used in the calculations.
Condition Video ID # Frames # Smooth Acc. Threshold
Tumbling Freq. Nr. Traj.
Control @ 1 min RPMSB_2 1 1 540 0.33 276
Control @ 5 min RPMSB_3 1 5 500 0.26 216
Control @15 min RPMSB_4 1 5 600 0.29 238
Control @ 20 min RPMSB_5 1 3 887 0.3 354
Stimulated @ 1 min RPMSB_26 2 5 320 0.01 420
Stimulated @ 5 min RPMSB_27 3 2 400 0 315
Stimulated @ 10 min RPMSB_42 3 5 600 0 137
Stimulated @ 15 min RPMSB_43 2 4 200 0.11 253
Stimulated @ 20 min RPMSB_30 1 2 600 0.25 86
Stimulated @ 40 min RPMSB_45 2 5 160 0.22 308
2. Supplementary Figures
12
Figure S1. Number of trajectories detected by TaxisPy as a function of time for the P. putida experiments. Panel A shows the number of trajectories detected by TaxisPy as a function of time for the control condition. Panels B to E show the same temporal evolution for different concentrations of shikimate. The three lines in each panel correspond to each one of the triplicate videos recorded for each condition. The orange solid line in panel B is drawn only over ten seconds due to technical problems with the corresponding video which limited its length. The shaded blue areas represent the first 20 seconds of each video used to determine the minimum average tumbling frequency.
3. Installing Docker
13
3.1 What is Docker?
Docker is a computer program that performs operating-system-level virtualization. It is used to run software packages called containers. Containers are isolated from each other and bundle their own application, tools, libraries and configuration files. All containers are run by a single operating-system kernel and are thus more lightweight than virtual machines. Containers are created from images that specify their precise contents.
3.2 Docker Desktop for Mac
If you are a Mac user, installing Docker is straightforward. The following instructions were adapted from the Docker webpage :
1. Create a Docker ID to access Docker Hub.2. Download the installer from Docker Hub.3. Double-click Docker.dmg to open the installer, then drag the Docker icon to the Applications
folder.
4. Double-click Docker.app in the Applications folder to start Docker.
5. Alternatively, Docker.app can be found using the Spotlight Search function of Mac.
You are prompted to authorize Docker.app with your system password after you launch it. Privileged access is needed to install networking components and links to the Docker apps.
The Docker menu in the top status bar indicates that Docker Desktop is running, and accessible
from a terminal: . Log in to your account to be able to pull Docker images.
Refer to the Docker Webpage for Mac for general information and troubleshooting
3.3 Docker Desktop for Windows
The following instructions were adapted from the Docker webpage :
1. Create a Docker ID to access Docker Hub.2. Download the installer from Docker Hub.3. Double-click Docker Desktop Installer.exe to run the installer.4. Follow the instructions on the installation wizard to accept the license, authorize the installer,
and proceed with the install. When asked whether to use Linux or Windows containers, select Linux containers, since TaxisPy is a Linux-based image. When prompted, authorize the Docker Desktop Installer with your system password during the installation process. Privileged access is needed to install networking components, links to the Docker apps, and manage the Hyper-V VMs.
5. Click Finish on the setup complete dialog and launch the Docker Desktop application.6. Docker Desktop does not start automatically after installation. To start Docker Desktop,
search for Docker, and select Docker Desktop in the search results.
7. When the whale icon in the status bar stays steady, Docker Desktop is up-and-running, and is accessible from any terminal window.
After installing the Docker Desktop app, you also get a pop-up success message with suggested next steps, and a link to the documentation. Log in to your account to be able to pull Docker images.
3.4 Docker Toolbox for Windows 10 Home and earlier
If you are a Windows user and Docker Desktop is not available for your machine, you can install Docker Toolbox instead, which is a legacy desktop solution. Docker Toolbox provides a way to
16
use Docker on Windows systems that do not meet minimal system requirements for the Docker Desktop for Windows app. The following instructions were adapted from the Docker webpage.
1. Make sure your Windows system supports Hardware Virtualization Technology and that it is enabled. This step is hardware dependent. A quick Google search will provide you with the required steps to enable the Hardware Virtualization Technology in case it is not enabled by default. No additional software is required in this step.
2. Download the latest version of Docker Toolbox. Go to Toolbox Releases and download the latest .exe file.
3. Install Docker Toolbox by double-clicking the installer. The installer launches the “Setup – Docker Toolbox” dialog. If Windows security dialog prompts you to allow the program to make a change, choose Yes. The system displays the Setup – Docker Toolbox for Windows wizard.
4. Press Next to accept all the defaults and then Install. Accept all the installer defaults. The installer takes a few minutes to install all the components
5. When notified by Windows Security that the installer will make changes, make sure you allow the installer to make the necessary changes. When it completes, the installer reports it was successful
6. Uncheck “View Shortcuts in File Explorer” and press Finish. The installer adds Docker Toolbox, VirtualBox, and Kitematic to your Applications folder and creates respective icons on your Desktop.
18
7. Click the Docker QuickStart icon to launch a pre-configured Docker Toolbox terminal. If the
system displays a User Account Control prompt to allow VirtualBox to make changes to your computer. Choose Yes. The terminal does several things to set up Docker Toolbox for you. When it is done, the terminal displays the $ prompt.
4. Using the Docker Image for TaxisPy
4.1 Basic Usage of the TaxisPy Docker Image
To use TaxisPy via Docker follow these simple steps:
1. Install Docker 2. Open a terminal window (macOS and Linux) or Command Prompt (Microsoft Windows)3. Download the TaxisPy image by executing the following command line on the terminal
window:
docker pull m1vg/taxispy
4. Create a container by executing the following command line:
docker run -d -p 8888:8888 m1vg/taxispy
5. Open http://localhost:8888 in a browser window. If you are a Windows user and the webpage cannot be loaded, refer to additional instructions for Windows in section 4.4.
The following page should appear after performing step 5
4.2 Writing and Reading Files on the Host Computer from a Docker Container
The command docker run -d -p 8888:8888 m1vg/taxispy initializes a docker container that cannot write or read files of the host computer (i.e., your own computer). Consequently, created notebooks and all changes to existing notebooks/files within the container will be lost after stopping the container. In order to be able to permanently write notebooks in the memory of the host computer, additional flags are required when creating a Docker container from the TaxisPy Image. An option is to use the −−mount flag:
On Mac/Linux:
docker run -d -p 8888:8888 −−mount type=bind,source=/Users,target=/Documents/host m1vg/taxispy
On Windows:
docker run -d -p 8888:8888 −−mount type=bind,source=//c/Users,target=/Documents/host m1vg/taxispy
This command mounts the “/Users” directory (or //c/Users on Windows) of the host machine in the folder “/Documents/host” of the Docker container. Files saved under this directory will remain after stopping TaxisPy. If you want to mount a specific folder from your machine, replace “/Users” by the location of the desired folder, for example “/Users/test_user/Documents”.
4.3 Stopping Docker Containers
After finishing your work with TaxisPy, you may want to stop the container by executing the following command from a terminal window:
Running containers can be listed by executing the command docker container ls:
Specific containers can also be manually stopped and removed by using the commands docker stop along with docker rm. We will first stop and then remove the container with the name “zealous_elbakyan”:
4.4 Instructions for Windows 10 Home Users
Home editions of Windows do not support Docker Desktop. Instead, Docker Toolbox needs to be installed. If you are a Windows 10 Home user, the commands to download TaxisPy, run and stop containers need to be executed from within the Docker QuickStart Terminal:
Look for the “Docker QuickStart Terminal” icon on your desktop and open it. A Terminal window pops up. Execute the following commands to:
Pull TaxisPy Image: docker pull m1vg/taxispy
Start Container: docker run -d -p 8888:8888 m1vg/taxispy
Start Container with Access to Host Files:
docker run -d -p 8888:8888 −−mount type=bind,source=//c/Users,target=/Documents/host m1vg/taxispy
After Docker has been installed on your operating system and a TaxisPy container has been initialized, you will be able to run TaxisPy by accessing the address http://localhost:8888 (or http://192.168.99.100:8888 on a Windows Home machine) in an internet browser. Please refer to the Notebook ReadMe_TaxisPy_0.1.6.3.ipynb (Note that 0.1.6.3 refers to the TaxisPy version and will be changed as new versions are released) for further instructions.
The following window should appear after opening the ReadMe notebook:
You should be able to see the following window after starting the user interface of TaxisPy:
Similarly, the following window should appear when initializing an instance of the video Splitter:
23
Please refer to the tutorial contained within the Docker Image under /Tutorial/Tutorial_TaxisPy.ipynb for further details on how to use the functionalities provided by TaxisPy:
24
6. Frequently Asked Questions
Using Docker
Question 1: The image size of the current version of TaxisPy is 2.24 GB. This is unexpectedly large. Do I have other options to install TaxisPy? Where can I find the source code of TaxisPy?
Answer 1: The TaxisPy Docker image is relatively large because it contains all the software dependencies required by TaxisPy, including the ffmpeg software used to split videos into frames. The Docker image is ideal for users with limited programming knowledge. More experienced users can find the TaxisPy’s source in its GitHub repository under: https://github.com/m1vg/taxispy
Question 2: What is the difference between a Docker image and a container?
Answer 2: When creating TaxisPy, we started with a base image (jupyter/minimal-notebook). We boot it up, made changes and those changes were saved in layers to form the TaxisPy image. An image is an immutable file.
When you run a TaxisPy image using the command:
docker run m1vg/taxispy
a container from that image is created. In other words, a container is an instance of an image. You can have many running containers of the same image. However, each container will need its own address. If you wish to start two TaxisPy containers, use for instance the following commands:
Container 1: docker run -d -p 8888:8888 m1vg/taxispyContainer 2: docker run -d -p 8889:8888 m1vg/taxispy
Each container will be available at its respective address:
All changes performed to internal files of a container will be lost after the container is stopped.
Question 3: How do I test my docker installation?
Answer 3: Test that your installation works by running the hello-world Docker image. Open a terminal window (macOS and Linux) or Command Prompt (Microsoft Windows) and execute the following command:
Question 4: I am a Mac user. While trying to pull the TaxisPy image, I get the error message:
‘pull m1vg/taxispy’ is not a docker command.
Answer 4: It seems like your system was not correctly configured to run docker commands. Try using the following commands instead:
/usr/local/bin/docker pull m1vg/taxispy
If this works, replace all instances of docker by /usr/local/bin/docker.
Question 5: I am a Windows user. I am getting an error message while trying to mount a host directory using the --mount flag.
Answer 5: Make sure that Docker has access to the Drive you are trying to access. In the System Tray, you should have the Docker whale swimming. Right click on the icon and select Settings:
26
In the Settings dialog window that comes up, click on Shared Drives. This should be able to list the drives that you have available on your Windows machine. Use the checkbox to select the drive you want to expose to Docker:
In this example, only the Drive D is available to Docker.
Question 6: What exactly does the --mount flag do? What does granting access to files on the host computer mean?
Answer 6: When you use the --mount flag:
docker run -d -p 8888:8888 --mount type=bind,source=/Users,target=/Documents/host m1vg/taxispy
a file or a directory on the host machine (i.e., your own computer) is mounted into a container. In the code above, the directory /Users is mounted into the folder /Documents/host of the TaxisPy container. This means that TaxisPy can read and write files into this directory, as shown in the figure below:
27
Alternatively, you can restrict the TaxisPy container to only read files by using the variable readonly:
docker run -d -p 8888:8888 --mount type=bind,source=/Users,target=/Documents/host,readonly m1vg/taxispy
Note that the --mount flag is necessary if you want to analyze videos saved on your own computer.
Question 7: I’m a Windows user. Is TaxisPy a Windows- or a Linux-based image?
Answer 7: TaxisPy is a Linux-based image.
Using TaxisPy
Question 8: I would like to reproduce the results presented in this paper. Where can I find the frames for the P. putida and E. coli experiments? Answer 8: This paper analyzed a total of 25 videos, 10 for E. coli and 15 for P. putida. Corresponding frames can be found in the folders /Ecoli_Aspartate and /Pseudomonas_Shikimate of the TaxisPy Image, respectively. Refer to the ReadMe file located in each folder and follow the instructions provided.
Question 9: I have a video that I would like to analyze using TaxisPy. How can I use the Splitter provided by TaxisPy to generate the required frames for the analysis?
Answer 9: First, you will need to start a TaxisPy container with access to the directory where your video is located. Let’s assume that the video you would like to analyze (e.g., myEcoli1.mov) is located in the folder /Users/mustermann/videos. Then, you should start a TaxisPy container using the following command:
docker run -d -p 8888:8888 --mount type=bind,source=/Users/mustermann/videos,target=/Documents/host m1vg/taxispy
This command will mount the specified host directory into the directory /Documents/host of the TaxisPy container. In other words, all the contents of the host folder /Users/mustermann/videos will be available through the directory /Documents/host of the TaxisPy container.
Open the notebook: ReadMe_TaxisPy_0.1.6.3 located within the TaxisPy container for instructions on how to launch the Splitter:
28
After initializing an instance of the Splitter, provide source and output directories. Following the example, you should provide the directory /Documents/host/myEcoli1.mov as the Source directory. The Output directory could be for instance: /Documents/host/myFrames. Note that the Output directory will be created by the Splitter if it does not exist.
Then, click on Split. If the Splitter was successful, you should see the word Success! Under the Split button:
Additionally, the folder /Documents/host/myFrames will contain the desired frames:
29
Question 10: I have a set of frames on my computer that I would like to analyze using TaxisPy. How can I load the frames into the software?
Answer 10: First, you need to start a TaxisPy container with access to the directory where your frames are located. Let’s assume that the folder containing the frames you would like to analyze (e.g., /myFrames) is located in the directory /Users/mustermann/videos. Then, you should start a TaxisPy container using the following command:
docker run -d -p 8888:8888 --mount type=bind,source=/Users/mustermann/videos,target=/Documents/host m1vg/taxispy
Open the notebook: ReadMe_TaxisPy_0.1.6.3 located within the TaxisPy container for instructions on how to launch an instance of the user interface. After starting an instance of TaxisPy, provide the path to the folder containing your frames. According to this example, your frames will be located under the path /Documents/host/myFrames. Then, click on the button “Load Frames”. If TaxisPy is able to load your frames, the number of frames contained in the specified folder will be shown next to the “Frames” slider, as shown below:
30
Question 11: TaxisPy crashed/is not responding. What can I do?
Answer 11: In the unlikely event that TaxisPy becomes unresponsive or crashes, you can simply restart the user interface by hitting shift+return on any cell of code containing the following commands:
from taxispy import InitGuiy = InitGui.UserInterface()y.interface
If the user interface is not reloaded, you might need to restart the kernel by clicking the option Restart & Clear Output in the Kernel menu:
Some steps of the analysis, especially the determination of optimal parameter values for the identification of tumbling frequencies are computationally intensive and can take several minutes to complete (up to 15 minutes or more depending on your hardware and the size of the training set). You can check the status of the software by looking at the status circle in the top right corner of the notebook window. When the kernel is busy, the circle is solid. This means that TaxisPy is still performing calculations and you should wait for the software to finish.
31
If TaxisPy crashed, restart the software and refer to Fig. 3 in the main manuscript for an overview of possible workflows depending on what kind of information is available.
If the malfunction persists, email [email protected] with a detailed bug description so that TaxisPy can be improved.
Question 12: TaxisPy seems to be taking a long-time for the estimation of key parameter values. How do I know if the software is stuck? Can I speed up this process?
Answer 12: The determination of key parameter values for the estimation of the average tumbling frequency is a computationally intensive step and can take several minutes to complete. The total time required depends on three factors: 1) the size of the training set, 2) the size of the population and the number of generations selected for the genetic algorithm, and 3) the number of available CPU cores.
The status circle of the notebook, located on the top right corner of the window, can be used to determine whether TaxisPy is running or is stuck. Additionally, a status update of the genetic algorithm is provided in the terminal window from which the TaxisPy container was started. For that, remove the flag -d:
docker run -p 8888:8888 --mount type=bind,source=/Users,target=/Documents/host m1vg/taxispy
When running the genetic algorithm, a status update will be provided as shown below:
In this specific example, the status update of a genetic algorithm run with a population size of 10 and a number of generations of 5 is shown. Gen stands for generations and nevals refers to the number of evaluations of the fitness function.
The time required by the genetic algorithm can be decreased by reducing the population size and the number of generations used by the genetic algorithm.
7. Suggestions for Optimal Video Acquisition and Image Analysis
7.1 Suggestions for Video Acquisition
In the aqueous droplet visualized by an inverted microscope used for this method, cells are capable of swimming in 3D. This software depends on our ability to record cell tracks for prolonged time increments; therefore, to artificially generate a plane where long bacterial trajectories are recorded, it is optimal to focus on the interface of the slide glass and the droplet of culture. Bacterial cells can track along the surface of the glass for significant trajectories several seconds or minutes in length1.
The most important consideration for video tracking, as with most chemotaxis assays, is to assay cell cultures when they are highly motile. In the case of Pseudomonas putida and E. coli, the peak motility occurs in mid-exponential growth when the OD600 is between 0.3 and 0.7.2 For other bacterial species, this OD600 could vary. Similar to capillary assays, we recommend that you only proceed with video recording if 60% or more of the population appears motile under microscopy2.
Second, for robust data, the more trajectories per sample (or in one video) is ideal to a point. Users may be tempted to record high density cell culture to generate the highest number of trajectories as possible in one video. However, we advise to limit the number of cells recorded per video to control for cell crowding. Dilutions of cells harvested at OD600 of 0.4 and 0.6 were diluted 2- to 3-fold in CB (see materials and methods) for the experiments shown here.
1 Vigeant, M.A.S., Ford, R.M. 1997. Interactions between motile Escherichia coli and glass in media with various ionic strengths, as observed with a three-dimensional-tracking microscope. Appl. Environ. Microbiol. 63, 3474–3479.2 Ditty, J. L., Parales, R. E. 2017. Protocols for the measurement of bacterial chemotaxis to hydrocarbons. In: Hydrocarbon and Lipid Microbiology Protocols (McGenity, T.J. (Ed.)) 7–42 (Springer Protocols Handbooks, 2017).
33
Cell crowding in a recording can have two major negative effects: (i) unfocused movement of the cells in the foreground can cause a mass background movement that interferes with trajectories tracking. To generate sufficient contrast (Section 7.2) between the background and the feature, cells that are swimming up to or away from the glass surface are still partially visible. With particularly high cell density, these blurry cell features generate a wavy background. (ii) Overlapping trajectories can be interpreted by the software as additional turns. When the software identifies two features and these two features meet in the 2D plane, the software is unable to determine which feature emerges from the overlap in which trajectory. Too many overlapping trajectories increases false positive turns, resulting in a high tumbling frequency across all samples.
7.2 Suggestions for Image Analysis
TaxisPy employs the functionality provided by Trackpy 0.4.2 (Allan et al. 2019) – a Python package that implements feature-finding and linking algorithms originally introduced by Crocker and Grier (1996)– to identify cells in individual frames and link them to produce cellular trajectories. The parameters Diameter and Min. Mass are used to inform the tracking routines about the diameter (in pixels) and brightness of the particles of interest. According to the developers3 of the original tracking routines, particles of interest should ideally be between 5 and 20 pixels in diameter.
Based on our analysis of various E. coli and P. putida videos taken with a total magnification of 400X, a Diameter of 25 pixels and a Min. Mass of 2000 deliver good results. The value for the Diameter was determined empirically after determining the diameter of several cells. The diameter of a given cell (e.g., Fig. A below) can be trivially determined by zooming in and visually counting the number of pixels contained within (see Fig. B below):
Note that the software is designed to look for bright particles on a black background. If you have black particles on a bright background (like in the figure above), you will have to invert the image using the Invert? option provided in the Feature Identification tab of TaxisPy.
If the diameter of your particles is too small or too large and TaxisPy is not able to correctly identify cells, adjust the total magnification of your microscope until the diameter is within the required order of magnitude.
The Min. Mass parameter can be set using the three histograms provided in the Feature Identification tab as a guidance and by visually assessing the ability of TaxisPy to correctly identify cells in the three frames shown in the same tab.
For instance, the histogram B, which corresponds to the frame A, clearly suggests that the value of Min. Mass should be increased to at least 1500 in order to get rid of particles with a too low intensity value. After setting Min. Mass to 2000, the number of detected particles in the same frame dramatically decreases (frame C). The mass (brightness) of the particles is summarized in histogram D.
If you obtain the following error message while adjusting the values for Diameter and Min. Mass:
/opt/conda/lib/python3.6/site-packages/trackpy/feature.py:429: UserWarning: No maxima survived mass- and size-based filtering. Be advised that the mass computation was changed from version 0.2.4 to 0.3.0 and from 0.3.3 to 0.4.0. See the documentation and the convenience functions 'minmass_v03_change' and 'minmass_v04_change'. warnings.warn("No maxima survived mass- and size-based filtering. "
35
It simply means that the tracking routines were not able to find any particle with the required properties (Diameter & Min. Mass) and you should reduce the value of one of these parameters or both.
After Trackpy (Allan et al. 2019) has scanned all frames and identified particles in each frame, it will try to link the position of cells to generate cellular trajectories. This step is controlled by two additional parameters: Max. Disp. and Min. # Frms. Default values of 25 pixels and 20 frames yielded good results and were used in this paper for the analysis of all videos. Max. Disp. refers to the maximum distance (in pixels) that a particle can move between frames, while Min. # Frms. refers to the minimum duration (in frames) for trajectories to be considered by TaxisPy.
If the average swimming velocity of the microorganism under analysis is known, Max. Disp. can be estimated using the following formula:
Where Av_vel is the average velocity in micron/seconds, Pixel_micron is the number of pixels in 1 micron and the Frame_rate corresponds to the number of frames captured per second.
If the minimum duration in seconds for a trajectory is set, Min. # Frms can be estimated as:
Where Duration refers to the desired minimum duration in seconds that a trajectory should have to be considered by TaxisPy.
