perceul 0.4.0__py3-none-any.whl

perceul/__init__.py

@@ -0,0 +1,10 @@
+from .clustering import explore_clusters, final_clustering
+from .interpretation import get_pca_loadings
+from .selectors import NumericSelector
+
+__all__ = [
+    "explore_clusters",
+    "final_clustering",
+    "get_pca_loadings",
+    "NumericSelector"
+]

perceul/clustering.py

@@ -0,0 +1,152 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import joblib
+from importlib import resources
+
+from .utils.cluster import *
+from .utils.auxiliary import build_umap, build_hdbscan, format_outliers, format_deviations_as_columns
+
+from sklearn.cluster import KMeans
+
+__all__ = [
+    "explore_clusters",
+    "final_clustering"
+]
+
+# ============================================================
+#                       CLUSTER EXPLORATION 
+# ============================================================
+def explore_clusters(file: str):
+    """
+    Clusters data points using PCA + KMeans, identifies top drivers for each cluster.
+
+    Args:
+        file (str): Path to the input CSV file containing worker data.
+
+    Returns:
+        A tuple containing:
+        * fig (matplotlib.figure.Figure): The HDBSCAN scatter plot figure with clusters and outliers colored.
+        * cluster_summary (dict): A dictionary containing cluster numbers (key) and number of data points within it (value).
+        * outliers (str): Markdown-formatted string showing number of outliers.
+    """
+
+    df = pd.read_csv(file)
+    
+    pkg_resource = resources.files("perceul.assets").joinpath("exploration_pipeline.pkl")
+    
+    with pkg_resource.open("rb") as f:
+        exploration_pipeline = joblib.load(f)
+
+    X_exp = exploration_pipeline.fit_transform(df)
+
+    # dynamic UMAP constructor
+    umap_model = build_umap(df) 
+    X_umap = umap_model.fit_transform(X_exp)
+    
+    # dynamic HDBSCAN constructor
+    hdb = build_hdbscan(df) 
+    labels_hdb = hdb.fit_predict(X_umap)
+
+    # --- cluster statistics ---
+    from collections import Counter
+    label_counts = Counter(labels_hdb)
+
+    n_outliers = label_counts.pop(-1, 0)
+
+    cluster_summary = {
+        f"Cluster {key}": value
+        for key, value in sorted(label_counts.items())
+    }
+
+    # --- visualization ---
+    fig, ax = plt.subplots(figsize=(7, 5))
+
+    ax.scatter(
+        X_umap[:, 0],
+        X_umap[:, 1],
+        c=labels_hdb,
+        s=5,
+        alpha=0.8
+    )
+
+    ax.set_title("Cluster Exploration of Worker Profiles")
+    ax.set_xlabel("Dimension 1")
+    ax.set_ylabel("Dimension 2")
+
+    fig.tight_layout()
+    
+    return fig, cluster_summary, format_outliers(n_outliers)
+
+# ============================================================
+#                      FINAL CLUSTERING 
+# ============================================================
+def final_clustering(file: str, top_features: int):
+    """
+    Clusters data points using PCA + KMeans, identifies top drivers for each cluster.
+
+    Args:
+        file (str): Path to the input CSV file containing worker data.
+        top_features (int): Number of top features to identify as drivers for each cluster.
+
+    Returns:
+        A tuple containing:
+        * fig (matplotlib.figure.Figure): The PCA scatter plot figure with clusters colored.
+        * best_k (int): optimal number of clusters determined by silhouette score.
+        * deviations_markdown (str): markdown-formatted string showing top feature deviations for each cluster.
+        * pca (sklearn.decomposition.PCA): The fitted PCA model.
+        * feature_names (list): List of feature names corresponding to the original data.
+    """
+    df = pd.read_csv(file)
+    
+    pkg_resource = resources.files("perceul.assets").joinpath("core_pipeline.pkl")
+    
+    with pkg_resource.open("rb") as f:
+        core_pipeline = joblib.load(f)
+
+    X_pca = core_pipeline.fit_transform(df)
+
+    best_k = choose_k(X_pca)                                                # choose_k() is from utils.cluster; dynamic `k` selection
+
+    kmeans = KMeans(
+        n_clusters=best_k,
+        random_state=42,
+        n_init="auto"
+    )
+    labels = kmeans.fit_predict(X_pca)
+
+    # ===================================================
+    #               Plotting PCA Clusters
+    # ===================================================
+
+    fig, ax = plt.subplots(figsize=(7, 5))
+    scatter = ax.scatter(
+        X_pca[:, 0],
+        X_pca[:, 1],
+        c=labels,
+        s=5,
+        alpha=0.8
+    )
+    ax.set_title("Final Clustering of Worker Profiles (PCA Space)")
+    ax.set_xlabel("PC1")
+    ax.set_ylabel("PC2")
+    legend1 = ax.legend(*scatter.legend_elements(), title="Clusters")
+    ax.add_artist(legend1)
+    fig.tight_layout()
+
+    # ===================================================
+    #               Cluster Analysis
+    # ===================================================
+    pca = core_pipeline.named_steps["pca"]                                  # Named Step Access to PCA model
+    scaler = core_pipeline.named_steps["scaler"]                            # Named Step Access to Scaler model
+    feature_names = df.columns.tolist()
+    centroids = compute_cluster_centroids_pca(X_pca, labels)                # function is from `cluster_utils.py`; returns a DataFrame with PCA-space centroids for each cluster
+    original_centroids = inverse_project_centroids(
+        centroids,
+        pca,
+        scaler,
+        feature_names
+    )                                                                       # converts PCA-space centroids to original features; returns a DataFrame
+    top_drivers = identify_top_drivers(original_centroids, top_features)    # returns a dict 
+    deviations_markdown = format_deviations_as_columns(top_drivers)         # formats the output as a markdown table string
+
+    return fig, best_k, deviations_markdown, pca, feature_names

perceul/interpretation.py

@@ -0,0 +1,28 @@
+import pandas as pd
+from sklearn.decomposition import PCA 
+
+# ============================================================
+# A function to retreive the loadings of the PCA components
+# ============================================================
+
+def get_pca_loadings(pca: PCA, feature_names: list) -> pd.DataFrame:
+    """
+    Get loadings of PCA components.
+
+    Args:
+        pca (sklearn.decomposition.PCA): PCA object from sklearn
+        feature_names (list): List of feature names corresponding to the original data
+
+    Returns:
+        pd.DataFrame: DataFrame with PCA loadings for each component and feature
+    """
+    loadings = pd.DataFrame(
+        pca.components_.T,                                          # transposes the get features as rows and components as columns
+        columns=[f'PC{i+1}' for i in range(pca.n_components_)],     # names the columns as PC1, PC2, ...
+        index=feature_names                                         # names the rows with the original feature names
+    )
+
+    # Convert the index into a visible column named 'Feature'
+    loadings = loadings.reset_index().rename(columns={'index': 'Feature'})
+
+    return loadings

perceul/selectors.py

@@ -0,0 +1,12 @@
+from sklearn.base import BaseEstimator, TransformerMixin
+
+class NumericSelector(BaseEstimator, TransformerMixin):
+    def __init__(self):
+        pass
+
+    def fit(self, X, y=None):
+        self.numeric_cols_ = X.select_dtypes(include=[float, int]).columns
+        return self
+
+    def transform(self, X):
+        return X[self.numeric_cols_]

perceul/utils/__init__.py

@@ -0,0 +1,14 @@
+from .auxiliary import choose_umap_params, build_hdbscan, build_umap, format_outliers, format_deviations_as_columns
+from .cluster import choose_k, compute_cluster_centroids_pca, compute_cluster_stats, inverse_project_centroids, identify_top_drivers
+
+__all__ = [
+    "choose_umap_params",
+    "build_hdbscan",
+    "build_umap",
+    "format_outliers",
+    "format_deviations_as_columns",
+    "choose_k", "compute_cluster_centroids_pca",
+    "compute_cluster_stats",
+    "inverse_project_centroids",
+    "identify_top_drivers"
+]

perceul/utils/auxiliary.py

@@ -0,0 +1,80 @@
+import numpy as np
+import pandas as pd
+
+import umap as UMAP
+import hdbscan
+
+def choose_umap_params(n_samples, n_features): # created to emphasize local structure of data
+    # use simple heuristic
+    sample_based = int(np.sqrt(n_samples) - 1)
+    feature_based = int(np.log2(n_features) - 1)
+
+    floor = 2
+    min_n_neighbors = min(sample_based, feature_based)
+
+    # find best_min_dist
+    best_min_dist = 0.1 if n_features < 20 else 0.0 
+    
+    return max(floor, min_n_neighbors), best_min_dist
+
+def build_umap(X):
+    n_samples, n_features = X.shape
+
+    # helper function defined above
+    best_n_neighbors, best_min_dist = choose_umap_params(n_samples, n_features)
+    
+    return UMAP(
+        n_neighbors=best_n_neighbors,
+        min_dist=best_min_dist,
+        n_components=2,
+        random_state=42
+    )
+
+def build_hdbscan(X):
+    n_samples = X.shape[0]
+
+    min_cluster_size = int(max(2, 0.01 * n_samples))
+    min_samples = max(2, int(0.5 * min_cluster_size))
+
+    return hdbscan.HDBSCAN(
+        min_cluster_size=min_cluster_size,
+        min_samples=min_samples,
+        cluster_selection_method="eom", # default
+        prediction_data=True # default
+    )
+
+def format_outliers(n_outliers):
+    if n_outliers == 0:
+        return "✅ No outliers detected."
+        
+    return f"⚠️ **{n_outliers} workers** do not strongly belong to any cluster."
+    
+
+def format_deviations_as_columns(drivers: dict) -> str:
+    """
+    Format the top feature deviations for each cluster into a markdown table with clusters as columns.
+
+    Args:
+        drivers (dict): A dictionary where keys are cluster IDs and values are dictionaries containing feature deviations.
+
+    Returns:
+        str: A markdown table with clusters as columns and feature deviations as rows.
+    """
+    headers = []
+    cells = []
+
+    for cid, data in drivers.items():
+        headers.append(f"Cluster {cid}")
+
+        dev_lines = [
+            f"{feature}: {value:.3f}"
+            for feature, value in data["deviations"].items()
+        ]
+
+        cells.append("<br>".join(dev_lines))
+
+    table = "| " + " | ".join(headers) + " |\n"
+    table += "|" + "|".join(["---"] * len(headers)) + "|\n"
+    table += "| " + " | ".join(cells) + " |"
+
+    return table

perceul/utils/cluster.py

@@ -0,0 +1,117 @@
+import pandas as pd 
+from sklearn.metrics import silhouette_score
+from sklearn.cluster import KMeans
+
+__all__ = [
+    "choose_k",
+    "compute_cluster_centroids_pca",
+    "inverse_project_centroids",
+    "compute_cluster_stats",
+    "identify_top_drivers"
+]
+
+#========== Before Final Clustering ========== 
+def choose_k(X_pca):
+    best_k = 2
+    best_score = -1
+    
+    # Ensure k does not exceed n_samples - 1 for silhouette_score validity
+    n_samples = X_pca.shape[0]
+    max_k_for_silhouette = n_samples # range is exclusive of end, so this will allow k up to n_samples - 1
+
+    for k in range(2, min(12, max_k_for_silhouette)):
+        km = KMeans(n_clusters=k, random_state=42, n_init='auto') # Added n_init='auto' to suppress future warning
+        labels = km.fit_predict(X_pca)
+        score = silhouette_score(X_pca, labels)
+
+        if score > best_score:
+            best_score = score
+            best_k = k
+
+    print(f"Executing choose_k()... Best Score: {best_score}")
+
+    return best_k
+
+#========== During Cluster Analysis ========== 
+def compute_cluster_centroids_pca(df_pca: pd.DataFrame, labels: list) -> pd.DataFrame:
+    """
+    Compute cluster centroids in PCA space.
+
+    Args:
+        df_pca (pd.DataFrame): DataFrame with PCA-transformed data.
+        labels (list): List of cluster labels for each data point.
+
+    Returns:
+        pd.DataFrame: DataFrame with cluster centroids.
+    """
+    df = pd.DataFrame(df_pca)
+    df['cluster'] = labels
+
+    return df.groupby('cluster').mean()
+
+# maps PCA-space centroids back to original feature space
+def inverse_project_centroids(pca_centroids, pca_model, scaler_model, original_feature_names) -> pd.DataFrame:
+    """
+    Inverse project PCA-space centroids back to original feature space.
+
+    Args:
+        pca_centroids (pd.DataFrame): DataFrame with PCA-space centroids.
+        pca_model (sklearn.decomposition.PCA): Fitted PCA model.
+        scaler_model (sklearn.preprocessing.StandardScaler): Fitted scaler model.
+        original_feature_names (list): List of original feature names.
+
+    Returns:
+        pd.DataFrame: DataFrame with centroids in original feature space.
+    """
+
+    scaled_centroids = pca_model.inverse_transform(pca_centroids.values) # back-project from PCA space to scaled feature space
+    original_space_centroids = scaler_model.inverse_transform(scaled_centroids) # undo scaling
+
+    df_original = pd.DataFrame(
+        original_space_centroids,
+        columns=original_feature_names,
+        index=pca_centroids.index
+    )
+
+    return df_original
+
+# function to compute and save cluster stats
+def compute_cluster_stats(df_pca, labels, feature_names):
+    df = pd.DataFrame(df_pca, columns=feature_names)
+    df['cluster'] = labels
+
+    stats = {}
+
+    for cluster_id in sorted(df['cluster'].unique()):
+        cluster_data = df[df['cluster'] == cluster_id].drop(columns=['cluster'])
+
+        stats[cluster_id] = {
+            "count": len(cluster_data),
+            "mean": cluster_data.mean().to_dict(),
+            "median": cluster_data.median().to_dict(),
+            "std": cluster_data.std().to_dict(),
+            "min": cluster_data.min().to_dict(),
+            "max": cluster_data.max().to_dict(),
+            "range": (cluster_data.max() - cluster_data.min()).to_dict()
+        }
+
+    return stats
+
+# ranks top drivers based on `top_n`
+def identify_top_drivers(original_space_centroids: pd.DataFrame, top_n: int) -> dict:
+    global_mean = original_space_centroids.mean()
+
+    drivers = {}
+
+    for cluster_id, row in original_space_centroids.iterrows():
+        deviation = row - global_mean
+        ranked = deviation.abs().sort_values(ascending=False)
+
+        top_features = ranked.head(top_n).index.tolist()
+
+        drivers[cluster_id] = {
+            # "top_features": top_features,
+            "deviations": deviation[top_features].to_dict()
+        }
+
+    return drivers

perceul-0.4.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: perceul
+Version: 0.4.0
+Summary: A framework for unsupervised profiling of perception and cognitive-environmental ergonomics in the workplace.
+Author-email: Jasper Gomez <gomezjasper123@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jasper-gomez/perceul
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gradio>=6.20.0
+Requires-Dist: hdbscan>=0.8.40
+Requires-Dist: joblib>=1.5.0
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: numpy>=2.5.0
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: umap-learn>=0.5.10
+Dynamic: license-file
+
+# PERCEUL
+A Framework and Prototype for Unsupervised Profiling of Perception and Cognitive Ergonomics in the Workplace
+
+---
+
+## 📌 Overview
+
+PERCEUL aims to bridge ergonomics and AI, with the project using Unsupervised Learning for clustering latent perceptual profiles of workers in different work settings. It can be used by Ergonomics Analysts and Consultants who are sufficiently knowledgeable on Unsupervised Learning implementation, workflow, and cluster interpretation. The project includes using psychological, perceptual, self-reporting scales or tools, and Unsupervised Learning algorithms and workflow. PERCEUL exists to address the gap in AI and ergonomics, serving as an innovation that automates the profiling of workers for workspace reorganization, resource allocation, and strategic workplace dynamics, ultimately becoming a decision-support tool.
+
+---
+
+## 📂 Contents
+```
+- artifacts
+  - perceul-framework.png
+  - concept-brief.md
+  - pipelines
+    - core_pipeline.pkl
+    - exploration_pipeline.pkl
+- notebooks
+  - PERCEUL.ipynb
+- README.md
+- LICENSE
+- CITATION.cff
+```
+
+--- 
+## 📄 License
+
+This project is licensed under the **MIT License**, which allows commercial and non-commercial use, modification, and distribution, provided that proper attribution is given.
+
+See the full license text in the [`LICENSE`](./LICENSE) file.
+
+---
+
+## 📑 Citation
+
+If you use PERCEUL — whether the framework, methodology, prototype implementation, or any derived components — please cite the repository using the metadata provided in the [`CITATION.cff`](./CITATION.cff) file.
+
+GitHub will automatically generate a “Cite this repository” button that you can use.
+
+---
+
+## 📝 Attribution Requirements
+
+When building upon or reusing this work, please include:
+
+- **Author name**: Jasper Gomez  
+- **Repository name**: PERCEUL  
+- **Repository link**: https://github.com/jasper-gomez/perceul/tree/main
+- **Citation using the `CITATION.cff` metadata**  
+- A note in your documentation, publication, or code comments acknowledging the original work
+
+Example acknowledgment:
+
+> “This work builds on *PERCEUL: A Framework and Prototype for Unsupervised Profiling of Perception and Cognitive Ergonomics in the Workplace* by Jasper Gomez (MIT Licensed).”
+
+Following these guidelines helps support academic and ethical reuse.

perceul-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+perceul/__init__.py,sha256=_7pu5IAKaUif5f52QCaO_V9Wb1OBnHd4yallg2KNESQ,260
+perceul/clustering.py,sha256=KQeAWy7Kic2iAQv71tgYdF1Kgxg8mI7JAyi17ibFD5U,5444
+perceul/interpretation.py,sha256=F0R_c-Jo8maeNMR_Zeearu7zLqL8F78gIf8KHUuieKk,1200
+perceul/selectors.py,sha256=B9UaerWPpS5-XOwf-rpEqaLWUnz0c2AnG2p7vDgqJMw,342
+perceul/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+perceul/assets/core_pipeline.pkl,sha256=UA8eYl3m0TE1hm1XF48LFqi3NEAB5nuMAFYlytFqzmM,678
+perceul/assets/exploration_pipeline.pkl,sha256=UA8eYl3m0TE1hm1XF48LFqi3NEAB5nuMAFYlytFqzmM,678
+perceul/utils/__init__.py,sha256=6FQ-YDiEIYePsjhkscbBXIqMAyUUrBdl3bkO7-zKB_Q,538
+perceul/utils/auxiliary.py,sha256=9dFixtYxCBWjGmgjwIgzvzHQRwlU80yixAd6U-TATIY,2329
+perceul/utils/cluster.py,sha256=4I38KB7AOYvZBkJKTtPI-ZPOKi8fDd6Ax5HgQLhTu0Q,3902
+perceul-0.4.0.dist-info/licenses/LICENSE,sha256=56nX4htom3J4eI-Z-DUhIgJa9rfTdcJuaWUydXvxCZA,1090
+perceul-0.4.0.dist-info/METADATA,sha256=6ZFuse673RHLN9684A4aNYiMeMzndwQvuXt6zh1dygA,3252
+perceul-0.4.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+perceul-0.4.0.dist-info/top_level.txt,sha256=WXygJgoGUI3LLm1fxYDHeBIc0-McvCNvMcDeyyNSG-E,8
+perceul-0.4.0.dist-info/RECORD,,

perceul-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

perceul-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jasper Gomez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

perceul-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+perceul