Merge pull request #109 from amueller/usability_improvements

Usability improvements work in progress

Author: amueller

.gitignore

@@ -72,6 +72,7 @@ target/
 
 # IDE
 .idea
+*.swp
 
 # Other
 *.pkl

doc/progress.rst

@@ -66,17 +66,3 @@ API call                                        implemented tested properly test
 =============================================== =========== ====== =============== ========== =====================
 
 We do not plan to implement API calls marked with an **X**!
-
-Convenience Functions
-=====================
-
-=============================================== =========== ====== =============== ========== =====================
-Method                                          implemented tested properly tested loads json proper error handling
-=============================================== =========== ====== =============== ========== =====================
-_get_cached_split                               yes
-_get_cached_splits                              yes
-_get_cached_dataset                             yes         yes
-_get_cached_datasets                            yes         yes
-get_cached_task                                 yes
-get_cached_tasks                                yes
-=============================================== =========== ====== =============== ========== =====================

examples/OpenMLDemo.ipynb

@@ -118,7 +118,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "First 10 of 3335 datasets...\n",
+      "First 10 of 2806 datasets...\n",
       "   did             name  NumberOfInstances  NumberOfFeatures\n",
       "0    1           anneal                898                39\n",
       "1    2           anneal                898                39\n",
@@ -361,7 +361,7 @@
     }
    ],
    "source": [
-    "X, y, attribute_names = dataset.get_dataset(target=dataset.default_target_attribute, return_attribute_names=True)\n",
+    "X, y, attribute_names = dataset.get_data(target=dataset.default_target_attribute, return_attribute_names=True)\n",
     "iris = pd.DataFrame(X, columns=attribute_names)\n",
     "iris['class'] = y\n",
     "print(iris[:10])"
@@ -417,7 +417,7 @@
    ],
    "source": [
     "dataset = openml.datasets.get_dataset(61)\n",
-    "X, y = dataset.get_dataset(target=dataset.default_target_attribute)\n",
+    "X, y = dataset.get_data(target=dataset.default_target_attribute)\n",
     "clf = ensemble.RandomForestClassifier()\n",
     "clf.fit(X, y)"
    ]
@@ -464,7 +464,23 @@
    "metadata": {
     "collapsed": false
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "RandomForestClassifier(bootstrap=True, class_weight=None, criterion='gini',\n",
+       "            max_depth=None, max_features='auto', max_leaf_nodes=None,\n",
+       "            min_samples_leaf=1, min_samples_split=2,\n",
+       "            min_weight_fraction_leaf=0.0, n_estimators=10, n_jobs=1,\n",
+       "            oob_score=False, random_state=None, verbose=0,\n",
+       "            warm_start=False)"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "X_2d = X[:,2:4]\n",
     "clf.fit(X_2d, y)\n",
@@ -502,7 +518,7 @@
     }
    ],
    "source": [
-    "X, y, categorical = dataset.get_dataset(target=dataset.default_target_attribute,return_categorical_indicator=True)\n",
+    "X, y, categorical = dataset.get_data(target=dataset.default_target_attribute,return_categorical_indicator=True)\n",
     "enc = preprocessing.OneHotEncoder(categorical_features=categorical)\n",
     "X = enc.fit_transform(X)\n",
     "clf.fit(X, y)"
@@ -537,16 +553,16 @@
    },
    "outputs": [
     {
-     "ename": "TypeError",
-     "evalue": "int() argument must be a string, a bytes-like object or a number, not 'NoneType'",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[1;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
-      "\u001b[1;32m<ipython-input-14-7653a7076e49>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[0mtask_list\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mopenml\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mtasks\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mlist_tasks\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m      2\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      3\u001b[0m \u001b[0mtasks\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mpd\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mDataFrame\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mtask_list\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      4\u001b[0m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m\"First 5 of %s tasks:\"\u001b[0m \u001b[1;33m%\u001b[0m \u001b[0mlen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mtasks\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      5\u001b[0m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mtasks\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;36m5\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'tid'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;34m'did'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;34m'name'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;34m'task_type'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;34m'estimation_procedure'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
-      "\u001b[1;32m/home/andy/checkout/openml-python/openml/tasks/task_functions.py\u001b[0m in \u001b[0;36mlist_tasks\u001b[1;34m()\u001b[0m\n\u001b[0;32m    136\u001b[0m         \u001b[0mthe\u001b[0m \u001b[0massociated\u001b[0m \u001b[0mdataset\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0msome\u001b[0m \u001b[0mof\u001b[0m \u001b[0mthese\u001b[0m \u001b[0mare\u001b[0m \u001b[0malso\u001b[0m \u001b[0mreturned\u001b[0m\u001b[1;33m.\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    137\u001b[0m     \"\"\"\n\u001b[1;32m--> 138\u001b[1;33m     \u001b[1;32mreturn\u001b[0m \u001b[0m_list_tasks\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'task/list'\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    139\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    140\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
-      "\u001b[1;32m/home/andy/checkout/openml-python/openml/tasks/task_functions.py\u001b[0m in \u001b[0;36m_list_tasks\u001b[1;34m(api_call)\u001b[0m\n\u001b[0;32m    160\u001b[0m     \u001b[0mproc_dict\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mdict\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mx\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'id'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mx\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;32mfor\u001b[0m \u001b[0mx\u001b[0m \u001b[1;32min\u001b[0m \u001b[0mprocs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    161\u001b[0m     \u001b[1;32mfor\u001b[0m \u001b[0mtask_\u001b[0m \u001b[1;32min\u001b[0m \u001b[0mtasks_dict\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'oml:tasks'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'oml:task'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 162\u001b[1;33m         task = {'tid': int(task_['oml:task_id']),\n\u001b[0m\u001b[0;32m    163\u001b[0m                 \u001b[1;34m'did'\u001b[0m\u001b[1;33m:\u001b[0m \u001b[0mint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mtask_\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'oml:did'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    164\u001b[0m                 \u001b[1;34m'name'\u001b[0m\u001b[1;33m:\u001b[0m \u001b[0mtask_\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'oml:name'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
-      "\u001b[1;31mTypeError\u001b[0m: int() argument must be a string, a bytes-like object or a number, not 'NoneType'"
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "First 5 of 8566 tasks:\n",
+      "   tid  did        name                  task_type     estimation_procedure\n",
+      "0    1    1      anneal  Supervised Classification  10-fold Crossvalidation\n",
+      "1    2    2      anneal  Supervised Classification  10-fold Crossvalidation\n",
+      "2    3    3    kr-vs-kp  Supervised Classification  10-fold Crossvalidation\n",
+      "3    4    4       labor  Supervised Classification  10-fold Crossvalidation\n",
+      "4    5    5  arrhythmia  Supervised Classification  10-fold Crossvalidation\n"
      ]
     }
    ],
@@ -644,8 +660,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Uploaded run with id 538163\n",
-      "Check it at www.openml.org/r/538163\n"
+      "Uploaded run with id 538241\n",
+      "Check it at www.openml.org/r/538241\n"
      ]
     }
    ],
@@ -667,24 +683,6 @@
    "source": [
     "More to come soon..."
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

openml/_api_calls.py

@@ -5,63 +5,6 @@
 from . import config
 
 
-"""
-Provides an interface to the OpenML server.
-
-All parameters of the APIConnector can be either specified in a config
-file or when creating this object. The config file must be placed in a
-directory ``.openml`` inside the users home directory and have the name
-``config``. If one of the parameters is specified by passing it to the
-constructor of this class, it will override the value specified in the
-configuration file.
-
-Parameters
-----------
-cache_directory : string, optional (default=None)
-    A local directory which will be used for caching. If this is not set, a
-    directory '.openml/cache' in the users home directory will be used.
-    If either directory does not exist, it will be created.
-
-apikey : string, optional (default=None)
-    Your OpenML API key which will be used to authenticate you at the OpenML
-    server.
-
-server : string, optional (default=None)
-    The OpenML server to connect to.
-
-verbosity : int, optional (default=None)
-
-configure_logger : bool (default=True)
-    Whether the python logging module should be configured by the openml
-    package. If set to true, this is a very basic configuration,
-    which only prints to the standard output. This is only recommended
-    for testing or small problems. It is set to True to adhere to the
-    `specifications of the OpenML client API
-    <https://github.com/openml/OpenML/wiki/Client-API>`_.
-    When the openml module is used as a library, it is recommended that
-    the main application controls the logging level, e.g. see
-    `here <http://pieces.openpolitics.com
-    /2012/04/python-logging-best-practices/>`_.
-
-private_directory : str, optional (default=None)
-    A local directory which can be accessed through the OpenML package.
-    Useful to access private datasets through the same interface.
-
-Raises
-------
-ValueError
-    If apikey is neither specified in the config nor given as an argument.
-OpenMLServerError
-    If the OpenML server returns an unexptected response.
-
-Notes
------
-Testing the API calls in Firefox is possible with the Firefox AddOn
-HTTPRequestor.
-
-"""
-
-
 def _perform_api_call(call, data=None, file_dictionary=None,
                       file_elements=None, add_authentication=True):
     """

openml/config.py

@@ -1,3 +1,7 @@
+"""
+Stores module level information like the API key, cache director, private
+directory and the server.
+"""
 import os
 import sys
 import logging
@@ -21,6 +25,16 @@
 
 
 def _setup():
+    """Setup openml package. Called on first import.
+
+    Reads the config file and sets up apikey, server, cache appropriately.
+    key and server can be set by the user simply using
+    openml.config.apikey = THEIRKEY
+    openml.config.server = SOMESERVER
+    The cache dir needs to be set up calling set_cache_directory
+    because it needs some setup.
+    We could also make it a property but that's less clear.
+    """
     global apikey
     global server
     # read config file, create cache directory
@@ -38,6 +52,24 @@ def _setup():
 
 
 def set_cache_directory(cachedir, privatedir):
+    """Set module-wide cache directory.
+
+    Sets the cache directory into which to download datasets, tasks etc.
+    Also sets the private directory for storing local datasets.
+
+    Parameters
+    ----------
+    cachedir : string
+        Path to use as cache directory.
+
+    privatedir : string
+        Path containing private datasets, tasks, etc.
+
+    See also
+    --------
+    get_cache_directory
+    get_private_directory
+    """
     global _cachedir
     global _privatedir
     _cachedir = cachedir
@@ -67,6 +99,8 @@ def set_cache_directory(cachedir, privatedir):
 
 
 def _parse_config():
+    """Parse the config file, set up defaults.
+    """
     defaults = {'apikey': apikey,
                 'server': server,
                 'verbosity': 0,
@@ -99,10 +133,34 @@ def _parse_config():
 
 
 def get_cache_directory():
+    """Get the current cache directory.
+
+    Returns
+    -------
+    cachedir : string
+        The current cache directory.
+
+    See also
+    --------
+    set_cache_directory
+    get_private_directory
+    """
     return _cachedir
 
 
 def get_private_directory():
+    """Get the current private directory.
+
+    Returns
+    -------
+    privatecir : string
+        The current private directory.
+
+    See also
+    --------
+    set_cache_directory
+    get_cache_directory
+    """
     return _privatedir
 
 __all__ = ["set_cache_directory", 'get_cache_directory', 'get_private_directory']

openml/datasets/__init__.py

@@ -1,11 +1,7 @@
 from .functions import (list_datasets, list_datasets_by_tag,
-                        check_datasets_active, get_datasets, get_dataset,
-                        _get_dataset_description,
-                        _get_dataset_features, _get_dataset_qualities)
+                        check_datasets_active, get_datasets, get_dataset)
 from .dataset import OpenMLDataset
 
 __all__ = ['check_datasets_active', 'get_dataset', 'get_datasets',
-           'get_datasets_arf', '_get_dataset_features',
-           '_get_dataset_qualities', 'OpenMLDataset', 'list_datasets',
-           'list_datasets_by_tag',
-           '_get_dataset_description', 'list_datasets']
+           'OpenMLDataset', 'list_datasets', 'list_datasets_by_tag',
+           'list_datasets']