Changeset 3570


Ignore:
Timestamp:
Jul 19, 2007, 8:45:03 AM (14 years ago)
Author:
Nicklas Nordborg
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r3565 r3570  
    17701770              by reading the headers from the input stream and checking if
    17711771              it stopped at an unknown type of line or not:
    1772               <example>
    1773                 <title>Checking file headers</title>
    17741772                <programlisting>
    17751773public final boolean isImportable(InputStream in)
     
    17891787}
    17901788</programlisting>
    1791               </example>
    17921789            </para>
    17931790            <para>
     
    27212718      <methodname>Plugin.getMainType()</methodname> method. The information returned from
    27222719      <methodname>InteractivePlugin.getGuiContexts()</methodname>
    2723       must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>] since
    2724       this is the only place where the web client looks for analysis plug-ins.
     2720      must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>]
     2721      since this is the main place where the web client looks for analysis plug-ins. If
     2722      the plug-in can work on a subset of the bioassays it may also include
     2723      [<constant>Item.BIOASSAY</constant>, <constant>Type.LIST</constant>]
     2724      among the contexts. This will make it possible for a user to select
     2725      bioassays from the list and then invoke the plug-in.
    27252726    </para>
    27262727   
    2727 <programlisting>private static final Set&lt;GuiContext&gt; guiContexts =
     2728<programlisting>
     2729private static final Set&lt;GuiContext&gt; guiContexts =
    27282730   Collections.singleton(new GuiContext(Item.BIOASSAYSET, GuiContext.Type.ITEM));
    27292731
     
    27332735}</programlisting>
    27342736
     2737    <para>
     2738    If the plugin depends on a specific raw data type or on the number of
     2739    channels, it should check that the current bioassayset is of the
     2740    correct type in the <methodname>InteractivePlugin.isInContext()</methodname>
     2741    method. It is also a good idea to check if the current user has permission
     2742    to use the current experiment. This permission is needed to create new bioassaysets or
     2743    other data belonging to the experiment.
     2744    </para>
     2745 
     2746    <programlisting>
     2747public boolean isInContext(GuiContext context, Object item)
     2748{
     2749   if (item == null)
     2750   {
     2751      message = "The object is null";
     2752   }
     2753   else if (!(item instanceof BioAssaySet))
     2754   {
     2755      message = "The object is not a BioAssaySet: " + item;
     2756   }
     2757   else
     2758   {
     2759      BioAssaySet bas = (BioAssaySet)item;
     2760      int channels = bas.getRawDataType().getChannels();
     2761      if (channels != 2)
     2762      {
     2763         message = "This plug-in requires 2-channel data, not " + channels + "-channel.";
     2764      }
     2765      else
     2766      {
     2767         Experiment e = bas.getExperiment();
     2768         e.checkPermission(Permission.USE);
     2769      }
     2770   }
     2771}
     2772</programlisting>
     2773
     2774    <para>
     2775    The plugin should always include a parameter asking for the current
     2776    bioassay set when the <methodname>InteractivePlugin.getRequestInformation()</methodname>
     2777    is called with <literal>command = Request.COMMAND_CONFIGURE_JOB</literal>.
     2778    </para>
     2779
     2780    <programlisting>
     2781private static final RequestInformation configurePlugin;
     2782private RequestInformation configureJob;
     2783private PluginParameter&lt;BioAssaySet&gt; bioAssaySetParameter;
     2784
     2785public RequestInformation getRequestInformation(GuiContext context, String command)
     2786   throws BaseException
     2787{
     2788   RequestInformation requestInformation = null;
     2789   if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
     2790   {
     2791      requestInformation = getConfigurePlugin(context);
     2792   }
     2793   else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
     2794   {
     2795      requestInformation = getConfigureJob(context);
     2796   }
     2797   return requestInformation;
     2798}
     2799
     2800private RequestInformation getConfigureJob(GuiContext context)
     2801{
     2802   if (configureJob == null)
     2803   {
     2804      bioAssaySetParameter; = new PluginParameter&lt;BioAssaySet&gt;(
     2805         "bioAssaySet",
     2806         "Bioassay set",
     2807         "The bioassay set used as the source for this analysis plugin",
     2808         new ItemParameterType&lt;BioAssaySet&gt;(BioAssaySet.class, null, true, 1, null)
     2809      );
     2810
     2811      List&lt;PluginParameter&lt;?&gt;&gt; parameters = new ArrayList&lt;PluginParameter&lt;?&gt;&gt;();
     2812      parameters.add(bioAssaySetParameter);
     2813      // Add more plug-in-specific parameters here...
     2814   
     2815      configureJob = new RequestInformation(
     2816         Request.COMMAND_CONFIGURE_JOB,
     2817         "Configure job",
     2818         "Set parameter for plug-in execution",
     2819         parameters
     2820      );
     2821   }
     2822   return configureJob;
     2823}
     2824</programlisting>
     2825
     2826    <para>
     2827    Of course, the <methodname>InteractivePlugin.configure()</methodname> method needs
     2828    to validate and store the bioassay set parameter as well:
     2829    </para>
     2830 
     2831    <programlisting>
     2832public void configure(GuiContext context, Request request, Response response)
     2833{
     2834   String command = request.getCommand();
     2835   try
     2836   {
     2837      if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
     2838      {
     2839         // Validate and store configuration parameters
     2840         response.setDone("Plugin configuration complete");
     2841      }
     2842      else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
     2843      {
     2844         List&lt;Throwable&gt; errors =
     2845            validateRequestParameters(configureJob.getParameters(), request);
     2846         if (errors != null)
     2847         {
     2848            response.setError(errors.size() +
     2849               " invalid parameter(s) were found in the request", errors);
     2850            return;
     2851         }
     2852         storeValue(job, request, bioAssaySetParameter);
     2853         // Store other plugin-specific parameters
     2854     
     2855         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
     2856      }
     2857   }
     2858   catch (Throwable ex)
     2859   {
     2860      // Never throw exception, always set response!
     2861      response.setError(ex.getMessage(), Arrays.asList(ex));
     2862   }
     2863}
     2864</programlisting>
     2865
     2866    <para>
     2867    Now, the typical <methodname>Plugin.run()</methodname> method loads the specfied bioassay set
     2868    and it's spot data. It may do some filtering and recalculation of the spot
     2869    intensity value(s). In most cases it will store the result as a child bioassay
     2870    set with one bioassay for each bioassay in the parent bioassay set.
     2871    Here is an example, which just copies the intensity values, while
     2872    removing those with a negative value in either channel.
     2873    </para>
     2874 
     2875    <programlisting>
     2876public void run(Request request, Response response, ProgressReporter progress)
     2877{
     2878   DbControl dc = sc.newDbControl();
     2879   try
     2880   {
     2881      BioAssaySet source = (BioAssaySet)job.getParameter("bioAssaySet");
     2882      // Reload with current DbControl
     2883      source = BioAssaySet.getById(dc, source.getId());
     2884      int channels = source.getRawDataType().getChannels();
     2885     
     2886      // Create transformation and new bioassay set
     2887      Job j = Job.getById(dc, job.getId());
     2888      Transformation t = source.newTransformation(j);
     2889      t.setName("Copy spot intensities &gt;= 0");
     2890      dc.saveItem(t);
     2891
     2892      BioAssaySet result = t.newProduct(null, "new", true);
     2893      result.setName("After: Copying spot intensities");
     2894      dc.saveItem(result);
     2895
     2896      // Get query for source data
     2897      DynamicSpotQuery query = source.getSpotData();
     2898     
     2899      // Do not return spots with intensities &lt; 0
     2900      for (int ch = 1; ch &lt;= channels; ++ch)
     2901      {
     2902         query.restrict(
     2903            Restrictions.gteq(
     2904               Dynamic.column(VirtualColumn.channel(ch)),
     2905               Expressions.integer(0)
     2906            )
     2907         );
     2908      }
     2909     
     2910      // Create batcher and copy data
     2911      SpotBatcher batcher = result.getSpotBatcher();
     2912      int spotsCopied = batcher.insert(query);
     2913      batcher.close();
     2914     
     2915      // Commit and return
     2916      dc.commit();
     2917      response.setDone("Copied " + spotsCopied + " spots.");
     2918   }
     2919   catch (Throwable t)
     2920   {
     2921      response.setError(t.getMessage(), Arrays.asList(t));
     2922   }
     2923   finally
     2924   {
     2925      if (dc != null) dc.close();
     2926   }
     2927}
     2928</programlisting>
     2929
     2930    <para>
     2931    See <xref linkend="api_overview.dynamic_and_batch_api" />
     2932    for more examples of using the analysis API.
     2933    </para>
     2934
     2935    <sect2 id="plugin_developer.analyse.abstractanalysis">
     2936      <title>The AbstractAnalysisPlugin class</title>
     2937     
    27352938      <para>
    2736         More documentation is available in the old format.
    2737         See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html"
    2738           >http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html</ulink>
     2939        This class is an abstract base class. It is a useful
     2940        class for most analysis plug-ins to inherit from. It's main
     2941        purpose is to define <classname>PluginParameter</classname>
     2942        objects that are commonly used in analysis plug-ins. This includes:
    27392943      </para>
    2740 
     2944     
     2945      <itemizedlist>
     2946      <listitem>
     2947        <para>
     2948        The source bioassay set:
     2949          <methodname>getSourceBioAssaySetParameter()</methodname>,
     2950          <methodname>getCurrentBioAssaySet()</methodname>,
     2951          <methodname>getSourceBioAssaySet()</methodname>
     2952        </para>
     2953      </listitem>
     2954      <listitem>
     2955        <para>
     2956        The name and description of the child bioassay set that
     2957        is going to be created by the plug-in:
     2958        <methodname>getChildNameParameter()</methodname>,
     2959        <methodname>getChildDescriptionParameter()</methodname>
     2960        </para>
     2961      </listitem>
     2962      <listitem>
     2963        <para>
     2964        The name and description of the transformation that
     2965        represents the execution of the plug-in:
     2966        <methodname>getTransformationNameParameter()</methodname>,
     2967        <methodname>getTransformationName()</methodname>
     2968        </para>
     2969      </listitem>
     2970      </itemizedlist>
     2971     
     2972    </sect2>
    27412973
    27422974  </sect1>
Note: See TracChangeset for help on using the changeset viewer.