reordered tutorials

givasile · Oct 30, 2024 · 90520d6 · 90520d6
1 parent 2c44eb5
commit 90520d6
Show file tree

Hide file tree

Showing 36 changed files with 52 additions and 37 deletions.
diff --git a/Makefile b/Makefile
@@ -1,54 +1,66 @@
-#################################################################################
-# GLOBALS                                                                       #
-#################################################################################
+# global variables
 SHELL := /bin/bash
 
 PROJECT_NAME = effector
 PYTHON ?= 3.10
 ENV ?= sandbox
-
 REQUIREMENTS := $(if $(findstring sandbox,$(ENV)),requirements.txt,requirements-$(ENV).txt)
 
 # Conda related commands
-.PHONY: remove-conda-env
-remove-conda-env:
+.PHONY: conda-remove-env
+conda-remove-env:
 	@conda env list | grep -q "^$(PROJECT_NAME)-$(ENV) " && conda env remove --name $(PROJECT_NAME)-$(ENV) -y || echo "Environment $(PROJECT_NAME)-$(ENV) does not exist, skipping removal."
 
-.PHONY: create-conda-env
-create-conda-env:
+.PHONY: conda-create-env
+conda-create-env:
 	@conda create --name $(PROJECT_NAME)-$(ENV) python=$(PYTHON) -y
 
-.PHONY: install-conda-requirements
-install-conda-requirements:
+.PHONY: conda-install-requirements
+conda-install-requirements:
 	@conda run -n $(PROJECT_NAME)-$(ENV) pip install --upgrade pip
 	@conda run -n $(PROJECT_NAME)-$(ENV) pip install -r $(REQUIREMENTS)
+	@conda run -n $(PROJECT_NAME)-$(ENV) pip install -e .
 
 .PHONY: conda-init
-conda-init: remove-conda-env create-conda-env install-conda-requirements
+conda-init: conda-remove-env conda-create-env conda-install-requirements
 
 .PHONY: conda-update
-conda-update: install-conda-requirements
+conda-update: conda-install-requirements
 
 # Pip related commands
-.PHONY: remove-venv
-remove-venv:
+.PHONY: venv-remove
+venv-remove:
 	rm -rf .venv-$(ENV)
 
-.PHONY: create-venv
-create-venv:
+.PHONY: venv-create
+venv-create:
 	python -m venv .venv-$(ENV)
 
-.PHONY: install-venv-requirements
-install-venv-requirements:
+.PHONY: venv-install-requirements
+venv-install-requirements:
 	source .venv-$(ENV)/bin/activate && python -m pip install --upgrade pip
 	source .venv-$(ENV)/bin/activate && python -m pip install -r $(REQUIREMENTS)
+	source .venv-$(ENV)/bin/activate && python -m pip install -e .
 
 .PHONY: venv-init
-venv-init: remove-venv create-venv install-venv-requirements
+venv-init: venv-remove venv-create venv-install-requirements
 
 .PHONY: venv-update
-venv-update: install-venv-requirements
+venv-update: venv-install-requirements
+
+# Documentation related commands
+.PHONY: docs-update
+docs-update:
+	@source .venv-dev/bin/activate && jupyter nbconvert --to markdown ./notebooks/real-examples/* --output-dir docs/docs/Tutorials/real-examples/
+	@source .venv-dev/bin/activate && jupyter nbconvert --to markdown ./notebooks/synthetic-examples/* --output-dir docs/docs/Tutorials/synthetic-examples/
+
+docs-serve:
+	@source .venv-dev/bin/activate && cd docs/ && mkdocs serve
 
+# Test related commands
+.PHONY: test
+test:
+	@source .venv-test/bin/activate && pytest -v
 
 # Delete all compiled Python files
 .PHONY: clean

diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_2.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_33_2.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_37_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_37_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_37_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_37_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_2.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_43_2.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_2.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_52_2.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_56_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_56_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_56_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_56_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_0.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_0.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_1.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_1.png
diff --git a/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_2.png b/...ocs/Tutorials/synthetic-examples/02_regional_pdp_files/02_regional_pdp_61_2.png
diff --git a/docs/docs/Tutorials/synthetic-examples/02_regional_rhale.md b/docs/docs/Tutorials/synthetic-examples/02_regional_rhale.md
@@ -37,9 +37,7 @@ X_cor = generate_dataset_correlated(N)
 ### Black-box function
 
 We will use the following linear model with a subgroup-specific interaction term:
- $$ y = 3x_1I_{x_3>0} - 3x_1I_{x_3\leq0} + x_3$$ 
-
-The presence of interaction terms ($3x_1I_{x_3>0}$, $3x_1I_{x_3\leq0}$) makes it impossible to define a solid ground truth effect. However, under some mild assumptions, we can agree tha
+ $$ y = 3x_1I_{x_3>0} - 3x_1I_{x_3\leq0} + x_3$$.
 
 ## Ground truth effect (uncorrelated setting)
 

diff --git a/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_13_0.png b/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_13_0.png
diff --git a/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_13_1.png b/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_13_1.png
diff --git a/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_0.png b/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_0.png
diff --git a/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_1.png b/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_1.png
diff --git a/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_2.png b/...Tutorials/synthetic-examples/02_regional_rhale_files/02_regional_rhale_19_2.png
diff --git a/effector/global_effect.py b/effector/global_effect.py
@@ -83,14 +83,14 @@ def __init__(
         self.is_fitted: np.ndarray = np.ones([self.dim]) < 1
 
         # parameters used when fitting the feature effect
-        self.method_args: dict = {}
+        self.fit_args: dict = {}
 
-        # dictionary with all the information required for plotting or evaluating the feature effect
+        # dict, like {"feature_i": {"quantity_1": value_1, "quantity_2": value_2, ...}} for the i-th
         self.feature_effect: dict = {}
 
     @abstractmethod
     def fit(self, features: Union[int, str, list] = "all", **kwargs) -> None:
-        """Fit the feature effect for the given features.
+        """Fit, i.e., compute the quantities that are necessary for evaluating and plotting the feature effect, for the given features.
 
         Args:
             features: the features to fit. If set to "all", all the features will be fitted.
@@ -108,14 +108,16 @@ def plot(self, feature: int, *args) -> None:
         """
         raise NotImplementedError
 
-    def refit(self, feature, centering):
-        """Checks if refitting is needed."""
+    def requires_refit(self, feature, centering):
+        """Check if refitting is needed
+           TODO: generalize this method using the method_args, instead of centering
+        """
         if not self.is_fitted[feature]:
             return True
         else:
             if centering is not False:
                 if (
-                    self.method_args["feature_" + str(feature)]["centering"]
+                    self.fit_args["feature_" + str(feature)]["centering"]
                     != centering
                 ):
                     return True
@@ -128,6 +130,7 @@ def eval(
         xs: np.ndarray,
         heterogeneity: bool = False,
         centering: Union[bool, str] = False,
+        **kwargs,
     ) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray, np.ndarray]]:
         """Evaluate the effect of the s-th feature at positions `xs`.
 

diff --git a/effector/global_effect_ale.py b/effector/global_effect_ale.py
@@ -88,7 +88,7 @@ def _fit_loop(self, features, binning_method, centering):
                 ] = self.empty_symbol
 
             self.is_fitted[s] = True
-            self.method_args["feature_" + str(s)] = {
+            self.fit_args["feature_" + str(s)] = {
                 "centering": centering,
             }
 
@@ -142,7 +142,7 @@ def eval(
         """
         centering = helpers.prep_centering(centering)
 
-        if self.refit(feature, centering):
+        if self.requires_refit(feature, centering):
             self.fit(features=feature, centering=centering)
 
         # Check if the lower bound is less than the upper bound

diff --git a/effector/global_effect_pdp.py b/effector/global_effect_pdp.py
@@ -119,7 +119,7 @@ def fit(
                 s, centering, points_for_centering, use_vectorized
             )
             self.is_fitted[s] = True
-            self.method_args["feature_" + str(s)] = {
+            self.fit_args["feature_" + str(s)] = {
                 "centering": centering,
                 "points_for_centering": points_for_centering,
             }
@@ -165,7 +165,7 @@ def eval(
         """
         centering = helpers.prep_centering(centering)
 
-        if self.refit(feature, centering):
+        if self.requires_refit(feature, centering):
             self.fit(
                 features=feature, centering=centering, use_vectorized=use_vectorized
             )

diff --git a/effector/global_effect_shap.py b/effector/global_effect_shap.py
@@ -201,7 +201,7 @@ def fit(
                 s, centering, points_for_centering
             )
             self.is_fitted[s] = True
-            self.method_args["feature_" + str(s)] = {
+            self.fit_args["feature_" + str(s)] = {
                 "centering": centering,
                 "points_for_centering": points_for_centering,
             }
@@ -236,7 +236,7 @@ def eval(
         """
         centering = helpers.prep_centering(centering)
 
-        if self.refit(feature, centering):
+        if self.requires_refit(feature, centering):
             self.fit(features=feature, centering=centering)
 
         # Check if the lower bound is less than the upper bound

diff --git a/real-examples/01_bike_sharing_dataset.ipynb → ...al-examples/01_bike_sharing_dataset.ipynb b/real-examples/01_bike_sharing_dataset.ipynb → ...al-examples/01_bike_sharing_dataset.ipynb
diff --git a/synthetic-examples/01_linear_model.ipynb → .../synthetic-examples/01_linear_model.ipynb b/synthetic-examples/01_linear_model.ipynb → .../synthetic-examples/01_linear_model.ipynb
diff --git a/...02_global_effect_methods_comparison.ipynb → ...02_global_effect_methods_comparison.ipynb b/...02_global_effect_methods_comparison.ipynb → ...02_global_effect_methods_comparison.ipynb
diff --git a/synthetic-examples/02_regional_pdp.ipynb → .../synthetic-examples/02_regional_pdp.ipynb b/synthetic-examples/02_regional_pdp.ipynb → .../synthetic-examples/02_regional_pdp.ipynb
diff --git a/synthetic-examples/02_regional_rhale.ipynb → ...ynthetic-examples/02_regional_rhale.ipynb b/synthetic-examples/02_regional_rhale.ipynb → ...ynthetic-examples/02_regional_rhale.ipynb
diff --git a/synthetic-examples/02_regional_shapdp.ipynb → ...nthetic-examples/02_regional_shapdp.ipynb b/synthetic-examples/02_regional_shapdp.ipynb → ...nthetic-examples/02_regional_shapdp.ipynb
diff --git a/...les/03_regional_effects_synthetic_f.ipynb → ...les/03_regional_effects_synthetic_f.ipynb b/...les/03_regional_effects_synthetic_f.ipynb → ...les/03_regional_effects_synthetic_f.ipynb
diff --git a/...examples/04_regional_effects_real_f.ipynb → ...examples/04_regional_effects_real_f.ipynb b/...examples/04_regional_effects_real_f.ipynb → ...examples/04_regional_effects_real_f.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,8 @@
 [build-system]
-requires = ["setuptools", "setuptools-scm"]
-build-backend = "setuptools.build_meta"
+#requires = ["setuptools", "setuptools-scm"]
+#build-backend = "setuptools.build_meta"
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
 
 [tool.setuptools]
 packages = ['effector']