bigml 4.1.0

An open source binding to BigML.io, the public BigML API

BigML Python Bindings
=====================

`BigML <https://bigml.com>`_ 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 <https://bigml.com/gallery/models>`_ that
can be easily understood and interacted with.

These BigML Python bindings allow you to interact with
`BigML.io <https://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 <http://bigml.readthedocs.org>`_.

This module is licensed under the `Apache License, Version
2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_.

Support
-------

Please report problems and bugs to our `BigML.io issue
tracker <https://github.com/bigmlcom/io/issues>`_.

Discussions about the different bindings take place in the general
`BigML mailing list <http://groups.google.com/group/bigml>`_. Or join us
in our `Campfire chatroom <https://bigmlinc.campfirenow.com/f20a0>`_.

Requirements
------------

Python 2.7 and Python 3 are currently supported by these bindings.

The basic third-party dependencies are the
`requests <https://github.com/kennethreitz/requests>`_,
`poster <http://atlee.ca/software/poster/#download>`_ and
`unidecode <http://pypi.python.org/pypi/Unidecode/#downloads>`_ 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 <http://www.numpy.org/>`_ and
`scipy <http://www.scipy.org/>`_ 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.

Installation
------------

To install the latest stable release with
`pip <http://www.pip-installer.org/>`_

.. code-block:: bash

$ pip install bigml

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

.. code-block:: bash

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

Running the Tests
-----------------

To run the tests you will need to install
`lettuce <http://packages.python.org/lettuce/tutorial/simple.html>`_

.. code-block:: bash

$ pip install lettuce

and set up your authentication via environment variables, as explained
below. With that in place, you can run the test suite simply by

.. code-block:: bash

$ cd tests
$ lettuce

Some tests need the `numpy <http://www.numpy.org/>`_ and
`scipy <http://www.scipy.org/>`_ 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:

.. code-block:: python

import bigml.api

Alternatively you can just import the BigML class:

.. code-block:: python

from bigml.api import BigML

Authentication
--------------

All the requests to BigML.io must be authenticated using your username
and `API key <https://bigml.com/account/apikey>`_ 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:

.. code-block:: bash

export BIGML_USERNAME=myusername
export BIGML_API_KEY=ae579e7e53fb9abd646a6ff8aa99d4afe83ac291

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

.. code-block:: python

from bigml.api import BigML
api = BigML()

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

.. code-block:: python

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

Also, you can initialize the library to work in the Sandbox environment by
passing the parameter ``dev_mode``:

.. code-block:: python

api = BigML(dev_mode=True)

Quick Start
-----------

Imagine that you want to use `this csv
file <https://static.bigml.com/csv/iris.csv>`_ containing the `Iris
flower dataset <http://en.wikipedia.org/wiki/Iris_flower_data_set>`_ 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

You can easily generate a prediction following these steps:

.. code-block:: python

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, {'sepal length': 5, 'sepal width': 2.5})

You can then print the prediction using the ``pprint`` method:

.. code-block:: python

>>> api.pprint(prediction)
species for {"sepal width": 2.5, "sepal length": 5} is Iris-virginica

Additional Information
----------------------

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

.. code-block:: bash

$ 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 <https://github.com/bigmlcom/python/pulls>`_.


For details on the underlying API, see the
`BigML API documentation <https://bigml.com/developers>`_.


.. :changelog:

History
-------

4.1.0 (2015-04-14)
~~~~~~~~~~~~~~~~~~

- Adding median based predictions to ensembles.

4.0.2 (2015-04-12)
~~~~~~~~~~~~~~~~~~

- Fixing bug: multimodels median predictions failed.

4.0.1 (2015-04-10)
~~~~~~~~~~~~~~~~~~

- Adding support for median-based predictions in MultiModels.

4.0.0 (2015-04-10)
~~~~~~~~~~~~~~~~~~

- Python 3 added to supported Python versions.
- Test suite migrated to nose.


3.0.3 (2015-04-08)
~~~~~~~~~~~~~~~~~

- Changing setup to ensure compatible Python and requests versions.
- Hiding warnings when SSL verification is disabled.

3.0.2 (2015-03-26)
~~~~~~~~~~~~~~~~~~

- Adding samples as Fields generator resources

3.0.1 (2015-03-17)
~~~~~~~~~~~~~~~~~~

- Changing the Ensemble object init method to use the max_models argument
also when loading the ensemble fields to trigger garbage collection.

3.0.0 (2015-03-04)
~~~~~~~~~~~~~~~~~~

- Adding Google App Engine support for remote REST calls.
- Adding cache_get argument to Ensemble constructor to allow getting
local model objects from cache.

2.2.0 (2015-02-26)
~~~~~~~~~~~~~~~~~~

- Adding lists of local models as argument for the local ensemble
constructor.

2.1.0 (2015-02-22)
~~~~~~~~~~~~~~~~~~

- Adding distribution and median to ensembles' predictions output.

2.0.0 (2015-02-12)
~~~~~~~~~~~~~~~~~~

- Adding REST API calls for samples.

1.10.8 (2015-02-10)
~~~~~~~~~~~~~~~~~~~

- Adding distribution units to the predict method output of the local model.

1.10.7 (2015-02-07)
~~~~~~~~~~~~~~~~~~~

- Extending the predict method in local models to get multiple predictions.
- Changing the local model object to add the units used in the distribution
and the add_median argument in the predict method.

1.10.6 (2015-02-06)
~~~~~~~~~~~~~~~~~~~

- Adding the median as prediction for the local model object.

1.10.5 (2014-01-29)
~~~~~~~~~~~~~~~~~~~

- Fixing bug: centroids failed when predicted from local clusters with
summary fields.

1.10.4 (2014-01-17)
~~~~~~~~~~~~~~~~~~~

- Improvements in docs presentation and content.
- Adding tree_CSV method to local model to output the nodes information
in CSV format.

1.10.3 (2014-01-16)
~~~~~~~~~~~~~~~~~~~

- Fixing bug: local ensembles were not retrieved from the stored JSON file.
- Adding the ability to construct local ensembles from any existing JSON file
describing an ensemble structure.

1.10.2 (2014-01-15)
~~~~~~~~~~~~~~~~~~~

- Source creation from inline data.

1.10.1 (2014-12-29)
~~~~~~~~~~~~~~~~~~~

- Fixing bug: source upload failed in old Python versions.

1.10.0 (2014-12-29)
~~~~~~~~~~~~~~~~~~~

- Refactoring the BigML class before adding the new project resource.
- Changing the ok and check_resource methods to download lighter resources.
- Fixing bug: cluster summarize for 1-centroid clusters.
- Fixing bug: adapting to new SSL verification in Python 2.7.9.

1.9.8 (2014-12-01)
~~~~~~~~~~~~~~~~~~

- Adding impurity to Model leaves, and a new method to select impure leaves.
- Fixing bug: the Model, Cluster and Anomaly objects had no resource_id
attribute when built from a local resource JSON structure.

1.9.7 (2014-11-24)
~~~~~~~~~~~~~~~~~~

- Adding method in Anomaly object to build the filter to exclude anomalies
from the original dataset.
- Basic code refactorization for initial resources structure.

1.9.6 (2014-11-09)
~~~~~~~~~~~~~~~~~~

- Adding BIGML_PROTOCOL, BIGML_SSL_VERIFY and BIGML_PREDICTION_SSL_VERIFY
environment variables to change the default corresponding values in
customized private environments.

1.9.5 (2014-11-03)
~~~~~~~~~~~~~~~~~~

- Fixing bug: summarize method breaks for clusters with text fields.

1.9.4 (2014-10-27)
~~~~~~~~~~~~~~~~~~

- Changing MultiModel class to return in-memory list of predictions.

1.9.3 (2014-10-23)
~~~~~~~~~~~~~~~~~~

- Improving Fields and including the new Cluster and
Anomalies fields structures as fields resources.
- Improving ModelFields to filter missing values from input data.
- Forcing garbage collection in local ensemble to lower memory usage.

1.9.2 (2014-10-13)
~~~~~~~~~~~~~~~~~~

- Changing some Fields exceptions handling.
- Refactoring api code to handle create, update and delete methods dynamically.
- Adding connection info string for printing.
- Improving tests information.

1.9.1 (2014-10-10)
~~~~~~~~~~~~~~~~~~

- Adding the summarize and statistics_CSV methods to local cluster object.

1.9.0 (2014-10-02)
~~~~~~~~~~~~~~~~~~

- Adding the batch anomaly score REST API calls.

1.8.0 (2014-09-09)
~~~~~~~~~~~~~~~~~~

- Adding the anomaly detector and anomaly score REST API calls.
- Adding the local anomaly detector.

1.7.0 (2014-08-29)
~~~~~~~~~~~~~~~~~~

- Adding to local model predictions the ability to use the new
missing-combined operators.

1.6.7 (2014-08-05)
~~~~~~~~~~~~~~~~~~

- Fixing bug in corner case of model predictions using proportional missing
strategy.
- Adding the unique path to the first missing split to the predictions using
proportional missing strategy.

1.6.6 (2014-07-31)
~~~~~~~~~~~~~~~~~~

- Improving the locale handling to avoid problems when logging to console under
Windows.

1.6.5 (2014-07-26)
~~~~~~~~~~~~~~~~~~

- Adding stats method to Fields to show fields statistics.
- Adding api method to create a source from a batch prediction.

1.6.4 (2014-07-25)
~~~~~~~~~~~~~~~~~~

- Changing the create methods to check if origin resources are finished
by downloading no fields information.

1.6.3 (2014-07-24)
~~~~~~~~~~~~~~~~~~

- Changing some variable names in the predict method (add_count, add_path) and
the prediction structure to follow other bindigns naming.

1.6.2 (2014-07-19)
~~~~~~~~~~~~~~~~~~

- Building local model from a JSON model file.
- Predictions output can contain confidence, distribution, instances and/or
rules.

1.6.1 (2014-07-09)
~~~~~~~~~~~~~~~~~~

- Fixing bug: download_dataset method did not return content when no filename
was provided.

1.6.0 (2014-07-03)
~~~~~~~~~~~~~~~~~~

- Fixing bug: check valid parameter in distribution merge function.
- Adding downlod_dataset method to api to export datasets to CSV.

1.5.1 (2014-06-13)
~~~~~~~~~~~~~~~~~~

- Fixing bug: local clusters' centroid method crashes when text or categorical
fields are not present in input data.

1.5.0 (2014-06-05)
~~~~~~~~~~~~~~~~~~

- Adding local cluster to produce centroid predictions locally.

1.4.4 (2014-05-23)
~~~~~~~~~~~~~~~~~~

- Adding shared urls to datasets.
- Fixing bug: error renaming variables.

1.4.3 (2014-05-22)
~~~~~~~~~~~~~~~~~~

- Adding the ability to change the remote server domain in the API
connection constructor (for VPCs).
- Adding the ability to generate datasets from clusters.

1.4.2 (2014-05-20)
~~~~~~~~~~~~~~~~~~

- Fixing bug when using api.ok method for centroids and batch centroids.

1.4.1 (2014-05-19)
~~~~~~~~~~~~~~~~~~

- Docs and test updates.

1.4.0 (2014-05-14)
~~~~~~~~~~~~~~~~~~

- Adding REST methods to manage clusters, centroids and batch centroids.

1.3.1 (2014-05-06)
~~~~~~~~~~~~~~~~~~

- Adding the average_confidence method to local models.
- Fixing bug in pprint for predictions with input data keyed by field names.

1.3.0 (2014-04-07)
~~~~~~~~~~~~~~~~~~

- Changing Fields object constructor to accept also source, dataset or model
resources.

1.2.2 (2014-04-01)
~~~~~~~~~~~~~~~~~~

- Changing error message when create_source calls result in http errors
to standarize them.
- Simplifying create_prediction calls because now API accepts field names
as input_data keys.
- Adding missing_counts and error_counts to report the missing values and
error counts per field in the dataset.

1.2.1 (2014-03-19)
~~~~~~~~~~~~~~~~~~

- Adding error to regression local predictions using proportional missing
strategy.

1.2.0 (2014-03-07)
~~~~~~~~~~~~~~~~~~

- Adding proportional missing strategy to MultiModel and solving tie breaks
in remote predictions.
- Adding new output options to model's python, rules and tableau outputs:
ability to extract the branch of the model leading to a certain node with
or without the hanging subtree.
- Adding HTTP_TOO_MANY_REQUESTS error handling in REST API calls.

1.1.0 (2014-02-10)
~~~~~~~~~~~~~~~~~~

- Adding Tableau-ready ouput to local model code generators.

1.0.6 (2014-02-03)
~~~~~~~~~~~~~~~~~~

- Fixing getters: getter for batch predictions was missing.

1.0.5 (2014-01-22)
~~~~~~~~~~~~~~~~~~

- Improving BaseModel and Model. If they receive a partial model
structure with a correct model id, the needed model resource is downloaded
and stored (if storage is enabled in the given api connection).
- Improving local ensemble. Adding a new `fields` attribute that
contains all the fields used in its models.

1.0.4 (2014-01-21)
~~~~~~~~~~~~~~~~~~

- Adding a summarize method to local ensembles with data distribution
and field importance information.

1.0.3 (2014-01-21)
~~~~~~~~~~~~~~~~~~

- Fixes bug in regressions predictions with ensembles and plurality without
confidence information. Predictions values were not normalized.
- Updating copyright information.

1.0.2 (2014-01-20)
~~~~~~~~~~~~~~~~~~

- Fixes bug in create calls: the user provided args dictionaries were
updated inside the calls.

1.0.1 (2014-01-05)
~~~~~~~~~~~~~~~~~~

- Changing the source for ensemble field importance computations.
- Fixes bug in http_ok adding the valid state for updates.

1.0.0 (2013-12-09)
~~~~~~~~~~~~~~~~~~

- Adding more info to error messages in REST methods.
- Adding new missing fields strategy in predict method.
- Fixes bug in shared models: credentials where not properly set.
- Adding batch predictions REST methods.

0.10.3 (2013-12-19)
~~~~~~~~~~~~~~~~~~~

- Fixes bug in local ensembles with more than 200 fields.

0.10.2 (2013-12-02)
~~~~~~~~~~~~~~~~~~~

- Fixes bug in summarize method of local models: field importance report
crashed.
- Fixes bug in status method of the BigML connection object: status for
async uploads of source files crashed while uploading.

0.10.1 (2013-11-25)
~~~~~~~~~~~~~~~~~~~

- Adding threshold combiner to MultiModel objects.

0.10.0 (2013-11-21)
~~~~~~~~~~~~~~~~~~~

- Adding a function printing field importance to ensembles.
- Changing Model to add a lightweight BaseModel class with no Tree
information.
- Adding function to get resource type from resource id or structure.
- Adding resource type checks to REST functions.
- Adding threshold as new combination method for local ensembles.

0.9.1 (2013-10-17)
~~~~~~~~~~~~~~~~~~

- Fixes duplication changing field names in local model if they are not unique.

0.9.0 (2013-10-08)
~~~~~~~~~~~~~~~~~~

- Adds the environment variables and adapts the create_prediction method
to create predictions using a different prediction server.
- Support for shared models.

0.8.0 (2013-08-10)
~~~~~~~~~~~~~~~~~~

- Adds text analysis local predict function
- Modifies outputs for text analysis: rules, summary, python, hadoop

0.7.5 (2013-08-22)
~~~~~~~~~~~~~~~~~~

- Fixes temporarily problems in predictions for regression models and
ensembles
- Adds en-gb to the list of available locales, avoiding spurious warnings

0.7.4 (2013-08-17)
~~~~~~~~~~~~~~~~~~

- Changes warning logger level to info

0.7.3 (2013-08-09)
~~~~~~~~~~~~~~~~~~

- Adds fields method to retrieve only preferred fields
- Fixes error message when no valid resource id is provided in check_resource

0.7.2 (2013-07-04)
~~~~~~~~~~~~~~~~~~

- Fixes check_resource method that was not using query-string data
- Add list of models as argument in Ensemble constructor
- MultiModel has BigML connection as a new optional argument

0.7.1 (2013-06-19)
~~~~~~~~~~~~~~~~~~

- Fixes Multimodel list_models method
- Fixes check_resource method for predictions
- Adds local configuration environment variable BIGML_DOMAIN replacing
BIGML_URL and BIGML_DEV_URL
- Refactors Ensemble and Model's predict method

0.7.0 (2013-05-01)
~~~~~~~~~~~~~~~~~~

- Adds splits in datasets to generate new datasets
- Adds evaluations for ensembles

0.6.0 (2013-04-27)
~~~~~~~~~~~~~~~~~~

- REST API methods for model ensembles
- New method returning the leaves of tree models
- Improved error handling in GET methods

0.5.2 (2013-03-03)
~~~~~~~~~~~~~~~~~~

- Adds combined confidence to combined predictions
- Fixes get_status for resources that have no status info
- Fixes bug: public datasets, that should be downloadable, weren't

0.5.1 (2013-02-12)
~~~~~~~~~~~~~~~~~~

- Fixes bug: no status info in public models, now shows FINISHED status code
- Adds more file-like objects (e.g. stdin) support in create_source input
- Refactoring Fields pair method and Model predict method to increase
- Adds some more locale aliases

0.5.0 (2013-01-16)
~~~~~~~~~~~~~~~~~~

- Adds evaluation api functions
- New prediction combination method: probability weighted
- Refactors MultiModels lists of predictions into MultiVote
- Multimodels partial predictions: new format

0.4.8 (2012-12-21)
~~~~~~~~~~~~~~~~~~

- Improved locale management
- Adds new features to MultiModel to allow local batch predictions
- Improved combined predictions
- Adds local predictions options: plurality, confidence weighted

0.4.7 (2012-12-06)
~~~~~~~~~~~~~~~~~~

- Warning message to inform of locale default if verbose mode

0.4.6 (2012-12-06)
~~~~~~~~~~~~~~~~~~

- Fix locale code for windows

0.4.5 (2012-12-05)
~~~~~~~~~~~~~~~~~~

- Fix remote predictions for input data containing fields not included in rules

0.4.4 (2012-12-02)
~~~~~~~~~~~~~~~~~~

- Tiny fixes
- Fix local predictions for input data containing fields not included in rules
- Overall clean up

0.4.3 (2012-11-07)
~~~~~~~~~~~~~~~~~~

- A few tiny fixes
- Multi models to generate predictions from multiple local models
- Adds hadoop-python code generation to create local predictions

0.4.2 (2012-09-19)
~~~~~~~~~~~~~~~~~~

- Fix Python generation
- Add a debug flag to log https requests and responses
- Type conversion in fields pairing

0.4.1 (2012-09-17)
~~~~~~~~~~~~~~~~~~

- Fix missing distribution field in new models
- Add new Field class to deal with BigML auto-generated ids
- Add by_name flag to predict methods to avoid reverse name lookups
- Add summarize method in models to generate class grouped printed output

0.4.0 (2012-08-20)
~~~~~~~~~~~~~~~~~~

- Development Mode
- Remote Sources
- Bigger files streamed with Poster
- Asynchronous Uploading
- Local Models
- Local Predictions
- Rule Generation
- Python Generation
- Overall clean up


0.3.1 (2012-07-05)
~~~~~~~~~~~~~~~~~~

- Initial release for the "andromeda" version of BigML.io.