workbench 0.8.89__py3-none-any.whl

workbench/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2021-2024 SuperCowPowers LLC
+
+"""
+Workbench Main Classes
+- Artifacts
+  - DataSource
+  - FeatureSet
+  - Model
+  - Endpoint
+- Transforms
+  - DataLoaders
+  - DataToData
+  - DataToFeatures
+  - FeaturesToModel
+  - ModelToEndpoint
+
+  For help on particular classes you can do this
+  - from workbench.core.transforms.data_loaders.light.json_to_data_source import JSONToDataSource
+  - help(JSONToDataSource)
+
+
+      class JSONToDataSource(workbench.core.transforms.transform.Transform)
+     |  JSONToDataSource(json_file_path: str, data_uuid: str)
+     |
+     |  JSONToDataSource: Class to move local JSON Files into a Workbench DataSource
+     |
+     |  Common Usage:
+     |      json_to_data = JSONToDataSource(json_file_path, data_uuid)
+     |      json_to_data.set_output_tags(["abalone", "json", "whatever"])
+     |      json_to_data.transform()
+"""
+import os
+from importlib.metadata import version
+
+try:
+    __version__ = version("workbench")
+except Exception:
+    __version__ = "unknown"
+
+# Workbench Logging
+from workbench.utils.workbench_logging import logging_setup
+
+# Check the environment variable to decide whether to set up logging
+if os.getenv("WORKBENCH_SKIP_LOGGING", "False").lower() != "true":
+    logging_setup()

workbench/algorithms/dataframe/Readme.md

@@ -0,0 +1,3 @@
+# Algorithms: Dataframe
+- **Dataframes:** These algorithms are algorithms that have Pandas Dataframes as inputs and typically (not always) DataFrames as outputs. Depedending on the algorithm they might have outputs like dictionaries or lists.
+- **Light:** These algorithms are considered **light** algorithms since they are contrained by one process where the data is in memory.

workbench/algorithms/dataframe/__init__.py

@@ -0,0 +1,12 @@
+"""Welcome to the Dataframe Algorithm Classes
+
+These classes provide functionality for Pandas Dataframes
+
+- TBD: TBD
+"""
+
+from .feature_space_proximity import FeatureSpaceProximity
+from .residuals_calculator import ResidualsCalculator
+from .dimensionality_reduction import DimensionalityReduction
+
+__all__ = ["FeatureSpaceProximity", "ResidualsCalculator", "DimensionalityReduction"]

workbench/algorithms/dataframe/aggregation.py

@@ -0,0 +1,99 @@
+"""Aggregation: Perform Row Aggregation on a DataFrame"""
+
+import pandas as pd
+import logging
+
+# Workbench Logger
+log = logging.getLogger("workbench")
+
+
+def aggregate(df: pd.DataFrame, group_column: str, features: list = None) -> pd.DataFrame:
+    """Aggregate Row of a DataFrame
+    Args:
+        df: Pandas DataFrame
+        group_column: The column to aggregate/group on
+        features: List of column names (numeric) to perform aggregation on (default: None)
+    Returns:
+        Pandas DataFrame with aggregated rows and averaged numeric columns
+    """
+
+    # If no features are given, indentify all numeric columns
+    if features is None:
+        features = [x for x in df.select_dtypes(include="number").columns.tolist() if not x.endswith("id")]
+        log.info("No features given, auto identifying numeric columns...")
+        log.info(f"{features}")
+
+    # Sanity checks
+    if not all(column in df.columns for column in features):
+        log.critical("Some features are missing in the DataFrame")
+        return df
+    if df.empty:
+        log.critical("DataFrame is empty")
+        return df
+
+    # Now aggregate the DataFrame
+    log.info(f"Aggregating dataframe, averaging {features}...")
+
+    # Subset the DataFrame to only the features and group column
+    df = df[features + [group_column]].copy()
+    df["group_count"] = 1
+
+    # Define the aggregation methods for each column
+    agg_methods = {feature: "mean" for feature in features}
+    agg_methods["group_count"] = "size"
+
+    # Group by the group column and perform the aggregation
+    df = df.groupby(group_column).agg(agg_methods).reset_index()
+
+    # Return the DataFrame
+    return df
+
+
+def test():
+    """Test for the Row Aggregation Class"""
+    # Set some pandas options
+    pd.set_option("display.max_columns", None)
+    pd.set_option("display.width", 1000)
+
+    # Make some fake data
+    data = {
+        "ID": [
+            "id_0",
+            "id_0",
+            "id_2",
+            "id_3",
+            "id_4",
+            "id_5",
+            "id_6",
+            "id_7",
+            "id_8",
+            "id_9",
+        ],
+        "feat1": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat2": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat3": [0.1, 0.1, 0.2, 1.6, 2.5, 0.1, 0.1, 0.2, 1.6, 2.5],
+        "price": [31, 60, 62, 40, 20, 31, 61, 60, 40, 20],
+        "outlier_group": [
+            "sample",
+            "a_low",
+            "sample",
+            "b_high",
+            "sample",
+            "c_high",
+            "sample",
+            "d_low",
+            "sample",
+            "e_high",
+        ],
+    }
+    data_df = pd.DataFrame(data)
+
+    # Aggregate the DataFrame
+    new_df = aggregate(data_df, group_column="outlier_group")
+
+    # Output the DataFrame
+    print(new_df)
+
+
+if __name__ == "__main__":
+    test()

workbench/algorithms/dataframe/data_source_eda.py

@@ -0,0 +1,46 @@
+"""DataSourceEDA: Provide basic EDA (Exploratory Data Analysis) for a DataFrame"""
+
+import pandas as pd
+import logging
+
+# Local Imports
+from workbench.core.transforms.pandas_transforms.data_to_pandas import DataToPandas
+from workbench.utils import pandas_utils
+
+
+class DataSourceEDA:
+    def __init__(self, data_source_uuid: str):
+        """DataSourceEDA: Provide basic EDA (Exploratory Data Analysis) for a DataSource
+        Args:
+            data_source_uuid (AthenaSource): DataSource for Exploratory Data Analysis"""
+        self.log = logging.getLogger("workbench")
+        self.data_source_uuid = data_source_uuid
+
+        # Spin up the DataToPandas class
+        self.data_to_pandas = DataToPandas(self.data_source_uuid)
+        self.log.info(f"Getting DataFrame from {self.data_source_uuid}...")
+        self.data_to_pandas.transform()
+        self.df = self.data_to_pandas.get_output()
+
+    def get_column_info(self):
+        """Return the Column Information for the DataSource"""
+        column_info_df = pandas_utils.info(self.df)
+        return column_info_df
+
+    def get_numeric_stats(self):
+        """Return the Column Information for the DataSource"""
+        stats_df = pandas_utils.numeric_stats(self.df)
+        return stats_df
+
+
+if __name__ == "__main__":
+    """Exercise the DataSourceEDA Class"""
+
+    # Set some pandas options
+    pd.set_option("display.max_columns", None)
+    pd.set_option("display.width", 1000)
+
+    # Spin up the class and get the EDA output
+    my_eda = DataSourceEDA("abalone_data")
+    print(my_eda.get_column_info())
+    print(my_eda.get_numeric_stats())

workbench/algorithms/dataframe/dimensionality_reduction.py

@@ -0,0 +1,145 @@
+"""DimensionalityReduction: Perform Dimensionality Reduction on a DataFrame"""
+
+import numpy as np
+import pandas as pd
+import logging
+from sklearn.manifold import TSNE, MDS
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import StandardScaler
+
+
+# Dimensionality Reduction Class
+class DimensionalityReduction:
+    def __init__(self):
+        """DimensionalityReduction:  Perform Dimensionality Reduction on a DataFrame"""
+        self.log = logging.getLogger("workbench")
+        self.projection_model = None
+        self.features = None
+
+    def fit_transform(self, df: pd.DataFrame, features: list = None, projection: str = "TSNE") -> pd.DataFrame:
+        """Fit and Transform the DataFrame
+        Args:
+            df: Pandas DataFrame
+            features: List of feature column names (default: None)
+            projection: The projection model to use (TSNE, MDS or PCA, default: PCA)
+        Returns:
+            Pandas DataFrame with new columns x and y
+        """
+
+        # If no features are given, indentify all numeric columns
+        if features is None:
+            features = [x for x in df.select_dtypes(include="number").columns.tolist() if not x.endswith("id")]
+            # Also drop group_count if it exists
+            features = [x for x in features if x != "group_count"]
+            self.log.info("No features given, auto identifying numeric columns...")
+            self.log.info(f"{features}")
+        self.features = features
+
+        # Sanity checks
+        if not all(column in df.columns for column in self.features):
+            self.log.critical("Some features are missing in the DataFrame")
+            return df
+        if len(self.features) < 2:
+            self.log.critical("At least two features are required")
+            return df
+        if df.empty:
+            self.log.critical("DataFrame is empty")
+            return df
+
+        # Most projection models will fail if there are any NaNs in the data
+        # So we'll fill NaNs with the mean value for that column
+        for col in df[self.features].columns:
+            df[col].fillna(df[col].mean(), inplace=True)
+
+        # Normalize the features
+        scaler = StandardScaler()
+        normalized_data = scaler.fit_transform(df[self.features])
+        df[self.features] = normalized_data
+
+        # Project the multidimensional features onto an x,y plane
+        self.log.info("Projecting features onto an x,y plane...")
+
+        # Perform the projection
+        if projection == "TSNE":
+            # Perplexity is a hyperparameter that controls the number of neighbors used to compute the manifold
+            # The number of neighbors should be less than the number of samples
+            perplexity = min(40, len(df) - 1)
+            self.log.info(f"Perplexity: {perplexity}")
+            self.projection_model = TSNE(perplexity=perplexity)
+        elif projection == "MDS":
+            self.projection_model = MDS(n_components=2, random_state=0)
+        elif projection == "PCA":
+            self.projection_model = PCA(n_components=2)
+
+        # Fit the projection model
+        # Hack PCA + TSNE to work together
+        projection = self.projection_model.fit_transform(df[self.features])
+
+        # Put the projection results back into the given DataFrame
+        df["x"] = projection[:, 0]  # Projection X Column
+        df["y"] = projection[:, 1]  # Projection Y Column
+
+        # Jitter the data to resolve coincident points
+        # df = self.resolve_coincident_points(df)
+
+        # Return the DataFrame with the new columns
+        return df
+
+    @staticmethod
+    def resolve_coincident_points(df: pd.DataFrame):
+        """Resolve coincident points in a DataFrame
+        Args:
+            df(pd.DataFrame): The DataFrame to resolve coincident points in
+        Returns:
+            pd.DataFrame: The DataFrame with resolved coincident points
+        """
+        # Adding Jitter to the projection
+        x_scale = (df["x"].max() - df["x"].min()) * 0.1
+        y_scale = (df["y"].max() - df["y"].min()) * 0.1
+        df["x"] += np.random.normal(-x_scale, +x_scale, len(df))
+        df["y"] += np.random.normal(-y_scale, +y_scale, len(df))
+        return df
+
+
+def test():
+    """Test for the Dimensionality Reduction Class"""
+    # Set some pandas options
+    pd.set_option("display.max_columns", None)
+    pd.set_option("display.width", 1000)
+
+    # Make some fake data
+    data = {
+        "ID": [
+            "id_0",
+            "id_0",
+            "id_2",
+            "id_3",
+            "id_4",
+            "id_5",
+            "id_6",
+            "id_7",
+            "id_8",
+            "id_9",
+        ],
+        "feat1": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat2": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat3": [0.1, 0.1, 0.2, 1.6, 2.5, 0.1, 0.1, 0.2, 1.6, 2.5],
+        "price": [31, 60, 62, 40, 20, 31, 61, 60, 40, 20],
+    }
+    data_df = pd.DataFrame(data)
+    features = ["feat1", "feat2", "feat3"]
+
+    # Create the class and run the dimensionality reduction
+    projection = DimensionalityReduction()
+    new_df = projection.fit_transform(data_df, features=features, projection="TSNE")
+
+    # Check that the x and y columns were added
+    assert "x" in new_df.columns
+    assert "y" in new_df.columns
+
+    # Output the DataFrame
+    print(new_df)
+
+
+if __name__ == "__main__":
+    test()

workbench/algorithms/dataframe/feature_resolution.py

@@ -0,0 +1,243 @@
+"""FeatureResolution: Report on Feature Space Resolution Issues"""
+
+import logging
+from typing import Union
+import pandas as pd
+from sklearn.neighbors import KNeighborsRegressor
+from sklearn.preprocessing import StandardScaler
+
+# Workbench Imports
+from workbench.utils.pandas_utils import DataFrameBuilder
+
+
+# Feature Resolution Class
+class FeatureResolution:
+    def __init__(
+        self,
+        input_df: pd.DataFrame,
+        features: list,
+        target_column: str,
+        id_column: str,
+        distance_metric: str = "minkowski",
+    ):
+        """Initialize the FeatureResolution object
+
+        Args:
+            distance_metric: Distance metric to use (default: "minkowski")
+        """
+        self.log = logging.getLogger("workbench")
+        self.df = input_df.copy().reset_index(drop=True)
+        self.features = features
+        self.target_column = target_column
+        self.id_column = id_column
+        self.n_neighbors = 10
+        self.scalar = StandardScaler()
+        self.knn = KNeighborsRegressor(metric=distance_metric, n_neighbors=self.n_neighbors, weights="distance")
+        self.dataframe_builder = DataFrameBuilder()
+        self.recursive_df_list = []
+
+    def compute(
+        self, within_distance: float, min_target_difference: float, output_columns: list = [], verbose=True
+    ) -> Union[pd.DataFrame, None]:
+        """FeatureResolution: Compute Feature Space to Target Resolution and Report Issues
+
+        Args:
+            within_distance: Features within this distance should have similar target values
+            min_target_difference: Minimum target difference to consider
+            output_columns: List of additional columns to output (default: []])
+            verbose: Whether to print out the resolution issues (default: True)
+
+        Returns:
+            Pandas DataFrame of Feature Space to Target Resolution Issues
+            Includes any additional output_columns if specified
+        """
+
+        # Check for expected columns
+        for column in [self.target_column] + self.features:
+            if column not in self.df.columns:
+                self.log.error(f"DataFrame does not have required {column} Column!")
+                return
+
+        # Set up the output columns (add id and target columns if they are not already included)
+        output_columns = list(set(output_columns).union({self.id_column, self.target_column}))
+
+        # Check the output columns
+        if output_columns is not None:
+            for column in output_columns:
+                if column not in self.df.columns:
+                    self.log.error(f"DataFrame does not have required {column} Column!")
+                    return
+
+        # Check for NaNs in the features and log the percentage
+        for feature in self.features:
+            nan_count = self.df[feature].isna().sum()
+            if nan_count > 0:
+                print(f"Feature '{feature}' has {nan_count} NaNs ({nan_count / len(self.df) * 100:.2f}%).")
+
+        # Remove and NaNs or INFs in the features
+        self.log.info(f"Dataframe Shape before NaN/INF removal {self.df.shape}")
+        self.df = self.df.replace([float("inf"), float("-inf")], pd.NA).dropna().reset_index(drop=True)
+        self.log.info(f"Dataframe Shape after NaN/INF removal {self.df.shape}")
+
+        # Standardize the features
+        X = self.scalar.fit_transform(self.df[self.features])
+        y = self.df[self.target_column]
+
+        # Fit the KNN model
+        self.knn.fit(X, y)
+
+        # Compute the feature space to target resolution to the nearest neighbors
+        output_count = 0
+        for my_index, row in enumerate(X):
+            # Find the nearest neighbors
+            distances, indices = self.knn.kneighbors([row])
+            distances = distances[0]  # Returns a list within a list so grab the inner list
+            indices = indices[0]
+            target_values = y[indices]
+
+            # Grab the info for this observation
+            my_id = self.df.iloc[my_index][self.id_column]
+            my_output_data = self.df.iloc[my_index][output_columns]
+            my_target = y[my_index]
+
+            # Loop through the neighbors
+            for n_index, n_distance, n_target in zip(indices, distances, target_values):
+                # Skip myself
+                if n_index == my_index:
+                    continue
+
+                # Compute the difference in feature space and target space
+                feature_diff = n_distance
+                target_diff = abs(my_target - n_target)
+
+                # Compute target differences `within_distance` feature space
+                if feature_diff <= within_distance and target_diff >= min_target_difference:
+                    # Gather info about the neighbor
+                    neighbor_id = self.df.iloc[n_index][self.id_column]
+                    neighbor_output_data = self.df.iloc[n_index][output_columns]
+
+                    # Add to the output DataFrame
+                    row_data = my_output_data.to_dict()
+                    row_data["feature_diff"] = feature_diff
+                    row_data["target_diff"] = target_diff
+                    row_data["n_id"] = neighbor_id
+                    self.dataframe_builder.add_row(row_data)
+
+                    # Print out the resolution issue (if verbose)
+                    if verbose:
+                        print(f"{output_count} Feature Diff: {feature_diff} Target Diff: {target_diff}")
+                        print(f"\t{my_id}: {my_target:.3f} {list(my_output_data)}")
+                        print(f"\t{neighbor_id}: {n_target:.3f} {list(neighbor_output_data)}")
+                    # Increment the output count
+                    output_count += 1
+
+        # Return the output DataFrame
+        return self.dataframe_builder.build()
+
+    def recursive_compute(
+        self, within_distance: float, min_target_difference: float, output_columns: list = [], verbose=True
+    ) -> pd.DataFrame:
+        """Compute Feature Resolution Issues, remove the issues, and recurse until no issues are found"""
+
+        # Compute the resolution issues
+        resolution_df = self.compute(within_distance, min_target_difference, output_columns, verbose)
+        self.recursive_df_list.append(resolution_df)
+
+        # If there are no resolution issues, return the combined DataFrame
+        if len(resolution_df) == 0:
+            return pd.concat(self.recursive_df_list)
+
+        # Gather all IDs to be removed
+        ids_to_remove = set(list(resolution_df[self.id_column]) + list(resolution_df["n_id"]))
+
+        # Remove the rows of the observations that had issues
+        print("Removing IDs: ", ids_to_remove)
+        self.df = self.df[~self.df[self.id_column].isin(ids_to_remove)]
+
+        # Recurse
+        print("Recursing...")
+        self.df = self.df.reset_index(drop=True)
+        self.dataframe_builder = DataFrameBuilder()
+        return self.recursive_compute(within_distance, min_target_difference, output_columns, verbose)
+
+
+# Test the FeatureResolution Class
+def simple_unit_test():
+    """Test for the Feature Spider Class"""
+    # Set some pandas options
+    pd.set_option("display.max_columns", None)
+    pd.set_option("display.width", 1000)
+
+    # Make some fake data
+    data = {
+        "ID": [
+            "id_0",
+            "id_1",
+            "id_2",
+            "id_3",
+            "id_4",
+            "id_5",
+            "id_6",
+            "id_7",
+            "id_8",
+            "id_9",
+        ],
+        "feat1": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat2": [1.0, 1.0, 1.1, 3.0, 4.0, 1.0, 1.0, 1.1, 3.0, 4.0],
+        "feat3": [0.1, 0.2, 0.2, 1.6, 2.5, 0.1, 0.3, 0.2, 1.6, 2.5],
+        "price": [10, 11, 12, 40, 20, 35, 61, 60, 40, 20],
+    }
+    data_df = pd.DataFrame(data)
+
+    # Create the class and run the report
+    resolution = FeatureResolution(data_df, features=["feat1", "feat2", "feat3"], target_column="price", id_column="ID")
+    resolution.compute(within_distance=0.1, min_target_difference=10)
+
+
+def unit_test():
+    """Unit Test for the FeatureResolution Class"""
+    from workbench.api.feature_set import FeatureSet
+    from workbench.api.model import Model
+
+    # Grab a test dataframe
+    fs = FeatureSet("aqsol_mol_descriptors")
+    test_df = fs.pull_dataframe()
+
+    # Get the target and feature columns
+    m = Model("aqsol-mol-regression")
+    target_column = m.target()
+    feature_columns = m.features()
+
+    # Create the class and run the report
+    resolution = FeatureResolution(
+        test_df, features=feature_columns, target_column=target_column, id_column=fs.id_column
+    )
+    df = resolution.compute(within_distance=0.01, min_target_difference=1.0)
+    print(df)
+
+
+def recursive_test():
+    from workbench.api.feature_set import FeatureSet
+    from workbench.api.model import Model
+
+    # Grab a test dataframe
+    fs = FeatureSet("aqsol_mol_descriptors")
+    test_df = fs.pull_dataframe()
+
+    # Get the target and feature columns
+    m = Model("aqsol-mol-regression")
+    target_column = m.target()
+    feature_columns = m.features()
+
+    # Create the class and run the report
+    resolution = FeatureResolution(
+        test_df, features=feature_columns, target_column=target_column, id_column=fs.id_column
+    )
+    df = resolution.recursive_compute(within_distance=0.01, min_target_difference=1.0)
+    print(df)
+
+
+if __name__ == "__main__":
+    simple_unit_test()
+    unit_test()
+    # recursive_test()