Skip to content

Commit 5c1fee3

Browse files
rinzivrinziv
authored
Add comprehensive API documentation with GitHub Pages deployment
Add comprehensive API documentation with GitHub Pages deployment
2 parents 335cc54 + 574d15a commit 5c1fee3

25 files changed

Lines changed: 2541 additions & 120 deletions

‎.github/workflows/docs.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
pull_request:
9+
branches:
10+
- main
11+
- master
12+
workflow_dispatch:
13+
14+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
# Allow only one concurrent deployment
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: false
24+
25+
jobs:
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
with:
32+
submodules: recursive
33+
34+
- name: Set up Python
35+
uses: actions/setup-python@v5
36+
with:
37+
python-version: '3.10'
38+
39+
- name: Install dependencies
40+
run: |
41+
python -m pip install --upgrade pip
42+
pip install sphinx sphinx-autodoc-typehints
43+
pip install -e .
44+
45+
- name: Build documentation
46+
run: |
47+
cd docs
48+
make html
49+
50+
- name: Upload artifact
51+
uses: actions/upload-pages-artifact@v3
52+
with:
53+
path: docs/_build/html
54+
55+
deploy:
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
runs-on: ubuntu-latest
60+
needs: build
61+
# Only deploy on push to main/master branch
62+
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v4

‎README.rst‎

Lines changed: 27 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,12 +58,12 @@ Image Data
5858
Text Data
5959
---------
6060

61-
* 🚧 **Work in Progress** - Coming soon!
61+
* **LIME** - Local Interpretable Model-agnostic Explanations for text classification
6262

6363
Time Series Data
6464
----------------
6565

66-
* 🚧 **Work in Progress** - Coming soon!
66+
* **LASTS** - Local Agnostic Subsequence-based Time Series explanations
6767

6868
|
6969
@@ -110,19 +110,24 @@ Here's a simple example of using LIME for tabular data explanation:
110110

111111
.. code-block:: python
112112
113-
from xailib import Explainer
113+
from xailib.explainers.lime_explainer import LimeXAITabularExplainer
114+
from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper
114115
115-
# Initialize your black-box model
116-
# model = YourModel()
116+
# Wrap your scikit-learn model
117+
bb = sklearn_classifier_wrapper(your_trained_model)
117118
118-
# Create an explainer
119-
explainer = Explainer(model, method='lime')
119+
# Create and fit the LIME explainer
120+
explainer = LimeXAITabularExplainer(bb)
121+
explainer.fit(df, 'target_column', config={
122+
'discretize_continuous': True,
123+
'feature_selection': 'auto'
124+
})
120125
121-
# Generate explanation for a sample
122-
explanation = explainer.explain(sample_data)
126+
# Generate explanation for an instance
127+
explanation = explainer.explain(instance, num_samples=1000)
123128
124-
# Visualize the explanation
125-
explainer.visualize(explanation)
129+
# Visualize feature importance
130+
explanation.plot_features_importance()
126131
127132
For more examples and detailed usage, please check the `examples/ <https://github.com/kdd-lab/XAI-Lib/tree/main/examples>`_ directory.
128133

@@ -133,10 +138,18 @@ For more examples and detailed usage, please check the `examples/ <https://githu
133138

134139
For detailed documentation, tutorials, and API reference, visit:
135140

136-
* **Documentation**: `https://xai-lib.readthedocs.io/ <https://xai-lib.readthedocs.io/>`_
141+
* **GitHub Pages Documentation**: `https://kdd-lab.github.io/XAI-Lib/ <https://kdd-lab.github.io/XAI-Lib/>`_
142+
* **Read the Docs**: `https://xai-lib.readthedocs.io/ <https://xai-lib.readthedocs.io/>`_
137143
* **GitHub Repository**: `https://github.com/kdd-lab/XAI-Lib <https://github.com/kdd-lab/XAI-Lib>`_
138144
* **Issue Tracker**: `https://github.com/kdd-lab/XAI-Lib/issues <https://github.com/kdd-lab/XAI-Lib/issues>`_
139145

146+
The documentation includes:
147+
148+
* **Getting Started Guide**: Installation and quick start tutorials
149+
* **API Reference**: Complete documentation of all classes and methods
150+
* **Examples**: Practical examples for tabular, image, and text data
151+
* **Contributing Guide**: How to contribute to the project
152+
140153
|
141154
142155
🤝 Contributing
@@ -165,17 +178,13 @@ This project is licensed under the MIT License - see the `LICENSE <LICENSE.txt>`
165178

166179
|
167180
168-
🙏 Acknowledgments
181+
Acknowledgments
169182
==================
170183

171184
This library is developed as part of the **XAI Project** (`https://xai-project.eu/ <https://xai-project.eu/>`_), a European initiative dedicated to advancing explainable artificial intelligence.
172185

173-
The XAI Project aims to:
186+
The Xai project focuses on the urgent open challenge of how to construct meaningful explanations of opaque AI/ML systems in the context of ai based decision making, aiming at empowering individual against undesired effects of automated decision making, implementing the right of explanation, helping people make better decisions preserving (and expand) human autonomy.
174187

175-
* Develop new methods for explainable AI
176-
* Create practical tools for AI transparency
177-
* Foster collaboration between research and industry
178-
* Promote responsible AI development
179188

180189
For more information about the XAI Project, visit `https://xai-project.eu/ <https://xai-project.eu/>`_.
181190

‎docs/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@
22
# To build the module reference correctly, make sure every external package
33
# under `install_requires` in `setup.cfg` is also listed here!
44
sphinx>=3.2.1
5+
sphinx-autodoc-typehints>=1.12.0
56
# sphinx_rtd_theme

‎src/xailib/__init__.py‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
"""
2+
XAI-Lib: An Integrated Python Library for Explainable AI.
3+
4+
**XAI-Lib** provides a unified interface for various explanation methods,
5+
making machine learning models more interpretable and transparent. The library
6+
simplifies the process of explaining black-box models across different data types.
7+
8+
This project is part of the `XAI Project <https://xai-project.eu/>`_ - a European
9+
initiative focused on advancing explainable artificial intelligence research
10+
and applications.
11+
12+
Main Modules
13+
------------
14+
15+
Core Classes
16+
~~~~~~~~~~~~
17+
18+
.. autosummary::
19+
:toctree: _autosummary
20+
21+
xailib.xailib_base
22+
xailib.xailib_tabular
23+
xailib.xailib_image
24+
xailib.xailib_text
25+
xailib.xailib_ts
26+
xailib.xailib_transparent_by_design
27+
28+
Explainers
29+
~~~~~~~~~~
30+
31+
.. autosummary::
32+
:toctree: _autosummary
33+
34+
xailib.explainers.lime_explainer
35+
xailib.explainers.shap_explainer_tab
36+
xailib.explainers.lore_explainer
37+
xailib.explainers.gradcam_explainer
38+
xailib.explainers.rise_explainer
39+
xailib.explainers.intgrad_explainer
40+
xailib.explainers.abele_explainer
41+
xailib.explainers.lasts_explainer
42+
xailib.explainers.nam_explainer_tab
43+
44+
Model Wrappers
45+
~~~~~~~~~~~~~~
46+
47+
.. autosummary::
48+
:toctree: _autosummary
49+
50+
xailib.models.bbox
51+
xailib.models.sklearn_classifier_wrapper
52+
xailib.models.keras_classifier_wrapper
53+
xailib.models.pytorch_classifier_wrapper
54+
55+
Data Loaders
56+
~~~~~~~~~~~~
57+
58+
.. autosummary::
59+
:toctree: _autosummary
60+
61+
xailib.data_loaders.dataframe_loader
62+
63+
Metrics
64+
~~~~~~~
65+
66+
.. autosummary::
67+
:toctree: _autosummary
68+
69+
xailib.metrics.insertiondeletion
70+
71+
Quick Start
72+
-----------
73+
74+
Here's a simple example using LIME for tabular data explanation::
75+
76+
from xailib.explainers.lime_explainer import LimeXAITabularExplainer
77+
from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper
78+
79+
# Wrap your scikit-learn model
80+
bb = sklearn_classifier_wrapper(your_sklearn_model)
81+
82+
# Create and fit the explainer
83+
explainer = LimeXAITabularExplainer(bb)
84+
explainer.fit(df, 'target_column', config={})
85+
86+
# Generate explanation for an instance
87+
explanation = explainer.explain(instance)
88+
89+
# Visualize feature importance
90+
explanation.plot_features_importance()
91+
92+
For more examples, see the `examples/ <https://github.com/kdd-lab/XAI-Lib/tree/main/examples>`_
93+
directory in the repository.
94+
95+
License
96+
-------
97+
98+
This project is licensed under the MIT License.
99+
100+
Acknowledgments
101+
---------------
102+
103+
This library is developed as part of the **XAI Project** (https://xai-project.eu/),
104+
a European initiative dedicated to advancing explainable artificial intelligence.
105+
"""
106+
107+
from importlib.metadata import PackageNotFoundError, version
108+
109+
try:
110+
__version__ = version("XAI-Library")
111+
except PackageNotFoundError:
112+
__version__ = "unknown"
113+
114+
# Import main classes for convenient access
115+
from xailib.xailib_base import Explainer, Explanation
116+
117+
__all__ = [
118+
"__version__",
119+
"Explainer",
120+
"Explanation",
121+
]

‎src/xailib/data_loaders/__init__.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
"""
2+
Data loading utilities for XAI-Lib.
3+
4+
This subpackage provides utilities for loading and preparing data
5+
for use with XAI-Lib explainers.
6+
7+
Available Loaders
8+
-----------------
9+
10+
- :func:`~xailib.data_loaders.dataframe_loader.prepare_dataframe`:
11+
Prepare a pandas DataFrame for use with XAI-Lib explainers.
12+
13+
Example
14+
-------
15+
>>> from xailib.data_loaders.dataframe_loader import prepare_dataframe
16+
>>>
17+
>>> df, feature_names, class_values, numeric_columns, \\
18+
... rdf, real_feature_names, features_map = prepare_dataframe(df, 'target')
19+
"""

‎src/xailib/data_loaders/dataframe_loader.py‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,53 @@
1+
"""
2+
DataFrame loading and preparation utilities for XAI-Lib.
3+
4+
This module provides utilities for loading and preparing pandas DataFrames
5+
for use with XAI-Lib tabular data explainers.
6+
7+
Functions:
8+
prepare_dataframe: Prepare a DataFrame for use with explainers.
9+
10+
Example:
11+
>>> from xailib.data_loaders.dataframe_loader import prepare_dataframe
12+
>>>
13+
>>> df, feature_names, class_values, numeric_columns, \\
14+
... rdf, real_feature_names, features_map = prepare_dataframe(df, 'target')
15+
"""
16+
117
from lore_explainer.datamanager import prepare_dataset
218

319

420
def prepare_dataframe(df, class_field):
21+
"""
22+
Prepare a pandas DataFrame for use with XAI-Lib explainers.
23+
24+
This function wraps the LORE library's prepare_dataset function to
25+
process a DataFrame for use with various XAI-Lib explainers. It
26+
handles feature encoding, categorical variable mapping, and other
27+
preprocessing steps.
28+
29+
Args:
30+
df (pd.DataFrame): Input DataFrame containing features and target.
31+
class_field (str): Name of the target/class column in the DataFrame.
32+
33+
Returns:
34+
tuple: A tuple containing:
35+
- df: Processed DataFrame
36+
- feature_names: List of feature column names
37+
- class_values: List of unique class values
38+
- numeric_columns: List of numeric column names
39+
- rdf: Reconstructed DataFrame with original encoding
40+
- real_feature_names: Original feature names before encoding
41+
- features_map: Mapping of encoded to original features
42+
43+
Example:
44+
>>> import pandas as pd
45+
>>> df = pd.DataFrame({
46+
... 'age': [25, 30, 35],
47+
... 'income': [50000, 60000, 70000],
48+
... 'approved': [0, 1, 1]
49+
... })
50+
>>> result = prepare_dataframe(df, 'approved')
51+
>>> df_processed, feature_names, class_values, *rest = result
52+
"""
553
return prepare_dataset(df, class_field)

0 commit comments

Comments
 (0)