MAINT deprecate HMMs

Fixes scikit-learn#2731.

doc/modules/hmm.rst

@@ -6,6 +6,14 @@ Hidden Markov Models
 
 .. currentmodule:: sklearn.hmm
 
+.. warning::
+
+   The `sklearn.hmm` module has now been deprecated due to it no longer matching
+   the scope and the API of the project. It is scheduled for removal in the
+   0.17 release of the project. Discussions are still underway regarding
+   moving this module to a seperate repository.
+
+
 `sklearn.hmm` implements the Hidden Markov Models (HMMs).
 The HMM is a generative probabilistic model, in which a sequence of observable
 :math:`\mathbf{X}` variable is generated by a sequence of internal hidden

doc/whats_new.rst

@@ -8,6 +8,9 @@
 Changelog
 ---------
 
+   - :mod:`sklearn.hmm` is deprecated. Its removal is planned
+     for the 0.17 release.
+
    - Use of :class:`covariance.EllipticEnvelop` has now been removed after
      deprecation.
      Please use :class:`covariance.EllipticEnvelope` instead.

examples/applications/plot_hmm_stock_analysis.py

@@ -7,6 +7,12 @@
 It uses stock price data, which can be obtained from yahoo finance.
 For more information on how to get stock prices with matplotlib, please refer
 to date_demo1.py of matplotlib.
+
+.. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
 """
 
 from __future__ import print_function

examples/plot_hmm_sampling.py

@@ -10,6 +10,11 @@
 between them. We can see that, as specified by our transition matrix,
 there are no transition between component 1 and 3.
 
+.. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
 """
 print(__doc__)
 

sklearn/hmm.py

@@ -8,8 +8,7 @@
 The :mod:`sklearn.hmm` module implements hidden Markov models.
 
 **Warning:** :mod:`sklearn.hmm` is orphaned, undocumented and has known
-numerical stability issues. If nobody volunteers to write documentation and
-make it more stable, this module will be removed in version 0.11.
+numerical stability issues. This module will be removed in version 0.17.
 """
 
 import string
@@ -37,9 +36,14 @@
 decoder_algorithms = ("viterbi", "map")
 
 
+@deprecated("WARNING: The HMM module and its functions will be removed in 0.17"
+            "as it no longer falls within the project's scope and API.")
 def normalize(A, axis=None):
     """ Normalize the input array so that it sums to 1.
 
+    WARNING: The HMM module and its functions will be removed in 0.17
+    as it no longer falls within the project's scope and API.
+
     Parameters
     ----------
     A: array, shape (n_samples, n_features)
@@ -65,6 +69,8 @@ def normalize(A, axis=None):
     return A / Asum
 
 
+@deprecated("WARNING: The HMM module and its function will be removed in 0.17"
+            "as it no longer falls within the project's scope and API.")
 class _BaseHMM(BaseEstimator):
     """Hidden Markov Model base class.
 
@@ -75,6 +81,11 @@ class _BaseHMM(BaseEstimator):
     See the instance documentation for details specific to a
     particular object.
 
+    .. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
     Attributes
     ----------
     n_components : int
@@ -152,8 +163,6 @@ def __init__(self, n_components=1, startprob=None, transmat=None,
         self._algorithm = algorithm
         self.random_state = random_state
 
-    @deprecated("HMM.eval was renamed to HMM.score_samples in 0.14 and will be"
-                " removed in 0.16.")
     def eval(self, X):
         return self.score_samples(X)
 
@@ -600,6 +609,11 @@ class GaussianHMM(_BaseHMM):
     This class allows for easy evaluation of, sampling from, and
     maximum-likelihood estimation of the parameters of a HMM.
 
+    .. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
     Parameters
     ----------
     n_components : int
@@ -888,6 +902,11 @@ def fit(self, obs):
 class MultinomialHMM(_BaseHMM):
     """Hidden Markov Model with multinomial (discrete) emissions
 
+    .. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
     Attributes
     ----------
     n_components : int
@@ -1081,6 +1100,11 @@ def fit(self, obs, **kwargs):
 class GMMHMM(_BaseHMM):
     """Hidden Markov Model with Gaussin mixture emissions
 
+    .. warning::
+
+       The HMM module and its functions will be removed in 0.17
+       as it no longer falls within the project's scope and API.
+
     Attributes
     ----------
     init_params : string, optional