From bb634fba6663663ed50ddab610182ec73e988553 Mon Sep 17 00:00:00 2001
From: LihongChenWestern <lchen893@uwo.ca>
Date: Mon, 17 Feb 2025 23:45:40 -0500
Subject: [PATCH 1/2] Improve NCA example references in User Guide and API docs

---
 doc/modules/neighbors.rst |  1 +
 sklearn/neighbors/_nca.py | 39 ++++++++++++++++++++++++++-------------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/doc/modules/neighbors.rst b/doc/modules/neighbors.rst
index 82caa397b60d2..4f333989d8998 100644
--- a/doc/modules/neighbors.rst
+++ b/doc/modules/neighbors.rst
@@ -757,6 +757,7 @@ by each method. Each data sample belongs to one of 10 classes.
 
 * :ref:`sphx_glr_auto_examples_neighbors_plot_nca_classification.py`
 * :ref:`sphx_glr_auto_examples_neighbors_plot_nca_dim_reduction.py`
+* :ref:`sphx_glr_auto_examples_neighbors_plot_nca_illustration.py`
 * :ref:`sphx_glr_auto_examples_manifold_plot_lle_digits.py`
 
 .. _nca_mathematical_formulation:
diff --git a/sklearn/neighbors/_nca.py b/sklearn/neighbors/_nca.py
index a4ef3c303b851..4ff98baf35a6d 100644
--- a/sklearn/neighbors/_nca.py
+++ b/sklearn/neighbors/_nca.py
@@ -181,6 +181,19 @@ class NeighborhoodComponentsAnalysis(
     KNeighborsClassifier(...)
     >>> print(knn.score(nca.transform(X_test), y_test))
     0.961904...
+
+    For detailed examples demonstrating the use of
+    :class:`~sklearn.neighbors.NeighborhoodComponentsAnalysis` in different
+    scenarios, please refer to:
+
+    - Illustration of how NCA transforms distances for classification:
+      :ref:`sphx_glr_auto_examples_neighbors_plot_nca_illustration.py`
+
+    - Comparison of NCA, PCA, and LDA for dimensionality reduction:
+      :ref:`sphx_glr_auto_examples_neighbors_plot_nca_dim_reduction.py`
+
+    - Comparing nearest neighbors classification with and without NCA:
+      :ref:`sphx_glr_auto_examples_neighbors_plot_nca_classification.py`
     """
 
     _parameter_constraints: dict = {
@@ -201,16 +214,16 @@ class NeighborhoodComponentsAnalysis(
     }
 
     def __init__(
-        self,
-        n_components=None,
-        *,
-        init="auto",
-        warm_start=False,
-        max_iter=50,
-        tol=1e-5,
-        callback=None,
-        verbose=0,
-        random_state=None,
+            self,
+            n_components=None,
+            *,
+            init="auto",
+            warm_start=False,
+            max_iter=50,
+            tol=1e-5,
+            callback=None,
+            verbose=0,
+            random_state=None,
     ):
         self.n_components = n_components
         self.init = init
@@ -253,9 +266,9 @@ def fit(self, X, y):
             )
         # If warm_start is enabled, check that the inputs are consistent
         if (
-            self.warm_start
-            and hasattr(self, "components_")
-            and self.components_.shape[1] != X.shape[1]
+                self.warm_start
+                and hasattr(self, "components_")
+                and self.components_.shape[1] != X.shape[1]
         ):
             raise ValueError(
                 f"The new inputs dimensionality ({X.shape[1]}) does not "

From a395123971eb65a410f1331d993fcc1216b2ea6b Mon Sep 17 00:00:00 2001
From: LihongChenWestern <lchen893@uwo.ca>
Date: Tue, 18 Feb 2025 00:05:13 -0500
Subject: [PATCH 2/2] Fix formatting issues in _nca.py

---
 sklearn/neighbors/_nca.py | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/sklearn/neighbors/_nca.py b/sklearn/neighbors/_nca.py
index 4ff98baf35a6d..70c20609a6c1d 100644
--- a/sklearn/neighbors/_nca.py
+++ b/sklearn/neighbors/_nca.py
@@ -214,16 +214,16 @@ class NeighborhoodComponentsAnalysis(
     }
 
     def __init__(
-            self,
-            n_components=None,
-            *,
-            init="auto",
-            warm_start=False,
-            max_iter=50,
-            tol=1e-5,
-            callback=None,
-            verbose=0,
-            random_state=None,
+        self,
+        n_components=None,
+        *,
+        init="auto",
+        warm_start=False,
+        max_iter=50,
+        tol=1e-5,
+        callback=None,
+        verbose=0,
+        random_state=None,
     ):
         self.n_components = n_components
         self.init = init
@@ -266,9 +266,9 @@ def fit(self, X, y):
             )
         # If warm_start is enabled, check that the inputs are consistent
         if (
-                self.warm_start
-                and hasattr(self, "components_")
-                and self.components_.shape[1] != X.shape[1]
+            self.warm_start
+            and hasattr(self, "components_")
+            and self.components_.shape[1] != X.shape[1]
         ):
             raise ValueError(
                 f"The new inputs dimensionality ({X.shape[1]}) does not "