ml-drift-detection 📈🔍

A Streamlit dashboard for visual monitoring of machine learning data drift and model performance metrics.

Overview

ml-drift-detection provides an instant, interactive dashboard to compare two datasets (e.g., baseline/reference vs. new/production data) for feature drift, label drift, and concept drift, alongside the latest model performance metrics.

• Visualizes drift in both numeric and categorical features
• Highlights changes in model evaluation metrics
• Supports light and dark dashboard themes
• Usable as a command-line tool or Python library

Installation

pip install ml-drift-detection

Requires Python ≥ 3.9.

Usage

1. Command-Line Interface (CLI)

Run the dashboard using Streamlit, providing your datasets and settings as arguments:

streamlit run -m ml_drift_detection.cli -- \
  --prod-data=PATH_TO_REFERENCE_DATA \
  --new-data=PATH_TO_NEW_DATA \
  --numeric-cols=NUMERIC_COLUMN_NAMES \
  --categorical-cols=CATEGORICAL_COLUMN_NAMES \
  --target-variable=TARGET_COLUMN_NAME \
  --target-type=TARGET_TYPE \
  --prod-metrics=PRODUCTION_METRICS \
  --new-metrics=NEW_METRICS

Argument descriptions

Optional arguments

Default gauge colour bands

Unless customized, all metrics use these relative change bands:

Custom bands can be provided as JSON/Python lists (see documentation).

2. Library Usage

You can also use the dashboard as part of a Python workflow:

import pandas as pd
from ml_drift_detection import dashboard_main

reference_df = pd.read_csv("PATH_TO_REFERENCE_DATA")
current_df = pd.read_csv("PATH_TO_NEW_DATA")

dashboard_main(
    prod_df=reference_df,
    new_df=current_df,
    numeric_cols=[...],          # List of your numeric feature names
    categorical_cols=[...],      # List of your categorical feature names
    target_variable="...",       # Your target column name
    target_type="...",           # "categorical" or "continuous"
    prod_metrics={...},          # Dict of production metrics
    new_metrics={...},           # Dict of new metrics
    # Optional: background_color, metric_x_threshold_steps
)

All arguments follow the same meaning as in the CLI.

Public API

Example

Below is a sample CLI invocation and Python snippet using generic variable names—replace the file names and column names with your actual project details:

CLI Example

streamlit run -m ml_drift_detection.cli -- \
  --prod-data=reference_data.csv \
  --new-data=current_data.csv \
  --numeric-cols=feature1,feature2,feature3 \
  --categorical-cols=category1,category2 \
  --target-variable=target_column \
  --target-type=categorical \
  --prod-metrics=metricA=0.91,metricB=0.88 \
  --new-metrics=metricA=0.83,metricB=0.79 \
  --background-color="#0E1117"

streamlit run "C:\Python\Lib\site-packages\ml_drift_detection\cli.py" -- `
  --prod-data="C:\data\reference_data.csv" `
  --new-data="C:\data\current_data.csv" `
  --numeric-cols="feature1,feature2,feature3" `
  --categorical-cols="category1,category2" `
  --target-variable="target_column" `
  --target-type="categorical" `
  --prod-metrics="metricA=0.91,metricB=0.88" `
  --new-metrics="metricA=0.83,metricB=0.79"

Library Example

import pandas as pd
from ml_drift_detection import dashboard_main

reference_df = pd.read_csv("reference_data.csv")
current_df = pd.read_csv("current_data.csv")

dashboard_main(
    prod_df=reference_df,
    new_df=current_df,
    numeric_cols=["feature1", "feature2", "feature3"],
    categorical_cols=["category1", "category2"],
    target_variable="target_column",
    target_type="categorical",
    prod_metrics={"metricA": 0.91, "metricB": 0.88},
    new_metrics={"metricA": 0.83, "metricB": 0.79},
    background_color="#0E1117",        # optional
)

Note: Use your actual data file paths, feature column names, and model metric names. The CLI and API accept any well-formed data file and column configuration compatible with your use case.

Contributing

Clone the repo:

git clone https://github.com/knowusuboaky/ml-drift-detection

Install dev dependencies:

pip install -e ".[dev,test]"

Run code quality checks:

pre-commit install

Test:

pytest

Pull requests and feature requests are welcome! Please open an issue first to discuss any major changes.

License

MIT © Kwadwo Daddy Nyame Owusu-Boakye