congrads 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

congrads/descriptor.py

@@ -1,33 +1,14 @@
 class Descriptor:
-    """
-    A class to manage the mapping of neurons to layers and their properties
-    (e.g., output, constant, or variable) in a neural network.
-
-    This class enables the organization and description of network elements,
-    such as associating neurons with specific layers and categorizing layers
-    as outputs, constants, or variables.
-
-    This allows users to easily place constraints on parts of the network by
-    referencing the name that is configured in this class.
-    """
+    # TODO regenerate documentation
 
     def __init__(
         self,
     ):
-        """
-        Initialize the Descriptor class with empty mappings for neurons and layers.
-
-        This includes:
-            - `neuron_to_layer`: A dictionary mapping neuron names to their corresponding layer names.
-            - `neuron_to_index`: A dictionary mapping neuron names to their corresponding index within a layer.
-            - `output_layers`: A set that holds the names of layers marked as output layers.
-            - `constant_layers`: A set that holds the names of layers marked as constant layers.
-            - `variable_layers`: A set that holds the names of layers marked as variable layers.
-        """
 
         # Define dictionaries that will translate neuron names to layer and index
         self.neuron_to_layer: dict[str, str] = {}
         self.neuron_to_index: dict[str, int] = {}
+        self.neuron_to_minmax: dict[str, tuple[float, float]] = {}
 
         # Define sets that will hold the layers based on which type
         self.output_layers: set[str] = set()
@@ -37,20 +18,13 @@ class Descriptor:
     def add(
         self,
         layer_name: str,
-        neuron_names: list[str],
+        index: int,
+        neuron_name: str,
+        min: float = 0,
+        max: float = 1,
         output: bool = False,
         constant: bool = False,
     ):
-        """
-        Add a layer to the descriptor, associating it with neurons and marking it
-        as an output or constant layer.
-
-        Args:
-            layer_name (str): The name of the layer to be added.
-            neuron_names (list[str]): A list of neuron names that belong to the layer.
-            output (bool, optional): If True, mark this layer as an output layer. Defaults to False.
-            constant (bool, optional): If True, mark this layer as a constant layer. Defaults to False.
-        """
 
         if output:
             self.output_layers.add(layer_name)
@@ -60,6 +34,17 @@ class Descriptor:
         else:
             self.variable_layers.add(layer_name)
 
-        for index, neuron_name in enumerate(neuron_names):
-            self.neuron_to_layer[neuron_name] = layer_name
-            self.neuron_to_index[neuron_name] = index
+        self.neuron_to_layer[neuron_name] = layer_name
+        self.neuron_to_index[neuron_name] = index
+
+        if min != None and max == None:
+            raise ValueError(
+                f"The min parameter was set without setting the max parameter. Either set both or set none."
+            )
+
+        if max != None and min == None:
+            raise ValueError(
+                f"The max parameter was set without setting the min parameter. Either set both or set none."
+            )
+
+        self.neuron_to_minmax[neuron_name] = (min, max)

congrads/metrics.py

@@ -1,64 +1,49 @@
-from torch import Tensor, tensor, sum, numel
-from torchmetrics import Metric
+from typing import Callable
+from torch import Tensor, mean, cat
+from torch.utils.tensorboard import SummaryWriter
 
-# NOTE
 
+class Metric:
+    def __init__(
+        self, name: str, accumulator: Callable[..., Tensor] = mean, device=None
+    ) -> None:
+        self.name = name
+        self.accumulator = accumulator
+        self.device = device
 
-class ConstraintSatisfactionRatio(Metric):
-    """
-    A custom metric to calculate the ratio of satisfied constraints in a neural network model.
-    It computes the proportion of constraints that have been satisfied,
-    where satisfaction is determined based on the provided constraint results.
+        self.values = []
+        self.sample_count = 0
 
-    This metric tracks the number of unsatisfied constraints and the total number of constraints
-    during the training process, and computes the ratio of satisfied constraints once all updates
-    have been made.
+    def accumulate(self, value: Tensor) -> None:
+        self.values.append(value)
+        self.sample_count += value.size(0)
 
-    Attributes:
-        unsatisfied (Tensor): Tracks the number of unsatisfied constraints.
-        total (Tensor): Tracks the total number of constraints processed.
+    def aggregate(self) -> Tensor:
+        combined = cat(self.values)
+        return self.accumulator(combined)
 
-    Note:
-        For more information about custom metrics, we refer to the Pytorch Lightning documentation
-        at https://lightning.ai/docs/torchmetrics/stable/pages/implement.html
-    """
+    def reset(self) -> None:
+        self.values = []
+        self.sample_count = 0
 
-    def __init__(self, **kwargs):
-        """
-        Initializes the ConstraintSatisfactionRatio metric by setting up the
-        state variables to track the number of unsatisfied and total constraints.
 
-        Args:
-            **kwargs: Additional arguments to pass to the base Metric class constructor.
-        """
+class MetricManager:
+    def __init__(self, writer: SummaryWriter, device: str) -> None:
+        self.writer = writer
+        self.device = device
+        self.metrics: dict[str, Metric] = {}
 
-        # Init parent class
-        super().__init__(**kwargs)
+    def register(self, name: str, accumulator: Callable[..., Tensor] = mean) -> None:
+        self.metrics[name] = Metric(name, accumulator, self.device)
 
-        # Init scalar tensors that will hold metric values
-        self.add_state("unsatisfied", default=tensor(0), dist_reduce_fx="sum")
-        self.add_state("total", default=tensor(0), dist_reduce_fx="sum")
+    def accumulate(self, name: str, value: Tensor) -> None:
+        self.metrics[name].accumulate(value)
 
-    def update(self, constraint_result: Tensor) -> None:
-        """
-        Updates the state of the metric with the latest constraint results.
+    def record(self, epoch: int) -> None:
+        for name, metric in self.metrics.items():
+            result = metric.aggregate()
+            self.writer.add_scalar(name, result.item(), epoch)
 
-        Args:
-            constraint_result (Tensor): A tensor representing the result of
-                                         the constraint checks, where each
-                                         element indicates whether a constraint
-                                         is satisfied (e.g., 0 for satisfied,
-                                         1 for unsatisfied).
-        """
-        self.unsatisfied += sum(constraint_result)
-        self.total += numel(constraint_result)
-
-    def compute(self) -> Tensor:
-        """
-        Computes the constraint satisfaction ratio, defined as:
-        1 - (number of unsatisfied constraints / total constraints).
-
-        Returns:
-            Tensor: The satisfaction ratio as a scalar tensor.
-        """
-        return 1 - (self.unsatisfied.float() / self.total)
+    def reset(self) -> None:
+        for metric in self.metrics.values():
+            metric.reset()

congrads/networks.py

@@ -24,9 +24,9 @@ class MLPNetwork(Module):
 
     def __init__(
         self,
-        n_inputs=25,
-        n_outputs=2,
-        n_hidden_layers=2,
+        n_inputs,
+        n_outputs,
+        n_hidden_layers=3,
         hidden_dim=35,
     ):
         """
@@ -47,7 +47,7 @@ class MLPNetwork(Module):
         self.hidden_dim = hidden_dim
 
         # Set up the components of our model
-        self.input = self.linear(self.n_inputs, self.hidden_dim)
+        self.input = Linear(self.n_inputs, self.hidden_dim)
         self.hidden = Sequential(
             *(
                 self.linear(self.hidden_dim, self.hidden_dim)
@@ -67,10 +67,9 @@ class MLPNetwork(Module):
             dict: A dictionary containing the 'input' (original input) and
                   'output' (predicted output) of the network.
         """
-        input = X
         output = self.out(self.hidden(self.input(X)))
 
-        return {"input": input, "output": output}
+        return {"input": X, "output": output}
 
     @staticmethod
     def linear(in_features, out_features):

congrads/utils.py

@@ -0,0 +1,310 @@
+import pandas as pd
+import numpy as np
+from torch.utils.data import Dataset, random_split, DataLoader
+
+
+def splitDataLoaders(
+    data: Dataset,
+    loader_args: dict = None,
+    train_loader_args: dict = None,
+    valid_loader_args: dict = None,
+    test_loader_args: dict = None,
+    train_size: float = 0.8,
+    valid_size: float = 0.1,
+    test_size: float = 0.1,
+) -> tuple[DataLoader, DataLoader, DataLoader]:
+
+    # Validate split sizes
+    if not (0 < train_size < 1 and 0 < valid_size < 1 and 0 < test_size < 1):
+        raise ValueError(
+            "train_size, valid_size, and test_size must be between 0 and 1."
+        )
+    if not abs(train_size + valid_size + test_size - 1.0) < 1e-6:
+        raise ValueError("train_size, valid_size, and test_size must sum to 1.")
+
+    # Perform the splits
+    train_val_data, test_data = random_split(data, [1 - test_size, test_size])
+    train_data, valid_data = random_split(
+        train_val_data,
+        [
+            train_size / (1 - test_size),
+            valid_size / (1 - test_size),
+        ],
+    )
+
+    # Set default arguments for each loader
+    train_loader_args = train_loader_args or loader_args or {}
+    valid_loader_args = valid_loader_args or loader_args or {}
+    test_loader_args = test_loader_args or loader_args or {}
+
+    # Create the DataLoaders
+    train_generator = DataLoader(train_data, **train_loader_args)
+    valid_generator = DataLoader(valid_data, **valid_loader_args)
+    test_generator = DataLoader(test_data, **test_loader_args)
+
+    return train_generator, valid_generator, test_generator
+
+
+def preprocess_BiasCorrection(df: pd.DataFrame) -> pd.DataFrame:
+
+    def date_to_datetime(df: pd.DataFrame) -> pd.DataFrame:
+        """Transform the string that denotes the date to the datetime format in pandas."""
+        # make copy of dataframe
+        df_temp = df.copy()
+        # add new column at the front where the date string is transformed to the datetime format
+        df_temp.insert(0, "DateTransformed", pd.to_datetime(df_temp["Date"]))
+        return df_temp
+
+    def add_year(df: pd.DataFrame) -> pd.DataFrame:
+        """Extract the year from the datetime cell and add it as a new column to the dataframe at the front."""
+        # make copy of dataframe
+        df_temp = df.copy()
+        # extract year and add new column at the front containing these numbers
+        df_temp.insert(0, "Year", df_temp["DateTransformed"].dt.year)
+        return df_temp
+
+    def add_month(df: pd.DataFrame) -> pd.DataFrame:
+        """Extract the month from the datetime cell and add it as a new column to the dataframe at the front."""
+        # make copy of dataframe
+        df_temp = df.copy()
+        # extract month and add new column at index 1 containing these numbers
+        df_temp.insert(1, "Month", df_temp["DateTransformed"].dt.month)
+        return df_temp
+
+    def add_day(df: pd.DataFrame) -> pd.DataFrame:
+        """Extract the day from the datetime cell and add it as a new column to the dataframe at the front."""
+        # make copy of dataframe
+        df_temp = df.copy()
+        # extract day and add new column at index 2 containing these numbers
+        df_temp.insert(2, "Day", df_temp["DateTransformed"].dt.day)
+        return df_temp
+
+    def add_input_output_temperature(df: pd.DataFrame) -> pd.DataFrame:
+        """Add a multiindex denoting if the column is an input or output variable."""
+        # copy the dataframe
+        temp_df = df.copy()
+        # extract all the column names
+        column_names = temp_df.columns.tolist()
+        # only the last 2 columns are output variables, all others are input variables. So make list of corresponding lengths of 'Input' and 'Output'
+        input_list = ["Input"] * (len(column_names) - 2)
+        output_list = ["Output"] * 2
+        # concat both lists
+        input_output_list = input_list + output_list
+        # define multi index for attaching this 'Input' and 'Output' list with the column names already existing
+        multiindex_bias = pd.MultiIndex.from_arrays([input_output_list, column_names])
+        # transpose such that index can be adjusted to multi index
+        new_df = pd.DataFrame(df.transpose().to_numpy(), index=multiindex_bias)
+        # transpose back such that columns are the same as before except with different labels
+        return new_df.transpose()
+
+    def normalize_columns_bias(df: pd.DataFrame) -> pd.DataFrame:
+        """Normalize the columns for the bias correction dataset. This is different from normalizing all the columns separately because the
+        upper and lower bounds for the output variables are assumed to be the same."""
+        # copy the dataframe
+        temp_df = df.copy()
+        # normalize each column
+        for feature_name in df.columns:
+            # the output columns are normalized using the same upper and lower bound for more efficient check of the inequality
+            if feature_name == "Next_Tmax" or feature_name == "Next_Tmin":
+                max_value = 38.9
+                min_value = 11.3
+            # the input columns are normalized using their respective upper and lower bounds
+            else:
+                max_value = df[feature_name].max()
+                min_value = df[feature_name].min()
+            temp_df[feature_name] = (df[feature_name] - min_value) / (
+                max_value - min_value
+            )
+        return temp_df
+
+    def sample_2500_examples(df: pd.DataFrame) -> pd.DataFrame:
+        """Sample 2500 examples from the dataframe without replacement."""
+        temp_df = df.copy()
+        sample_df = temp_df.sample(n=2500, replace=False, random_state=3, axis=0)
+        return sample_df
+
+    return (
+        # drop missing values
+        df.dropna(how="any")
+        # transform string date to datetime format
+        .pipe(date_to_datetime)
+        # add year as a single column
+        .pipe(add_year)
+        # add month as a single column
+        .pipe(add_month)
+        # add day as a single column
+        .pipe(add_day)
+        # remove original date string and the datetime format
+        .drop(["Date", "DateTransformed"], axis=1, inplace=False)
+        # convert all numbers to float32
+        .astype("float32")
+        # normalize columns
+        .pipe(normalize_columns_bias)
+        # add multi index indicating which columns are corresponding to input and output variables
+        .pipe(add_input_output_temperature)
+        # sample 2500 examples out of the dataset
+        .pipe(sample_2500_examples)
+    )
+
+
+def preprocess_FiniteIncome(df: pd.DataFrame) -> pd.DataFrame:
+
+    def normalize_columns_income(df: pd.DataFrame) -> pd.DataFrame:
+        """Normalize the columns for the Family Income dataframe. This can also be applied to other dataframes because this function normalizes
+        all columns individually."""
+        # copy the dataframe
+        temp_df = df.copy()
+        # normalize each column
+        for feature_name in df.columns:
+            max_value = df[feature_name].max()
+            min_value = df[feature_name].min()
+            temp_df[feature_name] = (df[feature_name] - min_value) / (
+                max_value - min_value
+            )
+        return temp_df
+
+    def check_constraints_income(df: pd.DataFrame) -> pd.DataFrame:
+        """Check if all the constraints are satisfied for the dataframe and remove the examples that do not satisfy the constraint. This
+        function only works for the Family Income dataset and the constraints are that the household income is larger than all the expenses
+        and the food expense is larger than the sum of the other (more detailed) food expenses.
+        """
+        temp_df = df.copy()
+        # check that household income is larger than expenses in the output
+        input_array = temp_df["Input"].to_numpy()
+        income_array = np.add(
+            np.multiply(
+                input_array[:, [0, 1]],
+                np.subtract(np.asarray([11815988, 9234485]), np.asarray([11285, 0])),
+            ),
+            np.asarray([11285, 0]),
+        )
+        expense_array = temp_df["Output"].to_numpy()
+        expense_array = np.add(
+            np.multiply(
+                expense_array,
+                np.subtract(
+                    np.asarray(
+                        [
+                            791848,
+                            437467,
+                            140992,
+                            74800,
+                            2188560,
+                            1049275,
+                            149940,
+                            731000,
+                        ]
+                    ),
+                    np.asarray([3704, 0, 0, 0, 1950, 0, 0, 0]),
+                ),
+            ),
+            np.asarray([3704, 0, 0, 0, 1950, 0, 0, 0]),
+        )
+        expense_array_without_dup = expense_array[:, [0, 4, 5, 6, 7]]
+        sum_expenses = np.sum(expense_array_without_dup, axis=1)
+        total_income = np.sum(income_array, axis=1)
+        sanity_check_array = np.greater_equal(total_income, sum_expenses)
+        temp_df["Unimportant"] = sanity_check_array.tolist()
+        reduction = temp_df[temp_df.Unimportant]
+        drop_reduction = reduction.drop("Unimportant", axis=1)
+
+        # check that the food expense is larger than all the sub expenses
+        expense_reduced_array = drop_reduction["Output"].to_numpy()
+        expense_reduced_array = np.add(
+            np.multiply(
+                expense_reduced_array,
+                np.subtract(
+                    np.asarray(
+                        [
+                            791848,
+                            437467,
+                            140992,
+                            74800,
+                            2188560,
+                            1049275,
+                            149940,
+                            731000,
+                        ]
+                    ),
+                    np.asarray([3704, 0, 0, 0, 1950, 0, 0, 0]),
+                ),
+            ),
+            np.asarray([3704, 0, 0, 0, 1950, 0, 0, 0]),
+        )
+        food_mul_expense_array = expense_reduced_array[:, [1, 2, 3]]
+        food_mul_expense_array_sum = np.sum(food_mul_expense_array, axis=1)
+        food_expense_array = expense_reduced_array[:, 0]
+        sanity_check_array = np.greater_equal(
+            food_expense_array, food_mul_expense_array_sum
+        )
+        drop_reduction["Unimportant"] = sanity_check_array.tolist()
+        new_reduction = drop_reduction[drop_reduction.Unimportant]
+        satisfied_constraints_df = new_reduction.drop("Unimportant", axis=1)
+
+        return satisfied_constraints_df
+
+    def add_input_output_family_income(df: pd.DataFrame) -> pd.DataFrame:
+        """Add a multiindex denoting if the column is an input or output variable."""
+        # copy the dataframe
+        temp_df = df.copy()
+        # extract all the column names
+        column_names = temp_df.columns.tolist()
+        # the 2nd-9th columns correspond to output variables and all others to input variables. So make list of corresponding lengths of 'Input' and 'Output'
+        input_list_start = ["Input"]
+        input_list_end = ["Input"] * (len(column_names) - 9)
+        output_list = ["Output"] * 8
+        # concat both lists
+        input_output_list = input_list_start + output_list + input_list_end
+        # define multi index for attaching this 'Input' and 'Output' list with the column names already existing
+        multiindex_bias = pd.MultiIndex.from_arrays([input_output_list, column_names])
+        # transpose such that index can be adjusted to multi index
+        new_df = pd.DataFrame(df.transpose().to_numpy(), index=multiindex_bias)
+        # transpose back such that columns are the same as before except with different labels
+        return new_df.transpose()
+
+    def sample_2500_examples(df: pd.DataFrame) -> pd.DataFrame:
+        """Sample 2500 examples from the dataframe without replacement."""
+        temp_df = df.copy()
+        sample_df = temp_df.sample(n=2500, replace=False, random_state=3, axis=0)
+        return sample_df
+
+    return (
+        # drop missing values
+        df.dropna(how="any")
+        # convert object to fitting dtype
+        .convert_dtypes()
+        # remove all strings (no other dtypes are present except for integers and floats)
+        .select_dtypes(exclude=["string"])
+        # transform all numbers to same dtype
+        .astype("float32")
+        # drop column with label Agricultural Household indicator because this is not really a numerical input but rather a categorical/classification
+        .drop(["Agricultural Household indicator"], axis=1, inplace=False)
+        # this column is dropped because it depends on Agricultural Household indicator
+        .drop(["Crop Farming and Gardening expenses"], axis=1, inplace=False)
+        # use 8 output variables and 24 input variables
+        .drop(
+            [
+                "Total Rice Expenditure",
+                "Total Fish and  marine products Expenditure",
+                "Fruit Expenditure",
+                "Restaurant and hotels Expenditure",
+                "Alcoholic Beverages Expenditure",
+                "Tobacco Expenditure",
+                "Clothing, Footwear and Other Wear Expenditure",
+                "Imputed House Rental Value",
+                "Transportation Expenditure",
+                "Miscellaneous Goods and Services Expenditure",
+                "Special Occasions Expenditure",
+            ],
+            axis=1,
+            inplace=False,
+        )
+        # add input and output labels to each column
+        .pipe(add_input_output_family_income)
+        # normalize all the columns
+        .pipe(normalize_columns_income)
+        # remove all datapoints that do not satisfy the constraints
+        .pipe(check_constraints_income)
+        # sample 2500 examples
+        .pipe(sample_2500_examples)
+    )

congrads-0.2.0.dist-info/LICENSE

@@ -0,0 +1,26 @@
+Copyright 2024 DTAI - KU Leuven
+
+Redistribution and use in source and binary forms, with or without modification, 
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, 
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, 
+this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its 
+contributors may be used to endorse or promote products derived from 
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.