OmniXAI Documentation

OmniXAI is structured into five core subpackages that cover the machine learning lifecycle for explainability:

1. omnixai.data: Data representation. Provides classes for tabular, image, text, and timeseries data. These classes can be constructed from common formats like numpy arrays, pandas DataFrames, Pillow images, or strings.
2. omnixai.preprocessing: Feature engineering and transformation. Includes modules for categorical encoding, normalization, and scaling. For tabular data, omnixai.preprocessing.tabular.TabularTransform is the primary tool for preparing raw data for models.
3. omnixai.explainers: The core engine. Contains various explainer groups (data exploration, prediction metrics, and domain-specific explainers for tabular, vision, NLP, etc.).
4. omnixai.explanations: Result containers. Stores the output of explainers (e.g., feature_importance) and provides built-in visualization methods like plot (Matplotlib), plotly_plot (Dash), and ipython_plot (IPython).
5. omnixai.visualization: A GUI dashboard built with Plotly Dash for exploring both global and local explanations.

OmniXAI uses a factory pattern to provide a simplified interface for generating explanations across different data modalities.

Core Abstractions

• Explainers: Use TabularExplainer, VisionExplainer, NLPExplainer, or TimeseriesExplainer to generate local and global explanations for your models. These act as factories for individual algorithms like SHAP, LIME, or Grad-CAM.
• Analyzers: Use DataAnalyzer for feature analysis and PredictionAnalyzer for analyzing model prediction results and performance metrics.
• Dashboard: A visualization tool (built on Dash) that consumes explanations from explainers and metrics from analyzers to provide an interactive UI for model inspection and "what-if" analysis.

Requirements for Explanations

To generate explanations, you must specify:

1. The ML model: A scikit-learn, TensorFlow, or PyTorch model, or a black-box prediction function.
2. The pre-processing function: A function that converts raw input (e.g., a Tabular instance) into the format the model expects.
3. The post-processing function (optional): A function to convert model outputs (e.g., logits) into a user-friendly format like class probabilities.
4. The explainers to apply: A list of algorithm names (e.g., ["lime", "shap"]).

To generate explanations using OmniXAI, you need to provide four core components to an explainer (like TabularExplainer):

1. The ML model to explain: This can be a scikit-learn, TensorFlow, or PyTorch model, or any black-box prediction function.
2. The pre-processing function: A function that converts raw data (e.g., a Tabular instance) into the format required by the model.
3. The post-processing function (optional): A function to convert model outputs into a user-specific form, such as class probabilities. The output must be a numpy array.
4. The explainers to apply: A list of specific algorithms to use, such as SHAP, LIME, MACE, or PDP (Partial Dependence Plot).

Depending on the task, you should use the appropriate explainer class:

• Tabular data: omnixai.explainers.tabular.TabularExplainer
• Vision data: omnixai.explainers.vision.VisionExplainer
• NLP data: omnixai.explainers.nlp.NLPExplainer
• Time series data: omnixai.explainers.timeseries.TimeseriesExplainer

To add a new explanation method to OmniXAI, follow these steps:

1. Identify Task and Type: Choose a task type (tabular, vision, nlp, or timeseries) and an explainer type (model-agnostic, model-specific, or counterfactual).
2. Create the Class: Inherit from omnixai.explainers.base.ExplainerBase.
   • For model-agnostic explainers, use __init__(self, predict_function, mode, **kwargs). predict_function takes raw features and returns model outputs.
   • For model-specific explainers, use __init__(self, model, preprocess_function, postprocess_function, mode, **kwargs). postprocess_function is optional.
3. Define Metadata:
   • Add explanation_type (string: "local", "global", or "both").
   • Add alias (list of strings) to register the name used in the high-level Explainer classes.
4. Implement Logic:
   • Implement explain(self, **kwargs) for local explanations.
   • Implement explain_global(self, X, **kwargs) for global explanations, where X is a Tabular, Image, Text, or Timeseries instance.
5. Return Explanations: The explain method must return an instance of a class inheriting from omnixai.explanations.base.ExplanationBase.
6. Register: Import the class into the __init__.py of the appropriate package (omnixai.explainers.tabular, vision, nlp, or timeseries).

OmniXAI provides built-in interfaces for BentoML to facilitate model serving. You can deploy an explainer by saving it to the BentoML local model store and initializing a service that exposes /predict and /explain endpoints.

1. Save the Explainer

Use save_model from omnixai.deployment.bentoml.omnixai to persist your TabularExplainer (or other explainer types) to the BentoML store.

2. Initialize the Service

Create a service file (e.g., service.py) using init_service from omnixai.deployment.bentoml.omnixai. This function automatically configures the API endpoints for predictions and explanations.

3. Run the Server

Use the BentoML CLI to serve your service locally for testing.

# 1. Save the model
from omnixai.explainers.tabular import TabularExplainer
from omnixai.deployment.bentoml.omnixai import save_model

explainer = TabularExplainer(
  explainers=["lime", "shap", "mace", "pdp", "ale"],
  mode="classification",
  data=train_data,
  model=model,
  preprocess=lambda z: transformer.transform(z),
  params={
     "mace": {"ignored_features": ["Sex", "Race", "Relationship", "Capital Loss"]}
  }
)
save_model("tabular_explainer", explainer)

# 2. service.py
from omnixai.deployment.bentoml.omnixai import init_service

svc = init_service(
    model_tag="tabular_explainer:latest",
    task_type="tabular",
    service_name="tabular_explainer"
)

# 3. Start the server
bentoml serve service:svc --reload

To extend OmniXAI with a new explanation method, follow these steps:

1. Define Task and Explainer Types:
   • Task Type: Choose from tabular, vision, nlp, or timeseries.
   • Explainer Type: Choose from model-agnostic, model-specific, or counterfactual.
2. File Placement: Create a new Python script in the appropriate directory (e.g., explainers/tabular/agnostic/ for a model-agnostic tabular explainer).
3. Implement the Explainer Class: Inherit from omnixai.explainers.base.ExplainerBase. Use one of the following constructor patterns:
   • Model-Agnostic: __init__(self, predict_function, mode, **kwargs)
     • predict_function: A function that takes raw input features and returns model outputs.
     • mode: The task type (e.g., classification, regression).
   • Model-Specific: __init__(self, model, preprocess_function, postprocess_function, mode, **kwargs)
     • model: The ML model to explain.
     • preprocess_function: Converts raw features into model inputs (e.g., image resizing).
     • postprocess_function: (Optional) Converts model logits into class probabilities.
     • mode: The task type (e.g., classification, regression).
4. Set Class Attributes:
   • explanation_type (string): Set to local, global, or both.
   • alias (list): A list of strings specifying the names used to call the explainer.
5. Implement Explanation Logic:
   • For local explanations: Implement explain(self, **kwargs).
   • For global explanations: Implement explain_global(self, X, **kwargs), where X is an instance of Tabular, Image, Text, or Timeseries.
6. Register the Explainer: Import the class in the __init__.py of the corresponding package (omnixai.explainers.tabular, omnixai.explainers.vision, omnixai.explainers.nlp, or omnixai.explainers.timeseries).

Once registered, the explainer can be accessed via the relevant high-level explainer class (e.g., TabularExplainer) by providing one of the names defined in alias.