ViperCharts

 

ViperCharts API

ViperCharts enables easy access to its charting services via the ViperCharts API.
It's all very simple in just three steps:
  • Prepare your data in the required JSON format.
  • Make a POST request to 'http://viper.ijs.si/api/' with the appropriate JSON formatted data.
  • Follow the provided link in the response to access your performance chart.

Example of use

The ViperCharts API can be accesed by employing only few lines of code. Here is an example in Python:
>>> import urllib2, json
>>> url = "http://viper.ijs.si/api/"
>>> data = json.dumps({"chart":"rocc", "data":[{"name":"alg1","actual":[1,1,1,0,0,0],"predicted":[1.2,0.8,0.6,0.8,0.5,0.6]}]})
>>> req = urllib2.Request(url, data)
>>> req.add_header('Content-Type', 'application/json')
>>> response = urllib2.urlopen(req)
The API returns a JSON formatted response with two parameters: a message reporting success or errors and the URL to the generated performance chart.
>>> response.read()
'{"msg": "ROC curve chart succesfully created.", "url": "http://viper.ijs.si/api/curve/roc/cfeb5099-7630-4cfe-9ef2-d689347c4bbf/" }
Detailed guidelines on data formatting, making a POST request, and getting a response, are described below.

Data format

Each request to the ViperCharts API should include the following JSON formated data.
Two required parameters are "chart", indicating the desired chart type, and "data", a list of performance results: 
{
  "chart": "rocc",
  "data": [ ... ],
  "title": "My chart"
}
The "title" parameter is optional for display of a chart caption. The value should be a string in parenthesis.
All parameter names should be formatted as a string in parenthesis.

"chart" parameter

Here is the list of possible "chart" parameter values for the different chart types provided by the ViperCharts API:

Scatter charts

ValueChart
prsPR space chart (including F-isolines)
rocsROC space chart

Curve charts

ValueChart
prcPR curves
liftLift curves
roccROC curves
rochROC hull curves
costCost curves
ratedrivenRate-driven curves
kendallKendall curves

Column charts

ValueChart
columnColumn chart

"data" parameter

Formatting the data of the "data" parameter depends on the chart type you have chosen.

Scatter charts

The PR space scatter chart requires the "recall" and "precision" parameters and their respective values between 0 and 1, as well as the "name" of each point in the PR space. 
{
  "chart": "prs",
  "data": [
            {
              "name": "Algorithm_1",
              "recall": 0.93,
              "precision": 0.87
            },
            ...
          ]
}
The ROC space scatter chart requires the "fpt" (false positive rate) and "tpr" (true positive rate) parameters and their respective values between 0 and 1, as well as the "name" of each point in the ROC space. 
{
  "chart": "rocs",
  "data": [
            {
              "name": "Algorithm_1",
              "fpr": 0.93,
              "tpr": 0.87
            },
            ...
          ]
}

Curve charts

All curve charts require the same data input, the "name" of each curve and the chart and two lists indicating the "actual" class of the instances in the examined dataset (1 for the possitive class, and 0 for the other(s)), and the "predicted" values for the same order of instances (higher values are assumed to indicate the positive class). 
{
  "chart": "lift",
  "data": [
            {
              "name": "Algorithm_1",
              "actual": [1,1,1,0,0,0],
              "predicted":[1.2,0.8,0.6,0.8,0.5,0.6],
            },
            ...
          ]
}
By default prediction scores are expected, in the case of predicted ranks an optional parameter "predtype" with value "rank" should be added to the request data. 
{
  "chart": "lift",
  "data": [ ... ],
  "predtype": "rank"
}

Column charts

Column chart enable you to visualize multiple performance measures for a set of algorithms. This is formatted in the following way. 
{
  "chart": "column",
  "data": [
            {
              "name": "Algorithm_1",
              "measure_1": 0.99,
              "measure_2": 0.66,
              ...
            },
            ...
          ]
}
The "name" parameter is reserved for naming the evaluated algorithms and should not be used as a measure label. Change the measure labels as you like, e.g. "measure_1" to "precision", etc.

POST request

Now that you know how to format the input data, you are ready to send it to the ViperCharts API. The charting service can be accesed via the address 'http://viper.ijs.si/api/'. A simple POST request including the JSON formated data will generate your chart and give you a response.

Don't forget to set the content-type parameter to 'application/json' in the header of your POST request.

An example showing how to make such POST requests in Python is descibed at the top of this page.

API response

After your POST request to the ViperCharts API you will receive a JSON response providing a message reporting success or errors, and the URL to the generated performance chart.
{
  "msg": "ROC curve chart succesfully created.",
  "url": "http://viper.ijs.si/api/curve/roc/cfeb5099-7630-4cfe-9ef2-d689347c4bbf/"
}