> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Visualizations

> How CRAFT Insights Agent generates interactive Plotly charts from query results to visualize data patterns and trends.

# Visualizations

The Data Insights solution generates interactive **Plotly** visualizations as part of the conversational analytics pipeline. When a user's question benefits from a visual answer, the Insights Agent automatically selects and generates the appropriate chart type.

## How Visualizations Are Generated

The Insights Agent determines when a visualization would enhance the answer and generates it as part of the agentic loop:

<Steps>
  <Step title="Question analysis">
    The Insights Agent evaluates whether the question implies a visual answer. Questions about trends, comparisons, distributions, or proportions typically trigger visualization.
  </Step>

  <Step title="Data retrieval">
    The Text2SQL Agent generates and executes a query to retrieve the data needed for the visualization.
  </Step>

  <Step title="Chart type selection">
    The LLM selects the most appropriate chart type based on the data shape, question intent, and number of dimensions:

    | Data Pattern        | Chart Type            |
    | ------------------- | --------------------- |
    | Trends over time    | Line chart            |
    | Category comparison | Bar chart             |
    | Part-to-whole       | Pie / Donut chart     |
    | Distribution        | Histogram             |
    | Correlation         | Scatter plot          |
    | Multi-dimensional   | Grouped / Stacked bar |
  </Step>

  <Step title="Code generation">
    The Insights Agent generates Python code using Plotly to create the visualization:

    ```python theme={null}
    import plotly.express as px

    fig = px.bar(
        df,
        x="product_category",
        y="revenue",
        title="Revenue by Product Category",
        color="region",
        barmode="group"
    )
    fig.update_layout(
        xaxis_title="Category",
        yaxis_title="Revenue ($)"
    )
    ```
  </Step>

  <Step title="Rendering and delivery">
    The chart is rendered and delivered as an artifact via the A2A protocol. The frontend renders it as an interactive Plotly chart with hover tooltips, zoom, and pan capabilities.
  </Step>
</Steps>

## Supported Chart Types

<Tabs>
  <Tab title="Standard Charts">
    | Chart           | When Used                     | Plotly Function  |
    | --------------- | ----------------------------- | ---------------- |
    | **Line**        | Time series, trends           | `px.line()`      |
    | **Bar**         | Category comparison           | `px.bar()`       |
    | **Pie / Donut** | Proportions (\< 8 categories) | `px.pie()`       |
    | **Scatter**     | Correlations, distributions   | `px.scatter()`   |
    | **Histogram**   | Value distributions           | `px.histogram()` |
    | **Area**        | Cumulative trends             | `px.area()`      |
  </Tab>

  <Tab title="Advanced Charts">
    | Chart           | When Used                     | Plotly Function           |
    | --------------- | ----------------------------- | ------------------------- |
    | **Grouped bar** | Multi-category comparison     | `px.bar(barmode="group")` |
    | **Stacked bar** | Part-to-whole over categories | `px.bar(barmode="stack")` |
    | **Heatmap**     | Matrix data, correlations     | `px.imshow()`             |
    | **Box plot**    | Statistical distributions     | `px.box()`                |
    | **Treemap**     | Hierarchical proportions      | `px.treemap()`            |
    | **Funnel**      | Sequential stages             | `px.funnel()`             |
  </Tab>
</Tabs>

## Interactive Features

Plotly charts rendered in the frontend support full interactivity:

* **Hover tooltips**: View exact values for each data point
* **Zoom and pan**: Focus on specific regions of the chart
* **Legend toggle**: Show/hide individual series by clicking the legend
* **Download**: Export as PNG or SVG directly from the chart toolbar
* **Responsive sizing**: Charts adapt to the container width

## Chart Generation Examples

<AccordionGroup>
  <Accordion title="Time series trend">
    **Question:** "Show me the monthly revenue trend for the past year"

    The Insights Agent generates a line chart with months on the x-axis and revenue on the y-axis, including trend annotations for significant changes.
  </Accordion>

  <Accordion title="Category comparison">
    **Question:** "Compare sales across product categories by region"

    The agent generates a grouped bar chart with categories on the x-axis, sales on the y-axis, and color-coded bars for each region.
  </Accordion>

  <Accordion title="Distribution analysis">
    **Question:** "What does the distribution of order values look like?"

    The agent generates a histogram showing the frequency distribution of order values, with optional statistics overlay (mean, median, standard deviation).
  </Accordion>

  <Accordion title="Proportion breakdown">
    **Question:** "What percentage of revenue comes from each channel?"

    The agent generates a pie or donut chart showing revenue proportions by channel, with percentage labels.
  </Accordion>
</AccordionGroup>

## Artifact Storage

Generated visualizations are stored as session artifacts in the Talk2Data database:

| Artifact Component      | Storage                                       |
| ----------------------- | --------------------------------------------- |
| **Chart specification** | Plotly JSON stored in the artifacts table     |
| **Underlying data**     | Query results stored alongside the chart      |
| **Python code**         | Generation code preserved for reproducibility |
| **Metadata**            | Chart type, title, axes, timestamp            |

Artifacts persist for the duration of the session and can be referenced in follow-up questions ("Make that a line chart instead" or "Add a trend line").

## Customization in Follow-Up Questions

Users can refine visualizations through natural-language follow-ups:

| Request                   | Result                          |
| ------------------------- | ------------------------------- |
| "Make that a bar chart"   | Chart type changed              |
| "Show only the top 5"     | Data filtered, chart updated    |
| "Add a trend line"        | Trend line overlay added        |
| "Use a logarithmic scale" | Y-axis scale changed            |
| "Split by region"         | Color dimension added           |
| "Show as a percentage"    | Values converted to proportions |

## Next Steps

<CardGroup cols={2}>
  <Card title="Chat With Data" icon="comments" href="/data-insights/chat-with-data">
    See the full conversational pipeline that produces visualizations.
  </Card>

  <Card title="Text-to-SQL" icon="code" href="/data-insights/text-to-sql">
    Understand how data is retrieved before visualization.
  </Card>

  <Card title="Analysis Agent" icon="chart-line" href="/data-insights/analysis-agent">
    Learn about the reasoning engine that selects chart types.
  </Card>

  <Card title="Data Source Setup" icon="database" href="/guides/data-source-setup">
    Connect a database to start visualizing your data.
  </Card>
</CardGroup>