Rename functions and quantities of interest

doc/api.rst

@@ -30,8 +30,8 @@ This is the full API documentation of the `sharp` package.
     qoi.DiffQoI
     qoi.FlipQoI
     qoi.LikelihoodQoI
-    qoi.RankingQoI
-    qoi.RankingScoreQoI
+    qoi.RankQoI
+    qoi.RankScoreQoI
     qoi.TopKQoI
 
 
@@ -68,4 +68,4 @@ This is the full API documentation of the `sharp` package.
     utils.check_inputs
     utils.check_measure
     utils.check_qoi
-    utils.scores_to_rank
+    utils.scores_to_ordering

examples/plot_basic_usage.py

@@ -37,7 +37,7 @@ def score_function(X):
 # Next, we will set up ``ShaRP``:
 
 xai = ShaRP(
-    qoi="ranking",
+    qoi="rank",
     target_function=score_function,
     measure="shapley",
     sample_size=None,
@@ -50,8 +50,8 @@ def score_function(X):
 ######################################################################################
 # Let's take a look at some shapley values used for ranking explanations:
 
-print("Global contribution of a single feature:", xai.feature(0, X))
-print("Global feature contributions:", xai.all(X).mean(axis=0))
+print("Aggregate contribution of a single feature:", xai.feature(0, X))
+print("Aggregate feature contributions:", xai.all(X).mean(axis=0))
 
 individual_scores = xai.individual(9, X)
 print("Feature contributions to a single observation: ", individual_scores)
@@ -76,6 +76,6 @@ def score_function(X):
 
 # Waterfall explaining rank for sample 2
 axes[1] = xai.plot.waterfall(individual_scores)
-axes[1].suptitle("Ranking explanation for Sample 9")
+axes[1].suptitle("Rank explanation for Sample 9")
 
 plt.show()

sharp/base.py

@@ -1,18 +1,5 @@
 """
 Base object used to set up explainability objects.
-
-Topics that must be covered:
-- Single-observation explanation
-- Global-input explanation
-  * Set qii
-  * Unary qii
-  * Marginal qii
-  * Shapley
-  * Banzhaff
-
-TODO: Check params functions (data/object types and such)
-TODO: Parallelization/Vectorization
-TODO: Ensure inputs are converted to numpy arrays
 """
 
 import numpy as np

sharp/qoi/__init__.py

@@ -6,8 +6,8 @@
     DiffQoI,
     FlipQoI,
     LikelihoodQoI,
-    RankingQoI,
-    RankingScoreQoI,
+    RankQoI,
+    RankScoreQoI,
     TopKQoI,
     QOI_OBJECTS,
 )
@@ -16,8 +16,8 @@
     "DiffQoI",
     "FlipQoI",
     "LikelihoodQoI",
-    "RankingQoI",
-    "RankingScoreQoI",
+    "RankQoI",
+    "RankScoreQoI",
     "TopKQoI",
     "QOI_OBJECTS",
 ]

sharp/qoi/_qoi.py

@@ -1,4 +1,4 @@
-from .base import BaseQoI, BaseRankingQoI
+from .base import BaseQoI, BaseRankQoI
 
 
 class DiffQoI(BaseQoI):
@@ -80,9 +80,9 @@ def _calculate(self, rows1, rows2):
         return self.estimate(rows1) - self.estimate(rows2)  # .mean()
 
 
-class RankingQoI(BaseRankingQoI):
+class RankQoI(BaseRankQoI):
     """
-    Ranking specific QoI. Uses rank as the quantity being measured. The influence score
+    Rank specific QoI. Uses rank as the quantity being measured. The influence score
     is based on the comparison between the rank of a sample and synthetic data (based on
     the original sample). ``target_function`` should output scores.
 
@@ -98,7 +98,7 @@ def _calculate(self, rows1, rows2):
         return (self.estimate(rows2) - self.estimate(rows1)).mean()
 
 
-class RankingScoreQoI(BaseRankingQoI):
+class RankScoreQoI(BaseRankQoI):
     """
     A general, ranking-oriented QoI, similar to ``DiffQoI``. ``target_function`` must
     output scores.
@@ -115,9 +115,9 @@ def _calculate(self, rows1, rows2):
         return (self.estimate(rows1) - self.estimate(rows2)).mean()
 
 
-class TopKQoI(BaseRankingQoI):
+class TopKQoI(BaseRankQoI):
     """
-    Ranking-specific QoI. Estimates the likelihood of reaching the top-K as the
+    Rank-specific QoI. Estimates the likelihood of reaching the top-K as the
     quantity of interest.
 
     Parameters
@@ -142,7 +142,7 @@ def _calculate(self, rows1, rows2):
     "diff": DiffQoI,
     "flip": FlipQoI,
     "likelihood": LikelihoodQoI,
-    "ranking": RankingQoI,
-    "ranking_score": RankingScoreQoI,
+    "rank": RankQoI,
+    "rank_score": RankScoreQoI,
     "top_k": TopKQoI,
 }

sharp/qoi/base.py

@@ -75,7 +75,7 @@ def _calculate(self, rows1, rows2):
         pass
 
 
-class BaseRankingQoI(BaseQoI, metaclass=ABCMeta):
+class BaseRankQoI(BaseQoI, metaclass=ABCMeta):
     """
     Base class to implement Quantities of Interest (QoI) for ranking tasks. It should not
     be used directly. Any QoI must define at least 2 functions:

sharp/tests/test_basic_usage.py

@@ -11,7 +11,7 @@
 N_SAMPLES = 50
 rng = check_random_state(RNG_SEED)
 
-rank_qois_str = ["ranking", "ranking_score", "top_k"]
+rank_qois_str = ["rank", "rank_score", "top_k"]
 rank_qois_obj = [QOI_OBJECTS[qoi] for qoi in rank_qois_str]
 
 clf_qois_str = ["diff", "flip", "likelihood"]

sharp/utils/__init__.py

@@ -3,12 +3,12 @@
 """
 
 from ._checks import check_feature_names, check_inputs, check_measure, check_qoi
-from ._rank_utils import scores_to_rank
+from ._rank_utils import scores_to_ordering
 
 __all__ = [
     "check_feature_names",
     "check_inputs",
     "check_measure",
     "check_qoi",
-    "scores_to_rank",
+    "scores_to_ordering",
 ]

sharp/utils/_rank_utils.py

@@ -1,7 +1,7 @@
 import numpy as np
 
 
-def scores_to_rank(y, direction=-1):
+def scores_to_ordering(y, direction=-1):
     """
     Converts an array with scores to a ranking.
 

sharp/visualization/_waterfall.py

@@ -3,8 +3,6 @@
 import numpy as np
 from sharp.utils._utils import _optional_import
 
-# from sharp.utils import scores_to_rank
-
 
 blue_rgb = np.array([0, 0.54337757, 0.98337906])
 light_blue_rgb = np.array([127.0, 196, 252]) / 255