Changeset 2155

Timestamp:

Apr 7, 2006, 2:56:14 PM (17 years ago)

Author:

Nicklas Nordborg

Message:

Fixes #139: Write documentation: 5d) Analysis plug-ins
Added another example plugin: ExampleAnalyzer?

Location:

trunk

Files:

• build.xml (modified) (2 diffs)
• doc/development/index.html (modified) (1 diff)
• doc/development/plugins/analysis/index.html (modified) (3 diffs)
• src/examples/plugins/build.xml (modified) (1 diff)
• src/examples/plugins/src/net/sf/basedb/exampleplugins/ExampleAnalyzer.java (added)

trunk/build.xml

@@ -638 +638 @@
       srcdir="${exampledir}/src"
       destdir="${exampledir}/bin"
+      debug="true"
       >
       <classpath>
@@ -660 +661 @@
       />
     </tar>
+    <delete file="${exampledir}/ExamplePlugins.jar" />
+    <delete includeemptydirs="true">
+      <fileset dir="${exampledir}/bin" includes="**/*"/>
+    </delete>
   </target>
   

trunk/doc/development/index.html

@@ -300 +300 @@
       and if existing samples should be updated or not, but doesn't
       actually import anything.
+
+    <li>ExampleAnalyzer: Asks for a multiplication factor and a cut-off value.
+      It will create a child bioassay set by multiplying the original intensities
+      with the given factor and filter out those with original intensities less than
+      the cut-off. It works for any number of channels.
+    
     </ul>
     <br>

trunk/doc/development/plugins/analysis/index.html

@@ -3 +3 @@
   $Id$
 
-  BioArray Software Environment (BASE) - http://base.thep.lu.se/
-  Copyright (C) 2002-2004 Lao Saal, Carl Troein,
-  Johan Vallon-Christersson, Jari Häkkinen, Nicklas Nordborg
-
-  This file is part of BASE.
+  Copyright (C) 2006 Nicklas Nordborg
+
+  This file is part of BASE - BioArray Software Environment.
+  Available at http://base.thep.lu.se/
 
   BASE is free software; you can redistribute it and/or
@@ -44 +43 @@
   <div class="abstract">
   
-    TODO
+    <p>
+    This document contains information specific for writing analysis plugins.
+    </p>
   
     <p>
@@ -50 +51 @@
     </p>
     <ol>
-      <li>
-
+      <li><a href="#analysis">Analysis plugins</a>
     </ol>
+    
     <p>
     <b>See also</b>
+    </p>
+    
     <ul>
-    <li>
+    <li><a href="../index.html">How to write plug-ins</a>
+    <li><a href="../../overview/dynamic/index.html">Dynamic API for experiments and analysis</a>
     </ul>
-    </p>
     
     <p class="authors">
-    <b>Last updated:</b> $Date$
+    <b>Last updated:</b> $Date$<br>
+    <b>Copyright &copy;</b> 2006 The respective authors. All rights reserved.
     </p>
   </div>
-
+  
+  <a name="analysis"></a>
+  <h2>1. Analysis plugins</h2>
+  
+  <p>
+  A plugin becoms an analysis plugin simply by returning <code>Plugin.MainType.ANALYSIS</code>
+  from the <code>Plugin.getMainType()</code> method.
+  </p>
+
+  <p>
+  The information return from <code>InteractivePlugin.getGuiContexts()</code>
+  must include: <code>GuiContext = [Item.BIOASSAYSET, Type.ITEM]</code>
+  since this is the only place where the web client looks for analysis plugins.
+  </p>
+  
+  <pre class="code">
+private static final Set&lt;GuiContext&gt; guiContexts = 
+   Collections.singleton(new GuiContext(Item.BIOASSAYSET, GuiContext.Type.ITEM));
+
+public Set&lt;GuiContext&gt; getGuiContexts()
+{
+   return guiContexts;
+}
+</pre>
+  
+  <p>
+  If the plugin depends on a specific raw data type or on the number of
+  channels, it should check that the current bioassayset is of the
+  correct type in the <code>InteractivePlugin.isInContext()</code> method:
+  </p>
+  
+  <pre class="code">
+/**
+   Check if the item is a bioassay set with a 2-channel raw data type
+*/
+public boolean isInContext(GuiContext context, Object item)
+{
+   if (item instanceof BioAssaySet)
+   {
+      BioAssaySet bas = (BioAssaySet)item;
+      RawDataType rdt = bas.getRawDataType();
+      int channels = rdt.getChannels();
+      return channels == 2;
+   }
+   return false;
+}
+</pre>
+
+  <p>
+  The plugin should always include a parameter asking for the current 
+  bioassay set when the <code>InteractivePlugin.getRequestInformation()</code>
+  is called with the <code>command = Request.COMMAND_CONFIGURE_JOB</code>.
+  </p>  
+
+  <pre class="code">
+private static final RequestInformation configurePlugin;
+private RequestInformation configureJob;
+private PluginParameter&lt;BioAssaySet&gt; bioAssaySetParameter;
+
+public RequestInformation getRequestInformation(GuiContext context, String command) 
+   throws BaseException
+{
+   RequestInformation requestInformation = null;
+   if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
+   {
+      requestInformation = getConfigurePlugin(guiContext);
+   }
+   else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
+   {
+      requestInformation = getConfigureJob(guiContext);
+   }
+   return requestInformation;
+}
+
+private RequestInformation getConfigureJob(GuiContext context)
+{
+   if (configureJob == null)
+   {
+      bioAssaySetParameter; = new PluginParameter&lt;BioAssaySet&gt;(
+         "bioAssaySet",
+         "Bioassay set",
+         "The bioassay set used as the source for this analysis plugin",
+         new ItemParameterType&lt;BioAssaySet&gt;(BioAssaySet.class, null, true, 1, null)
+      );
+
+      List&lt;PluginParameter&lt;?&gt;&gt; parameters = new ArrayList&lt;PluginParameter&lt;?&gt;&gt;();
+      parameters.add(bioAssaySetParameter);
+      // Add more plugin-specific parameters...
+    
+      configureJob = new RequestInformation(
+         Request.COMMAND_CONFIGURE_JOB,
+         "Configure job",
+         "TODO - description",
+         parameters
+      );
+   }
+   return configureJob;
+}
+private RequestInformation getConfigurePlugin(GuiContext context)
+{
+   if (configurePlugin == null)
+   {
+      // TODO - Add plugin-specific parameters
+      configurePlugin = new RequestInformation(
+         Request.COMMAND_CONFIGURE_PLUGIN,
+         "Configure plugin",
+         "This plugin has no configuration options.",
+         null
+      );
+   }
+}
+</pre>
+
+  <p>
+  Of course, the <code>configure</code> method needs to validate and store
+  the bioassay set parameter as well:
+  </p>
+  
+  <pre class="code">
+public void configure(GuiContext context, Request request, Response response)
+{
+   String command = request.getCommand();
+   try
+   {
+      if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
+      {
+         // Validate and store configuration parameters
+         response.setDone("Plugin configuration complete");
+      }
+      else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
+      {
+         List&lt;Throwable&gt; errors = 
+            validateRequestParameters(configureJob.getParameters(), request);
+         if (errors != null)
+         {
+            response.setError(errors.size() +
+               " invalid parameter(s) were found in the request", errors);
+            return;
+         }
+         storeValue(job, request, bioAssaySetParameter);
+         // Store other plugin-specific parameters
+      
+         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
+         // TODO - better estimate of execution time!!
+      }
+   }
+   catch (Throwable ex)
+   {
+      // Never throw exception, always set response!
+      response.setError(ex.getMessage(), Arrays.asList(ex));
+   }
+}
+</pre>
+
+  <p>
+  Now, the typical <code>run()</code> method loads the specfied bioassay set
+  and it's spot data. It may do some filtering and recalculation of the spot
+  intensity value(s). In most cases it will store the result as a child bioassay
+  set with one bioassay for each bioassay in the parent bioassay set.
+  Here is an example, which just copies the intensity values, while
+  removing those with a negative value in either channel.
+  </p>
+  
+  <pre class="code">
+public void run(Request request, Response response, ProgressReporter progress)
+{
+   DbControl dc = sc.newDbControl();
+   try
+   {
+      BioAssaySet source = (BioAssaySet)job.getParameter("bioAssaySet");
+      // Reload with current DbControl
+      source = BioAssaySet.getById(dc, source.getId());
+      int channels = source.getRawDataType().getChannels();
+      
+      // Create transformation and new bioassay set
+      Job j = Job.getById(dc, job.getId());
+      Transformation t = source.newTransformation(j);
+      t.setName("Copy spot intensities &gt;= 0");
+      BioAssaySet result = t.newProduct(null, "new");
+      result.setName("After: Copying spot intensities");
+      dc.saveItem(t);
+      dc.saveItem(result);
+      
+      // Create child bioassays for each source bioassay
+      for (BioAssay ba : source.getBioAssays.list(dc))
+      {
+         dc.saveItem(result.newBioAssay(ba));
+      }
+
+      // Get query for source data
+      DynamicSpotQuery query = source.getSpotData();
+      
+      // Do not return spots with intensities &lt; 0
+      for (int ch = 1; ch &lt;= channels; ++ch)
+      {
+         query.restrict(
+            Restrictions.gteq(
+               Dynamic.column(VirtualColumn.channel(ch)),
+               Expressions.integer(0)
+            )
+         );
+      }
+      
+      // Create batcher and copy data
+      SpotBatcher batcher = result.getSpotBatcher();
+      int spotsCopied = batcher.insert(query);
+      batcher.close();
+      
+      // Commit and return
+      dc.commit();
+      response.setDone("Copied " + spotsCopied + " spots.");
+   }
+   catch (Throwable t)
+   {
+      response.setError(t.getMessage(), Arrays.asList(t));
+   }
+   finally
+   {
+      if (dc != null) dc.close();
+   }
+}
+</pre>
+
+  <p>
+  See the <a href="../../overview/dynamic/index.html">Dynamic API for experiments and analysis</a>
+  for more examples of using the analysis API.
+  </p>
+  
 </body>
 </html>

trunk/src/examples/plugins/build.xml

@@ -27 +27 @@
          srcdir="${src}"
          destdir="${bin}"
+         debug="true"
          classpathref="classpath">
       </javac>