.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/mlearning/clustering_model/plot_clustering_api.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_mlearning_clustering_model_plot_clustering_api.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_mlearning_clustering_model_plot_clustering_api.py:


High-level functions
====================

The :mod:`gemseo.mlearning` package includes high-level functions
to create clustering models from model class names.

.. GENERATED FROM PYTHON SOURCE LINES 29-41

.. code-block:: Python


    from __future__ import annotations

    from gemseo import configure_logger
    from gemseo import create_benchmark_dataset
    from gemseo.mlearning import create_clustering_model
    from gemseo.mlearning import get_clustering_models
    from gemseo.mlearning import get_clustering_options

    configure_logger()






.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <RootLogger root (INFO)>



.. GENERATED FROM PYTHON SOURCE LINES 42-46

Available models
----------------
Use the :func:`.get_clustering_models`
to list the available model class names:

.. GENERATED FROM PYTHON SOURCE LINES 46-48

.. code-block:: Python

    get_clustering_models()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ['GaussianMixture', 'KMeans']



.. GENERATED FROM PYTHON SOURCE LINES 49-54

Available model options
-----------------------
Use the :func:`.get_clustering_options`
to get the options of a model
from its class name:

.. GENERATED FROM PYTHON SOURCE LINES 54-56

.. code-block:: Python

    get_clustering_options("GaussianMixture", pretty_print=False)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    {'additionalProperties': False, 'description': 'The settings of the Gaussian mixture model.', 'properties': {'transformer': {'additionalProperties': True, 'description': 'The strategies to transform the variables.\n\nThe values are instances of :class:`.BaseTransformer`\nwhile the keys are the names of\neither the variables\nor the groups of variables,\ne.g. ``"inputs"`` or ``"outputs"``\nin the case of the regression algorithms.\nIf a group is specified,\nthe :class:`.BaseTransformer` will be applied\nto all the variables of this group.\nIf :attr:`.IDENTITY`, do not transform the variables.', 'title': 'Transformer', 'type': 'object'}, 'parameters': {'additionalProperties': True, 'description': 'Other parameters.', 'title': 'Parameters', 'type': 'object'}, 'var_names': {'default': [], 'description': 'The names of the variables.', 'items': {'type': 'string'}, 'title': 'Var Names', 'type': 'array'}, 'n_clusters': {'default': 5, 'description': 'The number of clusters of the clustering algorithm.', 'exclusiveMinimum': 0, 'title': 'N Clusters', 'type': 'integer'}, 'random_state': {'anyOf': [{'minimum': 0, 'type': 'integer'}, {'type': 'null'}], 'default': 0, 'description': 'The random state parameter.\n\nIf ``None``, use the global random state instance from ``numpy.random``.\nCreating the model multiple times will produce different results.\nIf ``int``, use a new random number generator seeded by this integer.\nThis will produce the same results.', 'title': 'Random State'}}, 'title': 'GaussianMixture_Settings', 'type': 'object'}



.. GENERATED FROM PYTHON SOURCE LINES 57-68

.. seealso::
   The functions
   :func:`.get_clustering_models` and :func:`.get_clustering_options`
   can be very useful for the developers.
   As a user,
   it may be easier to consult :ref:`this page <gen_clustering_algos>`
   to find out about the different algorithms and their options.

Creation
--------
Given a training dataset, *e.g.*

.. GENERATED FROM PYTHON SOURCE LINES 69-70

.. code-block:: Python

    dataset = create_benchmark_dataset("IrisDataset")







.. GENERATED FROM PYTHON SOURCE LINES 71-73

use the :func:`.create_clustering_model` function
to create a clustering model from its class name and settings:

.. GENERATED FROM PYTHON SOURCE LINES 73-75

.. code-block:: Python

    model = create_clustering_model("KMeans", data=dataset, n_clusters=3)
    model.learn()








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.011 seconds)


.. _sphx_glr_download_examples_mlearning_clustering_model_plot_clustering_api.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_clustering_api.ipynb <plot_clustering_api.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_clustering_api.py <plot_clustering_api.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_clustering_api.zip <plot_clustering_api.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_