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

For completed MLI experiments, users 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.

Note: This reason code pipeline is not currently available for multinomial experiments.

Prerequisites

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

  • Java 7 runtime (JDK 1.7) or newer. Note: Using Java 11+ is recommended 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 via the JVM system property ai.h2o.mojos.runtime.license.filename.

For example:

# Specify the license via 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 is an example of how the Java runtime can be executed from the command line:

java <JVM options> -cp mojo2-runtime-x.y.z.jar:your-other.jar:many-more-libs.jar ai.h2o.mojos.ExecuteMojo path-to/klime_mojo.zip path-to/input.csv path-to/output.csv

The following is an example of how the Java runtime can be executed if additional libraries are not needed:

java <JVM options> -jar mojo2-runtime-x.y.z.jar path-to/klime_mojo.zip path-to/input.csv path-to/output.csv

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

JVM Options

  • keepCarriageReturn (boolean) - Specify whether to keep the carriage return after parsing. This value defaults to True.

  • stripCrFromLastColumn (boolean) - Workaround for issues relating to the OpenCSV parser. This value defaults to True.

  • quotedHeaders (boolean) - Specify whether to quote header names in the output CSV file. This value defaults to False.

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

  • 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.

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

  • 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`.

  • date.formats (string) - Specify a format for dates. This value defaults to an empty string.

  • 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.

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 = loadMojoFromFileResource("klime_mojo.zip");

        // Get and fill the input columns
        final MojoFrameBuilder frameBuilder = model.getInputFrameBuilder();
        final MojoRowBuilder rowBuilder = frameBuilder.getMojoRowBuilder();
        rowBuilder.setValue("AGE", "68");
        rowBuilder.setValue("RACE", "2");
        rowBuilder.setValue("DCAPS", "2");
        rowBuilder.setValue("VOL", "0");
        rowBuilder.setValue("GLEASON", "6");
        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,GLEASON,DCAPS,AGE,VOL
0.445133897439256,3.0,-0.09579754094219743,0.1112825797986618,-0.11090914864397795,-0.0