V1.

0 User’s Manual
OpenCASA
User’s Manual
User’s Manual

Table of Contents
Specifications ..................................................................................................................................1
Installation ......................................................................................................................................1
For users ......................................................................................................................................1
For developers ............................................................................................................................1
Main Window .................................................................................................................................2
Settings ............................................................................................................................................2
Motility module..............................................................................................................................5
Results..........................................................................................................................................5
Parameters involved ..................................................................................................................5
Chemotaxis module .......................................................................................................................6
Results..........................................................................................................................................6
Parameters involved ..................................................................................................................7
Viability module.............................................................................................................................8
Results..........................................................................................................................................8
Parameters involved ..................................................................................................................8
Morphometry module ...................................................................................................................9
Results........................................................................................................................................10
Parameters involved ................................................................................................................10
Simulation module ......................................................................................................................11
Results........................................................................................................................................11
Parameters involved ................................................................................................................11
User’s Manual
Specifications

This program has been developed and tested on Windows 7 (64-bit) using Imagej v1.49q
and Java 1.8.0_101 (64-bit). There are no specific requierements to use this plugin but a special
attention of RAM memory is suggested when video analysis is carried on. At least 5GB of
heap memory size is recommended, but it depends on the size of the files. One good
estimation could be to use a heap memory size of 2.5 times the size of the heaviest file that is
going to be analyzed. Information about how to increase memory on ImageJ can be found
following this link: https://imagej.net/Troubleshooting#OutOfMemoryError. For all tests,
only videos in AVI format and images in JPEG or PNG format were used. The plugin has not
been tested on Linux or MAC platforms.

Installation

For users

First of all, it is necessary to have installed ImageJ. The latest version of the program can be
downloaded from https://imagej.nih.gov/ij/download.html. We recommend to download
the 64-bit bundle with the latest java version.

To install OpenCASA plugin on ImageJ, we recommend to follow these instructions:

https://imagej.net/Installing_3rd_party_plugins: just drag and drop the .jar file into the
ImageJ menu and select the destination folder. Once this is done, the OpenCASA_ option in
the menu bar will be added.

For developers

To develop with ImageJ in Eclipse, it is recommended to follow the instructions specified

in: https://imagej.net/Developing_ImageJ_in_Eclipse. Briefly, to set up and run an existing
ImageJ project in eclipse, it is necessary to follow these four steps:

1. Install the Java Development Kit

2. Install and configure Eclipse
3. Clone the source code
4. Import the source code

1
User’s Manual

Note: the source code is included in the .jar file. It is possible to extract it using a common
software like 7zip or WinRAR. Once the source code has been extracted, for small changes,
the plugin can be modified and compiled using the embedded java compiler in ImageJ
located on the Plugins menu (in order to be sure that all changes have been updated, it is
recommended to remove, previously the compilation, all .class files included in both folder
and subfolders of OpenCASA plugin).

Tip: In order to increase the heap memory in eclipse, after the project has been set up, in the
menu bar go to Run->Run Configuration, find the name of the class you have been running,
select it, click the Arguments tab and then add:

-Xms5120M –Xmx5120M

where 5120 is the 5 gigabytes of memory that you want to assign (in megabytes). Remember
that a heap memory size of 2.5 times the size of the heaviest file that is going to be analyzed
is recommended.

Main Window

The OpenCASA main window consists in a set

of buttons corresponding each one with one
functionality or module. In this version, five
modules were implemented (Motility,
Chemotaxis, Viability, Morphometry and
Simulation), and a Settings menu was added in
order to configure the parameters for each
analysis.

Settings

In this window, the user can modify the value of

a few parameters related with the input data and
the analysis. The window is divided in four tabs.
In the General tab, the user can set a few
parameters related with the scale (it depends on
the objective used to capture images or videos),
the size of the cells or other fields like male
identifier or the date of the analysis. In the Video
tab, the user can set a few parameters related
with the video analysis. In the Chemotaxis tab,
the user can modify a few parameters involved
in the chemotaxis analysis, such as the gradient
direction or the number of bootstrapping resamples used for bootstrapping analysis. Finally,

2
User’s Manual

in the Motility tab, the user can set the parameters related to cells in movement, like the vcl
filter used to classify the cells in motile/non motile, or the value that determines when a cell
has progressive motility or not.

The parameters that the user can configure for each category are specified in the following
tables:

General
Microns per pixel This is the ratio of microns per pixels.
Minimum cell size Minimum cell size to be detected (in microns).
Maximum cell size Maximum cell size to be detected (in microns).
Male (optional) Identifier of the male that is analyzed.
Date (optional) Date of the analysis.
Generic Field (optional) This generic field can be used to add
extra info to the final report.
Video
Frame rate Frame rate of the video (frames / second).
Minimum track length Trajectories with less length will not be
considered (microns).
Maximum displacement between frames Maximum displacement that a cell could carry on
between two following frames (microns).
Window size Length of the rectangle window used in the
moving average method to calculate the average
path (frames).
Print XY Coordinates This option allows the user to save the x-y
coordinates of each trajectory. Only available for
file analysis (not directories) in both chemotaxis
and motility analysis.

Chemotaxis
Chemotaxis gradient direction Gradient direction (degrees).
Chemotaxis cone’s amplitude Gradient amplitude (degrees).
Number of bootstrapping resamples Used to calculate the OR threshold in
bootstrapping analysis.
Angle delta Used when the frame rate of the recordings is too
fast. For high frame rates, cells don’t move
enough between two following frames, so this
parameter is used to calculate the angle between
frame t and frame (t + angle delta). This parameter
is not a strict decimator factor, in the context of
signal processing.
Compare opposite directions If this parameter is set to true, the analysis only
takes into account angles in both the gradient and
opposite directions as positive and negative
displacements respectively, and ignore the rest.
Otherwise, the module takes into account all
angles in all directions.

3
User’s Manual

Motility
Progressive motility Threshold used to determine when a cell has
progressive motility or not. The value means %
of STR motility parameter.
Minimum VCL Minimum curvilinear velocity to consider a
trajectory as motile.
VCL lower threshold Only for file analysis. These parameters are used
VCL upper threshold together to classify trajectories in three categories
depending on their vcl value: Slow – Medium –
Fast. Tracks below lower threshold are tagged as
SLOW. Between lower threshold and upper
threshold are tagged MEDIUM, and trajectories
above upper threshold are tagged as FAST.

4
User’s Manual

Motility module

This module allows the user to analyze a single or multiple recordings of cells in movement,
and extract a set of motility parameters for each sample. The program accepts videos in AVI
format. There are three options: analyze a file, a directory or multiple directories.

If the user wants to analyze multiple

directories, it is necessary to provide all
the data in a specific way. It is necessary
to create a folder with the name of the
experiment. This will be the main folder
and the one that have to be selected
when the program asks you for a
directory in the multiple directories
option. All folders that the user wants to
analyze have to be added
as a subfolders of the
experiment directory, as
it is represented in the
figure on the right. Each
subfolder has to contain
all AVI videos that will be
analyzed.

Results

Depending on the selected analysis, this module shows different results, summarized in the
following table:

File This analysis returns two reports: one with all motility parameters for each
tracked cell, and an average report with the mean values of each parameter.
Directory This analysis returns two reports: one with all motility parameters for each
tracked cell, and an average report with the mean values of each parameter,
one row for each video contained in the directory.
Multiple This analysis return one report: for each subfolder, the average motility
directories parameters is calculated. The repost contains one row for each subfolder.

Parameters involved

General Video Chemotaxis Motility

All All - All

5
User’s Manual

Chemotaxis module

This module allows the user to carry on a chemotaxis analysis in a single or multiple
recordings. The program accepts files in AVI format. There are three options: analyze a file,
a directory or simulate multiple samples. In both directory and multiple simulations, the
user can choose between two different analyses: ch-index analysis and bootstrapping
analysis.

For directory analysis, the data has

to be provided in a particular way.
It is necessary to create a main
folder with the name of the
experiment, and to add at least two
subfolders inside it. One of them
has to be named as “control” and it
will contain all recordings related
to control condition. The resting
subfolders will contain the
corresponding files for a
particular experimental
condition.

When the user selects an

experiment folder to be
analyzed, the program
compares automatically
the control files with each
condition separately. For
this purpose, each control
file has to share the same
ID with its corresponding condition file. For example, if there is a control file names as
“sample1.avi”, there has to be one file with the same name for each condition folder, in order
to allow the program to match and compare them.

Results

Depending on the selected analysis, this module shows different results, summarized in the
following table:

Ch-index For a single file analysis, the program returns two diagrams as a report,
one corresponding for the straight line analysis, and other a rose diagram
showing the circular histogram of the instantaneous angles between the
cell displacement and the gradient direction.
For experiments, the program returns a report summarizing all ch-index
and sl-index calculated for each sample.

6
User’s Manual

Bootstrapping This analysis is only available for experiments. The program returns, for
each experimental condition, the list of all analyzed samples, indicating
which ones give positive and which ones not on chemotaxis, with 5%-
confidence level. The threshold is calculated using all control samples
included in the subfolder “control” and the number of bootstrapping
resamples to calculate it can be configured in the settings menu.

Parameters involved

General Video Chemotaxis Motility

All All All Minimum VCL

7
User’s Manual

Viability module

This module allows the user to

count cells in two colors: red and
green. There are two options:
analyze one single image or
multiple images, but both work
in the same way. Once the
program has load the first image,
a window similar to this one is
shown. This window has three
different functional areas
distributed in 6 components. The
functionalities are explained in
the following table:

Area Component Function

Intensity- 1 Automatic threshold. Two possible methods to apply:
based Otsu and Minimum.
thresholding 2 Manual threshold. For each color, red and green, the user
can select a different color intensity-based threshold.
Workspace 3 The current image name.
4 The current image. The detected cells are shown with a
unique numerical identifier for the current threshold. If
the user clicks on this area, the raw unlabeled image is
shown. This is useful to be sure that all cells are well
classified.
Navigation 5 When a directory of images is analyzed, this button
allows the user to navigate throw previous images.
6 When a directory of images is analyzed, this button
allows the user to navigate throw next images. Also,
clicking on it, the results of the analysis are added to the
report. This click is necessary even in a single file analysis
or the last image of a directory.

Results
This program returns a report with the number of cells of each type that have been
counted. This report includes one row for each image.

Parameters involved

General Video Chemotaxis Motility

All - - -

8
User’s Manual

Morphometry module

This module allows the

user to calculate some
morphometric parameters
for a given cells. There are
two options for the user
but they work in the same
way: analyze one single
image or multiple images.
Once the program has load
the first image, a window
similar to this one is
shown. This window has
three different functional
areas distributed in six components. The functionalities are explained in the following table.
When the user considers that one or multiple cells are well outlined, it is only necessary to
click over them in order to add the corresponding morphometric parameters of these cells to
the report.

Area Component Function

Intensity- 1 Automatic threshold. Two possible methods to apply:
based Otsu and Minimum.
thresholding 2 Manual threshold. The user can select a different color
intensity-based threshold.
Workspace 3 The current image name.
4 The current image. The detected cells are shown with a
unique numerical identifier for the current threshold. If
the user clicks on this area, the raw unlabeled image is
shown. This is useful to be sure that all cells are well
outlined.
Navigation 5 When a directory of images is analyzed, this button
allows the user to navigate throw previous images.
6 When a directory of images is analyzed, this button
allows the user to navigate throw next images.

9
User’s Manual

Results

The program will show a report with various morphometric parameters from the selected
cells (one row for each cell). The morphometric parameters calculated by the program are:

Parameter Definition
Mean gray Average gray value of all pixels contained in the cell area (value between 0
value and 255).
Area Area of the cell (µm2).
Perimeter Perimeter of the cell (µm).
Length Length of the cell following the principal axis. Equivalent to Feret value
(µm).
Width Width of the cell following the secondary axis. Equivalent to Min_Feret
(µm).

Ellipticity Length
Width

Roughness 4 𝑥 𝜋 𝑥 𝐴𝑟𝑒𝑎
𝑃𝑒𝑟𝑖𝑚𝑒𝑡𝑒𝑟 2

Elongation 𝐿𝑒𝑛𝑔𝑡ℎ − 𝑊𝑖𝑑𝑡ℎ

𝐿𝑒𝑛𝑔𝑡ℎ + 𝑊𝑖𝑑𝑡ℎ

Regularity 𝐿𝑒𝑛𝑔𝑡ℎ 𝑥 𝑊𝑖𝑑𝑡ℎ 𝑥 𝜋

4 𝑥 𝐴𝑟𝑒𝑎

Parameters involved

General Video Chemotaxis Motility

All - - -

10
User’s Manual

Simulation module

This module allows the user to create a video simulation of 100 cells following a persistent
random walk model being attracted to the x-axis direction. Before the creation of a
simulation, a dialog is shown to configure three parameters:

Parameter Definition
Beta This parameter is equivalent to the level of attraction. Bigger the
parameter, stronger the attraction. The positive or negative sign of the
parameter will determine the right/left direction of the cells, and a
value of 0 means no attraction. A recommended range of this
parameter is between [-5,5].
Responsiveness This parameter indicates the percentage of the cells that are attracted.
The rest of the cells follow a classical persistent random walk with no
particular bias in their movement.
Length of the This parameter indicates the length (in frames) of the simulation.
simulation

Results
After setting these parameters, a video simulation is shown. The user can save the video as
usual in ImageJ going to File menu -> Save As -> AVI…

Parameters involved

General Video Chemotaxis Motility

- - - -

11