Analysis method development - Revision history

Lan@dote.ru: /* Implementing parameters */

2013-09-13T07:06:09Z

‎Implementing parameters

Lan@dote.ru: /* Classes */

2013-09-13T07:05:36Z

‎Classes

Lan@dote.ru: +Creating custom parameter editor (stub)

2013-09-12T09:23:50Z

+Creating custom parameter editor (stub)

Lan@dote.ru: /* Implementing analysis */

2013-09-12T09:22:27Z

‎Implementing analysis

Lan@dote.ru: +referenceType selector /* Registering complex parameters */

2013-09-12T09:00:16Z

+referenceType selector - ‎Registering complex parameters

Lan@dote.ru at 11:10, 11 September 2013

2013-09-11T11:10:29Z

Lan@dote.ru: /* Writing bean info class for parameters */

2013-09-11T11:02:08Z

‎Writing bean info class for parameters

Lan@dote.ru: link to exceptions page fixed /* Logging */

2013-09-11T05:23:50Z

link to exceptions page fixed - ‎Logging

Lan@dote.ru: Preliminary description of analysis

2013-09-11T05:23:11Z

Preliminary description of analysis

New page

BioUML analysis method is a function which takes some user-defined parameters, processes them somehow (probably using [[repository]] elements and databases) and produces some results, storing them in the repository. This page describes implementation details on how to create your own analysis method.

If you want to create your analysis method in new plugin, please read [[plugin development]] page first.

== Classes ==
To create analysis method, you should create at least three classes:
# '''Analysis class''': class implementing {{Class|ru.biosoft.analysis.AnalysisMethod}} interface. It's strongly recommended to extend {{Class|ru.biosoft.analysis.AnalysisMethodSupport}} class parameterizing it via parameters class.
# '''Parameters class''': bean class for analysis parameters, which must implement {{Class|ru.biosoft.analysis.AnalysisParameters}} interface. It's strongly recommended to extend {{Class|ru.biosoft.analysis.AbstractAnalysisParameters}} class.
# '''Bean info for parameters class''': class implementing {{Class|java.beans.BeanInfo}} interface which describes parameters class. Must have the same name as parameters class with <code>BeanInfo</code> suffix. It's strongly recommended to extend {{Class|ru.biosoft.util.bean.BeanInfoEx2}} class.

The following naming conventions are used. Consider, you want to create some analysis to "process data". Then analysis class should be named as <code>ProcessData</code> or <code>ProcessDataAnalysis</code>, parameters class should be named as <code>ProcessDataParameters</code> and bean info for parameters class should be named as <code>ProcessDataParametersBeanInfo</code>.

If your analysis has not very much code, you may consider putting parameters class and its bean info as nested static classes into analysis class in the following manner:

public class ProcessDataAnalysis extends AnalysisMethodSupport<ProcessDataAnalysis.ProcessDataParameters>
{
...
public static class ProcessDataParameters extends AbstractAnalysisParameters
{
...
}

public static class ProcessDataParametersBeanInfo extends BeanInfoEx2
{
...
}
}

== Extension ==
To make your analysis available in the tree, you must register it as extension for [[Method (extension point)|ru.biosoft.analysis.method]] extension point. Consider also creating [[method description HTML file]] and JavaScript host object (or use existing one).

== Implementing parameters ==
Parameters class must have default constructor and getter and setter methods for all parameters used in analysis method. Setters must call {{Method|com.beanexplorer.beans.Option.firePropertyChange}} superclass method. Getters can be annotated using {{Annotation|ru.biosoft.util.bean.PropertyName}} and {{Annotation|ru.biosoft.util.bean.PropertyDescription}} annotations. Usual implementation look like this:

public class ProcessDataParameters extends AbstractAnalysisParameters
{
private DataElementPath inputPath, outputPath;
private String myStringParameter;
private boolean myBooleanParameter;

@PropertyName("Input table")
@PropertyDescription("Table to process")
public DataElementPath getInputPath()
{
return inputPath;
}

public void setInputPath(DataElementPath inputPath)
{
Object oldValue = this.inputPath;
this.inputPath = inputPath;
firePropertyChange("inputPath", oldValue, this.inputPath);
}

@PropertyName("String parameter")
@PropertyDescription("String which will be used during processing")
public String getMyStringParameter()
{
return myStringParameter;
}

public void setMyStringParameter(String myStringParameter)
{
Object oldValue = this.myStringParameter;
this.myStringParameter = myStringParameter;
firePropertyChange("myStringParameter", oldValue, myStringParameter);
}

@PropertyName("Verbose output")
@PropertyDescription("Whether to print additional messages during processing")
public boolean isMyBooleanParameter()
{
return myBooleanParameter;
}

public void setMyBooleanParameter(boolean myBooleanParameter)
{
Object oldValue = this.myBooleanParameter;
this.myBooleanParameter = myBooleanParameter;
firePropertyChange("myBooleanParameter", oldValue, myBooleanParameter);
}
}

=== Parameter types ===
Many parameter types are supported, including (but not limited to) the following:
* Primitive types (boolean, short, int, long, float, double);
* {{Class|java.lang.String}} for textual parameters;
* {{Class|ru.biosoft.access.DataElementPath}} for paths to the [[repository]] elements (both for inputs and outputs);
* {{Class|ru.biosoft.access.DataElementPathSet}} for sets of input [[repository]] elements;
* {{Class|biouml.standard.type.Species}} for selection of species from preinstalled list;
* {{Class|ru.biosoft.bsa.BasicGenomeSelector}} and {{Class|ru.biosoft.bsa.GenomeSelector}} for convenient selection of the genome (either in preinstalled database or user-uploaded);
* {{Class|java.awt.Color}} for color selection;
* Java arrays of any supported types (array elements can be added or deleted by user).

You may use your own bean as complex parameter type, but the following requirements should be met:
* Your bean should extend {{Class|com.beanexplorer.beans.Option}} class.
* Your bean should be serializable via {{Method|ru.biosoft.util.TextUtil.fromString}}/{{Method|ru.biosoft.util.TextUtil.toString}} methods. See [[text serialization]] for details.

=== Writing bean info class for parameters ===
{{Stub}}

=== Advanced parameters features ===
{{Stub}}

== Implementing analysis ==
{{Stub}}
=== Logging ===
To log messages during analysis execution, use {{Field|ru.biosoft.analysis.AnalysisMethodSupport.log}} logger instance. This instance is connected with analysis or [[workflow]] log. In case of unrecoverable error, it's better to throw [[BioUML exception]] out of <code>justAnalyzeAndPut</code> method than to log it by yourself.

=== Progress bar ===

=== Parallelization ===

[[Category:Development]]

@@ Line 33: / Line 33: @@
 Parameters class must have default constructor and getter and setter methods for all parameters used in analysis method. Setters must call {{Method|com.beanexplorer.beans.Option.firePropertyChange}} superclass method. Getters can be annotated using {{Annotation|ru.biosoft.util.bean.PropertyName}} and {{Annotation|ru.biosoft.util.bean.PropertyDescription}} annotations. Usual implementation look like this:
-  public class ProcessDataParameters extends AbstractAnalysisParameters
+  public class ProcessDataParameters extends {{Class|ru.biosoft.analysis.AbstractAnalysisParameters}}
+  {
     private DataElementPath inputPath, outputPath;
@@ Line 100: / Line 100: @@
 Bean info class must have the same name as parameters class with <code>BeanInfo</code> suffix. It must have default constructor which calls superclass constructor passing parameters class name:
-  public class ProcessDataParametersBeanInfo extends BeanInfoEx2
+  public class ProcessDataParametersBeanInfo extends {{Class|ru.biosoft.util.bean.BeanInfoEx2}}
+  {
     public ProcessDataParametersBeanInfo()

← Older revision		Revision as of 09:23, 12 September 2013
Line 136:		Line 136:
	* For {{Class\|java.awt.Color}} parameter type set {{Class\|com.beanexplorer.editors.ColorEditor}} property editor class.		* For {{Class\|java.awt.Color}} parameter type set {{Class\|com.beanexplorer.editors.ColorEditor}} property editor class.

		+	=== Creating custom parameter editor ===
	{{Stub}}		{{Stub}}

@@ Line 124: / Line 124: @@
 ** Use {{Method|ru.biosoft.access.repository.DataElementPathEditor.registerInputMulti}} methods to register set of input elements (user will be able to select several elemens using Ctrl or Shift buttons).
 ** Use {{Method|ru.biosoft.access.repository.DataElementPathEditor.registerOutput}} methods to register output element (user will be asked for confirmation to overwrite an existing item).
-* Table column name selector should be registered via static methods defined in {{Class|ru.biosoft.table.columnbeans.ColumnNameSelector}}:
+* {{Type link|table|Table}} column name selector should be registered via static methods defined in {{Class|ru.biosoft.table.columnbeans.ColumnNameSelector}}:
 ** Use {{Method|ru.biosoft.table.columnbeans.ColumnNameSelector.registerSelector}} methods to allow selection of any column.
 ** Use {{Method|ru.biosoft.table.columnbeans.ColumnNameSelector.registerNumericSelector}} methods to allow selection of numerical column only.
 *: <b>Note</b>: column name must be defined as {{Class|java.lang.String}} in parameters class and its default value must be either {{Constant|ru.biosoft.table.columnbeans.ColumnNameSelector.NONE_COLUMN}} or any existing column (not null).
-* Set of table column names should be registered via static methods defined in {{Class|ru.biosoft.table.columnbeans.ColumnNamesSelector}}:
+* Set of {{Type link|table}} column names should be registered via static methods defined in {{Class|ru.biosoft.table.columnbeans.ColumnNamesSelector}}:
 ** Use {{Method|ru.biosoft.table.columnbeans.ColumnNameSelector.registerSelector}} methods to allow selection of any columns.
 ** Use {{Method|ru.biosoft.table.columnbeans.ColumnNameSelector.registerNumericSelector}} methods to allow selection of numerical columns only.
 *: <b>Note</b>: column names must be defined as {{Class|java.lang.String[]}} in parameters class.
-* Selector for predefined species can be registered using {{Class|ru.biosoft.workbench.editors.DataElementComboBoxSelector.registerSelector}} method with {{Constant|biouml.standard.type.Species.SPECIES_PATH}} as collectionPath parameter.
+* Selector for predefined species can be registered using {{Method|ru.biosoft.workbench.editors.DataElementComboBoxSelector.registerSelector}} method with {{Constant|biouml.standard.type.Species.SPECIES_PATH}} as collectionPath parameter.
 * For {{Class|java.awt.Color}} parameter type set {{Class|com.beanexplorer.editors.ColorEditor}} property editor class.

@@ Line 98: / Line 98: @@
 === Writing bean info class for parameters ===
 Bean info class must have the same name as parameters class with <code>BeanInfo</code> suffix. It must have default constructor which calls superclass constructor passing parameters class name:
@@ Line 118: / Line 117: @@
 Parameters will appear in the form in the registration order. By convention first should be input repository elements, then other parameters and finally output repository elements. If parameter X depends on parameter Y, then X must be registered after Y.
-For some data types {{Class|java.beans.PropertyDescriptor}} should be created using special convenience methods.
+=== Registering complex parameters ===
 * Repository elements should be registered via static methods defined in {{Class|ru.biosoft.access.repository.DataElementPathEditor}}:
 ** Use {{Method|ru.biosoft.access.repository.DataElementPathEditor.registerInput}} methods to register input element (user will be forced to select existing element of given type).
@@ Line 131: / Line 132: @@
 ** Use {{Method|ru.biosoft.table.columnbeans.ColumnNameSelector.registerNumericSelector}} methods to allow selection of numerical columns only.
 *: <b>Note</b>: column names must be defined as {{Class|java.lang.String[]}} in parameters class.
 {{Stub}}

@@ Line 13: / Line 13: @@
 If your analysis has not very much code, you may consider putting parameters class and its bean info as nested static classes into analysis class in the following manner:
-  public class ProcessDataAnalysis extends AnalysisMethodSupport<ProcessDataAnalysis.ProcessDataParameters>
+  public class ProcessDataAnalysis extends {{Class|ru.biosoft.analysis.AnalysisMethodSupport}}<ProcessDataAnalysis.ProcessDataParameters>
+  {
     ...
-    public static class ProcessDataParameters extends AbstractAnalysisParameters
+    public static class ProcessDataParameters extends {{Class|ru.biosoft.analysis.AbstractAnalysisParameters}}
+    {
       ...
+    }
-    public static class ProcessDataParametersBeanInfo extends BeanInfoEx2
+    public static class ProcessDataParametersBeanInfo extends {{Class|ru.biosoft.util.bean.BeanInfoEx2}}
+    {
       ...

@@ Line 139: / Line 139: @@
 == Implementing analysis ==
-{{Stub}}
+If your analysis extends {{Class|ru.biosoft.analysis.AnalysisMethodSupport}} abstract class, then it's necessary to create constructor and override {{Method|ru.biosoft.analysis.AnalysisMethodSupport.justAnalyzeAndPut}} method where actual analysis must be performed. Normally constructor looks like this:
 === Logging ===
 To log messages during analysis execution, use {{Field|ru.biosoft.analysis.AnalysisMethodSupport.log}} logger instance. This instance is connected with analysis or [[workflow]] log. In case of unrecoverable error, it's better to throw [[BioUML exceptions|BioUML exception]] out of <code>justAnalyzeAndPut</code> method than to log it by yourself.
 === Progress bar ===
 === Parallelization ===
 [[Category:Development]]