schafer lab worm analysis toolbox user manual · worm analysis toolbox 1.0: user manual 7/16/2009...

Worm Analysis Toolbox 1.0:

User Manual http://www.mrc-lmb.cam.ac.uk/wormtracker

7/16/2009

Tadas Jucikas, Victoria Butler and Eviatar Yemini

MRC Laboratory of Molecular Biology, Hills Road, Cambridge, CB2 0QH

UK.Tel: +44 (0) 1223 248011 Fax: +44 (0) 1223 213556

Web: http://www.mrc-lmb.cam.ac.uk

Worm Analysis Toolbox 1.0: User Manual

MRC Laboratory of Molecular Biology, Hills Road, Cambridge, CB2 0QH, UK. Tel: +44 (0) 1223 248011 Fax: +44 (0) 1223 213556 Web: http://www.mrc-lmb.cam.ac.uk

2 Contents

Contents

CONTENTS ..................................................................................... 2

TABLE OF FIGURES ........................................................................ 3

INTRODUCTION ............................................................................. 4

INSTALLATION .............................................................................. 5

STARTING THE TOOLBOX ............................................................... 6

KEY FEATURES ............................................................................... 7

SEGMENTING THE WORM............................................................... 8

FEATURE EXTRACTION ................................................................ 13

CREATING A DIRECTORY ..................................................................... 13

SKELETON ALIGNMENT AND ORIENTATION ................................................. 15

CALCULATING METRICS ...................................................................... 21

DRAWING HISTOGRAMS ...................................................................... 24

HELPER TOOLS ............................................................................ 26

WORM VIEWER ............................................................................... 26

VIDEO DIAGNOSTIC TOOL ................................................................... 28

REFERENCES ................................................................................ 30



3 Table of Figures

Table of Figures

FIGURE 1 MAIN USER INTERFACE ............................................................... 6

FIGURE 2 MODULE 2 SEGMENTATION INTERFACE............................................. 8

FIGURE 3 FILE BROWSER FOR LOADING VIDEOS FOR SEGMENTATION ...................... 9

FIGURE 4 MODULE 2 SEGMENTATION INTERFACE DISPLAYING SEGMENTATION RESULT 10

FIGURE 5 MODULE 2 SEGMENTATION INTERFACE INDICATING SEGMENTATION OF THE

VIDEO IS COMPLETE ........................................................................ 11

FIGURE 6 MODULE 3 FEATURE EXTRACTION AND ANALYSIS INTERFACE ................. 13

FIGURE 7 FILE BROWSER FOR SELECTING FOLDER FOR DIRECTORY STRUCTURE CREATION

............................................................................................... 14

FIGURE 8 LOADING WORM SKELETONS FOR ALIGNMENT AND ORIENTATION CHECKS USING

MODULE 3 FEATURE EXTRACTION AND ANALYSIS INTERFACE ........................ 15

FIGURE 9 FILE BROWSER FOR SELECTING FOLDER CONTAINING WORM* FOLDERS TO

CHECK SKELETON ORIENTATION .......................................................... 16

FIGURE 10 WORMPROC WINDOW FOR CHECKING SKELETON ALIGNMENT AND

ORIENTATION ............................................................................... 17

FIGURE 11 WORM DUPLICATE CHECK BOX ................................................... 17

FIGURE 12 WORMPROC WINDOW DISPLAYING WORM SKELETON .......................... 18

FIGURE 13 DIALOGUE BOX TO SAVE ALIGNED WORM SKELETONS ......................... 19

FIGURE 14 STATUS BOX IN MODULE 3 INDICATES SKELETON ALIGNMENT COMPLETED

FOR A FOLDER .............................................................................. 20

FIGURE 15 ENTERING CALIBRATION FACTORS TO CALCULATE MILLIMETERS PER PIXEL . 22

FIGURE 16 STATUS OF MODULE 3 FEATURE EXTRACTION AND ANALYSIS INDICATING

METRICS ARE BEING CALCULATED ........................................................ 22

FIGURE 17 STATUS OF MODULE 3 FEATURE EXTRACTION AND ANALYSIS INDICATING

THAT METRICS HAVE BEEN SUCCESSFULLY CALCULATED ............................... 23

FIGURE 18 FILE BROWSER FOR LOADING FOLDERS TO PLOT HISTOGRAMS ............... 24

FIGURE 19 MODULE 3 STATUS BOX INDICATING HISTOGRAM FUNCTION FAILURE ...... 25

FIGURE 20 WORM VIEWER INTERFACE....................................................... 26

FIGURE 21 WORM VIEWER INTERFACE WITH VIDEO AND SKELETON SUCCESSFULLY

LOADED...................................................................................... 27

FIGURE 22 WORM DIAGNOSTICS WINDOW .................................................. 28

FIGURE 23 WORM DIAGNOSTICS WINDOW WITH VIDEO SUCCESSFULLY LOADED ....... 29



4 Introduction

Worm Analysis Toolbox 1.0:

User Manual

Introduction

Worm Analysis Toolbox 1.0 is a free worm video data analysis package. It was designed to be used with data collected with Worm Tracker 2.0. It is a first beta

release programmed in Matlab. Source code will be available soon. At the moment please download compiled Worm Analysis Toolbox version.

The software was created by Tadas Jucikas and Eviatar Yemini and is tested by

Victoria Butler at the Schafer Lab. Please send an email to Tadas in case of

technical issues, suggestions and bug reports. Send an email to Victoria with

usage questions and experimental issues.



5 Installation

Installation

You will need Matlab or Matlab Compiler Runtime Environment (MCR) to run Worm Analysis Toolbox 1.0. Installer will automatically download and install MCR if you don't have Matlab. If you want to install the toolbox on a computer

disconnected from the Internet, please download the MCR from here and install it manually. You will need to download and install ffdshow a media decoder

used for decoding compressed video formats. You can download it from our website, or look for the newest version in ffdshow website.



6 Starting the Toolbox

Starting the Toolbox

• Open the Worm Analysis Toolbox, either from the Program menu or by double-clicking on the Worm Analysis Toolbox shortcut.

• This will open the main user interface shown below:

Figure 1 Main User Interface



7 Key Features

Key Features

• The main user interface has 6 buttons; 3 modules and 3 helper tools

• The 3 modules are:

1. Module 1: stage movement

This button is currently not functional

It will allow the path of the worm to be recreated and viewed

2. Module 2: segmentation

This button allows the user to load collected videos for segmentation of the worm

3. Module 3: feature extraction

This button allows the user to load segmented worm skeletons for

feature extraction

• The 3 helper tools are:

1. Worm Viewer

This button allows the user to load a video and the segmented worm skeleton and view the overlap between worm and skeleton

2. Worm Diagnostics Tool

This button allows the user to load a video and check the segmentation result

3. Dropped Frame Detector

This button allows the user to identify frames dropped by the

segmentation process

This button does not need to be used in the latest version of Worm Toolbox



8 Segmenting the worm

Segmenting the worm

Once videos have been collected with Worm Tracker 2.0 software they can be loaded for segmentation. This process identifies the worm in the video and distributes a skeleton of 13 points along the length of the body.

To segment collected videos:

• Click on the “Module 2: segmentation” button on the main user interface.

• This will open the “Module 2: Segmentation” interface:

Figure 2 Module 2 Segmentation Interface




• Click the “Load” button at the top right of the interface.

• This will open the following file browser:

Figure 3 File browser for loading videos for segmentation

• Select the folder containing the videos to be segmented and then click “OK”. The folder name will be loaded into the bar in the “Control panel” box.

• Click the “Start module 2” button.

• After a few seconds, the first video will be loaded and segmentation will

start. The video frame with the segmentation result can be visualized in the “Segmentation result example” box. The segmentation result is shown

for every 200 video frames.




Figure 4 Module 2 Segmentation Interface displaying segmentation result

• The status box indicates:

1. The video currently being analyzed out of the total number of videos loaded

2. The frame currently being analyzed

3. The status of the segmentation – whether segmentation is still ongoing or segmentation of the videos is complete




• The “Width profile” box displays the width of the worm from the calculated skeleton; from the head to the tail down one side of the worm and then

from the tail to the head down the other side of the worm. This graph should ideally be symmetrical about the middle of the x-axis, indicating

the skeleton is positioned centrally on the body of the worm.

• Once segmentation is complete the “Status” box will indicate that “Module2 finished analyzing files in …” the loaded folder and the module 2

interface can be closed.

Figure 5 Module 2 Segmentation Interface indicating segmentation of the

video is complete




• The folder containing the loaded videos will now contain the successfully segmented worm skeletons as _seg files, preceeded by the date and time

each video was collected. Copy these _seg files into a new folder.

• The folder loaded will also contain 2 new folders called “finished” and

“unfinished”. The “finished” folder will contain all videos successfully

segmented. The “unfinished” folder will contain videos that were not

successfully segmented.

• If segmentation of the video is unsuccessful the “Status” box will indicate

that “Module2 finished analyzing files in …” the loaded folder a few

seconds after clicking the “Start module 2” button.

• Unsuccessful segmentation most likely results from the first video frame

containing the worm coiled on itself in some way. Ensure that videos are

started when the worm is moving forward and the entire length of the

body is clearly visible.



13 Feature Extraction

Feature Extraction

Creating a directory

Before continuing with analysis of the segmented worm skeletons, a directory

structure must be constructed for the worm videos to sort videos of the same name into the same folder.

To do this:

• Click on the “Module 3: feature extraction” button on the main user

interface. This will open the “Module 3: feature extraction and analysis” interface:

Figure 6 Module 3 Feature Extraction and Analysis Interface




• Click on the “Start Create” button at the top right of the interface in the “Step 1: Create dir structure” box


Figure 7 File browser for selecting folder for directory structure creation

• Click on the folder that contains the _seg skeleton files and then click

“OK”.

• After a few seconds the “Status” box will indicate that a new directory

structure has successfully been created.

• This new directory will sort all worm skeletons with the same assigned

name into the same folder and number them worm 1 to worm X where X

is total number of videos with that particular assigned name. It is therefore important to keep the naming of videos consistent.

• The organized folders can then be loaded to check skeleton orientation.




Skeleton alignment and orientation

The “Module 3: feature extraction” button also allows the user to check the segmented worm skeleton, define the head-tail orientation of the worm and view

and edit excluded frames.

To do this:

• Click on the “Load” button in the middle of the “Step 2. Wormproc: alignment and orientation” box:

Figure 8 Loading worm skeletons for alignment and orientation checks using Module 3

Feature Extraction and Analysis Interface





Figure 9 File browser for selecting folder containing Worm* folders to check skeleton

orientation

• Click on the genotype folder containing the segmented worm skeletons to be analyzed and then “OK”.

• This folder name will then be loaded into the bar at the left of the “Step 2.

Wormproc: alignment and orientation” box.

• Click the “Start Wormproc” button at the right of the “Step 2. Wormproc: alignment and orientation” box.

• If the folder is being loaded into Wormproc for the first time, this will open

the Wormproc window, shown below:




Figure 10 Wormproc window for checking skeleton alignment and orientation

• If a folder has been loaded into Wormproc before, the following “Wormproc duplicate check” box appears:

Figure 11 Worm duplicate check box

• If you want to overwrite the previously saved head-tail orientation for a particular worm video click “Yes”, if not click “No”. When “Yes” is clicked the Wormproc window is opened. If “No” is clicked a “Wormproc duplicate

check” box appears for the next worm video in the folder.




• To visualize the worm skeleton click the “Play >” button at the left of the Wormproc window. The skeleton of the worm will appear with 13 points

connected by blue lines. A red circle at one end of the skeleton identifies the head.

Figure 12 Wormproc window displaying worm skeleton

• The playback speed of the video can be adjusted using the “Playback

Speed” bar at the bottom of the Wormproc window.

• The playback speed can be further increased or decreased using the fast-forward (“>>” and “>>>” buttons) or rewind buttons (“<<” and “<<<”).

• Press the “Stop” button to stop the video at a particular frame.

• The “< Step” and “Step >” buttons allow the user to go forwards or back 1 frame.




• There are 2 toggle buttons;

1. “Accpt/Rejct”

This button switches between accepting and rejecting a frame. A

rejected frame has a large red cross through the centre. Once a particular frame is rejected, the next frame to be accepted must have this button clicked to go back to the Accept mode

2. “Flip”

This button allows the user to switch the head-tail orientation of the worm. Once clicked, the red circle defining the head will switch to the other end of the skeleton

• The frame currently be displayed is indicated at the top of the Wormproc screen (“Frame = NNNN”), as well as the length of the skeleton compared to the average length.

• Frames with skeleton lengths 5% above or below the average skeleton

length are automatically excluded by Wormproc.

• Click the “Done” button once the worm skeleton has been checked.

• The following dialogue box will appear and click “Yes” to save.

Figure 13 Dialogue box to save aligned worm skeletons




• The next worm skeleton will automatically be loaded and a new Wormproc window will appear for it.

• Once all worm skeleton files in a folder have been checked, the Wormproc window will disappear. The “Status” box in Module 3 will indicate that the “Wormproc function finished successfully!” and the user can proceed to

calculate metrics.

Figure 14 Status box in Module 3 indicates skeleton alignment completed for a folder




Calculating metrics

Once the worm skeleton is aligned, the user can proceed to calculate metrics for each video. This results in an Excel spreadsheet containing data on the 13

skeleton points of the worm that is used to calculate locomotion features and create the histograms.

• To calculate accurate metrics the user must enter;

1. Frames per time block

This defines the number of frames over which metrics are calculated. We set this to 1, so metrics are calculated for each frame

2. Length of video in seconds

3. Microns per step

This value is dependent on the actuators being used to move the stage

4. Pixels per step

This value is dependent on the magnification of the camera

• Microns per step and pixels per step are used to calculate millimeters per

pixel. This value is displayed in the centre of the “Step 3. Metrics: feature calculation” box in Module 3.




Figure 15 Entering calibration factors to calculate millimeters per pixel

• Load the checked worm skeleton folder for metrics analysis by clicking on the “Load” button at the bottom middle of the “Step 3. Metrics: feature calculation” box. Once a folder has been loaded “Step 2. Wormproc:

alignment and orientation” box, it will automatically be loaded into the “Step 3. Metrics: feature calculation” box.

• Click on the “Start metrics6” button at the right in the “Step 3. Metrics:

feature calculation” box to begin calculating metrics.

• An entire directory can have metrics calculated by loading that directory and clicking the “Batch process dir” button.

• Whilst the metrics are being calculated the “Status” box in Module 3 will

display the message “metrics6 function is analyzing the directory…” followed by the directory being analyzed.

Figure 16 Status of Module 3 Feature Extraction and Analysis indicating

metrics are being calculated




• When calculation of metrics is complete the “Status” box in Module 3 will indicate “metrics6 function finished successfully!”. Currently, for a 5

minute video it takes approximately 1 minute to calculate metrics.

Figure 17 Status of Module 3 Feature Extraction and Analysis indicating that metrics

have been successfully calculated




Drawing histograms

Currently histograms for instantaneous velocity, centroid velocity, flex and frequency of body bending, track amplitude and wavelength and length-

normalized track amplitude and wavelength can be drawn.

To create histograms:

• Click on the “Load” buttons in the “Step 4. Histograms” box and select the folders to be analyzed. These folders must contain subfolders named

“Worm1”, “Worm2” ….

Figure 18 File browser for loading folders to plot histograms




• Click on “Start Histograms” when all folders to be compared have been loaded.

• In a few seconds windows containing the histograms for instantaneous

velocity, centroid velocity, flex and frequency of body bending, track amplitude and wavelength and length-normalized track amplitude and

wavelength will appear.

• If the histograms function failed this will be indicated in the “Status” box:

Figure 19 Module 3 Status box indicating histogram function failure

• The most likely cause for histogram function failure is loading a folder that

does not contain worm* subfolders.



26 Helper Tools

Helper Tools

Worm Viewer

This helper tool allows the user to load a video and the segmented worm skeleton and view the overlap between worm and skeleton.

To do this:

• Click on the “Worm Viewer” button on the main user interface to open the

“wormViewer” interface:

Figure 20 Worm Viewer Interface

• Load a video file and a skeleton file by clicking on the 2 “Load” buttons at

the top right of the interface.



27 Helper Tools

Figure 21 Worm Viewer Interface with video and skeleton successfully loaded

• Click the “Play” button to visualize the overlap of the skeleton on the worm, click the “Stop” button to stop the video from playing and move

from one frame to the next by clicking the “Prev.” and “Next” buttons.

• The user can jump to a particular frame by entering the frame number in

the bar at the bottom right of the interface.

• The frame being displayed is indicated at the bottom right of the interface.



28 Helper Tools

Video Diagnostic Tool

This tool allows the user to visually check the segmentation of the worm and the quality of the videos being produced.

• Click on the “Worm diagnostics Tool” on the main user interface to open the “wormDiagnostics” window, shown below:

Figure 22 Worm Diagnostics window

• Load a video by clicking on the “Load” button at the top right on the

window.



29 Helper Tools

Figure 23 Worm Diagnostics window with video successfully loaded

• This window displays the original video and the segmentation result. The

binary image, filled edges, worm outline, worm skeleton and width profile can also be viewed in this window.

• Click on the “Prev.” and “Next” buttons to move between frames or jump

to a particular frame by entering the frame number in the “Enter frame:” bar.



30 References

References

Baek J-H, Cosman P, Feng Z, Silver J, Schafer WR. (2002) "Using machine vision

system to analyze and classify of C. elegans behavioral phenotypes quantitatively" J. Neurosci Meth. 118: 9-21. pdf

Cronin CJ, Mendel JE, Mukhtar S, Kim YM, Stirbl RC, Bruck J, Sternberg PW.

(2005) “An automated system for measuring parameters of nematode sinusoidal movement” BMC Genet. Feb 7;6(1):5

Feng Z., Cronin CJ, Wittig JH Jr, Sternberg PW, Schafer WR. (2004) "An imaging

system for standardized quantitative analysis of C. elegies behavior" BMC Bioinformatics 5: 115. pdf

Geng W, Cosman P, Baek J-H, Berry CC, Schafer WR. (2003) "Quantitative classification and natural clustering of C. elegans behavioral phenotypes"

Genetics 165: 1117-1123. pdf

Geng W, Cosman P, Berry CC, Feng Z, Schafer WR. (2004) "Automatic tracking, feature extraction and classification of C. elegans phenotypes" IEEE Trans Biomed. Eng 51: 1811-20. pdf

Geng W, Cosman P. Palm M, Schafer W. (2005) C. elegans egg-laying detection and behavior study using image analysis" EURASIP J. App. Sig. Proc. 14 : 2229-2240. pdf

Hardaker, LA, Singer E, Kerr R, Zhou GT, Schafer WR. (2001) "Serotonin

modulates locomotory behavior and coordinates egg-laying and movement in Caenorhabditis elegans" J. Neurobiol. 49: 303-313. pdf

Huang KM, Cosman P, Schafer WR. (2006) "Machine vision based detection of omega bends and reversals in C. elegans" J Neurosci Methods. Epub 2006 Jul 1

pdf

Waggoner LE, Zhou GT, Schafer RW, Schafer WR. (1998) “Control of alternative behavioral states by serotonin in Caenorhabditis elegans” Neuron 21: 203-214. pdf

Zhou GT, Schafer WR, Schafer RW. (1998) “A three-state biological point

process model and its parameter estimation” IEEE Trans. Signal Process. 46: 2698-2707. pdf

schafer lab worm analysis toolbox user manual · worm analysis toolbox 1.0: user manual 7/16/2009...

Documents