Skip to main content
RSS feed Subscribe to feed

 

Skip Navigation LinksHome  Extending the Spotfire Platform  Common Tasks and Idioms  Spotfire Statistics Services Primer (C#)  Spotfire Statistics Services Function Client

©Spotfire 2011

Spotfire Statistics Services Function Client

Code example explaining how to use Spotfire Statistics Services Function Client C# API.

Overview

You can use the Function Client API to call S functions on the S engine on the server, and then examine the results (returned in the SplusDataResult object).

Note: The Function Client API is designed specifically for calling user-created S functions through Spotfire Statistics Services. It does not handle unnamed arguments, and all parameters are passed to the function as strings. The user functions should be written with these constraints in mind and the functions should coerce the parameters to desired data types as necessary. To execute arbitrary expressions, use the Expression Client API.

The Function Client API contains four overloads of the Eval() function to provide flexibility in sending jobs to the server:

  • You can run the job, passing the function name, the name of the package that contains it, any specific parameters, its data set, and instructions to run it immediately or asynchronously.
  • You can run an asynchronous job, specifying a date and time to begin the run. If an engine is available in the engine pool, the job runs at the specified time. (After the job has run, you can use the job ID, returned in the SplusDataResult object, to find the results.)

For either of these options, you can pass an SplusDataRequest object containing a list of S-PLUS objects and/or encapsulated data for input arguments for evaluation. This option does not require reading data from a server repository.

When you run a sychronous job, the server returns an SplusDataResult object containing data, a path to any image, text, any errors or warnings, and (optionally) detailed log files.

When you run an asynchronous job or a scheduled job, the server returns an SplusDataResult object containing only the job ID and status.

Creating a Function Library or Package

The Function Client processes only one function at a time, and the function must exist in a library on the server. Most of the time, you will probably want to perform a series of tasks on a data set, including importing the data, cleaning it, modeling it, and graphing the results of your analysis.

  1. Using the Spotfire S+ console, the Spotfire S+ Workbench or GUI, write and test your functions. Then wrap your functions in one function, and create a library or a package to contain your wrapper function.
  2. Use UpdatePackageVersion to upload your package to the package repository.
  3. Work with your server administrator to add your package to the engines' initialization scripts, so it is loaded when the engine starts.
  4. Design a .NET application that calls your function in Visual Studio. When the application calls Eval() to run your function, it should identify your library or package name in the packageName argument:
    SplusDataResult res = api.Eval("myfunction", "mypackage", "myfunctionparam", "mydataset", true);

Example

  1. Set the path to the server and authentication credentials:
    string serviceUrl = "http://localhost:8080/SplusServer";
    string username   = "myusername";
    string password   = "mypassword";
  2. Create the FunctionClient object:
    IFunctionClient client = ClientFactory.GetFunctionClient(serviceUrl, username, password);
  3. Evaluate the function myfunction in package mypackage with the named inputs. This would be equivalent to the S-PLUS expression myfunction(x=c("1","2","3"), y=c("x", "y", "z"))
    client.Eval("myfunction", "mypackage", 
             new Dictionary() { 
               { "x", new string[] {"1", "2", "3"} }, 
               { "y", new string[] {"x", "y", "z"} }
             }, 
             new SynchronousJobStartup(3000));
  4. Return error or warning, if necessary:
    if (job.HasWarnings)
    	Console.WriteLine("Warnings: " + job.Warnings + "\n");
    if (job.HasError)
    	Console.WriteLine("Error: " + job.Error + "\n");
  5. Examine any console text output (for example, logs):
    if (job.HasTextOutput)
    	Console.WriteLine(job.TextOutput + "\n");

See also: