The analysis system supports iterated sub-analyses as a hidden part of an analysis.

The following example iterates through all bridge fragility keys, and does a bridge damage and bridge functionality analysis with them, then feeds these result datasets into a map parameter called bridgeFunctionalityMap.

 <analysis-description id="ncsa.maeviz.test.TestAnalysis" help-context="ncsa.maeviz.ui.bridge_damage">

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

	<sub-analysis-iterator output-id='bridgeFunctionalityMap' output-type="datasetmap" iteration-generator-type="fragilityKeyContributor" iteration-id="ncsa.maeviz.bridges.BridgeFragilityKeyContributor">
		<sub-analysis analysis-id="ncsa.maeviz.bridges.BridgeDamage" output-id='bridgeDamage'>
			<fixed-param source='iterator' modifier='guidmapmodifier' key='retrofits' modifier-param='bridges'/>
			<require-optional-param param='bridgeRetrofitCostEstimate'/>
		</sub-analysis>
		<sub-analysis analysis-id="ncsa.maeviz.bridges.BridgeFunctionality" add-to-iterator-output="true">
			<fixed-param source='sub-analysis-output' from-output-id='bridgeDamage' key='bridgeDamage' is-dataset="true"/>
		</sub-analysis>
	</sub-analysis-iterator>


	<parameter  phylum="string" cardinality="single" key="subtestAnalysis.resultName" friendly-name="Result Name" >
		<description>Name for the resulting dataset</description>
	</parameter>

	<parameter  phylum="datasetmap" format="sub-analysis-result" cardinality="multiple" key="bridgeFunctionalityMap" friendly-name="Bridge Functionality">
		<types>
			<type>bridgeFunctionality</type>
		</types>

	</parameter>



	<!-- OUTPUTS -->

	<output friendly-name="Bridge Damage" key="subtestAnalysis" phylum="dataset" format="shapefile" geom="bridges" guids="bridges">
		<property name="bridges" type="base-dataset-key" value="bridges" />
		<property name="schema" type="schema" value="ncsa.maeviz.schemas.bridgeDamage.v1.0" />
	</output>



</analysis-description>

 A few notes:

 iteration-generator-type refers to an extension point that controls the iteration of the sub-analyses.  To create new iterations for sub-analyses, the extension point ncsa.analysis.subanalysisIterationGenerator should be extended, implementing the SubAnalysisIterationGenerator interface.  In this case, fragilityKeyContributor returns a list of elements based on a fragilityKeyContributor.  iteration-id is an id that can be used by the SubAnalysisIterationGenerator in whatever way is necessary for it to determine what elements to return.

When doing sub-analyses, all the input parameters of the sub-analyses are added to the input page of the master analysis, except for parameters that are specified using fixed-param element.  The fixed-param element is used to specify parameters that should not be added to the UI.  At this time, there are two types of these, which should be specified by a source attribute. 

If source is specified as iterator, the value will come from the iterator value for each iteration.  If this is used, a modifier attribute must also be used, which refers to the ncsa.analysis.scriptvariablemodifier extension point.  These point to an implementation of ScriptVariableModifier which is used to convert values from simple strings (the iteration value) to any complex values or objects that are used as parameters.  In this example, the iteration value is just a string that refers to the retrofit level of the bridges.  But the parameter must be a map that maps each GUID of the feature dataset to a retrofit level. So the guidmapmodifier extension point refers to a class that converts from a string to this guid map.  The modifier also takes a param which is the name of an analysis parameter that can be passed it to help make the conversion.  (in this case, the converter needs access to the bridges parameter to get the GUIDS).

The other type of source for fixed-params is sub-analysis-output, which means that it gets its input from the output of a previous sub-analysis.  In this case, the previous sub-analysis must include a fromt-output-id attribute, which makes an id to match its output to the input of this other fixed parameter.

In addition to marking parameters as fixed, parameters in sub-analysis can be marked to promote them from optional parameters to required parameters.  In this example, in the original bridge damage analysis, the retrofit cost estimate is optional.  But in our test analysis, we want it to be required.  The require-optional-param element promotes this parameter to being required.

  • No labels