Fix version tag
This repository offers a generic Business Operation for leveraging predictive models expressed in PMML in your Interoperability productions. See below for a description of the utility code or skip through to the sample.
If you're not familiar with PMML, you can read more about it here and on how InterSystems IRIS supports it here.
If you already have a PMML model in some
MyModel.pmml file, here's the TL;DR:
USER> do ##class(%DeepSee.PMML.Utils).CreateFromFile("/path/to/MyModel.pmml","Demo.MyModel") ...
USER> set data("Feature1") = 123, data("Feature2") = "abc", ...
USER> do ##class(Demo.MyModel).%GetModelInstance(.model)
USER> do model.%ExecuteModel(.data, .output)
USER> zwrite output
Running PMML models natively in an InterSystems IRIS Business Process has of course always been the goal of our PMML support, but somehow never made it into the kit because there were a few dependencies and choices that needed addressing and answering. Anyhow, thanks to some pushing and code snippets from @amirsamary, we finally got it wrapped in a GitHub repo for your enjoyment, review and suggestions.
The utility classes in this repo offer two ways to invoke PMML models from a BO.
The generic BO class
PMML.Interop.BusinessOperation is just that: a generic BO. If you include it in your production, you have to supply a value for its
PMMLClassName setting, which should refer to the classname of a valid PMML definition class (inherit from
PMML.Interop.GenericRequest object allows specifying the name of the model to use (in case your PMML definition has more than one) and has a generic array in which you can dump all the model input values. This means that in the Assign steps, you'll have to supply a key that corresponds to the model input name, which is slightly less convenient for large or complex models. The
PMML.Interop.GenericResponse object has the main predicted value straight as a property, but also includes an array holding all the other output fields produced by the model, upon succesful completion of the model code.
If you're not entirely limited to SMP access to your instance (in which case the above is your only option right now), you can use the
PMML.Interop.Utils class to generate a dedicated BO and corresponding request and response message classes for your PMML models. While an extra step, having those request and response messages refer to your input and output field names directly is a great help when using the request builder. To generate these classes, simply call
This will create the corresponding operation and message classes in the same generated package as the other PMML artefacts (overwriting existing entries).
⚠️ Note that the BO generation mechanism requires a few serialization enhancements to the core PMML support in IRIS that are only packaged with IRIS 2019.1. If you want to work with an earlier version, please stick to the generic
This repo includes a full example production showcasing how you can invoke both the generic and a generated BO for PMML models. It leverages a simple demo PMML file gratefully borrowed from dmg.org, the site hosting the PMML specification. The PMML file contains two tree models predicting whether it's a good idea to go golfing based on simple weather inputs.
The sample code included in the Demo package consists of the following classes:
MyGolfModel.pmmlis the raw PMML model definition containing two dummy decision trees. Note that the corresponding
%DeepSee.PMML.Definitionclass is, nor the artefacts generated by PMML.Interop.Utils are included on the repo. See below for instructions on how to generate those.
To install and use the sample, follow these steps:
Import and compile all this repo's classes into an Interoparability-enabled namespace. Don't bother about the compile errors you might see from the BPL or Production class, as they refer to classes we're about to generate.
Alternatively, use the ZPM installation:
INTEROP> zpm zpm: INTEROP>load /path/to/isc-pmml-utils
[pmml-utils] Reload START
[pmml-utils] Reload SUCCESS
[pmml-utils] Module object refreshed.
[pmml-utils] Validate START
[pmml-utils] Validate SUCCESS
We first need to import the raw
MyGolfModel.pmml file and create a PMML definition class in IRIS. This is taken care of if you chose to install through ZPM.
w ##class(%DeepSee.PMML.Utils).CreateFromFile("/path/to/src/pmml/MyGolfModel.pmml", "Demo.SampleModels.GolfModel")
We now want to generate a dedicated BO for our PMML model, as used in the Production. This is also taken care of if you chose to install through ZPM. Please mind the class name argument or change the corresponding references in the production correspondingly.
We're done setting up! Now it's just about testing our production:
Demo.WeatherRequestobject, invoke the testing service and admire the simple yet clear logging through the Visual Trace capability.
Don't hesitate to open issues or shoot me an email if you run into trouble.
Fix version tag
Added ZPM support & improved documenation & repo structure