Analyzer Devices - A.16 MVAModelType

A.16 MVAModelType

The MVAModel Variables are used to hold the description of a mathematical process and associated information to convert scaled data into one or more derived values. MVAModelType is formally defined in Table 115

All MVAModel Variables are located in the ChemometricModelSettings FunctionalGroup on a Stream. It may also be located ChemometricModelSettings FunctionalGroup on the AnalyzerDevice if they are used only in the context of the prediction service.

Table 115 – MVAModelType Definition

Attribute		Value
BrowseName		MVAModelType
IsAbstract		True
References	NodeClass		BrowseName	DataType	TypeDefinition	ModellingRule
Subtype of the ChemometricModelType defined in ADI specification
HasProperty	Variable		MainDataIndex	Int32	PropertyType	Mandatory
HasOutput	Variable		<User defined Output#>	-	MVAOutputParameterType	OptionalPlaceholder

MainDataIndex is the index of the Inputs parameter that is used as MainData for the source timestamp. All derived / predicted data will have this timestamp.

The output parameter descriptions, referred by HasOutput ordered references, shall appear in the same order as the Outputs array of the MVAPredict method. It shall be possible to use these parameters directly without having to do intermediate mathematic or method call.

Table 116 summarizes constraints on Variable Attributes for MVAModelType.

Table 116 - Setting OPC UA Variable Attributes for MVAModelType

Attributes/Properties	Description
Value	Binary blob containing all elements of the chemometric model
DataType	ByteString
ValueRank	Always set to -1 (Scalar)
ArrayDimensions	Not applicable

A.16.1 MVAOutputParameterType

The MVAOutputParameterType describes output paramaters of the MVAModelType and MVAPredictMethodType.

MVAOutputParameterType is formally defined in Table 117.

Table 117 – MVAOutputParameterType Definition

Attribute		Value
BrowseName		MVAOutputParameterType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	ModellingRule
Subtype of the DataItemType defined in [OPC 10000-8]
HasProperty	Variable		WarningLimits	Range	PropertyType	Optional
HasProperty	Variable		AlarmLimits	Range	PropertyType	Optional
HasProperty	Variable		AlarmState	AlarmStateEnumeration	PropertyType	Mandatory
HasProperty	Variable		VendorSpecificError	String	PropertyType	Optional
HasComponent	Variable		Statistics	MVAOutputParameterType []	BaseDataVariableType	OptionalPlaveholder

WarningLimits and AlarmLimits describe the ranges used to determine the acceptable limits of the resulting numerical MVAOutputParameter value. These values shall be set for numerical values.

In terms of automation, if value is:

value ˂ AlarmLimits.Low → ALARM_LOW

WarningLimits.Low ≤ value ˂ AlarmLimits.Low → WARNING_LOW

WarningLimits.Low ≤ value ≤ WarningLimits.High → NORMAL

WarningLimits.High ˂ value ≤ AlarmLimits.High → WARNING_HIGH

AlarmLimits.High < value → ALARM_HIGH

AlarmState describes if the resulting MVAOutputParameter value is acceptable for example within the value limits. However, a value may be between the limits and still be in alarm due to other model consideration or for example, if a classification model is not able to classify a given sample.

Table 118 – AlarmStateEnumeration Values

Value	Description
NORMAL_0	Normal
WARNING_LOW_1	In low warning range
WARNING_HIGH_2	In high warning range
WARNING_4	In warning range (low or high) or some other warning cause
ALARM_LOW_8	In low alarm range
ALARM_HIGH_16	In high alarm range
ALARM_32	In alarm range (low or high) or some other alarm cause

The Statistics is an array of statistics generated at the same time as the MVAOutputParameter that qualifies it.

The VendorSpecificError contains detailed vendor specific error message explaining the alarm state.

The DataType attribute of MVAOutputParameter may be:

AnalogItemType for scalar value or unstructured array. In this case, WarningLimits and AlarmLimits shall be set. EngineeringUnits should be set.
ArrayItemType subtype if parameters like spectrum.
DataItemType for String

A.16.1.1 Good practices for MVA input and output parameters

It is strongly recommended to express MVAModel parameters in terms of high level types, for example, a spectrometer produces spectra that are YArrayItemType. The address space should expose a single parameter for it rather than N scalar values where N is the number of data points in the spectrum. This may imply that models shall be built using some convention rules, but doing so, really simplify the interaction with the prediction service of the ADI server. For example:

If all scalar variables defining an YArrayItemType are prefixed with something like "NIR_", then the SetConfiguration, LoadModel may easily detect it and create the right parameter type.
Use a convention where the first variable is the MainData variable or prefixing the MainData variable variables with the "MainData_" prefix may help to automatically find the MainDataIndex.

The Predict method should be able to extract the required range from a high level type input parameter. For example, if the input parameter is a spectrum with a X axis range of 400cm-1 to 5000cm-1, it shall be possible to pass a spectrum with a range of 200cm-1 to 6000cm-1 to the Predict method and the Predict method shall be able to extract the right region.

To guarantee the correctness of the predictions, the server should apply some validation rules to verify that the input parameters are compatible with the model, for example, for spectral data, the validation may include:

The alignment of the sampling grid of spectral data shall be compatible with the model.
The spectral range of the input spectrum is wide enough to cover the range expected by the model.

Inputs and Outputs parameters shall not be a brutal dump of the API of the vendor predictor, but rather express in terms of what an end user needs to see. It does not forbid exposing the API structures, but often these structures are very difficult to use for "process clients" like DCS or SCADA.

A.16.2 MVAPredictMethodType

All MVAModels may be predicted directly by calling the MVAPredict method described in Table 119.

Table 119 - MVAPredictMethodType

Method	Description
MVAPredict	Predict Outputs using the TargetModel against these Inputs.
	InputArguments
	Name	dataType	ValueRank / arrayDimension	Description
	TargetModel	NodeId	-1[0]	NodeId of the MVAModel to be predicted.
	MainDataIndex	Int32	-1[0]	Index of the Inputs parameter that is used as MainData for the source timestamp.
	Inputs	ObjectType	1[x]	Input parameters as defined by Inputs.
	OutputArguments
	*Name*	*dataType*	*arraySize / arrayDimension*	*Description*
	Outputs	ObjectType	1[x]	Output parameters as defined by Outputs.

All fields of each Inputs and Outputs arguments must be filled, the user relies on them to discover the model information.

The vendor specific predictor return code should be returned using the DiagnosticInfo.SymbolicId.

The role of the MVAPredict method is really to allow a client to predict against the target MVAModel. The MVAPredict method:

May be called at any time after the AnalyserDeviceStateMachine reaches the Operating state if the MVAModels are located in the ChemometricModelSettings located at AnalyserDevce level. Potential conflicts with AnalyserChannel operations like loading configuration shall be handled by the implementer following the rules describe below.
May be called at any time after the AnalyserChannel reaches the Idle state, during Idle, Starting and Execute state, if the MVAModel are attached to a given Stream. This will avoid potential conflicts with AnalyserChannel operations like loading configuration.
May be called more than once concurrently by the same client.
May be called concurrently by more than one client at the same time.
Shall produce output MVAOutputParameters that may be used directly without having to do intermediate mathematic or method call.

This is the server responsibility to deal with multi-threading issues. The client side shall never have to deal with these issues. It is perfectly legal to serialize all requests on a given model and even at the Predictor level, as long as the client does not have to be aware of it.

The MVAPredict method Executable and UserExecutable attributes shall be used to signal when MVAPredict may be called or not.

The implementer may allow some MVAModels to be updated directly by writing the Value attribute of the MVAModel. For example, let say that the Value attribute is an exact copy of the model file, the client application only has to use the OPC UA Write service to transfer the model directly to the UA server. If the model is too large to fit in a single UA message, the model may be transferred in chunk using the NumericRange parameter of the Write service.

All ADI time management rules apply:

All output parameters shall have the same timestamp as the main parameter, the one defined by MainDataIndex.

To avoid unexpected behaviours, the following rules must be applied when models are updated with the Write service:

ADI server shall verify the integrity / validity of the Model ByteString and returned an error code if not correct without modifying anything in the actual server configuration. If the model is transferred in chunks, the final verification shall be done on the write of the last chunk.
ADI address shall be updated to reflect the new model.
ADI server shall handle multi-threading issues where a GetConfiguration, SetConfiguration GetConfigDataDigest and others, while updating the models. This may be done by serializing the requests as long as the client does not have to be aware of it.
ADI server shall return the vendor specific predictor return code using the DiagnosticInfo.SymbolicId.

If the MVAModel is used to evaluate values appearing in any AcquisitionData FunctionalGroup, the following supplemental rules must also be applied:

MVAModel objects may only be updated when the AnalyserChannel is in Stop state.
ADI server shall update/change the Configuration and the ConfigDataDigest if the new model is different from the previous one and only in that case.