Skip to content

v1.3.0 (2025-06-17)

Latest
Latest
Compare
Choose a tag to compare
@mmschlk mmschlk released this 17 Jun 08:59
v1.3.0
54c6414
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Below you find the reals notes for shapiq version 1.3.0.

✨Highlights

SPEX (SParse EXplainer) by @justinkang221 and @landonbutler spex_logo

shapiq.SPEX (Sparse Exact) approximator for efficient computation of sparse interaction values for really large models and games. Paper: SPEX: Scaling Feature Interaction Explanations for LLMs

# load your data and model with large number of features
data, model, n_features = ...

# use the SPEX approximator directly
approximator = shapiq.SPEX(n=n_features, index="FBII", max_order=2)
fbii_scores = approximator.approximate(budget=2000, game=model.predict)

# or use SPEX with an explainer
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="FBII",
    max_order=2,
    approximator="spex"  # specify SPEX as approximator
)
explanation = explainer.explain(data[0])
spec_results

AgnosticExplainer

The shapiq.AgnosticExplainer is a generic explainer that works for any value function or shapiq.Game object, allowing for more flexibility in explainers.

# get your game behavior and pass it to AgnosticExplainer
my_logic = ...

def value_function(coalition: np.ndarray[bool]) -> np.ndarray[float]:
    return my_logic(coalition)

explainer = shapiq.AgnosticExplainer(
    game=value_function,
    index="FSII",
    max_order=2,
    approximator="auto"
)
explanation = explainer.explain(budget=100)

Full Changelog

New Features

  • adds the SPEX (Sparse Exact) module in approximator.sparse for efficient computation of sparse interaction values #379
  • adds shapiq.AgnosticExplainer which is a generic explainer that can be used for any value function or shapiq.Game object. This allows for more flexibility in the explainers. #100, #395
  • changes budget to be a mandatory parameter given to the TabularExplainer.explain() method #355
  • changes logic of InteractionValues.get_n_order() function to be callable with either the order: int parameter and optional assignment of min_order: int and max_order: int parameters or with the min/max order parameters #372
  • renamed min_percentage parameter in the force plot to contribution_threshold to better reflect its purpose #391
  • adds verbose parameter to the Explainer's explain_X() method to control weather a progress bar is shown or not which is defaulted to False. #391
  • made InteractionValues.get_n_order() and InteractionValues.get_n_order_values() function more efficient by iterating over the stored interactions and not over the powerset of all potential interactions, which made the function not usable for higher player counts (models with many features, and results obtained from TreeExplainer). Note, this change does not really help get_n_order_values() as it still needs to create a numpy array of shape n_players times order #372
  • streamlined the network_plot() plot function to use the si_graph_plot() as its backend function. This allows for more flexibility in the plot function and makes it easier to use the same code for different purposes. In addition, the si_graph_plot was modified to make plotting more easy and allow for more flexibility with new parameters. #349
  • adds Game.compute() method to the shapiq.Game class to compute game values without changing the state of the game object. The compute method also introduces a shapiq.utils.sets.generate_interaction_lookup_from_coalitions() utility method which creates an interaction lookup dict from an array of coalitions. #397
  • streamlines the creation of network plots and graph plots which now uses the same backend. The network plot via shapiq.network_plot() or InteractionValues.plot_network() is now a special case of the shapiq.si_graph_plot() and InteractionValues.plot_si_graph(). This allows to create more beautiful plots and easier maintenance in the future. #349

Testing, Code-Quality and Documentation

  • activates "ALL" rules in ruff-format configuration to enforce stricter code quality checks and addressed around 500 (not automatically solvable) issues in the code base. #391
  • improved the testing environment by adding a new fixture module containing mock InteractionValues objects to be used in the tests. This allows for more efficient and cleaner tests, as well as easier debugging of the tests #372
  • removed check and error message if the index parameter is not in the list of available indices in the TabularExplainer since the type hints were replaced by Literals #391
  • removed multiple instances where shapiq tests if some approximators/explainers can be instantiated with certain indices or not in favor of using Literals in the __init__ method of the approximator classes. This allows for better type hinting and IDE support, as well as cleaner code. #391
  • Added documentation for all public modules, classes, and functions in the code base to improve the documentation quality and make it easier to understand how to use the package. #391
  • suppress a RuntimeWarning in Regression approximators solve_regression()method when the solver is not able to find good interim solutions for the regression problem.
  • refactors the tests into tests_unit/ and tests_integration/ to better separate unit tests from integration tests. #395
  • adds new integration tests in tests/tests_integration/test_explainer_california_housing which compares the different explainers against ground-truth interaction values computed by shapiq.ExactComputer and interaction values stored on disk as a form of regression test. This test should help finding bugs in the future when the approximators, explainers, or exact computation are changed. #395

Bug Fixes

  • fixed a bug in the shapiq.waterfall_plot function that caused the plot to not display correctly resulting in cutoff y_ticks. Additionally, the file was renamed from watefall.py to waterfall.py to match the function name #377
  • fixes a bug with TabPFNExplainer, where the model was not able to be used for predictions after it was explained. This was due to the model being fitted on a subset of features, which caused inconsistencies in the model's predictions after explanation. The fix includes that after each call to the TabPFNImputer.value_function, the tabpfn model is fitted on the whole dataset (without omitting features). This means that the original model can be used for predictions after it has been explained. #396.
  • fixed a bug in computing BII or BV indices with shapiq.approximator.MonteCarlo approximators (affecting SHAP-IQ, SVARM and SVARM-IQ). All orders of BII should now be computed correctly. #395

Autogenerated Notes

  • Relax interaction values by @hbaniecki in #360
  • 355 disallow budgetnone in explainer andor other occurrences by @Advueu963 in #356
  • Extends Code Quality Rules by @mmschlk in #363
  • Enforce "PTH" Linting Rule and Adds UpSet API Example Notebook by @mmschlk in #366
  • ⚒️ Extends ruff's formatting ruleset and adds docs dependencies into a uv group by @mmschlk in #371
  • ⚒️ Improves InteractionValues.get_n_order(), Adds Test Fixtures, and new install-import CI Workflow by @mmschlk in #372
  • Add extra tree tests by @IsaH57 in #373
  • Minor Bugfixed for shapiq.waterfall_plot by @Advueu963 in #377
  • Bump astral-sh/setup-uv from 5 to 6 by @dependabot in #375
  • Add the SPEX approximator to shapiq by @justinkang221 in #379
  • Docs-update by @mmschlk in #383
  • Docs-update by @mmschlk in #384
  • 🛠️ update of ruff-format ruleset to "ALL" by @mmschlk in #391
  • 📈streamline-network-and-si-grap-plot by @heinzll in #349
  • Rename t parameter in SPEX and Sparse by @mmschlk in #392
  • Add Game.compute function and related test to the Game class by @IsaH57 in #397
  • fixes bug with a TabPFN model not working as intended after explanations by @mmschlk in #401
  • adds AgnosticExplainer and refactors explanation/approximation code by @mmschlk in #395
  • Add references with sphinxcontrib-bibtex by @pwhofman in #394
  • shapiq 1.3.0 release by @mmschlk in #402

New Contributors

Full Changelog: v.1.2.3...v1.3.0

Contributors

justinkang221, dependabot, and 7 other contributors
Assets 2
Loading
0 Join discussion