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
Python 2.7 and Python 3 are currently supported by these bindings.
The basic third-party dependencies are the requests, poster, unidecode and requests-toolbelt 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.
Additional numpy and scipy libraries are needed in case you want to use local predictions for regression models (including the error information) using proportional missing strategy. As these are quite heavy libraries and they are so seldom used, they are not included in the automatic installation dependencies. The test suite includes some tests that will need these libraries to be installed.
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 below. With that in place, you can run the test suite simply by issuing
$ python setup.py nosetests
Some tests need the numpy and scipy libraries to be installed too. They are not automatically installed as a dependency, as they are quite heavy and very seldom used.
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. 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
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')
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 length': 2.45, 'petal width': 1.75})
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
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 length': 2.45, 'petal width': 1.75})
This method retrieves the remote object in its latest state and updates
the variable used as argument with this information. 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.
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. You can also check other simple examples in the following documents:
- model 101
- logistic regression 101
- ensemble 101
- cluster 101
- anomaly detector 101
- association 101
- topic model 101
- time series 101
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:
- Fork the project on github.com.
- Create a new branch.
- Commit changes to the new branch.
- Send a pull request.
For details on the underlying API, see the BigML API documentation.