js-example-fraud-score

Example use of DeployR as a real-time, R analytics scoring engine.

Installation

There are two ways to install the js-example-fraud-score example:

The preferred way is to use the DeployR command line interface (CLI) to install.
Manual Installation without the DeployR CLI.

About

This example demonstrates the use of DeployR as a real-time, R analytics scoring engine.

The example scenario mimics a real world application where employees at a fictitious bank can request fraud scores for one or more bank account records to help detect fraudulent account activity.

This example is built using the DeployR RBroker Framework, the simplest way to integrate R analytics inside any Java, JavaScript or .NET application.

This example consists of three distinct parts:

Example R Analytics
Example Server Application
Example Client Application

The final section of this document provides additional details regarding the DeployR integration implemented for this example.

Example R Analytics

Source: analytics/*

This example uses an R model built to score fictitious bank account data to help uncover fraudulent account activity. The model used is found here:

analytics/fraudModel.rData

The model uses three variables associated with individual bank accounts:

The number of transactions on the account
The account balance
The credit line on the account

This example makes use of a scoring function that uses the model to help determine the likelihood of fraud on a given account based on these data inputs. The scoring function is found here:

analytics/ccFraudScore.R

The R scripts and data models used by this example application are bundled by default within the DeployR 7.3 repository, inside the example-fraud-score directory owned by testuser.

However, if for any reason your DeployR repository does not contain these files you can add them using the DeployR Repository Manager as follows:

Log in as testuser into the Repository Manager
Create a new repository directory called example-fraud-score
Upload analytics/fraudModel.rData to the example-fraud-score directory
Upload analytics/ccFraudScore.R to the example-fraud-score directory

Example Server Application

Source:

server.js

server/**/*

The example server application represents a real world application, capable of processing client requests for fraud scores on one or more bank account records.

The example server application is implemented as a simple Express Node.js Web application.

The example server application exposes a simple REST API through which client applications can submit fraud scoring requests:

/fraud/score/{num_of_records}

The example server application handles client requests internally using the RBroker Framework to run the required R analytics that scores each requested bank account record.

The score, generated by the R analytics and returned to the server via the RBroker Framework, is then pushed by the server application, using WebSockets through an abstraction layer for real-time communication called Primus to client applications that have subscribed as listeners on:

/fraudengine/topic/fraud

Example Client Application

Source: client/app/*

The example client application simulates a computer system made available to employees at a fictitious bank.

The example client application is implemented as a simple, single page AngularJS application. The single page is divided into two distinct sections:

RBroker Runtime Window

This window gives the user a live view of all activity that is taking place through the RBroker Framework on behalf of the client application. The runtime data provided indicates among other things the live throughput performance being delivered by DeployR behaving as a real-time R analytics scoring engine.

Note: The details presented in the RBroker Runtime Window would not typically appear in a real-world client application. These data are presented here simply to aid developers understand by observation how an _RBroker Framework_integration works.
Bank Account Fraud Score Result Window

This window displays the fraud score results generated by the real-time R analytics scoring engine powered by DeployR. The end user can also use the Execute button in this window to launch one or more fraud scoring requests.

The data for example bank account records is randomly generated by the application. Requests are submitted by the client application through the server application REST API.

The score generated per request is returned to the client application within a JSON message delivered over a WebSocket channel.

Manual Installation

Note The preferred way to install this example is to use the DeployR command line interface (CLI).

Download and install Node.js, which ships with npm.

Clone the repository:

$ git clone https://github.com/deployr/js-example-fraud-score.git
$ cd js-example-fraud-score

Install the dependencies:
```
$ npm install
```
Set the DeployR server endpoint location if not running at localhost in the configuration file config/config.json

Running the Example

By default, the build configuration assumes an instance of the DeployR server is running on localhost. If your instance of DeployR is running at some other IP address then please update the endpoint property in the configuration file config/config.json as appropriate:

{
   "endpoint": "http://localhost:8.0.5",
   "port": "9080",
   "credentials": {
      "username": "testuser",
      "password": "TESTUSER_PASSWORD"
   },
   "logging": false,
   "constants" : {
      "REPO_OWNER": "testuser",
      "REPO_SCRIPT": "ccFraudScore.R",
      "REPO_DIRECTORY": "example-fraud-score", 
      "FRAUD_MODEL": "fraudModel.rData"
   }
}

To run this example application:

Set the DeployR endpoint and the appropriate credentials

$ cd js-example-fraud-score

$ npm start

Observe the console output in your terminal window to determine if the server application has started successfully. Once started, open the client application in your Web browser:

http://localhost:9080

Multiple Users Running the Example

By default, the example build configuration defaults to using testuser account credentials when authenticating with the DeployR server. If two or more users intend running this example application at the same time against the same DeployR server instance then:

Each user must update the username property in their config/config.json configuration file, each indicating the username of their own user account.
The Access Control setting for each of the R analytics file dependencies in the DeployR repository must be changed from Private access to Shared access.

DeployR Integration Details

R Analytics Dependencies

DeployR-powered applications typically depend on repository-managed R analytics scripts, models and/or data files. See the DeployR Repository Manager for details on how best to manage your own R analytics dependencies.

This example depends on two repository-managed files:

/testuser/example-fraud-score/fraudModel.rData
/testuser/example-fraud-score/ccFraudScore.R

Both files, an R model and scoring function respectively, are owned by testuser and can be found in the example-fraud-score repository-managed directory owned by testuser.

These example file dependencies ship, pre-deployed in the DeployR repository so there is no further action for you to take in order for this example to use them.

RBroker Framework - Pooled Task Runtime

This examples uses the RBroker Framework to integrate DeployR real-time scoring capabilities inside the example server application.

Specifically, this example uses the Pooled Task Runtime provided by the RBroker Framework.

RBroker Framework - Throughput

The Resize button in the RBroker Runtime Window in the example client application lets the end user experiment with the size of the pool of R sessions associated with the Pooled Task Runtime.

We recommend experimenting with the size of the pool and observing the effect this has on throughput. See the following sections of the RBroker Framework tutorial for related details:

Building

To build the Client portion of the application:

$ ./node_modules/.bin/browserify client/app/js/main.js > client/app/js/bundle.js

License

This program is licensed to you under the terms of Version 2.0 of the Apache License. This program is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THOSE OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Please refer to the Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0) for more details.