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

Author: csala

CONTRIBUTING.rst

@@ -172,24 +172,26 @@ The process of releasing a new version involves several steps combining both ``g
 
 1. Merge what is in ``master`` branch into ``stable`` branch.
 2. Update the version in ``setup.cfg``, ``mlblocks/__init__.py`` and ``HISTORY.md`` files.
-3. Create a new TAG pointing at the correspoding commit in ``stable`` branch.
+3. Create a new git tag pointing at the corresponding commit in ``stable`` branch.
 4. Merge the new commit from ``stable`` into ``master``.
-5. Update the version in ``setup.cfg`` and ``mlblocks/__init__.py`` to open the next
-   development interation.
+5. Update the version in ``setup.cfg`` and ``mlblocks/__init__.py``
+   to open the next development iteration.
 
-**Note:** Before starting the process, make sure that ``HISTORY.md`` has a section titled
-**Unreleased** with the list of changes that will be included in the new version, and that
-these changes are committed and available in ``master`` branch.
-Normally this is just a list of the Pull Requests that have been merged since the latest version.
+.. note:: Before starting the process, make sure that ``HISTORY.md`` has been updated with a new
+          entry that explains the changes that will be included in the new version.
+          Normally this is just a list of the Pull Requests that have been merged to master
+          since the last release.
 
-Once this is done, just run the following commands::
+Once this is done, run of the following commands:
+
+1. If you are releasing a patch version::
 
-    git checkout stable
-    git merge --no-ff master    # This creates a merge commit
-    bumpversion release   # This creates a new commit and a TAG
-    git push --tags origin stable
     make release
-    git checkout master
-    git merge stable
-    bumpversion --no-tag patch
-    git push
+
+2. If you are releasing a minor version::
+
+    make release-minor
+
+3. If you are releasing a major version::
+
+    make release-major

HISTORY.md

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+0.3.1 - Pipelines Discovery
+---------------------------
+
+* Support flat hyperparameter dictionaries
+  [Issue #92](https://github.com/HDI-Project/MLBlocks/issues/92) by @csala
+* Load pipelines by name and register them as `entry_points`
+  [Issue #88](https://github.com/HDI-Project/MLBlocks/issues/88) by @csala
+* Implement partial re-fit
+  [Issue #61](https://github.com/HDI-Project/MLBlocks/issues/61) by @csala
+* Move argument parsing to MLBlock
+  [Issue #86](https://github.com/HDI-Project/MLBlocks/issues/86) by @csala
+* Allow getting intermediate outputs
+  [Issue #58](https://github.com/HDI-Project/MLBlocks/issues/58) by @csala
+
 0.3.0 - New Primitives Discovery
 --------------------------------
 

Makefile

@@ -98,6 +98,11 @@ fix-lint: ## fix lint issues using autoflake, autopep8, and isort
 	autopep8 --in-place --recursive --aggressive tests
 	isort --apply --atomic --recursive tests
 
+.PHONY: lint-docs
+lint-docs: ## check docs formatting with doc8 and pydocstyle
+	doc8 mlblocks/
+	pydocstyle mlblocks/
+
 
 # TEST TARGETS
 
@@ -122,7 +127,6 @@ coverage: ## check code coverage quickly with the default Python
 .PHONY: docs
 docs: clean-docs ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
-	touch docs/_build/html/.nojekyll
 
 .PHONY: view-docs
 view-docs: docs ## view docs in browser

README.md

@@ -58,11 +58,26 @@ make install
 For development, you can use `make install-develop` instead in order to install all
 the required dependencies for testing and code linting.
 
+## MLPrimitives
+
+In order to be usable, MLBlocks requires a compatible primitives library.
+
+The official library, required in order to follow the following MLBlocks tutorial,
+is [MLPrimitives](https://github.com/HDI-Project/MLPrimitives), which you can install
+with this command:
+
+```bash
+pip install mlprimitives
+```
+
 # Usage Example
 
 Below there is a short example about how to use MLBlocks to create a simple pipeline, fit it
 using demo data and use it to make predictions.
 
+Please make sure to having installed [MLPrimitives](https://github.com/HDI-Project/MLPrimitives)
+before following it.
+
 For advance usage and more detailed explanation about each component, please have a look
 at the [documentation](https://HDI-Project.github.io/MLBlocks)
 
@@ -81,10 +96,10 @@ them to the `MLPipeline` class.
 >>> pipeline = MLPipeline(primitives)
 ```
 
-Optionally, specific hyperparameters can be also set by specifying them in a dictionary:
+Optionally, specific initialization arguments can be also set by specifying them in a dictionary:
 
 ```python
->>> hyperparameters = {
+>>> init_params = {
 ...    'skimage.feature.hog': {
 ...        'multichannel': True,
 ...        'visualize': False
@@ -93,7 +108,7 @@ Optionally, specific hyperparameters can be also set by specifying them in a dic
 ...         'n_estimators': 100,
 ...    }
 ... }
->>> pipeline = MLPipeline(primitives, hyperparameters)
+>>> pipeline = MLPipeline(primitives, init_params=init_params)
 ```
 
 If you can see which hyperparameters a particular pipeline is using, you can do so by calling

docs/advanced_usage/adding_primitives.rst

@@ -91,20 +91,27 @@ In order to make **MLBLocks** able to find the primitives defined in such a libr
 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.
+1. It has to be published under the group ``mlblocks``.
+2. It has to be named exactly ``primitives``.
+3. It has to point at a variable that contains a path or a list of paths to the JSONS folder(s).
 
 An example of such an entry point would be::
 
     entry_points = {
-        'mlprimitives': [
-            'jsons_path=some_module:SOME_VARIABLE'
+        'mlblocks': [
+            'primitives=some_module:SOME_VARIABLE'
         ]
     }
 
 where the module `some_module` contains a variable such as::
 
-    SOME_VARIABLE = os.path.join(os.path.dirname(__file__), 'jsons')
+    SOME_VARIABLE = 'path/to/primitives'
+
+or::
+
+    SOME_VARIABLE = [
+        'path/to/primitives',
+        'path/to/more/primitives'
+    ]
 
 .. _Entry Point: https://packaging.python.org/specifications/entry-points/

docs/advanced_usage/pipelines.rst

@@ -86,7 +86,7 @@ This can be done by passing an extra dictionary to the MLPipeline when it is cre
             'n_estimators': 100
         }
     }
-    pipeline = MLPipeline(primitives, init_params)
+    pipeline = MLPipeline(primitives, init_params=init_params)
 
 This dictionary must have as keys the name of the blocks that the arguments belong to, and
 as values the dictionary that contains the argument names and their values.
@@ -271,7 +271,7 @@ Like primitives, Pipelines can also be annotated and stored as dicts or JSON fil
 the different arguments expected by the ``MLPipeline`` class, as well as the set hyperparameters
 and tunable hyperparameters.
 
-Representing a  Pipeline as a dict
+Representing a Pipeline as a dict
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The dict representation of an Pipeline can be obtained directly from an ``MLPipeline`` instance,
@@ -344,6 +344,86 @@ that allows loading the pipeline directly from a JSON file:
 
     pipeline = MLPipeline.load('pipeline.json')
 
+
+Intermediate Outputs and Partial Execution
+------------------------------------------
+
+Sometimes we might be interested in capturing an intermediate output within a
+pipeline execution in order to inspect it, for debugging purposes, or to reuse
+it later on in order to speed up a tuning process where the pipeline needs
+to be executed multiple times over the same data.
+
+For this, two special arguments have been included in the ``fit`` and ``predict``
+methods of an MLPipeline:
+
+output\_
+~~~~~~~~
+
+The ``output_`` argument indicates which block within the pipeline we are interested
+in taking the output values from. This, implicitly, indicates up to which block the
+pipeline needs to be executed within ``fit`` and ``predict`` before returning.
+
+The ``output_`` argument is optional, and it can either be ``None``, which is the default,
+and Integer or a String.
+
+And its format is as follows:
+
+* If it is ``None`` (default), the ``fit`` method will return nothing and the
+  ``predict`` method will return the output of the last block in the pipeline.
+* If an integer is given, it is interpreted as the block index, starting on 0,
+  and the whole context after executing the specified block will be returned.
+  In case of ``fit``, this means that the outputs will be returned after fitting
+  a block and then producing it on the same data.
+* If it is a string, it can be interpreted in three ways:
+
+    * **block name**: If the string matches a block name exactly, including
+      its hash and counter number ``#n`` at the end, the whole context will be
+      returned after that block is produced.
+    * **variable_name**: If the string does not match any block name and does
+      not contain any dot character, ``'.'``, it will be considered a variable
+      name. In this case, the indicated variable will be extracted from the
+      context and returned after the last block has been produced.
+    * **block_name + variable_name**: If the complete string does not match a
+      block name but it contains at least one dot, ``'.'``, it will be split
+      in two parts on the last dot. If the first part of the string matches a
+      block name exactly, the second part of the string will be considered a
+      variable name, assuming the format ``{block_name}.{variable_name}``, and
+      the indicated variable will be extracted from the context and returned
+      after the block has been produced. Otherwise, if the extracted
+      ``block_name`` does not match a block name exactly, a ``ValueError``
+      will be raised.
+
+start\_
+~~~~~~~
+
+The ``start_`` argument indicates which block within the pipeline we are interested
+in starting the computation from when executing ``fit`` and ``predict``, allowing us
+to skip some of the initial blocks.
+
+The ``start_`` argument is optional, and it can either be ``None``, which is the default,
+and Integer or a String.
+
+And its format is as follows:
+
+* If it is ``None``, the execution will start on the first block.
+* If it is an integer, it is interpreted as the block index
+* If it is a string, it is expected to be the name of the block, including the counter
+  number at the end.
+
+This is specially useful when used in combination with the ``output_`` argument, as it
+effectively allows us to both capture intermediate outputs for debugging purposes or
+reusing intermediate states of the pipeline to accelerate tuning processes.
+
+An example of this situation, where we want to reuse the output of the first block, could be::
+
+    context_0 = pipeline.fit(X_train, y_train, output_=0)
+
+    # Afterwards, within the tuning loop
+    pipeline.fit(start_=1, **context_0)
+    predictions = pipeline.predict(X_test)
+    score = compute_score(y_test, predictions)
+
+
 .. _API Reference: ../api_reference.html
 .. _primitives: ../primitives.html
 .. _mlblocks.MLPipeline: ../api_reference.html#mlblocks.MLPipeline

docs/api/mlblocks.discovery.rst

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

docs/api/mlblocks.primitives.rst

@@ -1 +1 @@
-.. include:: ../HISTORY.md
+.. mdinclude:: ../HISTORY.md

docs/changelog.rst

@@ -18,18 +18,9 @@
 # relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 
-import os
-import sys
-
 import sphinx_rtd_theme # For read the docs theme
-from recommonmark.parser import CommonMarkParser
-# from recommonmark.transform import AutoStructify
-
-# sys.path.insert(0, os.path.abspath('..'))
 
 import mlblocks
-# 
-# mlblocks.add_primitives_path('../mlblocks_primitives')
 
 # -- General configuration ---------------------------------------------
 
@@ -40,13 +31,21 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'sphinx.ext.napoleon',
+    'm2r',
+    'sphinx.ext.autodoc',
     'sphinx.ext.githubpages',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
     'sphinx.ext.graphviz',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
+    'autodocsumm',
 ]
 
+autodoc_default_options = {
+    'autosummary': True,
+}
+
 ipython_execlines = ["import pandas as pd", "pd.set_option('display.width', 1000000)"]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,10 +55,6 @@
 # You can specify multiple suffix as a list of string:
 source_suffix = ['.rst', '.md', '.ipynb']
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
 # The master toctree document.
 master_doc = 'index'