pyaerial 0.1.0__py3-none-any.whl

aerial/__init__.py

@@ -0,0 +1,29 @@
+import logging
+from . import discretization, rule_quality, model
+from aerial.rule_extraction import generate_rules, generate_frequent_itemsets
+
+__all__ = [discretization, rule_quality, model, generate_rules, generate_frequent_itemsets]
+
+# Create a package-wide logger
+logger = logging.getLogger("aerial")
+logger.propagate = True
+logger.addHandler(logging.NullHandler())
+
+
+def setup_logging(level=logging.INFO, propagate=True):
+    """Configure package logging"""
+    logger.propagate = propagate
+    logger.setLevel(level)
+
+    # Remove all existing handlers
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    # Add new console handler if level is not NOTSET
+    if level != logging.NOTSET:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)

aerial/data_preparation.py

@@ -0,0 +1,74 @@
+"""
+Copyright (c) [2025] [Erkan Karabulut - DiTEC Project]
+
+This script implements data preparation functions for tabular for association rule mining with Aerial
+"""
+
+import concurrent
+import numpy as np
+import pandas as pd
+
+from concurrent.futures import ThreadPoolExecutor
+
+from aerial.table import get_unique_values_per_column
+
+
+def _one_hot_encoding_with_feature_tracking(transactions: pd.DataFrame, parallel_workers=1):
+    """
+    Create input vectors for training the Autoencoder in a one-hot encoded form. And returns indices of each feature
+    values in a structured way for future tracking when extracting rules from a trained Autoencoder
+    :param transactions: pandas DataFrame of transactions
+    :return: a python dictionary with 3 objects
+        vector_list: transactions as a list of one-hot encoded vectors,
+        vector_tracker_list: a list ,
+        "feature_value_indices": feature_value_indices,
+    """
+    # Aerial uses "__" to separate column names and their values when one-hot encoding, {COL_NAME}__{value}
+    # therefore, replace all "__" in column names with "--" to avoid later confusion in naming
+    transactions.columns = [col.replace('__', '--') for col in transactions.columns]
+    columns = transactions.columns.tolist()
+
+    # Get input vectors in the form of one-hot encoded vectors
+    unique_values, value_count = get_unique_values_per_column(transactions)
+    feature_value_indices = []
+    vector_tracker = []
+    start = 0
+
+    # Track what each value in the input vector corresponds to
+    # Track where do values for each feature start and end in the input feature
+    for feature, values in unique_values.items():
+        end = start + len(values)
+        feature_value_indices.append({'feature': feature, 'start': start, 'end': end})
+        vector_tracker.extend([f"{feature}__{value}" for value in values])
+        start = end
+
+    # Map tracker entries to indices for fast lookup
+    tracker_index_map = {key: idx for idx, key in enumerate(vector_tracker)}
+
+    # Preallocate vector list
+    vector_list = np.zeros((len(transactions), value_count), dtype=int)
+
+    # Function to process each transaction
+    def process_transaction(transaction_idx, transaction):
+        transaction_vector = np.zeros(value_count, dtype=int)
+        for col_idx, value in enumerate(transaction):
+            if not pd.isna(value):
+                key = f"{columns[col_idx]}__{value}"
+                transaction_vector[tracker_index_map[key]] = 1
+        return transaction_idx, transaction_vector
+
+    # Parallelize transaction processing
+    # NOTE: Preparing the input data for each of the algorithms is not included in the execution time calculation
+    # Therefore, we preprocess data in parallel where possible for each of the algorithm
+    with concurrent.futures.ThreadPoolExecutor(max_workers=parallel_workers) as executor:
+        futures = [
+            executor.submit(process_transaction, transaction_idx, transaction)
+            for transaction_idx, transaction in enumerate(transactions.itertuples(index=False))
+        ]
+
+        for future in concurrent.futures.as_completed(futures):
+            transaction_idx, transaction_vector = future.result()
+            vector_list[transaction_idx] = transaction_vector
+
+    vector_list = pd.DataFrame(vector_list, columns=vector_tracker)
+    return vector_list, feature_value_indices

aerial/discretization.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) [2025] [Erkan Karabulut - DiTEC Project]
+
+This script include different discretization methods for tabular data
+"""
+import logging
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger("aerial")
+
+
+def equal_frequency_discretization(df: pd.DataFrame, n_bins=10):
+    """
+    Detect numerical columns automatically and discretize them into n_bins intervals based on equal frequency.
+    Intervals are represented as strings.
+
+    :param df: tabular data in pandas DataFrame form
+    :param n_bins: number of intervals (bins)
+    :return: df with discrete columns
+    """
+    df_discretized = df.copy()
+    num_cols = df.select_dtypes(include=[np.number]).columns
+
+    for col in num_cols:
+        try:
+            # Use labels=True to get string intervals
+            df_discretized[col] = pd.qcut(df[col], q=n_bins, duplicates='drop')
+            df_discretized[col] = df_discretized[col].astype(str)
+        except ValueError:
+            logger.debug(f"Column '{col}' could not be discretized due to insufficient unique values.")
+
+    return df_discretized
+
+
+def equal_width_discretization(df: pd.DataFrame, n_bins=10):
+    """
+    Detect numerical columns automatically and discretize them into n_bins intervals based on equal width.
+    Intervals are represented as strings.
+
+    :param df: tabular data in pandas DataFrame form
+    :param n_bins: number of intervals (bins)
+    :return: df with discrete columns
+    """
+    df_discretized = df.copy()
+    num_cols = df.select_dtypes(include=[np.number]).columns
+
+    for col in num_cols:
+        try:
+            df_discretized[col] = pd.cut(df[col], bins=n_bins)
+            df_discretized[col] = df_discretized[col].astype(str)
+        except ValueError:
+            logger.debug(f"Column '{col}' could not be discretized due to insufficient unique values.")
+
+    return df_discretized

aerial/model.py

@@ -0,0 +1,179 @@
+"""
+Copyright (c) [2025] [Erkan Karabulut - DiTEC Project]
+
+Construct an Autoencoder for association rule mining as described in the paper (Neurosymbolic association rule mining
+from tabular data - https://arxiv.org/abs/2504.19354)
+"""
+
+import os
+import logging
+import torch
+import pandas as pd
+from torch import nn
+import math
+import torch.nn.functional as F
+
+from torch.utils.data import TensorDataset, DataLoader
+
+from aerial.data_preparation import _one_hot_encoding_with_feature_tracking
+
+logger = logging.getLogger("aerial")
+
+
+class AutoEncoder(nn.Module):
+    """
+    This autoencoder is used to create a neural representation of tabular data for association rule mining
+    """
+
+    def __init__(self, input_dimension, feature_count, layer_dims: list = None):
+        """
+        The init function can either construct an under-complete Autoencoder based on the input dimension and feature
+        count, automatically deciding the number of layers and layer dimensions.
+        Or, if specified by the user, it can also use the layer counts and dimensions from the user.
+        Note that fine-tuning layer count and dimensions based on your table dimension and size
+        will result in better performance in general
+
+        :param input_dimension: number of features after one-hot encoding (input dimension)
+        :param feature_count: target feature count (initial column count of tabular data)
+        :param layer_dims: (optional) list of int, specific dimensions for hidden layers
+                           (excluding input/output dimensions)
+        """
+        super().__init__()
+
+        self.input_dimension = input_dimension
+        self.feature_count = feature_count
+        self.input_vectors = None
+        self.feature_value_indices = None
+        self.feature_values = None
+
+        # Determine the layer dimensions
+        if layer_dims is None:
+            # Compute default number of layers based on log base 16
+            layer_count = max(1, math.ceil(math.log(input_dimension, 16)) - 1)
+
+            # Calculate dimensions with consistent reduction ratio
+            reduction_ratio = (feature_count / input_dimension) ** (1 / (layer_count))
+            dimensions = [input_dimension]
+            for i in range(1, layer_count):
+                next_dim = max(feature_count, int(dimensions[-1] * reduction_ratio))
+                dimensions.append(next_dim)
+            dimensions.append(feature_count)
+        else:
+            # Use provided layer dimensions, adding input and output dimensions
+            dimensions = [input_dimension] + layer_dims
+
+        self.dimensions = dimensions  # save for inspection
+
+        # Build Encoder
+        encoder_layers = []
+        for i in range(len(dimensions) - 1):
+            encoder_layers.append(nn.Linear(dimensions[i], dimensions[i + 1]))
+            if i != len(dimensions) - 2:  # No activation after last encoder layer
+                encoder_layers.append(nn.Tanh())
+
+        self.encoder = nn.Sequential(*encoder_layers)
+
+        # Build Decoder (mirror of encoder, excluding final layer's activation)
+        decoder_layers = []
+        reversed_dimensions = list(reversed(dimensions))
+        for i in range(len(reversed_dimensions) - 1):
+            decoder_layers.append(nn.Linear(reversed_dimensions[i], reversed_dimensions[i + 1]))
+            if i != len(reversed_dimensions) - 2:
+                decoder_layers.append(nn.Tanh())
+
+        self.decoder = nn.Sequential(*decoder_layers)
+
+        self.encoder.apply(self.init_weights)
+        self.decoder.apply(self.init_weights)
+
+    @staticmethod
+    def init_weights(m):
+        """
+        all weights are initialized with values sampled from uniform distributions with the Xavier initialization
+        and the biases are set to 0, as described in the paper by Delong et al. (2023)
+        """
+        if isinstance(m, nn.Linear):
+            torch.nn.init.xavier_uniform_(m.weight)
+            m.bias.data.zero_()
+
+    def save(self, name):
+        torch.save(self.encoder.state_dict(), name + "_encoder.pt")
+        torch.save(self.decoder.state_dict(), name + '_decoder.pt')
+
+    def load(self, name):
+        if os.path.isfile(name + '_encoder.pt') and os.path.isfile(name + '_decoder.pt'):
+            self.encoder.load_state_dict(torch.load(name + '_encoder.pt'))
+            self.decoder.load_state_dict(torch.load(name + '_decoder.pt'))
+            self.encoder.eval()
+            self.decoder.eval()
+            return True
+        else:
+            return False
+
+    def forward(self, x, feature_value_indices):
+        y = self.encoder(x)
+        y = self.decoder(y)
+
+        # Split the tensor into chunks based on the ranges
+        chunks = [y[:, start:end] for start, end in feature_value_indices]
+
+        # Apply softmax to each chunk
+        softmax_chunks = [F.softmax(chunk, dim=1) for chunk in chunks]
+
+        # Concatenate the chunks back together
+        y = torch.cat(softmax_chunks, dim=1)
+
+        return y
+
+
+def train(transactions: pd.DataFrame, autoencoder: AutoEncoder = None, noise_factor=0.5,
+          lr=5e-3, epochs=1, batch_size=2, loss_function=torch.nn.BCELoss(), num_workers=1, layer_dims: list = None):
+    """
+    train an autoencoder for association rule mining
+    """
+    input_vectors, feature_value_indices = _one_hot_encoding_with_feature_tracking(transactions, num_workers)
+    columns = input_vectors.columns.tolist()
+
+    if not autoencoder:
+        autoencoder = AutoEncoder(input_dimension=len(columns), feature_count=len(feature_value_indices),
+                                  layer_dims=layer_dims)
+
+    autoencoder.input_vectors = input_vectors
+
+    input_vectors = input_vectors.to_numpy()
+
+    autoencoder = torch.compile(autoencoder)
+    autoencoder.feature_value_indices = feature_value_indices
+    autoencoder.feature_values = columns
+
+    optimizer = torch.optim.Adam(autoencoder.parameters(), lr=lr, weight_decay=2e-8)
+
+    vectors_tensor = torch.tensor(input_vectors, dtype=torch.float32)
+    dataset = TensorDataset(vectors_tensor)
+    dataloader = DataLoader(dataset, batch_size=batch_size, shuffle=True, num_workers=num_workers)
+
+    softmax_ranges = [(cat['start'], cat['end']) for cat in feature_value_indices]
+
+    for epoch in range(epochs):
+        # print(f"Epoch {epoch + 1}/{epochs}")
+        for batch_index, (batch,) in enumerate(dataloader):
+            noisy_batch = (batch + torch.randn_like(batch) * noise_factor).clamp(0, 1)
+
+            # Forward pass
+            reconstructed_batch = autoencoder(noisy_batch, softmax_ranges)
+
+            # Compute loss for the entire batch
+            total_loss = sum(
+                loss_function(
+                    reconstructed_batch[:, start:end],
+                    batch[:, start:end]
+                )
+                for (start, end) in softmax_ranges
+            )
+
+            # Backpropagation and optimization step
+            optimizer.zero_grad()
+            total_loss.backward()
+            optimizer.step()
+
+    return autoencoder

aerial/rule_extraction.py

@@ -0,0 +1,243 @@
+"""
+Copyright (c) [2025] [Erkan Karabulut - DiTEC Project]
+
+Includes the Aerial algorithm's source code for association rule (and frequent itemsets) extraction from a
+trained Autoencoder (Neurosymbolic association rule mining from tabular data - https://arxiv.org/abs/2504.19354)
+"""
+
+import torch
+
+from itertools import combinations
+
+from aerial.model import AutoEncoder
+import numpy as np
+import logging
+
+logger = logging.getLogger("aerial")
+
+
+def generate_rules(autoencoder: AutoEncoder, ant_similarity=0.5, cons_similarity=0.8, max_antecedents=2,
+                   target_class=None):
+    """
+    extract rules from a trained Autoencoder using Aerial+ algorithm
+    @param target_class: if given a target class, generate rules with the target class on the right hand side only
+    :param max_antecedents: max number of antecedents that the rules will contain
+    :param cons_similarity: consequent simi
+    :param ant_similarity:
+    :param autoencoder:
+    """
+    if not autoencoder:
+        logger.error("A trained Autoencoder has to be provided before generating rules.")
+        return None
+
+    logger.debug("Extracting association rules from the given trained Autoencoder ...")
+
+    association_rules = []
+    input_vector_size = autoencoder.encoder[0].in_features
+
+    feature_value_indices = autoencoder.feature_value_indices
+    target_range = range(input_vector_size)
+
+    # If target_class is specified, narrow the target range and features
+    # this is to do "constraint-based rule mining"
+    if target_class:
+        for feature in feature_value_indices:
+            if feature["feature"] == target_class:
+                target_range = range(feature["start"], feature["end"])
+                break
+
+    low_support_antecedents = np.array([])
+
+    # Initialize input vectors
+    unmarked_features = _initialize_input_vectors(input_vector_size, feature_value_indices)
+
+    # Precompute target indices for softmax to speed things up
+    feature_value_indices = [(cat['start'], cat['end']) for cat in feature_value_indices]
+    softmax_ranges = feature_value_indices
+
+    for r in range(1, max_antecedents + 1):
+        if r == 2:
+            softmax_ranges = [
+                (start, end) for (start, end) in softmax_ranges
+                if not all(idx in low_support_antecedents for idx in range(start, end))
+            ]
+
+        feature_combinations = list(combinations(softmax_ranges, r))  # Generate combinations
+
+        # Vectorized model evaluation batch
+        batch_vectors = []
+        batch_candidate_antecedent_list = []
+
+        for category_list in feature_combinations:
+            test_vectors, candidate_antecedent_list = _mark_features(unmarked_features, list(category_list),
+                                                                     low_support_antecedents)
+            if len(test_vectors) > 0:
+                batch_vectors.extend(test_vectors)
+                batch_candidate_antecedent_list.extend(candidate_antecedent_list)
+
+        if batch_vectors:
+            batch_vectors = torch.tensor(np.array(batch_vectors), dtype=torch.float32)
+            # Perform a single model evaluation for the batch
+            implications_batch = autoencoder(batch_vectors, feature_value_indices).detach().numpy()
+            for test_vector, implication_probabilities, candidate_antecedents \
+                    in zip(batch_vectors, implications_batch, batch_candidate_antecedent_list):
+                if len(candidate_antecedents) == 0:
+                    continue
+
+                # Identify low-support antecedents
+                if any(implication_probabilities[ant] <= ant_similarity for ant in candidate_antecedents):
+                    if r == 1:
+                        low_support_antecedents = np.append(low_support_antecedents, candidate_antecedents)
+                    continue
+
+                # Identify high-support consequents
+                consequent_list = [
+                    prob_index for prob_index in target_range
+                    if prob_index not in candidate_antecedents and
+                       implication_probabilities[prob_index] >= cons_similarity
+                ]
+
+                if consequent_list:
+                    new_rule = _get_rule(candidate_antecedents, consequent_list, autoencoder.feature_values)
+                    for consequent in new_rule['consequents']:
+                        association_rules.append({'antecedents': new_rule['antecedents'], 'consequent': consequent})
+
+    logger.debug("%d association rules extracted.", len(association_rules))
+    return association_rules
+
+
+def generate_frequent_itemsets(autoencoder: AutoEncoder, similarity=0.5, max_length=2):
+    """
+    Generate frequent itemsets using the Aerial+ algorithm.
+    """
+    if not autoencoder:
+        logger.error("A trained Autoencoder has to be provided before extracting frequent items.")
+        return None
+
+    logger.debug("Extracting frequent items from the given trained Autoencoder ...")
+
+    frequent_itemsets = []
+    input_vector_size = len(autoencoder.feature_values)
+
+    low_support_antecedents = np.array([])
+
+    feature_value_indices = autoencoder.feature_value_indices
+
+    # Initialize input vectors once
+    unmarked_features = _initialize_input_vectors(input_vector_size, feature_value_indices)
+
+    # Precompute target indices for softmax
+    feature_value_indices = [(cat['start'], cat['end']) for cat in feature_value_indices]
+    softmax_ranges = feature_value_indices
+
+    # Iteratively process combinations of increasing size
+    for r in range(1, max_length + 1):
+        softmax_ranges = [
+            (start, end) for (start, end) in softmax_ranges
+            if not all(idx in low_support_antecedents for idx in range(start, end))
+        ]
+
+        feature_combinations = list(combinations(softmax_ranges, r))  # Generate combinations
+
+        # Vectorized model evaluation batch
+        batch_vectors = []
+        batch_candidate_antecedent_list = []
+
+        for category_list in feature_combinations:
+            test_vectors, candidate_antecedent_list = _mark_features(unmarked_features, list(category_list),
+                                                                     low_support_antecedents)
+            if len(test_vectors) > 0:
+                batch_vectors.extend(test_vectors)
+                batch_candidate_antecedent_list.extend(candidate_antecedent_list)
+        if batch_vectors:
+            batch_vectors = torch.tensor(np.array(batch_vectors), dtype=torch.float32)
+            # Perform a single model evaluation for the batch
+            implications_batch = autoencoder(batch_vectors, feature_value_indices).detach().numpy()
+            for test_vector, implication_probabilities, candidate_antecedents \
+                    in zip(batch_vectors, implications_batch, batch_candidate_antecedent_list):
+                if len(candidate_antecedents) == 0:
+                    continue
+
+                # Identify low-support antecedents
+                if any(implication_probabilities[ant] <= similarity for ant in candidate_antecedents):
+                    if r == 1:
+                        low_support_antecedents = np.append(low_support_antecedents, candidate_antecedents)
+                    continue
+
+                # Add to frequent itemsets
+                frequent_itemsets.append(
+                    [autoencoder.feature_values[idx] for idx in candidate_antecedents]
+                )
+
+    logger.debug("%d frequent itemsets extracted.", len(frequent_itemsets))
+    return frequent_itemsets
+
+
+def _mark_features(unmarked_test_vector, features, low_support_antecedents):
+    """
+    Create a list of test vectors by marking the given features in the unmarked test vector.
+    This optimized version processes features in bulk using NumPy operations.
+    """
+    input_vector_size = unmarked_test_vector.shape[0]
+
+    # Compute valid feature ranges excluding low_support_antecedents
+    feature_ranges = [
+        np.setdiff1d(np.arange(start, end), low_support_antecedents)
+        for (start, end) in features
+    ]
+
+    # Create all combinations of feature indices
+    combinations = np.array(np.meshgrid(*feature_ranges)).T.reshape(-1, len(features))
+
+    # Initialize test_vectors and candidate_antecedents
+    n_combinations = combinations.shape[0]
+    test_vectors = np.tile(unmarked_test_vector, (n_combinations, 1))
+    candidate_antecedents = [[] for _ in range(n_combinations)]
+
+    # Vectorized marking of test_vectors
+    for i, (start, end) in enumerate(features):
+        # Get the feature range
+        valid_indices = combinations[:, i]
+
+        # Ensure indices are within bounds
+        valid_indices = valid_indices[(valid_indices >= 0) & (valid_indices < input_vector_size)]
+
+        # Mark test_vectors based on valid indices for the current feature
+        for j, idx in enumerate(valid_indices):
+            test_vectors[j, start:end] = 0  # Set feature range to 0
+            test_vectors[j, idx] = 1  # Mark the valid index with 1
+            candidate_antecedents[j].append(idx)  # Append the index to the j-th test vector's antecedents
+
+    # Convert lists of candidate_antecedents to numpy arrays
+    candidate_antecedents = [np.array(lst) for lst in candidate_antecedents]
+    return test_vectors, candidate_antecedents
+
+
+def _initialize_input_vectors(input_vector_size, categories):
+    """
+    Initialize the input vectors with equal probabilities for each feature range.
+    """
+    vector_with_unmarked_features = np.zeros(input_vector_size)
+    for category in categories:
+        vector_with_unmarked_features[category['start']:category['end']] = 1 / (
+                category['end'] - category['start'])
+    return vector_with_unmarked_features
+
+
+def _get_rule(antecedents, consequents, feature_values):
+    """
+    Find the corresponding feature value for the given antecedents and consequent that are indices in test vectors
+    :param antecedents: a list of indices in the test vectors marking the antecedent locations
+    :param consequents: an index in the test vector marking the consequent location
+    :param feature_values: a list of string that keeps track of which neuron in the Autoencoder input corresponds
+        to which feature value in the tabular data
+    :return:
+    """
+    rule = {'antecedents': [], 'consequents': []}
+    for antecedent in antecedents:
+        rule['antecedents'].append(feature_values[antecedent])
+
+    for consequent in consequents:
+        rule['consequents'].append(feature_values[consequent])
+
+    return rule