Driverless AI k-LIME MOJO Reason Code Pipeline - Java Runtime

For completed MLI experiments, you can download the k-LIME MOJO. The k-LIME MOJO Reason Code Pipeline is a reason code engine that can be deployed in any Java environment to generate reason codes in real time.

The following steps describe how to download the k-LIME MOJO scoring pipeline.

  1. Run an interpretation with the k-LIME/LIME-SUP explainer recipe enabled. You can enable the k-LIME/LIME-SUP explainer recipe from the Completed Experiment page by clicking Interpret this model > With custom settings > Recipes.

  2. Navigate to the explanations page for the interpretation and click the Surrogate Models tab.

  3. Click Surrogates and Shapleys zip Archive to download a zip file that contains klime_mojo.zip.

Note

The k-LIME MOJO Reason Code pipeline does not support multinomial, natural language processing (NLP), and time series models.

Download k-LIME MOJO button

Prerequisites

The following are required in order to run the k-LIME MOJO reason code pipeline.

  • Java: The DAI MOJO runtime supports the following range of Java runtimes.

    • Minimum supported version: Java 8

    • Maximum supported version: Java 17

Note: It is recommended to use Java 11+ due to a bug in Java. (For more information, see https://bugs.openjdk.java.net/browse/JDK-8186464.)

  • Valid Driverless AI license. You can download the license.sig file from the machine hosting Driverless AI (usually in the license folder). Copy the license file into the downloaded mojo-pipeline folder.

  • mojo2-runtime.jar file. This is available from the top navigation menu in the Driverless AI UI and in the downloaded mojo-pipeline.zip file for an experiment.

License Specification

Driverless AI requires a license to be specified in order to run any DAI/MLI MOJO. The license can be specified with one of the following:

  • An environment variable:

    • DRIVERLESS_AI_LICENSE_FILE: Path to the Driverless AI license file, or

    • DRIVERLESS_AI_LICENSE_KEY: The Driverless AI license key (Base64 encoded string)

  • A system property of JVM (-D option):

    • ai.h2o.mojos.runtime.license.file: Path to the Driverless AI license file, or

    • ai.h2o.mojos.runtime.license.key: The Driverless AI license key (Base64 encoded string)

  • An application classpath:

    • The license is loaded from a resource called /license.sig.

    • The default resource name can be changed with the JVM system property ai.h2o.mojos.runtime.license.filename.

For example:

# Specify the license with a temporary environment variable
export DRIVERLESS_AI_LICENSE_FILE="path/to/license.sig"

k-LIME Reason Code Pipeline Files

The klime_mojo folder includes the following files/folders:

  • domains

  • experimental

  • model.ini

  • models

Quickstart

  1. On the completed MLI page, click on the Download k-LIME MOJO Reason Code Pipeline button.

Download k-LIME MOJO button

  1. To run the Java application for reason code generation directly, use the following command:

java -Dai.h2o.mojos.runtime.license.file=license.sig -cp mojo2-runtime.jar ai.h2o.mojos.ExecuteMojo klime_mojo.zip example.csv

k-LIME MOJO Command Line Options

Executing the Java Runtime

The following are two general examples of how the Java runtime can be executed from the command-line.

  • With additional libraries:

java <JVM options> [options...] -cp mojo2-runtime.jar:your-other.jar:many-more-libs.jar ai.h2o.mojos.ExecuteMojo path-to/pipeline.mojo path-to/input.csv path-to/output.csv

  • Without additional libraries:

java <JVM options> -jar mojo2-runtime.jar path-to/pipeline.mojo path-to/input.csv path-to/output.csv

  • For JDK >= 16, the following JVM argument must be passed:

java <JVM options> --add-opens=java.base/java.lang=ALL-UNNAMED -jar mojo2-runtime.jar path-to/pipeline.mojo path-to/input.csv path-to/output.csv

So, for example, the sys.ai.h2o.mojos.parser.csv.separator option can be passed with the following:

java -Dsys.ai.h2o.mojos.parser.csv.separator='|' -Dai.h2o.mojos.runtime.license.file=../license.sig -jar mojo2-runtime.jar pipeline.mojo input.csv output.csv

Similarly, the sys.ai.h2o.mojos.exposedInputs option can be passed with:

java -Xmx5g -Dsys.ai.h2o.mojos.exposedInputs=ALL -Dai.h2o.mojos.runtime.license.file= -cp mojo2-runtime.jar ai.h2o.mojos.ExecuteMojo pipeline.mojo example.csv

Note: Data can be streamed from stdin to stdout by replacing both the input and output CSV arguments with `-`.

JVM Options

  • sys.ai.h2o.mojos.parser.csv.keepCarriageReturn (boolean) - Specify whether to keep the carriage return after parsing. This value defaults to True.

  • sys.ai.h2o.mojos.parser.csv.stripCrFromLastColumn (boolean) - Workaround for issues relating to the OpenCSV parser. This value defaults to True.

  • sys.ai.h2o.mojos.parser.csv.quotedHeaders (boolean) - Specify whether to quote header names in the output CSV file. This value defaults to False.

  • sys.ai.h2o.mojos.parser.csv.separator (char) - Specify the separator used between CSV fields. The special value `TAB` can be used for tab-separated values. This value defaults to `,`.

  • sys.ai.h2o.mojos.parser.csv.escapeChar (char) - Specify the escape character for parsing CSV fields. If this value is not specified, then no escaping is attempted. This value defaults to an empty string.

  • sys.ai.h2o.mojos.parser.csv.batch (int) - Specify the number of input records brought into memory for batch processing (determines consumed memory). This value defaults to 1000.

  • sys.ai.h2o.mojos.pipelineFormats (string) - When multiple formats are recognized, this option specifies the order in which they are tried. This value defaults to `pbuf,toml,klime,h2o3`.

  • sys.ai.h2o.mojos.parser.csv.date.formats (string) - Specify a format for dates. This value defaults to an empty string.

  • sys.ai.h2o.mojos.exposedInputs (string) - Specify a comma separated list of input cols that are needed on output. The special value `ALL` takes all inputs. This defaults to a null value.

  • sys.ai.h2o.mojos.useWeakHash (boolean) - Specify whether to use WeakHashMap. This is set to False by default. Enabling this setting may improve MOJO loading times.

JVM Options for Access Control

  • ai.h2o.mojos.runtime.license.key - Specify a license key.

  • ai.h2o.mojos.runtime.license.file - Specify the location of a license key.

  • ai.h2o.mojos.runtime.license.filename - Override the default license file name.

  • ai.h2o.mojos.runtime.signature.filename - Override the default signature file name.

  • ai.h2o.mojos.runtime.watermark.filename - Override the default watermark file name.

JVM Options for Access Control

  • ai.h2o.mojos.runtime.license.key - Specify a license key.

  • ai.h2o.mojos.runtime.license.file - Specify the location of a license key.

  • ai.h2o.mojos.runtime.license.filename - Override the default license file name.

  • ai.h2o.mojos.runtime.signature.filename - Override the default signature file name.

  • ai.h2o.mojos.runtime.watermark.filename - Override the default watermark file name.

Execute the MOJO from Java

  1. Open a new terminal window. Create an experiment folder and change directories to that folder:

mkdir experiment && cd experiment

  1. Create your main program in the experiment folder by creating a new file called DocsExample.java (for example, with vim DocsExample.java). Include the following content:

import ai.h2o.mojos.runtime.MojoPipeline;
import ai.h2o.mojos.runtime.frame.MojoFrame;
import ai.h2o.mojos.runtime.frame.MojoFrameBuilder;
import ai.h2o.mojos.runtime.frame.MojoRowBuilder;
import ai.h2o.mojos.runtime.lic.LicenseException;
import ai.h2o.mojos.runtime.utils.CsvWritingBatchHandler;
import com.opencsv.CSVWriter;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
public class DocsExample {
    public static void main(String[] args) throws IOException, LicenseException {
        // Load model and csv
        final MojoPipeline model = MojoPipelineService.loadPipeline("klime_mojo.zip");
        // Get and fill the input columns
        final MojoFrameBuilder frameBuilder = model.getInputFrameBuilder();
        final MojoRowBuilder rowBuilder = frameBuilder.getMojoRowBuilder();
        rowBuilder.setValue("petal_wid", "0.2");
        rowBuilder.setValue("class", "Iris-setosa");
        rowBuilder.setValue("sepal_len", "5.1");
        rowBuilder.setValue("petal_len", "1.4");
        frameBuilder.addRow(rowBuilder);
        // Create a frame which can be transformed by MOJO pipeline
        final MojoFrame iframe = frameBuilder.toMojoFrame();
        // Transform input frame by MOJO pipeline
        final MojoFrame oframe = model.transform(iframe);
        // `MojoFrame.debug()` can be used to view the contents of a Frame
        // oframe.debug();
        // Output prediction as CSV
        final Writer writer = new BufferedWriter(new OutputStreamWriter(System.out));
        final CSVWriter csvWriter = new CSVWriter(writer);
        CsvWritingBatchHandler.csvWriteFrame(csvWriter, oframe, true);
    }
}

  1. Compile the source code with the files of the MOJO runtime (mojo2-runtime.jar) copied into the experiment:

javac -cp mojo2-runtime.jar -J-Xms2g -J-XX:MaxPermSize=128m DocsExample.java

  1. Run the MOJO example with the license (license.sig) copied into the experiment:

# Linux and OS X users
java -Dai.h2o.mojos.runtime.license.file=license.sig -cp .:mojo2-runtime.jar DocsExample
# Windows users
java -Dai.h2o.mojos.runtime.license.file=license.sig -cp .;mojo2-runtime.jar DocsExample

  1. The following output is displayed:

model_pred,cluster,petal_wid,class,sepal_len,petal_len
3.4530200678814422,1.0,-0.01619126014214789,1.3624817331603232E-6,2.5224436307972296,-0.5251985209647447