Protocols is a graphical environment that enables anyone to prototype and design image processing and quantification protocols graphically, without any prior knowledge in programming.
More than just words, let's start with an introductory (although slightly outdated) video:
How to design a protocol
- Adds blocks to your protocol, either by right-clicking inside the workspace and navigating the various categories, or by using the keyword-based search using the left-hand side panel. Each block represents an elementary image processing or quantification task. Ideally, all plugins in Icy should have their block counterpart. If you notice a plugin that is not available as a block, you are very welcome to submit a comment on the page of the plugin you wish to use and ask for it.
- Link blocks together by dragging arrows (on the edge of each block) from block to block. By doing so, the blocks will automatically communicate and transfer their results between one another and run sequentially.
A protocol and all its parameters may at any time be saved (in XML format), and submitted to the Icy website for immediate sharing and/or perma-linking in a scientific publication. Any protocol published online may be downloaded and installed in a seamless manner (all required plug-ins are automatically installed). Any user can hence re-run a given protocol using the original parameters, and further edit the pipeline by adjusting parameters or adding and removing blocks.
If you don't feel confident enough to start from scratch, don't worry, a number of protocols already exist and are freely available on the Icy website. Click here to access this list.
Processing many files at once
In addition to bringing powerful programming abilities to non-expert users, one of the major benefits of Protocols is the ability to run a given protocol on a large number of images automatically (a process many users refer to as "batch mode").
Creating batches with protocols is as simple as building the protocol itself. Let's start with a simple protocol that runs on the current (active, or focused) sequence, computes statistics on the ROI in the sequence and save these statistics to a workbook on disk:
In order to batch process an entire folder, we basically need to run the entire protocol multiple times, replacing the "active sequence" from the first block each file of the folder. To do so, click on the "embed" icon in the Protocols interface (the one to the left of the "Play" button). When clicked, a menu appears and offers a number of options to perform loops and batch processing. Then, click on "sequence file batch", which basically says "embed the current protocol inside a batch to process a folder of sequence files". The intial protocol now appears embeded within a larger, enclosing block with a few parameters defining the batch parameters:
As can be seen from the screenshot above, one of the batch parameter is the folder to process. To the right of this parameter is an arrow that will read and provide, one after the other, all of the sequences available inside the specified folder, ready to be processed by the inner blocks. The last step is thus to make the final link from this arrow to the entry point of our embeded protocol, here replacing the "active sequence" of the first "inner" block:
Note that the batch parameters will change depending on the type of batch requested. In the current example, the "sequence file batch" block will automatically list all available sequence files in the specified folder (discarding non-image data) and read them from disk before passing them to the inner blocks. But it is also possible to run other types of batch processes, for instance on a list of files (images or not), a series of files from a multi-series dataset (e.g. lif, mvd2), etc.
That's (almost) it! When clicking on the "Play" button, the enclosing block will read the first image, run the inner protocol, then move on to the second image of the folder, run the protocol again, and so forth. Why is "almost" it? Well, we are missing one small (but important) adjustment. The last block that saves the statistics to a workbook on disk is currently set to write the workbook anew for every new file, which is not so useful in a batch context. All we need is to change the "if file exists" option from "overwrite" to "merge sheets, excluding first row" (excluding the first row will exlude the header row from the statistics table from the second run onwards, because we don't need a new header row everytime a new image is processed).
For the most tech-savvy, protocols can also be run from the command-line, again in a very straightforward manner. The key point here is being able to pass arguments from the command-line to the various input blocks of the protocol. To do so, let's start with a minimal protocol that reads a sequence from a disk file, and saves it to another file on disk. Here we will add a new "input" block (accessible by right-clicking in the workspace and going to the "read" subsection). Go ahead and add a "File" input block:
This file parameter can naturally be set via the graphical interface, but we need to give it an ID such that it can be set from the command-line. To set the ID, click on the block's menu (the upper-left-hand icon), and set the ID to, say, "input1":
Let's repeat the operation again by adding another "File" input block, and setting its ID to "output1":
Let's finalize the protocol by renaming and linking these blocks to the other ones:
And our protocol is ready. Here comes the magic spell:
icy.sh -hl -x plugins.adufour.protocols.Protocols protocol=/my/great.protocol input1=/my/inputFile output1=/my/outputFile
Let's briefly analyse this line:
- icy.sh is the Icy startup command (NB: replace by icy.exe on windows; you can also generically use "java -jar icy.jar" instead)
- "-hl" is short for "headless", which means icy will run on the command line and no graphical interface will appear
- "-x" tells icy to run a specific plugin at startup (this plugin is "Protocols", as you might have guessed)
- "protocol=..." indicates the path to the protocol file to run
- "input1=..." and "output1=..." are used to pass all the necessary parameters to the protocol, using the IDs specified above.
That's it. You can now run Icy with your favorite protocol on any Java-friendly machine (desktop, server, cluster, smart fridge, etc.)
Contributors to this project include:
- Ludovic Laborde (copy/pasting, dis-embedding, search bar, block renaming)
- Stephane Dallongeville (for stress-testing, troubleshooting and continous support, one update at a time)
- All of the happy (and patient) alpha/beta/gamma testers and feature requesters out there!