feat: add PCA projection support

Author: aleks-iv

README.md

@@ -17,7 +17,8 @@ color points by a chosen column and control which columns are used as features.
 - Feature prep: numeric columns included; low-cardinality categoricals one-hot encoded
   if enabled; user can pick feature columns.
 - Dimensionality reduction: choose [UMAP](https://umap-learn.readthedocs.io/)
-  or [t-SNE](https://scikit-learn.org/stable/modules/generated/sklearn.manifold.TSNE.html),
+  or [t-SNE](https://scikit-learn.org/stable/modules/generated/sklearn.manifold.TSNE.html)
+  or [PCA](https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html),
   with configurable defaults and per-view JSON overrides.
 - Rendering: embedding plotted to PNG.
 - API: `dimred_get_dimred_preview` returns the embedding and metadata
@@ -30,7 +31,7 @@ color points by a chosen column and control which columns are used as features.
 
 1. Add a tabular resource (csv/tsv/xls/xlsx).
 2. Create a new resource view of type `dimred_view`.
-3. (Optional) Choose method (`umap`/`tsne`), pick `Color by column`, and select feature
+3. (Optional) Choose method (`umap`/`tsne`/`pca`), pick `Color by column`, and select feature
    columns.
 4. Save or Preview to see the rendered embedding (PNG).
 
@@ -98,7 +99,7 @@ To install ckanext-dimred:
 General defaults:
 
 - `ckanext.dimred.default_method` (default: `umap`)
-- `ckanext.dimred.allowed_methods` (default: `umap tsne`)
+- `ckanext.dimred.allowed_methods` (default: `umap tsne pca`)
 - `ckanext.dimred.max_file_size_mb` (default: `50`)
 - `ckanext.dimred.max_rows` (default: `50000`)
 - `ckanext.dimred.enable_categorical` (default: `true`)
@@ -117,6 +118,11 @@ t-SNE defaults:
 - `ckanext.dimred.tsne.perplexity` (default: `30`)
 - `ckanext.dimred.tsne.n_components` (default: `2`)
 
+PCA defaults:
+
+- `ckanext.dimred.pca.n_components` (default: `2`)
+- `ckanext.dimred.pca.whiten` (default: `false`)
+
 Example:
 
 ```

ckanext/dimred/config.py

@@ -10,16 +10,17 @@
 
 ENABLE_CATEGORICAL = "ckanext.dimred.enable_categorical"
 MAX_CATEGORIES_FOR_OHE = "ckanext.dimred.max_categories_for_ohe"
-
+CACHE_ENABLED = "ckanext.dimred.cache_enabled"
+CACHE_TTL = "ckanext.dimred.cache_ttl"
 UMAP_N_NEIGHBORS = "ckanext.dimred.umap.n_neighbors"
 UMAP_MIN_DIST = "ckanext.dimred.umap.min_dist"
 UMAP_N_COMPONENTS = "ckanext.dimred.umap.n_components"
 
 TSNE_PERPLEXITY = "ckanext.dimred.tsne.perplexity"
 TSNE_N_COMPONENTS = "ckanext.dimred.tsne.n_components"
 
-CACHE_ENABLED = "ckanext.dimred.cache_enabled"
-CACHE_TTL = "ckanext.dimred.cache_ttl"
+PCA_N_COMPONENTS = "ckanext.dimred.pca.n_components"
+PCA_WHITEN = "ckanext.dimred.pca.whiten"
 
 
 def default_method() -> str:
@@ -56,6 +57,16 @@ def max_categories_for_ohe() -> int:
     return int(tk.config[MAX_CATEGORIES_FOR_OHE])
 
 
+def cache_enabled() -> bool:
+    """Whether caching for dimred previews is enabled."""
+    return tk.asbool(tk.config.get(CACHE_ENABLED, True))
+
+
+def cache_ttl() -> int:
+    """TTL for cached dimred previews in seconds."""
+    return int(tk.config.get(CACHE_TTL, 3600))
+
+
 def umap_n_neighbors() -> int:
     """Default UMAP n_neighbors value."""
     return int(tk.config[UMAP_N_NEIGHBORS])
@@ -82,11 +93,11 @@ def tsne_n_components() -> int:
     return tk.config[TSNE_N_COMPONENTS]
 
 
-def cache_enabled() -> bool:
-    """Whether caching for dimred previews is enabled."""
-    return tk.asbool(tk.config.get(CACHE_ENABLED, True))
+def pca_n_components() -> int:
+    """Number of output components for PCA."""
+    return int(tk.config[PCA_N_COMPONENTS])
 
 
-def cache_ttl() -> int:
-    """TTL for cached dimred previews in seconds."""
-    return int(tk.config.get(CACHE_TTL, 3600))
+def pca_whiten() -> bool:
+    """Whether to whiten PCA output."""
+    return tk.asbool(tk.config.get(PCA_WHITEN, False))

ckanext/dimred/config_declaration.yaml

@@ -11,7 +11,7 @@ groups:
           "Create with default settings" button.
 
       - key: ckanext.dimred.allowed_methods
-        default: umap tsne
+        default: umap tsne pca
         type: list
         description: >
           Space-separated list of enabled methods for dimred previews.
@@ -91,3 +91,17 @@ groups:
         type: int
         description: >
           Number of output components for t-SNE.
+
+  - annotation: PCA defaults
+    options:
+      - key: ckanext.dimred.pca.n_components
+        default: 2
+        type: int
+        description: >
+          Number of output components for PCA.
+
+      - key: ckanext.dimred.pca.whiten
+        default: false
+        type: bool
+        description: >
+          Whether to apply whitening to PCA output.

ckanext/dimred/methods/__init__.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 from ckanext.dimred.methods.base import BaseProjectionMethod
+from ckanext.dimred.methods.pca import PCAProjection
 from ckanext.dimred.methods.tsne import TSNEProjection
 from ckanext.dimred.methods.umap import UMAPProjection
 
 PROJECTION_METHODS: dict[str, type[BaseProjectionMethod]] = {
     UMAPProjection.name: UMAPProjection,
     TSNEProjection.name: TSNEProjection,
+    PCAProjection.name: PCAProjection,
 }
 
 
@@ -22,6 +24,7 @@ def get_projection_method(name: str) -> type[BaseProjectionMethod]:
     "BaseProjectionMethod",
     "UMAPProjection",
     "TSNEProjection",
+    "PCAProjection",
     "PROJECTION_METHODS",
     "get_projection_method",
 ]

ckanext/dimred/methods/pca.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from sklearn.decomposition import PCA
+
+from ckanext.dimred import config as dimred_config
+from ckanext.dimred.methods.base import BaseProjectionMethod
+
+
+class PCAProjection(BaseProjectionMethod):
+    """Wrapper around sklearn.decomposition.PCA."""
+
+    name = "pca"
+
+    def __init__(self, **params: Any) -> None:
+        super().__init__(**params)
+        self._reducer = PCA(
+            n_components=self.params["n_components"],
+            whiten=self.params.get("whiten", False),
+            random_state=self.params.get("random_state", 42),
+        )
+
+    @classmethod
+    def default_params(cls) -> dict[str, Any]:
+        """Return default parameters for PCA."""
+        return {
+            "n_components": dimred_config.pca_n_components(),
+            "whiten": dimred_config.pca_whiten(),
+            "random_state": 42,
+        }
+
+    def fit_transform(self, x_matrix: np.ndarray):
+        """Run PCA and return the embedding matrix."""
+        return self._reducer.fit_transform(x_matrix)

ckanext/dimred/plugin.py

@@ -66,6 +66,16 @@ def setup_template_variables(self, context: types.Context, data_dict: types.Data
         resource = data_dict["resource"]
         resource_view = data_dict["resource_view"]
 
+        if not resource_view.get("id"):
+            return {
+                "image_data_url": None,
+                "meta": {},
+                "error": None,
+                "resource": resource,
+                "resource_view": resource_view,
+                "package": data_dict.get("package", {}),
+            }
+
         try:
             result = tk.get_action("dimred_get_dimred_preview")(
                 context,

ckanext/dimred/tests/test_action.py

@@ -41,6 +41,25 @@ def test_dimred_get_dimred_preview_runs_pipeline(package, create_with_upload):
     assert prepare["n_features"] >= 2
 
 
+@pytest.mark.usefixtures("clean_db", "with_plugins")
+def test_dimred_get_dimred_preview_pca(package, create_with_upload):
+    with open(IRIS_CSV, "rb") as csv:
+        resource = create_with_upload(csv.read(), "iris.csv", format="csv", package_id=package["id"])
+
+    view = call_action(
+        "resource_view_create",
+        {},
+        resource_id=resource["id"],
+        view_type="dimred_view",
+        title="Dimred",
+        method="pca",
+    )
+
+    result = call_action("dimred_get_dimred_preview", id=resource["id"], view_id=view["id"])
+
+    assert result["meta"]["method"] == "pca"
+
+
 @pytest.mark.usefixtures("clean_db", "with_plugins")
 def test_dimred_get_dimred_preview_color_and_features(package, create_with_upload):
     with open(IRIS_CSV, "rb") as csv: