machine_learning.k_medoids
==========================

.. py:module:: machine_learning.k_medoids

.. autoapi-nested-parse::

   k-Medoids Clustering Algorithm

   For more details, see:
   https://en.wikipedia.org/wiki/K-medoids



Functions
---------

.. autoapisummary::

   machine_learning.k_medoids._assign_clusters
   machine_learning.k_medoids._compute_distances
   machine_learning.k_medoids._get_data
   machine_learning.k_medoids._initialize_medoids
   machine_learning.k_medoids._update_medoids
   machine_learning.k_medoids.apply_k_medoids
   machine_learning.k_medoids.main


Module Contents
---------------

.. py:function:: _assign_clusters(distances: numpy.ndarray) -> numpy.ndarray

   Assign each data point to the nearest medoid.

   Args:
       distances: Pairwise distance matrix.

   Returns:
       ndarray: Cluster assignments.

   >>> d = np.array([[0.1, 0.4], [0.2, 0.3], [0.9, 0.1]])
   >>> _assign_clusters(d)
   array([0, 0, 1])


.. py:function:: _compute_distances(data_matrix: numpy.ndarray, medoids: numpy.ndarray) -> numpy.ndarray

   Compute pairwise distances between points and medoids.

   Args:
       data_matrix: Input dataset.
       medoids: Indices of current medoids.

   Returns:
       ndarray: Distance matrix of shape (n_samples, n_clusters).

   >>> x = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]])
   >>> d = _compute_distances(x, np.array([0, 2]))
   >>> d.shape
   (3, 2)


.. py:function:: _get_data() -> tuple[numpy.ndarray, numpy.ndarray]

   Load the Iris dataset and return features and labels.

   Returns:
       tuple[ndarray, ndarray]: Feature matrix and target labels.

   >>> features, labels = _get_data()
   >>> features.shape
   (150, 4)
   >>> labels.shape
   (150,)


.. py:function:: _initialize_medoids(n_samples: int, n_clusters: int, random_state: int | None = None) -> numpy.ndarray

   Randomly select initial medoids.

   Args:
       n_samples: Total number of samples.
       n_clusters: Number of clusters.
       random_state: Optional random seed.

   Returns:
       ndarray: Indices of initial medoids.

   >>> np.random.seed(42)
   >>> _initialize_medoids(10, 3).shape
   (3,)


.. py:function:: _update_medoids(data_matrix: numpy.ndarray, clusters: numpy.ndarray, n_clusters: int) -> numpy.ndarray

   Update medoids by minimizing intra-cluster distances.

   Args:
       data_matrix: Dataset.
       clusters: Cluster assignments.
       n_clusters: Number of clusters.

   Returns:
       ndarray: Updated medoid indices.

   >>> x = np.array([[0.0, 0.0], [1.0, 0.0], [5.0, 0.0]])
   >>> clusters = np.array([0, 0, 1])
   >>> _update_medoids(x, clusters, 2).shape
   (2,)


.. py:function:: apply_k_medoids(data_matrix: numpy.ndarray, n_clusters: int = 3, max_iter: int = 100, random_state: int | None = None) -> tuple[numpy.ndarray, numpy.ndarray]

   Apply k-Medoids clustering to a dataset.

   Args:
       data_matrix: Input dataset.
       n_clusters: Number of clusters.
       max_iter: Maximum iterations.
       random_state: Optional random seed.

   Returns:
       tuple[ndarray, ndarray]: Final medoids and cluster assignments.

   >>> features, _ = _get_data()
   >>> medoids, clusters = apply_k_medoids(features, n_clusters=3, max_iter=10)
   >>> len(medoids)
   3


.. py:function:: main() -> None

   Run k-Medoids on the Iris dataset and display results.

   >>> main()  # doctest: +ELLIPSIS
   k-Medoids clustering (first 10 assignments):
   [...]