The Groovy Console

Groovy (www.groovy-lang.org) is an "agile and dynamic language for the Java platform". The groovy scripting language makes it extremely easy to programmatically interact with Java programs, in much the same way that Javascript is used to generate and interact with applets and other objects on the page.

Getting Groovy...
Jalview comes with an embedded installation of Groovy. Just select Tools→Groovy Console... from the Jalview Desktop's drop-down menu. After a short pause, you should then see the Groovy Console appear. This allows you to interactively execute Groovy scripts whilst Jalview is running. We've also provided a Calculations→Run Groovy Console Script button so you can execute the currently loaded groovy script whilst viewing an alignment.

Executing groovy scripts on Jalview startup
The --groovy <script> option on the Jalview command line will execute the contents of <script>. <script> may be a file, a URL, or alternatively if it is "STDIN" then the standard input will be used.
Note: The groovy script will be executed after any data is loaded, and before images or any output files are written. This allows you to perform customised Jalview analysis workflows with groovy.

Access to Jalview's functions from Groovy Scripts
The scripting interface to Jalview is still a work in progress, so we recommend you also take a look at Jalview's source, since all the public methods of the jalview class hierarchy can be called from Groovy scripts. In addition, the following objects are also defined:

• Jalview - this is bound to jalview.bin.groovy.JalviewObject providing access to the following useful methods:
  • Jalview.getAlignFrames() - returns a list of jalview.gui.AlignFrame objects
  • Jalview.getCurrentAlignFrame() - returns the alignment window which has most recently been in focus. If you change focus to another alignment window then re-running Jalview.getCurrentAlignFrame() will return the new AlignFrame.
• currentAlFrame When used on the command line this refers to the current opened alignment.
  When used from the Groovy Console, it refers to the alignment that was in focus when the Groovy Console was opened.
  When a Groovy Console script is run from Calculate->Run Groovy Console Script, currentAlFrame us updated to that alignment.

If you specify a --groovy argument before an --open argument then you should ensure your script doesn't refer to currentAlFrame.

A simple script

• Getting the title, alignment and first sequence from the current alignFrame
  

  def al = Jalview.getCurrentAlignFrame();
  print al.getTitle();
  def alignment = al.viewport.alignment;
  def seq = alignment.getSequenceAt(0);
  

• If you wanted to do the same thing from the command line, you can refer to alignment that was just loaded with currentAlFrame:
  

  print currentAlFrame.getTitle();

Example scripts
If you have downloaded the InstallAnywhere version of Jalview, you can find additional groovy scripts in the examples/groovy subfolder of the installation directory. The examples are also available at https://www.jalview.org/examples/groovy.

Using Groovy to add new Alignment Calculations
We've simplified the alignment analysis programming interface in Jalview 2.10 to make it easy for you to add your own dynamic annotation tracks with Groovy. Have a look at the featuresCounter.groovy example for more information.

Creating custom colourschemes
You can create your own alignment colourschemes with a groovy script. We've provided two examples:

• colourConserved.groovy creates an 'Conserved' colourscheme - similar to the classic GeneDOC shading model.
• colourUnconserved.groovy creates an 'Unconserved' colourscheme, where any unconserved residues are coloured pink.