README

In this repository you'll find an open source PHP library that gives you a simple way to interact with BigML using its API.

This module is licensed under the Apache License, Version 2.0.**

Notice: the BigML PHP bindings are not entirely backwards compatible with versions prior to 2.0. In particular, all static methods have been removed from the BigML class. So, if you ever used the syntaxis, e.g.:

BigML::create_source(...);

you will get an error. On the other hand, if you followed the syntaxis which was documented in this README, i.e.,

$api->create_source(...)

you will be fine.

Additionally, notice that the old constructor which accepted all of its parameters as individual arguments has been deprecated in favour of a new one supporting the specification of named parameters. Use the new syntaxis instead, as described below. The old constructor syntaxis will be maintained until version 3.0, then removed.

Table of Contents

Requirements

PHP 8.0 or higher is currently supported by these bindings.

You will also need to have the non-default extensions mbstring, cURL, and OpenSSL installed. Depending on how you installed PHP, you may already have one or more of these extensions.

To check which modules you have currently installed, run

php -m

To install with Linux:

At the command line, run

sudo apt-get install phpXY-mbstring
sudo apt-get install phpXY-curl

where XY is the PHP version currently installed on your system (e.g., php72-curl).

To install with MacOS:

At the command line, run

sudo port install phpXY-mbstring
sudo port install phpXY-curl
sudo port install phpXY-openssl

where XY is the PHP version currently installed on your system (e.g., php72-curl).

If you installed PHP by tapping homebrew-php, mbstring should already be installed. You will still need to install curl and openssl using

brew install --with-openssl curl

To install with Windows:

If you have access to the php.ini, remove the semicolon in front of these lines in the php.ini

extension = php_mbstring.dll
extension = php_curl.dll
extension = php_openssl.dll

You will have to be sure you have these dll files, and they are available on your PATH. You may also need to check that libeay32.dll and ssleay32.dll are in your php directory.

Once you have made the changes, don't forget to restart your server for them to take effect.

Importing the module

Using Composer

If you are currently using Composer to manage your project's libraries, simply add the following to your current composer.json

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/bigmlcom/bigml-php/"
        }
    ],
    "require": {
        "bigml/bigml-php": "dev-master",
        "wamania/php-stemmer": "@dev"
    },
    "autoload":{
        "classmap": ["vendor/bigml/bigml-php/bigml/"]
    }
}

At the command line, run the command

php composer.phar install

This will install this library and all required library dependencies (but not extensions such as mbstring).

In your code:

At the beginning of your file include the line

<? php
require 'vendor/autoload.php';

Cloning from GitHub

If you would prefer, you can manually clone this repo from GitHub. You will still need to use Composer to install some third-party libraries.

If you haven't already done so, you will need to install Composer.

Linux/OSX:

Follow the instructions in the download section to get the composer.phar file, and run

php composer.phar install

This will install all necessary dependencies.

Windows:

Follow the instructions on the Composer website for downloading Composer, and run

php composer.phar install

This will install all necessary dependencies.

In your code:

At the beginning of your file you will need to include the various files you will be using. If you will be making any remote calls, you will need bigml.php. If you will be making any local models, you will need their specific files. The most common files to include are

<?php
include('bigml.php');
include('anomaly.php');
include('association.php');
include('boostedensemble.php');
include('cluster.php');
include('ensemble.php');
include('logistic.php');
include('model.php');
include('prediction.php');
include('topicmodel.php');

Authentication

All the requests to BigML.io must be authenticated using your username and API key. and are always transmitted over HTTPS.

This module will look for your username and API key in the environment variables BIGML_USERNAME and BIGML_API_KEY respectively. You can add the following lines to your .bashrc or .bash_profile to set those variables automatically when you log in

export BIGML_USERNAME=myusername
export BIGML_API_KEY=a11e579e7e53fb9abd646a6ff8aa99d4afe83ac2

With that environment and your aliases set up, connecting to BigML is a breeze

$api = new BigML\BigML();

Otherwise, you can initialize directly when instantiating the BigML class as follows by manually supplying your credentials:

$api = new BigML\BigML([ "username" => "myusername",
                         "apiKey" => "my_api_key"]);

Caching

An important feature provided by the api constructor is the specification of a local cache to speed up the retrieval of resources. If you supply a storage for your BigML instance, the PHP bindings will hit the network only once for each resource. On subsequent accesses, the resource will be retrieved from the local cache.

This is how you can set the storage argument when you instantiate the BigML class:

$api = new BigML\BigML([ "username" => "myusername",
                         "apiKey" => "my_api_key",
                         "storage" => "storage/data"]);

Or, more succinctly:

$api = new BigML\BigML(["storage" => "storage/data"]);

if you have your environment set.

All resources will be created, updated, or retrieved in/from the chosen directory.

Virtual Private Clouds

For Virtual Private Cloud setups, you can change the remote server domain:

$api = new BigML\BigML([ "username" => "myusername",
                         "apiKey" => "my_api_key",
                         "domain" => "my_VPC.bigml.io",
                         "storage" => "storage/data"]);

NOTICE: BigML API used to provide a sandbox mode, also know as development mode. This has been deprecated and is not supported in the PHP binding anymore. To guarantee backward-compatibility, the BigML class constructor still supports the specification of a dev_mode argument, but it is now ignored.

Projects and Organizations

When you instantiate the BigML class you can specify a project or organization that the instance shall default to:

$api = new BigML\BigML(["username" => "myusername",
                         "apiKey" => "my_api_key",
                         "project" => $projectID]);

$api = new BigML\BigML(["username" => "myusername",
                         "apiKey" => "my_api_key",
                         "organization" => $organization]);

When $project is set to a project ID and that project exists for an organization, the user is considered to be working in an organization project. The scope of the API requests will be limited to this project and permissions should be previously given by the organization administrator.

If the specified project does not belong to an organization but is a project of the user's, then the scope of all API requests will be limited to that project.

When $organization is set to an organization ID, the user is considered to be working for an organization. The scope of the API requests will be limited to the projects of the organization and permissions need to be previously given by the organization administrator.

Quick Start

Imagine that you want to use this csv file containing the Iris flower dataset to predict the species of a flower whose sepal length is 5 and whose sepal width is 2.5. A preview of the dataset is shown below. It has 4 numeric fields: sepal length, sepal width, petal length, petal width and a categorical field: species. By default, BigML considers the last field in the dataset as the objective field (i.e., the field that you want to generate predictions for).

sepal length,sepal width,petal length,petal width,species
5.1,3.5,1.4,0.2,Iris-setosa
4.9,3.0,1.4,0.2,Iris-setosa
4.7,3.2,1.3,0.2,Iris-setosa
...
5.8,2.7,3.9,1.2,Iris-versicolor
6.0,2.7,5.1,1.6,Iris-versicolor
5.4,3.0,4.5,1.5,Iris-versicolor
...
6.8,3.0,5.5,2.1,Iris-virginica
5.7,2.5,5.0,2.0,Iris-virginica
5.8,2.8,5.1,2.4,Iris-virginica

If your credentials are stored in the environment as mentioned above, you can easily generate a prediction following these steps

$api = new BigML\BigML();

$source = $api->create_source('./tests/data/iris.csv');
$dataset = $api->create_dataset($source);
$model = $api->create_model($dataset);
$prediction = $api->create_prediction($model, array('sepal length'=> 5, 'sepal width'=> 2.5));

then:

$objective_field_name = $prediction->object->fields->{$prediction->object->objective_fields[0]}->name;

"petal width"

$value = $prediction->object->prediction->{$prediction->object->objective_fields[0]};

0.30455

$api->pprint($prediction);

petal width for {"sepal length":5,"sepal width":2.5} is 0.30455

also, you can generate an evaluation for the model by using

$test_source = $api->create_source('./tests/data/iris.csv');
$test_dataset = $api->create_dataset($test_source);
$evaluation = $api->create_evaluation($model, $test_dataset);

Dataset

If you want to get some basic statistics for each field you can retrieve the fields from the dataset as follows to get a dictionary keyed by field id

$dataset = $api->get_dataset($dataset);
print_r($api->get_fields($dataset))

The field filtering options are also available using a query string expression, for instance

$dataset = $api->get_dataset($dataset, "limit=20")

limits the number of fields that will be included in dataset to 20.

Model

One of the greatest things about BigML is that the models that it generates for you are fully white-boxed. To get the explicit tree-like predictive model for the example above

$model = $api->get_model($model_id);

print_r($model->object->model->root);

stdClass Object
(
[children] => Array
    (
        [0] => stdClass Object
            (
                [children] => Array
                    (
                        [0] => stdClass Object...

Again, filtering options are also available using a query string expression, for instance

$model = $api->get_model($model_id, "limit=5");

limits the number of fields that will be included in model to 5.

Evaluation

The predictive performance of a model can be measured using many different measures. In BigML these measures can be obtained by creating evaluations. To create an evaluation you need the id of the model you are evaluating and the id of the dataset that contains the data to be tested with. The result is shown as

$evaluation = $api->get_evaluation($evaluation_id);

Cluster

For unsupervised learning problems, the cluster is used to classify in a limited number of groups your training data. The cluster structure is defined by the centers of each group of data, named centroids, and the data enclosed in the group. As for in the model’s case, the cluster is a white-box resource and can be retrieved as a JSON

$cluster = $api->get_cluster($cluster_id)

Anomaly detector

For anomaly detection problems, BigML anomaly detector uses iforest as an unsupervised kind of model that detects anomalous data in a dataset. The information it returns encloses a top_anomalies block that contains a list of the most anomalous points. For each, we capture a score from 0 to 1. The closer to 1, the more anomalous. We also capture the row which gives values for each field in the order defined by input_fields. Similarly we give a list of importances which match the row values. These importances tell us which values contributed most to the anomaly score. Thus, the structure of an anomaly detector is similar to

{"category": 0,
"code": 200,
"columns": 14,
"constraints": false,
"created": "2014-09-08T18:51:11.893000",
"credits": 0.11653518676757812,
"credits_per_prediction": 0.0,
"dataset": "dataset/540dfa9d9841fa5c88000765",
"dataset_field_types": {   "categorical": 21,
                           "datetime": 0,
                           "numeric": 21,
                           "preferred": 14,
                           "text": 0,
                           "total": 42},
"dataset_status": true,
"dataset_type": 0,
"description": "",
"excluded_fields": [],
"fields_meta": {   "count": 14,
                   "limit": 1000,
                   "offset": 0,
                   "query_total": 14,
                   "total": 14},
"forest_size": 128,
"input_fields": [   "000004",
                    "000005",
                    "000009",
                    "000016",
                    "000017",
                    "000018",
                    "000019",
                    "00001e",
                    "00001f",
                    "000020",
                    "000023",
                    "000024",
                    "000025",
                    "000026"],
"locale": "en_US",
"max_columns": 42,
"max_rows": 200,
"model": {   "fields": {   "000004": {   "column_number": 4,
                                         "datatype": "int16",
                                         "name": "src_bytes",
                                         "optype": "numeric",
                                         "order": 0,
                                         "preferred": true,
                                         "summary": {   "bins": [   [   143,
                                                                        2],
                                                                    ...
                                                                    [   370,
                                                                        2]],
                                                        "maximum": 370,
                                                        "mean": 248.235,
                                                        "median": 234.57157,
                                                        "minimum": 141,
                                                        "missing_count": 0,
                                                        "population": 200,
                                                        "splits": [   159.92462,
                                                                      173.73312,
                                                                      188,
                                                                      ...
                                                                      339.55228],
                                                        "standard_deviation": 49.39869,
                                                        "sum": 49647,
                                                        "sum_squares": 12809729,
                                                        "variance": 2440.23093}},
                           "000005": {   "column_number": 5,
                                         "datatype": "int32",
                                         "name": "dst_bytes",
                                         "optype": "numeric",
                                         "order": 1,
                                         "preferred": true,
                                          ...
                                                        "sum": 1030851,
                                                        "sum_squares": 22764504759,
                                                        "variance": 87694652.45224}},
                           "000009": {   "column_number": 9,
                                         "datatype": "string",
                                         "name": "hot",
                                         "optype": "categorical",
                                         "order": 2,
                                         "preferred": true,
                                         "summary": {   "categories": [   [   "0",
                                                                              199],
                                                                          [   "1",
                                                                              1]],
                                                        "missing_count": 0},
                                         "term_analysis": {   "enabled": true}},
                           "000016": {   "column_number": 22,
                                         "datatype": "int8",
                                         "name": "count",
                                         "optype": "numeric",
                                         "order": 3,
                                         "preferred": true,
                                                        ...
                                                        "population": 200,
                                                        "standard_deviation": 5.42421,
                                                        "sum": 1351,
                                                        "sum_squares": 14981,
                                                        "variance": 29.42209}},
                           "000017": { ... }}},
             "kind": "iforest",
             "mean_depth": 12.314174107142858,
             "top_anomalies": [   {   "importance": [   0.06768,
                                                        0.01667,
                                                        0.00081,
                                                        0.02437,
                                                        0.04773,
                                                        0.22197,
                                                        0.18208,
                                                        0.01868,
                                                        0.11855,
                                                        0.01983,
                                                        0.01898,
                                                        0.05306,
                                                        0.20398,
                                                        0.00562],
                                      "row": [   183.0,
                                                 8654.0,
                                                 "0",
                                                 4.0,
                                                 4.0,
                                                 0.25,
                                                 0.25,
                                                 0.0,
                                                 123.0,
                                                 255.0,
                                                 0.01,
                                                 0.04,
                                                 0.01,
                                                 0.0],
                                      "score": 0.68782},
                                  {   "importance": [   0.05645,
                                                        0.02285,
                                                        0.0015,
                                                        0.05196,
                                                        0.04435,
                                                        0.0005,
                                                        0.00056,
                                                        0.18979,
                                                        0.12402,
                                                        0.23671,
                                                        0.20723,
                                                        0.05651,
                                                        0.00144,
                                                        0.00612],
                                      "row": [   212.0,
                                                 1940.0,
                                                 "0",
                                                 1.0,
                                                 2.0,
                                                 0.0,
                                                 0.0,
                                                 1.0,
                                                 1.0,
                                                 69.0,
                                                 1.0,
                                                 0.04,
                                                 0.0,
                                                 0.0],
                                      "score": 0.6239},
                                      ...],
             "trees": [   {   "root": {   "children": [   {   "children": [   {   "children": [   {   "children": [   {   "children":[   {   "population": 1,
                                                                                                                          "predicates": [   {   "field": "00001f",
                                                                                                                                                "op": ">",
                                                                                                                                                "value": 35.54357}]},

                                                                                                                      {   "population": 1,
                                                                                                                          "predicates": [   {   "field": "00001f",
                                                                                                                                                "op": "<=",
                                                                                                                                                "value": 35.54357}]}],
                                                                                                      "population": 2,
                                                                                                      "predicates": [   {   "field": "000005",
                                                                                                                            "op": "<=",
                                                                                                                            "value": 1385.5166}]}],
                                                                                  "population": 3,
                                                                                  "predicates": [   {   "field": "000020",
                                                                                                        "op": "<=",
                                                                                                        "value": 65.14308},
                                                                                                    {   "field": "000019",
                                                                                                        "op": "=",
                                                                                                        "value": 0}]}],
                                                              "population": 105,
                                                              "predicates": [   {   "field": "000017",
                                                                                    "op": "<=",
                                                                                    "value": 13.21754},
                                                                                {   "field": "000009",
                                                                                    "op": "in",
                                                                                    "value": [   "0"]}]}],
                                          "population": 126,
                                          "predicates": [   true,
                                                            {   "field": "000018",
                                                                "op": "=",
                                                                "value": 0}]},
                              "training_mean_depth": 11.071428571428571}]},
"name": "tiny_kdd's dataset anomaly detector",
"number_of_batchscores": 0,
"number_of_public_predictions": 0,
"number_of_scores": 0,
"out_of_bag": false,
"price": 0.0,
"private": true,
"project": null,
"range": [1, 200],
"replacement": false,
"resource": "anomaly/540dfa9f9841fa5c8800076a",
"rows": 200,
"sample_rate": 1.0,
"sample_size": 126,
"seed": "BigML",
"shared": false,
"size": 30549,
"source": "source/540dfa979841fa5c7f000363",
"source_status": true,
"status": {   "code": 5,
              "elapsed": 32397,
              "message": "The anomaly detector has been created",
              "progress": 1.0},
"subscription": false,
"tags": [],
"updated": "2014-09-08T23:54:28.647000",
"white_box": false}

Samples

To provide quick access to your row data you can create a sample. Samples are in-memory objects that can be queried for subsets of data by limiting their size, the fields or the rows returned. The structure of a sample would be:

Samples are not permanent objects. Once they are created, they will be available as long as GETs are requested within periods smaller than a pre-established TTL (Time to Live). The expiration timer of a sample is reset every time a new GET is received.

If requested, a sample can also perform linear regression and compute Pearson's and Spearman's correlations for either one numeric field against all other numeric fields or between two specific numeric fields.

Correlations

A correlation resource contains a series of computations that reflect the degree of dependence between the field set as objective for your predictions and the rest of fields in your dataset. The dependence degree is obtained by comparing the distributions in every objective and non-objective field pair, as independent fields should have probabilistic independent distributions. Depending on the types of the fields to compare, the metrics used to compute the correlation degree will be:

for numeric to numeric pairs: Pearson's and Spearman's correlation coefficients.
for numeric to categorical pairs: One-way Analysis of Variance, with the categorical field as the predictor variable.
for categorical to categorical pairs: contingency table (or two-way table), Chi-square test of independence , and Cramer's V and Tschuprow's T coefficients.

An example of the correlation resource JSON structure is

{"category": 0,
"clones": 0,
"code": 200,
"columns": 5,
"correlations": {   "correlations": [   {   "name": "one_way_anova",
                                              "result": {   "000000": {   "eta_square": 0.61871,
                                                                            "f_ratio": 119.2645,
                                                                            "p_value": 0,
                                                                            "significant": [   true,
                                                                                                true,
                                                                                                true]},
                                                             "000001": {   "eta_square": 0.40078,
                                                                            "f_ratio": 49.16004,
                                                                            "p_value": 0,
                                                                            "significant": [   true,
                                                                                                true,
                                                                                                true]},
                                                             "000002": {   "eta_square": 0.94137,
                                                                            "f_ratio": 1180.16118,
                                                                            "p_value": 0,
                                                                            "significant": [   true,
                                                                                                true,
                                                                                                true]},
                                                             "000003": {   "eta_square": 0.92888,
                                                                            "f_ratio": 960.00715,
                                                                            "p_value": 0,
                                                                            "significant": [   true,
                                                                                                true,
                                                                                                true]}}}],
                     "fields": {   "000000": {   "column_number": 0,
                                                   "datatype": "double",
                                                   "idx": 0,
                                                   "name": "sepal length",
                                                   "optype": "numeric",
                                                   "order": 0,
                                                   "preferred": true,
                                                   "summary": {   "bins": [   [   4.3,
                                                                                    1],
                                                                                [   4.425,
                                                                                    4],
                                                                                  ...
                                                                                [   7.9,
                                                                                    1]],
                                                                   "kurtosis": -0.57357,
                                                                   "maximum": 7.9,
                                                                   "mean": 5.84333,
                                                                   "median": 5.8,
                                                                   "minimum": 4.3,
                                                                   "missing_count": 0,
                                                                   "population": 150,
                                                                   "skewness": 0.31175,
                                                                   "splits": [   4.51526,
                                                                                  4.67252,
                                                                                  4.81113,
                                                                                  4.89582,
                                                                                  4.96139,
                                                                                  5.01131,
                                                                                  ...
                                                                                  6.92597,
                                                                                  7.20423,
                                                                                  7.64746],
                                                                   "standard_deviation": 0.82807,
                                                                   "sum": 876.5,
                                                                   "sum_squares": 5223.85,
                                                                   "variance": 0.68569}},
                                    "000001": {   "column_number": 1,
                                                   "datatype": "double",
                                                   "idx": 1,
                                                   "name": "sepal width",
                                                   "optype": "numeric",
                                                   "order": 1,
                                                   "preferred": true,
                                                   "summary": {   "counts": [   [   2,
                                                                                      1],
                                                                                  [   2.2,
                                                                                  ...
                                                               ]]}},
                                    "000004": {   "column_number": 4,
                                                   "datatype": "string",
                                                   "idx": 4,
                                                   "name": "species",
                                                   "optype": "categorical",
                                                   "order": 4,
                                                   "preferred": true,
                                                   "summary": {   "categories": [   [   "Iris-setosa",
                                                                                          50],
                                                                                      [   "Iris-versicolor",
                                                                                          50],
                                                                                      [   "Iris-virginica",
                                                                                          50]],
                                                                   "missing_count": 0},
                                                   "term_analysis": {   "enabled": true}}},
                     "significance_levels": [0.01, 0.05, 0.1]},
"created": "2015-07-28T18:07:37.010000",
"credits": 0.017581939697265625,
"dataset": "dataset/55b7a6749841fa2500000d41",
"dataset_status": true,
"dataset_type": 0,
"description": "",
"excluded_fields": [],
"fields_meta": {   "count": 5,
                    "limit": 1000,
                    "offset": 0,
                    "query_total": 5,
                    "total": 5},
"input_fields": ["000000", "000001", "000002", "000003"],
"locale": "en_US",
"max_columns": 5,
"max_rows": 150,
"name": "iris' dataset correlation",
"objective_field_details": {   "column_number": 4,
                                "datatype": "string",
                                "name": "species",
                                "optype": "categorical",
                                "order": 4},
"out_of_bag": false,
"price": 0.0,
"private": true,
"project": null,
"range": [1, 150],
"replacement": false,
"resource": "correlation/55b7c4e99841fa24f20009bf",
"rows": 150,
"sample_rate": 1.0,
"shared": false,
"size": 4609,
"source": "source/55b7a6729841fa24f100036a",
"source_status": true,
"status": {   "code": 5,
               "elapsed": 274,
               "message": "The correlation has been created",
               "progress": 1.0},
"subscription": true,
"tags": [],
"updated": "2015-07-28T18:07:49.057000",
"white_box": false}

Note that the output in the snippet above has been abbreviated. As you see, the correlations attribute contains the information about each field correlation to the objective field.

Statistical Tests

A statisticaltest resource contains a series of tests that compare the distribution of data in each numeric field of a dataset to certain canonical distributions, such as the normal distribution or Benford's law distribution. Statistical test are useful in tasks such as fraud, normality, or outlier detection.

- Fraud Detection Tests: Benford: This statistical test performs a comparison of the distribution of first significant digits (FSDs) of each value of the field to the Benford's law distribution. Benford's law applies to numerical distributions spanning several orders of magnitude, such as the values found on financial balance sheets. It states that the frequency distribution of leading, or first significant digits (FSD) in such distributions is not uniform. On the contrary, lower digits like 1 and 2 occur disproportionately often as leading significant digits. The test compares the distribution in the field to Bendford's distribution using a Chi-square goodness-of-fit test, and Cho-Gaines d test. If a field has a dissimilar distribution, it may contain anomalous or fraudulent values.

- Normality tests: These tests can be used to confirm the assumption that the data in each field of a dataset is distributed according to a normal distribution. The results are relevant because many statistical and machine learning techniques rely on this assumption. Anderson-Darling: The Anderson-Darling test computes a test statistic based on the difference between the observed cumulative distribution function (CDF) to that of a normal distribution. A significant result indicates that the assumption of normality is rejected. Jarque-Bera: The Jarque-Bera test computes a test statistic based on the third and fourth central moments (skewness and kurtosis) of the data. Again, a significant result indicates that the normality assumption is rejected. Z-score: For a given sample size, the maximum deviation from the mean that would expected in a sampling of a normal distribution can be computed based on the 68-95-99.7 rule. This test simply reports this expected deviation and the actual deviation observed in the data, as a sort of sanity check.

- Outlier tests: Grubbs: When the values of a field are normally distributed, a few values may still deviate from the mean distribution. The outlier tests reports whether at least one value in each numeric field differs significantly from the mean using Grubb's test for outliers. If an outlier is found, then its value will be returned.

The JSON structure for statisticaltest resources is similar to this one

{  "category": 0,
   "clones": 0,
   "code": 200,
   "columns": 5,
   "created": "2015-07-28T18:16:40.582000",
   "credits": 0.017581939697265625,
   "dataset": "dataset/55b7a6749841fa2500000d41",
   "dataset_status": true,
   "dataset_type": 0,
   "description": "",
   "excluded_fields": [],
   "fields_meta": {   "count": 5,
                       "limit": 1000,
                       "offset": 0,
                       "query_total": 5,
                       "total": 5},
   "input_fields": ["000000", "000001", "000002", "000003"],
   "locale": "en_US",
   "max_columns": 5,
   "max_rows": 150,
   "name": "iris' dataset test",
   "out_of_bag": false,
   "price": 0.0,
   "private": true,
   "project": null,
   "range": [1, 150],
   "replacement": false,
   "resource": "statisticaltest/55b7c7089841fa25000010ad",
   "rows": 150,
   "sample_rate": 1.0,
   "shared": false,
   "size": 4609,
   "source": "source/55b7a6729841fa24f100036a",
   "source_status": true,
   "status": {   "code": 5,
                  "elapsed": 302,
                  "message": "The test has been created",
                  "progress": 1.0},
   "subscription": true,
   "tags": [],
   "statistical_tests": {   "ad_sample_size": 1024,
                 "fields": {   "000000": {   "column_number": 0,
                                               "datatype": "double",
                                               "idx": 0,
                                               "name": "sepal length",
                                               "optype": "numeric",
                                               "order": 0,
                                               "preferred": true,
                                               "summary": {   "bins": [   [   4.3,
                                                                                1],
                                                                            [   4.425,
                                                                                4],
                                                                            [   7.9,
                                                                                1]],
                                                               "kurtosis": -0.57357,
                                                               "maximum": 7.9,
                                                               "mean": 5.84333,
                                                               "median": 5.8,
                                                               "minimum": 4.3,
                                                               "missing_count": 0,
                                                               "population": 150,
                                                               "skewness": 0.31175,
                                                               "splits": [   4.51526,
                                                                              4.67252,
                                                                              4.81113,
                                                                              4.89582,
                                                                              ...
                                                                              7.20423,
                                                                              7.64746],
                                                               "standard_deviation": 0.82807,
                                                               "sum": 876.5,
                                                               "sum_squares": 5223.85,
                                                               "variance": 0.68569}},
                                ...
                                "000004": {   "column_number": 4,
                                               "datatype": "string",
                                               "idx": 4,
                                               "name": "species",
                                               "optype": "categorical",
                                               "order": 4,
                                               "preferred": true,
                                               "summary": {   "categories": [   [   "Iris-setosa",
                                                                                      50],
                                                                                  [   "Iris-versicolor",
                                                                                      50],
                                                                                  [   "Iris-virginica",
                                                                                      50]],
                                                               "missing_count": 0},
                                               "term_analysis": {   "enabled": true}}},
                 "fraud": [   {   "name": "benford",
                                   "result": {   "000000": {   "chi_square": {   "chi_square_value": 506.39302,
                                                                                    "p_value": 0,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "cho_gaines": {   "d_statistic": 7.124311073683573,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "distribution": [   0,
                                                                                      0,
                                                                                      0,
                                                                                      22,
                                                                                      61,
                                                                                      54,
                                                                                      13,
                                                                                      0,
                                                                                      0],
                                                                 "negatives": 0,
                                                                 "zeros": 0},
                                                  "000001": {   "chi_square": {   "chi_square_value": 396.76556,
                                                                                    "p_value": 0,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "cho_gaines": {   "d_statistic": 7.503503138331123,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "distribution": [   0,
                                                                                      57,
                                                                                      89,
                                                                                      4,
                                                                                      0,
                                                                                      0,
                                                                                      0,
                                                                                      0,
                                                                                      0],
                                                                 "negatives": 0,
                                                                 "zeros": 0},
                                                  "000002": {   "chi_square": {   "chi_square_value": 154.20728,
                                                                                    "p_value": 0,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "cho_gaines": {   "d_statistic": 3.9229974017266054,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "distribution": [   50,
                                                                                      0,
                                                                                      11,
                                                                                      43,
                                                                                      35,
                                                                                      11,
                                                                                      0,
                                                                                      0,
                                                                                      0],
                                                                 "negatives": 0,
                                                                 "zeros": 0},
                                                  "000003": {   "chi_square": {   "chi_square_value": 111.4438,
                                                                                    "p_value": 0,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "cho_gaines": {   "d_statistic": 4.103257341299901,
                                                                                    "significant": [   true,
                                                                                                        true,
                                                                                                        true]},
                                                                 "distribution": [   76,
                                                                                      58,
                                                                                      7,
                                                                                      7,
                                                                                      1,
                                                                                      1,
                                                                                      0,
                                                                                      0,
                                                                                      0],
                                                                 "negatives": 0,
                                                                 "zeros": 0}}}],
                 "normality": [   {   "name": "anderson_darling",
                                       "result": {   "000000": {   "p_value": 0.02252,
                                                                     "significant": [   false,
                                                                                         true,
                                                                                         true]},
                                                      "000001": {   "p_value": 0.02023,
                                                                     "significant": [   false,
                                                                                         true,
                                                                                         true]},
                                                      "000002": {   "p_value": 0,
                                                                     "significant": [   true,
                                                                                         true,
                                                                                         true]},
                                                      "000003": {   "p_value": 0,
                                                                     "significant": [   true,
                                                                                         true,
                                                                                         true]}}},
                                   {   "name": "jarque_bera",
                                       "result": {   "000000": {   "p_value": 0.10615,
                                                                     "significant": [   false,
                                                                                         false,
                                                                                         false]},
                                                      "000001": {   "p_value": 0.25957,
                                                                     "significant": [   false,
                                                                                         false,
                                                                                         false]},
                                                      "000002": {   "p_value": 0.0009,
                                                                     "significant": [   true,
                                                                                         true,
                                                                                         true]},
                                                      "000003": {   "p_value": 0.00332,
                                                                     "significant": [   true,
                                                                                         true,
                                                                                         true]}}},
                                   {   "name": "z_score",
                                       "result": {   "000000": {   "expected_max_z": 2.71305,
                                                                     "max_z": 2.48369},
                                                      "000001": {   "expected_max_z": 2.71305,
                                                                     "max_z": 3.08044},
                                                      "000002": {   "expected_max_z": 2.71305,
                                                                     "max_z": 1.77987},
                                                      "000003": {   "expected_max_z": 2.71305,
                                                                     "max_z": 1.70638}}}],
                 "outliers": [   {   "name": "grubbs",
                                      "result": {   "000000": {   "p_value": 1,
                                                                    "significant": [   false,
                                                                                        false,
                                                                                        false]},
                                                     "000001": {   "p_value": 0.26555,
                                                                    "significant": [   false,
                                                                                        false,
                                                                                        false]},
                                                     "000002": {   "p_value": 1,
                                                                    "significant": [   false,
                                                                                        false,
                                                                                        false]},
                                                     "000003": {   "p_value": 1,
                                                                    "significant": [   false,
                                                                                        false,
                                                                                        false]}}}],
                 "significance_levels": [0.01, 0.05, 0.1]},
   "updated": "2015-07-28T18:17:11.829000",
   "white_box": false}

Creating deepnets

Deepnets can also solve classification and regression problems. Deepnets are an optimized version of Deep Neural Networks, a class of machine-learned models inspired by the neural circuitry of the human brain. In these classifiers, the input features are fed to a group of “nodes” called a “layer”. Each node is essentially a function on the input that transforms the input features into another value or collection of values. Then the entire layer transforms an input vector into a new “intermediate” feature vector. This new vector is fed as input to another layer of nodes. This process continues layer by layer, until we reach the final “output” layer of nodes, where the output is the network’s prediction: an array of per-class probabilities for classification problems or a single, real value for regression problems.

Deepnets predictions compute a probability associated to each class in the objective field for classification problems. As the rest of models, deepnets can be created from a dataset by calling the corresponding create method:

$deepnet = $api->create_deepnet('dataset/5143a51a37203f2cf7000972',
                                array("name" => "my deepnet",
                                      "objective_field" => "my_objective_field"));

In this example, we created a deepnet named my deepnet and set the objective field to be my_objective_field. Other arguments, like number_of_hidden_layers, learning_rate and missing_numerics can also be specified as attributes in an arguments dictionary at creation time. For a more detailed description of the available attributes and its syntax, please see the Developers API Documentation.

Creating batch predictions

We have shown how to create predictions individually, but when the amount of predictions to make increases, this procedure is far from optimal. In this case, the more efficient way of predicting remotely is to create a dataset containing the input data you want your model to predict from and to give its id and the one of the model to the create_batch_prediction api call

$batch_prediction = $api->$create_batch_prediction($model,
                                                   $dataset,
                                                   array("name"=>"my batch prediction",
                                                         "all_fields"=> true,
                                                         "header": true,
                                                         "confidence": true));

In this example, setting all_fields to true causes the input data to be included in the prediction output, header controls whether a headers line is included in the file or not and confidence set to true causes the confidence of the prediction to be appended. If none of these arguments is given, the resulting file will contain the name of the objective field as a header row followed by the predictions.

As for the rest of resources, the create method will return an incomplete object, that can be updated by issuing the corresponding $api->get_batch_prediction call until it reaches a FINISHED status. Then you can download the created predictions file using

$api->download_batch_prediction('batchprediction/526fc344035d071ea3031d70',
                                'my_dir/my_predictions.csv');

Creating batch centroids

As described in the previous section, it is also possible to make centroids’ predictions in batch. First you create a dataset containing the input data you want your cluster to relate to a centroid. The create_batch_centroid call will need the id of the dataset and the cluster to assign a centroid to each input data

$batch_centroid = $api->create_batch_centroid($cluster,
                                              $dataset,
                                              array("name"=>"my batch centroid",
                                                    "all_fields"=> true,
                                                    "header"=> true));

Creating batch anomaly scores

Input data can also be assigned an anomaly score in batch. You train an anomaly detector with your training data and then build a dataset from your input data. The create_batch_anomaly_score call will need the id of the dataset and of the anomaly detector to assign an anomaly score to each input data instance

$batch_anomaly_score = $api->create_batch_anomaly_score($anomaly,
                                                        $dataset,
                                                        array("name" => "my batch anomaly score"
                                                              "all_fields" => true,
                                                              "header" => true))

Listing Resources

You can list resources with the appropriate api method:

$api->list_sources()
$api->list_datasets()
$api->list_models()
$api->list_predictions()
$api->list_evaluations()
$api->list_ensembles()
$api->list_batch_predictions()
$api->list_clusters()
$api->list_centroids()
$api->list_batch_centroids()
$api->list_anomalies()
$api->list_anomaly_scores()
$api->list_batch_anomaly_scores()
$api->list_deepnets()

you will receive a dictionary with the following keys:

code: If the request is successful you will get a bigml.api.HTTP_OK (200) status code. Otherwise, it will be one of the standard HTTP error codes. See BigML documentation on status codes for more info.
meta: A dictionary including the following keys that can help you paginate listings:
previous: Path to get the previous page or null if there is no previous page.
next: Path to get the next page or null if there is no next page.
offset: How far off from the first entry in the resources is the first one listed in the resources key.
limit: Maximum number of resources that you will get listed in the resources key.
total_count: The total number of resources in BigML.
objects: A list of resources as returned by BigML.
error: If an error occurs and the resource cannot be created, it will contain an additional code and a description of the error. In this case, meta, and resources will be null.

Filtering Resources

You can filter resources in listings using the syntax and fields labeled as filterable in the BigML documentation. for each resource.

A few examples:

Ids of the first 5 sources created before April 1st, 2012:

$api->list_sources("limit=5;created__lt=2012-04-1");

Name of the first 10 datasets bigger than 1MB:

$api->list_datasets("limit=10;size__gt=1048576");

Name of models with more than 5 fields (columns):

$api->list_models("columns__gt=5");

Ids of predictions whose model has not been deleted:

$api->list_predictions("model_status=true");

Ordering Resources

You can order resources in listings using the syntax and fields labeled as sortable in the BigML documentation. for each resource.

A few examples:

Name of sources ordered by size:

$api->list_sources("order_by=size");

Number of instances in datasets created before April 1st, 2012 ordered by size:

$api->list_datasets("created__lt=2012-04-1;order_by=size");

Model ids ordered by number of predictions (in descending order):

$api->list_models("order_by=-number_of_predictions");

Name of predictions ordered by name:

$api->list_predictions("order_by=name");

Updating Resources

When you update a resource, it is returned in a dictionary exactly like the one you get when you create a new one. However the status code will be bigml.api.HTTP_ACCEPTED if the resource can be updated without problems or one of the HTTP standard error codes otherwise:

$api->update_source($source, array("name"=> "new name"));
$api->update_dataset($dataset, array("name"=> "new name"));
$api->update_model($model, array("name"=> "new name"));
$api->update_prediction($prediction, array("name"=> "new name"));
$api->update_evaluation($evaluation, array("name"=> "new name"));
$api->update_ensemble($ensemble, array("name"=> "new name"));
$api->update_batch_prediction($batch_prediction, array("name"=> "new name"));
$api->update_cluster($cluster, array("name"=> "new name"));
$api->update_centroid($centroid, array("name"=> "new name"));
$api->update_batch_centroid($batch_centroid, array("name"=> "new name"));
$api->update_anomaly($anomaly, array("name"=> "new name"));
$api->update_anomaly_score($anomaly_score, array("name": "new name"));
$api->update_batch_anomaly_score($batch_anomaly_score, array("name": "new name"));
$api->update_deepnet($deepnet, array("name": "new name"));

Updates can change resource general properties, such as the name or description attributes of a dataset, or specific properties. As an example, let’s say that your source has a certain field whose contents are numeric integers. BigML will assign a numeric type to the field, but you might want it to be used as a categorical field. You could change its type to categorical by calling:

$api->update_source($source, array("fields"=> array("000001"=> array("optype"=> "categorical"))));

where 000001 is the field id that corresponds to the updated field. You will find detailed information about the updatable attributes of each resource in BigML developer’s documentation.

Deleting Resources

Resources can be deleted individually using the corresponding method for each type of resource

$api->delete_source($source);
$api->delete_dataset($dataset);
$api->delete_model($model);
$api->delete_prediction($prediction);
$api->delete_evaluation($evaluation);
$api->delete_ensemble($ensemble);
$api->delete_batch_prediction($batch_prediction);
$api->delete_cluster($cluster);
$api->delete_centroid($centroid);
$api->delete_batch_centroid($batch_centroid);
$api->delete_anomaly($anomaly);
$api->delete_anomaly_score($anomaly_score);
$api->delete_batch_anomaly_score($batch_anomaly_score);
$api->delete_deepnet($deepnet);

Each of the calls above will return a dictionary with the following keys:

code If the request is successful, the code will be a bigml.api.HTTP_NO_CONTENT (204) status code. Otherwise, it wil be one of the standard HTTP error codes. See the documentation on status codes for more info. error If the request does not succeed, it will contain a dictionary with an error code and a message. It will be null otherwise.

Local Models

You can use the information returned by the API when asking for a model to create a Model object in your own computer that will be able to produce predictions with no further connection to the remote API. The local Model object can be instantiated by using the entire response of the GET call to the API:

$api = new BigML\BigML();

$model = api->get_model('model/538XXXXXXXXXXXXXXXXXXX2');
$local_model = new BigML\Model(model);

It also accepts the model ID as the first argument. In this case, a new connection will be created internally to download the model information.:

$local_model = new BigML\Model("model/538XXXXXXXXXXXXXXXXXXX2");

If you want to use a specific connection object for the remote retrieval, you can set it as the second parameter:

$local_model = new BigML\Model("model/538XXXXXXXXXXXXXXXXXXX2", $api);

To set default storage

$local_model = new BigML\Model("model/538XXXXXXXXXXXXXXXXXXX2", null, 'storagedirectory');

Local Predictions

Once you have a local model you can use to generate predictions locally

$prediction = $local_model->predict(array("petal length"=> 3, "petal width"=> 1));

You can also use the predict_probability function to obtain a probability prediction for each possible class of the objective field:

$predict_probability = $local_model->predict_probability(array("petal width"=> 0.5));

Local predictions have three clear advantages:

Removing the dependency from BigML to make new predictions.
No cost (i.e., you do not spend BigML credits).
Extremely low latency to generate predictions for huge volumes of data.

Local Clusters

You can use the information returned by the API when asking for a cluster to create a Cluster object in your own computer that will be able to produce predictions with no further connection to the remote API. The local Cluster object can be instantiated by using the entire response of the GET call to the API:

$cluster = $api->get_cluster("cluster/539xxxxxxxxxxxxxxxxxxxx18");
$local_cluster = new BigML\Cluster($cluster);

It also accepts the cluster ID as the first argument. This will retrieve the remote cluster information, using an implicitly built BigML() connection object (see the Authentication section for more details on how to set your credentials) and return a Cluster object that you can use to make local centroid predictions.

$local_cluster = new BigML\Cluster("cluster/539xxxxxxxxxxxxxxxxxxxx18");

If you want to use a specfic connection object for the remote retrieval, you can set it as second parameter

$local_cluster = new BigML\Cluster("cluster/539xxxxxxxxxxxxxxxxxxxx18", $api);

To set default storage if you have storage unset in your API object

$local_cluster = new BigML\Cluster("cluster/539xxxxxxxxxxxxxxxxxxxx18", null, $storagedirectory);

(where $storagedirectory is the desired storage location.)

Local Centroids

Using the local cluster object, you can predict the centroid associated to an input data set:

$local_cluster->centroid(array("pregnancies"=> 0,
                               "plasma glucose"=> 118,
                               "blood pressure"=> 84,
                               "triceps skin thickness"=> 47,
                               "insulin"=> 230,
                               "bmi"=> 45.8,
                               "diabetes pedigree"=> 0.551,
                               "age"=> 31,
                               "diabetes"=> "true"));

array('distance'=> 0.454110207355, 'centroid_name'=> 'Cluster 4', 'centroid_id'=> '000004');

You must keep in mind, though, that to obtain a centroid prediction, input data must have values for all the numeric fields. No missing values for the numeric fields are allowed. As in the local model predictions, producing local centroids can be done independently of BigML servers, so no cost or connection latencies are involved.

Local Anomaly Detector

You can also instantiate a local version of a remote anomaly.

$local_anomaly = new BigML\Anomaly('anomaly/502fcbff15526876610002435');

This will retrieve the remote anomaly detector information, using an implicitly built BigML() connection object (see the Authentication section for more details on how to set your credentials) and return an Anomaly object that you can use to make local anomaly scores. If you want to use a specfic connection object for the remote retrieval, you can set it as second parameter

$api = new BigML\BigML("username", "password");
$local_anomaly = new BigML\Anomaly('anomaly/502fcbff15526876610002435',
                             $api);

or even use the remote anomaly information retrieved previously to build the local anomaly detector object

$api = new BigML\BigML()
$anomaly = $api->get_anomaly('anomaly/502fcbff15526876610002435',
                             'limit=-1')

Note that in this example we used a limit=-1 query string for the anomaly retrieval. This ensures that all fields are retrieved by the get method in the same call (unlike in the standard calls where the number of fields returned is limited).

Local Anomaly Scores

Using the local anomaly detector object, you can predict the anomaly score associated to an input data set

$local_anomaly->anomaly_score(array("src_bytes"=> 350))
0.9268527808726705

As in the local model predictions, producing local anomaly scores can be done independently of BigML servers, so no cost or connection latencies are involved.

Local Deepnet

You can also instantiate a local version of a remote Deepnet.

require 'vendor/autoload.php';

$local_deepnet = new Deepnet('deepnet/502fdbff15526876610022435');

This will retrieve the remote deepnet information, using an implicitly built BigML() connection object (see the Authentication section for more details on how to set your credentials) and return a Deepnet object that you can use to make local predictions. If you want to use a specfic connection object for the remote retrieval, you can set it as second parameter

require 'vendor/autoload.php';
$api = new BigML();

$local_deepnet = new Deepnet('deepnet/502fdbcf15526876210042435', $api);

You can also reuse a remote Deepnet JSON structure as previously retrieved to build the local Deepnet object

require 'vendor/autoload.php';

$api = new BigML();
$deepnet = $api->get_deepnet('deepnet/502fdbcf15526876210042435', 'limit=-1');

$local_deepnet = new Deepnet($deepnet);

Note that in this example we used a limit=-1 query string for the deepnet retrieval. This ensures that all fields are retrieved by the get method in the same call (unlike in the standard calls where the number of fields returned is limited).

Local Deepnet Predictions

Using the local deepnet object, you can predict the prediction for an input data set

$local_deepnet->predict(array("petal length" => 2, "sepal length" => 1.5,
                              "petal width" => 0.5, "sepal width" => 0.7));

array('distribution' => array( array('category' => 'Iris-virginica',
                                     'probability' => 0.5041444478857267),
                               array('category' => 'Iris-versicolor',
                                     'probability' => 0.46926542042788333),
                               array('category' => 'Iris-setosa',
                                     'probability' => 0.02659013168639014)),
      'prediction' => 'Iris-virginica',
      'probability' => 0.5041444478857267)

As you can see, the prediction contains the predicted category and the associated probability. It also shows the distribution of probabilities for all the possible categories in the objective field.

To be consistent with the Model class interface, deepnets have also a predict_probability method, which takes two of the same arguments as Model->predict: by_name and compact.

As with local Models, if compact is False (the default), the output is a list of maps, each with the keys prediction and probability mapped to the class name and its associated probability.

So, for example

$local_deepnet->predict_probability(array("petal length" => 2, "sepal length" => 1.5,
                                          "petal width" => 0.5, "sepal width" => 0.7));

array( array('prediction' => 'Iris-setosa', 'probability' => 0.02659013168639014),
       array('prediction' => 'Iris-versicolor', 'probability' => 0.46926542042788333),
       array('prediction' => 'Iris-virginica', 'probability' => 0.5041444478857267))

If compact is True, only the probabilities themselves are returned, as a list in class name order, again, as is the case with local Models.

Local Topic Model

You can also instantiate a local version of a remote topic model.

require 'vendor/autoload.php';

$local_topic_model = new BigML\TopicModel('topicmodel/502fdbcf15526876210042435');

This will retrieve the remote topic model information, using an implicitly built BigML() connection object (see the Authentication section for more details on how to set your credentials) and return a TopicModel object that you can use to obtain local topic distributions. If you want to use a specific connection object for the remote retrieval, you can set it as second parameter

require 'vendor/autoload.php';

$api = new BigML\BigML();
$local_topic_model = new BigML\TopicModel('topicmodel/502fdbcf15526876210042435', $api);

You can also reuse a remote topic model JSON structure as previously retrieved to build the local topic model object

require 'vendor/autoload.php';

$api = new BigML\BigML();
$topic_model = $api->get_topicmodel('topicmodel/502fdbcf15526876210042435', 'limit=-1');

$local_topic_model = new TopicModel($topic_model);

Note that in this example we used a limit=-1 query string for the topic model retrieval. This ensures that all fields are retrieved by the get method in the same call (unlike in the standard calls where the number of fields returned is limited).

Please note you will need to use Composer to import the third-party stemming library used to create local topic models.

Multi Models

Multi Models use a numbers of BigML remote models to build a local version that can be used to generate predictions locally. Predictions are generated combining the outputs of each model

$multimodel = new BigML\MultiModel(array("model/5111xxxxxxxxxxxxxxxxxx12",model/538Xxxxxxxxxxxxxxxxxxx32"));

$multimodel = new BigML\MultiModel(array("model/5111xxxxxxxxxxxxxxxxxx12",model/538Xxxxxxxxxxxxxxxxxxx32"), $api);

or set default storage if you have storage unset in $api

$multimodel = new BigML\MultiModel(array("model/5111xxxxxxxxxxxxxxxxxx12",model/538Xxxxxxxxxxxxxxxxxxx32"), null, $storage);

  $prediction = $multimodel->predict(array("petal length"=> 3, "petal width"=> 1));

The combination method used by default is plurality for categorical predictions and mean value for numerical ones. You can also use:

confidence weighted

$prediction = $multimodel->predict(array("petal length"=> 3, "petal width"=> 1), 1);

that will weight each vote using the confidence/error given by the model to each prediction, or even probability weighted

$prediction = $multimodel->predict(array("petal length"=> 3, "petal width"=> 1), 2);

that weights each vote by using the probability associated to the training distribution at the prediction node.

There’s also a threshold method that uses an additional set of options: threshold and category. The category is predicted if and only if the number of predictions for that category is at least the threshold value. Otherwise, the prediction is plurality for the rest of predicted values.

An example of threshold combination method would be

$prediction = $multimodel->predict(array("petal length"=> 3, "petal width"=> 1), 3, false, array('threshold'=> 3, 'category'=> 'Iris-virginica'));

When making predictions on a test set with a large number of models, batch_predict can be useful to log each model’s predictions in a separated file. It expects a list of input data values and the directory path to save the prediction files in

$multimodel->batch_predict(array("petal length"=> 3, "petal width"=> 1, "petal length"=> 1, "petal width"=> 5.1), "data/predictions");

The predictions generated for each model will be stored in an output file in data/predictions using the syntax model[id of the model]__predictions.csv. For instance, when using model/50c0de043b563519830001c2 to predict, the output file name will be model_50c0de043b563519830001c2__predictions.csv. An additional feature is that using reuse=True as argument will force the function to skip the creation of the file if it already exists. This can be helpful when using repeatedly a bunch of models on the same test set

$multimodel->batch_predict(array("petal length"=> 3, "petal width"=> 1, "petal length"=> 1, "petal width"=> 5.1), "data/predictions", true, true);

Prediction files can be subsequently retrieved and converted into a votes list using batch_votes

$multimodel.batch_votes("data/predictions");

which will return a list of MultiVote objects. Each MultiVote contains a list of predictions.

These votes can be further combined to issue a final prediction for each input data element using the method combine

foreach($multimodel->batch_votes("data/predictions") as $multivote) {
   $prediction = $multivote->combine();
}

Again, the default method of combination is plurality for categorical predictions and mean value for numerical ones. You can also use confidence weighted

$prediction = $multivote->combine(1);

or probability weighted

$prediction = $multivote->combine(2);

You can also get a confidence measure for the combined prediction

$prediction = $multivote->combine(0, true);

For classification, the confidence associated to the combined prediction is derived by first selecting the model’s predictions that voted for the resulting prediction and computing the weighted average of their individual confidence. Nevertheless, when probability weighted is used, the confidence is obtained by using each model’s distribution at the prediction node to build a probability distribution and combining them. The confidence is then computed as the wilson score interval of the combined distribution (using as total number of instances the sum of all the model’s distributions original instances at the prediction node)

In regression, all the models predictions’ confidences contribute to the weighted average confidence.

Local Ensembles

Remote ensembles can also be used locally through the Ensemble class. The simplest way to access an existing ensemble and using it to predict locally is

$ensemble = new BigML\Ensemble("ensemble/53dxxxxxxxxxxxxxxxxxxafa");

$ensemble->predict(array("petal length"=>3, "petal width"=> 1));

This call will download all the ensemble related info and store it in a ./storage directory ready to be used to predict. As in MultipleModel, several prediction combination methods are available, and you can choose another storage directory or even avoid storing at all, for instance

$api = new BigML("username", "password", false, "storagedirectory");

ensemble = $api->create_ensemble('dataset/5143a51a37203f2cf7000972');

$ensemble = new BigML\Ensemble($ensemble, $api);

$ensemble->predict(array("petal length"=>3, "petal width"=> 1), true, 1);

creates a new ensemble and stores its information in ./storagedirectory folder. Then this information is used to predict locally using the confidence weighted method.

Similarly, local ensembles can also be created by giving a list of models to be combined to issue the final prediction

$ensemble = new BigML\Ensemble(array('model/50c0de043b563519830001c2','model/50c0de043b5635198300031b'));

$ensemble->predict(array("petal length": 3, "petal width": 1));

Also, an ensemble previously stored in a directory can be used to build a local Ensemble object. In next example, the "storagedirectory" directory contains a JSON file ensemble_5143a51a37203f2cf7000928 and some additional JSON files, one per model contained in the ensemble, named after their IDs where slashes have been replaced by underscores.

$api = new BigML("username", "password", false, "storagedirectory");

$ensemble = $api->retrieve_resource('ensemble/5143a51a37203f2cf7000928');

$local_ensemble = new BigML\Ensemble($ensemble, api=$api);

$local_ensemble->predict(array("petal length"=>3, "petal width"=> 1), true, 1);

Local ensembles also offer the predict_probability function to obtain a probability prediction for each possible class of the objective field

$ensemble->predict_probability(array("petal width"=> 0.5));

Rule Generation

You can also use a local model to generate a IF-THEN rule set that can be very helpful to understand how the model works internally

$local_model->rules();

IF petal_length > 2.45 AND
   IF petal_width > 1.65 AND
      IF petal_length > 5.05 THEN
         species = Iris-virginica
      IF petal_length <= 5.05 AND
         IF sepal_width > 2.9 AND
            IF sepal_length > 5.95 AND
               IF petal_length > 4.95 THEN
                  species = Iris-versicolor
               IF petal_length <= 4.95 THEN
                  species = Iris-virginica
            IF sepal_length <= 5.95 THEN
               species = Iris-versicolor
         IF sepal_width <= 2.9 THEN
            species = Iris-virginica
   IF petal_width <= 1.65 AND
      IF petal_length > 4.95 AND
         IF sepal_length > 6.05 THEN
            species = Iris-virginica
         IF sepal_length <= 6.05 AND
            IF sepal_width > 2.45 THEN
              species = Iris-versicolor
            IF sepal_width <= 2.45 THEN
              species = Iris-virginica
      IF petal_length <= 4.95 THEN
         species = Iris-versicolor
IF petal_length <= 2.45 THEN
   species = Iris-setosa

Testing

To run the test you need phpunit that you can download from here http://phpunit.de/#download.

Make sure that you have set up your authentication variables in your environment.

To run all tests

cd tests
configtests.xml
phpunit.phar --configuration configtests.xml

To Run a specific test

phpunit.phar test_01_prediction.php

bigml / bigml-php

Maintainers

Details