Workflow:Interpretml Interpret EBM Model Export
| Knowledge Sources | |
|---|---|
| Domains | Machine_Learning, Interpretability, Model_Deployment |
| Last Updated | 2026-02-07 12:00 GMT |
Overview
End-to-end process for exporting a fitted Explainable Boosting Machine to portable formats (JSON and Excel) for model sharing, auditing, deployment, and domain expert review.
Description
This workflow covers exporting a trained EBM model into human-readable and machine-readable formats. The JSON export produces a structured, serializable representation of the complete model including all shape functions, bin definitions, and metadata, enabling model reconstruction in other environments. The Excel export produces a richly formatted workbook with interactive charts, shape function plots, and an evaluation worksheet that allows domain experts to manually explore model behavior by inputting feature values and seeing predicted scores, all without any code.
Key outputs:
- JSON: A portable, version-controlled model representation
- Excel: An interactive workbook with charts and a manual evaluation sheet
Scope:
- Covers JSON serialization at multiple detail levels (minimal to full)
- Covers Excel workbook generation with overview, variables, shape plots, and evaluation
- Supports roundtrip: JSON can be loaded back into a functional EBM object
Strategy:
- JSON uses nested dictionaries with special handling for NaN/Infinity values
- Excel uses xlsxwriter to create formatted workbooks with embedded charts
- Multiple detail levels allow trading file size for completeness
Usage
Execute this workflow when you need to share a trained EBM model with stakeholders, deploy it to a production system, archive it for regulatory compliance, or enable domain expert review. Use JSON export for programmatic consumption, version control, or model reconstruction. Use Excel export when non-technical reviewers need to inspect and interact with the model, or when auditors require a self-contained document showing model behavior.
Execution Steps
Step 1: Prepare the Fitted Model
Ensure the EBM model has been trained and is in a fitted state. Verify that all term scores, bin definitions, feature metadata, and intercepts are available. The model must have completed the full training pipeline including aggregation and postprocessing.
Key considerations:
- The model must be fitted (check_is_fitted validation)
- All term_scores, bins, feature metadata must be populated
- For JSON export: the model's entire state is serialized
- For Excel export: term scores and bin structures are needed for charts
Step 2: Select Export Format and Detail Level
Choose between JSON and Excel export based on the intended use. For JSON, select the appropriate detail level that controls how much information is included.
JSON detail levels:
- minimal: Core shape functions and feature definitions only. Suitable for lightweight deployment.
- interpretable: Adds standard deviations, bin weights, and histogram data. Suitable for visualization reconstruction.
- mergeable: Adds bagged scores needed for merge_ebms operations. Suitable for federated learning workflows.
- all: Complete model state including implementation parameters. Suitable for full model reconstruction.
Excel format:
- Single detail level producing a complete interactive workbook
- No detail level selection needed
Step 3: Execute JSON Export
Convert the fitted EBM model into a JSON-serializable dictionary structure. The export traverses all model components: output configuration (task type, classes, link function), feature definitions (names, types, bin boundaries), and term data (scores, weights, standard deviations).
What happens:
- Model metadata is extracted: task type, number of classes, link function
- Feature definitions are serialized: names, types, categories or cut points, bounds
- Term structures are serialized: which features each term uses, score tensors, bin weights
- Special float values are handled: NaN becomes "nan", infinity becomes "+inf"/"-inf"
- For mergeable/all levels: bagged per-bag scores are included
- For all level: implementation parameters (learning rate, max rounds, etc.) are preserved
- The output is a nested dictionary ready for json.dumps()
Step 4: Execute Excel Export
Generate a richly formatted Excel workbook with multiple worksheets containing model documentation, variable summaries, shape function charts, and an interactive evaluation tool.
Generated worksheets:
- Overview: Model title, description, table of contents with hyperlinks to other sheets
- Variables: Feature summary table with min, max, and absolute max contribution values, plus an amplitude comparison chart
- VariablesData: Hidden data sheet with computed values for shape plots
- ShapePlots: Per-feature shape function charts (scatter for continuous, column for categorical, heatmap for interactions)
- Evaluation: Interactive worksheet where users can enter feature values and see: input variable scores, baseline score, total model score, predicted probability, and a waterfall chart showing the contribution breakdown
Key considerations:
- Charts are embedded and interactive within the Excel file
- The evaluation sheet uses Excel formulas to compute predictions
- Domain experts can modify input values and see predictions update
- The waterfall chart visually decomposes the prediction into feature contributions
Step 5: Save and Distribute
Write the exported model to disk and distribute to the intended audience. JSON files can be committed to version control or served via an API. Excel files can be emailed or shared via document management systems.
Key considerations:
- JSON files should use .json extension for proper tooling support
- JSON can be loaded back with UNTESTED_from_jsonable() for model reconstruction
- Excel files are self-contained and require no additional software beyond a spreadsheet application
- Version the exports alongside the training code for reproducibility