AshReports.ChartEngine (ash_reports v0.1.0)

Core chart engine for AshReports.

Provides a unified interface for generating server-side SVG charts and visualizations using Contex with automatic chart type selection and caching capabilities.

Features

  • Server-Side SVG Generation: Pure Elixir chart generation using Contex
  • Automatic Chart Selection: Intelligent chart type selection based on data characteristics
  • Multi-Renderer Support: SVG output works across HTML, HEEX, PDF, and JSON renderers
  • Internationalization: Integration with CLDR and translation systems
  • Performance Optimization: Efficient chart data processing and ETS-based caching

Supported Chart Types

Basic Charts:

  • Line Charts: Time series data, trends, continuous data
  • Bar Charts: Categorical comparisons, rankings, grouped data
  • Pie Charts: Proportional data, percentages, parts-of-whole
  • Area Charts: Cumulative data, stacked comparisons

Advanced Charts:

  • Scatter Plots: Correlation analysis, data distribution
  • Histogram Charts: Frequency distribution, statistical analysis
  • Box Plots: Statistical summaries, outlier detection
  • Heatmaps: Density visualization, correlation matrices

Chart Generation

All charts are generated server-side using Contex, producing SVG output that can be:

  • Embedded directly in HTML/HEEX templates
  • Converted to images for PDF rendering
  • Served as data through JSON APIs
  • Cached for improved performance

Usage Examples

Basic Chart Generation

chart_config = %ChartConfig{
  type: :line,
  data: time_series_data,
  title: "Sales Trend"
}

{:ok, chart} = ChartEngine.generate(chart_config, context)

Automatic Chart Selection

data = %{
  sales_by_month: monthly_sales_data,
  profit_margins: percentage_data
}

charts = ChartEngine.auto_select_charts(data, context)

Real-time Chart Configuration

realtime_config = %ChartConfig{
  type: :bar,
  data: sales_data,
  real_time: true,
  update_interval: 30_000  # 30 seconds
}

{:ok, chart} = ChartEngine.generate(realtime_config, context)

Summary

Types

chart_result()
chart_type()

Functions

auto_select_charts(data, context)

Automatically select appropriate chart types based on data characteristics.

generate(config, context)

Generate a chart using the specified configuration and render context.

generate_chart_set(chart_configs, context)

Generate multiple charts for comprehensive data visualization.

get_metrics()

Get chart generation statistics and performance metrics.

Types

chart_result()

@type chart_result() ::
  {:ok, AshReports.ChartEngine.ChartData.t()} | {:error, String.t()}

chart_type()

@type chart_type() ::
  :line | :bar | :pie | :area | :scatter | :histogram | :boxplot | :heatmap

Functions

auto_select_charts(data, context)

@spec auto_select_charts(map(), AshReports.RenderContext.t()) :: [
  AshReports.ChartEngine.ChartConfig.t()
]

Automatically select appropriate chart types based on data characteristics.

Analyzes the provided data and suggests the most suitable chart types for visualization based on data patterns, types, and relationships.

Examples

data = %{
  revenue: [100, 150, 200, 175],
  months: ["Jan", "Feb", "Mar", "Apr"]
}

suggestions = ChartEngine.auto_select_charts(data, context)
# Returns: [%ChartConfig{type: :line, confidence: 0.9}, ...]

generate(config, context)

@spec generate(AshReports.ChartEngine.ChartConfig.t(), AshReports.RenderContext.t()) ::
  chart_result()

Generate a chart using the specified configuration and render context.

Uses Contex for server-side SVG generation.

Examples

config = %ChartConfig{
  type: :line,
  data: [[1, 10], [2, 20], [3, 15]],
  title: "Sales Trend"
}

{:ok, chart} = ChartEngine.generate(config, context)

generate_chart_set(chart_configs, context)

@spec generate_chart_set(map(), AshReports.RenderContext.t()) ::
  {:ok, map()} | {:error, String.t()}

Generate multiple charts for comprehensive data visualization.

Creates a set of related charts that provide different perspectives on the same dataset for dashboard-style reporting.

Examples

chart_set = %{
  overview: %ChartConfig{type: :line, data: trend_data},
  breakdown: %ChartConfig{type: :pie, data: category_data},
  comparison: %ChartConfig{type: :bar, data: comparison_data}
}

{:ok, charts} = ChartEngine.generate_chart_set(chart_set, context)

get_metrics()

@spec get_metrics() :: map()

Get chart generation statistics and performance metrics.