batchPreProcess help

The program carries out batch processing and analysis of images.

• It can read two series of images from a folder or from MATLAB variables, and
• analyze them according to a MATLAB script, and
• save the processed images into a folder or to a MATLAB variable, and
• save the analysis results into a MATLAB variable.

Written by Peter Nagy (peter.v.nagy@gmail.com).

Web page: peternagyweb.hu

Requirements:

• BioFormats
• DipImage
• openpicture

The program will use "openpicture" to open conventional and microscopy image formats. Since "openpicture" uses BioFormats to import images of microscopy image files, both openpicture and BioFormats have to be installed and available. Processed images are saved in ICS format for which DipImage is used. The program will check for the presence of these utilities, and will complain if they are absent.

A. Specifying the primary image series

There are four options for specifying the images to be precessed.

• Folder: The image series can be in a folder. In this case, the "Choose input folder" button will be enabled, and you can specify the folder containing the images to be processed. The program will attempt to read all files in the folder, therefore only the image files to be analyzed should be present in the specified folder.
• Variable list: If the images to be processed have already been loaded into MATLAB, they can be specified as a variable list. In this case, the "Variable for variable list" box will be enabled, and you can select the variable using a dropdown menu. The variable contaning the list of variables storing the images is a cell array of chatecters, e.g.,
  if you define a variable using the following command
  varlist={'control','treated1','treated2'}
  and you will select "varlist" as the "Variable for variable list", you will instruct the program to analyze the images stored in variables 'conrol', 'treated1' and 'treated2'.
• Selected files: You can select multiple files in a folder, and the selected files will be processed.
• Single variable: If the image has already been loaded into MATLAB, and you would like to process only one image, you can specify the variable storing the image to be processed.

You can specify how you will refer to these images in your script (in section F) in panel D. If you enter 'a' into the text field "Name of 1st input in code", then you will refer to these images with variable 'a' in your code.

B. Specifying an optional second image series

You can specify a second, optional images series to analyze. If you want to analyze only one image series, choose "Nothing" in section B. The same principles apply as to the specification of the first image series:

• You can read the images from a folder or from variables in MATLAB
• You can specify how you will refer to these images in your script.

C. Specifying image output

You can store the processed images either by saving them in a folder, or by storing them in a MATLAB variable. The images are processed according to the script, and the processed image is assigned to a variable in the script. You have to specify this variable in the text field "Name of output in code" in section D.

• If you would like to save the processed image in a folder, specify the folder in the output panel (section E) by clicking the button "Choose output folder". In the example below, you are processing images in a folder, and you name these images 'a' in your script, you store the processed image that is named "result" in your script. In this case, the processed image is the ratio of two color channels, and it will be saved in a folder you specify:
  
  The script
  result=a(:,:,0)/a(:,:,1);
  instructs the program to divide the first color channel by the second color channel, and store the result in 'result', which will be saved in the folder you specify. The saved images will have the same name as the imported image, and their format will be 'ICS'.
  You can save several images in a 3D stack. The following scrtipt saves two images in two layers of a 3D stack:
  result=newim(size(a,1),size(a,2),2);
  result(:,:,0)=a(:,:,0)/a(:,:,1);
  result(:,:,1)=a(:,:,0)/a(:,:,2);
  The first line defines a 3D stack according to DipImage syntax, the second and third lines save two ratios in the first and second layer, respectively (numbered 0 and 1 according to DipImage conventions). If the generated result is not a simple image, but rather a structure, such as in the example above, the result will be saved as a MAT file.
  
• If you select 'Variable' as the output type, as shown in the figure below, the results will be saved in a variable in the MATLAB workspace according to the name you specify in the output section of field E. In the example below, the variable in your script, which will be saved in the MATLAB workspace as a variable named 'ratios', is the variable named 'result' in your script.
  
  The script shows how to save several images in the result variable. Using the dot notation, you will save a MATLAB structure variable with fields named 'ratio1' and 'ratio2' storing two ratios:
  result.ratio1=a(:,:,0)/a(:,:,1);
  result.ratio2=a(:,:,0)/a(:,:,2);
  The variable exported to the MATLAB workspace will contain as many rows as the number of images analyzed. The processed images will be in the column (field) named "processed". In the current example, this is a structure containing two images named ratio1 and ratio2. The second column of the variable shows the names of the processed images.

D. Names of input and output variables in the code

As explained in the previous sections, you have to specify how you refer to the imported images and to the processed image in your script.

E. Specify input and output folders or variables

As explained in the previous sections, you have to specify the location of the input and output folders (if you import images from files. or if you export processed images into files), or the variables (if you process images already loaded into MATLAB, or if you export the processed images into a variable).

F. The script window

You have to write your script according to MATLAB syntax. The script will be performed for each processed image. According to DipImage conventions, numbering of pixels begins from 0. Consequently, image layers in 3D image stacks are numbered 0, 1, 2, etc. Besides the regular MATLAB commands you can use the following script commands:

• exportvariable

This command can be used for exporting results of calculations to the MATLAB workspace.

Syntax: exportvariable varname

The command will export the variable 'varname' from your script to the MATLAB workspace. The name of the variable into which the variables will be saved is specified in field H.

In the example above, images are imported from a folder into variable 'a'. The script is as follows:

m1=mean(a(:,:,0));
m2=mean(a(:,:,1));
image1=squeeze(a(:,:,0));
exportvariable m1
exportvariable m2
exportvariable image1

The first two lines calculate the mean of the first and second layers of the 3D stack and store them in variables m1 and m2, respectively. The third line stores the first layer of the 3D stack in variable 'image1'. The last three lines will store the calculated variables. The name of the variable in the MATLAB workspace into which these results will be exported is specified in field H under the code window. In the current example, the results were exported into variable 'myresults'. 'myresults' contains a row for every image, and the exported variables, 'm1', 'm2' and 'image1' in the current example, are present in the columns of the variable, and correspond to fields of a MATLAB structure array. Furthermore, the program automatically generates a field named 'input1' containing the name of the input image or input variable.

You can also use the 'exportvariable' expression to refer to different fields of the exportvariable structure stored for a previous image. For this, "exportvariable" has to be followed by proper dot notation of MATLAB structures, i.e., a dot followed by a field name. In the following script, the "seedPos" variable is generated for the first image, and it is used to perform watershed segmentation with all subsequent images.

gfp=squeeze(a(:,:,0));
loopvariable k
if k==1
[m,~,seedPos]=watershed_segment(gfp,1,8,2,1,100);
else
[m,~,seedPos]=watershed_segment(gfp,1,8,2,1,100,exportvariable(1).seedPos);
end
exportvariable seedPos
exportvariable m

The command "watershed_segment" performs manually-seeded watershed segmentation.

If the 6th line is replaced by the following

[m,~,seedPos]=watershed_segment(gfp,1,8,2,1,100,exportvariable(k-1).seedPos);

then the seed positions stored in "seedPos" will always be used from the previous image.

• savepicture

This command allows you to save images generated in the sctipt to a file. This is an additional possibility, besides the one specified in panel C, to save images.

Syntax: savepicture varname filename location

The command will save variable 'varname' with the name 'filename'. 'filename' is the file name without an extension. The location can be either

1: in this case, the file will be saved in the folder specified in the output section of panel E (assuming "Folder" is chosen in panel C).

folder: you can specify the path to a folder.

In the example above, images are imported into variable 'a', and the following script is executed:

s=a(:,:,0)+a(:,:,1);
d=a(:,:,0)-a(:,:,1);
savepicture s summa 1
savepicture d diff 'd:\Temp\Test2'

The first line calculates the sum of the first two layers, while the second one calculates their difference. The results are stored in variable 's' and 'd'. According to the third line, 's' is saved in image named 'summa' suffixed with '_' and a number, i.e., the files are named 'summa_1.ics' and 'summa_2.ics', and they are saved in the folder specified in the output section of panel E. According to the fourth line, 'd' is saved in image named 'diff' in the folder 'd:\Temp\Test2'. Images are saved in ICS format.

• simpleopenpicture

The command allows you to import images in addition to the ones specified in panels A and B.

Syntax: simpleopenpicture varname filename ext folder

varname: the image will be imported into the variable named 'varname'

filename: name of the file without the extension.

ext: extension of the file name. If the specified filename is 'testimage', and the extension is 'jpg', the folder has to contain images named 'testimage_1.jpg', 'testimage_2.jpg', etc. The number of these images has to be the same as the number of images specified in panel A.

folder: it is the folder from which images are read.

In the following script, 'a' is the variable into which images are imported according to panel A. The second line opens images from 'd:\Temp\test3' into variable 'colorimage'. The image name is 'testimage', the extension is 'jpg', so the folder has to contain images named 'testimage_1.jpg', 'testimage_2.jpg', etc. The third and fourth lines calculate means, the fifth one adds them, and the last line stores them in variable m.

s=a(:,:,0)+a(:,:,1);
simpleopenpicture colorimage 'testimage' 'jpg' 'd:\Temp\test3'
m1=mean(s);
m2=mean(colorimage(:,:,0));
m=m1+m2;
exportvariable m

• loopvariable

This command specifies a variable that will increase its value by one in each execution of the loop (starting from 1), i.e., for every image processed.

Syntax: loopvariable varname

loopvariable k
m=mean(a);
time=k*15;
exportvariable time
exportvariable m

The script above specifies that the loop variable is named 'k', calculates the mean of the image imported into variable 'a' (as spcified in panel A). If images were recorded every 15 seconds, then the time of recording is 15 multiplied by the image number, which is calculated in line 3, and stored in variable 'time'. The last two lines specify that the time and the mean are saved in the variable specified in field H. The variable will look like this:

• batchmessage

If you include this command, a message specified after the command will be displayed, e.g.,

batchmessage Don't panic.

will display the message 'Don't panic'. The message will be displayed while the next command is executed.

• batchmessageforever

If you include this command, a message specified after the command will be displayed, e.g.,

batchmessage Don't panic.

will display the message 'Don't panic'. The message will be displayed until another batchmessage or batchmessageforever command is found or until the end of the script..

• batchmessageremove

This command removes the message that was displayed with batchmessageforever.

• if ... then ... else

Conditional expressions are interpreted. The condition, 'else' and 'end' have to be written in individual lines, e.g.,

if test==1
result='ok';
else
result='not ok';
end

• labelline, gotolabel

A command line can be labeled by the 'labelline' statement. The number or string following 'labelline' is the ID of the line, e.g.,

labelline returnhere1

the ID of the line will be 'returnhere1'

The 'gotolabel X' statement jumps program executation to the line labeled by X.

Example:

labelline 1
resp=questdlg('Are you happy?','Satisfied','Yes','No','Yes');
if strcmp(resp,'No')
gotolabel 1
end

In the following code, if you respond 'No' to the 'Are you happy?" question, program executation will return to the line labeled by 'labelline 1'.

G. Save and load code

You can save the code in the script window (panel F) in a text file (with the default MATLAB extension 'm'), and reload it later.

H. Structure variable for calculation results

As explained in the section describing the script syntax (section F), you can specify the name of the variable exported to the MATLAB workspace, which will store calculation results specified by the 'exportvariable' command.

I. Input structure variable

The script can import a MATLAB structure variable. In the dropdown menu, select the variable to be imported, and in the text field "Name in code", specify how you will refer to the imported variable. The imported variable has to be a structure variable with the proper fields that you have to explicitly refer to in your script. In the example below, variable "results" will be imported, and it will be refered to as "inputvar" in the script. The script will use the "seeds" field of the input variable (line 2).

gfp=squeeze(a(:,:,0));
[m,~,seedPos]=watershed_segment(gfp,1,8,2,1,100,inputvar.seeds);
exportvariable seedPos
exportvariable m

If you do not specify which array member you would like to use, e.g. "inputvar.seeds", the ith element in the structure array will be used for the ith image.

inputvar(1).seeds - the first element in the structure array will be used

If you specify a loop variable, you can flexibly refer to arbitrary elements of the imported variable. In the example below, "seedPos" of the 2nd element will be used for the 1st image, the 3rd element will be used for the 2nd image, etc.

gfp=squeeze(a(:,:,0));
loopvariable k
[m,~,seedPos]=watershed_segment(gfp,1,8,2,1,100,inputvar(k+1).seedPos);
exportvariable seedPos
exportvariable m