{"id":13656008,"url":"https://github.com/bigmlcom/python","last_synced_at":"2025-05-16T07:06:39.555Z","repository":{"id":3165502,"uuid":"4196332","full_name":"bigmlcom/python","owner":"bigmlcom","description":"Python bindings for BigML.io","archived":false,"fork":false,"pushed_at":"2025-03-27T18:02:12.000Z","size":26330,"stargazers_count":287,"open_issues_count":1,"forks_count":179,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-14T15:51:25.488Z","etag":null,"topics":["api","bigml","machine-learning","ml","python"],"latest_commit_sha":null,"homepage":"http://bigml.com/api","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigmlcom.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-05-01T20:42:24.000Z","updated_at":"2025-03-27T18:02:13.000Z","dependencies_parsed_at":"2025-04-14T15:37:18.098Z","dependency_job_id":"f80f7b66-5d44-45e8-9b8b-dc4c62f34672","html_url":"https://github.com/bigmlcom/python","commit_stats":{"total_commits":1393,"total_committers":22,"mean_commits":63.31818181818182,"dds":0.1751615218951902,"last_synced_commit":"bc620ab7588a6a520b8f79f7c12d3fe363e599d8"},"previous_names":[],"tags_count":274,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigmlcom%2Fpython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigmlcom%2Fpython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigmlcom%2Fpython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigmlcom%2Fpython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigmlcom","download_url":"https://codeload.github.com/bigmlcom/python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485063,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bigml","machine-learning","ml","python"],"created_at":"2024-08-02T04:00:45.757Z","updated_at":"2025-05-16T07:06:34.543Z","avatar_url":"https://github.com/bigmlcom.png","language":"Python","readme":"BigML Python Bindings\n=====================\n\n`BigML \u003chttps://bigml.com\u003e`_ makes machine learning easy by taking care\nof the details required to add data-driven decisions and predictive\npower to your company. Unlike other machine learning services, BigML\ncreates\n`beautiful predictive models \u003chttps://bigml.com/gallery/models\u003e`_ that\ncan be easily understood and interacted with.\n\nThese BigML Python bindings allow you to interact with\n`BigML.io \u003chttps://bigml.io/\u003e`_, the API\nfor BigML. You can use it to easily create, retrieve, list, update, and\ndelete BigML resources (i.e., sources, datasets, models and,\npredictions). For additional information, see\nthe `full documentation for the Python\nbindings on Read the Docs \u003chttp://bigml.readthedocs.org\u003e`_.\n\nThis module is licensed under the `Apache License, Version\n2.0 \u003chttp://www.apache.org/licenses/LICENSE-2.0.html\u003e`_.\n\nSupport\n-------\n\nPlease report problems and bugs to our `BigML.io issue\ntracker \u003chttps://github.com/bigmlcom/io/issues\u003e`_.\n\nDiscussions about the different bindings take place in the general\n`BigML mailing list \u003chttp://groups.google.com/group/bigml\u003e`_. Or join us\nin our `Campfire chatroom \u003chttps://bigmlinc.campfirenow.com/f20a0\u003e`_.\n\nRequirements\n------------\n\nOnly ``Python 3`` versions are currently supported by these bindings.\nSupport for Python 2.7.X ended in version ``4.32.3``.\n\nThe basic third-party dependencies are the\n`requests \u003chttps://github.com/kennethreitz/requests\u003e`_,\n`unidecode \u003chttp://pypi.python.org/pypi/Unidecode/#downloads\u003e`_,\n`requests-toolbelt \u003chttps://pypi.python.org/pypi/requests-toolbelt\u003e`_,\n`bigml-chronos \u003chttps://pypi.org/project/bigml-chronos\u003e`_,\n`msgpack \u003chttps://pypi.org/project/msgpack\u003e`_,\n`numpy \u003chttp://www.numpy.org/\u003e`_ and\n`scipy \u003chttp://www.scipy.org/\u003e`_ libraries. These\nlibraries are automatically installed during the basic setup.\nSupport for Google App Engine has been added as of version 3.0.0,\nusing the `urlfetch` package instead of `requests`.\n\nThe bindings will also use ``simplejson`` if you happen to have it\ninstalled, but that is optional: we fall back to Python's built-in JSON\nlibraries is ``simplejson`` is not found.\n\nThe bindings provide support to use the ``BigML`` platform to create, update,\nget and delete resources, but also to produce local predictions using the\nmodels created in ``BigML``. Most of them will be actionable with the basic\ninstallation, but some additional dependencies are needed to use local\n``Topic Models`` and Image Processing models. Please, refer to the\n`Installation \u003c#installation\u003e`_ section for details.\n\nOS Requirements\n~~~~~~~~~~~~~~~\n\nThe basic installation of the bindings is compatible and can be used\non Linux and Windows based Operating Systems.\nHowever, the extra options that allow working with\nimage processing models (``[images]`` and ``[full]``) are only supported\nand tested on Linux-based Operating Systems.\nFor image models, Windows OS is not recommended and cannot be supported out of\nthe box, because the specific compiler versions or dlls required are\nunavailable in general.\n\nInstallation\n------------\n\nTo install the basic latest stable release with\n`pip \u003chttp://www.pip-installer.org/\u003e`_, please use:\n\n.. code-block:: bash\n\n    $ pip install bigml\n\nSupport for local Topic Distributions (Topic Models' predictions)\nand local predictions for datasets that include Images will only be\navailable as extras, because the libraries used for that are not\nusually available in all Operative Systems. If you need to support those,\nplease check the `Installation Extras \u003c#installation-extras\u003e`_ section.\n\nInstallation Extras\n-------------------\n\nLocal Topic Distributions support can be installed using:\n\n.. code-block:: bash\n\n    pip install bigml[topics]\n\nImages local predictions support can be installed using:\n\n.. code-block:: bash\n\n    pip install bigml[images]\n\nThe full set of features can be installed using:\n\n.. code-block:: bash\n\n    pip install bigml[full]\n\n\nWARNING: Mind that installing these extras can require some extra work, as\nexplained in the `Requirements \u003c#requirements\u003e`_ section.\n\nYou can also install the development version of the bindings directly\nfrom the Git repository\n\n.. code-block:: bash\n\n    $ pip install -e git://github.com/bigmlcom/python.git#egg=bigml_python\n\n\nRunning the Tests\n-----------------\n\nThe tests will be run using `pytest \u003chttps://docs.pytest.org/en/7.2.x/\u003e`_.\nYou'll need to set up your authentication\nvia environment variables, as explained\nin the authentication section. Also some of the tests need other environment\nvariables like ``BIGML_ORGANIZATION`` to test calls when used by Organization\nmembers and ``BIGML_EXTERNAL_CONN_HOST``, ``BIGML_EXTERNAL_CONN_PORT``,\n``BIGML_EXTERNAL_CONN_DB``, ``BIGML_EXTERNAL_CONN_USER``,\n``BIGML_EXTERNAL_CONN_PWD`` and ``BIGML_EXTERNAL_CONN_SOURCE``\nin order to test external data connectors.\n\nWith that in place, you can run the test suite simply by issuing\n\n.. code-block:: bash\n\n    $ pytest\n\nAdditionally, `Tox \u003chttp://tox.testrun.org/\u003e`_ can be used to\nautomatically run the test suite in virtual environments for all\nsupported Python versions.  To install Tox:\n\n.. code-block:: bash\n\n    $ pip install tox\n\nThen run the tests from the top-level project directory:\n\n.. code-block:: bash\n\n    $ tox\n\nImporting the module\n--------------------\n\nTo import the module:\n\n.. code-block:: python\n\n    import bigml.api\n\nAlternatively you can just import the BigML class:\n\n.. code-block:: python\n\n    from bigml.api import BigML\n\nAuthentication\n--------------\n\nAll the requests to BigML.io must be authenticated using your username\nand `API key \u003chttps://bigml.com/account/apikey\u003e`_ and are always\ntransmitted over HTTPS.\n\nThis module will look for your username and API key in the environment\nvariables ``BIGML_USERNAME`` and ``BIGML_API_KEY`` respectively.\n\nUnix and MacOS\n--------------\n\nYou can\nadd the following lines to your ``.bashrc`` or ``.bash_profile`` to set\nthose variables automatically when you log in:\n\n.. code-block:: bash\n\n    export BIGML_USERNAME=myusername\n    export BIGML_API_KEY=ae579e7e53fb9abd646a6ff8aa99d4afe83ac291\n\nrefer to the next chapters to know how to do that in other operating systems.\n\nWith that environment set up, connecting to BigML is a breeze:\n\n.. code-block:: python\n\n    from bigml.api import BigML\n    api = BigML()\n\nOtherwise, you can initialize directly when instantiating the BigML\nclass as follows:\n\n.. code-block:: python\n\n    api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291')\n\nThese credentials will allow you to manage any resource in your user\nenvironment.\n\nIn BigML a user can also work for an ``organization``.\nIn this case, the organization administrator should previously assign\npermissions for the user to access one or several particular projects\nin the organization.\nOnce permissions are granted, the user can work with resources in a project\naccording to his permission level by creating a special constructor for\neach project. The connection constructor in this case\nshould include the ``project ID``:\n\n.. code-block:: python\n\n    api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291',\n                project='project/53739b98d994972da7001d4a')\n\nIf the project used in a connection object\ndoes not belong to an existing organization but is one of the\nprojects under the user's account, all the resources\ncreated or updated with that connection will also be assigned to the\nspecified project.\n\nWhen the resource to be managed is a ``project`` itself, the connection\nneeds to include the corresponding``organization ID``:\n\n.. code-block:: python\n\n    api = BigML('myusername', 'ae579e7e53fb9abd646a6ff8aa99d4afe83ac291',\n                organization='organization/53739b98d994972da7025d4a')\n\n\nAuthentication on Windows\n-------------------------\n\nThe credentials should be permanently stored in your system using\n\n.. code-block:: bash\n\n    setx BIGML_USERNAME myusername\n    setx BIGML_API_KEY ae579e7e53fb9abd646a6ff8aa99d4afe83ac291\n\nNote that ``setx`` will not change the environment variables of your actual\nconsole, so you will need to open a new one to start using them.\n\n\nAuthentication on Jupyter Notebook\n----------------------------------\n\nYou can set the environment variables using the ``%env`` command in your\ncells:\n\n.. code-block:: bash\n\n    %env BIGML_USERNAME=myusername\n    %env BIGML_API_KEY=ae579e7e53fb9abd646a6ff8aa99d4afe83ac291\n\n\nAlternative domains\n-------------------\n\n\nThe main public domain for the API service is ``bigml.io``, but there are some\nalternative domains, either for Virtual Private Cloud setups or\nthe australian subdomain (``au.bigml.io``). You can change the remote\nserver domain\nto the VPC particular one by either setting the ``BIGML_DOMAIN`` environment\nvariable to your VPC subdomain:\n\n.. code-block:: bash\n\n    export BIGML_DOMAIN=my_VPC.bigml.io\n\nor setting it when instantiating your connection:\n\n.. code-block:: python\n\n    api = BigML(domain=\"my_VPC.bigml.io\")\n\nThe corresponding SSL REST calls will be directed to your private domain\nhenceforth.\n\nYou can also set up your connection to use a particular PredictServer\nonly for predictions. In order to do so, you'll need to specify a ``Domain``\nobject, where you can set up the general domain name as well as the\nparticular prediction domain name.\n\n.. code-block:: python\n\n    from bigml.domain import Domain\n    from bigml.api import BigML\n\n    domain_info = Domain(prediction_domain=\"my_prediction_server.bigml.com\",\n                         prediction_protocol=\"http\")\n\n    api = BigML(domain=domain_info)\n\nFinally, you can combine all the options and change both the general domain\nserver, and the prediction domain server.\n\n.. code-block:: python\n\n    from bigml.domain import Domain\n    from bigml.api import BigML\n    domain_info = Domain(domain=\"my_VPC.bigml.io\",\n                         prediction_domain=\"my_prediction_server.bigml.com\",\n                         prediction_protocol=\"https\")\n\n    api = BigML(domain=domain_info)\n\nSome arguments for the Domain constructor are more unsual, but they can also\nbe used to set your special service endpoints:\n\n- protocol (string) Protocol for the service\n  (when different from HTTPS)\n- verify (boolean) Sets on/off the SSL verification\n- prediction_verify (boolean) Sets on/off the SSL verification\n  for the prediction server (when different from the general\n  SSL verification)\n\n**Note** that the previously existing ``dev_mode`` flag:\n\n.. code-block:: python\n\n    api = BigML(dev_mode=True)\n\nthat caused the connection to work with the Sandbox ``Development Environment``\nhas been **deprecated** because this environment does not longer exist.\nThe existing resources that were previously\ncreated in this environment have been moved\nto a special project in the now unique ``Production Environment``, so this\nflag is no longer needed to work with them.\n\n\nQuick Start\n-----------\n\nImagine that you want to use `this csv\nfile \u003chttps://static.bigml.com/csv/iris.csv\u003e`_ containing the `Iris\nflower dataset \u003chttp://en.wikipedia.org/wiki/Iris_flower_data_set\u003e`_ to\npredict the species of a flower whose ``petal length`` is ``2.45`` and\nwhose ``petal width`` is ``1.75``. A preview of the dataset is shown\nbelow. It has 4 numeric fields: ``sepal length``, ``sepal width``,\n``petal length``, ``petal width`` and a categorical field: ``species``.\nBy default, BigML considers the last field in the dataset as the\nobjective field (i.e., the field that you want to generate predictions\nfor).\n\n::\n\n    sepal length,sepal width,petal length,petal width,species\n    5.1,3.5,1.4,0.2,Iris-setosa\n    4.9,3.0,1.4,0.2,Iris-setosa\n    4.7,3.2,1.3,0.2,Iris-setosa\n    ...\n    5.8,2.7,3.9,1.2,Iris-versicolor\n    6.0,2.7,5.1,1.6,Iris-versicolor\n    5.4,3.0,4.5,1.5,Iris-versicolor\n    ...\n    6.8,3.0,5.5,2.1,Iris-virginica\n    5.7,2.5,5.0,2.0,Iris-virginica\n    5.8,2.8,5.1,2.4,Iris-virginica\n\nYou can easily generate a prediction following these steps:\n\n.. code-block:: python\n\n    from bigml.api import BigML\n\n    api = BigML()\n\n    source = api.create_source('./data/iris.csv')\n    dataset = api.create_dataset(source)\n    model = api.create_model(dataset)\n    prediction = api.create_prediction(model, \\\n        {\"petal width\": 1.75, \"petal length\": 2.45})\n\nYou can then print the prediction using the ``pprint`` method:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e api.pprint(prediction)\n    species for {\"petal width\": 1.75, \"petal length\": 2.45} is Iris-setosa\n\nCertainly, any of the resources created in BigML can be configured using\nseveral arguments described in the `API documentation \u003chttps://bigml.com/api\u003e`_.\nAny of these configuration arguments can be added to the ``create`` method\nas a dictionary in the last optional argument of the calls:\n\n.. code-block:: python\n\n    from bigml.api import BigML\n\n    api = BigML()\n\n    source_args = {\"name\": \"my source\",\n         \"source_parser\": {\"missing_tokens\": [\"NULL\"]}}\n    source = api.create_source('./data/iris.csv', source_args)\n    dataset_args = {\"name\": \"my dataset\"}\n    dataset = api.create_dataset(source, dataset_args)\n    model_args = {\"objective_field\": \"species\"}\n    model = api.create_model(dataset, model_args)\n    prediction_args = {\"name\": \"my prediction\"}\n    prediction = api.create_prediction(model, \\\n        {\"petal width\": 1.75, \"petal length\": 2.45},\n        prediction_args)\n\nThe ``iris`` dataset has a small number of instances, and usually will be\ninstantly created, so the ``api.create_`` calls will probably return the\nfinished resources outright. As BigML's API is asynchronous,\nin general you will need to ensure\nthat objects are finished before using them by using ``api.ok``.\n\n.. code-block:: python\n\n    from bigml.api import BigML\n\n    api = BigML()\n\n    source = api.create_source('./data/iris.csv')\n    api.ok(source)\n    dataset = api.create_dataset(source)\n    api.ok(dataset)\n    model = api.create_model(dataset)\n    api.ok(model)\n    prediction = api.create_prediction(model, \\\n        {\"petal width\": 1.75, \"petal length\": 2.45})\n\nNote that the prediction\ncall is not followed by the ``api.ok`` method. Predictions are so quick to be\ngenerated that, unlike the\nrest of resouces, will be generated synchronously as a finished object.\n\nThe example assumes that your objective field (the one you want to predict)\nis the last field in the dataset. If that's not he case, you can explicitly\nset the name of this field in the creation call using the ``objective_field``\nargument:\n\n\n.. code-block:: python\n\n    from bigml.api import BigML\n\n    api = BigML()\n\n    source = api.create_source('./data/iris.csv')\n    api.ok(source)\n    dataset = api.create_dataset(source)\n    api.ok(dataset)\n    model = api.create_model(dataset, {\"objective_field\": \"species\"})\n    api.ok(model)\n    prediction = api.create_prediction(model, \\\n        {'sepal length': 5, 'sepal width': 2.5})\n\n\nYou can also generate an evaluation for the model by using:\n\n.. code-block:: python\n\n    test_source = api.create_source('./data/test_iris.csv')\n    api.ok(test_source)\n    test_dataset = api.create_dataset(test_source)\n    api.ok(test_dataset)\n    evaluation = api.create_evaluation(model, test_dataset)\n    api.ok(evaluation)\n\nIf you set the ``storage`` argument in the ``api`` instantiation:\n\n.. code-block:: python\n\n    api = BigML(storage='./storage')\n\nall the generated, updated or retrieved resources will be automatically\nsaved to the chosen directory.\n\nAlternatively, you can use the ``export`` method to explicitly\ndownload the JSON information\nthat describes any of your resources in BigML to a particular file:\n\n.. code-block:: python\n\n    api.export('model/5acea49a08b07e14b9001068',\n               filename=\"my_dir/my_model.json\")\n\nThis example downloads the JSON for the model and stores it in\nthe ``my_dir/my_model.json`` file.\n\nIn the case of models that can be represented in a `PMML` syntax, the\nexport method can be used to produce the corresponding `PMML` file.\n\n.. code-block:: python\n\n    api.export('model/5acea49a08b07e14b9001068',\n               filename=\"my_dir/my_model.pmml\",\n               pmml=True)\n\nYou can also retrieve the last resource with some previously given tag:\n\n.. code-block:: python\n\n     api.export_last(\"foo\",\n                     resource_type=\"ensemble\",\n                     filename=\"my_dir/my_ensemble.json\")\n\nwhich selects the last ensemble that has a ``foo`` tag. This mechanism can\nbe specially useful when retrieving retrained models that have been created\nwith a shared unique keyword as tag.\n\nFor a descriptive overview of the steps that you will usually need to\nfollow to model\nyour data and obtain predictions, please see the `basic Workflow sketch\n\u003capi_sketch.html\u003e`_\ndocument. You can also check other simple examples in the following documents:\n\n- `model 101 \u003c101_model.html\u003e`_\n- `logistic regression 101 \u003c101_logistic_regression.html\u003e`_\n- `linear regression 101 \u003c101_linear_regression.html\u003e`_\n- `ensemble 101 \u003c101_ensemble.html\u003e`_\n- `cluster 101 \u003c101_cluster\u003e`_\n- `anomaly detector 101 \u003c101_anomaly.html\u003e`_\n- `association 101 \u003c101_association.html\u003e`_\n- `topic model 101 \u003c101_topic_model.html\u003e`_\n- `deepnet 101 \u003c101_deepnet.html\u003e`_\n- `time series 101 \u003c101_ts.html\u003e`_\n- `fusion 101 \u003c101_fusion.html\u003e`_\n- `scripting 101 \u003c101_scripting.html\u003e`_\n\nAdditional Information\n----------------------\n\nWe've just barely scratched the surface. For additional information, see\nthe `full documentation for the Python\nbindings on Read the Docs \u003chttp://bigml.readthedocs.org\u003e`_.\nAlternatively, the same documentation can be built from a local checkout\nof the source by installing `Sphinx \u003chttp://sphinx.pocoo.org\u003e`_\n(``$ pip install sphinx``) and then running\n\n.. code-block:: bash\n\n    $ cd docs\n    $ make html\n\nThen launch ``docs/_build/html/index.html`` in your browser.\n\nHow to Contribute\n-----------------\n\nPlease follow the next steps:\n\n  1. Fork the project on github.com.\n  2. Create a new branch.\n  3. Commit changes to the new branch.\n  4. Send a `pull request \u003chttps://github.com/bigmlcom/python/pulls\u003e`_.\n\n\nFor details on the underlying API, see the\n`BigML API documentation \u003chttps://bigml.com/developers\u003e`_.\n","funding_links":[],"categories":["Python","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigmlcom%2Fpython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigmlcom%2Fpython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigmlcom%2Fpython/lists"}