Model Exporter Interpreter

The Model_Exporter Interpreter consists of two main versions, one for Microsoft .NET and one for Java. Both of these versions provide classes to apply Model_Exporter models to new data. The Interpreter can be used in any of these environments and includes all source files:

• Java
• Microsoft .NET environments (VS2012 or later)
• Generic C#-based compilers

The following describes the classes implemented and their use. The classes include the ModelInterpreter, Workspace, and Matrix classes.

The ModelInterpreter class allows a software developer to indicate an exported model they want to make predictions with and the data that they want to make predictions from. They can then apply the model and access the prediction results. The other two classes (Matrix and Workspace) are used by ModelInterpreter and are available to the software developer to manage numerical data.

The source code for these classes is supplied with Model_Exporter and can be used, compiled, and redistributed without restriction. Note that such redistribution permission does not permit the user to redistribute the Model_Exporter product itself - only the interpreter.

Microsoft .NET Interpreter

The following is a description of the .NET ModelInterpreter implementation, describing the classes and methods available. This implementation can also be used with generic C#-based compilers.

ModelInterpreter Class

The primary class in the Model_Exporter Interpreter is a ModelInterpreter object. The object's interface implements the ability to assign input data, specify a model to interpret and apply, and retrieve results from the application. Input data and results are all stored using the Matrix class described below.

Constructors

ModelInterpreter(String filename)

This form of the constructor method allows passing a filename of a Model_Exporter XML file which should be read and parsed for application.

ModelInterpreter(XmlDocument xdoc)

This form of the constructor method allows passing a XmlDocument object which contains the contents of a Model_Exporter XML file. This method may be preferred when the content of an exported model has been previously read and stored in another location like a database. In such cases, the alternative ways to create XmlDocuments (see the XmlDocument documentation) which can be used to pass the parsed XML contents directly to the ModelInterpreter class.

Methods

apply()

Applies the model to the inputdata and stores results in the results property. This method has no return value itself. An error is thrown if inputdata has not already been assigned.

Properties

Read-Only Properties
inputDataSize	(Int32) The number of columns expected for the inputdata matrix.
modeltype	(String) The model type of the model. One of the supported model types such as: "PCA" "PLS" "PCR" "CLS" or "PLSDA" (or other supported model types) This often helps identify what variables are of interest in the results workspace after application of the model.
information	(XmlDocument) The raw, unparsed XML contained in the information section of the model. This may be of interest to help identify where the model came from, what the model is predicting, how many outputs to expect, etc. See the exported model's <information> tag for details included.
results	(Workspace) The workspace object that contains all the results after applying the model. This contains all the variables (see Workspace class below) that were used during model application as well as the variables which hold the results of interest such as yhat, T2, or Q. In particular, the results available from a model prediction will be present as variables in the script's workspace. The user is responsible for making use of these variables as needed. The list of output variables is the same as those listed under the M-file format description.
Read/Write Properties
inputdata	(Matrix) Specifies the data to which the model should be applied. Type is Matrix as defined using the Matrix class described below. This field is not modified by applying the model. Assigning a new value this field erases the results from a previous model application.

Examples

The following C# example shows use of the ModelInterpreter class along with the Matrix and Workspace classes (described below). It start by creating a new ModelInterpreter object loading the model contained in plsexample.xml. It then creates a Matrix object with a vector of value from 1 to the number of variables expected by the model, stores this matrix in the inputdata, and applies the model. Finally, it retrieves the results from that model by listing ALL workspace contents. Alternatively, the commented-out code shows how the typical PLS (or other regression model) results would be retrieved specifically.

 ModelInterpreter test = new ModelInterpreter("plsexample.xml");

 //display some of the common model information
 Console.WriteLine("Model type: " + test.modeltype);
 Console.WriteLine("Expected Data Size:" + test.inputDataSize);

 //create data to pass to the model
 Matrix inmatrix = new Matrix(1, test.inputDataSize);
 for (int i = 0; i < inmatrix.NoCols; i++) { inmatrix[0, i] = i + 1; };
 test.inputdata = inmatrix;

 //set data and apply model           
 test.inputdata = inmatrix;     //assign input data to object
 test.apply();  //apply model

 //Typical outputs for a PLS or other regression model:
 //Console.WriteLine("yhat = " + test.results.getVar("yhat"));
 //Console.WriteLine("T2 = " + test.results.getVar("T2"));
 //Console.WriteLine("Q = " + test.results.getVar("Q"));
               
 //List ALL contents of workspace      
 foreach (String name in test.results.varList)
 {
   Console.WriteLine(name + " = \n" + test.results.getVar(name));
 }

Typical Outputs

Models output a number of variables in the workspace. Typical outputs are described in the m-file description in the main Model_Exporter page.

Workspace Class

The Workspace class serves as a way to store any number of matrices (Matrix objects) each associated with a name. These names and their corresponding matrix are referred to as a "variable". A variable is stored in the workspace using the setVar() method and retrieved using the getVar() method.

Note that although variables names can contain upper- and lower-case characters, the case is ignored when retrieving. Thus, a variable set using the name "Pred" can be set or retrieved using "Pred", "pred", or any other combination of upper- and lower-case. Since these two would be considered the same variable, you cannot set two different variables which are identical except for the case of the variable name.

Constructors

Workspace()

Creates an instance of the Workspace class.

Methods

The following methods are defined for the Workspace class. These are the primary means for assigning and retrieving values from a Workspace.

setVar(String name, Matrix value)	Sets the variable specified by name with the matrix value. If name already exists in the workspace, the previous value is overwritten without any warning. This method returns nothing. void setVar(String name, Matrix value)
setVar(Workspace toadd)	Copies all variables in the toadd workspace into the workspace being addressed by the method. Any variables in the current workspace which have the same name as a variable in the toadd workspace are overwritten without warning. This method returns nothing. void setVar(Workspace toadd)
getVar(String name)	(Matrix) Retrieves the specified variable name from the workspace. Returned value is a Matrix object. Matrix getVar(String name)
isSet(String name)	(Boolean) Returns boolean TRUE if the given variable name is currently set in the workspace. Boolean isSet(String name)
clearAll()	Clears all values from the workspace. This method returns nothing. void clearAll()

Properties

varList

(List<String>) Returns the alphabetically sorted list of names for all variables currently set in the Workspace as a List<String> type. These names can be used with the getVar method to retrieve the values.

Examples

The following example creates a new empty Workspace called "ws", a new Matrix (in this case, a vector with 1 row and 5 columns) called "myvalue", then stores myvalue into ws under the variable named "x". It then looks

 Workspace ws = New Workspace();    //create new workspace
 Matrix myvalue = New Matrix(1,5);  //create all-zeros matrix "myvalue" as exmple
 ws.setVar("x",myvalue);            //assign variable "x" the value myvalue in workspace

Example of retrieving a variable from a workspace "ws"

 if (ws.isSet("y"))                 //is the variable "y" assigned?
 {
   retrieved = ws.getVar("y");      //get value assigned in y
 }
 else
 {
   retrieved = New Matrix(0,0);     //no "y" was set? use empty matrix instead
 }

Matrix Class

The Matrix class is defined through a public-domain class implemented in the cMatrixLib. This class allows storing and retrieval of data in a simple two-dimensional matrix as well as performing various matrix calculations on that data. For the purposes of the Model_Exporter Interpreter, the main use is to provide a convenient method to exchange data between the client and the interpreter. Thus, the details of the class are not given here, but only the main creation and access information. This class is used for the inputdata property and the variables stored in the results Workspace of the ModelInterpreter.

Constructors

Constructor for a new Matrix object is by either specifying the size (in rows and columns) for the new Matrix, or by passing an array of Double to the constructor:

Matrix(int rows, int columns)	Create a Matrix with the specified number of rows and columns. Matrix is initialized to all zeros. Note that rows = 0 and columns = 0 can be used to create an "empty" matrix. Matrix mymatrix = new Matrix(int rows, int columns)
Matrix(Double[,] data)	Create a Matrix from the Double array data using the sizes of that array. Matrix mymatrix = new Matrix(Double[,] data)

Methods

Changing and accessing values in a matrix can be accomplished using standard (zero-based) indexing.

 mymatrix[0,0] = value;   //replace element 0,0 with specified Double "value"
 value = mymatrix[0,0];   //retrieve value at element 0,0

Properties

To determine the size of a given matrix, use the NoRows and NoCols properties:

NoRows	(int) Returns the total number of rows the matrix object is currently dimensioned to contain.
NoCols	(int) Returns the total number of columns the matrix object is currently dimensioned to contain.

Examples

Below are some general examples of using the constructors, methods, and properties specified above. Other methods exist which are not indicated in this documentation. See also the examples given for the Workspace class above.

Create a matrix and populate it with some numbers:

 Matrix mat = New Matrix(3,5);
 For (int row=0; row<3; row++)
 {
   For (int col=0; col<5; col++)
   {
     mat[row,col] = row*10 + col;   //assigns values to indicated row/column
   }
 }

Retrieve value from row 2 column 4:

 Double value = mat[1,3];     //remember this is zero indexed

Display all elements of the first row of a matrix on the console:

 int ncols = mat.NoCols;
 For (int col=0; col<ncols; col++) Console.Write(mat[0,col] + "  ");

Java Interpreter

The following is a description of the Java ModelInterpreter implementation, describing the classes and methods available.

ModelInterpreter Class

The primary class in the Java Model_Exporter Interpreter is the ModelInterpreter class. The class interface allows the ability to assign input data, specify a model to interpret and apply, and retrieve results from the application. Input data and results are all stored using the JAMA Matrix class described below.

Constructors

ModelInterpreter(String filename)

This form of the constructor method allows passing a filename of a Model_Exporter XML file which should be read and parsed for application.

ModelInterpreter(org.w3c.dom.Document xdoc)

This form of the constructor method allows passing a org.w3c.dom.Document object which contains the contents of a Model_Exporter XML file. This method may be preferred when the content of an exported model has been previously read and stored in another location like a database. In such cases, the alternative ways to create org.w3c.dom.Document (see the org.w3c.dom.Document documentation) which can be used to pass the parsed XML contents directly to the ModelInterpreter class.

Methods

apply()

Applies the model to the myData Matrix and stores results in the myWorkspace Workspace property. This method has no return value itself. An error is thrown if myData has not already been assigned.

Properties

Read-Only Properties
inputDataSize	(Int32) The number of columns expected for the inputdata matrix.
modeltype	(String) The model type of the model. One of the supported model types such as: "PCA" "PLS" "PCR" "CLS" or "PLSDA" (or other supported model types) This often helps identify what variables are of interest in the myWorkspace workspace after application of the model.
information	(XmlNode) The raw, unparsed XML contained in the information section of the model. This may be of interest to help identify where the model came from, what the model is predicting, how many outputs to expect, etc. See the exported model's <information> tag for details included.
myWorkspace	(Workspace) The workspace object that contains all the results after applying the model. This contains all the variables (see Workspace class below) that were used during model application as well as the variables which hold the results of interest such as yhat, T2, or Q. In particular, the results available from a model prediction will be present as variables in the script's workspace. The user is responsible for making use of these variables as needed. The list of output variables is the same as those listed under the M-file format description.
Read/Write Properties
myData	(Matrix) Specifies the data to which the model should be applied. Type is Matrix as defined using the Matrix class described below. This field is not modified by applying the model. Assigning a new value this field erases the results from a previous model application.

Examples

The following Java code example shows use of the ModelInterpreter class along with the Matrix and Workspace classes (described below). It starts by creating a new ModelInterpreter object loading the model contained in plsexample.xml. It then creates a Matrix object with a vector of value from 1 to the number of variables expected by the model, stores this matrix in the inputdata, and applies the model. Next, it retrieves the typical PLS (or other regression model) results yhat, T2 and Q. Finally, it retrieves the listing of all workspace contents.

 ModelInterpreter test = new ModelInterpreter("plsexample.xml");
 
 //display some of the common model information
 String modeltype = test.getModelType();
 System.out.println("Model type: " + modeltype);
 System.out.println("Expected Data Size:" + test.getInputDataSize());
 
 //create data to pass to the model
 Matrix inmatrix = new Matrix(1, test.getInputDataSize());
 for (int i = 0; i < inmatrix.getColumnDimension(); i++) { 
   inmatrix.set(0, i, (i+1));
 };
 
 //set data and apply model            
 test.setInputData(inmatrix);
 
 //apply model
 test.apply();
 
 //Typical outputs for a PLS or other regression model:
 Workspace res = test.getResults();
 Matrix yhat = test.getResults().getVar("yhat");
 System.out.println("yhat = " + yhat.get(0, 0));
 Matrix t2 = test.getResults().getVar("T2");
 Matrix q  = test.getResults().getVar("Q");
 System.out.println("T2 = " + test.getResults().getVar("T2").get(0, 0));
 System.out.println("Q = " + test.getResults().getVar("Q").get(0, 0));
 
 //List ALL contents of workspace  
 for(String varname : test.getMyWorkspace().getVarList()) {
   System.out.println(varname + " = \n" + test.getMyWorkspace().getVar(varname));
 }

Typical Outputs

Models output a number of variables in the workspace. Typical outputs are described in the m-file description in the main Model_Exporter page.

Workspace Class

The Workspace class serves as a way to store any number of matrices (Matrix objects) each associated with a name. These names and their corresponding matrix are referred to as a "variable". A variable is stored in the workspace using the setVar() method and retrieved using the getVar() method.

Note that although variables names can contain upper- and lower-case characters, the case is ignored when retrieving. Thus, a variable set using the name "Pred" can be set or retrieved using "Pred", "pred", or any other combination of upper- and lower-case. Since these two would be considered the same variable, you cannot set two different variables which are identical except for the case of the variable name.

Constructors

Workspace()

Creates an instance of the Workspace class.

Methods

The following methods are defined for the Workspace class. These are the primary means for assigning and retrieving values from a Workspace.

setVar(String name, Matrix value)	Sets the variable specified by name with the matrix value. If name already exists in the workspace, the previous value is overwritten without any warning. This method returns nothing. void setVar(String name, Matrix value)
setVar(Workspace toadd)	Copies all variables in the toadd workspace into the workspace being addressed by the method. Any variables in the current workspace which have the same name as a variable in the toadd workspace are overwritten without warning. This method returns nothing. void setVar(Workspace toadd)
getVar(String name)	(Matrix) Retrieves the specified variable name from the workspace. Returned value is a Matrix object. Matrix getVar(String name)
isSet(String name)	(Boolean) Returns boolean TRUE if the given variable name is currently set in the workspace. Boolean isSet(String name)
clearAll()	Clears all values from the workspace. This method returns nothing. void clearAll()

Properties

getVarList

(List<String>) Returns the alphabetically sorted list of names for all variables currently set in the Workspace as a List<String> type. These names can be used with the getVar method to retrieve the values.

Examples

The following example creates a new empty Workspace called "ws", a new Matrix (in this case, a vector with 1 row and 5 columns) called "myvalue", then stores myvalue into ws under the variable named "x". It then looks

 Workspace ws = new Workspace();    //create new workspace
 Matrix myvalue = new Matrix(1,5);  //create all-zeros matrix "myvalue" as exmple
 ws.setVar("x",myvalue);            //assign variable "x" the value myvalue in workspace

Example of retrieving a variable from a workspace "ws"

 Matrix retrieved = null;
 if (ws.isSet("y"))                 //is the variable "y" assigned?
 {
   retrieved = ws.getVar("y");      //get value assigned in y
 }
 else
 {
   retrieved = new Matrix(0,0);     //no "y" was set? use empty matrix instead
 }

Matrix Class

The Matrix class is defined through a public-domain class implemented in the Jama package in the packaged Jama-1.0.3.jar file. This class allows storing and retrieval of data in a simple two-dimensional matrix as well as performing various matrix calculations on that data. For the purposes of the Model_Exporter Interpreter, the main use is to provide a convenient method to exchange data between the client and the interpreter. Thus, the details of the class are not given here, but only the main creation and access information. This class is used for the myData property and the variables stored in the myWorkspace Workspace of the ModelInterpreter.

Constructors

Constructor for a new Matrix object is by either specifying the size (in rows and columns) for the new Matrix, or by passing an array of Double to the constructor:

Matrix(int rows, int columns)	Create a Matrix with the specified number of rows and columns. Matrix is initialized to all zeros. Note that rows = 0 and columns = 0 can be used to create an "empty" matrix. Matrix mymatrix = new Matrix(int rows, int columns)
Matrix(Double[][] data)	Create a Matrix from the Double array data using the sizes of that array. Matrix mymatrix = new Matrix(Double[][] data)

Methods

Changing and accessing values in a matrix can be accomplished using standard (zero-based) indexing.

 mymatrix.set(0,0,value);     //replace element 0,0 with specified Double "value"
 value = mymatrix.get(0,0);   //retrieve value at element 0,0

Properties

To determine the size of a given matrix, use the NoRows and NoCols properties:

getRowDimension	(int) Returns the total number of rows the matrix object is currently dimensioned to contain.
getColumnDimension	(int) Returns the total number of columns the matrix object is currently dimensioned to contain.

Examples

Below are some general examples of using the constructors, methods, and properties specified above. Other methods exist which are not indicated in this documentation. See also the examples given for the Workspace class above.

Create a matrix and populate it with some numbers:

 Matrix mat = new Matrix(3,5);
 for (int row=0; row<3; row++)
 {
   for (int col=0; col<5; col++)
   {
     mat.set(row,col, row*10 + col);   //assigns values to indicated row/column
   }
 }

Retrieve value from row 2 column 4:

 double value = mat.get(1,3);          //remember this is zero indexed

Display all elements of the first row of a matrix on the console:

 int ncols = mat.getColumnDimension();
 for (int col=0; col<ncols; col++) System.out.print(mat.get(0,col) + "  ");