Skip to content

Commit 6fb9ca7

Browse files
mfeurermfeurer
committed
Merge pull request #12 from mfeurer/master
Update documentation and add early failure mechanism to test
2 parents 7b445c6 + d8a73df commit 6fb9ca7

4 files changed

Lines changed: 134 additions & 90 deletions

File tree

‎openml/apiconnector.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -877,6 +877,30 @@ def _create_task_cache_dir(self, task_id):
877877

878878
def _perform_api_call(self, call, data=None, add_authentication=True,
879879
**kwargs):
880+
"""Perform an API call at the OpenML server.
881+
882+
This method must be used by all other methods using the REST API.
883+
884+
Parameters
885+
----------
886+
call : str
887+
The API call. For example openml.task.search
888+
data : dict (default=None)
889+
Dictionary containing data which will be sent to the OpenML
890+
server via a POST request.
891+
add_authentication : bool (default=True)
892+
DO NOT CHANGE THIS. The only method which should set this
893+
argument to False is `authenticate`.
894+
**kwargs
895+
Further arguments which are appended as GET arguments.
896+
897+
Returns
898+
-------
899+
return_code : int
900+
HTTP return code
901+
return_value : str
902+
Return value of the OpenML server
903+
"""
880904
# TODO: do input validation!
881905
url = self.config.get("FAKE_SECTION", "server") + "/api/?f="
882906
url += "" + call

‎source/index.rst‎

Lines changed: 14 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -54,99 +54,23 @@ From within the directory of the cloned package, execute
5454
5555
python setup.py test
5656
57-
-----------
58-
Basic Usage
59-
-----------
57+
Usage
58+
~~~~~
6059

61-
Connecting to the OpenML server
62-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63-
64-
The OpenML server can only be accessed by users who have signed up to the OpenML
65-
platform. If you don't have an account yet,
66-
`sign up now <http://openml.org/register>`_.
67-
68-
.. code:: python
69-
70-
>>> from openml.apiconnector import APIConnector
71-
72-
>>> username = "Your OpenML username"
73-
>>> password = "Your OpenML password"
74-
>>> connector = APIConnector(username=username, password=password)
75-
76-
The :class:`~openml.apiconnector.APIConnector` will create a cache directory
77-
and authenticate you at the OpenML server. By this you obtain a session key,
78-
which is valid for one hour.
79-
80-
You can also configure the OpenML package, e.g. change the cache directory.
81-
Information about the configuration is in the
82-
`OpenML client API description <https://github
83-
.com/openml/OpenML/wiki/Client-API>`_.
84-
85-
Working with datasets
86-
~~~~~~~~~~~~~~~~~~~~~
87-
88-
.. code:: python
89-
90-
>>> dataset_id = 31
91-
>>> dataset = connector.download_dataset(1)
92-
93-
Attributes of the dataset are stored as member variables:
94-
95-
.. code:: python
96-
97-
>>> dataset.name
98-
u'credit-g'
99-
>>> dataset.default_target_attribute
100-
u'class'
101-
102-
Data can be loaded in the following ways:
103-
104-
.. code:: python
105-
106-
>>> pd, categorical = dataset.get_pandas()
107-
108-
returns the dataset as a pandas.DataFrame and a list of booleans,
109-
indicating which attributes are categorical. Categorical attributes are
110-
already encoded as integers.
111-
112-
.. code:: python
113-
114-
>>> X, y, categorical = dataset.get_pandas()
115-
116-
returns the dataset split into X and y, as well as a list indicating which
117-
attributes are categorical. In case you are working with `scikit-learn
118-
<http://scikit-learn>`_, you can use this data right away:
119-
120-
.. code:: python
121-
122-
>>> from sklearn import preprocessing, ensemble
123-
>>> enc = preprocessing.OneHotEncoder(categorical_features=categorical)
124-
OneHotEncoder(categorical_features=[True, False, True, True, False, True,
125-
True, False, True, True, False, True, False, True, True, False, True,
126-
False, True, True], dtype=<type 'float'>, n_values='auto',
127-
sparse=True)
128-
>>> X = enc.transform(X).todense()
129-
>>> clf = ensemble.RandomForestClassifier()
130-
>>> clf.fit(X, y)
131-
RandomForestClassifier(bootstrap=True, compute_importances=None,
132-
criterion='gini', max_depth=None, max_features='auto',
133-
max_leaf_nodes=None, min_density=None, min_samples_leaf=1,
134-
min_samples_split=2, n_estimators=10, n_jobs=1,
135-
oob_score=False, random_state=None, verbose=0)
136-
137-
Working with tasks
138-
~~~~~~~~~~~~~~~~~~
139-
140-
Using the cache
141-
~~~~~~~~~~~~~~~
60+
* :ref:`usage`
61+
* :ref:`api`
14262

143-
Large scale experiments
144-
~~~~~~~~~~~~~~~~~~~~~~~
63+
Contributing
64+
~~~~~~~~~~~~
14565

146-
Indices and tables
147-
==================
66+
Contribution to the OpenML package is highly appreciated. Currently,
67+
there is a lot of work left on implementing API calls,
68+
testing them and providing examples to allow new users to easily use the
69+
OpenML package. See the :ref:`progress` page for open tasks.
14870

149-
* :ref:`api`
150-
* :ref:`search`
71+
Please contact `Matthias <http://aad.informatik.uni-freiburg.de/people/feurer/index.html>`_
72+
prior to start working on an issue or missing feature to avoid duplicate work
73+
. Please check the current implementations of the API calls and the method
15174

75+
.. automethod:: openml.apiconnector.APIConnector._perform_api_call
15276

‎source/usage.rst‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
:orphan:
2+
3+
.. _usage:
4+
5+
Basic Usage
6+
***********
7+
8+
Connecting to the OpenML server
9+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10+
11+
The OpenML server can only be accessed by users who have signed up to the OpenML
12+
platform. If you don't have an account yet,
13+
`sign up now <http://openml.org/register>`_.
14+
15+
.. code:: python
16+
17+
>>> from openml.apiconnector import APIConnector
18+
19+
>>> username = "Your OpenML username"
20+
>>> password = "Your OpenML password"
21+
>>> connector = APIConnector(username=username, password=password)
22+
23+
The :class:`~openml.apiconnector.APIConnector` will create a cache directory
24+
and authenticate you at the OpenML server. By this you obtain a session key,
25+
which is valid for one hour.
26+
27+
You can also configure the OpenML package, e.g. change the cache directory.
28+
Information about the configuration is in the
29+
`OpenML client API description <https://github
30+
.com/openml/OpenML/wiki/Client-API>`_.
31+
32+
Working with datasets
33+
~~~~~~~~~~~~~~~~~~~~~
34+
35+
.. code:: python
36+
37+
>>> dataset_id = 31
38+
>>> dataset = connector.download_dataset(1)
39+
40+
Attributes of the dataset are stored as member variables:
41+
42+
.. code:: python
43+
44+
>>> dataset.name
45+
u'credit-g'
46+
>>> dataset.default_target_attribute
47+
u'class'
48+
49+
Data can be loaded in the following ways:
50+
51+
.. code:: python
52+
53+
>>> pd, categorical = dataset.get_pandas()
54+
55+
returns the dataset as a pandas.DataFrame and a list of booleans,
56+
indicating which attributes are categorical. Categorical attributes are
57+
already encoded as integers.
58+
59+
.. code:: python
60+
61+
>>> X, y, categorical = dataset.get_pandas()
62+
63+
returns the dataset split into X and y, as well as a list indicating which
64+
attributes are categorical. In case you are working with `scikit-learn
65+
<http://scikit-learn>`_, you can use this data right away:
66+
67+
.. code:: python
68+
69+
>>> from sklearn import preprocessing, ensemble
70+
>>> enc = preprocessing.OneHotEncoder(categorical_features=categorical)
71+
OneHotEncoder(categorical_features=[True, False, True, True, False, True,
72+
True, False, True, True, False, True, False, True, True, False, True,
73+
False, True, True], dtype=<type 'float'>, n_values='auto',
74+
sparse=True)
75+
>>> X = enc.transform(X).todense()
76+
>>> clf = ensemble.RandomForestClassifier()
77+
>>> clf.fit(X, y)
78+
RandomForestClassifier(bootstrap=True, compute_importances=None,
79+
criterion='gini', max_depth=None, max_features='auto',
80+
max_leaf_nodes=None, min_density=None, min_samples_leaf=1,
81+
min_samples_split=2, n_estimators=10, n_jobs=1,
82+
oob_score=False, random_state=None, verbose=0)
83+
84+
Working with tasks
85+
~~~~~~~~~~~~~~~~~~
86+
87+
Using the cache
88+
~~~~~~~~~~~~~~~
89+
90+
Large scale experiments
91+
~~~~~~~~~~~~~~~~~~~~~~~

‎tests/test_apiconnector.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ class TestAPIConnector(unittest.TestCase):
2828
"""
2929

3030
def setUp(self):
31+
config_file = os.path.expanduser('~/.openml/config')
32+
if not os.path.exists(config_file):
33+
raise Exception("OpenML config file required to run unit tests. "
34+
"See https://github.com/openml/OpenML/wiki/Client-API")
35+
3136
self.cwd = os.getcwd()
3237
workdir = os.path.dirname(os.path.abspath(__file__))
3338
self.workdir = os.path.join(workdir, "tmp")

0 commit comments

Comments
 (0)