FDFI Documentation

License: MIT Python 3.8+

FDFI (Flow-Disentangled Feature Importance) is a Python library for computing feature importance using disentangled methods, inspired by SHAP. This package implements both OT-based DFI and flow-based FDFI methods.

Key Features

  • Three explainer variants, all model-agnostic and sharing one API: OTExplainer (Gaussian OT — the fast default), EOTExplainer (entropic OT — non-Gaussian and mixed-type data), and FlowExplainer (normalizing flows — complex non-linear dependence)

  • Cross-fitted inference: Crossfitting wraps any variant for valid standard errors at small sample sizes

  • Shared Diagnostics: Latent independence (dCor) and distribution fidelity (MMD) checks for OT/EOT/Flow

  • Visualization: Summary, waterfall, force, dependence, CI, and diagnostics plots

  • Statistical Inference: Confidence intervals, one-sided tests, FDR correction, and group-level importance

  • Easy to Use: Simple API; background data replaces the predict_proba baseline

  • Extensible: Built with modularity for future enhancements

Note

Recent additions include configurable loss functions (any regression or binary-classification loss, or a custom callable) and one-sided confidence intervals in confidence_interval_plot(). See the Changelog for the full history and Confidence Intervals and Statistical Inference for worked examples.

Quick Example

import numpy as np
from fdfi.explainers import OTExplainer
from fdfi.plots import summary_bar

rng = np.random.default_rng(0)

def model(X):
    return X.sum(axis=1)

X_background = rng.standard_normal((100, 10))
explainer = OTExplainer(model, data=X_background, nsamples=50)

X_test = rng.standard_normal((50, 10))
results = explainer(X_test)

# Confidence intervals (one-sided, with FDR correction)
ci = explainer.conf_int(alpha=0.05, alternative="greater", multitest_method="fdr_bh")

feature_names = [f"X{i}" for i in range(X_background.shape[1])]
summary_bar(results["phi_X"], results["se_X"], feature_names, show=False)

Installation

git clone https://github.com/jinhongdu-lab/FDFI.git
cd FDFI
pip install -e .

# With optional dependencies
pip install -e ".[flow]"    # For flow matching models
pip install -e ".[dev]"     # For development

User Guide

Tutorials

Case Studies

API Reference

Development

Indices and tables