# PlotSense Technical Documentation v2

**PlotSense Technical Documentation**

1. **PlotSense Overview**

PlotSense is a Python package designed to automate the generation of intelligent data visualizations. Leveraging the power of explainable artificial intelligence (XAI) and large language models (LLMs), PlotSense assists data professionals by providing meaningful insights, suggesting optimal visualizations, and enhancing interpretability of complex datasets.

PlotSense addresses the challenge of selecting the right visualization and interpreting complex datasets by:

* Reducing time spent on exploratory data analysis.
* Lowering the barrier to insight discovery.
* Enhancing the communication of findings with explainable narratives.
* Supporting better data-driven decisions.

2. **PlotSense Architecture**

PlotSense is structured around a modular pipeline that processes user data, identifies patterns, determines suitable chart types, and generates both visual and textual explanations. The architecture integrates traditional statistical methods with modern AI.

![fig 1: visual representation of PlotSense Architecture](/files/94e8b0198304f47da45e335f0b944264147aec1c)

**2.1 Visualization Recommender System Module Overview**

The Visualization Recommender System is a PlotSense module that leverages multiple large language models (LLMs) in a weighted ensemble approach to recommend optimal data visualizations for a given panda DataFrame. The system analyses dataset characteristics and suggests appropriate matplotlib visualizations based on data types, statistical properties, and relationships between variables. It is implemented as a modular, extensible Python class (VisualizationRecommender) that can operate as both a standalone tool and a library function.

![fig 2: visual representation of recommender module](/files/b275347f824810ce7a80aec3e4544d69a849f318)

**2.1.1 Recommender Key Features**

**2.1.1.1 Data Profiling and Prompt Generation**

Upon receiving a pandas DataFrame, the system generates a detailed textual profile of the dataset. This includes column names, data types (numerical, categorical, datetime), sample values, and correlation metrics for numerical features. The profile is embedded in a highly structured prompt designed to guide LLMs toward producing correct and varied visualization suggestions. The prompt also enforces critical rules, such as ensuring numerical variables precede categorical ones and matching variable types to appropriate matplotlib plot types.

**2.1.1.2 Multi-Model Querying with Threaded Execution**

A collection of pre-configured LLMs (llama-3.3-70b-versatile, llama-3.1-8b-instant) is queried in parallel using a ThreadPoolExecutor. This ensures low-latency, concurrent querying, and enhances the diversity of model outputs. Each model receives the same prompt and returns a set of visualization suggestions.

**2.1.1.3 Structured Response Parsing**

The LLM responses are parsed into structured dictionaries, extracting fields like plot\_type and variables. Only variables present in the dataset are retained. Invalid or hallucinated suggestions are filtered out. This step enforces prompt-consistent formatting and ensures semantic correctness of the recommendations.

**2.1.1.4 Ensemble Ranking and Scoring**

To select the most relevant and trustworthy visualizations, the system employs a weighted ensemble scoring mechanism:

* Each model is assigned a configurable weight.
* Each unique recommendation (defined by its plot\_type and sorted variables) accumulates a raw weight score, derived from the product of the model’s assigned weight and the individual suggestion confidence (default 1.0).
* Recommendations contributed by multiple models benefit from higher model agreement scores, increasing their final ensemble ranking.

The final ensemble score is normalized and used to rank recommendations. The top-n results are returned, sorted by both ensemble\_score and model\_agreement. These balances:

* Model confidence,
* Consensus across models
* Variable validity.

If the number of high-quality recommendations is insufficient, the system attempts to supplement using targeted prompts referencing prior outputs.

**2.1.1.5 Variable Order Validation**

Before final output, a variable reordering pass ensures that the recommendations respect critical domain constraints (e.g., numerical before categorical, proper ordering for scatter plots). This ensures that outputs are not only insightful but also immediately valid for implementation in visualization libraries.

**2.1.1.6 User-Customized Ensemble Weighting**

By default, each model is assigned a neutral ensemble weight of 0.5, ensuring equal influence across responses during the aggregation process. However, advanced users and researchers can customize these weights to reflect:

* Confidence in a specific LLM’s performance,
* Domain-specific tuning (e.g., emphasizing larger models for complex datasets)

**2.1.1.7 Top N Recommendation Count**

Users can also customize the number of desired visualizations via the n parameter. The system ensures at least n unique, valid, and semantically correct recommendations are returned. If the initial results from ensemble scoring are insufficient, the system automatically supplements recommendations by querying the top-performing model with a follow-up prompt.

This makes the system suitable for both quick exploratory analysis (n=3) and deeper analytical sessions (n=10+), depending on user needs.

**2.1.2 Recommender Limitations**

* Currently optimized for matplotlib syntax
* Other libraries may require prompt adjustments
* Recommendations influenced by training data of underlying LLMs

**2.2 Smart Plot Generator Module Overview**

The Smart Plot Generator is a sophisticated Python class that transforms visualization recommendations for the recommender engine into actual matplotlib plots. It serves as the execution layer that takes abstract visualization suggestions (like *"scatter plot of age vs income"*) and generates the corresponding matplotlib figures with proper data handling, error checking, and aesthetic customization.

**2.2.1 Plot Generator Key Features**

**2.2.1.1 Multi-plot Support**

The Plot Generator system provides native support for a wide array of statistical visualization types including fundamental plots (scatter, bar, histogram) and specialized charts (boxplot, violin, hexbin). Each plot type implements strict variable requirement validation, ensuring numerical variables are properly prioritized and categorical groupings are automatically detected. The system maintains an extensible architecture that allows for seamless addition of new visualization types through standardized method templates.

**2.2.1.2 Intelligent Data Handling**

Built-in data handling capabilities automatically sanitize input datasets through NaN removal, type coercion, and statistical normalization. The engine performs dynamic data validation, rejecting incompatible variable combinations while suggesting appropriate alternatives. For multivariate visualizations, the system implements smart variable ordering protocols that ensure proper dimension mapping according to matplotlib's plotting conventions.

**2.2.1.3 Enhanced Visualisation**

Beyond basic matplotlib implementations, each plot type incorporates professional-grade enhancements including automated bin sizing for histograms, optimized whisker calculations for boxplots, and intelligent color mapping for multivariate scatter plots. The system provides built-in accessibility considerations through automatic color contrast validation and optional alt-text generation capabilities.

**2.2.1.4 Customisable Framework**

The generator exposes a comprehensive styling API that surfaces matplotlib's full configuration spectrum through parameterized kwargs. Users can override default aesthetics at multiple levels - from global figure properties to individual plot elements. The system includes preset style templates for common publication formats (IEEE, Nature, APA) while maintaining low-level control over all visual components.

**2.2.1.5 Dual Interface Paradigm**

The generator supports both index-based and direct object interaction models. The DataFrame index mode enables batch processing workflows, while the Series input option allows for precise control over individual visualizations. Both modes maintain consistent parameter handling and output quality, with automatic type conversion between interface formats. The system implements a singleton-based caching mechanism to optimize performance during iterative visualization development.

**2.2.2 Plot Generator Limitations**

* Limited Matplotlib Support: Currently supports about 10 common plot types but doesn't cover the full matplotlib repertoire
* No 3D Plots: Lacks support for surface, wireframe, and other 3D visualizations
* No Interactive Plots: Only generates static matplotlib figures without interactivity
* Size Limitations: May struggle with very large datasets (>1M rows) due to matplotlib performance
* Complex Data Types: Limited handling of datetime, timedelta, and complex number visualization
* Sparse Data: No special handling for sparse matrices or unusual data distributions
* No GPU Acceleration: Pure CPU-based rendering
* No Caching: Recomputes statistics for each plot generation
* Memory Usage: Could be optimized for very large figures

**2.3 Plot Explainer Module Overview**

The Plot Explainer is a sophisticated Python class that leverages Large Language Models (LLMs) to generate and iteratively refine explanations for data visualizations. It transforms matplotlib/seaborn plots into comprehensive, structured explanations through a multi-step refinement process.

![fig 3: visual representation of explainer module](/files/c26925a4a7096d68648277f917b68aa8e75729a9)

**2.3.1 Plot Explainer Key Features**

**23.1.1 Multi-Model LLM Support**

The system integrates with multiple LLM providers to generate explanations, ensuring flexibility and robustness.

**Supported Models**

* Groq API (with LLaMA models): meta-llama/llama-4-scout-17b-16e-instruct, meta-llama/llama-4-maverick-17b-128e-instruct
* Extensible Architecture: Can be expanded to support OpenAI, Anthropic, and other providers.

**Model Selection Logic**

* Automatically detects available models based on API keys.
* Cycles through models during refinement iterations for diverse perspectives.

**2.3.1.2 Iterative Refinement Process**

The explainer doesn’t just generate a single explanation—it iteratively refines the output for higher quality.

**Three-Stage Refinement Pipeline**

Initial Explanation

* Generates a structured breakdown of the visualization.
* Follows a 4-section format (Overview, Key Features, Insights, Conclusion).

Critique Generation

* The system self-evaluates the initial explanation.
* Identifies gaps, inaccuracies, or areas needing deeper analysis.

Refinement

* Enhances the explanation based on critique.
* Adds missing insights, clarifies ambiguities, and improves coherence.

Customizable Iteration Depth

* Default: 3 refinement cycles (can be adjusted via max\_iterations).
* Each iteration uses a different model (if available) for varied insights.

**2.3.1.3 Image Processing & Encoding**

Since LLMs require text input, the system converts plots into a format they can analyze.

Temporary Image Save

* The plot (matplotlib Figure or Axes) is saved as a JPEG (temp\_plot.jpg by default).
* Ensures high-quality input for the model.

Base64 Encoding

* The image is converted to a base64 string.
* Sent to the LLM as part of a multimodal prompt (text + image).

Automatic Cleanup

* Temporary files are deleted after processing.

**2.3.1.4 Structured Explanation Format**

The output is well-organized and data-driven, making it useful for reports, dashboards, or further analysis.

* Overview: Brief description of the visualization type and purpose.
* Key Features: Main visual elements (axes, labels, colors, markers), Statistical properties (ranges, distributions).
* Insights and Patterns: Trends, correlations, outliers.
* Conclusion: Summary of findings and suggestions for further analysis.

| **Feature**          | **Plot Explainer** | **Generic LLM Chat** | **Static Documentation** |
| -------------------- | ------------------ | -------------------- | ------------------------ |
| Structured Output    | ✅ Yes (4 sections) | ❌ Unstructured       | ✅ Manual formatting      |
| Image Understanding  | ✅ Yes              | ❌ Text-only          | ❌ Manual input           |
| Iterative Refinement | ✅ Yes              | ❌ Single-pass        | ❌ Static text            |
| Custom Prompts       | ✅ Yes              | ✅ Yes                | ❌ Fixed                  |
| Automated Cleanup    | ✅ Yes              | ❌ N/A                | ❌ N/A                    |

**2.3.1.5 Customizable Prompts & Parameters**

Users can tailor the explanation to their needs.

**Prompt Engineering**

* Default: "Explain this data visualization"
* Can be specialized (e.g., "Focus on outliers and statistical significance").

**LLM Generation Control**

* Adjustable via custom\_parameters:
* temperature (creativity vs. focus).
* max\_tokens (response length).
* top\_p (diversity of responses).

**2.3.2 Plot Explainer Limitations**

While the Plot Explainer is a powerful tool for generating and refining plot explanations, it has several limitations that users should be aware of:

**Model & API Dependencies**

* Currently it only supports the Groq API (with LLaMA models).
* Requires image-to-text conversion (base64 encoding), which may lose some visual details.
* Groq API has usage limits (free tier available, but may throttle under heavy use).

**Input & Data Handling**

* Poor performance on 3D plots (surface, mesh, 3D scatter) and Geospatial maps (unless converted to static images).
* Small datasets may lead to overinterpretation (LLMs may "hallucinate" trends).
* No statistical validation. Explanations are descriptive, not analytical.
* Must save plots as images (temp\_plot.jpg), which:
* Adds I/O overhead (slower than direct memory processing).

**Performance & Scalability**

* Each refinement iteration requires a new API call.
* Slower for large images (high-resolution plots take longer to encode).
* No Caching Mechanism
* Repeated explanations for the same plot trigger new API calls.
* No offline mode (requires internet for Groq API).
* No async support—explanations are generated sequentially.
* Not optimized for batch processing (e.g., 100+ plots at once).

**Security & Privacy Concerns**

* Plot images are sent to third-party APIs (Groq servers).
* Requires cloud-based LLMs (no local model support yet).

**2.4 Groq in PlotSense**

PlotSense uses Groq's ultra-fast LPU inference to generate real-time AI explanations for data visualizations.

* Lightning Speed: Delivers structured plot analyses in milliseconds (vs. seconds on GPUs)
* Optimized for Plots: Processes matplotlib/seaborn visuals via base64 encoding
* Smart Refinement: Iteratively improves explanations using Llama 3-70B
* Consistent Output: Returns markdown-formatted insights (Overview, Key Features, Insights, Conclusion)

**Why Groq?**

* 10x faster than GPU alternatives
* Cost-efficient high-volume processing
* Free tier available

**2.5 Conclusion**

PlotSense represents a transformative approach to data visualization analysis by combining cutting-edge AI with intuitive functionality. By leveraging Groq's lightning-fast LPU architecture, the system delivers real-time, intelligent plot explanations that would traditionally require manual analysis or slower AI processing.

The integration of iterative refinement ensures explanations are not just generated, but continuously improved for accuracy and depth. PlotSense's structured output format provides immediately actionable insights while maintaining flexibility for customization through prompt engineering.

With its ability to handle standard statistical visualizations out-of-the-box and its foundation for future expansion, PlotSense bridges the gap between raw data visualization and meaningful business or research insights. The solution is particularly valuable for:

* Data scientists conducting exploratory analysis
* Business analysts preparing reports
* Researchers documenting findings
* Educators explaining visual concepts

As AI-assisted analytics becomes increasingly crucial, PlotSense positions itself as an essential tool for anyone working with data visualizations - transforming static charts into dynamic sources of knowledge with unprecedented speed and clarity. The system's performance advantages and thoughtful architecture suggest it will scale effectively as both the underlying models and visualization needs continue to evolve.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://plotsenseai.gitbook.io/plotsense-technical-roadmap/plotsense-technical-documentation-v2/plotsense-technical-documentation-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.