Add PaCMAP dimensionality reduction (closes #173)

.github/workflows/ci.yml

@@ -12,8 +12,8 @@ jobs:
   qa:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7.0.1
-      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: actions/checkout@v7.0.0
+      - uses: astral-sh/setup-uv@v8.3.2
         with:
           python-version: "3.14"
           enable-cache: true
@@ -28,8 +28,8 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v7.0.1
-      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: actions/checkout@v7.0.0
+      - uses: astral-sh/setup-uv@v8.3.2
         with:
           python-version: "3.14"
           enable-cache: true
@@ -48,9 +48,9 @@ jobs:
 
     runs-on: ${{matrix.os}}
     steps:
-      - uses: actions/checkout@v7.0.1
+      - uses: actions/checkout@v7.0.0
       - name: Set up uv and Python ${{ matrix.python-version }}
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v8.3.2
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true

.github/workflows/docs.yml

@@ -18,10 +18,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7.0.1
+      - uses: actions/checkout@v7.0.0
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: astral-sh/setup-uv@v8.3.2
         with:
           python-version: "3.14"
           enable-cache: true

.github/workflows/python-publish.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v7.0.1
+      - uses: actions/checkout@v7.0.0
       - name: Set up uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v8.3.2
         with:
           python-version: "3.14"
           enable-cache: true
@@ -31,7 +31,7 @@ jobs:
       - name: Build package
         run: uv build
       - name: Publish package
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
         with:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}

pyproject.toml

@@ -38,6 +38,7 @@ dependencies = [
     "adjustText>=0.8",
     "openTSNE>=1.0.0",
     "llvmlite>=0.40",
+    "pacmap>=0.7.0",
 ]
 
 [project.optional-dependencies]

src/elementembeddings/_base.py

@@ -11,6 +11,7 @@
 import numpy as np
 import pandas as pd
 from openTSNE import TSNE
+from pacmap import PaCMAP
 from scipy.stats import energy_distance, pearsonr, spearmanr, wasserstein_distance
 from sklearn import decomposition
 from sklearn.metrics import DistanceMetric
@@ -260,6 +261,40 @@ def calculate_umap(self, n_components: int = 2, standardise: bool = True, **kwar
         umap = UMAP(n_components=n_components, **kwargs)
         return umap.fit_transform(embeddings_array)
 
+    def calculate_pacmap(
+        self,
+        n_components: int = 2,
+        standardise: bool = True,
+        init: str = "pca",
+        **kwargs,
+    ):
+        """Calculate PaCMAP (Pairwise Controlled Manifold Approximation) embeddings.
+
+        Args:
+        ----
+            n_components (int): The number of components to project the embeddings to.
+            standardise (bool): Whether to scale the embeddings before projecting.
+            init (str): Initialisation of the low-dimensional embedding, passed to
+                ``PaCMAP.fit_transform`` (e.g. ``"pca"`` or ``"random"``).
+            **kwargs: Other keyword arguments to be passed to PaCMAP.
+        """
+        if standardise:
+            if self.is_standardised:
+                embeddings_array = np.array(list(self.embeddings.values()))
+            else:
+                self.standardise(inplace=True)
+                embeddings_array = np.array(list(self.embeddings.values()))
+        else:
+            warnings.warn(
+                """It is recommended to scale the embeddings
+                before projecting with PaCMAP.
+                To do so, set `standardise=True`.""",
+            )
+            embeddings_array = np.array(list(self.embeddings.values()))
+
+        pacmap = PaCMAP(n_components=n_components, **kwargs)
+        return pacmap.fit_transform(embeddings_array, init=init)
+
     def compute_correlation_metric(
         self,
         el_sp1: str,

src/elementembeddings/plotter.py

@@ -115,7 +115,8 @@ def dimension_plotter(
         embedding (Embedding): The embedding to be plotted.
         ax (plt.axes, optional): The axes to plot on, by default None
         n_components (int): The number of components to reduce to, by default 2
-        reducer (str): The dimensionality reduction algorithm to use, by default "umap"
+        reducer (str): The dimensionality reduction algorithm to use. One of
+        "umap", "tsne", "pca" or "pacmap", by default "umap"
         adjusttext (bool): Whether to avoid overlap of the text labels, by default True
         reducer_params (dict, optional): Additional keyword arguments to pass to
         the reducer, by default None
@@ -132,8 +133,10 @@ def dimension_plotter(
         reduced = embedding.calculate_tsne(n_components=n_components, **reducer_params)
     elif reducer == "pca":
         reduced = embedding.calculate_pca(n_components=n_components, **reducer_params)
+    elif reducer == "pacmap":
+        reduced = embedding.calculate_pacmap(n_components=n_components, **reducer_params)
     else:
-        msg = "Unrecognised reducer."
+        msg = f"Unrecognised reducer: {reducer!r}. Expected one of 'umap', 'tsne', 'pca' or 'pacmap'."
         raise ValueError(msg)
 
     if isinstance(embedding, Embedding):

tests/test_core.py

@@ -474,6 +474,18 @@ def test_UMAP(self):
         umap2 = self.test_matscholar.calculate_umap(n_neighbors=15, random_state=42)
         assert (umap1 == umap2).all()
 
+    def test_PaCMAP(self):
+        """Test the PaCMAP function."""
+        pacmap_params = {"random_state": 42}
+        assert isinstance(self.test_matscholar.calculate_pacmap(), np.ndarray)
+        assert self.test_matscholar.calculate_pacmap().shape == (
+            len(self.test_matscholar.element_list),
+            2,
+        )
+        pacmap1 = self.test_matscholar.calculate_pacmap(**pacmap_params)
+        pacmap2 = self.test_matscholar.calculate_pacmap(**pacmap_params)
+        assert (pacmap1 == pacmap2).all()
+
 
 class SpeciesEmbeddingTest(unittest.TestCase):
     """Test the SpeciesEmbedding class."""

tests/test_plotter.py

@@ -131,6 +131,13 @@ def test_dimension_2d_plotter(self):
             adjusttext=True,
         )
         assert isinstance(skipatom_umap_plot, plt.Axes)
+        skipatom_pacmap_plot = dimension_plotter(
+            self.test_skipatom,
+            n_components=2,
+            reducer="pacmap",
+            adjusttext=False,
+        )
+        assert isinstance(skipatom_pacmap_plot, plt.Axes)
 
         with pytest.raises(ValueError):
             dimension_plotter(