10.13.0

Author: mathias-von-ottenbreit

API_REFERENCE_FOR_REGRESSION.md

@@ -373,6 +373,25 @@ Used for two-way or higher-order interactions. Specifies the number of evenly sp
 #### value
 A float representing the new intercept.
 
+## Method: plot_affiliation_shape(affiliation:str, plot:bool = True, save:bool = False, path:str = "")
+
+***Plots or saves the shape of a given unique term affiliation. For main effects, it produces a line plot. For two-way interactions, it produces a heatmap. Plotting for higher-order interactions is not supported. This method provides a convenient way to visualize model components.***
+
+### Parameters
+
+#### affiliation
+A string specifying which unique_term_affiliation to use.
+
+#### plot (default = True)
+If True, displays the plot.
+
+#### save (default = False)
+If True, saves the plot to a file.
+
+#### path (default = "")
+The file path to save the plot. If empty and save is True, a default path will be used, for example "shape_of_my_predictor.png".
+
+
 ## Method: remove_provided_custom_functions()
 
 ***Removes any custom functions provided for calculating the loss, negative gradient, or validation error. This is useful after model training with custom functions, ensuring that the APLRRegressor object no longer depends on these functions—so they do not need to be present in the Python environment when loading a saved model.***

README.md

@@ -13,6 +13,12 @@ To install APLR, use the following command:
 pip install aplr
 ```
 
+To include dependencies for plotting, use this command instead:
+
+```bash
+pip install aplr[plots]
+```
+
 ## Availability
 APLR is available for Windows, most Linux distributions, and macOS.
 

aplr/aplr.py

@@ -315,6 +315,108 @@ def get_cv_error(self) -> float:
     def set_intercept(self, value: float):
         self.APLRRegressor.set_intercept(value)
 
+    def plot_affiliation_shape(
+        self,
+        affiliation: str,
+        plot: bool = True,
+        save: bool = False,
+        path: str = "",
+    ):
+        """
+        Plots or saves the shape of a given unique term affiliation.
+
+        For main effects, it produces a line plot. For two-way interactions, it produces a heatmap.
+        Plotting for higher-order interactions is not supported.
+
+        :param affiliation: A string specifying which unique_term_affiliation to use.
+        :param plot: If True, displays the plot.
+        :param save: If True, saves the plot to a file.
+        :param path: The file path to save the plot. If empty and save is True, a default path will be used.
+        """
+        try:
+            import pandas as pd
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError(
+                "pandas and matplotlib are required for plotting. Please install them."
+            )
+
+        all_affiliations = self.get_unique_term_affiliations()
+        if affiliation not in all_affiliations:
+            raise ValueError(
+                f"Affiliation '{affiliation}' not found in model. "
+                f"Available affiliations are: {all_affiliations}"
+            )
+
+        affiliation_index = all_affiliations.index(affiliation)
+
+        predictors_in_each_affiliation = (
+            self.get_base_predictors_in_each_unique_term_affiliation()
+        )
+        predictor_indexes_used = predictors_in_each_affiliation[affiliation_index]
+
+        shape = self.get_unique_term_affiliation_shape(affiliation)
+        if shape.shape[0] == 0:
+            print(f"No shape data available for affiliation '{affiliation}'.")
+            return
+
+        predictor_names = affiliation.split(" & ")
+
+        shape_df = pd.DataFrame(shape, columns=predictor_names + ["contribution"])
+
+        is_main_effect: bool = len(predictor_indexes_used) == 1
+        is_two_way_interaction: bool = len(predictor_indexes_used) == 2
+
+        if is_main_effect:
+            fig = plt.figure()
+            plt.plot(shape_df.iloc[:, 0], shape_df.iloc[:, 1])
+            plt.xlabel(shape_df.columns[0])
+            plt.ylabel("Contribution to linear predictor")
+            plt.title(f"Main effect of {shape_df.columns[0]}")
+            plt.grid(True)
+        elif is_two_way_interaction:
+            fig = plt.figure(figsize=(8, 6))
+            pivot_table = shape_df.pivot_table(
+                index=shape_df.columns[0],
+                columns=shape_df.columns[1],
+                values=shape_df.columns[2],
+                aggfunc="mean",
+            )
+            plt.imshow(
+                pivot_table.values,
+                aspect="auto",
+                origin="lower",
+                extent=[
+                    pivot_table.columns.min(),
+                    pivot_table.columns.max(),
+                    pivot_table.index.min(),
+                    pivot_table.index.max(),
+                ],
+                cmap="Blues_r",
+            )
+            plt.colorbar(label="Contribution to the linear predictor")
+            plt.xlabel(shape_df.columns[1])
+            plt.ylabel(shape_df.columns[0])
+            plt.title(
+                f"Interaction between {shape_df.columns[0]} and {shape_df.columns[1]}"
+            )
+        else:
+            print(
+                f"Plotting for interaction level > 2 is not supported. Affiliation: {affiliation}"
+            )
+            return
+
+        if save:
+            save_path = (
+                path if path else f"shape_of_{affiliation.replace(' & ', '_')}.png"
+            )
+            plt.savefig(save_path)
+
+        if plot:
+            plt.show()
+
+        plt.close(fig)
+
     def remove_provided_custom_functions(self):
         self.APLRRegressor.remove_provided_custom_functions()
         self.calculate_custom_validation_error_function = None
@@ -504,7 +606,36 @@ def get_categories(self) -> List[str]:
         return self.APLRClassifier.get_categories()
 
     def get_logit_model(self, category: str) -> APLRRegressor:
-        return self.APLRClassifier.get_logit_model(category)
+        logit_model_cpp = self.APLRClassifier.get_logit_model(category)
+
+        logit_model_py = APLRRegressor(
+            m=self.m,
+            v=self.v,
+            random_state=self.random_state,
+            loss_function="binomial",
+            link_function="logit",
+            n_jobs=self.n_jobs,
+            cv_folds=self.cv_folds,
+            bins=self.bins,
+            max_interaction_level=self.max_interaction_level,
+            max_interactions=self.max_interactions,
+            min_observations_in_split=self.min_observations_in_split,
+            ineligible_boosting_steps_added=self.ineligible_boosting_steps_added,
+            max_eligible_terms=self.max_eligible_terms,
+            verbosity=self.verbosity,
+            boosting_steps_before_interactions_are_allowed=self.boosting_steps_before_interactions_are_allowed,
+            monotonic_constraints_ignore_interactions=self.monotonic_constraints_ignore_interactions,
+            early_stopping_rounds=self.early_stopping_rounds,
+            num_first_steps_with_linear_effects_only=self.num_first_steps_with_linear_effects_only,
+            penalty_for_non_linearity=self.penalty_for_non_linearity,
+            penalty_for_interactions=self.penalty_for_interactions,
+            max_terms=self.max_terms,
+            ridge_penalty=self.ridge_penalty,
+        )
+
+        logit_model_py.APLRRegressor = logit_model_cpp
+
+        return logit_model_py
 
     def get_validation_error_steps(self) -> FloatMatrix:
         return self.APLRClassifier.get_validation_error_steps()

documentation/APLR 10.12.1.pdf

@@ -3,5 +3,10 @@
 ## Feature importance
 Use the ***get_feature_importance*** method as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_classification.py).
 
+## Local feature contribution
+Use the ***calculate_local_feature_contribution*** method, for example on test data or new data. Usage of this method is demonstrated in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_classification.py).
+
 ## Main effects and interactions
-For best interpretability of interactions, do not use a higher ***max_interaction_level*** than 1. Use the ***calculate_local_feature_contribution*** method to interpret main effects and interactions as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_classification.py). You may also use the ***get_logit_model*** method to access the underlying APLR regression models as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_classification.py). You can interpret these models in the same way as described in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py).
+For each category, you can interpret the main effects and interactions of its underlying logit model. For best interpretability of interactions, do not use a higher ***max_interaction_level*** than 1.
+
+A convenient way to visualize the model components is to first use the ***get_logit_model*** method to access the underlying `APLRRegressor` model for a specific category. Then, you can use the ***plot_affiliation_shape*** method on that logit model to generate plots for its main effects (line plots) and two-way interactions (heatmaps). This is demonstrated in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_classification.py).

documentation/APLR 10.13.0.pdf

@@ -7,10 +7,10 @@ Use the ***get_feature_importance*** method as shown in this [example](https://g
 Use the ***calculate_feature_importance*** method or the ***calculate_local_feature_contribution*** method, for example on test data or new data. Usage of these methods is demonstrated in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py).
 
 ## Main effects
-Use the ***get_main_effect_shape*** method or the ***get_unique_term_affiliation_shape*** method to interpret main effects as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py). For each main effect, you may plot the output in a line plot.
+Use the ***plot_affiliation_shape*** method to easily plot main effects, as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py). Alternatively, use the ***get_main_effect_shape*** or ***get_unique_term_affiliation_shape*** methods to get the data for a custom plot.
 
 ## Interactions
-For best interpretability of interactions, do not use a higher ***max_interaction_level*** than 1. Use the ***get_unique_term_affiliation_shape*** method to interpret interactions as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py). For each two-way interaction of interest you may plot the output in a 3D surface plot.
+For best interpretability of interactions, do not use a higher ***max_interaction_level*** than 1. Use the ***plot_affiliation_shape*** method to easily plot two-way interactions as a heatmap, as shown in this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py). Alternatively, use the ***get_unique_term_affiliation_shape*** method to get the data for a custom plot, for example a 3D surface plot.
 
 ## Interpretation of model terms and their regression coefficients
 The above interpretations of main effects and interactions are sufficient to interpret an APLR model. However, it is possible to also inspect the underlying terms for those who wish to do so. For an example on how to interpret the terms in an APLR model, please see ***Section 5.1.3*** in the published article about APLR. You can find this article on [https://link.springer.com/article/10.1007/s00180-024-01475-4](https://link.springer.com/article/10.1007/s00180-024-01475-4) and [https://rdcu.be/dz7bF](https://rdcu.be/dz7bF).

documentation/model_interpretation_for_classification.md

@@ -52,7 +52,7 @@
         v=0.5,
         num_first_steps_with_linear_effects_only=0,  # Increasing this will increase interpretabilty but may decrease predictiveness.
         boosting_steps_before_interactions_are_allowed=0,  # Increasing this will increase interpretabilty but may decrease predictiveness.
-        **params
+        **params,
     )
     model.fit(
         data_train[predictors].values, data_train[response].values, X_names=predictors
@@ -95,10 +95,20 @@
     by="importance", ascending=False
 )
 
+# Generate and save plots of main effects and two-way interactions for each category. This is probably the most useful method for model interpretation.
+for category in categories:
+    logit_model = best_model.get_logit_model(category)
+    for affiliation in logit_model.get_unique_term_affiliations():
+        logit_model.plot_affiliation_shape(
+            affiliation,
+            plot=False,
+            save=True,
+            path=f"shape of {affiliation} for category {category}.png",
+        )
+
 # Local feature contribution for each prediction. For each prediction, uses calculate_local_feature_contribution() in the logit APLRRegressor model
 # for the category that corresponds to the prediction. Example in this data: If a prediction is "2" then using calculate_local_feature_contribution()
-# in the logit model that predicts whether an observation belongs to class "2" or not. This can be used to interpret the model, for example
-# by creating 3D surface plots against predictor values to interpret two-way interactions. This method can also be used on new data.
+# in the logit model that predicts whether an observation belongs to class "2" or not. This method can also be used on new data.
 local_feature_contribution = pd.DataFrame(
     best_model.calculate_local_feature_contribution(data_train[predictors]),
     columns=best_model.get_unique_term_affiliations(),

documentation/model_interpretation_for_regression.md

@@ -86,10 +86,20 @@
     by="importance", ascending=False
 )
 
+# Generate and save plots of main effects and two-way interactions for each category. This is probably the most useful method for model interpretation.
+for category in categories:
+    logit_model = best_model.get_logit_model(category)
+    for affiliation in logit_model.get_unique_term_affiliations():
+        logit_model.plot_affiliation_shape(
+            affiliation,
+            plot=False,
+            save=True,
+            path=f"shape of {affiliation} for category {category}.png",
+        )
+
 # Local feature contribution for each prediction. For each prediction, uses calculate_local_feature_contribution() in the logit APLRRegressor model
 # for the category that corresponds to the prediction. Example in this data: If a prediction is "2" then using calculate_local_feature_contribution()
-# in the logit model that predicts whether an observation belongs to class "2" or not. This can be used to interpret the model, for example
-# by creating 3D surface plots against predictor values to interpret two-way interactions. This method can also be used on new data.
+# in the logit model that predicts whether an observation belongs to class "2" or not. This method can also be used on new data.
 local_feature_contribution = pd.DataFrame(
     best_model.calculate_local_feature_contribution(data_train[predictors]),
     columns=best_model.get_unique_term_affiliations(),

examples/train_aplr_classification.py

@@ -104,66 +104,11 @@
     by="importance", ascending=False
 )
 
-# Shapes for all term affiliations in the model. For each term affiliation, shape_df contains predictor values and the corresponding
-# contributions to the linear predictor. Plots are created for main effects and two-way interactions.
-# This is probably the most useful method to use for understanding how the model works.
-predictors_in_each_affiliation = (
-    best_model.get_base_predictors_in_each_unique_term_affiliation()
-)
-for affiliation_index, affiliation in enumerate(
-    best_model.get_unique_term_affiliations()
-):
-    shape = best_model.get_unique_term_affiliation_shape(affiliation)
-    predictor_indexes_used = predictors_in_each_affiliation[affiliation_index]
-    shape_df = pd.DataFrame(
-        shape,
-        columns=[predictors[i] for i in predictor_indexes_used] + ["contribution"],
+# Generate and save plots of main effects and two-way interactions. This is probably the most useful method for model interpretation.
+for affiliation in best_model.get_unique_term_affiliations():
+    best_model.plot_affiliation_shape(
+        affiliation, plot=False, save=True, path=f"shape of {affiliation}.png"
     )
-    is_main_effect: bool = len(predictor_indexes_used) == 1
-    is_two_way_interaction: bool = len(predictor_indexes_used) == 2
-    if is_main_effect:
-        plt.plot(shape_df.iloc[:, 0], shape_df.iloc[:, 1])
-        plt.xlabel(shape_df.columns[0])
-        plt.ylabel(shape_df.columns[1])
-        plt.title("Contribution to the linear predictor")
-        plt.savefig(f"shape of {affiliation}.png")
-        plt.close()
-    elif is_two_way_interaction:
-        pivot_table = shape_df.pivot_table(
-            index=shape_df.columns[0],
-            columns=shape_df.columns[1],
-            values=shape_df.columns[2],
-            aggfunc="mean",
-        )
-        plt.figure(figsize=(8, 6))
-        plt.imshow(
-            pivot_table.values,
-            aspect="auto",
-            origin="lower",
-            extent=[
-                pivot_table.columns.min(),
-                pivot_table.columns.max(),
-                pivot_table.index.min(),
-                pivot_table.index.max(),
-            ],
-            cmap="Blues_r",
-        )
-        plt.colorbar(label="contribution")
-        plt.xlabel(shape_df.columns[1])
-        plt.ylabel(shape_df.columns[0])
-        plt.title("Contribution to the linear predictor")
-        plt.savefig(f"shape of {affiliation}.png")
-        plt.close()
-
-# Main effect shape for the third predictor. This can be visualized in a line plot.
-# Will be empty if the third predictor is not used as a main effect in the model.
-main_effect_shape = best_model.get_main_effect_shape(predictor_index=2)
-main_effect_shape = pd.DataFrame(
-    {
-        "predictor_value": main_effect_shape.keys(),
-        "contribution_to_linear_predictor": main_effect_shape.values(),
-    }
-)
 
 # Local contribution to the linear predictor for each prediction in the training data. This can be used to interpret the model,
 # for example by visualizing two-way interactions versus predictor values in a 3D surface plot. This method can also be used on new data.