Data Visualization - Usage Examples

This document provides usage examples for the Data Visualization module. All plotting functions use the Codomyrmex logging system (logging_monitoring) for logging. It is recommended to call setup_logging() and ensure_dependencies_installed() at application startup.

Initialization Example

from codomyrmex.logging_monitoring import setup_logging
# from codomyrmex.environment_setup.env_checker import ensure_dependencies_installed # Conceptual: ensure this function exists or use project-specific setup

setup_logging()  # Initialize logging system
# ensure_dependencies_installed()  # Conceptual: Check for required dependencies

Make sure to create the output directory (e.g., ./plot_output/) if it doesn't exist, or ensure your script has permissions to create it.

import os
# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

Example 1: Simple Line Plot

from codomyrmex.data_visualization import create_line_plot
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

x_data = np.array([1, 2, 3, 4, 5, 6])
y_data = np.array([10, 12, 5, 8, 15, 13])

create_line_plot(
    x_data,
    y_data,
    title="Website Traffic Over Time",
    x_label="Month",
    y_label="Unique Visitors (in thousands)",
    output_path=os.path.join(output_dir, "line_plot_traffic.png"),
    markers=True
)

Expected Outcome

A PNG file named line_plot_traffic.png will be saved in the ./plot_outputs directory, showing a line plot of website traffic.

Example 2: Multiple Lines Plot

from codomyrmex.data_visualization import create_line_plot
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

x_data = np.array([2018, 2019, 2020, 2021, 2022])
y_data_product_a = np.array([100, 120, 150, 130, 170])
y_data_product_b = np.array([80, 90, 100, 110, 140])

create_line_plot(
    x_data,
    [y_data_product_a, y_data_product_b],
    title="Product Sales Over Years",
    x_label="Year",
    y_label="Units Sold",
    line_labels=["Product A", "Product B"],
    output_path=os.path.join(output_dir, "line_plot_sales.png")
)

Expected Outcome

A PNG file line_plot_sales.png in ./plot_outputs with two lines representing sales for Product A and Product B, including a legend.

Example 3: Scatter Plot

from codomyrmex.data_visualization import create_scatter_plot
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

study_hours = np.array([2, 3, 1, 4, 5, 2.5, 3.5])
exam_scores = np.array([65, 75, 50, 80, 90, 70, 78])

create_scatter_plot(
    study_hours,
    exam_scores,
    title="Study Hours vs. Exam Scores",
    x_label="Hours Studied",
    y_label="Exam Score",
    output_path=os.path.join(output_dir, "scatter_plot_scores.png"),
    dot_color='green'
)

Expected Outcome

A PNG file scatter_plot_scores.png in ./plot_outputs showing the correlation between study hours and exam scores.

Example 4: Vertical Bar Chart

from codomyrmex.data_visualization import create_bar_chart
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

months = ['Jan', 'Feb', 'Mar', 'Apr', 'May']
rainfall = np.array([50, 40, 65, 30, 70]) # mm

create_bar_chart(
    months,
    rainfall,
    title="Monthly Rainfall",
    x_label="Month",
    y_label="Rainfall (mm)",
    output_path=os.path.join(output_dir, "bar_chart_rainfall.png")
)

Expected Outcome

A PNG file bar_chart_rainfall.png in ./plot_outputs showing monthly rainfall as a vertical bar chart.

Example 5: Horizontal Bar Chart

from codomyrmex.data_visualization import create_bar_chart
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

programming_languages = ['Python', 'JavaScript', 'Java', 'C#', 'TypeScript']
popularity = np.array([31.5, 20.2, 18.5, 15.1, 10.3]) # Fictional popularity scores

create_bar_chart(
    programming_languages,
    popularity,
    title="Programming Language Popularity (Fictional)",
    x_label="Popularity Score", # Becomes the value axis label for horizontal charts
    y_label="Language", # Becomes the category axis label for horizontal charts
    horizontal=True,
    bar_color='purple',
    output_path=os.path.join(output_dir, "bar_chart_languages_horizontal.png")
)

Expected Outcome

A PNG file bar_chart_languages_horizontal.png in ./plot_outputs showing language popularity as a horizontal bar chart.

Example 6: Histogram

from codomyrmex.data_visualization import create_histogram
import numpy as np
import random
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

# Simulate exam scores for 100 students
np_exam_scores_raw = [random.gauss(75, 10) for _ in range(100)]
np_exam_scores = np.clip(np_exam_scores_raw, 0, 100) # clamp between 0 and 100

create_histogram(
    np_exam_scores,
    bins=10,
    title="Distribution of Exam Scores",
    x_label="Score",
    y_label="Number of Students",
    output_path=os.path.join(output_dir, "histogram_scores.png")
)

Expected Outcome

A PNG file histogram_scores.png in ./plot_outputs showing the distribution of exam scores.

Example 7: Pie Chart

from codomyrmex.data_visualization import create_pie_chart
import numpy as np
import os

# Ensure output directory exists
output_dir = "./plot_outputs"
os.makedirs(output_dir, exist_ok=True)

labels = ['Work', 'Sleep', 'Eat', 'Leisure', 'Commute']
hours_spent = np.array([8, 7, 2, 4, 1])
explode_slices = [0, 0.1, 0, 0, 0]  # Explode the 'Sleep' slice

create_pie_chart(
    labels,
    hours_spent,
    title="Daily Time Allocation",
    explode=explode_slices,
    output_path=os.path.join(output_dir, "pie_chart_daily_time.png")
)

Expected Outcome

A PNG file pie_chart_daily_time.png in ./plot_outputs showing the daily time allocation as a pie chart, with the "Sleep" slice slightly offset.

Example 8: Heatmap

from codomyrmex.data_visualization import create_heatmap
import numpy as np
import os

# (Assume logging and environment setup as above)
data = np.random.rand(8, 12)
create_heatmap(
    data,
    x_labels=[f"Col {i+1}" for i in range(12)],
    y_labels=[f"Row {i+1}" for i in range(8)],
    title="Random Data Heatmap",
    output_path="./plot_output/heatmap_example.png",
    annot=True
)

Expected Outcome

A PNG file heatmap_example.png will be saved in the ./plot_outputs directory, displaying a heatmap of random data with annotations.

Using Plotting Tools via Model Context Protocol (MCP)

The Data Visualization module also exposes its plotting functions as MCP tools. This allows AI agents or other Codomyrmex modules to request plot generation programmatically.

Full details for each MCP tool, including all parameters, are available in the MCP Tool Specification.

Below are a couple of examples of how these tools might be invoked.

MCP Example 1: Creating a Line Plot

Request:

{
  "tool_name": "create_line_plot",
  "arguments": {
    "x_data": [1, 2, 3, 4, 5],
    "y_data": [2, 3, 5, 7, 6],
    "title": "MCP Generated Line Plot",
    "x_label": "Time (s)",
    "y_label": "Value",
    "output_path": "./plot_output/mcp_line_plot.png",
    "markers": true
  }
}

Expected Outcome (via MCP Response and file system):

An MCP response similar to: {"output_path": "./plot_output/mcp_line_plot.png", "fig_details": {"status": "saved_to_path"}} (Actual path in response might be absolute if server resolves it).
A PNG file named mcp_line_plot.png saved in the ./plot_outputs directory (or other designated MCP output location).

MCP Example 2: Creating a Bar Chart

Request:

{
  "tool_name": "create_bar_chart",
  "arguments": {
    "categories": ["Alpha", "Bravo", "Charlie", "Delta"],
    "values": [15, 22, 18, 25],
    "title": "MCP Generated Bar Chart",
    "x_label": "Group",
    "y_label": "Count",
    "output_path": "./plot_output/mcp_bar_chart.png",
    "horizontal": false,
    "bar_color": "teal"
  }
}

Expected Outcome (via MCP Response and file system):

An MCP response similar to: {"output_path": "./plot_output/mcp_bar_chart.png", "fig_details": {"status": "saved_to_path"}}.
A PNG file named mcp_bar_chart.png saved in the ./plot_outputs directory.

MCP Example 3: Creating a Histogram

Request:

{
  "tool_name": "create_histogram",
  "arguments": {
    "data": [10,12,12,13,14,14,15,15,15,16,18,20,21,21,22,25,30],
    "bins": 5,
    "title": "MCP Generated Histogram",
    "x_label": "Measurement",
    "y_label": "Frequency",
    "output_path": "./plot_output/mcp_histogram.png",
    "hist_color": "#FF9900",
    "density": false
  }
}

Expected Outcome (via MCP Response and file system):

An MCP response similar to: {"output_path": "./plot_output/mcp_histogram.png", "fig_details": {"status": "saved_to_path"}}.
A PNG file named mcp_histogram.png saved in the ./plot_outputs directory.

MCP Example 4: Creating a Pie Chart

Request:

{
  "tool_name": "create_pie_chart",
  "arguments": {
    "labels": ["Alpha", "Bravo", "Charlie", "Delta"],
    "sizes": [20, 30, 25, 25],
    "title": "MCP Generated Pie Chart",
    "output_path": "./plot_output/mcp_pie_chart.png",
    "explode": [0, 0.1, 0, 0],
    "startangle": 90,
    "autopct": "%1.1f%%"
  }
}

Expected Outcome (via MCP Response and file system):

An MCP response similar to: {"output_path": "./plot_output/mcp_pie_chart.png", "fig_details": {"status": "saved_to_path"}}.
A PNG file named mcp_pie_chart.png saved in the ./plot_outputs directory.

General Notes for MCP Usage:

output_path: Ensure the path specified is writable by the Codomyrmex application process and ideally within a designated output area to prevent arbitrary file writes.
Error Handling: MCP tool calls will return an error structure in the JSON response if plot generation fails (e.g., due to invalid data or parameters). Check the MCP_TOOL_SPECIFICATION.md for details on error responses.
Data Types: Ensure data passed in the arguments field matches the types specified in the MCP_TOOL_SPECIFICATION.md (e.g., arrays of numbers for x_data, y_data).

For detailed specifications of all available MCP plotting tools, including create_scatter_plot, create_histogram, create_pie_chart, and create_heatmap, please refer to the Data Visualization MCP Tool Specification.

Common Pitfalls & Troubleshooting

Issue: Logging not working or logs missing.
- Solution: Ensure setup_logging() is called before any plotting functions.
Issue: Missing dependencies (e.g., matplotlib, numpy).
- Solution: Ensure ensure_dependencies_installed() is called at startup, and install all required packages.
Issue: Output directory not found or permission denied when saving plots.
- Solution: Make sure the directory specified in output_path exists and that your application has write permissions to it. The save_plot helper attempts to create the directory, but deep path creation or permission issues can still occur.

Parent: Project Overview
Module Index: All Agents
Documentation: Reference Guides
Home: Root README

Initialization Example​

Example 1: Simple Line Plot​

Expected Outcome​

Example 2: Multiple Lines Plot​

Expected Outcome​

Example 3: Scatter Plot​

Expected Outcome​

Example 4: Vertical Bar Chart​

Expected Outcome​

Example 5: Horizontal Bar Chart​

Expected Outcome​

Example 6: Histogram​

Expected Outcome​

Example 7: Pie Chart​

Expected Outcome​

Example 8: Heatmap​

Expected Outcome​

Using Plotting Tools via Model Context Protocol (MCP)​

MCP Example 1: Creating a Line Plot​

MCP Example 2: Creating a Bar Chart​

MCP Example 3: Creating a Histogram​

MCP Example 4: Creating a Pie Chart​

General Notes for MCP Usage:​

Common Pitfalls & Troubleshooting​

Navigation Links​

Initialization Example

Example 1: Simple Line Plot

Expected Outcome

Example 2: Multiple Lines Plot

Expected Outcome

Example 3: Scatter Plot

Expected Outcome

Example 4: Vertical Bar Chart

Expected Outcome

Example 5: Horizontal Bar Chart

Expected Outcome

Example 6: Histogram

Expected Outcome

Example 7: Pie Chart

Expected Outcome

Example 8: Heatmap

Expected Outcome

Using Plotting Tools via Model Context Protocol (MCP)

MCP Example 1: Creating a Line Plot

MCP Example 2: Creating a Bar Chart

MCP Example 3: Creating a Histogram

MCP Example 4: Creating a Pie Chart

General Notes for MCP Usage:

Common Pitfalls & Troubleshooting

Navigation Links