Solo Predictor Reference Manual

Introduction

Solo_Predictor, from Eigenvector Research, Inc. (EVRI) is a stand-alone model application engine which applies models created by PLS_Toolbox or Solo. Solo_Predictor features a simple and flexible scripting language, platform- and operating-system-independent interface, and an inherent distributed-computation design.

This documentation describes the setup and use of Solo_Predictor and explains the script language used to issue commands.

System Requirements

Solo_Predictor requires the following:

• Operating system:

• Windows 7, 8, 10
• MAC OS X (special request)
• Linux (Intel only)

• 1.5 MB Disk Space (64-bit)
• minimum recommended 100 MB RAM (32-bit) / 200 MB RAM (64-bit)

For Windows OS note that Solo_Predictor requires the Microsoft .NET Framework 3.5 is installed on the computer. This is often already present but if it is not then you will be prompted to download it during the Solo_Predictor installation process, which you can do if the computer is connected to the internet. The .NET 3.5 installer can also be downloaded from Microsoft (https://www.microsoft.com/en-us/download/details.aspx?id=21). Microsoft also offers an offline installer for .NET Framework 3.5.

Features and Supported Methods

Solo_Predictor is a prediction engine which supports importing of data and models from an external source, application of those models to the data, and retrieval of the values from the prediction. It supports predictions for all methods which produce standard model structures in PLS_Toolbox and Solo. This includes all methods in the Analysis GUI (including, but not limited to, PCA, PARAFAC, MCR, Purity, PLS, PCR, MLR, PLSDA, SIMCA), Calibration Transfer GUI, and any other PLS_Toolbox command-line functions which produce standard model structures.

Solo_Predictor also supports:

• All preprocessing methods available in the custom Preprocessing GUI.
• Missing data replacement (where supported by the model type)
• Variable pre-alignment to model (handles resampling, extra variables, missing variables)
• Importing all data types supported by the Analysis GUI and Workspace Browser (for details, see Data Importing Formats)

Note that Solo_Predictor does not support execution of custom, user-defined MATLAB® scripts or commands. Such functionality requires a full MATLAB license. Please contact Eigenvector Research for more information on using Solo_Predictor in a MATLAB environment or for creating a custom version of Solo_Predictor for your application.

Solo_Predictor can be connected through a socket interface using TCP/IP, through an ActiveX or .NET object, or operate in a wait-for-file mode. It can send results to a client and/or write to an output file. Solo_Predictor also maintains a text-based log file to aid with diagnosis of problems.

Interface Specifications

In this description of the Solo_Predictor interface, the term "client" refers to a user-specified application which is requesting a prediction and the term "server" refers to Solo_Predictor. The client is often a distributed control system (DCS) or other data collection software (instrumentation software, etc) but can be any application which needs to apply a multivariate model to data. In general, the client issues one or more commands to Solo_Predictor either by passing data or by describing where data can be retrieved from. Additional commands are passed to instruct Solo_Predictor how to process that data and what results should be returned. See the Scripting Language section for details on the scripting language used for the instructions.

There are three interfacing options:

• ActiveX / .NET Interfaces
• Wait-for-File Interface
• Socket Interface

The choice of interface depends on the operating system and software which will be interacting with Solo_Predictor. For example, on the Linux operating system, ActiveX and .NET interfaces are not available. It may also be easier for some users to use the ActiveX interface instead of the socket connection. The choice of interface is mostly dependent on the user who needs to connect into Solo_Predictor and that user's comfort level with the different interfacing technologies. Examples are linked below for each of the interfacing options.

ActiveX and .NET Interfaces

For client applications which cannot or do not want to use sockets, Solo_Predictor provides both an ActiveX and .NET suite of objects called EigenvectorTools which can communicate with Solo_Predictor without the client having to implement socket interface code. EigenvectorTools must be installed on the same computer as the client application, but Solo_Predictor can still be located on the same computer or on a separate computer (if the socket option is used). Please note that EigenvectorTools are only available on Windows. Other platforms must use Sockets or wait-for-file protocols to communicate with Solo_Predictor.

For information on using EigenvectorTools, see the help page EigenvectorTools. Note that although the EigenvectorTools page makes reference to accessing graphical user interfaces (GUIs), Solo_Predictor does not allow access to the GUIs. Only the creation of data objects and application of models is permitted.

Wait-For-File Interface

Solo_Predictor also offers a basic wait-for-file method of interface. This feature is designed for compatibility with legacy systems which may not offer flexible interfacing. It allows a client to trigger an analysis by simply dropping a readable file into a specified folder. Solo_Predictor can be configured to write a response file for the client to read the results of the analysis. For more information on this option, see the Script Construction section and the Installation and Configuration section.

Socket Interfaces

Solo_Predictor can operate using standard TCP/IP (Transmission Control Protocol/Internet Protocol) communications over "socket" connections. Sockets are available on all operating system platforms (Windows, Mac, Linux) and are the same technology used in most Intranet and Internet communications including http, ftp, and other familiar inter-computer systems. They are also used for some "plug and play" hardware devices. Simply put, sockets are a general method to pass messages between two programs.

Although socket connections are most often used between computers, they can also be used when the client and server reside on the same computer (and even when that computer is not networked). When connecting two programs on the same computer, sockets are similar to other familiar inter-program communication systems (e.g. DDE or Active-X) with these added advantages:

1. Sockets are completely platform independent. The same communication methods are used on all operating systems and hardware. They can also be used across mixed operating systems and platforms (e.g. Windows to Linux.)
2. Most modern languages have some sort of provision for socket communication and require no proprietary technology to implement.
3. Socket technology allows the client and server to be located on the same computer or separate computers connected by a network. The identical software and setup are used in both cases. The only modification needed is to provide a remote IP address or name for the server. As a result, sockets also inherently allow for distributed computation.

The procedure of communication over sockets is well described in many places. The basic procedure is:

1. The client opens a socket connection between the client and server. This requires knowing the IP address of the server's computer (use "loopback" or "127.0.0.1" if the server and client are on the same computer) and the port number on which the server is "listening."
2. The client sends a command to the server. The end of the message is indicated when no additional characters are available.
3. The server receives the command and performs some operation.
4. The server returns a response to the client often containing either a simple acknowledgement of the message or possibly some additional data or results.
5. The socket connection is closed.

The messages passed to Solo_Predictor are passed in plain text, but the ability to pass XML to describe some more complicated data types also exists. The response from Solo_Predictor can be in any of a number of formats including plain text, XML, JSON, or HTML. In addition, Solo_Predictor also permits some standard HTTP-format (i.e. web browser-style) input and output messages. For more information on the message format, see the "Scripting Language" section in this manual.

See Appendix C Solo Predictor Example Connection Code for socket-connection coding examples.

Most programming languages include functions or classes which simplify communicating over sockets using HTTP, for example Matlab's "webread" function, and this leads to simple client code. See for example.

End-of-Message Indicator Option

In some cases, a system has a high load (many programs running) or the messages being transferred are large. In these cases, the message transferred by the client may be broken up into smaller pieces. This may cause Solo_Predictor to believe the message is complete before it has received the entire message. In these cases, Solo_Predictor can be told to expect an end-of-message (EOM) character or string (e.g. "[EOM]") and it will wait to process a message until it sees that string arrive. See Incoming Message Format and Timeout Settings for how to set an EOM string.

POST Protocol Option

Solo_Predictor also accepts the common HTTP POST protocol for incoming messages. This format specifies the expected length of the message and, thus, allows messages to be split into segments because Solo_Predictor will not process the entire message until the received message is that length. See this external page for a simple example of the POST protocol format. Although standard POST format allows specification of different content types, the only Content-Type header which Solo_Predictor currently supports is text/plain. The following gives an example of a valid POST message for Solo_Predictor:

  POST . HTTP/1.0
  Content-Length: 15
  Content-Type: text/plain

  data='[1 2 3]';

Also note that outgoing messages from Solo_Predictor are never "chunked" (split into several pieces) nor do they ever use the POST format.

Single- and Multi-Client Servers

A given installation of Solo_Predictor can be configured to allow socket connections from a specific number of clients (see the "maxclients" configuration option) and can be limited as to what IP addresses are permitted to connect (see the "validip" configuration option).

When limited to a single client, Solo_Predictor will automatically identify itself ("imprint") with the first client computer that makes contact with it. After imprinting, only that computer will be able to send commands to the server. This is true if the client and server are on the same computer, or on separate computers. Solo_Predictor can only be reset to respond to another client by restarting the server.

When configured for 2 or more clients, more than one client can connect. Thus, a single Solo_Predictor can be installed on a centrally-located, networked computer and serve a number of clients on different computers (or multiple clients on the same local computer). Note that although multiple clients can make connections and request predictions, the following conditions are put into place:

1. Each client normally has its own workspace to store data and results. That is, one client cannot normally access the workspace of other clients. This can be disabled if, for example, multiple clients are contributing to the data used to make a prediction or when a remote client will be used to interrogate the workspace of another client. See the Installation and Configuration section for more information on workspace options.
2. In order to assure the fastest response for a given client, Solo_Predictor will only execute one client's request at a time. Any other clients that attempt to connect while the first request is being processed will be held in queue until Solo_Predictor is done with the given request.

Installation and Configuration

Installation and configuration of Solo_Predictor are described in the Solo_Predictor Installation and Configuration page.

Script Construction

Solo_Predictor provides a simple, flexible scripting language with which clients can send instructions to load data, apply a model to that data ("make a prediction"), and retrieve results. For details, see the page: Solo_Predictor Script Construction

Appendices

The following additional information is available about using Solo_Predictor:

• Appendix A: DataSet XML Format - describes XML format used to create DataSet objects.
• Appendix B: Solo_Predictor Script Commands Summary
• Appendix C: Solo_Predictor Example Connection Code|