added warning

Author: mathias-von-ottenbreit

API_REFERENCE_FOR_REGRESSION.md

@@ -334,7 +334,7 @@ A numpy matrix with predictor values.
 
 ## Method: get_unique_term_affiliation_shape(unique_term_affiliation: str)
 
-***Returns a matrix containing one column for each predictor used in the unique term affiliation, in addition to one column for the contribution to the linear predictor. For main effects or two-way interactions this can be visualized in for example line plots and surface plots respectively. See this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py).***
+***Returns a matrix containing one column for each predictor used in the unique term affiliation, in addition to one column for the contribution to the linear predictor. For main effects or two-way interactions this can be visualized in for example line plots and surface plots respectively. See this [example](https://github.com/ottenbreit-data-science/aplr/blob/main/examples/train_aplr_regression.py). Please note that the get_unique_term_affiliation_shape method is currently very memory intensive when handling interactions and may crash without warning on larger models. Consider using either of the calculate_local_feature_contribution or calculate_local_contribution_from_selected_terms methods to interpret interactions on larger models.***
 
 ### Parameters
 

cpp/APLRRegressor.h

@@ -2630,6 +2630,12 @@ MatrixXd APLRRegressor::get_unique_term_affiliation_shape(const std::string &uni
     std::vector<size_t> relevant_term_indexes{compute_relevant_term_indexes(unique_term_affiliation)};
     size_t unique_term_affiliation_index{unique_term_affiliation_map[unique_term_affiliation]};
     size_t num_predictors_used_in_the_affiliation{base_predictors_in_each_unique_term_affiliation[unique_term_affiliation_index].size()};
+    if (num_predictors_used_in_the_affiliation > 1)
+    {
+        std::string warning{"Please note that the get_unique_term_affiliation_shape method is currently very memory intensive when handling interactions and may crash without warning on larger models. Consider using either of the calculate_local_feature_contribution or calculate_local_contribution_from_selected_terms methods to interpret interactions on larger models."};
+        std::cout << warning << std::endl;
+    }
+
     std::vector<std::vector<double>> split_points_in_each_predictor(num_predictors_used_in_the_affiliation);
     for (size_t i = 0; i < num_predictors_used_in_the_affiliation; ++i)
     {

cpp/functions.h

@@ -544,32 +544,32 @@ double calculate_standard_deviation(const VectorXd &vector, const VectorXd &samp
 
 MatrixXd generate_combinations_and_one_additional_column(const std::vector<std::vector<double>> &vectors)
 {
-    int numVectors = vectors.size();
-    std::vector<int> sizes(numVectors);
-    int numRows = 1;
+    int num_vectors = vectors.size();
+    std::vector<int> sizes(num_vectors);
+    int num_rows = 1;
 
     // Calculate the number of rows in the result matrix
-    for (int i = 0; i < numVectors; ++i)
+    for (int i = 0; i < num_vectors; ++i)
     {
         sizes[i] = vectors[i].size();
-        numRows *= sizes[i];
+        num_rows *= sizes[i];
     }
 
     // Initialize the result matrix with an additional unused column
-    MatrixXd result(numRows, numVectors + 1);
+    MatrixXd result(num_rows, num_vectors + 1);
 
     // Generate all combinations
-    for (int row = 0; row < numRows; ++row)
+    for (int row = 0; row < num_rows; ++row)
     {
         int index = row;
-        for (int col = 0; col < numVectors; ++col)
+        for (int col = 0; col < num_vectors; ++col)
         {
             int vecSize = sizes[col];
             result(row, col) = vectors[col][index % vecSize];
             index /= vecSize;
         }
         // Set the additional unused column to zero (or any other value)
-        result(row, numVectors) = 0;
+        result(row, num_vectors) = 0;
     }
 
     return result;

documentation/APLR 10.4.0.pdf renamed to documentation/APLR 10.4.1.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_unique_term_affiliation_shape*** method or the ***get_main_effect_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 ***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.
 
 ## 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 ***get_unique_term_affiliation_shape*** method if your computer has enough memory (the method is currently very memory intensive when handling interaction terms and may crash without warning on larger models) or either of the ***calculate_local_feature_contribution*** or ***calculate_local_contribution_from_selected_terms*** methods 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.
 
 ## 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_regression.md

@@ -102,10 +102,11 @@
     by="importance", ascending=False
 )
 
-# Shapes for all term affiliations in the model. For each term affiliation, contains relevant predictor values and the corresponding
-# contributions to the linear predictor.
-# This is probably the most useful method to use for understanding how the model works.
-# Plots are created for main effects and two-way interactions.
+# Shapes for all term affiliations in the model. For each term affiliation, 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 but it is currently very memory intensive when 
+# handling interactions and may crash without warning on larger models. Consider using either of the calculate_local_feature_contribution 
+# or calculate_local_contribution_from_selected_terms methods to interpret interactions on larger models.
 shapes: Dict[str, pd.DataFrame] = {}
 predictors_in_each_affiliation = (
     best_model.get_base_predictors_in_each_unique_term_affiliation()
@@ -161,6 +162,34 @@
     best_model.calculate_local_feature_contribution(data_train[predictors]),
     columns=best_model.get_unique_term_affiliations(),
 )
+# Combining predictor values with local feature contribution for the second feature in best_model.get_unique_term_affiliations().
+# This can be visualized if it is a main effect or a two-way interaction.
+unique_term_affiliation_index = 1
+predictors_in_the_second_feature = [
+    predictors[predictor_index]
+    for predictor_index in best_model.get_base_predictors_in_each_unique_term_affiliation()[
+        unique_term_affiliation_index
+    ]
+]
+data_to_visualize = pd.DataFrame(
+    np.concatenate(
+        (
+            data_train[predictors_in_the_second_feature].values,
+            local_feature_contribution[
+                [
+                    best_model.get_unique_term_affiliations()[
+                        unique_term_affiliation_index
+                    ]
+                ]
+            ],
+        ),
+        axis=1,
+    ),
+    columns=predictors_in_the_second_feature
+    + [
+        f"contribution from {best_model.get_unique_term_affiliations()[unique_term_affiliation_index]}"
+    ],
+)
 
 # Local (observation specific) contribution to the linear predictor from selected interacting predictors.
 # In this example this concerns two-way interaction terms in the model where the fourth and the seventh predictors in X interact.

examples/train_aplr_regression.py

@@ -27,7 +27,7 @@
 
 setuptools.setup(
     name="aplr",
-    version="10.4.0",
+    version="10.4.1",
     description="Automatic Piecewise Linear Regression",
     ext_modules=[sfc_module],
     author="Mathias von Ottenbreit",