How to Write Custom Workspace Nodes
A custom workspace node requires two files, an *.svx file that defines the operation of the node, and a *.dmi file that defines the node’s user interface. Both files should have the same file name; only the file extension should be different.
The *.svx File
The *.svx file must contain a sub-routine with the following signature, i.e., name and parameter list:
Sub AnalysisNode(dataIn() As InputDescriptor, _
ByVal reportDocs As StaDocCollection, _
dataOut() As InputDescriptor)
The sub-routine name and parameter types must be as shown above. The parameter names can be different.
The first parameter is an array of InputDescriptor objects. Each InputDescriptor has a r;DataSource member; that is an object of type r;InputSpreadsheet. An InputSpreadsheet object can be a regular Statistica Spreadsheet or it can be a Streaming Database Connector.
When a node is embedded in a Workspace, that node’s AnalysisNode() sub-routine is called at run-time. The InputDescriptor array is passed into the AnalysisNode() sub-routine. This array has one or more InputDescriptor objects, each containing a spreadsheet with output from the previous node in the Workspace.
The second parameter is a StaDocCollection object. This object is used to collect the results, from any node, that are destined to be displayed in the overall Workspace results. At run-time, the StaDocCollection object will be passed into the AnalysisNode() sub-routine. Your custom node should place into that StaDocCollection any output intended to be displayed in the overall Workspace results.
The third parameter is also an array of InputDescriptor objects. The objects in this array will be the output of this AnalysisNode. They will be made available to the next node in the Workspace. In other words, the third parameter in this node (DataOut) will be passed to the AnalysisNode() sub-routine of the next node as the first parameter (DataIn),(the output of this node becomes the input of the next node).
However, unlike the objects of the first two parameters, this array is not created elsewhere, and then passed into the AnalysisNode() sub-routine at run-time. Instead, this AnalysisNode() sub-routine must create the array of InputDescriptor objects named DataOut().
Following is an example that calls a function stats(), not shown here, that contains recorded SVB code to calculate descriptive statistics:
'#Uses "*CommonDataMinerInputErrorMessages.svx"
Option Base 1
'Standard SVB workspace node API.
'dataIn: collection of input objects.
'reportDocs: collection into which output objects should be
' placed to be displayed in output workbook.
'dataOut: collection into which output objects should be
' placed to be available for downstream analysis.
Sub AnalysisNode(dataIn() As InputDescriptor, _
ByVal reportDocs As StaDocCollection, _
dataOut() As InputDescriptor)
'Get variable to analyze from node UI.
Dim strVarIndex As String
strVarIndex = Dictionary("VarIndex")
Dim i As Long
Dim ssInput As Spreadsheet
Dim ssOutput As Spreadsheet
'Process each input object.
For i = LBound(dataIn) To UBound(dataIn)
'Calc descriptive stats.
Set ssInput = dataIn(i).DataSource
Set ssOutput = stats(ssInput, strVarIndex)
'Put results into output workbook
reportDocs.Add(ssOutput)
'Make results available for downstream analysis.
Dim idOut As New InputDescriptor
idOut.DataSource = ssOutput
ReDim Preserve dataOut(i) As InputDescriptor
Set dataOut(i) = idOut
Next i
End Sub
The code loops through all objects in the dataIn() array, and references the spreadsheet inside each InputDescriptor object using the DataSource member. That spreadsheet is then passed into the stats() function as input to a descriptive statistics analysis. The descriptive statistics results are returned as the spreadsheet ssOutput.
The ssOutput spreadsheet is then added to the reportDocs collection. That makes it part of the overall Workspace output.
Finally, the ssOutput spreadsheet is made available for processing by the next node in the Workspace. To do that, we must first create a new InputDescriptor object, and set that InputDescriptor object’s Data Source to be ssOutput. Then we re-size the dataOut() array to make room for another InputDescriptor object. And finally, we add the new InputDescriptor object, containing ssOutput, to the dataOut() array.
In this example, the stats() function calculates descriptive statistics. But that is incidental. Any function, with any type of analysis, can be used instead.
The *.dmi File
The *.dmi file is a text file that defines the user interface displayed when the user double-clicks on the node. The parameters defined in the *.dmi file can then be used by the *.svx code to read which options were selected by the user.
For example, in the SVB code above, you see the following:
'Get variable to analyze from node UI.
Dim strVarIndex As String
strVarIndex = Dictionary("VarIndex")
This is where the SVB code reads the input spreadsheet variable index specified by the user in the node UI. It is used as the input spreadsheet variable for which the descriptive statistics are calculated.
The Dictionary() function reads the contents of a UI object. The name of that UI object is specified in the *.dmi file.
The node UI looks like this:
Following is the corresponding *.dmi code, along with descriptive text in red, that describes what various lines in the *.dmi file means.
[NODE]
TYPE=2
NAME="CustomDescStats" (name of Workspace node)
MACRO="CustomDescStats.svx" (*.svx file to which this *.dmi file corresponds)
[PARAM1]
NAME=VarIndex (Dictionary parameter used by *.svx file to retrieve parameter value)
TYPE=Integer (type of parameter)
INITIALVALUE=1 (initial value of parameter)
LONGNAME="Index of variable to analyze" (descriptive parameter name shown in UI)
USERACCESS=READWRITE (specify read and/or write access)
Now we see the significance of the Dictionary function call in the *.svx file:
strVarIndex = Dictionary("VarIndex")
"VarIndex" is the name of a UI object specified in the *.dmi file.
Let’s take a closer look at the various *.dmi file options.
[NODE]
This section of the .dmi file contains information about the nature of the node:
TYPE = { k }
{ INPUTSPREADSHEET }
{ ANALYTIC }
{ INPUTDESCRIPTOR }
{ FILTER }
{ MERGEDATA }
This keyword describes the type of the node, i.e., the types of input arguments that are required by the respective node. The different types of nodes are described in the section on Nodes and Scripts: Input and output arguments for different types of nodes. You can either specify a value for k as shown below or use one of the keywords:
• 1 or INPUTSPREADSHEET - Input spreadsheet node (can only be used by Statistica)
• 2 or ANALYTIC - Analytic node for single or multiple data sources
• 3 or INPUTDESCRIPTOR - Input descriptor generator node
• 4 or FILTER - Data cleaning, filtering, and drilling node; or Merge-data node
NAME="Name"
This keyword describes the name of the node; this name will be used in the Node Browser to identify the node, and also in the Workspace to label the respective icon.
GROUP="Group Name"
This keyword describes the name of the group of nodes in the Node Browser, where this node should be displayed. In the current implementation of Statistica, this parameter is ignored, and the group of nodes where a particular node will be displayed is determined from its placement in the subdirectory structure of the Node Browser.
ICONFILE="Full or relative path to .ico file" or
ICONANALYSISID=STATISTICAAnalysisID
These keywords define the icon to be associated with the respective node. You can either specify a relative path name to an icon file (file name extension .ico; use this method to attach your own custom icon to a node), or you can specify one of the enumerated IDs for Statistica analyses, available in the Statistica Visual Basic Object Browser ( ICONANALYSISID=scBasicStatistics); in the latter case the icon for the respective type of analysis (module) will be used in the Workspace to identify the icon.
MACRO="Name of .svx file"
This keyword identifies the .svx script that is described by the current module .dmi file.
LONGDESC="Long description or help for the node"
The text used in conjunction with this keyword will be used in the Node Browser to describe the respective node.
SHORTDESC="Short description or help for the node"
This keyword is currently not used; enter a short description or label for the type of analysis or computations performed by the respective node.
[PARAMk]
The keywords and parameters in these sections can be used to set default parameter values for analyses performed by the respective nodes, define valid parameter ranges, and so on. The definitions in this section are also used for the interactive dialog boxes that enable the user to change certain parameter settings for the respective analysis or type of computation.
Each of the k parameters that can be modified by the user can be specified and further defined in the following manner. First make a new section for each parameter; for example, for the first parameter you want to define, make a section header [PARAM1]; for the second parameter in the respective analysis that you want to specify make another section header [PARAM2], and so on. For each section, the following keywords can be specified (in any order):
NAME = NameOfParameter
Required; specify a name for the Parameter; this name will be used in the interactive user interface for changing this parameter; and inside the script to set and/or retrieve the parameter.
TYPE = "Type"
Optional; specify the type of value that is to be used for this Parameter in the DictionaryObject; the default type is Double; will be used for data verification in the interactive user interface for changing this parameter; all valid data types can be specified, including String or arrays.
INITIALVALUE = Value
Required; specify the default value that is to be used for this Parameter in the DictionaryObject.
ENUM = "k1 Constant1 | k2 Constant2 | .... | kn ConstantN"
Optional; specify here the valid settings for enumerated constants ( for parameters such as casewise vs. pairwise deletion of missing data, types of fit, etc.);
MIN = MinimumPermissibleValue
Optional, specify the minimum permissible value for this Parameter (Parameter>=MinimumPermissibleValue); will be used for data verification in the interactive user interface for changing this Parameter.
MAX = MaximumPermissibleValue
Optional, specify the maximum permissible value for this Parameter (Parameter<=MaximumPermissibleValue); will be used for data verification in the interactive user interface for changing this Parameter.
LONGNAME = "Long Name of parameter"
Required; specify descriptive name for the Parameter; this name will be used in the interactive user interface as the prompt, for changing this parameter.
DESCRIPTION = "Description of parameter"
Optional, specify a long description for the Parameter; this name will be used in the interactive user interface to provide additional help.
USERACCESS = { READWRITE }
{ READONLY }
{ HIDDEN }
Optional; specify the type of access that the user of the node will have to the respective parameter; the default value is READWRITE, in which case the user can review and change the parameter via the parameter dialog box for this node; if READONLY is specified, the user can only review, but not modify the values for the parameter; if HIDDEN is specified, the user can neither review not change the parameter via the parameter dialog box for this node. This optional keyword is useful for example when you want to be able to show the ( remote) user the values for a parameter (e.g., specifications for a quality control chart), but not allow the user to change those parameters. The HIDDEN designation may be useful, for example, in educational settings when you want to give students access to only selected capabilities of the respective node.
Deploying the Workspace Node
Once you have created the *.svx and *.dmi files, you must deploy them so they can be used in Statistica workspaces. The requires the following steps:
