Merge pull request #46 from mmschlk/development

Add Collaborator Tutorial and Code of Conduct

.pre-commit-config.yaml

@@ -21,4 +21,4 @@ repos:
         name: ruff
         language: python
         types: [python]
-        entry: ruff --fix
+        entry: ruff --no-cache --fix

CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+
+# ✌️ Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`maximilian.muschalik"at"ifi.lmu.de`.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# ✌️ Contributing Guidelines
+
+This document outlines the guidelines for contributing to the project. It should enable contributors
+to understand the process for applying changes to the project and how to interact with the community.
+For the code of conduct, please refer to the [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+
+## 🗺️ What to Work On
+First, we welcome contributions from everyone in every form. If you feel that something is missing 
+or could be improved, feel free to change it. However, to streamline the process of contributing 
+higher-tier changes or features to the project, we maintain an open 
+[roadmap](https://github.com/users/mmschlk/projects/4/views/4). There, we collect ideas and features
+that we want to add to the project. If you want to work on something, please check the roadmap first
+to see if the feature is already planned or if there is a similar feature that you could contribute 
+to.
+
+### 🙏 Discussions
+If you have an idea for a new feature or a change, we encourage everyone to open a discussion in the
+[Discussions](https://github.com/mmschlk/shapiq/discussions/new/choose) section. 
+We encourage you to open a discussion so that we can align on the work to be done. It's generally a 
+good idea to have a quick discussion before opening a pull request that is potentially out-of-scope.
+
+
+## 📝 Typical Setup: Fork, Clone, and Pull
+
+The typical workflow for contributing to `shapiq` is:
+
+1. Fork the `main` branch from the [GitHub repository](https://github.com/mmschlk/shapiq/).
+2. Clone your fork locally.
+3. Commit changes.
+4. Push the changes to your fork.
+5. Send a pull request from your fork back to the original `main` branch.
+
+## 📦 Development Setup
+
+Start by cloning the repository:
+
+```sh
+git clone https://github.com/mmschlk/shapiq/
+```
+
+Next you need a python environment with a supported version of python. We recommend using
+[pyenv](https://github.com/pyenv/pyenv-installer). Once you have pyenv, you can install the latest 
+Python version `shapiq` supports:
+
+```sh
+pyenv install 3.9
+```
+
+Then, create a virtual environment and install the development dependencies:
+
+```sh
+cd shapiq
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+```
+
+Finally, install the [pre-commit](https://pre-commit.com/) push hooks. This will run some code 
+quality checks every time you push to GitHub.
+
+```sh
+pre-commit install --hook-type pre-push
+```
+
+If you want, you can optionally run `pre-commit` at any time as so:
+
+```sh
+pre-commit run --all-files
+```
+
+## 📝 Commit Messages
+
+We do not enforce a strict commit message format, but we encourage you to follow good practices.
+We recommend to use action-words to automatically close issues or pull requests (example: `closes #123`). 
+For example, start the commit message with a verb in the imperative mood, and keep the message short
+and concise. For example:
+
+```
+add feature-xyz and closes #123
+```
+
+## 🛠️ Making Changes
+
+Now, you're ready to make changes to the code. We recommend that you check out `shapiq`'s source
+code for inspiration before getting started. How you make changes is, of course, up to you. However,
+we can give you some tips on how to document and test your changes.
+
+### 📖 Documenting Changes
+If you are adding a new class of function, you will need to add a docstring to the class or 
+function. With `shapiq`, we use the [Google Style Convention](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+Please add a docstring in the same style.
+
+To build the documentation on your end and to check if your changes are documented correctly, you 
+need to install the documentation dependencies:
+
+```sh
+pip install -e .[docs]
+```
+
+Then, you can build the documentation from the root of the repository with:
+
+```sh
+sphinx-build docs/source docs/build
+```
+
+This will render the documentation in the `docs/build` directory. You can open the `index.html` file
+in your browser to see the rendered documentation.
+
+### 🎯 Testing Changes
+
+We use `pytest` for running unit tests and coverage. In the near future we will add `mypy` to the 
+static type checking. 
+
+#### Unit Tests
+
+Unit tests **absolutely need to pass**. Write unit tests for your changes. If you are adding a new
+feature, you need to add tests for the new feature. If you are fixing a bug it is a good idea to add
+a test that shows the bug and that your fix works.
+Unit tests are located in the `tests` directory. To run the tests, you can use the following command:
+
+```sh
+pytest
+```
+
+#### Coverage
+
+With `shapiq`, we aim to have a high test coverage (95% -100%). We aim that every pull request does
+not decrease the test coverage.
+We use `pytest-cov` to measure the test coverage. To run the tests with coverage, you can use the
+following command: 
+
+```sh
+pytest --cov=shapiq
+```
+
+#### Static Type Checking and Code Quality
+
+Currently, we do not have static type checking in place. We use `pre-commit` to run some code quality
+checks. These checks **absolutely need to pass**. You can run the checks with the following command:
+
+```sh
+pre-commit run --all-files
+```
+
+In the near future we aim to use `mypy` for type checking. Once added this will also be part of the
+pre-commit pipeline and hence **absolutely need to pass**.
+
+If you want, you can run `mypy` with the following command:
+
+```sh
+mypy shapiq
+```

setup.py

@@ -18,7 +18,7 @@
 with io.open(os.path.join(work_directory, "README.md"), encoding="utf-8") as f:
     long_description = "\n" + f.read()
 
-base_packages = ["numpy", "scipy", "pandas"]
+base_packages = ["numpy", "scipy", "pandas", "tqdm"]
 
 plotting_packages = ["matplotlib", "colour", "networkx"]
 
@@ -76,6 +76,15 @@
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
     ],
-    keywords=["python", "machine learning", "shap", "xai", "interaction"],
+    keywords=[
+        "python",
+        "machine learning",
+        "shap",
+        "xai",
+        "interaction",
+        "shapley interactions",
+        "shapley values",
+        "feature interaction",
+    ],
     zip_safe=True,
 )

shapiq/__init__.py

@@ -7,10 +7,11 @@
 from .approximator import (
     PermutationSamplingSII,
     PermutationSamplingSTI,
-    RegressionSII,
     RegressionFSI,
+    RegressionSII,
     ShapIQ,
 )
+from .datasets import load_bike
 
 # explainer classes
 from .explainer import InteractionExplainer
@@ -27,12 +28,10 @@
     get_explicit_subsets,
     get_parent_array,
     powerset,
-    split_subsets_budget,
     safe_isinstance,
+    split_subsets_budget,
 )
 
-from .datasets import load_bike
-
 __all__ = [
     # version
     "__version__",

shapiq/approximator/__init__.py

@@ -2,7 +2,7 @@
 from .k_sii import convert_ksii_into_one_dimension, transforms_sii_to_ksii
 from .permutation.sii import PermutationSamplingSII
 from .permutation.sti import PermutationSamplingSTI
-from .regression import RegressionSII, RegressionFSI, KernelSHAP
+from .regression import KernelSHAP, RegressionFSI, RegressionSII
 from .shapiq import ShapIQ
 
 __all__ = [
@@ -12,4 +12,6 @@
     "RegressionFSI",
     "RegressionSII",
     "ShapIQ",
+    "transforms_sii_to_ksii",
+    "convert_ksii_into_one_dimension",
 ]

shapiq/approximator/_base.py

@@ -3,7 +3,6 @@
 from typing import Callable, Optional
 
 import numpy as np
-
 from approximator._config import AVAILABLE_INDICES
 from approximator._interaction_values import InteractionValues
 from approximator._utils import _generate_interaction_lookup

shapiq/approximator/_interaction_values.py

@@ -3,9 +3,9 @@
 from typing import Optional
 
 import numpy as np
-
-from approximator._utils import _generate_interaction_lookup
 from approximator._config import AVAILABLE_INDICES
+from approximator._utils import _generate_interaction_lookup
+
 from shapiq.utils import powerset