documentation

xadupre · xadupre · commit be4c5ab40a3d · 2023-11-05T11:16:09.000+01:00
diff --git a/_doc/api/batch.rst b/_doc/api/batch.rst
@@ -1,6 +1,8 @@
+mlinsights.mlbatch
+==================
 
-Speed up batch training
-=======================
+This was written for older version of scikit-learn and never
+revisited since. It may not bring much value.
 
 MLCache
 +++++++
diff --git a/_doc/api/blaslapack.rst b/_doc/api/blaslapack.rst
@@ -1,9 +1,8 @@
 
-Blas & Lapack
-=============
+mlinsights.mlmodel.direct_blas_lapack
+=====================================
 
-.. contents::
-    :local:
+A simple try to call scipy blas and lapack function from cython.
 
 Lapack
 ++++++
diff --git a/_doc/api/helpers.rst b/_doc/api/helpers.rst
@@ -1,9 +1,6 @@
 
-Helpers
-=======
-
-.. contents::
-    :local:
+mlinsights.helpers
+==================
 
 Formatting
 ++++++++++
diff --git a/_doc/api/index.rst b/_doc/api/index.rst
@@ -10,6 +10,8 @@ API
     metrics
     batch
     mlmodel
+    mlmodel_tree
+    mlmodel_api
     tree
     search_rank
     blaslapack
diff --git a/_doc/api/metrics.rst b/_doc/api/metrics.rst
@@ -1,5 +1,4 @@
-
-metrics
-=======
+mlinsights.metrics
+==================
 
 .. autofunction:: mlinsights.metrics.correlations.non_linear_correlations
diff --git a/_doc/api/mlmodel.rst b/_doc/api/mlmodel.rst
@@ -1,9 +1,6 @@
-=======================
-Machine Learning Models
-=======================
-
-.. contents::
-    :local:
+==================
+mlinsights.mlmodel
+==================
 
 Helpers
 =======
@@ -67,12 +64,6 @@ PiecewiseRegressor
 .. autoclass:: mlinsights.mlmodel.piecewise_estimator.PiecewiseRegressor
     :members:
 
-PiecewiseTreeRegressor
-++++++++++++++++++++++
-
-.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression.PiecewiseTreeRegressor
-    :members:
-
 QuantileMLPRegressor
 ++++++++++++++++++++
 
@@ -160,57 +151,9 @@ TraceableTfidfVectorizer
 .. autoclass:: mlinsights.mlmodel.sklearn_text.TraceableTfidfVectorizer
     :members:
 
-Exploration
-===========
-
-The following implementation play with :epkg:`scikit-learn`
-API, it overwrites the code handling parameters.
-
-SkBaseTransformLearner
-++++++++++++++++++++++
-
-.. autoclass:: mlinsights.sklapi.sklearn_base_transform_learner.SkBaseTransformLearner
-    :members:
-
-SkBaseTransformStacking
-+++++++++++++++++++++++
-
-.. autoclass:: mlinsights.sklapi.sklearn_base_transform_stacking.SkBaseTransformStacking
-    :members:
-
 Exploration in C
 ================
 
-The following classes require :epkg:`scikit-learn` *>= 1.3.0*,
-otherwise, they do not get compiled.
-
-SimpleRegressorCriterion
-++++++++++++++++++++++++
-
-.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression_criterion.SimpleRegressorCriterion
-    :members:
-
-SimpleRegressorCriterionFast
-++++++++++++++++++++++++++++
-
-A similar design but a much faster implementation close to what
-:epkg:`scikit-learn` implements.
-
-.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression_criterion_fast.SimpleRegressorCriterionFast
-    :members:
-
-LinearRegressorCriterion
-++++++++++++++++++++++++
-
-The next one implements a criterion which optimizes the mean square error
-assuming the points falling into one node of the tree are approximated by
-a line. The mean square error is the error made with a linear regressor
-and not a constant anymore. The documentation will be completed later.
-
-`mlinsights.mlmodel.piecewise_tree_regression_criterion_linear.LinearRegressorCriterion`
-
-`mlinsights.mlmodel.piecewise_tree_regression_criterion_linear_fast.SimpleRegressorCriterionFast`
-
 Losses
 ++++++
 
diff --git a/_doc/api/mlmodel_tree.rst b/_doc/api/mlmodel_tree.rst
@@ -0,0 +1,79 @@
+==========================
+mlinsights.mlmodel (trees)
+==========================
+
+.. _blog-internal-api-impurity-improvement:
+
+Note about potentiel issues
+===========================
+
+The main estimator `PiecewiseTreeRegressor` is based on the implementation
+on new criterion. It relies on a non-public API and as such is more likely
+to break. The unit test are unstable. They work when *scikit-learn*
+and this package are compiled with the same set of tools. If installed
+from PyPi, you can check which versions were used at compilation time.
+
+.. runpython::
+    :showcode:
+
+    from mlinsights._config import (
+        CYTHON_VERSION,
+        NUMPY_VERSION,
+        SCIPY_VERSION,
+        SKLEARN_VERSION,
+    )
+    print(f"CYTHON_VERSION: {CYTHON_VERSION}")
+    print(f"NUMPY_VERSION: {NUMPY_VERSION}")
+    print(f"SCIPY_VERSION: {SCIPY_VERSION}")
+    print(f"SKLEARN_VERSION: {SKLEARN_VERSION}")
+
+
+The signature of method *impurity_improvement* has changed in version 0.24.
+That's usually easy to handle two versions of *scikit-learn* even overloaded
+in a class except that method is implemented in cython.
+The method must be overloaded the same way with the same signature.
+Tricks such as `*args` or `**kwargs` cannot be used.
+The way it was handled is implemented in
+PR `88 <https://github.com/sdpython/mlinsights/pull/88>`_.
+
+Estimators
+==========
+
+PiecewiseTreeRegressor
+++++++++++++++++++++++
+
+.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression.PiecewiseTreeRegressor
+    :members:
+
+Criterions
+==========
+
+The following classes require :epkg:`scikit-learn` *>= 1.3.0*,
+otherwise, they do not get compiled.
+
+SimpleRegressorCriterion
+++++++++++++++++++++++++
+
+.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression_criterion.SimpleRegressorCriterion
+    :members:
+
+SimpleRegressorCriterionFast
+++++++++++++++++++++++++++++
+
+A similar design but a much faster implementation close to what
+:epkg:`scikit-learn` implements.
+
+.. autoclass:: mlinsights.mlmodel.piecewise_tree_regression_criterion_fast.SimpleRegressorCriterionFast
+    :members:
+
+LinearRegressorCriterion
+++++++++++++++++++++++++
+
+The next one implements a criterion which optimizes the mean square error
+assuming the points falling into one node of the tree are approximated by
+a line. The mean square error is the error made with a linear regressor
+and not a constant anymore. The documentation will be completed later.
+
+`mlinsights.mlmodel.piecewise_tree_regression_criterion_linear.LinearRegressorCriterion`
+
+`mlinsights.mlmodel.piecewise_tree_regression_criterion_linear_fast.SimpleRegressorCriterionFast`
diff --git a/_doc/api/plotting.rst b/_doc/api/plotting.rst
@@ -1,6 +1,5 @@
-
-plotting
-========
+mlinsights.plotting
+===================
 
 .. autofunction:: mlinsights.plotting.gallery.plot_gallery_images
 
diff --git a/_doc/api/search_rank.rst b/_doc/api/search_rank.rst
@@ -1,6 +1,5 @@
-
-search_rank
-===========
+mlinsights.search_rank
+======================
 
 SearchEngineVectors
 +++++++++++++++++++
diff --git a/_doc/api/sklapi.rst b/_doc/api/sklapi.rst
@@ -0,0 +1,61 @@
+=================
+mlinsights.sklapi
+=================
+
+The following implementation play with :epkg:`scikit-learn`
+API, it overwrites the code handling parameters. It is pretty much
+useless unless to check the stability of the API.
+
+SkBase
+++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base.SkBase
+    :members:
+
+SkBaseClassifier
+++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_classifier.SkBaseClassifier
+    :members:
+
+SkException
++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_parameters.SkException
+    :members:
+
+SkBaseLearner
++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_learner.SkBaseLearner
+    :members:
+
+SkLearnParameters
++++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_parameters.SkLearnParameters
+    :members:
+
+SkBaseRegressor
++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_regressor.SkBaseRegressor
+    :members:
+
+SkBaseTransform
++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_transform.SkBaseTransform
+    :members:
+
+SkBaseTransformLearner
+++++++++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_transform_learner.SkBaseTransformLearner
+    :members:
+
+SkBaseTransformStacking
++++++++++++++++++++++++
+
+.. autoclass:: mlinsights.sklapi.sklearn_base_transform_stacking.SkBaseTransformStacking
+    :members:
diff --git a/_doc/api/timeseries.rst b/_doc/api/timeseries.rst
@@ -1,6 +1,6 @@
-==========
-Timeseries
-==========
+=====================
+mlinsights.timeseries
+=====================
 
 Datasets
 ========
diff --git a/_doc/api/tree.rst b/_doc/api/tree.rst
@@ -2,9 +2,6 @@
 Trees
 =====
 
-.. contents::
-    :local:
-
 Digging into the tree structure
 +++++++++++++++++++++++++++++++
 
diff --git a/_doc/i_ex.rst b/_doc/i_ex.rst
@@ -1,9 +1,6 @@
 Short Examples
 ==============
 
-.. contents::
-    :local:
-
 .. exreflist::
     :contents:
     :tag: sklearn
diff --git a/_doc/i_faq.rst b/_doc/i_faq.rst
@@ -1,8 +1,5 @@
 FAQ
 ===
 
-.. contents::
-    :local:
-
 .. faqreflist::
     :contents:
diff --git a/mlinsights/mlmodel/_piecewise_tree_regression_common.pyx b/mlinsights/mlmodel/_piecewise_tree_regression_common.pyx
@@ -22,9 +22,9 @@ cdef class CommonRegressorCriterion(Criterion):
     This implementation is not efficient but was made that way on purpose.
     It adds the features to the class.
 
-    If the file does not compile, some explanations are given
+    If the file does not compile or crashes, some explanations are given
     in :ref:`scikit-learn internal API
-    <blog-internal-api-impurity-improvement>`_.
+    <blog-internal-api-impurity-improvement>`.
     """
     def __getstate__(self):
         return {}
diff --git a/mlinsights/mlmodel/piecewise_tree_regression.py b/mlinsights/mlmodel/piecewise_tree_regression.py
@@ -12,6 +12,10 @@ class PiecewiseTreeRegressor(DecisionTreeRegressor):
 
     * ``mselin``: optimizes for a piecewise linear regression
     * ``simple``: optimizes for a stepwise regression (equivalent to *mse*)
+
+    If the file does not compile or crashes, some explanations are given
+    in :ref:`scikit-learn internal API
+    <blog-internal-api-impurity-improvement>`.
     """
 
     def __init__(
diff --git a/mlinsights/mlmodel/piecewise_tree_regression_criterion.pyx b/mlinsights/mlmodel/piecewise_tree_regression_criterion.pyx
@@ -26,6 +26,10 @@ cdef class SimpleRegressorCriterion(CommonRegressorCriterion):
     <https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/tree/_criterion.pyx>`_.
     This implementation is not efficient but was made that way on purpose.
     It adds the features to the class.
+
+    If the file does not compile or crashes, some explanations are given
+    in :ref:`scikit-learn internal API
+    <blog-internal-api-impurity-improvement>`.
     """
     cdef float64_t* sample_w
     cdef float64_t* sample_wy
diff --git a/mlinsights/mlmodel/piecewise_tree_regression_criterion_fast.pyx b/mlinsights/mlmodel/piecewise_tree_regression_criterion_fast.pyx
@@ -21,6 +21,10 @@ cdef class SimpleRegressorCriterionFast(CommonRegressorCriterion):
     This implementation is faster as it computes
     cumulated sums and avoids loops to compute
     intermediate gains.
+
+    If the file does not compile or crashes, some explanations are given
+    in :ref:`scikit-learn internal API
+    <blog-internal-api-impurity-improvement>`.
     """
     cdef float64_t* sample_w_left
     cdef float64_t* sample_wy2_left
diff --git a/mlinsights/mlmodel/piecewise_tree_regression_criterion_linear.pyx b/mlinsights/mlmodel/piecewise_tree_regression_criterion_linear.pyx
@@ -24,6 +24,10 @@ cdef class LinearRegressorCriterion(CommonRegressorCriterion):
     design used in :class:`SimpleRegressorCriterion
     <mlinsights.mlmodel.piecewise_tree_regression_criterion.SimpleRegressorCriterion>`
     and is even slow as the criterion is more complex to compute.
+
+    If the file does not compile or crashes, some explanations are given
+    in :ref:`scikit-learn internal API
+    <blog-internal-api-impurity-improvement>`.
     """
     cdef SIZE_t n_features
     cdef const float64_t[:, ::1] sample_X
