Prepare for v0.5.0 release

Signed-off-by: Abolfazl Shahbazi <abolfazl.shahbazi@intel.com>

.github/workflows/docs-test.yml

@@ -29,6 +29,6 @@ jobs:
     # make documentation
     - name: Make documentation
       shell: bash
-      working-directory: ./intel-xai-tools
+      working-directory: .
       continue-on-error: false
-      run: make html
+      run: make test-docs

.github/workflows/nb-test.yaml

@@ -40,6 +40,6 @@ jobs:
       - id: test
         name: Test Notebooks
         shell: bash
-        working-directory: intel-xai-tools
+        working-directory: . 
         continue-on-error: false
         run: make test-notebook

.github/workflows/unit-test.yaml

@@ -34,6 +34,6 @@ jobs:
         run: pip install virtualenv
       - name: Run Unit Test
         shell: bash
-        working-directory: ./intel-xai-tools
+        working-directory: .
         continue-on-error: false
         run: make test

.gitignore

@@ -97,6 +97,12 @@ target/
 # Jupyter Notebook
 .ipynb_checkpoints
 
+# Artifacts generated by notebooks
+notebooks/model_card_gen/*.pt
+notebooks/model_card_gen/*.html
+notebooks/model_card_gen/*.proto
+notebooks/model_card_gen/compas/
+
 # IPython
 profile_default/
 ipython_config.py

MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include explainer *
+recursive-include model_card_gen *

Makefile

@@ -0,0 +1,86 @@
+#
+# Copyright (c) 2022 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+ACTIVATE_TF = "intel_tf/bin/activate"
+ACTIVATE_PYT = "intel_pyt/bin/activate"
+ACTIVATE_TEST = "test_env/bin/activate"
+ACTIVATE_DOCS = $(ACTIVATE_TEST)
+ACTIVATE_NOTEBOOK = $(ACTIVATE_TEST)
+
+LISTEN_IP ?= 127.0.0.1
+LISTEN_PORT ?= 9090
+DOCS_DIR ?= docs
+
+venv-test:
+	@echo "Creating a virtualenv test_env..."
+	@test -d test_env || virtualenv -p python test_env
+
+	@echo "Building the XAI API in test_env env..."
+	@. $(ACTIVATE_TEST) && pip install --editable .[test]
+
+# TODO: running all tests in one pytest session randomly causes torch test to hang at last epoch
+test-torch: venv-test
+	@echo "Testing the API..."
+	@. $(ACTIVATE_TEST) && PYTHONPATH="$(CURDIR)/model_card_gen/tests" pytest -s model_card_gen/tests/test_end_to_end_torch.py
+
+test-mcg: test-torch
+	@echo "Testing the API..."
+	@. $(ACTIVATE_TEST) && PYTHONPATH="$(CURDIR)/model_card_gen/tests" pytest -s -k "not torch"
+
+install:
+	@pip install --editable .
+
+xai-whl:
+	@python setup.py bdist_wheel
+
+clean:
+	@rm -rf build dist intel_xai_tools.egg-info
+	@rm -rf test_env
+
+test-explainer: venv-test 
+	@. $(ACTIVATE_TEST) && pytest explainer/tests
+
+test: clean test-mcg test-explainer
+
+venv-docs: venv-test ${DOCS_DIR}/requirements-docs.txt
+	@echo "Installing docs dependencies..."
+	@. $(ACTIVATE_DOCS) && pip install -r ${DOCS_DIR}/requirements-docs.txt
+
+html: venv-docs
+	@echo "Building Sphinx documentation..."
+	@. $(ACTIVATE_DOCS) && $(MAKE) -C ${DOCS_DIR} clean html
+
+test-docs: html
+	@echo "Testing Sphinx documentation..."
+	@. $(ACTIVATE_DOCS) && $(MAKE) -C ${DOCS_DIR} doctest
+
+test-notebook: venv-test
+	@echo "Testing Jupyter notebooks..."
+	@. $(ACTIVATE_NOTEBOOK) && \
+	bash run_notebooks.sh $(CURDIR)/notebooks/explainer/imagenet_with_cam/ExplainingImageClassification.ipynb
+
+dist: venv-test
+	@echo "Create binary wheel..."
+	@. $(ACTIVATE_DOCS) && python setup.py bdist_wheel
+
+check-dist: dist
+	@echo "Testing the wheel..."
+	@. $(ACTIVATE_DOCS) && \
+	pip install twine && \
+	python setup.py bdist_wheel && \
+	twine check dist/*

README.md

@@ -2,59 +2,97 @@
 
 This repository provides tools for data scientists and MLOps engineers that have requirements specific to AI model interpretability.
 
-## Features
-| Core Feature | Description | 
-|----------|-----------|
-| [Model Card Generator](intel-xai-tools/model_card_gen) |  **Allows users to create interactive HTML reports containing model performance and fairness metrics.** |
-|[Explainer](intel-xai-tools/explainer) | **Allows users to run post-hoc model distillation and visualization methods to examine predictive behavior for both TensorFlow and PyTorch models via a simple Python API including the following modules:** <li> [Attributions](intel-xai-tools/explainer/attributions/): visualize negative and positive attributions of tabular features, pixels, and word tokens for predictions <li> [CAM](intel-xai-tools/explainer/cam/): create heatmaps for CNN image classifications using gradient-weight class activation CAM mapping <li> [Metrics](intel-xai-tools/explainer/metrics/): Gain insight into models with the measurements and visualizations needed during the machine learning workflow |
-
-## Build and Install
-Requirements:
-* Linux system (or WSL2 on Windows)
-* git
-* required python version: 3.9
-* `apt-get install build-essential python3-dev`
-
-### Basic Installation:
-```
-pip install intel-xai
-```
-### Advanced/Developer Installation:
-1. Clone this repo and navigate to the repo directory:
-   ```
-   git clone https://github.com/IntelAI/intel-xai-tools.git
+## Overview
 
-   cd intel-xai-tools
-   ```
-2. Create and activate a Python3.9 virtual environment using `virtualenv`:
+The Intel Explainable AI Tools are designed to help users detect and mitigate against issues of fairness and interpretability, while running best on Intel hardware.
+There are two Python* components in the repository:
+
+* [Model Card Generator](model_card_gen)
+  * Creates interactive HTML reports containing model performance and fairness metrics
+* [Explainer](explainer)
+  * Runs post-hoc model distillation and visualization methods to examine predictive behavior for both TensorFlow* and PyTorch* models via a simple Python API including the following modules:
+    * [Attributions](explainer/attributions/): Visualize negative and positive attributions of tabular features, pixels, and word tokens for predictions
+    * [CAM (Class Activation Mapping)](explainer/cam/): Create heatmaps for CNN image classifications using gradient-weight class activation CAM mapping
+    * [Metrics](explainer/metrics/): Gain insight into models with the measurements and visualizations needed during the machine learning workflow
+
+## Get Started
+
+### Requirements
+* Linux system or WSL2 on Windows (validated on Ubuntu* 20.04/22.04 LTS)
+* Python 3.9
+* Install required OS packages with `apt-get install build-essential python3-dev`
+* git (only required for the "Developer Installation")
+
+### Create and activate a Python3 virtual environment
+We encourage you to use a python virtual environment (virtualenv or conda) for consistent package management.
+There are two ways to do this:
+
+a. Using `virtualenv`:
    ```
    python3.9 -m virtualenv xai_env
    source xai_env/bin/activate
    ```
 
-   Or `conda`:
+b. Or `conda`:
    ```
    conda create --name xai_env python=3.9
    conda activate xai_env
    ```
-3. Install this tool with 
+
+### Basic Installation
+```
+pip install intel-xai
+```
+### Developer Installation
+Use these instructions to install the Intel Explainable AI Tools with a clone of the
+GitHub repository. This can be done instead of the basic pip install, if you plan
+on making code changes.
+
+1. Clone this repo and navigate to the repo directory:
+   ```
+   git clone https://github.com/IntelAI/intel-xai-tools.git
+
+   cd intel-xai-tools
+   ```
+2. Install the Intel Explainable AI Tools using the following command:
    ```
    make install
    ```
 
+### Additional Feature-Specific Steps
+Notebooks may require additional dependencies listed in their associated documentation.
+
+### Verify Installation
+
+Verify that your installation was successful by using the following commands, which display the Explainer and Model Card Generator versions:
+```
+python -c "from explainer import version; print(version.__version__)"
+python -c "from model_card_gen import version; print(version.__version__)"
+```
+
 ## Running Notebooks
 
-Run [example notebooks](notebooks/) that show how to use the explainer and model card generator API in various ML domains and use cases. Notebooks may require additional dependencies listed in their associated README's.
+The following links have Jupyter* notebooks showing how to use the Explainer and Model Card Generator APIs in various ML domains and use cases:
+* [Model Card Generator Notebooks](notebooks#model-card-generator-tutorial-notebooks)
+* [Explainer Notebooks](notebooks#explainer-tutorial-notebooks)
+
+## Support
+
+The Intel Explainable AI Tools team tracks bugs and enhancement requests using
+[GitHub issues](https://github.com/intelai/intel-xai-tools/issues). Before submitting a
+suggestion or bug report, search the existing GitHub issues to see if your issue has already been reported.
+
+*Other names and brands may be claimed as the property of others. [Trademarks](http://www.intel.com/content/www/us/en/legal/trademarks.html)
 
-#### DISCLAIMER: ####
+#### DISCLAIMER
 These scripts are not intended for benchmarking Intel platforms. For any performance and/or benchmarking information on specific Intel platforms, visit https://www.intel.ai/blog.
 
 Intel is committed to the respect of human rights and avoiding complicity in human rights abuses, a policy reflected in the Intel Global Human Rights Principles. Accordingly, by accessing the Intel material on this platform you agree that you will not use the material in a product or application that causes or contributes to a violation of an internationally recognized human right.
 
-#### License: ####
+#### License
 Intel® Explainable AI Tools is licensed under Apache License Version 2.0.
 
-#### Datasets: ####
+#### Datasets
 To the extent that any public datasets are referenced by Intel or accessed using tools or code on this site those datasets are provided by the third party indicated as the data source. Intel does not create the data, or datasets, and does not warrant their accuracy or quality. By accessing the public dataset(s) you agree to the terms associated with those datasets and that your use complies with the applicable license. [DATASETS](DATASETS.md)
 
 Intel expressly disclaims the accuracy, adequacy, or completeness of any public datasets, and is not liable for any errors, omissions, or defects in the data, or for any reliance on the data.  Intel is not liable for any liability or damages relating to your use of public datasets.

docs/.gitignore

@@ -1,2 +1,3 @@
 .ipynb_checkpoints
 _build
+markdown

docs/Makefile

@@ -36,6 +36,7 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	./build.sh $@
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 LISTEN_IP ?= 127.0.0.1

docs/README.MD

@@ -2,7 +2,7 @@
 
 ## Sphinx Documentation
 
-Install `intel-xai` and it's dependencies for developers as described [here](/README.md##build-and-install)
+Install `intel-xai-tools` and its dependencies for developers as described [here](/README.md#developer-installation).
 ```bash
 # Run these commands from intel-xai-tools project folder
 python3 -m virtualenv xai_env

docs/build.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# Copyright (c) 2023 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+COMMAND=${1}
+
+# Temp directory within docs
+TEMP_DIR="markdown"
+
+if [[ ${COMMAND} == "clean" ]]; then
+    rm -rf ${TEMP_DIR}
+elif [[ ${COMMAND} == "html" ]]; then
+    # Create a temp directory for markdown files that are just used for sphinx docs
+    mkdir -p ${TEMP_DIR}
+
+    # This script takes sections out of the main README.md to create smaller .md files that are used for pages
+    # in the sphinx doc table of contents (like Overview, Installation, Legal Information).
+    # If heading name changes are made in the main README.md, they will need to be updated here too because the sed
+    # commands are grabbing the text between two headers.
+
+    # We don't want to mess with the original README.md, so create a copy of it before we start editing
+    cp ../README.md ${TEMP_DIR}/Welcome.md
+
+    # Convert links to go to sphinx docs
+    sed -i 's#DATASETS.md#<datasets>#g' ${TEMP_DIR}/Welcome.md
+    sed -i 's#notebooks\#model-card-generator-tutorial-notebooks#<notebooks>#g' ${TEMP_DIR}/Welcome.md
+    sed -i 's#notebooks\#explainer-tutorial-notebooks#<notebooks>#g' ${TEMP_DIR}/Welcome.md
+
+    # Create an Overview doc
+    sed -n '/^ *## Overview *$/,/^ *## Get Started *$/p' ${TEMP_DIR}/Welcome.md > ${TEMP_DIR}/Overview.md
+    # Change the first instance of Intel to include the registered trademark symbol
+    sed -i '0,/Intel/{s/Intel/Intel®/}' ${TEMP_DIR}/Overview.md
+    sed -i '$d' ${TEMP_DIR}/Overview.md
+    echo "*Other names and brands may be claimed as the property of others. [Trademarks](http://www.intel.com/content/www/us/en/legal/trademarks.html)" >> ${TEMP_DIR}/Overview.md
+
+    # Create an Installation doc (including requirements)
+    echo "## Installation " > ${TEMP_DIR}/Install.md
+    sed -n '/^ *### Requirements *$/,/^ *### Create and activate a Python3 virtual environment *$/p' ${TEMP_DIR}/Welcome.md >> ${TEMP_DIR}/Install.md
+    sed -i '$d' ${TEMP_DIR}/Install.md
+    sed -i 's/### Requirements/### Software Requirements/g' ${TEMP_DIR}/Install.md
+    sed -n '/^ *### Create and activate a Python3 virtual environment *$/,/^ *## Running Notebooks *$/p' ${TEMP_DIR}/Welcome.md >> ${TEMP_DIR}/Install.md
+    sed -i '$d' ${TEMP_DIR}/Install.md
+    # Change the first instance of the tool name to include the registered trademark symbol
+    sed -i '0,/Intel Transfer Learning Tool/{s/Intel Transfer Learning Tool/Intel® Transfer Learning Tool/}' ${TEMP_DIR}/Install.md
+    echo "*Other names and brands may be claimed as the property of others. [Trademarks](http://www.intel.com/content/www/us/en/legal/trademarks.html)" >> ${TEMP_DIR}/Install.md
+
+    # Create a Legal Information doc
+    echo "# Legal Information " > ${TEMP_DIR}/Legal.md
+    sed -n '/#### DISCLAIMER/,$p' ${TEMP_DIR}/Welcome.md >> ${TEMP_DIR}/Legal.md
+    sed -i 's/#### DISCLAIMER/## Disclaimer/g' ${TEMP_DIR}/Legal.md
+    sed -i 's/#### License/## License/g' ${TEMP_DIR}/Legal.md
+    sed -i 's/#### Datasets/## Datasets/g' ${TEMP_DIR}/Legal.md
+    # Change the first instance of Intel to include the registered trademark symbol
+    sed -i '0,/Intel/{s/Intel/Intel®/}' ${TEMP_DIR}/Legal.md
+fi