Python bindings for BigML.io

Overview

BigML Python Bindings

BigML makes machine learning easy by taking care of the details required to add data-driven decisions and predictive power to your company. Unlike other machine learning services, BigML creates beautiful predictive models that can be easily understood and interacted with.

These BigML Python bindings allow you to interact with BigML.io, the API for BigML. You can use it to easily create, retrieve, list, update, and delete BigML resources (i.e., sources, datasets, models and, predictions). For additional information, see the full documentation for the Python bindings on Read the Docs.

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

Support

Please report problems and bugs to our BigML.io issue tracker.

Discussions about the different bindings take place in the general BigML mailing list. Or join us in our Campfire chatroom.

Requirements

Only Python 3 versions are currently supported by these bindings. Support for Python 2.7.X ended in version 4.32.3.

The basic third-party dependencies are the requests, unidecode and requests-toolbelt bigml-chronos, numpy and scipy libraries. These libraries are automatically installed during the setup. Support for Google App Engine has been added as of version 3.0.0, using the urlfetch package instead of requests.

The bindings will also use simplejson if you happen to have it installed, but that is optional: we fall back to Python's built-in JSON libraries is simplejson is not found.

Also in order to use local Topic Model predictions, you will need to install pystemmer. Using the pip install command for this library can produce an error if your system lacks the correct developer tools to compile it. In Windows, the error message will include a link pointing to the needed Visual Studio version and in OSX you'll need to install the Xcode developer tools.

Installation

To install the latest stable release with pip

$ pip install bigml

You can also install the development version of the bindings directly from the Git repository

$ pip install -e git://github.com/bigmlcom/python.git#egg=bigml_python

Running the Tests

The test will be run using nose , that is installed on setup, and you'll need to set up your authentication via environment variables, as explained in the authentication section. Also some of the tests need other environment variables like BIGML_ORGANIZATION to test calls when used by Organization members and BIGML_EXTERNAL_CONN_HOST, BIGML_EXTERNAL_CONN_PORT, BIGML_EXTERNAL_CONN_DB, BIGML_EXTERNAL_CONN_USER, BIGML_EXTERNAL_CONN_PWD and BIGML_EXTERNAL_CONN_SOURCE in order to test external data connectors.

With that in place, you can run the test suite simply by issuing

$ python setup.py nosetests

Additionally, Tox can be used to automatically run the test suite in virtual environments for all supported Python versions. To install Tox:

$ pip install tox

Then run the tests from the top-level project directory:

$ tox

Importing the module

To import the module:

import bigml.api

Alternatively you can just import the BigML class:

from bigml.api import BigML

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.

Unix and MacOS

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=ae579e7e53fb9abd646a6ff8aa99d4afe83ac291

refer to the next chapters to know how to do that in other operating systems.

With that environment set up, connecting to BigML is a breeze:

from bigml.api import BigML
api = BigML()

Otherwise, you can initialize directly when instantiating the BigML class as follows:

api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291')

These credentials will allow you to manage any resource in your user environment.

In BigML a user can also work for an organization. In this case, the organization administrator should previously assign permissions for the user to access one or several particular projects in the organization. Once permissions are granted, the user can work with resources in a project according to his permission level by creating a special constructor for each project. The connection constructor in this case should include the project ID:

api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291',
            project='project/53739b98d994972da7001d4a')

If the project used in a connection object does not belong to an existing organization but is one of the projects under the user's account, all the resources created or updated with that connection will also be assigned to the specified project.

When the resource to be managed is a project itself, the connection needs to include the corresponding``organization ID``:

api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291',
            organization='organization/53739b98d994972da7025d4a')

Authentication on Windows

The credentials should be permanently stored in your system using

setx BIGML_USERNAME myusername
setx BIGML_API_KEY ae579e7e53fb9abd646a6ff8aa99d4afe83ac291

Note that setx will not change the environment variables of your actual console, so you will need to open a new one to start using them.

Authentication on Jupyter Notebook

You can set the environment variables using the %env command in your cells:

%env BIGML_USERNAME=myusername
%env BIGML_API_KEY=ae579e7e53fb9abd646a6ff8aa99d4afe83ac291

Alternative domains

The main public domain for the API service is bigml.io, but there are some alternative domains, either for Virtual Private Cloud setups or the australian subdomain (au.bigml.io). You can change the remote server domain to the VPC particular one by either setting the BIGML_DOMAIN environment variable to your VPC subdomain:

export BIGML_DOMAIN=my_VPC.bigml.io

or setting it when instantiating your connection:

api = BigML(domain="my_VPC.bigml.io")

The corresponding SSL REST calls will be directed to your private domain henceforth.

You can also set up your connection to use a particular PredictServer only for predictions. In order to do so, you'll need to specify a Domain object, where you can set up the general domain name as well as the particular prediction domain name.

from bigml.domain import Domain
from bigml.api import BigML

domain_info = Domain(prediction_domain="my_prediction_server.bigml.com",
                     prediction_protocol="http")

api = BigML(domain=domain_info)

Finally, you can combine all the options and change both the general domain server, and the prediction domain server.

from bigml.domain import Domain
from bigml.api import BigML
domain_info = Domain(domain="my_VPC.bigml.io",
                     prediction_domain="my_prediction_server.bigml.com",
                     prediction_protocol="https")

api = BigML(domain=domain_info)

Some arguments for the Domain constructor are more unsual, but they can also be used to set your special service endpoints:

  • protocol (string) Protocol for the service (when different from HTTPS)
  • verify (boolean) Sets on/off the SSL verification
  • prediction_verify (boolean) Sets on/off the SSL verification for the prediction server (when different from the general SSL verification)

Note that the previously existing dev_mode flag:

api = BigML(dev_mode=True)

that caused the connection to work with the Sandbox Development Environment has been deprecated because this environment does not longer exist. The existing resources that were previously created in this environment have been moved to a special project in the now unique Production Environment, so this flag is no longer needed to work with them.

Quick Start

Imagine that you want to use this csv file containing the Iris flower dataset to predict the species of a flower whose petal length is 2.45 and whose petal width is 1.75. 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

You can easily generate a prediction following these steps:

from bigml.api import BigML

api = BigML()

source = api.create_source('./data/iris.csv')
dataset = api.create_dataset(source)
model = api.create_model(dataset)
prediction = api.create_prediction(model, \
    {"petal width": 1.75, "petal length": 2.45})

You can then print the prediction using the pprint method:

>>> api.pprint(prediction)
species for {"petal width": 1.75, "petal length": 2.45} is Iris-setosa

Certainly, any of the resources created in BigML can be configured using several arguments described in the API documentation. Any of these configuration arguments can be added to the create method as a dictionary in the last optional argument of the calls:

from bigml.api import BigML

api = BigML()

source_args = {"name": "my source",
     "source_parser": {"missing_tokens": ["NULL"]}}
source = api.create_source('./data/iris.csv', source_args)
dataset_args = {"name": "my dataset"}
dataset = api.create_dataset(source, dataset_args)
model_args = {"objective_field": "species"}
model = api.create_model(dataset, model_args)
prediction_args = {"name": "my prediction"}
prediction = api.create_prediction(model, \
    {"petal width": 1.75, "petal length": 2.45},
    prediction_args)

The iris dataset has a small number of instances, and usually will be instantly created, so the api.create_ calls will probably return the finished resources outright. As BigML's API is asynchronous, in general you will need to ensure that objects are finished before using them by using api.ok.

from bigml.api import BigML

api = BigML()

source = api.create_source('./data/iris.csv')
api.ok(source)
dataset = api.create_dataset(source)
api.ok(dataset)
model = api.create_model(dataset)
api.ok(model)
prediction = api.create_prediction(model, \
    {"petal width": 1.75, "petal length": 2.45})

Note that the prediction call is not followed by the api.ok method. Predictions are so quick to be generated that, unlike the rest of resouces, will be generated synchronously as a finished object.

The example assumes that your objective field (the one you want to predict) is the last field in the dataset. If that's not he case, you can explicitly set the name of this field in the creation call using the objective_field argument:

from bigml.api import BigML

api = BigML()

source = api.create_source('./data/iris.csv')
api.ok(source)
dataset = api.create_dataset(source)
api.ok(dataset)
model = api.create_model(dataset, {"objective_field": "species"})
api.ok(model)
prediction = api.create_prediction(model, \
    {'sepal length': 5, 'sepal width': 2.5})

You can also generate an evaluation for the model by using:

test_source = api.create_source('./data/test_iris.csv')
api.ok(test_source)
test_dataset = api.create_dataset(test_source)
api.ok(test_dataset)
evaluation = api.create_evaluation(model, test_dataset)
api.ok(evaluation)

If you set the storage argument in the api instantiation:

api = BigML(storage='./storage')

all the generated, updated or retrieved resources will be automatically saved to the chosen directory.

Alternatively, you can use the export method to explicitly download the JSON information that describes any of your resources in BigML to a particular file:

api.export('model/5acea49a08b07e14b9001068',
           filename="my_dir/my_model.json")

This example downloads the JSON for the model and stores it in the my_dir/my_model.json file.

In the case of models that can be represented in a PMML syntax, the export method can be used to produce the corresponding PMML file.

api.export('model/5acea49a08b07e14b9001068',
           filename="my_dir/my_model.pmml",
           pmml=True)

You can also retrieve the last resource with some previously given tag:

api.export_last("foo",
                resource_type="ensemble",
                filename="my_dir/my_ensemble.json")

which selects the last ensemble that has a foo tag. This mechanism can be specially useful when retrieving retrained models that have been created with a shared unique keyword as tag.

For a descriptive overview of the steps that you will usually need to follow to model your data and obtain predictions, please see the basic Workflow sketch document. You can also check other simple examples in the following documents:

Additional Information

We've just barely scratched the surface. For additional information, see the full documentation for the Python bindings on Read the Docs. Alternatively, the same documentation can be built from a local checkout of the source by installing Sphinx ($ pip install sphinx) and then running

$ cd docs
$ make html

Then launch docs/_build/html/index.html in your browser.

How to Contribute

Please follow the next steps:

  1. Fork the project on github.com.
  2. Create a new branch.
  3. Commit changes to the new branch.
  4. Send a pull request.

For details on the underlying API, see the BigML API documentation.

Issues
  • Addition of `predict_probability` for supervised models

    Addition of `predict_probability` for supervised models

    With the changes requested by @mmerce in her initial mini-review

    opened by charleslparker 11
  • Source creation from inline data

    Source creation from inline data

    opened by cheesinglee 9
  • Use prediction_domain for all prediction methods

    Use prediction_domain for all prediction methods

    Currently, when the api is instantiated with a value for prediction_domain, that value is only used for calls to create_prediction, and not other prediction-like methods such as create_batch_prediction, create_centroid, create_anomaly_score, etc.

    This PR changes the handlers for those methods to use the value for prediction_domain.

    opened by cheesinglee 5
  • Inconsistency With Remote Predictions in Anomaly Detectors

    Inconsistency With Remote Predictions in Anomaly Detectors

    In datasets where there are a significant number of categorical missing values, local predictions for anomaly detectors are dramatically different from remote predictions:

    In [3]: from bigml.anomaly import Anomaly                                       
    
    In [4]: from bigml.api import BigML                                             
    
    In [5]: data = csvload('shapsplain/lc.csv')                                     
    
    In [6]: jt = jload('shapsplain/testtree.json')                                  
    
    In [7]: rid = jt['resource']                                                    
    
    In [8]: api = BigML()                                                           
    
    In [9]: api.create_anomaly_score(rid, data[1])['object']['score']               
    Out[9]: 0.47451
    
    In [10]: local = Anomaly({'object': jt, 'resource': jt['resource']})            
    
    In [11]: local.anomaly_score(data[1])                                           
    Out[11]: 0.6618801118575603
    

    Specifically, the issue appears to be here:

    https://github.com/bigmlcom/python/blob/master/bigml/predicate.py#L242

    The above tree has predicates on categorical variables with the in operator. If there's a null in the input data and a null in the set of true values, this predicate still evaluates to false, as we drop into the condition above, which relies on the .missing attribute of the predicate, which does not get set in this case.

    The solution appears to be to set it, up here:

    https://github.com/bigmlcom/python/blob/master/bigml/predicate.py#L136

    Something like an additional clause:

    ...
            elif operation == 'in' and None in value:
                self.missing = True
    

    When I do that, consistency is restored:

    
    In [2]: data = csvload('shapsplain/lc.csv')                                     
    
    In [3]: jt = jload('shapsplain/testtree.json')                                  
    
    In [4]: local = Anomaly({'object': jt, 'resource': jt['resource']})             
    
    In [5]: local.anomaly_score(data[1])                                            
    Out[5]: 0.4745112731029698
    

    I can submit a PR, but I was a bit scared as that's fairly deep in the logic here. Let me know if that looks like a good solution.

    /cc @jaor @unmonoqueteclea

    opened by charleslparker 4
  • Input datetimes in local predictions

    Input datetimes in local predictions

    With this PR, the local models will accept raw datetime inputs. Currently, it only works with models. After this is reviewed, I will add the option to the rest of supervised-models

    opened by unmonoqueteclea 4
  • README.rst: Add syntax highlighting

    README.rst: Add syntax highlighting

    See at https://github.com/msabramo/python/blob/patch-1/README.rst

    opened by msabramo 4
  • Add tox support

    Add tox support

    Add support for Tox (http://tox.testrun.org/) to run tests in multiple virtualenvs. To use it, "pip install tox" and then run "tox" from the root directory.

    Note that tox checks the exit status from the test command (lettuce) to determine pass/fail, but the latest version of lettuce (0.2.5) erroneously exits with a non-zero exit status indicating an error. So, tox will report failures even though the test suite is passing.

    opened by njwilson 3
Owner
BigML Inc, Machine Learning made easy
BigML Inc, Machine Learning made easy
Python bindings for ArrayFire: A general purpose GPU library.

ArrayFire Python Bindings ArrayFire is a high performance library for parallel computing with an easy-to-use API. It enables users to write scientific

ArrayFire 380 Nov 3, 2021
Disqus API bindings for Python

disqus-python Let's start with installing the API: pip install disqus-python Use the API by instantiating it, and then calling the method through dott

DISQUS 159 Oct 22, 2021
Python bindings to the Syncthing REST interface.

python-syncthing Python bindings to the Syncthing REST interface. Python API Documentation Syncthing Syncthing REST Documentation Syncthing Forums $ p

Blake VandeMerwe 55 Sep 17, 2021
Python bindings for LibreTranslate

Python bindings for LibreTranslate

Argos Open Tech 16 Nov 18, 2021
pylunasvg - Python bindings for lunasvg

pylunasvg - Python bindings for lunasvg Pylunasvg is a simple wrapper around lunasvg that uses pybind11 to create python bindings. All public API of t

Eren 3 Sep 28, 2021
Python bindings for swm-core client REST API

Python bindings for swm-core client REST API Description Sky Port is an universal bus between user software and compute resources. It can also be cons

Sky Workflows 1 Nov 28, 2021
Official Python client for the MonkeyLearn API. Build and consume machine learning models for language processing from your Python apps.

MonkeyLearn API for Python Official Python client for the MonkeyLearn API. Build and run machine learning models for language processing from your Pyt

MonkeyLearn 147 Nov 27, 2021
PRAW, an acronym for "Python Reddit API Wrapper", is a python package that allows for simple access to Reddit's API.

PRAW: The Python Reddit API Wrapper PRAW, an acronym for "Python Reddit API Wrapper", is a Python package that allows for simple access to Reddit's AP

Python Reddit API Wrapper Development 2.7k Nov 29, 2021
PRAW, an acronym for "Python Reddit API Wrapper", is a python package that allows for simple access to Reddit's API.

PRAW: The Python Reddit API Wrapper PRAW, an acronym for "Python Reddit API Wrapper", is a Python package that allows for simple access to Reddit's AP

Python Reddit API Wrapper Development 2.7k Nov 25, 2021
alpaca-trade-api-python is a python library for the Alpaca Commission Free Trading API.

alpaca-trade-api-python is a python library for the Alpaca Commission Free Trading API. It allows rapid trading algo development easily, with support for both REST and streaming data interfaces

Alpaca 1.2k Nov 26, 2021
🖥️ Python - P1 Monitor API Asynchronous Python Client

??️ Asynchronous Python client for the P1 Monitor

Klaas Schoute 2 Nov 29, 2021
Volt is yet another discord api wrapper for Python. It supports python 3.8 +

Volt Volt is yet another discord api wrapper for Python. It supports python 3.8 + How to install [Currently Not Supported.] pip install volt.py Speed

Minjun Kim (Lapis0875) 13 Sep 25, 2021
Bagas Mirror&Leech Bot is a multipurpose Telegram Bot written in Python for mirroring files on the Internet to our beloved Google Drive. Based on python-aria-mirror-bot

- [ MAYBE UPDATE & ADD MORE MODULE ] Bagas Mirror&Leech Bot Bagas Mirror&Leech Bot is a multipurpose Telegram Bot written in Python for mirroring file

null 4 Nov 23, 2021
A python Discord wrapper made in well, python.

discord.why A python Discord wrapper made in well, python. Made to be used by devs who want something a bit more, general. Basic Examples Sending a me

HellSec 5 Nov 13, 2021
A wrapper for aqquiring Choice Coin directly through a Python Terminal. Leverages the TinyMan Python-SDK.

CHOICE_TinyMan_Wrapper A wrapper that allows users to acquire Choice Coin directly through their Terminal using ALGO and various Algorand Standard Ass

Choice Coin 7 Nov 23, 2021
Python On WhatsApp - Run your python codes on whatsapp along with talking to a chatbot

Python On WhatsApp Run your python codes on whatsapp along with talking to a chatbot This is a small python project to run python on whatsapp. and i c

Prajjwal Pathak 5 Nov 13, 2021
AWS SDK for Python

Boto3 - The AWS SDK for Python Boto3 is the Amazon Web Services (AWS) Software Development Kit (SDK) for Python, which allows Python developers to wri

the boto project 6.9k Nov 26, 2021