"""
Introduction
===================

An introduction to OpenML, followed up by a simple example.
"""
############################################################################
# OpenML is an online collaboration platform for machine learning which allows
# you to:
#
# * Find or share interesting, well-documented datasets
# * Define research / modelling goals (tasks)
# * Explore large amounts of machine learning algorithms, with APIs in Java, R, Python
# * Log and share reproducible experiments, models, results
# * Works seamlessly with scikit-learn and other libraries
# * Large scale benchmarking, compare to state of the art
#
# Installation
# ^^^^^^^^^^^^
# Installation is done via ``pip``:
#
# .. code:: bash
#
#     pip install openml
#
# For further information, please check out the installation guide at
# https://openml.github.io/openml-python/master/contributing.html#installation
#
# Authentication
# ^^^^^^^^^^^^^^
#
# The OpenML server can only be accessed by users who have signed up on the
# OpenML platform. If you don’t have an account yet, sign up now.
# You will receive an API key, which will authenticate you to the server
# and allow you to download and upload datasets, tasks, runs and flows.
#
# * Create an OpenML account (free) on http://www.openml.org.
# * After logging in, open your account page (avatar on the top right)
# * Open 'Account Settings', then 'API authentication' to find your API key.
#
# There are two ways to authenticate:
#
# * Create a plain text file **~/.openml/config** with the line
#   **'apikey=MYKEY'**, replacing **MYKEY** with your API key. The config
#   file must be in the directory ~/.openml/config and exist prior to
#   importing the openml module.
# * Run the code below, replacing 'YOURKEY' with your API key.
#
# .. warning:: This example uploads data. For that reason, this example
#   connects to the test server instead. This prevents the live server from
#   crowding with example datasets, tasks, studies, and so on.
############################################################################
import openml
from sklearn import neighbors

openml.config.start_using_configuration_for_example()

############################################################################
# When using the main server, instead make sure your apikey is configured.
# This can be done with the following line of code (uncomment it!).
# Never share your apikey with others.

# openml.config.apikey = 'YOURKEY'

############################################################################
# Caching
# ^^^^^^^
# When downloading datasets, tasks, runs and flows, they will be cached to
# retrieve them without calling the server later. As with the API key,
# the cache directory can be either specified through the config file or
# through the API:
#
# * Add the  line **cachedir = 'MYDIR'** to the config file, replacing
#   'MYDIR' with the path to the cache directory. By default, OpenML
#   will use **~/.openml/cache** as the cache directory.
# * Run the code below, replacing 'YOURDIR' with the path to the cache directory.

# Uncomment and set your OpenML cache directory
# import os
# openml.config.cache_directory = os.path.expanduser('YOURDIR')

############################################################################
# Simple Example
# ^^^^^^^^^^^^^^
# Download the OpenML task for the eeg-eye-state.
task = openml.tasks.get_task(403)
data = openml.datasets.get_dataset(task.dataset_id)
clf = neighbors.KNeighborsClassifier(n_neighbors=5)
run = openml.runs.run_model_on_task(clf, task, avoid_duplicate_runs=False)
# Publish the experiment on OpenML (optional, requires an API key).
# For this tutorial, our configuration publishes to the test server
# as to not crowd the main server with runs created by examples.
myrun = run.publish()
print("kNN on %s: http://test.openml.org/r/%d" % (data.name, myrun.run_id))

############################################################################
openml.config.stop_using_configuration_for_example()