Narrative Template Customization

This guide explains how to customize the narrative templates used by the to_narrative() method in Calibrated Explanations.

Overview

Narrative templates define how explanations are rendered into human-readable text. They use a YAML or JSON format with placeholders that get filled with actual values.

Template Structure

Templates are organized hierarchically:

narrative_templates:
  <problem_type>:
    <explanation_type>:
      <expertise_level>: |
        Template text with {placeholders}...

Problem Types

  • binary_classification - Two-class classification

  • multiclass_classification - Multi-class classification

  • regression - Standard regression with intervals

  • probabilistic_regression - Regression with probability thresholds

Explanation Types

  • factual - Explains why the current prediction was made

  • alternative - Shows how to change the prediction

Expertise Levels

  • beginner - Simple language, minimal details

  • intermediate - Includes weights and prediction intervals

  • advanced - Full weight intervals and explanation envelopes

Available Placeholders

Global Context

Placeholder

Description

{label}

Predicted class label

{positive_label}

Positive class label (binary classification)

{calibrated_pred}

Calibrated prediction value

{pred_interval_lower}

Lower bound of prediction interval

{pred_interval_upper}

Upper bound of prediction interval

{threshold}

Threshold value (scalar)

{threshold_condition}

Full threshold condition (e.g., “target <= 150” or “100 < target <= 200”)

{threshold_low}

Lower threshold (for tuple thresholds)

{threshold_high}

Upper threshold (for tuple thresholds)

{runner_up_class}

Second-most likely class (multiclass)

{margin_value}

Margin to runner-up class

{interval_width}

Width of prediction interval

Per-Feature Placeholders

Placeholder

Description

{feature_name}

Name of the feature

{feature_actual_value}

Actual value of the feature

{condition}

Feature condition (e.g., “> 5.0”)

{feature_weight}

Feature’s contribution weight

{feature_weight_low}

Lower bound of weight interval

{feature_weight_high}

Upper bound of weight interval

{predict}

Predicted value for this rule

{predict_low}

Lower bound of prediction

{predict_high}

Upper bound of prediction

Conjunctive Rules

When add_conjunctions() is called on explanations, multiple feature conditions are combined. In narratives, these appear with a configurable separator:

# Default: " AND "
explanations.to_narrative(conjunction_separator=" AND ")
# Result: "(Glucose > 120 AND BMI > 28)"

# Custom separator
explanations.to_narrative(conjunction_separator=" & ")
# Result: "(Glucose > 120 & BMI > 28)"

Conjunctive rules are automatically wrapped in parentheses for clarity.

Weight Alignment

By default, narratives vertically align the weight columns for better readability:

# With alignment (default)
explanations.to_narrative(align_weights=True)
# Result:
# * Glucose (145.0) > 120      — weight ≈ 0.150
# * BMI (28.5) > 25            — weight ≈ 0.082
# * Age (55) > 40              — weight ≈ 0.045

# Without alignment
explanations.to_narrative(align_weights=False)
# Result:
# * Glucose (145.0) > 120 — weight ≈ 0.150
# * BMI (28.5) > 25 — weight ≈ 0.082
# * Age (55) > 40 — weight ≈ 0.045

Interval Probabilistic Regression

For probabilistic regression with interval thresholds, use tuple thresholds:

# Scalar threshold: P(y <= 150)
explanations = explainer.explain_factual(x_test, threshold=150)

# Interval threshold: P(100 < y <= 200)
explanations = explainer.explain_factual(x_test, threshold=(100, 200))

The {threshold_condition} placeholder automatically adapts:

  • Scalar: “target <= 150.000”

  • Interval: “100.000 < target <= 200.000”

Output Formats

The to_narrative() method supports multiple output formats:

Format

Description

"dataframe"

pandas DataFrame (default)

"text"

Plain text with headers

"html"

HTML table

"dict"

List of dictionaries

"markdown"

Markdown with code blocks

Creating Custom Templates

  1. Copy the default template from src/calibrated_explanations/templates/explain_template.json

  2. Modify the templates as needed

  3. Pass your template path to to_narrative():

narratives = explanations.to_narrative(
    template_path="my_template.yaml",
    expertise_level="advanced",
    output_format="text"
)

Example Custom Template

narrative_templates:
  binary_classification:
    factual:
      beginner: |
        The model predicts: {label}
        Confidence: {calibrated_pred}

        Main reasons:
        * {feature_name} = {feature_actual_value}

Best Practices

  1. Use appropriate expertise levels: Beginners need simple explanations; experts want uncertainty details.

  2. Test with real data: Verify placeholders are filled correctly for your use case.

  3. Keep templates readable: Use line breaks and clear structure.

  4. Handle edge cases: Consider what happens when there are few features or missing values.

See Also