Generate narratives with to_narrative

Use explanations.to_narrative() to turn calibrated explanations into narrative text, HTML, or data structures without changing your modeling flow.

Basic usage

narratives = explanations.to_narrative(
    template_path="exp.yaml",
    expertise_level=("beginner", "advanced"),
    output_format="dataframe",
)

Output formats

1. DataFrame (default) — returns a pandas DataFrame

df_narratives = explanations.to_narrative(
    template_path="exp.yaml",
    expertise_level=("beginner", "advanced"),
    output_format="dataframe",
)

2. Text — returns formatted text string

text_narratives = explanations.to_narrative(
    template_path="exp.yaml",
    expertise_level="beginner",
    output_format="text",
)

3. HTML — returns an HTML table

html_narratives = explanations.to_narrative(
    template_path="exp.yaml",
    expertise_level=("beginner", "intermediate", "advanced"),
    output_format="html",
)

4. Dictionary — returns a list of dictionaries

dict_narratives = explanations.to_narrative(
    template_path="exp.yaml",
    expertise_level="advanced",
    output_format="dict",
)

Expertise levels

Single level

beginner_only = explanations.to_narrative(
    expertise_level="beginner",
    output_format="text",
)

Multiple levels

all_levels = explanations.to_narrative(
    expertise_level=("beginner", "intermediate", "advanced"),
    output_format="dataframe",
)

Template path handling

If exp.yaml doesn’t exist, the method automatically falls back to explain_template.json.

narratives = explanations.to_narrative(
    template_path="exp.yaml",  # Will use default if not found
    expertise_level=("beginner", "advanced"),
    output_format="dataframe",
)

Use a custom template:

narratives = explanations.to_narrative(
    template_path="/path/to/custom_template.yaml",
    expertise_level=("beginner", "advanced"),
    output_format="dataframe",
)

Use the default template explicitly:

narratives = explanations.to_narrative(
    template_path="explain_template.json",
    expertise_level=("beginner", "advanced"),
    output_format="dataframe",
)

The to_narrative method provides a clean, intuitive API for generating narratives from calibrated explanations.