Changeset 3570

Timestamp:

Jul 19, 2007, 8:45:03 AM (16 years ago)

Author:

Nicklas Nordborg

Message:

References #551. Moved (and updated) documentation about analysis plug-ins from the old format
to docbook

File:

• trunk/doc/src/docbook/developerdoc/plugin_developer.xml (modified) (4 diffs)

trunk/doc/src/docbook/developerdoc/plugin_developer.xml

@@ -1770 +1770 @@
               by reading the headers from the input stream and checking if 
               it stopped at an unknown type of line or not:
-              <example>
-                <title>Checking file headers</title>
                 <programlisting>
 public final boolean isImportable(InputStream in)
@@ -1789 +1787 @@
 }
 </programlisting>
-              </example>
             </para>
             <para>
@@ -2721 +2718 @@
       <methodname>Plugin.getMainType()</methodname> method. The information returned from
       <methodname>InteractivePlugin.getGuiContexts()</methodname>
-      must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>] since 
-      this is the only place where the web client looks for analysis plug-ins.
+      must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>] 
+      since this is the main place where the web client looks for analysis plug-ins. If
+      the plug-in can work on a subset of the bioassays it may also include
+      [<constant>Item.BIOASSAY</constant>, <constant>Type.LIST</constant>]
+      among the contexts. This will make it possible for a user to select
+      bioassays from the list and then invoke the plug-in.
     </para>
     
-<programlisting>private static final Set&lt;GuiContext&gt; guiContexts = 
+<programlisting>
+private static final Set&lt;GuiContext&gt; guiContexts = 
    Collections.singleton(new GuiContext(Item.BIOASSAYSET, GuiContext.Type.ITEM));
 
@@ -2733 +2735 @@
 }</programlisting>
 
+    <para>
+    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 <methodname>InteractivePlugin.isInContext()</methodname> 
+    method. It is also a good idea to check if the current user has permission
+    to use the current experiment. This permission is needed to create new bioassaysets or
+    other data belonging to the experiment.
+    </para>
+  
+    <programlisting>
+public boolean isInContext(GuiContext context, Object item)
+{
+   if (item == null)
+   {
+      message = "The object is null";
+   }
+   else if (!(item instanceof BioAssaySet))
+   {
+      message = "The object is not a BioAssaySet: " + item;
+   }
+   else
+   {
+      BioAssaySet bas = (BioAssaySet)item;
+      int channels = bas.getRawDataType().getChannels();
+      if (channels != 2)
+      {
+         message = "This plug-in requires 2-channel data, not " + channels + "-channel.";
+      }
+      else
+      {
+         Experiment e = bas.getExperiment();
+         e.checkPermission(Permission.USE);
+      }
+   }
+}
+</programlisting>
+
+    <para>
+    The plugin should always include a parameter asking for the current 
+    bioassay set when the <methodname>InteractivePlugin.getRequestInformation()</methodname>
+    is called with <literal>command = Request.COMMAND_CONFIGURE_JOB</literal>.
+    </para> 
+
+    <programlisting>
+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(context);
+   }
+   else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
+   {
+      requestInformation = getConfigureJob(context);
+   }
+   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 plug-in-specific parameters here...
+    
+      configureJob = new RequestInformation(
+         Request.COMMAND_CONFIGURE_JOB,
+         "Configure job",
+         "Set parameter for plug-in execution",
+         parameters
+      );
+   }
+   return configureJob;
+}
+</programlisting>
+
+    <para>
+    Of course, the <methodname>InteractivePlugin.configure()</methodname> method needs 
+    to validate and store the bioassay set parameter as well:
+    </para>
+  
+    <programlisting>
+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);
+      }
+   }
+   catch (Throwable ex)
+   {
+      // Never throw exception, always set response!
+      response.setError(ex.getMessage(), Arrays.asList(ex));
+   }
+}
+</programlisting>
+
+    <para>
+    Now, the typical <methodname>Plugin.run()</methodname> 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.
+    </para>
+  
+    <programlisting>
+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");
+      dc.saveItem(t);
+
+      BioAssaySet result = t.newProduct(null, "new", true);
+      result.setName("After: Copying spot intensities");
+      dc.saveItem(result);
+
+      // 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();
+   }
+}
+</programlisting>
+
+    <para>
+    See <xref linkend="api_overview.dynamic_and_batch_api" />
+    for more examples of using the analysis API.
+    </para>
+
+    <sect2 id="plugin_developer.analyse.abstractanalysis">
+      <title>The AbstractAnalysisPlugin class</title>
+      
       <para>
-        More documentation is available in the old format.
-        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html"
-          >http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html</ulink>
+        This class is an abstract base class. It is a useful
+        class for most analysis plug-ins to inherit from. It's main 
+        purpose is to define <classname>PluginParameter</classname>
+        objects that are commonly used in analysis plug-ins. This includes:
       </para>
-
+      
+      <itemizedlist>
+      <listitem>
+        <para>
+        The source bioassay set: 
+          <methodname>getSourceBioAssaySetParameter()</methodname>,
+          <methodname>getCurrentBioAssaySet()</methodname>,
+          <methodname>getSourceBioAssaySet()</methodname>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+        The name and description of the child bioassay set that
+        is going to be created by the plug-in:
+        <methodname>getChildNameParameter()</methodname>,
+        <methodname>getChildDescriptionParameter()</methodname>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+        The name and description of the transformation that
+        represents the execution of the plug-in:
+        <methodname>getTransformationNameParameter()</methodname>,
+        <methodname>getTransformationName()</methodname>
+        </para>
+      </listitem>
+      </itemizedlist>
+      
+    </sect2>
 
   </sect1>