Analysis Framework Developer's Guide

There are four steps required to add an Analysis to the Analysis Framework.

Step One: Create the Analysis Description

First, one must create a new Analysis Description file for the Analysis. This will require knowledge of the parameters, outputs, and runtime requirements of the Analysis to be implemented.

Step Two: Create the Task

Second, one must implement the Analysis as a Task. Pick the appropriate base class and implement the required methods. Remember that the keys given to the parameters in the Analysis Description must match the set methods in this class. Also, the column names given to the outputs must match the values given in the schema for the specific dataset type.

Step Three: Register with the ncsa.analysis.newAnalyses extension point

Third, register this extension. Remember that the id here must match the id given in the Analysis Description and the tag must match the tag in the ncsa.tools.ogrescript.ogreTasks extension point.

Step Four: Register with the ncsa.tools.ogrescript.ogreTasks extension point.

Lastly, register the Task with this extension point. Remember that the tag here must match the tag given in the ncsa.analysis.newAnalyses extension point above.

Analysis Description

The Analysis Description file provides detailed information about the various sections of an Analysis.

<analysis-description>

Attributes

Elements

Text

This element has no text.

<analysis-type>

Attributes

Elements

Text

This element has no text.

Example

<analysis-type type="simpleIteration">
    <property name="iteratingDatasetKey" value="bridgeDamage" />
</analysis-type>

<custom-script>

Attributes

This element has no attributes.

Elements

This element has no children.

Text

Defines a location for a custom OgreScript to use instead of auto-generating one. The format for this script will be defined on a separate page. This location is relative to the bundle in which the analysis is shipped.

Example

<custom-script>scripts/ogrescript-bridgeFunc.xml</custom-script>

<groups>

Groups are currently unused by the analysis system. See the optional and advanced attributes instead. If groups are included in the analysis description, they are ignored.

<parameter>

A parameter element with key <outputKey>.resultName is required. This is the only way to change a resultName for a given output.

<parameter key="mappingResult.resultName"  phylum="string" cardinality="single" friendly-name="Result Name" />

...

<output friendly-name="Mapping Result" key="mappingResult" phylum="dataset">
...

Attributes

Elements

Text

This element has no text.

Example

<parameter group="Required" format="dataset" cardinality="single" key="functionalityTable" friendly-name="Functionality Table">
    <types>
        <type>bridgeFunctionality</type>
    </types>
</parameter>

Syntax for various parameter widget types

A list of the various parameter widget types available, and an example for each, can be found on the Parameter Widget Examples page.

<output>

An <output> of type dataset requires two <property> elements.

• base-dataset-key - The key of the <parameter> which is the base for this new Dataset
• schema - The id of the schema that this Dataset implements.

Attributes

Elements

Text

This element has no text.

Example

<output friendly-name="Bridge Functionality" key="bridgeFunctionality" format="dataset">
    <property name="base-dataset-key" value="bridgeDamage" />
    <property name="schema" value="ncsa.maeviz.schemas.bridgeFunctionalityResults.v1.0" />
</output>

Task class

Each Analysis MUST implement a class which extends ncsa.analysis.maeviz.ogrescript.tasks.core.SimpleFeatureTask. In the future a choice of base class based on the specific implementation required will be available.

There are two required abstract methods.

protected abstract void preProcess() throws ScriptExecutionException;
    protected abstract void handleFeature( IProgressMonitor monitor ) throws ScriptExecutionException;

Requirements

For each <parameter> there must be a corresponding set method which corresponds to the key attribute in the <parameter>.

Example:

<parameter group="Required" format="dataset" cardinality="single" key="functionalityTable" friendly-name="Functionality Table" />

public void setFunctionalityTable( Dataset d );

The handleFeature method is responsible for two things. First is computing the values that are to be added to the new Feature. Second is to populate the resultMap.

Example:

resultMap.put( COL_LS_SLIGHT, dmg[0] );
resultMap.put( COL_LS_MODERATE, dmg[1] );

As a best practice, add public final static constants for each column in the Feature. These column names MUST match the fields as defined in the gisSchema for the created dataset.

ncsa.analysis.newAnalyses extension point

Each Analysis must register an extension with the ncsa.analysis.newAnalyses extension point. This registration allows the Analysis Framework to find all Analyses automatically.

ncsa.tools.ogrescript.ogreTasks extension point

Each Analysis must register its implementing class with the ncsa.tools.ogrescript.ogreTasks extension point.