Java package


Supported platforms

The Nexosis Client for Java supports Java versions 1.7 and 1.8.

Installing the Client

View package details

view the source code

Maven

Add this dependency to pom.xml:

<dependency>
    <groupId>com.nexosis</groupId>
    <artifactId>nexosisclient-java</artifactId>
    <version>1.0.1</version>
</dependency>

Gradle

Add this to the build.gradle file:

dependencies {
    compile 'com.nexosis:nexosisclient-java:1.0.1'
}

Java Quick Start

Initialize the Client

The NexosisClient has several constructor overloads.

To use the default constructor, create an environment variable called NEXOSIS_API_KEY and set it equal to your API Key. This also uses the default API Endpoint base URI https://ml.nexosis.com/v1.

NexosisClient client = new NexosisClient(); 

Initialize the client with an API key.

NexosisClient client = new NexosisClient("api_key_here");

Initialize the client with an API key and endpoint.

NexosisClient client = new NexosisClient("api_key_here", "https://ml.nexosis.com/v1/");

Creating and Uploading DataSets

Currently, there are two ways to upload data to Nexosis.

  1. CSV File
  2. Through a Java POJO / Model Object

CVS doesn’t yet support the MetaData object so one column must be named timestamp to run a forecasting or impact session. All dates must be in an ISO 8601 format. If no time-zone is specified, it is assumed to be UTC.

timeStamp,sales,transactions
2012-12-31 00:00:00,2922.13,459
2013-01-01 00:00:00,1500.56,195
2013-01-02 00:00:00,4078.52,696
2013-01-03 00:00:00,4545.69,743
2013-01-04 00:00:00,4872.63,797
2013-01-05 00:00:00,2420.81,367
2013-01-06 00:00:00,1664.22,241
2013-01-07 00:00:00,3693.01,647
2013-01-08 00:00:00,3874.89,653
2013-01-09 00:00:00,4134.05,700
2013-01-10 00:00:00,4314.94,723
...etc...

Given the csv file above, the FileInputStream can be passed to the create() method to upload the data.

String dataSetName = "SampleDataSet";
File initialFile = new File("./SampleData.csv");
InputStream inputStream = new FileInputStream(initialFile);

nexosisClient.getDataSets().create(dataSetName, inputStream);

Here’s an example of creating a DataSet using the DataSetData Model object, using generated random data:

// Generate a dataset
Random rand = new Random();
DateTime startDate = DateTime.parse("2016-08-01T00:00:00Z");
DateTime endDate = DateTime.parse("2017-03-26T00:00:00Z");

List<Map<String, String>> rows = new ArrayList<>();
// Generate a series of containing 
for (DateTime timeStamp = startDate; timeStamp.isBefore(endDate); timeStamp = timeStamp.plusDays(1)) {
    Map<String, String> row = new HashMap<>();
    row.put("timestamp", timeStamp.toDateTimeISO().toString());
    row.put("sales", Double.toString(rand.nextDouble() * 100));
    row.put("promotion", Boolean.toString(false);
    rows.add(row);
}
// Create and add all the rows to the DataSet.
DataSetData dataSet = new DataSetData();
data.setData(rows);

// Setup metadata that describes the dataset columns.
// For time-series, we want to indicate a TIMESTAMP column
// Indicate the sales column is the TARGET to forcast over
// The promotion column is a boolean indicating if the date is a promotional period
Columns cols = new Columns();
cols.setColumnMetadata("timestamp", DataType.DATE, DataRole.TIMESTAMP);
cols.setColumnMetadata("sales", DataType.NUMERIC, DataRole.TARGET); 
cols.setColumnMetadata("promotion", DataType.LOGICAL, DataRole.FEATURE);
// Add the Columns Metadata to the DataSet
dataSet.setColumns(cols);

String dataSetName = "SampleDataSet";
// Send the dataset to the API endpoint
nexosisClient.getDataSets().create(dataSetName, dataSet);

Retrieve a list of DataSets

 DataSetList list = nexosisClient.getDataSets().list();

Create a Forecast Session

To generate forecasts, the platform needs to know the DataSet name to build the forecasting models off of, a target column indicating what columns the model should be predicting, a prediction interval, and the start and end date of the desired prediction dates.

 nexosisClient.getSessions().createForecast(
                "OtherDataSet",
                "sales",
                DateTime.parse("2017-03-25T0:00:00Z"),
                DateTime.parse("2017-04-24T0:00:00Z"),
                ResultInterval.DAY
        );

Create an Impact Session

To analyze the impact of a past event, the platform needs to know the DataSet name to build the forecasting models off of, a target column indicating what columns the model will analyze, a prediction interval, and the start and end date of the event.

SessionResponse response = nexosisClient.getSessions().analyzeImpact(
        "websiteTraffic",
        "new-big-announcement",
        "hits",
        DateTime.parse("2016-11-26T00:00:00Z"),
        DateTime.parse("2016-12-25T00:00:00Z"),
        ResultInterval.DAY
);

// Save the SessionID
UUID sessionId = response.getSessionId();
// Use SessionID to check on the status and retrieve results when they are ready

Check On Session Status

// After starting a Session...

while (results.getStatus() != SessionStatus.COMPLETED) {
        Thread.sleep(4000);
        SessionResult results = nexosisClient.getSessions().getResults(savedSessionId);
}

// Retrieve the Results.

Issues

If you run into issues using this client library, create a new issue in github. Please include code to reproduce the error if possible.