help/help/html/features/groovy.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  -->
  22 <head>
  23 <title>Groovy Console</title>
  24 </head>
  25 <body>
  26   <p>
  27     <strong>The Groovy Console</strong>
  28   </p>
  29   <p>
  30     Groovy (<a href="http://www.groovy-lang.org/">www.groovy-lang.org</a>)
  31     is an &quot;<em>agile and dynamic language for the Java
  32       platform</em>&quot;. The groovy scripting language makes it extremely
  33     easy to programmatically interact with Java programs, in much the
  34     same way that Javascript is used to generate and interact with
  35     applets and other objects on the page.
  36   </p>
  37   <p>
  38     <em>Getting Groovy...</em><br> Jalview comes with an embedded
  39     installation of Groovy. Just select <strong>Tools&#8594;Groovy
  40       Console...</strong> from the Jalview Desktop's drop-down menu. After a
  41     short pause, you should then see the <a
  42       href="https://groovy-lang.org/groovyconsole.html">Groovy
  43       Console</a> appear. This allows you to interactively execute Groovy
  44     scripts whilst Jalview is running. We've also provided a <strong>Calculations&#8594;Run
  45       Groovy Console Script</strong> button so you can execute the currently loaded
  46     groovy script whilst viewing an alignment.
  47   </p>
  48   <p>
  49     <strong>Executing groovy scripts on Jalview startup</strong><br>
  50     The --groovy &lt;script&gt; option on the <a href="commandline.html">
  51       Jalview command line</a> will execute the contents of &lt;script&gt;.
  52     &lt;script&gt; may be a file, a URL, or alternatively if it is
  53     &quot;STDIN&quot; then the standard input will be used.<br> <em>Note:
  54       The groovy script will be executed <strong>after</strong> any data
  55       is loaded, and <strong>before</strong> images or any output files
  56       are written. This allows you to perform customised Jalview
  57       analysis workflows with groovy.
  58     </em>
  59   </p>
  60   <p>
  61     <strong>Access to Jalview's functions from Groovy Scripts</strong><br>
  62     The scripting interface to Jalview is still a work in progress, so
  63     we recommend you also take a look at Jalview's source, since all the
  64     public methods of the jalview class hierarchy can be called from
  65     Groovy scripts. In addition, the following objects are also defined:
  66   </p>
  67
  68   <ul>
  69     <li><strong>Jalview</strong> - this is bound to <code>jalview.bin.groovy.JalviewObject</code> providing access to the following useful
  70       methods:
  71       <ul>
  72         <li>Jalview.getAlignFrames() - returns a list of
  73           jalview.gui.AlignFrame objects</li>
  74         <li>Jalview.getCurrentAlignFrame() - returns the alignment
  75           window which has most recently been in focus.  If you change focus to another alignment window then re-running <code>Jalview.getCurrentAlignFrame()</code> will return the new <code>AlignFrame</code>.</li>
  76       </ul></li>
  77     <li><strong>currentAlFrame</strong> When used on the command line this refers to the current opened alignment.
  78     <br/>
  79     When used from the Groovy Console, it refers to the alignment that was in focus when the Groovy Console was opened.
  80     <br/>
  81     When a Groovy Console script is run from <em>Calculate</em>-&gt;<em>Run Groovy Console Script</em>, <code>currentAlFrame</code> us updated to that alignment.</li>
  82   </ul>
  83   <p>
  84     If you specify a <code>--groovy</code> argument before an <code>--open</code> argument
  85     then you should ensure your script doesn't refer to <code>currentAlFrame</code>.
  86   <p>
  87
  88   <p>
  89     <em>A simple script</em><br />
  90   <ul>
  91     <li>Getting the title, alignment and first sequence from the
  92       current alignFrame<br> <pre>
  93 def al = Jalview.getCurrentAlignFrame();
  94 print al.getTitle();
  95 def alignment = al.viewport.alignment;
  96 def seq = alignment.getSequenceAt(0);
  97 </pre>
  98     </li>
  99     <li>If you wanted to do the same thing from the command line,
 100       you can refer to alignment that was just loaded with
 101       currentAlFrame:<br> <pre>
 102 print currentAlFrame.getTitle();</pre>
 103   </ul>
 104   <p>
 105     <em>Example scripts</em><br />If you have downloaded the
 106     InstallAnywhere version of Jalview, you can find additional groovy
 107     scripts in the examples/groovy subfolder of the installation
 108     directory. The examples are also available at <a
 109       href="https://www.jalview.org/examples/groovy">https://www.jalview.org/examples/groovy</a>.
 110   </p>
 111   <p>
 112     <em>Using Groovy to add new Alignment Calculations</em><br />We've
 113     simplified the alignment analysis programming interface in Jalview
 114     2.10 to make it easy for you to add your own dynamic annotation
 115     tracks with Groovy. Have a look at the <a
 116       href="../groovy/featuresCounter.html">featuresCounter.groovy</a>
 117     example for more information.
 118   </p>
 119   <p><a name="groovyColours"/>
 120     <em>Creating custom colourschemes</em><br/>
 121     You can create your own alignment colourschemes with a groovy script. We've provided two examples:<br/>
 122     <ul>
 123     <li><a href="https://www.jalview.org/examples/groovy/colourConserved.groovy">colourConserved.groovy</a> creates an 'Conserved' colourscheme - similar to the classic <a href="http://www.nrbsc.org/old/gfx/genedoc/">GeneDOC</a> shading model.</li>
 124     <li><a href="https://www.jalview.org/examples/groovy/colourUnconserved.groovy">colourUnconserved.groovy</a> creates an 'Unconserved' colourscheme, where any unconserved residues are coloured pink.</li>
 125
 126     </ul>
 127   </p>
 128
 129 </body>
 130 </html>