Bactimas - User contributions [en]

Installation dev

2023-07-18T11:12:36Z

Igor:

== A note to the developers ==
To add a new algorithm one has to do two things:

*(a) Write a class that implements the ITrackingAlgorithm interface (javadoc here: http://homer.zpr.fer.hr/bactimas/doku.php?id=javadoc:javadoc).

These are the summaries of the requested methods:
void beforeBatch(int firstFrameNo)
Invoked before processing batch.
void beforeStep(int frameNo)
Invoked before every step().
java.lang.String getAbbrev()
Algorihm name abbreviation, used for display in the frame tree.
java.lang.String getClassName()
Class name, used for instantiation.
java.lang.String getName()
A friendly name, to be shown to the user.
void step(int frameNo, VPoint translation)
This is the main function to implement - the one that performs the tracking / segmentation.

From within the these methods, primarily step() method, a develeoper has at his disposal the entire ImageJ library and several
additional Bactimas methods, such as (from the CurrentExperiment class):

ImagePlus getImagePlus(ImageStripType channel, int frameNo, String altFormat)
Returns the ImageJ's ImagePlus object for the given frameNo, channel and (not required) alternative image format (tif, jpg, ...) with png being default
LinkedList<Bacteria> getBacteriasForFrame(int frameNo) getBacteriasForFrame(int frameNo)
Returns the list of bacterias on the given frame.
boolean saveROI(Roi roi, int frameNo, Bacteria b, int roiType)
Perists the (caluculated) roi for the bacteria b into the database.
etc.

Also, it is probably helpful to take a look at the implementation of proposed "Copy And Adjust" algorihtm in the class:
bactimas.algorithms.CopyAndAdjustAlgorithm implements ITrackingAlgorithm

* (b) Append the full class name in the conf/all.algorithms file text file so that Bactimas can instantiate it at run time.

----

Recommended:

* See the already available algorithms implementing the //ITrackingAlgorithm// interface.
* Consult the [[javadoc:javadoc|JavaDoc]] for the details.

Installation dev

2023-07-18T11:12:01Z

Igor: Created page with "====== A note to the developers ====== To add a new algorithm one has to do two things: **(a)** Write a class that implements the ITrackingAlgorithm interface (javadoc here: http://homer.zpr.fer.hr/bactimas/doku.php?id=javadoc:javadoc). These are the summaries of the requested methods: void beforeBatch(int firstFrameNo) Invoked before processing batch. void beforeStep(int frameNo) Invoked before every step(). java.lang.String g..."

====== A note to the developers ======
To add a new algorithm one has to do two things:

**(a)** Write a class that implements the ITrackingAlgorithm interface (javadoc here: http://homer.zpr.fer.hr/bactimas/doku.php?id=javadoc:javadoc).

These are the summaries of the requested methods:
void beforeBatch(int firstFrameNo)
Invoked before processing batch.
void beforeStep(int frameNo)
Invoked before every step().
java.lang.String getAbbrev()
Algorihm name abbreviation, used for display in the frame tree.
java.lang.String getClassName()
Class name, used for instantiation.
java.lang.String getName()
A friendly name, to be shown to the user.
void step(int frameNo, VPoint translation)
This is the main function to implement - the one that performs the tracking / segmentation.

From within the these methods, primarily step() method, a develeoper has at his disposal the entire ImageJ library and several
additional Bactimas methods, such as (from the CurrentExperiment class):

ImagePlus getImagePlus(ImageStripType channel, int frameNo, String altFormat)
Returns the ImageJ's ImagePlus object for the given frameNo, channel and (not required) alternative image format (tif, jpg, ...) with png being default
LinkedList<Bacteria> getBacteriasForFrame(int frameNo) getBacteriasForFrame(int frameNo)
Returns the list of bacterias on the given frame.
boolean saveROI(Roi roi, int frameNo, Bacteria b, int roiType)
Perists the (caluculated) roi for the bacteria b into the database.
etc.

Also, it is probably helpful to take a look at the implementation of proposed "Copy And Adjust" algorihtm in the class:
bactimas.algorithms.CopyAndAdjustAlgorithm implements ITrackingAlgorithm

**(b)** Append the full class name in the conf/all.algorithms file text file so that Bactimas can instantiate it at run time.

----

Recommended:
* See the already available algorithms implementing the //ITrackingAlgorithm// interface.
* Consult the [[javadoc:javadoc|JavaDoc]] for the details.

Database

2023-07-18T11:11:27Z

Igor: Created page with "== BactImAs Database == In principle, you can use any database you like as long as you can connect (have a) JDBC driver for that database. For the time being, we're using sqlite database, since it is light, portable, multi-platform and easy to install. Below, you'll find both sqlite create database script, and Microsoft SQL Server database script. Starting from those, it's easy to adjust the script for any SQL database server. Note that you should not bother with cr..."

== BactImAs Database ==

In principle, you can use any database you like as long as you can connect (have a) JDBC driver for that database.
For the time being, we're using sqlite database, since it is light, portable, multi-platform and easy to install.
Below, you'll find both sqlite create database script, and Microsoft SQL Server database script.
Starting from those, it's easy to adjust the script for any SQL database server.

Note that you should not bother with creating an empty sqlite database, there is one included in the installation package.

=== Database diagram ===

(Views are shown in gray.)\\
[[File:db.png]]

===== SqLite Create Database Script =====
CREATE TABLE Version (
version char(10) primary key
);
insert into Version(version) values ("v.0.7.");

CREATE TABLE [Bacteria] (
"idBacteria" integer PRIMARY KEY AUTOINCREMENT NOT NULL,
"idExperiment" integer,
"bactName" varchar(50) NOT NULL COLLATE NOCASE,
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment])
);
CREATE UNIQUE INDEX [Bacteria_unq_exp_bactName]
ON [Bacteria] ([idExperiment] DESC, [bactName] DESC);

CREATE TABLE [BacteriaSplit] (
"idBacteriaParent" integer NOT NULL,
"idBacteriaChildA" integer NOT NULL,
"idBacteriaChildB" integer NOT NULL,
"frameNo" integer NOT NULL,
PRIMARY KEY ([idBacteriaParent]),
FOREIGN KEY ([idBacteriaParent])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idBacteriaChildA])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idBacteriaChildB])
REFERENCES [Bacteria]([idBacteria])
);
CREATE TABLE [Measurement] (
"idMeasurement" integer PRIMARY KEY AUTOINCREMENT NOT NULL,
"measurementName" nvarchar(20) NOT NULL COLLATE NOCASE
);
CREATE UNIQUE INDEX [Measurement_unq_measurementName] ON [Measurement] ([measurementName] DESC);

CREATE TABLE [RoiType] (
"idRoiType" smallint NOT NULL,
"typeName" varchar(20) NOT NULL COLLATE NOCASE,
PRIMARY KEY ([idRoiType])
);
CREATE TABLE [Roi] (
"idBacteria" integer NOT NULL,
"frameNo" integer NOT NULL,
"idRoiType" smallint NOT NULL,
"roiBlob" blob,
"roiName" nvarchar(50) COLLATE NOCASE,
PRIMARY KEY ([idBacteria], [frameNo], [idRoiType]),
FOREIGN KEY ([idBacteria])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idRoiType])
REFERENCES [RoiType]([idRoiType])
);

CREATE TABLE [Frame] (
"idFrame" integer PRIMARY KEY AUTOINCREMENT NOT NULL,
"idExperiment" integer,
"frameNo" integer NOT NULL,
"frameRedFileName" nvarchar(500) COLLATE NOCASE,
"frameGreenFileName" nvarchar(500) COLLATE NOCASE,
"frameBlueFileName" nvarchar(500) COLLATE NOCASE,
"transX" smallint DEFAULT 0,
"transY" smallint DEFAULT 0,
ignoreFrame char(1) default 'n',
bgRedMean double,
bgGreenMean double,
bgBlueMean double,
Algorithm varchar(500),
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment])
);
CREATE INDEX idx_frame_id_experiment_frame_no on frame(idExperiment, frameNo);
CREATE TABLE [ExperimentMeasurements] (
"idExperiment" integer NOT NULL,
"idMeasurement" smallint NOT NULL,
"idChannel" smallint, collarSize int default 0,
PRIMARY KEY ([idExperiment], [idMeasurement])
,
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment]),
FOREIGN KEY ([idMeasurement])
REFERENCES [Measurement]([idMeasurement])
);
CREATE TABLE [Channel] (
"idChannel" smallint NOT NULL,
"channelName" nvarchar(5) NOT NULL COLLATE NOCASE,
PRIMARY KEY ([idChannel])

);
CREATE TABLE [Palette] (
"idPalette" smallint NOT NULL,
"paletteName" nvarchar(30) NOT NULL COLLATE NOCASE,
PRIMARY KEY ([idPalette])

);
CREATE TABLE [PaletteColor] (
"idPalette" smallint NOT NULL,
"ordinal" smallint NOT NULL,
"red" smallint NOT NULL,
"green" smallint NOT NULL,
"blue" smallint NOT NULL,
PRIMARY KEY ([idPalette], [ordinal])
);
CREATE TABLE [Experiment] (

[idExperiment] integer PRIMARY KEY AUTOINCREMENT NOT NULL,
[expName] char(100) NULL,
[redMovieFileName] nvarchar(500) NULL,
[greenMovieFileName] nvarchar(500) NULL,
[blueMovieFileName] nvarchar(500) NOT NULL,
[movieSpf] INTEGER NULL,
[dateCreated] integer NULL,
pixelWidthMicron decimal(6,2),
pixelHeightMicron decimal(6,2),
pictureScale decimal(6,2)
);

CREATE TABLE [BacteriaMeasurement] (
"idBacteria" integer NOT NULL,
"frameNo" integer NOT NULL,
"idMeasurement" smallint NOT NULL,
"idRoiType" smallint NOT NULL,
"idChannel" smallint not null,
"value" float NOT NULL,
PRIMARY KEY ([idBacteria], [frameNo], [idMeasurement], [idRoiType], idChannel),
FOREIGN KEY ([idBacteria])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idMeasurement])
REFERENCES [Measurement]([idMeasurement]),
FOREIGN KEY ([idChannel])
REFERENCES [Channel]([idChannel])
);

CREATE TABLE BacteriaState (
idState integer PRIMARY KEY,
stateName varchar(50) not null,
stateTag char(1) not null
);
CREATE TABLE BacteriaStateChange (
idBacteria integer ,
frameNo integer ,
idState integer ,
PRIMARY KEY (idBacteria, frameNo, idState),
FOREIGN KEY (idBacteria) REFERENCES Bacteria(idBacteria),
FOREIGN KEY (idState) REFERENCES BacteriaState(idState)
);
CREATE TABLE ExperimentEvent (
idExperiment integer NOT NULL,
frameNo integer NOT NULL,
eventDesc varchar(255) not null,
eventAbbr varchar(15) not null,
PRIMARY KEY (idExperiment, frameNo),
FOREIGN KEY (idExperiment) REFERENCES Experiment(idExperiment)
);

INSERT INTO Measurement(measurementName) VALUES ('area');
INSERT INTO Measurement(measurementName) VALUES ('mean');
INSERT INTO Measurement(measurementName) VALUES ('min');
INSERT INTO Measurement(measurementName) VALUES ('max');
INSERT INTO Measurement(measurementName) VALUES ('x');
INSERT INTO Measurement(measurementName) VALUES ('y');
INSERT INTO Measurement(measurementName) VALUES ('perim.');
INSERT INTO Measurement(measurementName) VALUES ('major');
INSERT INTO Measurement(measurementName) VALUES ('minor');
INSERT INTO Measurement(measurementName) VALUES ('angle');
INSERT INTO Measurement(measurementName) VALUES ('feret');
INSERT INTO Measurement(measurementName) VALUES ('kurt');
INSERT INTO Measurement(measurementName) VALUES ('slice');
INSERT INTO Measurement(measurementName) VALUES ('feretx');
INSERT INTO Measurement(measurementName) VALUES ('ferety');
INSERT INTO Measurement(measurementName) VALUES ('feretangle');
INSERT INTO Measurement(measurementName) VALUES ('minferet');
INSERT INTO Measurement(measurementName) VALUES ('length');
INSERT INTO Measurement(measurementName) VALUES ('width');
INSERT INTO Measurement(measurementName) VALUES ('rawintden');
INSERT INTO Measurement(measurementName) VALUES ('intden');
INSERT INTO Measurement(measurementName) VALUES ('stddev');
INSERT INTO Measurement(measurementName) VALUES ('height');
INSERT INTO Measurement(measurementName) VALUES ('median');

INSERT INTO Channel(idChannel, channelName) VALUES (1,'Red');
INSERT INTO Channel(idChannel, channelName) VALUES (2,'Green');
INSERT INTO Channel(idChannel, channelName) VALUES (3,'Blue');

insert into Palette(idPalette, paletteName) values (1, 'Default pallete');

INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,1,0,0,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,2,0,0,255);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,3,0,255,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,4,255,127,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,5,255,0,0);

insert into BacteriaState values (1, 'Death', '*');
insert into BacteriaState values (2, 'Ignore', '#');

CREATE VIEW vBacteriaMeanMeasurement as
SELECT idBacteria, frameNo, channelName, AVG(value) as mean, count(*) as cnt -- if there are duplicate measuements on diff channels
FROM BacteriaMeasurement
JOIN Measurement
ON BacteriaMeasurement.idMeasurement = Measurement.idMeasurement
AND lower(measurementName) = 'mean'
JOIN Channel
ON BacteriaMeasurement.idChannel = Channel.idChannel
GROUP BY idBacteria, frameNo, channelName;

CREATE VIEW vBacteriaAreaMeasurement as
SELECT MArea.idBacteria, frameNo, pixelWidthMicron * pixelHeightMicron * AVG(value)/(pictureScale * pictureScale) as areaSquareMicron, AVG(value) as area, count(*) as cnt -- if there are duplicate measuements on diff channels
FROM BacteriaMeasurement AS MArea
JOIN Measurement
ON MArea.idMeasurement = measurement.idMeasurement
AND lower(measurementName) = 'area'
JOIN Bacteria
ON MArea.idBacteria = Bacteria.idBacteria
JOIN Experiment
ON Bacteria.idExperiment = Experiment.idExperiment
GROUP BY MArea.idBacteria, frameNo, pixelWidthMicron, pixelHeightMicron, pictureScale;

CREATE VIEW vBacteriaMeasurement AS
SELECT expName as exp_name,
Bacteria.idExperiment AS id_experiment,
DistBactMeasurement.frameNo AS frame_no,
DistBactMeasurement.frameNo * movieSpf AS time_s,
Bacteria.bactName AS bact_name,
Bacteria.idBacteria AS id_bacteria,

length (Bacteria.bactName) AS generation,
Birth.parentName AS parent,
CASE WHEN (Bacteria.bactName = Birth.childAName) THEN Birth.childBName
ELSE Birth.childAName
END AS sibling,
-- Division.childAName || ', ' || Division.childBName AS progeny,
Division.childAName AS progeny_a,
Division.childBName AS progeny_b,

(Birth.frameNo - 1) * movieSpf AS birth_time,
(Division.frameNo - 1) * movieSpf AS division_time,
(Division.frameNo - Birth.frameNo) * movieSpf AS interdivision_time,

1.0 * (DivisionArea.areaSquareMicron/BirthArea.areaSquareMicron)/((Division.frameNo - Birth.frameNo) * movieSpf) AS growth_rate,
1.0 * (DivisionArea.areaSquareMicron - BirthArea.areaSquareMicron)/((Division.frameNo - Birth.frameNo) * movieSpf) AS growth_velocity,

CurrArea.area,
CurrArea.areaSquareMicron AS area_square_microns,
CASE WHEN (PrevFrame.frameNo IS NULL) THEN 0
ELSE CurrArea.areaSquareMicron - PrevArea.areaSquareMicron
END AS area_square_microns_growth,

CurrRedMean.Mean AS red_mean,
currGreenMean.Mean AS green_mean,
currBlueMean.Mean AS blue_mean,

Frame.bgRedMean AS red_bg,
Frame.bgGreenMean AS green_bg,
Frame.bgBlueMean AS blue_bg,

(CurrRedMean.Mean - Frame.bgRedMean) AS red_mean_bg_cor,
(currGreenMean.Mean - Frame.bgGreenMean) AS green_mean_bg_cor,
(currBlueMean.Mean - Frame.bgBlueMean) AS blue_mean_bg_cor,

(CurrRedMean.Mean - Frame.bgRedMean) * CurrArea.areaSquareMicron AS red_ctcf,
(currGreenMean.Mean - Frame.bgGreenMean) * CurrArea.areaSquareMicron AS green_ctcf,
(currBlueMean.Mean - Frame.bgBlueMean) * CurrArea.areaSquareMicron AS blue_ctcf,

(CurrRedMean.Mean - Frame.bgRedMean) - (PrevRedMean.Mean - PrevFrame.bgRedMean) AS red_mean_bg_cor_change,
(CurrGreenMean.Mean - Frame.bgGreenMean) - (PrevGreenMean.Mean - PrevFrame.bgGreenMean) AS green_mean_bg_cor_change,
(CurrBlueMean.Mean - Frame.bgBlueMean) - (PrevBlueMean.Mean - PrevFrame.bgBlueMean) AS blue_mean_bg_cor_change,

(CurrRedMean.Mean - Frame.bgRedMean) * CurrArea.areaSquareMicron - (PrevRedMean.Mean - PrevFrame.bgRedMean) * PrevArea.areaSquareMicron AS red_ctcf_change,
(CurrGreenMean.Mean - Frame.bgGreenMean) * CurrArea.areaSquareMicron - (PrevGreenMean.Mean - PrevFrame.bgGreenMean) * PrevArea.areaSquareMicron AS green_ctcf_change,
(CurrBlueMean.Mean - Frame.bgBlueMean) * CurrArea.areaSquareMicron - (PrevBlueMean.Mean - PrevFrame.bgBlueMean) * PrevArea.areaSquareMicron AS blue_ctcf_change

FROM (SELECT DISTINCT idBacteria, frameNo FROM BacteriaMeasurement) AS DistBactMeasurement
JOIN Bacteria
ON DistBactMeasurement.idBacteria = bacteria.idBacteria
JOIN Experiment
ON Bacteria.idExperiment = Experiment.idExperiment
JOIN Frame
ON Bacteria.idExperiment = Frame.idExperiment
AND DistBactMeasurement.frameNo = Frame.frameNo
AND Frame.ignoreFrame = 'n'
LEFT JOIN Frame PrevFrame
ON PrevFrame.idExperiment = Bacteria.idExperiment
AND PrevFrame.frameNo = (SELECT MAX(frameNo) FROM Frame F WHERE F.idExperiment = PrevFrame.idExperiment AND F.frameNo < DistBactMeasurement.frameNo AND ignoreFrame = 'n')
LEFT JOIN (
SELECT BirthParent.bactName AS parentName, idBacteriaChildA, idBacteriaChildB, BirthChildA.bactName AS childAName, BirthChildB.bactName AS childBName, frameNo
FROM BacteriaSplit
JOIN Bacteria AS BirthParent ON BacteriaSplit.idBacteriaParent = BirthParent.idBacteria
JOIN Bacteria AS BirthChildA ON BacteriaSplit.idBacteriaChildA = BirthChildA.idBacteria
JOIN Bacteria AS BirthChildB ON BacteriaSplit.idBacteriaChildB = BirthChildB.idBacteria
) AS Birth
ON (DistBactMeasurement.idBacteria = Birth.idBacteriaChildA OR DistBactMeasurement.idBacteria = Birth.idBacteriaChildB)

LEFT JOIN (
SELECT idBacteriaParent, DivChildA.bactName AS childAName, DivChildB.bactName AS childBName, frameNo
FROM BacteriaSplit
JOIN Bacteria AS DivChildA ON BacteriaSplit.idBacteriaChildA = DivChildA.idBacteria
JOIN Bacteria AS DivChildB ON BacteriaSplit.idBacteriaChildB = DivChildB.idBacteria
) AS Division
ON (DistBactMeasurement.idBacteria = Division.idBacteriaParent)

LEFT JOIN vBacteriaAreaMeasurement AS BirthArea
ON Birth.frameNo = BirthArea.frameNo
AND DistBactMeasurement.idBacteria = BirthArea.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS DivisionArea
ON DivisionArea.frameNo = ((SELECT MAX(frameNo) FROM Frame F WHERE F.idExperiment = Experiment.idExperiment AND F.frameNo < Division.frameNo AND ignoreFrame = 'n'))
AND DivisionArea.idBacteria = DistBactMeasurement.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS PrevArea
ON PrevFrame.frameNo = PrevArea.frameNo
AND DistBactMeasurement.idBacteria = PrevArea.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS CurrArea
ON DistBactMeasurement.frameNo = CurrArea.frameNo
AND DistBactMeasurement.idBacteria = CurrArea.idBacteria
--// Prev mean
LEFT JOIN vBacteriaMeanMeasurement AS prevBlueMean
ON PrevFrame.frameNo = prevBlueMean.frameNo
AND DistBactMeasurement.idBacteria = prevBlueMean.idBacteria
AND prevBlueMean.channelName = 'Blue'
LEFT JOIN vBacteriaMeanMeasurement AS prevGreenMean
ON PrevFrame.frameNo = prevGreenMean.frameNo
AND DistBactMeasurement.idBacteria = prevGreenMean.idBacteria
AND prevGreenMean.channelName = 'Green'
LEFT JOIN vBacteriaMeanMeasurement AS PrevRedMean
ON PrevFrame.frameNo = PrevRedMean.frameNo
AND DistBactMeasurement.idBacteria = PrevRedMean.idBacteria
AND PrevRedMean.channelName = 'Red'
--// Curr mean
LEFT JOIN vBacteriaMeanMeasurement AS currBlueMean
ON DistBactMeasurement.frameNo = currBlueMean.frameNo
AND DistBactMeasurement.idBacteria = currBlueMean.idBacteria
AND currBlueMean.channelName = 'Blue'
LEFT JOIN vBacteriaMeanMeasurement AS currGreenMean
ON DistBactMeasurement.frameNo = currGreenMean.frameNo
AND DistBactMeasurement.idBacteria = currGreenMean.idBacteria
AND currGreenMean.channelName = 'Green'
LEFT JOIN vBacteriaMeanMeasurement AS CurrRedMean
ON DistBactMeasurement.frameNo = CurrRedMean.frameNo
AND DistBactMeasurement.idBacteria = CurrRedMean.idBacteria
AND CurrRedMean.channelName = 'Red';

===== MS Sql Server Create Database Script =====
CREATE TABLE Version (
version char(10) primary key
);
insert into Version(version) values ('v.0.7.');

CREATE TABLE [Experiment] (
[idExperiment] integer PRIMARY KEY identity(1000, 1) NOT NULL,
[expName] char(100) NULL,
[redMovieFileName] nvarchar(500) NULL,
[greenMovieFileName] nvarchar(500) NULL,
[blueMovieFileName] nvarchar(500) NOT NULL,
[movieSpf] INTEGER NULL,
[dateCreated] integer NULL,
pixelWidthMicron decimal(6,2),
pixelHeightMicron decimal(6,2),
pictureScale decimal(6,2)
);

CREATE TABLE [Bacteria] (
idBacteria integer PRIMARY KEY identity(1, 1) NOT NULL,
idExperiment integer,
bactName varchar(50) NOT NULL ,
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment])
);
CREATE UNIQUE INDEX [Bacteria_unq_exp_bactName]
ON [Bacteria] ([idExperiment] DESC, [bactName] DESC);

CREATE TABLE [BacteriaSplit] (
idBacteriaParent integer NOT NULL,
idBacteriaChildA integer NOT NULL,
idBacteriaChildB integer NOT NULL,
frameNo integer NOT NULL,
PRIMARY KEY ([idBacteriaParent]),
FOREIGN KEY ([idBacteriaParent])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idBacteriaChildA])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idBacteriaChildB])
REFERENCES [Bacteria]([idBacteria])
);
CREATE TABLE [Measurement] (
idMeasurement integer PRIMARY KEY identity NOT NULL,
measurementName nvarchar(20) NOT NULL
);
CREATE UNIQUE INDEX [Measurement_unq_measurementName] ON [Measurement] ([measurementName] DESC);
INSERT INTO Measurement(measurementName) VALUES ('area');
INSERT INTO Measurement(measurementName) VALUES ('mean');
INSERT INTO Measurement(measurementName) VALUES ('min');
INSERT INTO Measurement(measurementName) VALUES ('max');
INSERT INTO Measurement(measurementName) VALUES ('x');
INSERT INTO Measurement(measurementName) VALUES ('y');
INSERT INTO Measurement(measurementName) VALUES ('perim.');
INSERT INTO Measurement(measurementName) VALUES ('major');
INSERT INTO Measurement(measurementName) VALUES ('minor');
INSERT INTO Measurement(measurementName) VALUES ('angle');
INSERT INTO Measurement(measurementName) VALUES ('feret');
INSERT INTO Measurement(measurementName) VALUES ('kurt');
INSERT INTO Measurement(measurementName) VALUES ('slice');
INSERT INTO Measurement(measurementName) VALUES ('feretx');
INSERT INTO Measurement(measurementName) VALUES ('ferety');
INSERT INTO Measurement(measurementName) VALUES ('feretangle');
INSERT INTO Measurement(measurementName) VALUES ('minferet');
INSERT INTO Measurement(measurementName) VALUES ('length');
INSERT INTO Measurement(measurementName) VALUES ('width');
INSERT INTO Measurement(measurementName) VALUES ('rawintden');
INSERT INTO Measurement(measurementName) VALUES ('intden');
INSERT INTO Measurement(measurementName) VALUES ('stddev');
INSERT INTO Measurement(measurementName) VALUES ('height');
INSERT INTO Measurement(measurementName) VALUES ('median');

CREATE TABLE [RoiType] (
idRoiType smallint NOT NULL,
typeName varchar(20) NOT NULL ,
PRIMARY KEY ([idRoiType])
);

insert into RoiType values (1, 'Human')
insert into RoiType values (2, 'Computer')

CREATE TABLE [Roi] (
idBacteria integer NOT NULL,
frameNo integer NOT NULL,
idRoiType smallint NOT NULL,
roiBlob VARBINARY (MAX),
roiName nvarchar(50) ,
PRIMARY KEY ([idBacteria], [frameNo], [idRoiType]),
FOREIGN KEY ([idBacteria])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idRoiType])
REFERENCES [RoiType]([idRoiType])
);

CREATE TABLE [Frame] (
idFrame integer PRIMARY KEY identity ,
idExperiment integer,
frameNo integer NOT NULL,
frameRedFileName nvarchar(500) ,
frameGreenFileName nvarchar(500) ,
frameBlueFileName nvarchar(500) ,
transX smallint DEFAULT 0,
transY smallint DEFAULT 0,
ignoreFrame char(1) default 'n',
bgRedMean float(53),
bgGreenMean float(53),
bgBlueMean float(53),
[Algorithm] varchar(500),
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment])
);
CREATE INDEX idx_frame_id_experiment_frame_no on frame(idExperiment, frameNo)
CREATE TABLE [ExperimentMeasurements] (
idExperiment integer NOT NULL,
idMeasurement integer NOT NULL,
idChannel smallint,
collarSize int default 0,
PRIMARY KEY ([idExperiment], [idMeasurement]),
FOREIGN KEY ([idExperiment])
REFERENCES [Experiment]([idExperiment]),
FOREIGN KEY ([idMeasurement])
REFERENCES [Measurement]([idMeasurement])
);
CREATE TABLE [Channel] (
idChannel smallint NOT NULL,
channelName nvarchar(5) NOT NULL ,
PRIMARY KEY ([idChannel])

);

INSERT INTO Channel(idChannel, channelName) VALUES (1,'Red');
INSERT INTO Channel(idChannel, channelName) VALUES (2,'Green');
INSERT INTO Channel(idChannel, channelName) VALUES (3,'Blue');

CREATE TABLE [Palette] (
idPalette smallint NOT NULL,
paletteName nvarchar(30) NOT NULL,
PRIMARY KEY ([idPalette])

);

insert into Palette(idPalette, paletteName) values (1, 'Default pallete')

CREATE TABLE [PaletteColor] (
idPalette smallint NOT NULL,
ordinal smallint NOT NULL,
red smallint NOT NULL,
green smallint NOT NULL,
blue smallint NOT NULL,
PRIMARY KEY ([idPalette], [ordinal])
FOREIGN KEY ([idPalette])
REFERENCES [Palette]([idPalette])
);

INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,1,0,0,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,2,0,0,255);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,3,0,255,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,4,255,127,0);
INSERT INTO PaletteColor(idPalette, ordinal, red, green, blue) VALUES (1,5,255,0,0);

CREATE TABLE [BacteriaMeasurement] (
idBacteria integer NOT NULL,
frameNo integer NOT NULL,
idMeasurement int NOT NULL,
idRoiType smallint NOT NULL,
idChannel smallint not null,
value float NOT NULL,
PRIMARY KEY ([idBacteria], [frameNo], [idMeasurement], [idRoiType], idChannel),
FOREIGN KEY ([idBacteria])
REFERENCES [Bacteria]([idBacteria]),
FOREIGN KEY ([idMeasurement])
REFERENCES [Measurement]([idMeasurement]),
FOREIGN KEY ([idChannel])
REFERENCES [Channel]([idChannel])
);

CREATE TABLE BacteriaState (
idState integer PRIMARY KEY,
stateName varchar(50) not null,
stateTag char(1) not null
);

insert into BacteriaState values (1, 'Death', '*');
insert into BacteriaState values (2, 'Ignore', '#');

CREATE TABLE BacteriaStateChange (
idBacteria integer ,
frameNo integer ,
idState integer ,
PRIMARY KEY (idBacteria, frameNo, idState),
FOREIGN KEY (idBacteria) REFERENCES Bacteria(idBacteria),
FOREIGN KEY (idState) REFERENCES BacteriaState(idState)
);
CREATE TABLE ExperimentEvent (
idExperiment integer NOT NULL,
frameNo integer NOT NULL,
eventDesc varchar(255) not null,
eventAbbr varchar(15) not null,
PRIMARY KEY (idExperiment, frameNo),
FOREIGN KEY (idExperiment) REFERENCES Experiment(idExperiment)
);

CREATE VIEW vBacteriaMeanMeasurement as
SELECT idBacteria, frameNo, channelName, AVG(value) as mean, count(*) as cnt -- if there are duplicate measuements on diff channels
FROM BacteriaMeasurement
JOIN Measurement
ON BacteriaMeasurement.idMeasurement = Measurement.idMeasurement
AND lower(measurementName) = 'mean'
JOIN Channel
ON BacteriaMeasurement.idChannel = Channel.idChannel
GROUP BY idBacteria, frameNo, channelName;

CREATE VIEW vBacteriaAreaMeasurement as
SELECT MArea.idBacteria, frameNo, pixelWidthMicron * pixelHeightMicron * AVG(value)/(pictureScale * pictureScale) as areaSquareMicron, AVG(value) as area, count(*) as cnt -- if there are duplicate measuements on diff channels
FROM BacteriaMeasurement AS MArea
JOIN Measurement
ON MArea.idMeasurement = measurement.idMeasurement
AND lower(measurementName) = 'area'
JOIN Bacteria
ON MArea.idBacteria = Bacteria.idBacteria
JOIN Experiment
ON Bacteria.idExperiment = Experiment.idExperiment
GROUP BY MArea.idBacteria, frameNo, pixelWidthMicron, pixelHeightMicron, pictureScale;

CREATE VIEW vBacteriaMeasurement AS
SELECT expName as exp_name,
Bacteria.idExperiment AS id_experiment,
DistBactMeasurement.frameNo AS frame_no,
DistBactMeasurement.frameNo * movieSpf AS time_s,
Bacteria.bactName AS bact_name,
Bacteria.idBacteria AS id_bacteria,

len (Bacteria.bactName) AS generation,
Birth.parentName AS parent,
CASE WHEN (Bacteria.bactName = Birth.childAName) THEN Birth.childBName
ELSE Birth.childAName
END AS sibling,
-- Division.childAName || ', ' || Division.childBName AS progeny,
Division.childAName AS progeny_a,
Division.childBName AS progeny_b,

(Birth.frameNo - 1) * movieSpf AS birth_time,
(Division.frameNo - 1) * movieSpf AS division_time,
(Division.frameNo - Birth.frameNo) * movieSpf AS interdivision_time,

1.0 * (DivisionArea.areaSquareMicron/BirthArea.areaSquareMicron)/((Division.frameNo - Birth.frameNo) * movieSpf) AS growth_rate,
1.0 * (DivisionArea.areaSquareMicron - BirthArea.areaSquareMicron)/((Division.frameNo - Birth.frameNo) * movieSpf) AS growth_velocity,

CurrArea.area,
CurrArea.areaSquareMicron AS area_square_microns,
CASE WHEN (PrevFrame.frameNo IS NULL) THEN 0
ELSE CurrArea.areaSquareMicron - PrevArea.areaSquareMicron
END AS area_square_microns_growth,

CurrRedMean.Mean AS red_mean,
currGreenMean.Mean AS green_mean,
currBlueMean.Mean AS blue_mean,

Frame.bgRedMean AS red_bg,
Frame.bgGreenMean AS green_bg,
Frame.bgBlueMean AS blue_bg,

(CurrRedMean.Mean - Frame.bgRedMean) AS red_mean_bg_cor,
(currGreenMean.Mean - Frame.bgGreenMean) AS green_mean_bg_cor,
(currBlueMean.Mean - Frame.bgBlueMean) AS blue_mean_bg_cor,

(CurrRedMean.Mean - Frame.bgRedMean) * CurrArea.areaSquareMicron AS red_ctcf,
(currGreenMean.Mean - Frame.bgGreenMean) * CurrArea.areaSquareMicron AS green_ctcf,
(currBlueMean.Mean - Frame.bgBlueMean) * CurrArea.areaSquareMicron AS blue_ctcf,

(CurrRedMean.Mean - Frame.bgRedMean) - (PrevRedMean.Mean - PrevFrame.bgRedMean) AS red_mean_bg_cor_change,
(CurrGreenMean.Mean - Frame.bgGreenMean) - (PrevGreenMean.Mean - PrevFrame.bgGreenMean) AS green_mean_bg_cor_change,
(CurrBlueMean.Mean - Frame.bgBlueMean) - (PrevBlueMean.Mean - PrevFrame.bgBlueMean) AS blue_mean_bg_cor_change,

(CurrRedMean.Mean - Frame.bgRedMean) * CurrArea.areaSquareMicron - (PrevRedMean.Mean - PrevFrame.bgRedMean) * PrevArea.areaSquareMicron AS red_ctcf_change,
(CurrGreenMean.Mean - Frame.bgGreenMean) * CurrArea.areaSquareMicron - (PrevGreenMean.Mean - PrevFrame.bgGreenMean) * PrevArea.areaSquareMicron AS green_ctcf_change,
(CurrBlueMean.Mean - Frame.bgBlueMean) * CurrArea.areaSquareMicron - (PrevBlueMean.Mean - PrevFrame.bgBlueMean) * PrevArea.areaSquareMicron AS blue_ctcf_change

FROM (SELECT DISTINCT idBacteria, frameNo FROM BacteriaMeasurement) AS DistBactMeasurement
JOIN Bacteria
ON DistBactMeasurement.idBacteria = bacteria.idBacteria
JOIN Experiment
ON Bacteria.idExperiment = Experiment.idExperiment
JOIN Frame
ON Bacteria.idExperiment = Frame.idExperiment
AND DistBactMeasurement.frameNo = Frame.frameNo
AND Frame.ignoreFrame = 'n'
LEFT JOIN Frame PrevFrame
ON PrevFrame.idExperiment = Bacteria.idExperiment
AND PrevFrame.frameNo = (SELECT MAX(frameNo) FROM Frame F WHERE F.idExperiment = PrevFrame.idExperiment AND F.frameNo < DistBactMeasurement.frameNo AND ignoreFrame = 'n')
LEFT JOIN (
SELECT BirthParent.bactName AS parentName, idBacteriaChildA, idBacteriaChildB, BirthChildA.bactName AS childAName, BirthChildB.bactName AS childBName, frameNo
FROM BacteriaSplit
JOIN Bacteria AS BirthParent ON BacteriaSplit.idBacteriaParent = BirthParent.idBacteria
JOIN Bacteria AS BirthChildA ON BacteriaSplit.idBacteriaChildA = BirthChildA.idBacteria
JOIN Bacteria AS BirthChildB ON BacteriaSplit.idBacteriaChildB = BirthChildB.idBacteria
) AS Birth
ON (DistBactMeasurement.idBacteria = Birth.idBacteriaChildA OR DistBactMeasurement.idBacteria = Birth.idBacteriaChildB)

LEFT JOIN (
SELECT idBacteriaParent, DivChildA.bactName AS childAName, DivChildB.bactName AS childBName, frameNo
FROM BacteriaSplit
JOIN Bacteria AS DivChildA ON BacteriaSplit.idBacteriaChildA = DivChildA.idBacteria
JOIN Bacteria AS DivChildB ON BacteriaSplit.idBacteriaChildB = DivChildB.idBacteria
) AS Division
ON (DistBactMeasurement.idBacteria = Division.idBacteriaParent)

LEFT JOIN vBacteriaAreaMeasurement AS BirthArea
ON Birth.frameNo = BirthArea.frameNo
AND DistBactMeasurement.idBacteria = BirthArea.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS DivisionArea
ON DivisionArea.frameNo = ((SELECT MAX(frameNo) FROM Frame F WHERE F.idExperiment = Experiment.idExperiment AND F.frameNo < Division.frameNo AND ignoreFrame = 'n'))
AND DivisionArea.idBacteria = DistBactMeasurement.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS PrevArea
ON PrevFrame.frameNo = PrevArea.frameNo
AND DistBactMeasurement.idBacteria = PrevArea.idBacteria

LEFT JOIN vBacteriaAreaMeasurement AS CurrArea
ON DistBactMeasurement.frameNo = CurrArea.frameNo
AND DistBactMeasurement.idBacteria = CurrArea.idBacteria
--// Prev mean
LEFT JOIN vBacteriaMeanMeasurement AS prevBlueMean
ON PrevFrame.frameNo = prevBlueMean.frameNo
AND DistBactMeasurement.idBacteria = prevBlueMean.idBacteria
AND prevBlueMean.channelName = 'Blue'
LEFT JOIN vBacteriaMeanMeasurement AS prevGreenMean
ON PrevFrame.frameNo = prevGreenMean.frameNo
AND DistBactMeasurement.idBacteria = prevGreenMean.idBacteria
AND prevGreenMean.channelName = 'Green'
LEFT JOIN vBacteriaMeanMeasurement AS PrevRedMean
ON PrevFrame.frameNo = PrevRedMean.frameNo
AND DistBactMeasurement.idBacteria = PrevRedMean.idBacteria
AND PrevRedMean.channelName = 'Red'
--// Curr mean
LEFT JOIN vBacteriaMeanMeasurement AS currBlueMean
ON DistBactMeasurement.frameNo = currBlueMean.frameNo
AND DistBactMeasurement.idBacteria = currBlueMean.idBacteria
AND currBlueMean.channelName = 'Blue'
LEFT JOIN vBacteriaMeanMeasurement AS currGreenMean
ON DistBactMeasurement.frameNo = currGreenMean.frameNo
AND DistBactMeasurement.idBacteria = currGreenMean.idBacteria
AND currGreenMean.channelName = 'Green'
LEFT JOIN vBacteriaMeanMeasurement AS CurrRedMean
ON DistBactMeasurement.frameNo = CurrRedMean.frameNo
AND DistBactMeasurement.idBacteria = CurrRedMean.idBacteria
AND CurrRedMean.channelName = 'Red';

JavaDoc

2023-07-18T11:09:20Z

Igor:

JavaDoc

2023-07-18T11:07:18Z

Igor:

JavaDoc

2023-07-18T11:06:26Z

Igor:

JavaDoc

2023-07-18T11:01:20Z

Igor: Created page with "{{url>https://homer.zpr.fer.hr/bactimas_javadoc/index.html 98%, 1024px}}"

{{url>https://homer.zpr.fer.hr/bactimas_javadoc/index.html 98%, 1024px}}

MediaWiki:Sidebar

2023-07-18T11:01:09Z

Igor:

MediaWiki:Sidebar

2023-07-18T11:00:54Z

Igor:

Video tutorial

2023-07-18T10:56:47Z

Igor: Created page with "= Video Tutorial = == 1. BactImAs structure and Phase 1 == Video explaining BactImAs structure and where to store experiment images and databases. <youtube>B_A87dSbhP8</youtube> == 2. New experiment == Video explaining how to define new experiment, and set the initial cell ROIs. <youtube>fEv40wU9x_Y</youtube>"

= Video Tutorial =

== 1. BactImAs structure and Phase 1 ==
Video explaining BactImAs structure and where to store experiment images and databases.
<youtube>B_A87dSbhP8</youtube>

== 2. New experiment ==
Video explaining how to define new experiment, and set the initial cell ROIs.

<youtube>fEv40wU9x_Y</youtube>

User manual

2023-07-18T10:55:33Z

Igor: /* 6.3. SQL Pane */

====== BactImAs User Manual ======

===== 1. BactImAs GUI =====
Image below shows the BactImAs GUI.

GUI consists of three main parts:
* R/G/B channel images, scrollable image panes showing every second frame of the experiment
* Frame/cell tree on the right showing all frames and cells/ROIs
* Status window showing messages from the program (can be minified)

[[File:Bactrack_gui.png|600px]]

If you chose (click) on a frame(on the tree or on the R/G/B channel image) a new image stack will appear showing that frame's images in all combinations: R, G, B, R+G, R+B, B+G, RGB, with annotated ROIs (you can turn off annotations using Roi Manager):

[[File:Frame.png|300px]]

One can scroll to any of these and use it (typically) to assign ROIs using ImageJ polygon selection tool.

Every GUI command/option is described in detail below (also, note the table of contents on the upper right side).

===== 2. Experiment =====

//**Note: please read the installation instructions first, especially the "BactImAs structure" part.**//

==== 2.1. Setup new experiment ====

You must prepare, beforehand, three folders: red, green and blue (each containing image sequence of the appropriate channel).
Images must be 8-bit PNGs, and must be named unanimously (having the same name, and increasing number at the end), e.g.:
* phase_image_0000.png
* phase_image_0001.png
* phase_image_0002.png
* ...

Don't worry, ImageJ will do this for you (by deafault), if you say File->Save As->Image sequence.
Also, note that once you've processed the movie (i.e. performed cell segmentations) you can measure on a whole different set of images (typically original TIFFs), as long as the ROIs (cell selections) hit the same spot.
These folders should not be moved afterwards (in this version) - the program will expect images to be at the same place when you (later) load the experiment.
Should you move them, you'll have to edit the experiment properties and set the new file locations.
In other words, images WILL NOT be saved to database, only the calculated/defined ROIs, measurements etc.

Once the folders are prepared (note that these can be stored anywhere (local hardrive, external server... but it is highly recommended to keep them in the default location under data/images folder). Start BactImAs.jar and select Experiment->New experiment.
You will be asked to choose folders for each channel (“Red”, “Green” and “Blue”. (the location you define in this step will be saved but can be changed later if you decide to move the folders). Then you must give an unique name to your experiment. Next to this name, BactImAs automatically assigns exp. id (e.g. id 1076) that can be later used in SQL queries. BactImAs will then load images in a few sec and you are ready to start the time-lapse movie processing.

Optional: This is a good time to also define here some important experimental settings such as pixel size. However, you can also do it at any other time.

==== 2.2. Load experiment ====
Use Experiment->Load ( Alt+2) to load an experiment.
Pick an existing experiment and wait for the experiment to load.
If you don't see the images on the R/G/B channels, that probably means that you haven't set up the folders right (see above), or you received a database from someone else and need to point the R/G/B folders to new locations.
Either way:
==== 2.3. Edit experiment (settings) ====
Once you've loaded the experiment you can change it's settings via Experiment->Edit current experiment (Alt+4).
You'll get a dialog like this one:

[[File:Editexperiment.png|400px]]

The most common use case for changing the experiment settings is when someone sends you his or hers database and adjoining image files.
Since they've probably stored the in the different folder (than you), you'll have to change this folder paths in order for the images to load.

==== 2.4. Delete experiment ====
To delete the experiment chose Experiment->delete (Alt+3).
This will not delete the image files on your disk, just the records in the database pertaining to that experiment.

===== 3. Segmentation =====

Once you've set up your experiment, given it a name, and set the images folders, you may proceed to actual cell segmentation.

==== 3.1. Detecting translations (registering) ====

It is common for have slight translations from one frame to another (eg due to sligt camera movements).
It is very important to align or "register" such images, since the default built-in "Copy-and-Adjust" algorithm is very sensitive to such defects.
You can use an external program to align/register images beforehand, all the better (e.g. http://bigwww.epfl.ch/thevenaz/stackreg/).
However, there is also a built-in algorithm for detection of translations, and if you haven't aligned the images externally, this is the first thing you must do in the segmentation process.
The built-in algorithm is suitable only for translations, so if you have rotations or some other kind of transformations, you'll have to adjust such images externally.
=== Built-in algorith ===
Select the first frame and then click "Detect trans" button below the cell tree on the right.
The program will ask you for a range (default = 20), this number specifies the number of pixels the program will 'slide' one image over the other (in every direction) in an attempt to align them.
Start with default = 20 (bigger number = slower), you can later detect translation for just one problematic frame if you need to (with the higher value than 20).
Translations will be saved to database and you will not have to do this again.

==== 3.2. Define initial cells =====
The built-in C&A algorithm tracks cells with regars to their position on the previous frame.
This implies that you have to define the initial cells on the first frame, and start tracking from the second frame.
To achieve that:
* Open the first frame, and define bacteria. You click on the frame tree (right) and issue "Add" command to generate bacteria,
and then you click on the bacterium and "Add" human ROIs (Regions Of Interest, i.e. selections)
Then you repeat the following (for each bacterium):
* define ROI with ImageJ's polygon selection tool
* click on the appropriate Human ROI node in the frame tree and issue 'Set Roi' command.

==== 3.3. Segmentation and Tracking Algorithm ====

Before describing the tracking via built-in algorithm, a quick note on the BactTrack modular structure.
BactImAs is designed to be a "platform for the cell segmentation and tracking" and should, ideally, be able to handle any such task.
We recognize that there is no single algorithm suitable for all kinds of tracking tasks and have therefore enabled for various algorithms to be included in the BactImAs Platform and used for cell segmentation.
While algorithm design is more a task for the developers (please, see Devs documentation), the user, on the other hand, has the option to use any of the available algorithms.
Not only can different algorithms be used for different experiments, the user can assign different algorithms for different frames of the same experiment!
Using the "Set Algorithm" command, a chosen algorithm can be assigned for any frame range.
If not assigned, the default built-in "Copy And Adjust" algorithm is used.
There is a "Fast Copy And Adjust" version of the algorithm available (not default) which differs from the default algorithm in the amount of information written to the log.
The "Fast Copy And Adjust" writes minimal information and is therefore faster, however cell segmentation results are identical.

==== 3.4. Segmentation and Tracking ====

Click on the frame (e.g. second frame) and issue 'Track' command. Enter the number of frames to process (default = 5).
Track will attempt to segment the cells on the assigned number of frames starting from the selected frame.
Each cell/frame is segmented using that cell's ROI from the previous frame.
Human ROIs always have precedence over computer ROIs, e.g. if there are both human and computer ROIs on the previous frame, the algorithm will use human ROI.

When you issue the "Track" command you'll have the option of changing certain algorithm parameters.
This is useful in situations when algorithm does not perform well.

[[File:Ca_params.png|}}px]]
Parameters description:
* "Ball radius" is a value in pixel that defines the size(radius) of the disk used to "draw" the cell. You may think of it as a radius of the tip of the broad ballpen used to draw the cell. In other words, this radius relates to the width of a cell - and you can measure that width W with ImageJ (or simply by zooming and counting the pixels yourself) and then assign the ball radius to just below the W/2. The default value is 4 which is appropriate for the cells of width 9, 10, 11...
* "Channel" is simply the channel used for segmentation, or more precisely - images from the so labelled channels (folders) are used. Note that you can use e.g. blue channel for the first 10 frames, then green channel for the next five, then blue again, etc. In general, you want to use the channel on which the edge detection works best, you can try that for yourself using ImageJ or "Help decide" button below.
* "Range" is a value in pixels relating to the possible elongation of the cells on their poles. If the algorithm doesn't catch up will cell growth on the poles, you may want to increase this number.
* "Max ball delta perc" is given in percentages and defines the maximal additional area one disk can contribute when expanding the selection. If you find that the cells are erroneously growing to fast, "bubbling up" on the sides and poles, you may want to decrease this number.
* "Threshold method" - the C&A algorithm relies heavily on the edge detection (and subsequent thresholding). If the algorithm performs badly, you may want to try changing the default method, you should choose the method that best outlines the cells (click 'Help decide' to see the gallery of methods).

Once you've set the parameters, the program will attempt to track the cells. You'll be able to see the segmentation as it happens and/or inspect it again using the "Reports" facilities:

==== 3.5. Reports ====
There are two types of reports (and command buttons):
* "Color report" is a report (ImageJ stack) on which every cell is drawn in a different color, while background is drawn in black. Cell's offsprings will be drawn in the nuance of the parent-cell color, e.g. all descendant of the red cell will be drawn in nuances of red. Example: [[File:Segmentation.png|200px]]

* "Report" is a report (ImageJ stack) on which cells ROIs are outlined over original images. There is also a color/BW version of this report (you're asked to chose on click). BW report uses less memory as each of the stack's image is BW and, of course, BW use less memory than color images.
* BW - human ROIs are outlined with white, and computer ROIs with black
* Color - human ROIs are outlined with green and computer ROIs with red, e.g.: [[File:Report_with_color_option.png|200px]]

==== 3.6. Cell divisions ====

For the time being cell division recognition is not supported and cell divisions are assigned manually in the following way:
- Open the frame where bacteriium (e.g. bacterium 'B') is splitting
- Click on the bacterium 'B' on the frame tree and issue "Split" command.
- Program will replace this bacterium in the current frame with its two offsprings: 'BA' and 'BB'. They will both have the human ROIs defined (erroneously), you have to overwrite it:
* Define ROIs with ImageJ's polygon selection tool for each offspring (and click "SetRoi" to save).

Split move/delete - If you made an error and defined split on the wrong frame, you can move the split up/down N frames, or even delete it all together.
To move the split you have to select one of the children in the split frame, and click on the "Move/del split".
E.g. let's say there is a split on the frame 10: A = AA + AB. QQ
Click on either AA or AB and then click 'Move/del split'.
The procedure is also thoroughly explained (in the program) when you click the "Move/del split" (and you have a chance to cancel if you change you mind).

===== 4. Measuring =====

Once cells are segmented, various measurements are acquired in a fully automated way.
BactImAs separates these two processes which has a nice side-effect that, for instance, cell segmentation and tracking can be outsourced or performed by a different person than a person taking measurements.
Using BactImAs's (color) reports (described above), it is easy to visually inspect the quality of the segmentation process.

==== 4.1. Background correction ====

Command "Set/msr bg (R+G+B)" is used to measure (store in the database) the background intensities of the red, green and blue channel images. These are used to compute the background corrected values afterwards.
After you click on this command an ImageJ stack will appear with all the frames of the experiment:
[[File:Measure_bg.png|200px]]
Using this stack, user has to assign the (rectangular) background area (subarea of the whole image), typically the are of the image that never holds any of the cells.
As with other measures, one can chose whether to measure on the original tif images (recommmended) or the png images used for tracking and segmentation.
Status window displays the progress and acquired measures.

==== 4.2. Cell measurements ====
Cells are measured using the "Measure" command. User can chose to take any or all available ImageJ measures on the assigned channel (r,g,b).
If you want to measure the same attribute on the different channels (e.g. mean on red and green channel) you have to measure twice: first on green and then on red channel (or vice versa).
When saving measurements in the database BactImAs behaves in the following way:
(a) if the same measurement on the same channel already exists - it is overwritten
(b) otherwise, measurement is saved (added to the already existing measurements)
So, in our example, green mean will be saved according to the (b) principle, and red mean also.
Should you measure the green mean again, the initial green mean would be overwritten in accordance with (a).

Upon clicking on the "Measure", a user is presented with following dialog:
[[File:Measure.png|200px]]

In the example above, the following will be measured:
* Area on the red channel (though channel is irrelevant for area measure)
* Mean on the green channel
* IntDen on the red channel with **collar** of one pixel. **Collar** is the width of the outer rim belt you want to ignore (e.g. if you want to exclude the cell's membranes)

Typically, you want to measure area and mean on all channels.

Status window displays the progress and acquired measures.
You can repeat the measuring process arbitrary number of times, or measure (repeat for) just a assigned number of frames, etc.

BactImAs provides a number of additional, derived measures, defined as follows:
(note that you must first measure area, mean on all channels and background fluorescences on all channels for these measures to be available):

^Name ^Description ^Is numerical (= can be mapped to the lin. tree) ^
|generation |Stage of descent from a common ancestor | |
|parent |Ancestor cell of a specific bacteria | |
|sibling |Sibling cell of a specific bacteria | |
|progeny_a |Specific progeny of a bacteria | |
|progeny_b |Specific progeny of the bacteria | |
|birth_time |Frame proceeding the division event |yes|
|division_time |Frame previous to the division event |yes|
|interdivision_time |=Division_time-Birth_ time |yes|
|growth_rate |=(Area at division_time/Area at birth_time)/interdivision time |yes|
|growth_velocity |=(Area at division_time-Area at birth_time)/interdivision time |yes|
|area_square_microns |=Measured area* (pixel_width*pixel_height)/scale*scale |yes|
|area_square_microns_growth |=(area_square_microns(n)-area_square_microns(n+1))/time |yes|
|red_mean_bg_cor |=Red_mean-red_bg |yes|
|green_mean_bg_cor |=Green_mean-green_bg |yes|
|blue_mean_bg_cor |=Blue_mean-blue_bg |yes|
|red_ctcf |=red_mean_bg_cor*area_square_microns |yes|
|green_ctcf |=green_mean_bg_cor*area_square_microns |yes|
|blue_ctcf |=blue_mean_bg_cor*area_square_microns |yes|
|red_mean_bg_cor_change |=(red_mean_bg_cor (n)-red_mean_bg_cor (n+1))/time |yes|
|green_mean_bg_cor_change |=(green_mean_bg_cor(n)-green_mean_bg_cor(n+1))/time |yes|
|blue_mean_bg_cor_change |=(blue_mean_bg_cor (n)-blue_mean_bg_cor (n+1))/time) |yes|
|red_ctcf_change |=(red_ctcf(n)-red_ctcf(n+1))/time |yes|
|green_ctcf_change |=(green_ctcf(n)-green_ctcf(n+1)/time |yes|
|blue_ctcf_change |=(blue_ctcf(n)-blue_ctcg(n+1))/time |yes|

Also, note the **"area_square_microns"** measure above, that stands for cell area in square microns of course.
It is defined as: **Measured area * (pixel_width*pixel_height)/scale*scale** where:
* Measured area is measured using ImageJ's "area" measurement (as shown above)
* pixel_width, pixel_height and scale are per experiement values that can be defined via Experiment->Edit experiment

===== 5. Other (misc) commmands =====

==== 5.1. Deleting (truncating) ROIs ====
"Trunc (after)" is a rarely used option for deleting the ROIs for (after) a selected frame.
Warning: deleted ROIs cannot be recovered and you'll have to detect them again.

==== 5.2. Collapse/Expand all ====
These commands are used to collapse or expand all nodes in the Frame/cell tree.

==== 5.3. Edit event ====
Using "Edit event" one can assign an arbitrary event at a certain frame (for instance, if the experiment conditions have changed, you may want to write that in the database).
The following dialog is shown:
[[File:Event.png|200px]]

Abbreviation is used to display the event in the tree, and the full desc is displayed in the lineage tree visualization.

If you want to delete the event, just edit it, and leave everything blank and the event will be deleted.

==== 5.4. Change cell state ====
With "Change bact state" command you can assign certain state (e.g. "Ignore", "Death") to the cell from some frame onward.
[[File:Bstate.png|200px]]
New state is annotated in the tree and on the lineage tree visualization.

To delete the assigned state, just set the empty state.

==== 5.5. Toggle ignore frame ====
With this command you can ignore (or un-ignore) the selected frame.
This is typically done when the frame if of a low quality (e.g. out of focus, unusable), but you want to keep it to keep the accurate timeline.
Cells on the ignored frame are not measured nor does the frame appear in the CSV dump.
When detecting cells on the frame F, the previous frame is considered to be the frame having maximal frame number f < F, such that it is not ignored.

===== 6. Analyis and Visualization =====

==== 6.1. Lineage tree visualization ====

BactImAs features the innovative lineage tree visualization that can map two, user selected, parameters to the cell division tree.
When you're done with measurements, choose Reports->BTree from the main menu.
The following dialog appears:

[[File:Btree_dialog.png|400px]]

It is possible to assign any of the measured (and derived - built in) variables to the two visualization properties: branch width and color.
Dialog shows the area of the cell mapped to the branch width, and green_ctcf mapped to the branch color.
Other than that, it is possible to assigne the following parameters:
* seconds per frame - used for the time scale on the right, where t(frame_no) = (frame_no-1) * seconds_per_frame
* min/max stroke width - min/max parameters on the branch color are scaled to min/max stroke width
* font size
* draw labels - whether to draw the cell labels
* convert to hours - whether to convert time in seconds to format: HH:MM:SS

BactImAs will draw a separate visualization for every cell present on the firt (non-igored) frame.
The following image shows a sample visualization from the demo database:

[[File:Btree.png|600px]]

It is our intention to include in the new version of BactImAs additional out-of-the-box statistics and visualization.
However, acknowledging that it will never be possible to cover all potential requirements, we've enabled the following option:

==== 6.2. Export data as CSV file ====

With Reports->Dump CSV one can export the experiment's data into a CSV file and proceed to analyze it in one's favorite data analysis tool.

After you assign the file name, the following dialog appears:

[[File:Dumpcsv.png|400px]]

with all the available measurements for the experiment.

==== 6.3. SQL Pane ====

BactImAs stores all the data (except images) in the SqLite database.
Database can be accessed using any of the SqLite client tools - there are many such tools freely available on the Internet.
It is also possible to access it using the simple built-in SQL Pane editor, which allows for arbitrary SQL statements (queries) to be executed and displayed in a table, and even exported as CSV.
The following figure shows the SQL pane:

[[File:Sqlpane.png|400px]]

Of course, to use SQL pane one has to know the SQL programming language.
It is our intention, for the future releases of BactImAs, to build a library of predefined SQL queries, with adjoining descriptions in natural language, so that
a user that has no knowledge of SQL language can pick from the set the available predefined queries and retrieve results for his or hers experiment.

===== 7. Backup, upgrade and data exchange =====

==== 7.1. Backup ====

To backup the data one should simply copy the "data" directory to a safe place, every once in a while.

==== 7.2. Upgrade ====

When upgrading BactImAs, it is best to:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 7.3. Data exchange ====

(see also the BactImAs structure in the User->Installation)
To exchange data, it is necessary to exchange database and images folder (best zipped).

[[File:Exchange.png|400px]]

Should person A want to send experiment data to person B, these are the steps to follow:

* Person A sends the images folder (best zipped) to person B. Person B saves (extracts) them to person B's images folder. One could use cloud storage for this steps (eg Dropbox, GDrive) as images are too big for email.
* Person A sends the BactImAs.s3db file (database) from dbs folder to person B. Person B potentially renames it (to avoid clashing with person B's database), saves it to the dbs folder, and adjust the URL in the conf/db.properties to point to this new database (see User->Installation)

The second step can be repeated if there are new data measured in the database, while the first step needs to be done only once.

User manual

2023-07-18T10:55:23Z

Igor: /* 6.2. Export data as CSV file */

====== BactImAs User Manual ======

===== 1. BactImAs GUI =====
Image below shows the BactImAs GUI.

GUI consists of three main parts:
* R/G/B channel images, scrollable image panes showing every second frame of the experiment
* Frame/cell tree on the right showing all frames and cells/ROIs
* Status window showing messages from the program (can be minified)

[[File:Bactrack_gui.png|600px]]

If you chose (click) on a frame(on the tree or on the R/G/B channel image) a new image stack will appear showing that frame's images in all combinations: R, G, B, R+G, R+B, B+G, RGB, with annotated ROIs (you can turn off annotations using Roi Manager):

[[File:Frame.png|300px]]

One can scroll to any of these and use it (typically) to assign ROIs using ImageJ polygon selection tool.

Every GUI command/option is described in detail below (also, note the table of contents on the upper right side).

===== 2. Experiment =====

//**Note: please read the installation instructions first, especially the "BactImAs structure" part.**//

==== 2.1. Setup new experiment ====

You must prepare, beforehand, three folders: red, green and blue (each containing image sequence of the appropriate channel).
Images must be 8-bit PNGs, and must be named unanimously (having the same name, and increasing number at the end), e.g.:
* phase_image_0000.png
* phase_image_0001.png
* phase_image_0002.png
* ...

Don't worry, ImageJ will do this for you (by deafault), if you say File->Save As->Image sequence.
Also, note that once you've processed the movie (i.e. performed cell segmentations) you can measure on a whole different set of images (typically original TIFFs), as long as the ROIs (cell selections) hit the same spot.
These folders should not be moved afterwards (in this version) - the program will expect images to be at the same place when you (later) load the experiment.
Should you move them, you'll have to edit the experiment properties and set the new file locations.
In other words, images WILL NOT be saved to database, only the calculated/defined ROIs, measurements etc.

Once the folders are prepared (note that these can be stored anywhere (local hardrive, external server... but it is highly recommended to keep them in the default location under data/images folder). Start BactImAs.jar and select Experiment->New experiment.
You will be asked to choose folders for each channel (“Red”, “Green” and “Blue”. (the location you define in this step will be saved but can be changed later if you decide to move the folders). Then you must give an unique name to your experiment. Next to this name, BactImAs automatically assigns exp. id (e.g. id 1076) that can be later used in SQL queries. BactImAs will then load images in a few sec and you are ready to start the time-lapse movie processing.

Optional: This is a good time to also define here some important experimental settings such as pixel size. However, you can also do it at any other time.

==== 2.2. Load experiment ====
Use Experiment->Load ( Alt+2) to load an experiment.
Pick an existing experiment and wait for the experiment to load.
If you don't see the images on the R/G/B channels, that probably means that you haven't set up the folders right (see above), or you received a database from someone else and need to point the R/G/B folders to new locations.
Either way:
==== 2.3. Edit experiment (settings) ====
Once you've loaded the experiment you can change it's settings via Experiment->Edit current experiment (Alt+4).
You'll get a dialog like this one:

[[File:Editexperiment.png|400px]]

The most common use case for changing the experiment settings is when someone sends you his or hers database and adjoining image files.
Since they've probably stored the in the different folder (than you), you'll have to change this folder paths in order for the images to load.

==== 2.4. Delete experiment ====
To delete the experiment chose Experiment->delete (Alt+3).
This will not delete the image files on your disk, just the records in the database pertaining to that experiment.

===== 3. Segmentation =====

Once you've set up your experiment, given it a name, and set the images folders, you may proceed to actual cell segmentation.

==== 3.1. Detecting translations (registering) ====

It is common for have slight translations from one frame to another (eg due to sligt camera movements).
It is very important to align or "register" such images, since the default built-in "Copy-and-Adjust" algorithm is very sensitive to such defects.
You can use an external program to align/register images beforehand, all the better (e.g. http://bigwww.epfl.ch/thevenaz/stackreg/).
However, there is also a built-in algorithm for detection of translations, and if you haven't aligned the images externally, this is the first thing you must do in the segmentation process.
The built-in algorithm is suitable only for translations, so if you have rotations or some other kind of transformations, you'll have to adjust such images externally.
=== Built-in algorith ===
Select the first frame and then click "Detect trans" button below the cell tree on the right.
The program will ask you for a range (default = 20), this number specifies the number of pixels the program will 'slide' one image over the other (in every direction) in an attempt to align them.
Start with default = 20 (bigger number = slower), you can later detect translation for just one problematic frame if you need to (with the higher value than 20).
Translations will be saved to database and you will not have to do this again.

==== 3.2. Define initial cells =====
The built-in C&A algorithm tracks cells with regars to their position on the previous frame.
This implies that you have to define the initial cells on the first frame, and start tracking from the second frame.
To achieve that:
* Open the first frame, and define bacteria. You click on the frame tree (right) and issue "Add" command to generate bacteria,
and then you click on the bacterium and "Add" human ROIs (Regions Of Interest, i.e. selections)
Then you repeat the following (for each bacterium):
* define ROI with ImageJ's polygon selection tool
* click on the appropriate Human ROI node in the frame tree and issue 'Set Roi' command.

==== 3.3. Segmentation and Tracking Algorithm ====

Before describing the tracking via built-in algorithm, a quick note on the BactTrack modular structure.
BactImAs is designed to be a "platform for the cell segmentation and tracking" and should, ideally, be able to handle any such task.
We recognize that there is no single algorithm suitable for all kinds of tracking tasks and have therefore enabled for various algorithms to be included in the BactImAs Platform and used for cell segmentation.
While algorithm design is more a task for the developers (please, see Devs documentation), the user, on the other hand, has the option to use any of the available algorithms.
Not only can different algorithms be used for different experiments, the user can assign different algorithms for different frames of the same experiment!
Using the "Set Algorithm" command, a chosen algorithm can be assigned for any frame range.
If not assigned, the default built-in "Copy And Adjust" algorithm is used.
There is a "Fast Copy And Adjust" version of the algorithm available (not default) which differs from the default algorithm in the amount of information written to the log.
The "Fast Copy And Adjust" writes minimal information and is therefore faster, however cell segmentation results are identical.

==== 3.4. Segmentation and Tracking ====

Click on the frame (e.g. second frame) and issue 'Track' command. Enter the number of frames to process (default = 5).
Track will attempt to segment the cells on the assigned number of frames starting from the selected frame.
Each cell/frame is segmented using that cell's ROI from the previous frame.
Human ROIs always have precedence over computer ROIs, e.g. if there are both human and computer ROIs on the previous frame, the algorithm will use human ROI.

When you issue the "Track" command you'll have the option of changing certain algorithm parameters.
This is useful in situations when algorithm does not perform well.

[[File:Ca_params.png|}}px]]
Parameters description:
* "Ball radius" is a value in pixel that defines the size(radius) of the disk used to "draw" the cell. You may think of it as a radius of the tip of the broad ballpen used to draw the cell. In other words, this radius relates to the width of a cell - and you can measure that width W with ImageJ (or simply by zooming and counting the pixels yourself) and then assign the ball radius to just below the W/2. The default value is 4 which is appropriate for the cells of width 9, 10, 11...
* "Channel" is simply the channel used for segmentation, or more precisely - images from the so labelled channels (folders) are used. Note that you can use e.g. blue channel for the first 10 frames, then green channel for the next five, then blue again, etc. In general, you want to use the channel on which the edge detection works best, you can try that for yourself using ImageJ or "Help decide" button below.
* "Range" is a value in pixels relating to the possible elongation of the cells on their poles. If the algorithm doesn't catch up will cell growth on the poles, you may want to increase this number.
* "Max ball delta perc" is given in percentages and defines the maximal additional area one disk can contribute when expanding the selection. If you find that the cells are erroneously growing to fast, "bubbling up" on the sides and poles, you may want to decrease this number.
* "Threshold method" - the C&A algorithm relies heavily on the edge detection (and subsequent thresholding). If the algorithm performs badly, you may want to try changing the default method, you should choose the method that best outlines the cells (click 'Help decide' to see the gallery of methods).

Once you've set the parameters, the program will attempt to track the cells. You'll be able to see the segmentation as it happens and/or inspect it again using the "Reports" facilities:

==== 3.5. Reports ====
There are two types of reports (and command buttons):
* "Color report" is a report (ImageJ stack) on which every cell is drawn in a different color, while background is drawn in black. Cell's offsprings will be drawn in the nuance of the parent-cell color, e.g. all descendant of the red cell will be drawn in nuances of red. Example: [[File:Segmentation.png|200px]]

* "Report" is a report (ImageJ stack) on which cells ROIs are outlined over original images. There is also a color/BW version of this report (you're asked to chose on click). BW report uses less memory as each of the stack's image is BW and, of course, BW use less memory than color images.
* BW - human ROIs are outlined with white, and computer ROIs with black
* Color - human ROIs are outlined with green and computer ROIs with red, e.g.: [[File:Report_with_color_option.png|200px]]

==== 3.6. Cell divisions ====

For the time being cell division recognition is not supported and cell divisions are assigned manually in the following way:
- Open the frame where bacteriium (e.g. bacterium 'B') is splitting
- Click on the bacterium 'B' on the frame tree and issue "Split" command.
- Program will replace this bacterium in the current frame with its two offsprings: 'BA' and 'BB'. They will both have the human ROIs defined (erroneously), you have to overwrite it:
* Define ROIs with ImageJ's polygon selection tool for each offspring (and click "SetRoi" to save).

Split move/delete - If you made an error and defined split on the wrong frame, you can move the split up/down N frames, or even delete it all together.
To move the split you have to select one of the children in the split frame, and click on the "Move/del split".
E.g. let's say there is a split on the frame 10: A = AA + AB. QQ
Click on either AA or AB and then click 'Move/del split'.
The procedure is also thoroughly explained (in the program) when you click the "Move/del split" (and you have a chance to cancel if you change you mind).

===== 4. Measuring =====

Once cells are segmented, various measurements are acquired in a fully automated way.
BactImAs separates these two processes which has a nice side-effect that, for instance, cell segmentation and tracking can be outsourced or performed by a different person than a person taking measurements.
Using BactImAs's (color) reports (described above), it is easy to visually inspect the quality of the segmentation process.

==== 4.1. Background correction ====

Command "Set/msr bg (R+G+B)" is used to measure (store in the database) the background intensities of the red, green and blue channel images. These are used to compute the background corrected values afterwards.
After you click on this command an ImageJ stack will appear with all the frames of the experiment:
[[File:Measure_bg.png|200px]]
Using this stack, user has to assign the (rectangular) background area (subarea of the whole image), typically the are of the image that never holds any of the cells.
As with other measures, one can chose whether to measure on the original tif images (recommmended) or the png images used for tracking and segmentation.
Status window displays the progress and acquired measures.

==== 4.2. Cell measurements ====
Cells are measured using the "Measure" command. User can chose to take any or all available ImageJ measures on the assigned channel (r,g,b).
If you want to measure the same attribute on the different channels (e.g. mean on red and green channel) you have to measure twice: first on green and then on red channel (or vice versa).
When saving measurements in the database BactImAs behaves in the following way:
(a) if the same measurement on the same channel already exists - it is overwritten
(b) otherwise, measurement is saved (added to the already existing measurements)
So, in our example, green mean will be saved according to the (b) principle, and red mean also.
Should you measure the green mean again, the initial green mean would be overwritten in accordance with (a).

Upon clicking on the "Measure", a user is presented with following dialog:
[[File:Measure.png|200px]]

In the example above, the following will be measured:
* Area on the red channel (though channel is irrelevant for area measure)
* Mean on the green channel
* IntDen on the red channel with **collar** of one pixel. **Collar** is the width of the outer rim belt you want to ignore (e.g. if you want to exclude the cell's membranes)

Typically, you want to measure area and mean on all channels.

Status window displays the progress and acquired measures.
You can repeat the measuring process arbitrary number of times, or measure (repeat for) just a assigned number of frames, etc.

BactImAs provides a number of additional, derived measures, defined as follows:
(note that you must first measure area, mean on all channels and background fluorescences on all channels for these measures to be available):

^Name ^Description ^Is numerical (= can be mapped to the lin. tree) ^
|generation |Stage of descent from a common ancestor | |
|parent |Ancestor cell of a specific bacteria | |
|sibling |Sibling cell of a specific bacteria | |
|progeny_a |Specific progeny of a bacteria | |
|progeny_b |Specific progeny of the bacteria | |
|birth_time |Frame proceeding the division event |yes|
|division_time |Frame previous to the division event |yes|
|interdivision_time |=Division_time-Birth_ time |yes|
|growth_rate |=(Area at division_time/Area at birth_time)/interdivision time |yes|
|growth_velocity |=(Area at division_time-Area at birth_time)/interdivision time |yes|
|area_square_microns |=Measured area* (pixel_width*pixel_height)/scale*scale |yes|
|area_square_microns_growth |=(area_square_microns(n)-area_square_microns(n+1))/time |yes|
|red_mean_bg_cor |=Red_mean-red_bg |yes|
|green_mean_bg_cor |=Green_mean-green_bg |yes|
|blue_mean_bg_cor |=Blue_mean-blue_bg |yes|
|red_ctcf |=red_mean_bg_cor*area_square_microns |yes|
|green_ctcf |=green_mean_bg_cor*area_square_microns |yes|
|blue_ctcf |=blue_mean_bg_cor*area_square_microns |yes|
|red_mean_bg_cor_change |=(red_mean_bg_cor (n)-red_mean_bg_cor (n+1))/time |yes|
|green_mean_bg_cor_change |=(green_mean_bg_cor(n)-green_mean_bg_cor(n+1))/time |yes|
|blue_mean_bg_cor_change |=(blue_mean_bg_cor (n)-blue_mean_bg_cor (n+1))/time) |yes|
|red_ctcf_change |=(red_ctcf(n)-red_ctcf(n+1))/time |yes|
|green_ctcf_change |=(green_ctcf(n)-green_ctcf(n+1)/time |yes|
|blue_ctcf_change |=(blue_ctcf(n)-blue_ctcg(n+1))/time |yes|

Also, note the **"area_square_microns"** measure above, that stands for cell area in square microns of course.
It is defined as: **Measured area * (pixel_width*pixel_height)/scale*scale** where:
* Measured area is measured using ImageJ's "area" measurement (as shown above)
* pixel_width, pixel_height and scale are per experiement values that can be defined via Experiment->Edit experiment

===== 5. Other (misc) commmands =====

==== 5.1. Deleting (truncating) ROIs ====
"Trunc (after)" is a rarely used option for deleting the ROIs for (after) a selected frame.
Warning: deleted ROIs cannot be recovered and you'll have to detect them again.

==== 5.2. Collapse/Expand all ====
These commands are used to collapse or expand all nodes in the Frame/cell tree.

==== 5.3. Edit event ====
Using "Edit event" one can assign an arbitrary event at a certain frame (for instance, if the experiment conditions have changed, you may want to write that in the database).
The following dialog is shown:
[[File:Event.png|200px]]

Abbreviation is used to display the event in the tree, and the full desc is displayed in the lineage tree visualization.

If you want to delete the event, just edit it, and leave everything blank and the event will be deleted.

==== 5.4. Change cell state ====
With "Change bact state" command you can assign certain state (e.g. "Ignore", "Death") to the cell from some frame onward.
[[File:Bstate.png|200px]]
New state is annotated in the tree and on the lineage tree visualization.

To delete the assigned state, just set the empty state.

==== 5.5. Toggle ignore frame ====
With this command you can ignore (or un-ignore) the selected frame.
This is typically done when the frame if of a low quality (e.g. out of focus, unusable), but you want to keep it to keep the accurate timeline.
Cells on the ignored frame are not measured nor does the frame appear in the CSV dump.
When detecting cells on the frame F, the previous frame is considered to be the frame having maximal frame number f < F, such that it is not ignored.

===== 6. Analyis and Visualization =====

==== 6.1. Lineage tree visualization ====

BactImAs features the innovative lineage tree visualization that can map two, user selected, parameters to the cell division tree.
When you're done with measurements, choose Reports->BTree from the main menu.
The following dialog appears:

[[File:Btree_dialog.png|400px]]

It is possible to assign any of the measured (and derived - built in) variables to the two visualization properties: branch width and color.
Dialog shows the area of the cell mapped to the branch width, and green_ctcf mapped to the branch color.
Other than that, it is possible to assigne the following parameters:
* seconds per frame - used for the time scale on the right, where t(frame_no) = (frame_no-1) * seconds_per_frame
* min/max stroke width - min/max parameters on the branch color are scaled to min/max stroke width
* font size
* draw labels - whether to draw the cell labels
* convert to hours - whether to convert time in seconds to format: HH:MM:SS

BactImAs will draw a separate visualization for every cell present on the firt (non-igored) frame.
The following image shows a sample visualization from the demo database:

[[File:Btree.png|600px]]

It is our intention to include in the new version of BactImAs additional out-of-the-box statistics and visualization.
However, acknowledging that it will never be possible to cover all potential requirements, we've enabled the following option:

==== 6.2. Export data as CSV file ====

With Reports->Dump CSV one can export the experiment's data into a CSV file and proceed to analyze it in one's favorite data analysis tool.

After you assign the file name, the following dialog appears:

[[File:Dumpcsv.png|400px]]

with all the available measurements for the experiment.

==== 6.3. SQL Pane ====

BactImAs stores all the data (except images) in the SqLite database.
Database can be accessed using any of the SqLite client tools - there are many such tools freely available on the Internet.
It is also possible to access it using the simple built-in SQL Pane editor, which allows for arbitrary SQL statements (queries) to be executed and displayed in a table, and even exported as CSV.
The following figure shows the SQL pane:

[[File:Sqlpane.png|200px]]

Of course, to use SQL pane one has to know the SQL programming language.
It is our intention, for the future releases of BactImAs, to build a library of predefined SQL queries, with adjoining descriptions in natural language, so that
a user that has no knowledge of SQL language can pick from the set the available predefined queries and retrieve results for his or hers experiment.

===== 7. Backup, upgrade and data exchange =====

==== 7.1. Backup ====

To backup the data one should simply copy the "data" directory to a safe place, every once in a while.

==== 7.2. Upgrade ====

When upgrading BactImAs, it is best to:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 7.3. Data exchange ====

(see also the BactImAs structure in the User->Installation)
To exchange data, it is necessary to exchange database and images folder (best zipped).

[[File:Exchange.png|400px]]

Should person A want to send experiment data to person B, these are the steps to follow:

* Person A sends the images folder (best zipped) to person B. Person B saves (extracts) them to person B's images folder. One could use cloud storage for this steps (eg Dropbox, GDrive) as images are too big for email.
* Person A sends the BactImAs.s3db file (database) from dbs folder to person B. Person B potentially renames it (to avoid clashing with person B's database), saves it to the dbs folder, and adjust the URL in the conf/db.properties to point to this new database (see User->Installation)

The second step can be repeated if there are new data measured in the database, while the first step needs to be done only once.

User manual

2023-07-18T10:55:10Z

Igor: /* 6.1. Lineage tree visualization */

====== BactImAs User Manual ======

===== 1. BactImAs GUI =====
Image below shows the BactImAs GUI.

GUI consists of three main parts:
* R/G/B channel images, scrollable image panes showing every second frame of the experiment
* Frame/cell tree on the right showing all frames and cells/ROIs
* Status window showing messages from the program (can be minified)

[[File:Bactrack_gui.png|600px]]

If you chose (click) on a frame(on the tree or on the R/G/B channel image) a new image stack will appear showing that frame's images in all combinations: R, G, B, R+G, R+B, B+G, RGB, with annotated ROIs (you can turn off annotations using Roi Manager):

[[File:Frame.png|300px]]

One can scroll to any of these and use it (typically) to assign ROIs using ImageJ polygon selection tool.

Every GUI command/option is described in detail below (also, note the table of contents on the upper right side).

===== 2. Experiment =====

//**Note: please read the installation instructions first, especially the "BactImAs structure" part.**//

==== 2.1. Setup new experiment ====

You must prepare, beforehand, three folders: red, green and blue (each containing image sequence of the appropriate channel).
Images must be 8-bit PNGs, and must be named unanimously (having the same name, and increasing number at the end), e.g.:
* phase_image_0000.png
* phase_image_0001.png
* phase_image_0002.png
* ...

Don't worry, ImageJ will do this for you (by deafault), if you say File->Save As->Image sequence.
Also, note that once you've processed the movie (i.e. performed cell segmentations) you can measure on a whole different set of images (typically original TIFFs), as long as the ROIs (cell selections) hit the same spot.
These folders should not be moved afterwards (in this version) - the program will expect images to be at the same place when you (later) load the experiment.
Should you move them, you'll have to edit the experiment properties and set the new file locations.
In other words, images WILL NOT be saved to database, only the calculated/defined ROIs, measurements etc.

Once the folders are prepared (note that these can be stored anywhere (local hardrive, external server... but it is highly recommended to keep them in the default location under data/images folder). Start BactImAs.jar and select Experiment->New experiment.
You will be asked to choose folders for each channel (“Red”, “Green” and “Blue”. (the location you define in this step will be saved but can be changed later if you decide to move the folders). Then you must give an unique name to your experiment. Next to this name, BactImAs automatically assigns exp. id (e.g. id 1076) that can be later used in SQL queries. BactImAs will then load images in a few sec and you are ready to start the time-lapse movie processing.

Optional: This is a good time to also define here some important experimental settings such as pixel size. However, you can also do it at any other time.

==== 2.2. Load experiment ====
Use Experiment->Load ( Alt+2) to load an experiment.
Pick an existing experiment and wait for the experiment to load.
If you don't see the images on the R/G/B channels, that probably means that you haven't set up the folders right (see above), or you received a database from someone else and need to point the R/G/B folders to new locations.
Either way:
==== 2.3. Edit experiment (settings) ====
Once you've loaded the experiment you can change it's settings via Experiment->Edit current experiment (Alt+4).
You'll get a dialog like this one:

[[File:Editexperiment.png|400px]]

The most common use case for changing the experiment settings is when someone sends you his or hers database and adjoining image files.
Since they've probably stored the in the different folder (than you), you'll have to change this folder paths in order for the images to load.

==== 2.4. Delete experiment ====
To delete the experiment chose Experiment->delete (Alt+3).
This will not delete the image files on your disk, just the records in the database pertaining to that experiment.

===== 3. Segmentation =====

Once you've set up your experiment, given it a name, and set the images folders, you may proceed to actual cell segmentation.

==== 3.1. Detecting translations (registering) ====

It is common for have slight translations from one frame to another (eg due to sligt camera movements).
It is very important to align or "register" such images, since the default built-in "Copy-and-Adjust" algorithm is very sensitive to such defects.
You can use an external program to align/register images beforehand, all the better (e.g. http://bigwww.epfl.ch/thevenaz/stackreg/).
However, there is also a built-in algorithm for detection of translations, and if you haven't aligned the images externally, this is the first thing you must do in the segmentation process.
The built-in algorithm is suitable only for translations, so if you have rotations or some other kind of transformations, you'll have to adjust such images externally.
=== Built-in algorith ===
Select the first frame and then click "Detect trans" button below the cell tree on the right.
The program will ask you for a range (default = 20), this number specifies the number of pixels the program will 'slide' one image over the other (in every direction) in an attempt to align them.
Start with default = 20 (bigger number = slower), you can later detect translation for just one problematic frame if you need to (with the higher value than 20).
Translations will be saved to database and you will not have to do this again.

==== 3.2. Define initial cells =====
The built-in C&A algorithm tracks cells with regars to their position on the previous frame.
This implies that you have to define the initial cells on the first frame, and start tracking from the second frame.
To achieve that:
* Open the first frame, and define bacteria. You click on the frame tree (right) and issue "Add" command to generate bacteria,
and then you click on the bacterium and "Add" human ROIs (Regions Of Interest, i.e. selections)
Then you repeat the following (for each bacterium):
* define ROI with ImageJ's polygon selection tool
* click on the appropriate Human ROI node in the frame tree and issue 'Set Roi' command.

==== 3.3. Segmentation and Tracking Algorithm ====

Before describing the tracking via built-in algorithm, a quick note on the BactTrack modular structure.
BactImAs is designed to be a "platform for the cell segmentation and tracking" and should, ideally, be able to handle any such task.
We recognize that there is no single algorithm suitable for all kinds of tracking tasks and have therefore enabled for various algorithms to be included in the BactImAs Platform and used for cell segmentation.
While algorithm design is more a task for the developers (please, see Devs documentation), the user, on the other hand, has the option to use any of the available algorithms.
Not only can different algorithms be used for different experiments, the user can assign different algorithms for different frames of the same experiment!
Using the "Set Algorithm" command, a chosen algorithm can be assigned for any frame range.
If not assigned, the default built-in "Copy And Adjust" algorithm is used.
There is a "Fast Copy And Adjust" version of the algorithm available (not default) which differs from the default algorithm in the amount of information written to the log.
The "Fast Copy And Adjust" writes minimal information and is therefore faster, however cell segmentation results are identical.

==== 3.4. Segmentation and Tracking ====

Click on the frame (e.g. second frame) and issue 'Track' command. Enter the number of frames to process (default = 5).
Track will attempt to segment the cells on the assigned number of frames starting from the selected frame.
Each cell/frame is segmented using that cell's ROI from the previous frame.
Human ROIs always have precedence over computer ROIs, e.g. if there are both human and computer ROIs on the previous frame, the algorithm will use human ROI.

When you issue the "Track" command you'll have the option of changing certain algorithm parameters.
This is useful in situations when algorithm does not perform well.

[[File:Ca_params.png|}}px]]
Parameters description:
* "Ball radius" is a value in pixel that defines the size(radius) of the disk used to "draw" the cell. You may think of it as a radius of the tip of the broad ballpen used to draw the cell. In other words, this radius relates to the width of a cell - and you can measure that width W with ImageJ (or simply by zooming and counting the pixels yourself) and then assign the ball radius to just below the W/2. The default value is 4 which is appropriate for the cells of width 9, 10, 11...
* "Channel" is simply the channel used for segmentation, or more precisely - images from the so labelled channels (folders) are used. Note that you can use e.g. blue channel for the first 10 frames, then green channel for the next five, then blue again, etc. In general, you want to use the channel on which the edge detection works best, you can try that for yourself using ImageJ or "Help decide" button below.
* "Range" is a value in pixels relating to the possible elongation of the cells on their poles. If the algorithm doesn't catch up will cell growth on the poles, you may want to increase this number.
* "Max ball delta perc" is given in percentages and defines the maximal additional area one disk can contribute when expanding the selection. If you find that the cells are erroneously growing to fast, "bubbling up" on the sides and poles, you may want to decrease this number.
* "Threshold method" - the C&A algorithm relies heavily on the edge detection (and subsequent thresholding). If the algorithm performs badly, you may want to try changing the default method, you should choose the method that best outlines the cells (click 'Help decide' to see the gallery of methods).

Once you've set the parameters, the program will attempt to track the cells. You'll be able to see the segmentation as it happens and/or inspect it again using the "Reports" facilities:

==== 3.5. Reports ====
There are two types of reports (and command buttons):
* "Color report" is a report (ImageJ stack) on which every cell is drawn in a different color, while background is drawn in black. Cell's offsprings will be drawn in the nuance of the parent-cell color, e.g. all descendant of the red cell will be drawn in nuances of red. Example: [[File:Segmentation.png|200px]]

* "Report" is a report (ImageJ stack) on which cells ROIs are outlined over original images. There is also a color/BW version of this report (you're asked to chose on click). BW report uses less memory as each of the stack's image is BW and, of course, BW use less memory than color images.
* BW - human ROIs are outlined with white, and computer ROIs with black
* Color - human ROIs are outlined with green and computer ROIs with red, e.g.: [[File:Report_with_color_option.png|200px]]

==== 3.6. Cell divisions ====

For the time being cell division recognition is not supported and cell divisions are assigned manually in the following way:
- Open the frame where bacteriium (e.g. bacterium 'B') is splitting
- Click on the bacterium 'B' on the frame tree and issue "Split" command.
- Program will replace this bacterium in the current frame with its two offsprings: 'BA' and 'BB'. They will both have the human ROIs defined (erroneously), you have to overwrite it:
* Define ROIs with ImageJ's polygon selection tool for each offspring (and click "SetRoi" to save).

Split move/delete - If you made an error and defined split on the wrong frame, you can move the split up/down N frames, or even delete it all together.
To move the split you have to select one of the children in the split frame, and click on the "Move/del split".
E.g. let's say there is a split on the frame 10: A = AA + AB. QQ
Click on either AA or AB and then click 'Move/del split'.
The procedure is also thoroughly explained (in the program) when you click the "Move/del split" (and you have a chance to cancel if you change you mind).

===== 4. Measuring =====

Once cells are segmented, various measurements are acquired in a fully automated way.
BactImAs separates these two processes which has a nice side-effect that, for instance, cell segmentation and tracking can be outsourced or performed by a different person than a person taking measurements.
Using BactImAs's (color) reports (described above), it is easy to visually inspect the quality of the segmentation process.

==== 4.1. Background correction ====

Command "Set/msr bg (R+G+B)" is used to measure (store in the database) the background intensities of the red, green and blue channel images. These are used to compute the background corrected values afterwards.
After you click on this command an ImageJ stack will appear with all the frames of the experiment:
[[File:Measure_bg.png|200px]]
Using this stack, user has to assign the (rectangular) background area (subarea of the whole image), typically the are of the image that never holds any of the cells.
As with other measures, one can chose whether to measure on the original tif images (recommmended) or the png images used for tracking and segmentation.
Status window displays the progress and acquired measures.

==== 4.2. Cell measurements ====
Cells are measured using the "Measure" command. User can chose to take any or all available ImageJ measures on the assigned channel (r,g,b).
If you want to measure the same attribute on the different channels (e.g. mean on red and green channel) you have to measure twice: first on green and then on red channel (or vice versa).
When saving measurements in the database BactImAs behaves in the following way:
(a) if the same measurement on the same channel already exists - it is overwritten
(b) otherwise, measurement is saved (added to the already existing measurements)
So, in our example, green mean will be saved according to the (b) principle, and red mean also.
Should you measure the green mean again, the initial green mean would be overwritten in accordance with (a).

Upon clicking on the "Measure", a user is presented with following dialog:
[[File:Measure.png|200px]]

In the example above, the following will be measured:
* Area on the red channel (though channel is irrelevant for area measure)
* Mean on the green channel
* IntDen on the red channel with **collar** of one pixel. **Collar** is the width of the outer rim belt you want to ignore (e.g. if you want to exclude the cell's membranes)

Typically, you want to measure area and mean on all channels.

Status window displays the progress and acquired measures.
You can repeat the measuring process arbitrary number of times, or measure (repeat for) just a assigned number of frames, etc.

BactImAs provides a number of additional, derived measures, defined as follows:
(note that you must first measure area, mean on all channels and background fluorescences on all channels for these measures to be available):

^Name ^Description ^Is numerical (= can be mapped to the lin. tree) ^
|generation |Stage of descent from a common ancestor | |
|parent |Ancestor cell of a specific bacteria | |
|sibling |Sibling cell of a specific bacteria | |
|progeny_a |Specific progeny of a bacteria | |
|progeny_b |Specific progeny of the bacteria | |
|birth_time |Frame proceeding the division event |yes|
|division_time |Frame previous to the division event |yes|
|interdivision_time |=Division_time-Birth_ time |yes|
|growth_rate |=(Area at division_time/Area at birth_time)/interdivision time |yes|
|growth_velocity |=(Area at division_time-Area at birth_time)/interdivision time |yes|
|area_square_microns |=Measured area* (pixel_width*pixel_height)/scale*scale |yes|
|area_square_microns_growth |=(area_square_microns(n)-area_square_microns(n+1))/time |yes|
|red_mean_bg_cor |=Red_mean-red_bg |yes|
|green_mean_bg_cor |=Green_mean-green_bg |yes|
|blue_mean_bg_cor |=Blue_mean-blue_bg |yes|
|red_ctcf |=red_mean_bg_cor*area_square_microns |yes|
|green_ctcf |=green_mean_bg_cor*area_square_microns |yes|
|blue_ctcf |=blue_mean_bg_cor*area_square_microns |yes|
|red_mean_bg_cor_change |=(red_mean_bg_cor (n)-red_mean_bg_cor (n+1))/time |yes|
|green_mean_bg_cor_change |=(green_mean_bg_cor(n)-green_mean_bg_cor(n+1))/time |yes|
|blue_mean_bg_cor_change |=(blue_mean_bg_cor (n)-blue_mean_bg_cor (n+1))/time) |yes|
|red_ctcf_change |=(red_ctcf(n)-red_ctcf(n+1))/time |yes|
|green_ctcf_change |=(green_ctcf(n)-green_ctcf(n+1)/time |yes|
|blue_ctcf_change |=(blue_ctcf(n)-blue_ctcg(n+1))/time |yes|

Also, note the **"area_square_microns"** measure above, that stands for cell area in square microns of course.
It is defined as: **Measured area * (pixel_width*pixel_height)/scale*scale** where:
* Measured area is measured using ImageJ's "area" measurement (as shown above)
* pixel_width, pixel_height and scale are per experiement values that can be defined via Experiment->Edit experiment

===== 5. Other (misc) commmands =====

==== 5.1. Deleting (truncating) ROIs ====
"Trunc (after)" is a rarely used option for deleting the ROIs for (after) a selected frame.
Warning: deleted ROIs cannot be recovered and you'll have to detect them again.

==== 5.2. Collapse/Expand all ====
These commands are used to collapse or expand all nodes in the Frame/cell tree.

==== 5.3. Edit event ====
Using "Edit event" one can assign an arbitrary event at a certain frame (for instance, if the experiment conditions have changed, you may want to write that in the database).
The following dialog is shown:
[[File:Event.png|200px]]

Abbreviation is used to display the event in the tree, and the full desc is displayed in the lineage tree visualization.

If you want to delete the event, just edit it, and leave everything blank and the event will be deleted.

==== 5.4. Change cell state ====
With "Change bact state" command you can assign certain state (e.g. "Ignore", "Death") to the cell from some frame onward.
[[File:Bstate.png|200px]]
New state is annotated in the tree and on the lineage tree visualization.

To delete the assigned state, just set the empty state.

==== 5.5. Toggle ignore frame ====
With this command you can ignore (or un-ignore) the selected frame.
This is typically done when the frame if of a low quality (e.g. out of focus, unusable), but you want to keep it to keep the accurate timeline.
Cells on the ignored frame are not measured nor does the frame appear in the CSV dump.
When detecting cells on the frame F, the previous frame is considered to be the frame having maximal frame number f < F, such that it is not ignored.

===== 6. Analyis and Visualization =====

==== 6.1. Lineage tree visualization ====

BactImAs features the innovative lineage tree visualization that can map two, user selected, parameters to the cell division tree.
When you're done with measurements, choose Reports->BTree from the main menu.
The following dialog appears:

[[File:Btree_dialog.png|400px]]

It is possible to assign any of the measured (and derived - built in) variables to the two visualization properties: branch width and color.
Dialog shows the area of the cell mapped to the branch width, and green_ctcf mapped to the branch color.
Other than that, it is possible to assigne the following parameters:
* seconds per frame - used for the time scale on the right, where t(frame_no) = (frame_no-1) * seconds_per_frame
* min/max stroke width - min/max parameters on the branch color are scaled to min/max stroke width
* font size
* draw labels - whether to draw the cell labels
* convert to hours - whether to convert time in seconds to format: HH:MM:SS

BactImAs will draw a separate visualization for every cell present on the firt (non-igored) frame.
The following image shows a sample visualization from the demo database:

[[File:Btree.png|600px]]

It is our intention to include in the new version of BactImAs additional out-of-the-box statistics and visualization.
However, acknowledging that it will never be possible to cover all potential requirements, we've enabled the following option:

==== 6.2. Export data as CSV file ====

With Reports->Dump CSV one can export the experiment's data into a CSV file and proceed to analyze it in one's favorite data analysis tool.

After you assign the file name, the following dialog appears:

[[File:Dumpcsv.png|200px]]

with all the available measurements for the experiment.

==== 6.3. SQL Pane ====

BactImAs stores all the data (except images) in the SqLite database.
Database can be accessed using any of the SqLite client tools - there are many such tools freely available on the Internet.
It is also possible to access it using the simple built-in SQL Pane editor, which allows for arbitrary SQL statements (queries) to be executed and displayed in a table, and even exported as CSV.
The following figure shows the SQL pane:

[[File:Sqlpane.png|200px]]

Of course, to use SQL pane one has to know the SQL programming language.
It is our intention, for the future releases of BactImAs, to build a library of predefined SQL queries, with adjoining descriptions in natural language, so that
a user that has no knowledge of SQL language can pick from the set the available predefined queries and retrieve results for his or hers experiment.

===== 7. Backup, upgrade and data exchange =====

==== 7.1. Backup ====

To backup the data one should simply copy the "data" directory to a safe place, every once in a while.

==== 7.2. Upgrade ====

When upgrading BactImAs, it is best to:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 7.3. Data exchange ====

(see also the BactImAs structure in the User->Installation)
To exchange data, it is necessary to exchange database and images folder (best zipped).

[[File:Exchange.png|400px]]

Should person A want to send experiment data to person B, these are the steps to follow:

* Person A sends the images folder (best zipped) to person B. Person B saves (extracts) them to person B's images folder. One could use cloud storage for this steps (eg Dropbox, GDrive) as images are too big for email.
* Person A sends the BactImAs.s3db file (database) from dbs folder to person B. Person B potentially renames it (to avoid clashing with person B's database), saves it to the dbs folder, and adjust the URL in the conf/db.properties to point to this new database (see User->Installation)

The second step can be repeated if there are new data measured in the database, while the first step needs to be done only once.

User manual

2023-07-18T10:54:08Z

Igor: Created page with "====== BactImAs User Manual ====== ===== 1. BactImAs GUI ===== Image below shows the BactImAs GUI. GUI consists of three main parts: * R/G/B channel images, scrollable image panes showing every second frame of the experiment * Frame/cell tree on the right showing all frames and cells/ROIs * Status window showing messages from..."

====== BactImAs User Manual ======

===== 1. BactImAs GUI =====
Image below shows the BactImAs GUI.

GUI consists of three main parts:
* R/G/B channel images, scrollable image panes showing every second frame of the experiment
* Frame/cell tree on the right showing all frames and cells/ROIs
* Status window showing messages from the program (can be minified)

[[File:Bactrack_gui.png|600px]]

If you chose (click) on a frame(on the tree or on the R/G/B channel image) a new image stack will appear showing that frame's images in all combinations: R, G, B, R+G, R+B, B+G, RGB, with annotated ROIs (you can turn off annotations using Roi Manager):

[[File:Frame.png|300px]]

One can scroll to any of these and use it (typically) to assign ROIs using ImageJ polygon selection tool.

Every GUI command/option is described in detail below (also, note the table of contents on the upper right side).

===== 2. Experiment =====

//**Note: please read the installation instructions first, especially the "BactImAs structure" part.**//

==== 2.1. Setup new experiment ====

You must prepare, beforehand, three folders: red, green and blue (each containing image sequence of the appropriate channel).
Images must be 8-bit PNGs, and must be named unanimously (having the same name, and increasing number at the end), e.g.:
* phase_image_0000.png
* phase_image_0001.png
* phase_image_0002.png
* ...

Don't worry, ImageJ will do this for you (by deafault), if you say File->Save As->Image sequence.
Also, note that once you've processed the movie (i.e. performed cell segmentations) you can measure on a whole different set of images (typically original TIFFs), as long as the ROIs (cell selections) hit the same spot.
These folders should not be moved afterwards (in this version) - the program will expect images to be at the same place when you (later) load the experiment.
Should you move them, you'll have to edit the experiment properties and set the new file locations.
In other words, images WILL NOT be saved to database, only the calculated/defined ROIs, measurements etc.

Once the folders are prepared (note that these can be stored anywhere (local hardrive, external server... but it is highly recommended to keep them in the default location under data/images folder). Start BactImAs.jar and select Experiment->New experiment.
You will be asked to choose folders for each channel (“Red”, “Green” and “Blue”. (the location you define in this step will be saved but can be changed later if you decide to move the folders). Then you must give an unique name to your experiment. Next to this name, BactImAs automatically assigns exp. id (e.g. id 1076) that can be later used in SQL queries. BactImAs will then load images in a few sec and you are ready to start the time-lapse movie processing.

Optional: This is a good time to also define here some important experimental settings such as pixel size. However, you can also do it at any other time.

==== 2.2. Load experiment ====
Use Experiment->Load ( Alt+2) to load an experiment.
Pick an existing experiment and wait for the experiment to load.
If you don't see the images on the R/G/B channels, that probably means that you haven't set up the folders right (see above), or you received a database from someone else and need to point the R/G/B folders to new locations.
Either way:
==== 2.3. Edit experiment (settings) ====
Once you've loaded the experiment you can change it's settings via Experiment->Edit current experiment (Alt+4).
You'll get a dialog like this one:

[[File:Editexperiment.png|400px]]

The most common use case for changing the experiment settings is when someone sends you his or hers database and adjoining image files.
Since they've probably stored the in the different folder (than you), you'll have to change this folder paths in order for the images to load.

==== 2.4. Delete experiment ====
To delete the experiment chose Experiment->delete (Alt+3).
This will not delete the image files on your disk, just the records in the database pertaining to that experiment.

===== 3. Segmentation =====

Once you've set up your experiment, given it a name, and set the images folders, you may proceed to actual cell segmentation.

==== 3.1. Detecting translations (registering) ====

It is common for have slight translations from one frame to another (eg due to sligt camera movements).
It is very important to align or "register" such images, since the default built-in "Copy-and-Adjust" algorithm is very sensitive to such defects.
You can use an external program to align/register images beforehand, all the better (e.g. http://bigwww.epfl.ch/thevenaz/stackreg/).
However, there is also a built-in algorithm for detection of translations, and if you haven't aligned the images externally, this is the first thing you must do in the segmentation process.
The built-in algorithm is suitable only for translations, so if you have rotations or some other kind of transformations, you'll have to adjust such images externally.
=== Built-in algorith ===
Select the first frame and then click "Detect trans" button below the cell tree on the right.
The program will ask you for a range (default = 20), this number specifies the number of pixels the program will 'slide' one image over the other (in every direction) in an attempt to align them.
Start with default = 20 (bigger number = slower), you can later detect translation for just one problematic frame if you need to (with the higher value than 20).
Translations will be saved to database and you will not have to do this again.

==== 3.2. Define initial cells =====
The built-in C&A algorithm tracks cells with regars to their position on the previous frame.
This implies that you have to define the initial cells on the first frame, and start tracking from the second frame.
To achieve that:
* Open the first frame, and define bacteria. You click on the frame tree (right) and issue "Add" command to generate bacteria,
and then you click on the bacterium and "Add" human ROIs (Regions Of Interest, i.e. selections)
Then you repeat the following (for each bacterium):
* define ROI with ImageJ's polygon selection tool
* click on the appropriate Human ROI node in the frame tree and issue 'Set Roi' command.

==== 3.3. Segmentation and Tracking Algorithm ====

Before describing the tracking via built-in algorithm, a quick note on the BactTrack modular structure.
BactImAs is designed to be a "platform for the cell segmentation and tracking" and should, ideally, be able to handle any such task.
We recognize that there is no single algorithm suitable for all kinds of tracking tasks and have therefore enabled for various algorithms to be included in the BactImAs Platform and used for cell segmentation.
While algorithm design is more a task for the developers (please, see Devs documentation), the user, on the other hand, has the option to use any of the available algorithms.
Not only can different algorithms be used for different experiments, the user can assign different algorithms for different frames of the same experiment!
Using the "Set Algorithm" command, a chosen algorithm can be assigned for any frame range.
If not assigned, the default built-in "Copy And Adjust" algorithm is used.
There is a "Fast Copy And Adjust" version of the algorithm available (not default) which differs from the default algorithm in the amount of information written to the log.
The "Fast Copy And Adjust" writes minimal information and is therefore faster, however cell segmentation results are identical.

==== 3.4. Segmentation and Tracking ====

Click on the frame (e.g. second frame) and issue 'Track' command. Enter the number of frames to process (default = 5).
Track will attempt to segment the cells on the assigned number of frames starting from the selected frame.
Each cell/frame is segmented using that cell's ROI from the previous frame.
Human ROIs always have precedence over computer ROIs, e.g. if there are both human and computer ROIs on the previous frame, the algorithm will use human ROI.

When you issue the "Track" command you'll have the option of changing certain algorithm parameters.
This is useful in situations when algorithm does not perform well.

[[File:Ca_params.png|}}px]]
Parameters description:
* "Ball radius" is a value in pixel that defines the size(radius) of the disk used to "draw" the cell. You may think of it as a radius of the tip of the broad ballpen used to draw the cell. In other words, this radius relates to the width of a cell - and you can measure that width W with ImageJ (or simply by zooming and counting the pixels yourself) and then assign the ball radius to just below the W/2. The default value is 4 which is appropriate for the cells of width 9, 10, 11...
* "Channel" is simply the channel used for segmentation, or more precisely - images from the so labelled channels (folders) are used. Note that you can use e.g. blue channel for the first 10 frames, then green channel for the next five, then blue again, etc. In general, you want to use the channel on which the edge detection works best, you can try that for yourself using ImageJ or "Help decide" button below.
* "Range" is a value in pixels relating to the possible elongation of the cells on their poles. If the algorithm doesn't catch up will cell growth on the poles, you may want to increase this number.
* "Max ball delta perc" is given in percentages and defines the maximal additional area one disk can contribute when expanding the selection. If you find that the cells are erroneously growing to fast, "bubbling up" on the sides and poles, you may want to decrease this number.
* "Threshold method" - the C&A algorithm relies heavily on the edge detection (and subsequent thresholding). If the algorithm performs badly, you may want to try changing the default method, you should choose the method that best outlines the cells (click 'Help decide' to see the gallery of methods).

Once you've set the parameters, the program will attempt to track the cells. You'll be able to see the segmentation as it happens and/or inspect it again using the "Reports" facilities:

==== 3.5. Reports ====
There are two types of reports (and command buttons):
* "Color report" is a report (ImageJ stack) on which every cell is drawn in a different color, while background is drawn in black. Cell's offsprings will be drawn in the nuance of the parent-cell color, e.g. all descendant of the red cell will be drawn in nuances of red. Example: [[File:Segmentation.png|200px]]

* "Report" is a report (ImageJ stack) on which cells ROIs are outlined over original images. There is also a color/BW version of this report (you're asked to chose on click). BW report uses less memory as each of the stack's image is BW and, of course, BW use less memory than color images.
* BW - human ROIs are outlined with white, and computer ROIs with black
* Color - human ROIs are outlined with green and computer ROIs with red, e.g.: [[File:Report_with_color_option.png|200px]]

==== 3.6. Cell divisions ====

For the time being cell division recognition is not supported and cell divisions are assigned manually in the following way:
- Open the frame where bacteriium (e.g. bacterium 'B') is splitting
- Click on the bacterium 'B' on the frame tree and issue "Split" command.
- Program will replace this bacterium in the current frame with its two offsprings: 'BA' and 'BB'. They will both have the human ROIs defined (erroneously), you have to overwrite it:
* Define ROIs with ImageJ's polygon selection tool for each offspring (and click "SetRoi" to save).

Split move/delete - If you made an error and defined split on the wrong frame, you can move the split up/down N frames, or even delete it all together.
To move the split you have to select one of the children in the split frame, and click on the "Move/del split".
E.g. let's say there is a split on the frame 10: A = AA + AB. QQ
Click on either AA or AB and then click 'Move/del split'.
The procedure is also thoroughly explained (in the program) when you click the "Move/del split" (and you have a chance to cancel if you change you mind).

===== 4. Measuring =====

Once cells are segmented, various measurements are acquired in a fully automated way.
BactImAs separates these two processes which has a nice side-effect that, for instance, cell segmentation and tracking can be outsourced or performed by a different person than a person taking measurements.
Using BactImAs's (color) reports (described above), it is easy to visually inspect the quality of the segmentation process.

==== 4.1. Background correction ====

Command "Set/msr bg (R+G+B)" is used to measure (store in the database) the background intensities of the red, green and blue channel images. These are used to compute the background corrected values afterwards.
After you click on this command an ImageJ stack will appear with all the frames of the experiment:
[[File:Measure_bg.png|200px]]
Using this stack, user has to assign the (rectangular) background area (subarea of the whole image), typically the are of the image that never holds any of the cells.
As with other measures, one can chose whether to measure on the original tif images (recommmended) or the png images used for tracking and segmentation.
Status window displays the progress and acquired measures.

==== 4.2. Cell measurements ====
Cells are measured using the "Measure" command. User can chose to take any or all available ImageJ measures on the assigned channel (r,g,b).
If you want to measure the same attribute on the different channels (e.g. mean on red and green channel) you have to measure twice: first on green and then on red channel (or vice versa).
When saving measurements in the database BactImAs behaves in the following way:
(a) if the same measurement on the same channel already exists - it is overwritten
(b) otherwise, measurement is saved (added to the already existing measurements)
So, in our example, green mean will be saved according to the (b) principle, and red mean also.
Should you measure the green mean again, the initial green mean would be overwritten in accordance with (a).

Upon clicking on the "Measure", a user is presented with following dialog:
[[File:Measure.png|200px]]

In the example above, the following will be measured:
* Area on the red channel (though channel is irrelevant for area measure)
* Mean on the green channel
* IntDen on the red channel with **collar** of one pixel. **Collar** is the width of the outer rim belt you want to ignore (e.g. if you want to exclude the cell's membranes)

Typically, you want to measure area and mean on all channels.

Status window displays the progress and acquired measures.
You can repeat the measuring process arbitrary number of times, or measure (repeat for) just a assigned number of frames, etc.

BactImAs provides a number of additional, derived measures, defined as follows:
(note that you must first measure area, mean on all channels and background fluorescences on all channels for these measures to be available):

^Name ^Description ^Is numerical (= can be mapped to the lin. tree) ^
|generation |Stage of descent from a common ancestor | |
|parent |Ancestor cell of a specific bacteria | |
|sibling |Sibling cell of a specific bacteria | |
|progeny_a |Specific progeny of a bacteria | |
|progeny_b |Specific progeny of the bacteria | |
|birth_time |Frame proceeding the division event |yes|
|division_time |Frame previous to the division event |yes|
|interdivision_time |=Division_time-Birth_ time |yes|
|growth_rate |=(Area at division_time/Area at birth_time)/interdivision time |yes|
|growth_velocity |=(Area at division_time-Area at birth_time)/interdivision time |yes|
|area_square_microns |=Measured area* (pixel_width*pixel_height)/scale*scale |yes|
|area_square_microns_growth |=(area_square_microns(n)-area_square_microns(n+1))/time |yes|
|red_mean_bg_cor |=Red_mean-red_bg |yes|
|green_mean_bg_cor |=Green_mean-green_bg |yes|
|blue_mean_bg_cor |=Blue_mean-blue_bg |yes|
|red_ctcf |=red_mean_bg_cor*area_square_microns |yes|
|green_ctcf |=green_mean_bg_cor*area_square_microns |yes|
|blue_ctcf |=blue_mean_bg_cor*area_square_microns |yes|
|red_mean_bg_cor_change |=(red_mean_bg_cor (n)-red_mean_bg_cor (n+1))/time |yes|
|green_mean_bg_cor_change |=(green_mean_bg_cor(n)-green_mean_bg_cor(n+1))/time |yes|
|blue_mean_bg_cor_change |=(blue_mean_bg_cor (n)-blue_mean_bg_cor (n+1))/time) |yes|
|red_ctcf_change |=(red_ctcf(n)-red_ctcf(n+1))/time |yes|
|green_ctcf_change |=(green_ctcf(n)-green_ctcf(n+1)/time |yes|
|blue_ctcf_change |=(blue_ctcf(n)-blue_ctcg(n+1))/time |yes|

Also, note the **"area_square_microns"** measure above, that stands for cell area in square microns of course.
It is defined as: **Measured area * (pixel_width*pixel_height)/scale*scale** where:
* Measured area is measured using ImageJ's "area" measurement (as shown above)
* pixel_width, pixel_height and scale are per experiement values that can be defined via Experiment->Edit experiment

===== 5. Other (misc) commmands =====

==== 5.1. Deleting (truncating) ROIs ====
"Trunc (after)" is a rarely used option for deleting the ROIs for (after) a selected frame.
Warning: deleted ROIs cannot be recovered and you'll have to detect them again.

==== 5.2. Collapse/Expand all ====
These commands are used to collapse or expand all nodes in the Frame/cell tree.

==== 5.3. Edit event ====
Using "Edit event" one can assign an arbitrary event at a certain frame (for instance, if the experiment conditions have changed, you may want to write that in the database).
The following dialog is shown:
[[File:Event.png|200px]]

Abbreviation is used to display the event in the tree, and the full desc is displayed in the lineage tree visualization.

If you want to delete the event, just edit it, and leave everything blank and the event will be deleted.

==== 5.4. Change cell state ====
With "Change bact state" command you can assign certain state (e.g. "Ignore", "Death") to the cell from some frame onward.
[[File:Bstate.png|200px]]
New state is annotated in the tree and on the lineage tree visualization.

To delete the assigned state, just set the empty state.

==== 5.5. Toggle ignore frame ====
With this command you can ignore (or un-ignore) the selected frame.
This is typically done when the frame if of a low quality (e.g. out of focus, unusable), but you want to keep it to keep the accurate timeline.
Cells on the ignored frame are not measured nor does the frame appear in the CSV dump.
When detecting cells on the frame F, the previous frame is considered to be the frame having maximal frame number f < F, such that it is not ignored.

===== 6. Analyis and Visualization =====

==== 6.1. Lineage tree visualization ====

BactImAs features the innovative lineage tree visualization that can map two, user selected, parameters to the cell division tree.
When you're done with measurements, choose Reports->BTree from the main menu.
The following dialog appears:

[[File:Btree_dialog.png|200px]]

It is possible to assign any of the measured (and derived - built in) variables to the two visualization properties: branch width and color.
Dialog shows the area of the cell mapped to the branch width, and green_ctcf mapped to the branch color.
Other than that, it is possible to assigne the following parameters:
* seconds per frame - used for the time scale on the right, where t(frame_no) = (frame_no-1) * seconds_per_frame
* min/max stroke width - min/max parameters on the branch color are scaled to min/max stroke width
* font size
* draw labels - whether to draw the cell labels
* convert to hours - whether to convert time in seconds to format: HH:MM:SS

BactImAs will draw a separate visualization for every cell present on the firt (non-igored) frame.
The following image shows a sample visualization from the demo database:

[[File:Btree.png|200px]]

It is our intention to include in the new version of BactImAs additional out-of-the-box statistics and visualization.
However, acknowledging that it will never be possible to cover all potential requirements, we've enabled the following option:

==== 6.2. Export data as CSV file ====

With Reports->Dump CSV one can export the experiment's data into a CSV file and proceed to analyze it in one's favorite data analysis tool.

After you assign the file name, the following dialog appears:

[[File:Dumpcsv.png|200px]]

with all the available measurements for the experiment.

==== 6.3. SQL Pane ====

BactImAs stores all the data (except images) in the SqLite database.
Database can be accessed using any of the SqLite client tools - there are many such tools freely available on the Internet.
It is also possible to access it using the simple built-in SQL Pane editor, which allows for arbitrary SQL statements (queries) to be executed and displayed in a table, and even exported as CSV.
The following figure shows the SQL pane:

[[File:Sqlpane.png|200px]]

Of course, to use SQL pane one has to know the SQL programming language.
It is our intention, for the future releases of BactImAs, to build a library of predefined SQL queries, with adjoining descriptions in natural language, so that
a user that has no knowledge of SQL language can pick from the set the available predefined queries and retrieve results for his or hers experiment.

===== 7. Backup, upgrade and data exchange =====

==== 7.1. Backup ====

To backup the data one should simply copy the "data" directory to a safe place, every once in a while.

==== 7.2. Upgrade ====

When upgrading BactImAs, it is best to:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 7.3. Data exchange ====

(see also the BactImAs structure in the User->Installation)
To exchange data, it is necessary to exchange database and images folder (best zipped).

[[File:Exchange.png|400px]]

Should person A want to send experiment data to person B, these are the steps to follow:

* Person A sends the images folder (best zipped) to person B. Person B saves (extracts) them to person B's images folder. One could use cloud storage for this steps (eg Dropbox, GDrive) as images are too big for email.
* Person A sends the BactImAs.s3db file (database) from dbs folder to person B. Person B potentially renames it (to avoid clashing with person B's database), saves it to the dbs folder, and adjust the URL in the conf/db.properties to point to this new database (see User->Installation)

The second step can be repeated if there are new data measured in the database, while the first step needs to be done only once.

Installation

2023-07-18T10:52:01Z

Igor: /* Release 0.7.1 */

===== BactImAs Installation Guide =====

==== 1. BactImAs releases (download) ====

=== Release 0.7.1 ===

* Binaries (ready to run)
* [https://homer.zpr.fer.hr/BactImAs_releases/071/BactImAs071.zip BactImAs(6 MB)]
* Source code (for the developers)
* Hosted at Github: [https://github.com/mekterovic/bactimas https://github.com/mekterovic/bactimas]

==== 2. Installation ====

BactImAs is a multi-platform application written in Java which uses sqlite database.
It can run (at least) on:
* Mac
* Linux
* Ms Windows

However, you should first install (if you don't already have it):
* Java (1.7+) [[http://docs.oracle.com/javase/7/docs/webnotes/install/|Download]]
* SqLite [[http://www.sqlite.org/download.html|Download]], [[http://www.tutorialspoint.com/sqlite/sqlite_installation.htm|Install guide]]
both of them being easy to install.

BactImAs is distributed in two ways:
- as an [[http://icy.bioimageanalysis.org/|Icy]] **plugin**
- **stand-alone** version

If you're using the plugin, then you can easily install BactImAs via the Icy plugin infrastructure (and Icy will make sure you always have an up-to-date version).

If you want the standalone version, then the installation boils down to downloading and extracting a zip file.
Once you've extracted BactImAs.zip into a folder of your choice, you start the app by:

(a) double clicking on the bactimas.jar
or, from console,using the following statement (from the BactImAs folder):
(b) java -jar bactimas.jar
or
(c) java -jar -Xmx500m bactimas.jar (to give it e.g. 500MB of memory, depends on your configuration)

In both cases, upon start, BactImAs will detect that you don't have the data and conf folders and will offer to set them up.
You should agree and subsequently choose whether you want to download the demo database (~180MB).
You can also download the demo database later, either through the same process or manually.

==== 3. BactImAs structure ====

BactImAs is structured as follows:

(bactimas folder)
|
|- bactimas.jar (main file, double click it to run BactImAs, or start it from the console with: java -jar BactImAs.jar)
|- IJ_Prefs.txt (IJ prefs file) - only in standalone version
|- ImageJ.cfg (IJ config file - used on Windows OS to control and save how much memory will ImageJ get, open it with any text editor and check) - only in standalone version
|- logs (logs folder, used for troubleshooting)
|- lib (folder with additional library files)
|- conf (folder with configuration files, here you specify the database and additional algorithms)
|- data (IMPORTANT: folder holding your data: database and image files.
|- images You should backup this folder periodically. )
|- dbs

==== 4. Architecture ====

BactImAs is designed to run in a single-user mode, meaning that the program is self-sufficient and does not require internet connection to work.
This is achieved by keeping the program and data (database and images) locally:

[[File:Arch1.png|300px]]

This doesn't mean that you cannot share your data with someone else. It is possible to have multiple databases on your machine (but work with only one at the time), e.g.:

[[File:Arch2.png|300px]]

Merging databases is not yet supported, but it will probably be supported in the future.

BactImAs could also be configured to run in an Intranet environment, where all users would save the data into the same database (but then it would be better to swap SQLite for some other database, e.g. MySql, PostgreSQL, etc.) maintained by the DB Administrator, e.g.:

[[File:Arch3.png|300px]]

==== 5. Version upgrade ====
To upgrade, download the latest version and:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 6. Troubleshooting: ====

=== BactImAs will not start ===
Check which version of Java you have installed because BactImAs runs on Java 7 or higher.
* In Mac OS: Go to system preferences. In the folder “Other” doubleclick on Java icon and a new window will appear where you can click “About” to check which Java version you have installed.
* In Windows, Linux, Mac: start the console (win_key+R, then type "cmd") and type "java -version" in the console to find your java version

=== There are no available experiments to load ===
If you haven't installed the empty version (in which case this is fine) then it is probably a path issue.
Check whether the URL in the conf/db.properties points to the existing file.
Make sure the database path is correct and you used the correct delimiter (there can be differences between OS: slash vs backslash).

Installation

2023-07-18T10:51:34Z

Igor:

===== BactImAs Installation Guide =====

==== 1. BactImAs releases (download) ====

=== Release 0.7.1 ===

* Binaries (ready to run)
* [https://homer.zpr.fer.hr/BactImAs_releases/071/BactImAs071.zip BactImAs(6 MB)]
* Source code (for the developers)
* Hosted at Github: [https://github.com/mekterovic/bactimas|https://github.com/mekterovic/bactimas]

==== 2. Installation ====

BactImAs is a multi-platform application written in Java which uses sqlite database.
It can run (at least) on:
* Mac
* Linux
* Ms Windows

However, you should first install (if you don't already have it):
* Java (1.7+) [[http://docs.oracle.com/javase/7/docs/webnotes/install/|Download]]
* SqLite [[http://www.sqlite.org/download.html|Download]], [[http://www.tutorialspoint.com/sqlite/sqlite_installation.htm|Install guide]]
both of them being easy to install.

BactImAs is distributed in two ways:
- as an [[http://icy.bioimageanalysis.org/|Icy]] **plugin**
- **stand-alone** version

If you're using the plugin, then you can easily install BactImAs via the Icy plugin infrastructure (and Icy will make sure you always have an up-to-date version).

If you want the standalone version, then the installation boils down to downloading and extracting a zip file.
Once you've extracted BactImAs.zip into a folder of your choice, you start the app by:

(a) double clicking on the bactimas.jar
or, from console,using the following statement (from the BactImAs folder):
(b) java -jar bactimas.jar
or
(c) java -jar -Xmx500m bactimas.jar (to give it e.g. 500MB of memory, depends on your configuration)

In both cases, upon start, BactImAs will detect that you don't have the data and conf folders and will offer to set them up.
You should agree and subsequently choose whether you want to download the demo database (~180MB).
You can also download the demo database later, either through the same process or manually.

==== 3. BactImAs structure ====

BactImAs is structured as follows:

(bactimas folder)
|
|- bactimas.jar (main file, double click it to run BactImAs, or start it from the console with: java -jar BactImAs.jar)
|- IJ_Prefs.txt (IJ prefs file) - only in standalone version
|- ImageJ.cfg (IJ config file - used on Windows OS to control and save how much memory will ImageJ get, open it with any text editor and check) - only in standalone version
|- logs (logs folder, used for troubleshooting)
|- lib (folder with additional library files)
|- conf (folder with configuration files, here you specify the database and additional algorithms)
|- data (IMPORTANT: folder holding your data: database and image files.
|- images You should backup this folder periodically. )
|- dbs

==== 4. Architecture ====

BactImAs is designed to run in a single-user mode, meaning that the program is self-sufficient and does not require internet connection to work.
This is achieved by keeping the program and data (database and images) locally:

[[File:Arch1.png|300px]]

This doesn't mean that you cannot share your data with someone else. It is possible to have multiple databases on your machine (but work with only one at the time), e.g.:

[[File:Arch2.png|300px]]

Merging databases is not yet supported, but it will probably be supported in the future.

BactImAs could also be configured to run in an Intranet environment, where all users would save the data into the same database (but then it would be better to swap SQLite for some other database, e.g. MySql, PostgreSQL, etc.) maintained by the DB Administrator, e.g.:

[[File:Arch3.png|300px]]

==== 5. Version upgrade ====
To upgrade, download the latest version and:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 6. Troubleshooting: ====

=== BactImAs will not start ===
Check which version of Java you have installed because BactImAs runs on Java 7 or higher.
* In Mac OS: Go to system preferences. In the folder “Other” doubleclick on Java icon and a new window will appear where you can click “About” to check which Java version you have installed.
* In Windows, Linux, Mac: start the console (win_key+R, then type "cmd") and type "java -version" in the console to find your java version

=== There are no available experiments to load ===
If you haven't installed the empty version (in which case this is fine) then it is probably a path issue.
Check whether the URL in the conf/db.properties points to the existing file.
Make sure the database path is correct and you used the correct delimiter (there can be differences between OS: slash vs backslash).

Installation

2023-07-18T10:50:47Z

Igor: Created page with "===== BactImAs Installation Guide ===== ==== 1. BactImAs releases (download) ==== === Release 0.7.1 === * Binaries (ready to run) * BactImAs(6 MB) * Source code (for the developers) * Hosted at Github: https://github.com/mekterovic/bactimas ==== 2. Installation ==== BactImAs is a multi-platform application written in Java which uses sqlite dat..."

===== BactImAs Installation Guide =====

==== 1. BactImAs releases (download) ====

=== Release 0.7.1 ===

* Binaries (ready to run)
* [[https://homer.zpr.fer.hr/BactImAs_releases/071/BactImAs071.zip|BactImAs(6 MB)]]
* Source code (for the developers)
* Hosted at Github: [[https://github.com/mekterovic/bactimas|https://github.com/mekterovic/bactimas]]

==== 2. Installation ====

BactImAs is a multi-platform application written in Java which uses sqlite database.
It can run (at least) on:
* Mac
* Linux
* Ms Windows

However, you should first install (if you don't already have it):
* Java (1.7+) [[http://docs.oracle.com/javase/7/docs/webnotes/install/|Download]]
* SqLite [[http://www.sqlite.org/download.html|Download]], [[http://www.tutorialspoint.com/sqlite/sqlite_installation.htm|Install guide]]
both of them being easy to install.

BactImAs is distributed in two ways:
- as an [[http://icy.bioimageanalysis.org/|Icy]] **plugin**
- **stand-alone** version

If you're using the plugin, then you can easily install BactImAs via the Icy plugin infrastructure (and Icy will make sure you always have an up-to-date version).

If you want the standalone version, then the installation boils down to downloading and extracting a zip file.
Once you've extracted BactImAs.zip into a folder of your choice, you start the app by:

(a) double clicking on the bactimas.jar
or, from console,using the following statement (from the BactImAs folder):
(b) java -jar bactimas.jar
or
(c) java -jar -Xmx500m bactimas.jar (to give it e.g. 500MB of memory, depends on your configuration)

In both cases, upon start, BactImAs will detect that you don't have the data and conf folders and will offer to set them up.
You should agree and subsequently choose whether you want to download the demo database (~180MB).
You can also download the demo database later, either through the same process or manually.

==== 3. BactImAs structure ====

BactImAs is structured as follows:

(bactimas folder)
|
|- bactimas.jar (main file, double click it to run BactImAs, or start it from the console with: java -jar BactImAs.jar)
|- IJ_Prefs.txt (IJ prefs file) - only in standalone version
|- ImageJ.cfg (IJ config file - used on Windows OS to control and save how much memory will ImageJ get, open it with any text editor and check) - only in standalone version
|- logs (logs folder, used for troubleshooting)
|- lib (folder with additional library files)
|- conf (folder with configuration files, here you specify the database and additional algorithms)
|- data (IMPORTANT: folder holding your data: database and image files.
|- images You should backup this folder periodically. )
|- dbs

==== 4. Architecture ====

BactImAs is designed to run in a single-user mode, meaning that the program is self-sufficient and does not require internet connection to work.
This is achieved by keeping the program and data (database and images) locally:

[[File:Arch1.png|300px]]

This doesn't mean that you cannot share your data with someone else. It is possible to have multiple databases on your machine (but work with only one at the time), e.g.:

[[File:Arch2.png|300px]]

Merging databases is not yet supported, but it will probably be supported in the future.

BactImAs could also be configured to run in an Intranet environment, where all users would save the data into the same database (but then it would be better to swap SQLite for some other database, e.g. MySql, PostgreSQL, etc.) maintained by the DB Administrator, e.g.:

[[File:Arch3.png|300px]]

==== 5. Version upgrade ====
To upgrade, download the latest version and:
(a) extract new BactImAs version into a new folder
(b) copy the old version's data folder over(write) the new version's data folder.

==== 6. Troubleshooting: ====

=== BactImAs will not start ===
Check which version of Java you have installed because BactImAs runs on Java 7 or higher.
* In Mac OS: Go to system preferences. In the folder “Other” doubleclick on Java icon and a new window will appear where you can click “About” to check which Java version you have installed.
* In Windows, Linux, Mac: start the console (win_key+R, then type "cmd") and type "java -version" in the console to find your java version

=== There are no available experiments to load ===
If you haven't installed the empty version (in which case this is fine) then it is probably a path issue.
Check whether the URL in the conf/db.properties points to the existing file.
Make sure the database path is correct and you used the correct delimiter (there can be differences between OS: slash vs backslash).

MediaWiki:Sidebar

2023-07-18T10:48:50Z

Igor:

* navigation
** mainpage|mainpage-description
* Users
** Installation|Installation
** User manual|User manual
** Video tutorial|Video tutorial
* Developers

MediaWiki:Sidebar

2023-07-18T10:48:01Z

Igor:

MediaWiki:Sidebar

2023-07-18T10:47:33Z

Igor: Created page with " * navigation ** mainpage|mainpage-description ** Users *** Installation|Installation *** User manual|User manual *** Video tutorial|Video tutorial ** Developers"

* navigation
** mainpage|mainpage-description
** Users
*** Installation|Installation
*** User manual|User manual
*** Video tutorial|Video tutorial
** Developers

Main Page

2023-07-18T10:42:10Z

Igor:

== Welcome to BactImAs Wiki pages ==

'''BactImAs is an open-source multi platform java application''' intended to assist the researcher in tracking various organisms in sequences of images and obtaining and visualizing their quantitative data.

Bactimas paper is published here: [[http://dx.doi.org/10.1186/1471-2105-15-251|DOI:10.1186/1471-2105-15-251]]

'''Motivation:'''
A common task in today’s synthetic and systems biology studies is the analysis of various features of organisms using movies obtained through time-lapse microscopy. \\
This process consists of identifying organisms on a large number of images and measuring their features whilst keeping track of their lineage which is **a very cumbersome and error prone task** for the researcher.
To facilitate the analysis, various mostly automated tools and algorithms were developed in recent years but all of them targeting rather specific organisms and/or laboratory setups, since a general purpose automated solution to this detection problem is extremely hard if not impossible.

'''Solution:'''
We've designed BactImAs as a "platform", that is as a collection of somewhat independent well defined modules working together. Such setup facilitates maintenance, customization and upgrades.
This property is particularly useful for the tracking algorithms - in BactImAs it is possible to include '''multiple tracking algorithms''' ("best-of-breed approach") and thus use the best fitted algoritm for the problem at hand. \\
It is even possible to mix-and-match algorithms in a way to segment one part of the movie with algorithm A and the other part with algorithm B.

BactImAs uses a semi-automated approach: it relies on the user to define the initial cells and all cell divisions. Other than that, the application tracks cells using a our newly developed algorithm. At any point, the user can intervene and correct any unsatisfactory cell detections.

BactImAs provides the following features:

* Easy to use GUI interface
* Frame anlignment algorithm
* Novel mycobacteria segmentation algorithm
* Novel configurable lineage tree visualization
* Automated acquisition of quantitative date
* Relational database storage, SQL interface to data
* Data export (CSV)

----

[[File:bactrack_main.png|400px]]
[[File:btree.png|400px]]
[[File:frame.png|400px]]
[[File:segmentation.png|400px]]

----
=== Example reports produced by BactImAs: ===

* BW Report video generated from the program (black outline - computer, white - human

<youtube>xSpLbs5pe_Y</youtube>

* Color report video generated from the program (green outline - human, red - human)

<youtube>GKMdunbu6CM</youtube>

Main Page

2023-07-18T10:35:42Z

Igor:

== Welcome to BactImAs Wiki pages ==

'''BactImAs is an open-source multi platform java application''' intended to assist the researcher in tracking various organisms in sequences of images and obtaining and visualizing their quantitative data.

Bactimas paper is published here: [[http://dx.doi.org/10.1186/1471-2105-15-251|DOI:10.1186/1471-2105-15-251]]

'''Motivation:'''
A common task in today’s synthetic and systems biology studies is the analysis of various features of organisms using movies obtained through time-lapse microscopy. \\
This process consists of identifying organisms on a large number of images and measuring their features whilst keeping track of their lineage which is **a very cumbersome and error prone task** for the researcher.
To facilitate the analysis, various mostly automated tools and algorithms were developed in recent years but all of them targeting rather specific organisms and/or laboratory setups, since a general purpose automated solution to this detection problem is extremely hard if not impossible.

'''Solution:'''
We've designed BactImAs as a "platform", that is as a collection of somewhat independent well defined modules working together. Such setup facilitates maintenance, customization and upgrades.
This property is particularly useful for the tracking algorithms - in BactImAs it is possible to include '''multiple tracking algorithms''' ("best-of-breed approach") and thus use the best fitted algoritm for the problem at hand. \\
It is even possible to mix-and-match algorithms in a way to segment one part of the movie with algorithm A and the other part with algorithm B.

BactImAs uses a semi-automated approach: it relies on the user to define the initial cells and all cell divisions. Other than that, the application tracks cells using a our newly developed algorithm. At any point, the user can intervene and correct any unsatisfactory cell detections.

BactImAs provides the following features:

* Easy to use GUI interface
* Frame anlignment algorithm
* Novel mycobacteria segmentation algorithm
* Novel configurable lineage tree visualization
* Automated acquisition of quantitative date
* Relational database storage, SQL interface to data
* Data export (CSV)

----

[[File:bactrack_main.png|400px]]
[[File:btree.png|400px]]
[[File:frame.png|400px]]
[[File:segmentation.png|400px]]

----
Example reports produced by BactImAs:

<embedvideo service="youtube">https://www.youtube.com/watch?v=xSpLbs5pe_Y</embedvideo>

{{youtube>xSpLbs5pe_Y?medium|BW Report video generated from the program (black outline - computer, white - human) }}
{{youtube>GKMdunbu6CM?medium|Color report video generated from the program (green outline - human, red - human) }}

File:Sqlpane.png

2023-07-18T10:33:15Z

Igor:

File:Segmentation.png

2023-07-18T10:33:02Z

Igor:

File:Report with color option.png

2023-07-18T10:32:53Z

Igor:

File:Phases.png

2023-07-18T10:32:41Z

Igor:

File:Measure bg.png

2023-07-18T10:32:30Z

Igor:

File:Measure.png

2023-07-18T10:32:20Z

Igor:

File:Frame.png

2023-07-18T10:32:10Z

Igor:

File:Exchange.png

2023-07-18T10:32:02Z

Igor:

File:Event.png

2023-07-18T10:31:50Z

Igor:

File:Editexperiment.png

2023-07-18T10:31:39Z

Igor:

File:Edge det algs.png

2023-07-18T10:31:29Z

Igor:

File:Dumpcsv.png

2023-07-18T10:31:18Z

Igor:

File:Db.png

2023-07-18T10:31:09Z

Igor:

File:Ca params.png

2023-07-18T10:31:01Z

Igor:

File:Btree dialog.png

2023-07-18T10:30:51Z

Igor:

File:Btree.png

2023-07-18T10:30:41Z

Igor:

File:Bstate.png

2023-07-18T10:30:23Z

Igor:

File:Bactrack main.png

2023-07-18T10:30:13Z

Igor:

File:Bactrack gui.png

2023-07-18T10:30:00Z

Igor:

File:Arch3.png

2023-07-18T10:29:51Z

Igor:

File:Arch2.png

2023-07-18T10:29:41Z

Igor:

File:Arch1.png

2023-07-18T10:29:30Z

Igor:

Main Page

2023-07-18T10:28:29Z

Igor:

== Welcome to BactImAs Wiki pages ==

'''BactImAs is an open-source multi platform java application''' intended to assist the researcher in tracking various organisms in sequences of images and obtaining and visualizing their quantitative data.

Bactimas paper is published here: [[http://dx.doi.org/10.1186/1471-2105-15-251|DOI:10.1186/1471-2105-15-251]]

'''Motivation:'''
A common task in today’s synthetic and systems biology studies is the analysis of various features of organisms using movies obtained through time-lapse microscopy. \\
This process consists of identifying organisms on a large number of images and measuring their features whilst keeping track of their lineage which is **a very cumbersome and error prone task** for the researcher.
To facilitate the analysis, various mostly automated tools and algorithms were developed in recent years but all of them targeting rather specific organisms and/or laboratory setups, since a general purpose automated solution to this detection problem is extremely hard if not impossible.

'''Solution:'''
We've designed BactImAs as a "platform", that is as a collection of somewhat independent well defined modules working together. Such setup facilitates maintenance, customization and upgrades.
This property is particularly useful for the tracking algorithms - in BactImAs it is possible to include '''multiple tracking algorithms''' ("best-of-breed approach") and thus use the best fitted algoritm for the problem at hand. \\
It is even possible to mix-and-match algorithms in a way to segment one part of the movie with algorithm A and the other part with algorithm B.

BactImAs uses a semi-automated approach: it relies on the user to define the initial cells and all cell divisions. Other than that, the application tracks cells using a our newly developed algorithm. At any point, the user can intervene and correct any unsatisfactory cell detections.

BactImAs provides the following features:

* Easy to use GUI interface
* Frame anlignment algorithm
* Novel mycobacteria segmentation algorithm
* Novel configurable lineage tree visualization
* Automated acquisition of quantitative date
* Relational database storage, SQL interface to data
* Data export (CSV)

----

{{:bactrack_main.png?400|}}
{{:btree.png?400|}}
{{:frame.png?400|}}
{{:segmentation.png?400|}}

----
Example reports produced by BactImAs:

{{youtube>xSpLbs5pe_Y?medium|BW Report video generated from the program (black outline - computer, white - human) }}
{{youtube>GKMdunbu6CM?medium|Color report video generated from the program (green outline - human, red - human) }}