make release-tag: Merge branch 'master' into stable

Author: csala

.gitignore

@@ -64,6 +64,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/pipeline.json
 
 # PyBuilder
 target/

HISTORY.md

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+0.3.0 - New Primitives Discovery
+--------------------------------
+
+* New primitives discovery system based on `entry_points`.
+* Conditional Hyperparameters filtering in MLBlock initialization.
+* Improved logging and exception reporting.
+
 0.2.4 - New Datasets and Unit Tests
 -----------------------------------
 

docs/advanced_usage/adding_primitives.rst

@@ -29,7 +29,7 @@ by writing the corresponding `JSON annotation <primitives.html#json-annotations>
 
 .. _MLPrimitives integrated primitives: https://github.com/HDI-Project/MLPrimitives/tree/master/mlblocks_primitives
 
-.. note:: If you integrate new primitives for MLBlocks, please consider contributing them to the
+.. note:: If you create new primitives for MLBlocks, please consider contributing them to the
           **MLPrimitives** project!
 
 The first thing to do when adding a new primitive is making sure that it complies with the
@@ -58,8 +58,8 @@ place known to **MLBlocks**.
 **MLBlocks** looks for primitives in the following folders, in this order:
 
 1. Any folder specified by the user, starting by the latest one.
-2. A folder named `mlblocks_primitives` in the current working directory.
-3. A folder named `mlblocks_primitives` in the `system prefix`_.
+2. A folder named ``mlblocks_primitives`` or ``mlprimitives`` in the current working directory.
+3. A folder named ``mlblocks_primitives`` or ``mlprimitives`` in the `system prefix`_.
 
 .. _system prefix: https://docs.python.org/3/library/sys.html#sys.prefix
 
@@ -80,3 +80,31 @@ However, sometimes you will want to add a custom directory.
 This can be easily done by using the `mlblocks.add_primitives_path`_ method.
 
 .. _mlblocks.add_primitives_path: ../api_reference.html#mlblocks.add_primitives_path
+
+Developing a Primitives Library
+-------------------------------
+
+Another option to add multiple libraries is creating a primitives library, such as
+`MLPrimitives`_.
+
+In order to make **MLBLocks** able to find the primitives defined in such a library,
+all you need to do is setting up an `Entry Point`_ in your `setup.py` script with the
+following specification:
+
+1. It has to be published under the name ``mlprimitives``.
+2. It has to be named exactly ``jsons_path``.
+3. It has to point at a variable that contains the path to the JSONS folder.
+
+An example of such an entry point would be::
+
+    entry_points = {
+        'mlprimitives': [
+            'jsons_path=some_module:SOME_VARIABLE'
+        ]
+    }
+
+where the module `some_module` contains a variable such as::
+
+    SOME_VARIABLE = os.path.join(os.path.dirname(__file__), 'jsons')
+
+.. _Entry Point: https://packaging.python.org/specifications/entry-points/

docs/advanced_usage/hyperparameters.rst

@@ -165,6 +165,19 @@ Conditional Hyperparameters
 
 In some other cases, the values that a hyperparameter can take depend on the value of another
 one.
+For example, sometimes a primitive has a hyperparameter that specifies a kernel, and depending
+on the kernel used some other hyperparameters may be or not be used, or they might be able
+to take only some specific values.
+
+In this case, the ``type`` of the hyperparameter whose values depend on the other is specified
+as ``conditional``.
+In this case, two additional entries are required:
+
+* an entry called ``condition``, which specifies the name of the other hyperparameter, the value
+  of which is evaluated to decide which values this hyperparameter can take.
+* an additional subdictionary called ``values``, which relates the  possible values that the
+  `condition` hyperparameter can have with the full specifications of the type and values that
+  this hyperparameter can take in each case.
 
 Suppose, for example, that the primitive explained in the previous point does not expect
 the ``mean``, ``min`` or ``max`` strings as values for the ``max_features`` hyperparameter,
@@ -190,7 +203,7 @@ In this case, the hyperparameters would be annotated like this::
     }
     "max_features_aggregation": {
         "type": "conditional",
-        "condition": "mas_features",
+        "condition": "max_features",
         "default": null,
         "values": {
             "auto": {
@@ -202,6 +215,10 @@ In this case, the hyperparameters would be annotated like this::
         }
     }
 
+.. note:: Just like a regular hyperparameter, if there is no match the default entry is used.
+          In this example, the ``null`` value indicates that the hyperparameter needs to be
+          disabled if there is no match, but instead of it we could add there a full specification
+          of type, range and default value as a nested dictionary to be used by default.
 
 .. _JSON Annotations: primitives.html#json-annotations
 .. _MLPrimitives: https://github.com/HDI-Project/MLPrimitives

docs/api/mlblocks.primitives.rst

@@ -0,0 +1,5 @@
+mlblocks.primitives
+===================
+
+.. automodule:: mlblocks.primitives
+    :members:

docs/index.rst

@@ -74,6 +74,7 @@ integrate with deep learning libraries.
 
    api/mlblocks
    api/mlblocks.datasets
+   api/mlblocks.primitives
 
 .. toctree::
    :caption: Resources

docs/pipeline.json

@@ -10,15 +10,15 @@
 * Documentation: https://HDI-Project.github.io/MLBlocks
 """
 
-from mlblocks.mlblock import MLBlock  # noqa
-from mlblocks.mlpipeline import MLPipeline  # noqa
-from mlblocks.primitives import add_primitives_path, get_primitives_paths, load_primitive  # noqa
+from mlblocks.mlblock import MLBlock
+from mlblocks.mlpipeline import MLPipeline
+from mlblocks.primitives import add_primitives_path, get_primitives_paths, load_primitive
 
 __author__ = 'MIT Data To AI Lab'
 __copyright__ = 'Copyright (c) 2018, MIT Data To AI Lab'
 __email__ = 'dailabmit@gmail.com'
 __license__ = 'MIT'
-__version__ = '0.2.4'
+__version__ = '0.3.0-dev'
 
 __all__ = [
     'MLBlock', 'MLPipeline', 'add_primitives_path',

mlblocks/__init__.py

@@ -40,6 +40,7 @@
 """
 
 import io
+import logging
 import os
 import tarfile
 import urllib
@@ -52,6 +53,8 @@
 from sklearn.metrics import accuracy_score, normalized_mutual_info_score, r2_score
 from sklearn.model_selection import KFold, StratifiedKFold, train_test_split
 
+LOGGER = logging.getLogger(__name__)
+
 INPUT_SHAPE = [224, 224, 3]
 
 DATA_PATH = os.path.join(
@@ -183,9 +186,12 @@ def get_splits(self, n_splits=1):
 
 def _download(dataset_name, dataset_path):
     url = DATA_URL.format(dataset_name)
+
+    LOGGER.debug('Downloading dataset %s from %s', dataset_name, url)
     response = urllib.request.urlopen(url)
     bytes_io = io.BytesIO(response.read())
 
+    LOGGER.debug('Extracting dataset into %s', DATA_PATH)
     with tarfile.open(fileobj=bytes_io, mode='r:gz') as tf:
         tf.extractall(DATA_PATH)
 
@@ -202,6 +208,7 @@ def _load(dataset_name):
 
 
 def _load_images(image_dir, filenames):
+    LOGGER.debug('Loading %s images from %s', len(filenames), image_dir)
     images = []
     for filename in filenames:
         filename = os.path.join(image_dir, filename)
@@ -217,6 +224,8 @@ def _load_images(image_dir, filenames):
 
 def _load_csv(dataset_path, name, set_index=False):
     csv_path = os.path.join(dataset_path, name + '.csv')
+
+    LOGGER.debug('Loading csv %s', csv_path)
     df = pd.read_csv(csv_path)
 
     if set_index:

mlblocks/datasets.py

@@ -3,9 +3,12 @@
 """Package where the MLBlock class is defined."""
 
 import importlib
+import logging
 
 from mlblocks.primitives import load_primitive
 
+LOGGER = logging.getLogger(__name__)
+
 
 def import_object(object_name):
     """Import an object from its Fully Qualified Name."""
@@ -83,7 +86,7 @@ def _extract_params(self, kwargs, hyperparameters):
                 value = param['default']
 
             else:
-                raise TypeError("Required argument '{}' not found".format(name))
+                raise TypeError("{} required argument '{}' not found".format(self.name, name))
 
             init_params[name] = value
 
@@ -107,6 +110,33 @@ def _extract_params(self, kwargs, hyperparameters):
 
         return init_params, fit_params, produce_params
 
+    @staticmethod
+    def _filter_conditional(conditional, init_params):
+        condition = conditional['condition']
+        default = conditional.get('default')
+
+        if condition not in init_params:
+            return default
+
+        condition_value = init_params[condition]
+        values = conditional['values']
+        return values.get(condition_value, default)
+
+    @classmethod
+    def _get_tunable(cls, hyperparameters, init_params):
+        tunable = dict()
+        for name, param in hyperparameters.get('tunable', dict()).items():
+            if name not in init_params:
+                if param['type'] == 'conditional':
+                    param = cls._filter_conditional(param, init_params)
+                    if param is not None:
+                        tunable[name] = param
+
+                else:
+                    tunable[name] = param
+
+        return tunable
+
     def __init__(self, name, **kwargs):
 
         self.name = name
@@ -133,13 +163,7 @@ def __init__(self, name, **kwargs):
         self._fit_params = fit_params
         self._produce_params = produce_params
 
-        tunable = hyperparameters.get('tunable', dict())
-        self._tunable = {
-            name: param
-            for name, param in tunable.items()
-            if name not in init_params
-            # TODO: filter conditionals
-        }
+        self._tunable = self._get_tunable(hyperparameters, init_params)
 
         default = {
             name: param['default']
@@ -193,6 +217,7 @@ def set_hyperparameters(self, hyperparameters):
         self._hyperparameters.update(hyperparameters)
 
         if self._class:
+            LOGGER.debug('Creating a new primitive instance for %s', self.name)
             self.instance = self.primitive(**self._hyperparameters)
 
     def fit(self, **kwargs):