scikit-learn · jnothman · Sep 23, 2020 · Jul 23, 2020 · Jul 31, 2020 · Jul 31, 2020
diff --git a/doc/model_selection.rst b/doc/model_selection.rst
@@ -15,5 +15,4 @@ Model selection and evaluation
     modules/cross_validation
     modules/grid_search
     modules/model_evaluation
-    modules/model_persistence
     modules/learning_curve
diff --git a/doc/modules/model_persistence.rst b/doc/modules/model_persistence.rst
@@ -5,22 +5,15 @@ Model persistence
 =================
 
 After training a scikit-learn model, it is desirable to have a way to persist
-the model for future use without having to retrain. The following section gives
-you an example of how to persist a model with pickle. We'll also review a few
-security and maintainability issues when working with pickle serialization.
+the model for future use without having to retrain. The following sections give
+you some hints on how to persist a scikit-learn model.
 
-An alternative to pickling is to export the model to another format using one
-of the model export tools listed under :ref:`related_projects`. Unlike
-pickling, once exported you cannot recover the full Scikit-learn estimator
-object, but you can deploy the model for prediction, usually by using tools
-supporting open model interchange formats such as `ONNX <https://onnx.ai/>`_ or
-`PMML <http://dmg.org/pmml/v4-4/GeneralStructure.html>`_.
-
-Persistence example
--------------------
+Python specific serialization
+-----------------------------
 
 It is possible to save a model in scikit-learn by using Python's built-in
-persistence model, namely `pickle <https://docs.python.org/3/library/pickle.html>`_::
+persistence model, namely `pickle
+<https://docs.python.org/3/library/pickle.html>`_::
 
   >>> from sklearn import svm
   >>> from sklearn import datasets
@@ -55,12 +48,13 @@ with::
 
    ``dump`` and ``load`` functions also accept file-like object
    instead of filenames. More information on data persistence with Joblib is
-   available `here <https://joblib.readthedocs.io/en/latest/persistence.html>`_.
+   available `here
+   <https://joblib.readthedocs.io/en/latest/persistence.html>`_.
 
 .. _persistence_limitations:
 
 Security & maintainability limitations
---------------------------------------
+......................................
 
 pickle (and joblib by extension), has some issues regarding maintainability
 and security. Because of this,
@@ -85,8 +79,44 @@ same range as before.
 
 Since a model internal representation may be different on two different
 architectures, dumping a model on one architecture and loading it on
-another architecture is not supported.
+another architecture is not a supported behaviour, even if it might work
+on some cases.
+To overcome the issue of portability, pickle models are often deployed in
+production using containers, like docker.
 
 If you want to know more about these issues and explore other possible
 serialization methods, please refer to this
-`talk by Alex Gaynor <https://pyvideo.org/video/2566/pickles-are-for-delis-not-software>`_.
+`talk by Alex Gaynor
+<https://pyvideo.org/video/2566/pickles-are-for-delis-not-software>`_.
+
+Interoperable formats
+---------------------
+
+For reproducibility and quality control needs, when different architectures
+and environments should be taken into account, exporting the model in
+`Open Neural Network
+Exchange <https://onnx.ai/>`_ format or `Predictive Model Markup Language
+(PMML) <http://dmg.org/pmml/v4-4-1/GeneralStructure.html>`_ format
+might be a better approach than using `pickle` alone.
+These are helpful where you may want to use your model for prediction in a
+different environment from where the model was trained.
+
+ONNX is a binary serialization of the model. It has been developed to improve
+the usability of the interoperable representation of data models.
+It aims to facilitate the conversion of the data
+models between different machine learning frameworks, and to improve their
+portability on different computing architectures. More details are available
+from the `ONNX tutorial <https://onnx.ai/get-started.html>`_.
+To convert scikit-learn model to ONNX a specific tool `sklearn-onnx
+<http://onnx.ai/sklearn-onnx/>`_ has been developed. 
+
+PMML is an implementation of the `XML
+<https://en.wikipedia.org/wiki/XML>`_ document standard
+defined to represent data models together with the data used to generate them.
+Being human and machine readable,
+PMML is a good option for model validation on different platforms and
+long term archiving. On the other hand, as XML in general, its verbosity does
+not help in production when performance is critical.
+To convert scikit-learn model to PMML you can use for example `sklearn2pmml
+<https://github.com/jpmml/sklearn2pmml>`_ distributed under the Affero GPLv3
+license.
diff --git a/doc/tutorial/basic/tutorial.rst b/doc/tutorial/basic/tutorial.rst
@@ -204,52 +204,6 @@ A complete example of this classification problem is available as an
 example that you can run and study:
 :ref:`sphx_glr_auto_examples_classification_plot_digits_classification.py`.
 
-
-Model persistence
------------------
-
-It is possible to save a model in scikit-learn by using Python's built-in
-persistence model, `pickle <https://docs.python.org/2/library/pickle.html>`_::
-
-  >>> from sklearn import svm
-  >>> from sklearn import datasets
-  >>> clf = svm.SVC()
-  >>> X, y = datasets.load_iris(return_X_y=True)
-  >>> clf.fit(X, y)
-  SVC()
-
-  >>> import pickle
-  >>> s = pickle.dumps(clf)
-  >>> clf2 = pickle.loads(s)
-  >>> clf2.predict(X[0:1])
-  array([0])
-  >>> y[0]
-  0
-
-In the specific case of scikit-learn, it may be more interesting to use
-joblib's replacement for pickle (``joblib.dump`` & ``joblib.load``),
-which is more efficient on big data but it can only pickle to the disk
-and not to a string::
-
-  >>> from joblib import dump, load
-  >>> dump(clf, 'filename.joblib') # doctest: +SKIP
-
-Later, you can reload the pickled model (possibly in another Python process)
-with::
-
-  >>> clf = load('filename.joblib') # doctest:+SKIP
-
-.. note::
-
-    ``joblib.dump`` and ``joblib.load`` functions also accept file-like object
-    instead of filenames. More information on data persistence with Joblib is
-    available `here <https://joblib.readthedocs.io/en/latest/persistence.html>`_.
-
-Note that pickle has some security and maintainability issues. Please refer to
-section :ref:`model_persistence` for more detailed information about model
-persistence with scikit-learn.
-
-
 Conventions
 -----------
 

diff --git a/doc/user_guide.rst b/doc/user_guide.rst
@@ -28,3 +28,4 @@ User Guide
    data_transforms.rst
    datasets.rst
    computing.rst
+   modules/model_persistence.rst