coba 8.0.5
A contextual bandit research package
License: BSD-3-Clause
Requires Python: >=3.8

[![codecov](https://codecov.io/gh/VowpalWabbit/coba/branch/master/graph/badge.svg?token=885XLZJ2D4)](https://codecov.io/gh/VowpalWabbit/coba)
[![binder](https://img.shields.io/badge/launch%20example-binder-579ACA.svg?logo=data:image/png;base64,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)](https://mybinder.org/v2/gh/VowpalWabbit/Coba/HEAD?filepath=doc/source/notebooks)
[![doc](https://readthedocs.org/projects/coba-docs/badge/?version=latest)](https://coba-docs.readthedocs.io/?badge=v8.0.3)
[![pypi](https://img.shields.io/badge/pypi-v8.0.3-blue)](https://pypi.org/project/coba/)

# Coba

 ### What is it?

 Coba is a powerful framework built to facilitate research with online contextual bandit (CB) algorithms.

 ### Documentation

 To start using Coba right away we recommend visiting our [documentation](https://coba-docs.readthedocs.io/).

 ### How do you research?

 Think for a second about the last time you considered evaluating CB methods for a research project

 1. Was it easy to incorporate your own data sets during CB analysis?
 2. Was it easy to incorporate the wide array of available CB algorithms?
 3. Was it easy to create, run and share the results of CB experiments?

 Coba was built from the ground up to do these three things and more.

 ### The Coba Way

 Coba is...

 * ... *light-weight* (there are minimal project dependencies to get started)
 * ... *verbose* (sophisticated logging is built-in for meaningful, readable feedback on log running jobs)
 * ... *robust* (results are frequently saved to disk so that no work is lost if research is interrupted for any reason)
 * ... *lazy* (resources are loaded just-in-time and then released quickly to minimize resource requirements)
 * ... *a duck?* (all code uses duck-typing so that inheritance is a non-issue when extending built-in functionality)

 But don't take our word for it. We encourage you to look at the code yourself or read more below.

 ## Workflow

 Coba is architected around a simple workflow: (Learners, Environments) -> Experiments -> Results -> Analysis.

 Environments represent unique CB problems that need to be solved. Learners are the CB algorithms that we can use to solve these problems. Experiments are combinations of Environments and Learners that we want to evaluate. And Results are the outcome of an Experiment, containing all the data from the Experiment.

 ## Learners

 Learners are algorithms which are able to improve their action selection through interactions with environments.

 A number of algorithms are provided natively with Coba for quick comparsions. These include:

 * All contextual bandit learners in [Vowpal Wabbit](https://vowpalwabbit.org/)
 * UCB1-Tuned Bandit Learner (Auer et al., 2002)
 * LinUCB (Li and Chu et al., 2011)
 * Linear Thompson Sampling (Agrawal and Goyal et al., 2013)
 * Corral (Agarwal et al., 2017)

 ## Environments

 Environments are the core unit of evaluation in Coba. They are nothing more than a sequence of interactions with contexts, actions and rewards. A number of tools have been built into Coba to make simulation creation easier. All these tools are defined in the `coba.environments` module. We describe a few of these tools here.

 ### Creating Environments From Classification Data Sets

 Classification data sets are the easiest way to create Environments in Coba. Coba natively supports:

 * Binay, multiclass and multi-label problems
 * Dense and sparse representations
 * Openml, Csv, Arff, Libsvm, and the extreme classification (Manik) format
 * Local files and files over http (with local caching)

 ### Creating Environments From Scratch

 If more customization is needed beyond what is offered above then you can easily create your own simulation by implementing Coba's `Environment` interface and generating interactions.

 ## Experiments

 Experiments are combinations of Learners and Environments. The Experiment class orchestrates the complex tasks of evaluating learners on environments in a resource efficient, repeatable, and robust manner. Experiments can be run on any number of processes (we often run on 96 core machines) and writes all results to file as it runs so that it can be restarted if it gets interrupted.

 ## Results

 The end result of an Experiment is a Result object that supports easy analysis. The result class provides a number of plots as well as filtering capabilities out of the box. If the built in functionality isn't advanced enough data can be exported to pandas dataframes where all manner of advanced filtering and plotting can be performed.

 ## Examples

 To learn more, many working code examples are provided in the [documentation](https://coba-docs.readthedocs.io/).