Short Description

Design your own bioimage analysis workflow, graphically, and automate it on many images (batch processing).

No programming knowledge required! Protocols can be shared and re-used straight from the Icy website.

Watch this 30 minutes introduction to protocols during the NEUBIAS Academy @home webinar (go directly to 29:18 to skip the general introduction to Icy) and see the corresponding slides (whole webinar or protocol part only).

Team: Bio image Analysis Unit
Institution: Institut Pasteur
Website: http://icy.bioimageanalysis.org

Documentation

The plugin Protocols provide a graphical environment that enables anyone to create graphically and without any prior knowledge in programming a bioimage analysis workflow, and automate it on many images (batch processing).

Available protocols

To get you quickly started and inspired, you can browse the online collection of Icy protocols or search directly through the Icy software search bar with your favorite keywords.

How to design a protocol

  • Add blocks to your protocol, either by right-clicking inside the workspace and navigating through the various categories, or by using the keyword-based search in the left-hand side panel. Each block represents an elementary image processing or quantification task. Most plugins in Icy 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.

Block description
  • Run the full protocol by clicking on the top play button. Run some blocks only by clicking on the play button of the block (see block description above). The protocol will be run till this block.

A protocol and all its parameters can be saved at any time (in XML format) by clicking on “save” and reloaded from a local repository by clicking on “Load”.

We encourage users to add their finished protocols to the Icy website for immediate sharing and/or perma-linking in a scientific publication. Indeed, protocols published on the Icy website can be downloaded directly from the Icy software. Any user can hence re-run a given protocol using the original parameters, and further edit the workflow by adjusting parameters, adding or removing blocks. To share a protocol on the Icy website, you need to create an account first, then log in your account, go to the dashboard and click on “Protocols -> Add New”.

How to organize large protocols

A protocol can quickly have a large number of blocks and managing screen space is then critical. We gather here a few useful tips:

  • rename your blocks to convey more information

  • collapse most of the blocks (see the block description above)
  • rearrange blocks or group of blocks in the space (ctrl+click to select one or more blocks)
  • embed blocks belonging to the same step or “component”, for instance “segmentation”, using workflow blocks. Add a workflow block to your protocol, select all the blocks you would like to embed with ctrl+click, cut them with ctrl+X and paste them inside the workflow block with a left click in the workflow block and then ctrl+V. In the end, expose the variables that need to be connected to outside of the workflow block (right click on the variable). Note that only real inputs and outputs can be exposed. Variables that are just “transferred” from one block to the other cannot be exposed.

How to do batch processing

You can run a given protocol on a large number of images automatically (a process many users refer to as “batch mode“).

Create and test your protocol on a single image. Then click on “embed” in the Protocols editor menu. This option embeds the current protocol in a batch type block.

There is many batch type blocks. File batch process sequentially all files in a given folder. Sequence file batch process sequentially all sequences (images) in a given folder. Etc.

Example of batch protocol

On the screenshot above, one of the batch parameter is the folder to process. To the right of this parameter, there is a black arrow that will read and provide, one after the other, all of the files available inside the specified folder, ready to be processed by the inner blocks. Connect this arrow to the entry point of our embeded protocol, here the “input file” of the first inner block “Load image”.

When clicking on the “Play” button, the enclosing block will import the first file, run the inner protocol, then move on to the second file of the folder, run the protocol again, and so forth.

Note that some inner block parameters may have to be adjusted after embedding. For instance, in a workbook to file, the “if file exists” option can be set to “merge sheets, excluding first row” in order to gather all results from all images into a single spreadsheet.

How to run a protocol from the command-line

Protocols can also be run from the command-line.The key point here is to pass arguments from the command-line to the various input blocks of the protocol.

To do this, we have to give an ID to each block whose input or output variable we want to modify via the command-line. Note that only a few blocks can receive an ID. They are listed in the “Read” section of the contextual menu (right click -> Read section). You may need to add additionnal blocks to your protocol to make it work from the command line. To set the ID, click on the block’s menu (the upper-left-hand icon), and write for instance “input1”, as in the video above.

 

 

To launch the protocol from the command line, the video above uses a command similar to this one:

icy.sh -hl -x plugins.adufour.protocols.Protocols protocol=/my/great.protocol input1=/my/inputFile

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=… is used to pass a parameter to the protocol (in the video, a path to a folder to process), using the ID created above. There can be as many IDs here as parameters needed: input1=…, input2=…, input3=…, output1=…

You can now run Icy with your favorite protocol on any Java-friendly machine (desktop, server, cluster, smart fridge, etc.).

Acknowledgements

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!

Resources needing this

9 reviews on “Protocols

  1. IcyLyd
    Just Awesome! Really great to chain several actions and so nice to be able to loop protocols to get batch analysis. It saves so much time. And on top of that it's really visual. IcyLyd
  2. Fabrice de Chaumont
    The most didactic plugin of Icy ! Super-easy to use, no error possible while linking blocks. Must be tried !
  3. Bertrand Vernay
    Very nice tool. A must have. A pan tool (space bar activated) will be useful especially when working on a small size display. Thanks
  4. It is wonderful to have the ability to draw a graphical design for you image processing.
  5. Emmanuel
    Very useful and powerful plugin that let scientist making programming without knowing anything to informatics language. Perhaps a zoom/navigation capability could help when creating large protocol. Many thanks for that
  6. DavidG
    This has fantastic capabilities to create tailored analysis sequences. Many thanks!

Leave a Review

Leave a review
Cancel review
View full changelog
Close changelog

Changelog

  • Version 3.0.8.0 • Released on: 2020-04-06 17:00:00
    Download
    Description:

    Minors improvements.

  • Version 3.0.7.0 • Released on: 2020-03-24 18:00:00
    Download
    Description:

    Fixed some bugs on complex protocols loading (links missing..)

  • Version 3.0.6.0 • Released on: 2019-07-10 15:00:00
    Download
    Description:

    fixed a bug with Java 12

  • Version 3.0.5.0 • Released on: 2019-05-20 16:00:00
    Download
    Description:

    Run until here button doesn't change priority anymore (sometime we don't want it)

  • Version 3.0.4.0 • Released on: 2018-07-24 14:39:41
    Download
    Description:

    Some GUI refresh optimizations

  • Version 3.0.3.0 • Released on: 2018-02-27 17:46:32
    Download
    Description:

    Added Protocols.getInstance() method to retrieve Protocols main instance (can be useful !)

  • Version 3.0.2.0 • Released on: 2018-02-12 17:40:55
    Download
    Description:

    Re introduced java 7 compatibility

  • Version 3.0.1.0 • Released on: 2017-02-24 16:59:15
    Download
    Description:

    Fixed an issue in headless mode on Linux

  • Version 3.0.0.0 • Released on: 2017-02-06 12:22:13
    Download
    Description:

    New: command-line support! Protocols can now be run directly from the command line, and arguments can be passed over to input blocks inside your protocols

  • Version 2.4.3.0 • Released on: 2016-06-13 12:03:54
    Download
  • Version 2.4.2.0 • Released on: 2016-05-27 10:58:08
    Download
    Description:

    Fixed a bug that occurred when installing missing blocks on-the-fly while opening a protocol

  • Version 2.4.1.0 • Released on: 2015-12-17 23:32:24
    Download
    Description:

    Fixed a graphical glitch when painting exposed links

  • Version 2.4.0.0 • Released on: 2015-12-17 23:22:37
    Download
    Description:

    * Fixed the copy-paste system
    * Only a single Protocol can be used

  • Version 2.3.1.0 • Released on: 2015-04-30 17:49:49
    Download
    Description:

    Fixed Block ID display for 3-digit numbers (yes, someone did break the century!)

  • Version 2.3.0.0 • Released on: 2015-03-18 00:11:34
    Download
    Description:

    New: execution log panel next to each protocol (BETA)

  • Version 2.2.4.0 • Released on: 2015-01-29 16:18:34
    Download
    Description:

    * Updated to SDK 4.4.5
    * Fixed display issues when loading protocols and drawing links

  • Version 2.2.3.0 • Released on: 2015-01-23 18:05:17
    Download
    Description:

    Fixed an issue causing embedded block not to allow their variables to be exposed

  • Version 2.2.2.0 • Released on: 2015-01-23 17:53:27
    Download
    Description:

    Attempting to fix a bug that is hard to find and reproduce...

  • Version 2.2.1.0 • Released on: 2014-12-19 13:05:08
    Download
    Description:

    * Upgraded to SDK v.2.2.1
    * "Run until here" and "ID" buttons are back due to popular demand
    * "Run until here" option now guarantees block highest priority

  • Version 2.2.0.0 • Released on: 2014-12-11 13:31:09
    Download
    Description:

    * Updated to SDK v.4.4
    * NEW: Protocols can now be opened directly by dropping ".protocol" files into Icy (just like images)
    * Revamped graphical user interface with all-in-one menu and status notification icon
    * Blocks can be removed using the backspace key
    * Loop: option to stop on first error

  • Version 2.1.6.0 • Released on: 2014-11-22 20:17:54
    Download
    Description:

    * Updated to Protocols engine 4.3.0.0
    * The block search panel now includes developer information in the documentation panel.

  • Version 2.1.5.0 • Released on: 2014-10-06 19:59:19
    Download
    Description:

    Fixed an issue when closing the Protocols window

  • Version 2.1.4.0 • Released on: 2014-10-05 18:18:16
    Download
    Description:

    Fixed issue causing blocks not to collapse properly

  • Version 2.1.3.0 • Released on: 2014-09-15 21:57:07
    Download
    Description:

    Bug fixes on protocol loading

  • Version 2.1.2.0 • Released on: 2014-09-12 17:40:05
    Download
    Description:

    Fixed drag'n'drop for ".protocol" files

  • Version 2.1.1.0 • Released on: 2014-08-04 17:21:52
    Download
    Description:

    Improved error handling, and fixed a few GUI glitches

  • Version 2.1.0.0 • Released on: 2014-07-24 19:16:43
    Download
    Description:

    * Major code refactoring: better separation between the engine (Protocols SDK) and the graphical user interface (Protocols)
    * Fixed memory leak
    * Improved error and message handling
    * Fixed drag'n'drop operations not working on some systems

  • Version 2.0.6.0 • Released on: 2014-07-23 00:05:09
    Download
    Description:

    Fixed the "cancel" button when closing the window

  • Version 2.0.5.0 • Released on: 2014-06-18 14:02:41
    Download
    Description:

    Fixed a copy/paste issue within inner workflows

  • Version 2.0.4.0 • Released on: 2014-06-17 18:33:02
    Download
    Description:

    Fixed an issue when copying links that contain an exposed variable (ignored for now)

  • Version 2.0.3.0 • Released on: 2014-06-17 14:45:14
    Download
    Description:

    Improved graphical layout & block descriptions

  • Version 2.0.2.0 • Released on: 2014-05-21 19:15:51
    Download
    Description:

    Update by Ludovic Laborde

    * Updated to Icy 1.5
    * Fixed drag'n'drop issue from the search bar

  • Version 2.0.1.0 • Released on: 2014-05-19 12:49:39
    Download
    Description:

    Fixed bug when closing a protocol and saving it (would not re-open it afterwards)

  • Version 2.0.0.1 • Released on: 2014-05-18 20:03:52
    Download
    Description:

    Updated jar file (line numbers did not match in bug reports)

  • Version 2.0.0.0 • Released on: 2014-05-16 21:21:18
    Download
    Description:

    Update by Ludovic Laborde

    Integrated search bar: find your blocks fast and easily, insert them with a simple drag'n'drop operation.

  • Version 1.7.5.0 • Released on: 2014-05-12 20:36:21
    Download
    Description:

    Fixed a bug causing the window closing operation not allowing to be cancelled

  • Version 1.7.4.0 • Released on: 2014-04-27 15:45:29
    Download
    Description:

    Fixed the "save as" button

  • Version 1.7.3.0 • Released on: 2014-04-24 18:45:50
    Download
    Description:

    * Removed "insert block" button from main interface (only accessible through right-click for the time being)
    * Adjusted tool bar and tool tips to be more explicit

  • Version 1.7.2.2 • Released on: 2014-01-27 13:56:44
    Download
    Description:

    Customize error message when blocks cannot be installed via Icy4Eclipse

  • Version 1.7.2.1 • Released on: 2013-11-15 21:44:58
    Download
    Description:

    Updated to Icy 1.4.2.0 (removed deprecated calls), no logic change

  • Version 1.7.2.0 • Released on: 2013-10-28 11:35:56
    Download
    Description:

    * Reload the interface when a protocol is opened from disk *after* a plugin reload event
    * Describe the loading process with an announcement frame

  • Version 1.7.1.0 • Released on: 2013-10-14 17:33:05
    Download
    Description:

    Online protocols are now downloaded to a new "protocols" subfolder inside Icy, so you can carry them with you at all times!

  • Version 1.7.0.0 • Released on: 2013-10-12 18:09:36
    Download
    Description:

    Fixed multiple reloading issues:
    * The Protocols interface now reloads only when a protocol requires the installation of one or more new plugins.
    * Reloading now correctly preserves and reloads previous state. No more data loss

  • Version 1.6.0.0 • Released on: 2013-07-12 13:46:25
    Download
    Description:

    New option to clean protocol results to save memory

  • Version 1.5.8.0 • Released on: 2013-07-12 13:33:36
    Download
    Description:

    Screenshots saved along protocols now have an extra "_protocols" suffix to avoid name clashes

  • Version 1.5.7.0 • Released on: 2013-05-27 18:05:30
    Download
    Description:

    * Fixed an issue causing all online protocols appearing in a search result to be downloaded locally (even if never used).
    * Selected protocols from the search bar are now downloaded to the default protocols folder

  • Version 1.5.6.0 • Released on: 2013-05-26 19:30:43
    Download
    Description:

    Upgraded online protocol provider to the new kernel (should reduce server load)

  • Version 1.5.5.0 • Released on: 2013-05-18 23:39:41
    Download
    Description:

    Updated to Icy 1.3.5.0 (removed deprecation calls)

  • Version 1.5.4.0 • Released on: 2013-03-25 09:13:05
    Download
    Description:

    * Images dropped in protocols are now opened in Icy
    * Fixed an issue causing Protocols to reload properly when the class loader changes

  • Version 1.5.3.0 • Released on: 2013-03-22 14:35:36
    Download
    Description:

    Fixed an issue causing Protocols to fail opening properly after Icy restarts

  • Version 1.5.2.0 • Released on: 2013-03-12 20:34:09
    Download
    Description:

    Show an error message when opening a wrong XML file (rather than a bug report)

  • Version 1.5.1.0 • Released on: 2013-03-08 15:05:08
    Download
    Description:

    Updated to Blocks v.2.4

  • Version 1.5.0.0 • Released on: 2013-02-28 19:58:29
    Download
    Description:

    Protocols can now be searched and loaded directly from Icy's search bar!

  • Version 1.4.3.0 • Released on: 2013-01-07 13:05:25
    Download
    Description:

    Fixed a memory leak (caused by the file drag'n'drop mechanism)

  • Version 1.4.2.0 • Released on: 2012-12-07 17:42:47
    Download
    Description:

    Fixed memory leaks

  • Version 1.4.1.0 • Released on: 2012-11-07 17:16:58
    Download
    Description:

    * NEW: the snapshot button has been removed from the interface; the snapshot is always saved alongside the xml file
    * Fixed minor drag'n'drop issue causing the interface border to disappear (the border is now no longer highlighted when dropping file(s))

  • Version 1.4.0.0 • Released on: 2012-11-07 16:53:00
    Download
    Description:

    * NEW: Drag protocols directly into the Protocols interface
    * Minor interface fixes when quitting Icy

  • Version 1.3.2.0 • Released on: 2012-10-16 15:01:01
    Download
    Description:

    Fixed loading bug (from 1.3.1.0)

  • Version 1.3.1.0 • Released on: 2012-10-15 16:57:28
    Download
    Description:

    Static access to the main frame (allows launching a protocol from outside the interface)

  • Version 1.3.0.0 • Released on: 2012-09-27 15:50:55
    Download
    Description:

    * Fixed support for live plugin loading/saving
    * Status bar indicates loading status

  • Version 1.2.0.0 • Released on: 2012-09-26 16:56:17
    Download
    Description:

    Resubmit jar file

  • Version 1.1.2.3 • Released on: 2012-09-26 16:20:58
    Download
    Description:

    * Updated to Blocks 1.8.0.0
    * New: the Protocols interface automatically saves its state and reloads when plugins are reloaded

  • Version 1.1.2.2 • Released on: 2012-09-06 16:28:32
    Download
    Description:

    Updated to Blocks 1.7

  • Version 1.1.2.1 • Released on: 2012-09-03 14:58:47
    Download
    Description:

    Improved error reporting (no logic change)

  • Version 1.1.2.0 • Released on: 2012-08-30 15:45:47
    Download
    Description:

    Updated to Blocks engine 1.6: ability to stop a running protocol

  • Version 1.1.1.0 • Released on: 2012-08-07 18:52:01
    Download
    Description:

    Updated to Blocks 1.5.0.0

  • Version 1.1.0.0 • Released on: 2012-08-03 12:03:49
    Download
    Description:

    Fixed bug reporting issue (bugs were never sent by email)

  • Version 1.0.2.0 • Released on: 2012-07-11 18:07:43
    Download
    Description:

    Snapshot feature restricts to the contents of the workflow

  • Version 1.0.1.0 • Released on: 2012-07-09 17:48:34
    Download
    Description:

    - Improved file saving dialog (overwrite prompt, auto-add extension)
    - Fixed a few memory leaks

  • Version 1.0.0.0 • Released on: 2012-07-06 12:06:58
    Download
    Description:

    First officially stable release !
    - Workflows can now be embedded into loops (useful for batch processing)

  • Version 0.9.9.2 • Released on: 2012-07-04 11:51:35
    Download
    Description:

    Updated to Blocks 0.12

  • Version 0.9.9.1 • Released on: 2012-07-03 18:52:50
    Download
    Description:

    Release Candidate 1:
    - Updated to Blocks 0.11.0.0
    - New status bar for each protocol
    - Removed "colorize links" button (true by default)
    - Collapse feature de-activated (will be improved in a later release)

  • Version 0.0.3.0 • Released on: 2012-06-29 19:07:58
    Download
    Description:

    * Improved interface labels and access to menus and blocks.
    * added second status bar for future use to monitor a running process

  • Version 0.0.2.0 • Released on: 2012-06-28 17:17:11
    Download
    Description:

    Added snapshot feature

  • Version 0.0.1.0 • Released on: 2012-06-22 14:11:11
    Download