General

Quadrant charts visualize data points across four quadrants based on two axes. They are useful for categorizing items based on two independent variables, such as priority matrices, portfolio analysis, or strategic planning.

The quadrant chart implementation in Sirena follows the established 7-file Parslet architecture pattern, ensuring consistency with other diagram types.

Architecture

Components

The quadrant chart implementation consists of seven main components:

  1. Diagram Model ([lib/sirena/diagram/quadrant.rb](lib/sirena/diagram/quadrant.rb:1))

    • QuadrantChart - Main diagram model

    • QuadrantPoint - Individual data point with coordinates and styling

  2. Parslet Grammar ([lib/sirena/parser/grammars/quadrant.rb](lib/sirena/parser/grammars/quadrant.rb:1))

    • Parses quadrantChart keyword

    • Axis definitions with labels

    • Quadrant labels (quadrant-1 through quadrant-4)

    • Data points with [x, y] coordinates

    • Point styling (radius, color, stroke)

  3. Transform ([lib/sirena/parser/transforms/quadrant.rb](lib/sirena/parser/transforms/quadrant.rb:1))

    • Converts parse tree to QuadrantChart model

    • Extracts title, axes, quadrant labels, and points

  4. Parser ([lib/sirena/parser/quadrant.rb](lib/sirena/parser/quadrant.rb:1))

    • Orchestrates grammar and transform

    • Provides error handling

  5. Layout Transform ([lib/sirena/transform/quadrant.rb](lib/sirena/transform/quadrant.rb:1))

    • Calculates 2x2 grid layout

    • Converts normalized coordinates (0-1) to SVG coordinates

    • Positions points in 2D space

  6. Renderer ([lib/sirena/renderer/quadrant.rb](lib/sirena/renderer/quadrant.rb:1))

    • Draws quadrant grid with colored backgrounds

    • Renders center axes

    • Adds axis labels and quadrant names

    • Renders data points as circles with labels

  7. Tests ([spec/sirena/parser/quadrant_spec.rb](spec/sirena/parser/quadrant_spec.rb:1))

    • Parser tests with 17 examples

    • 10 fixture files from Mermaid test suite

Data Flow 

Mermaid Source
      ↓
Grammar (Parslet) → Parse Tree
      ↓
Transform → QuadrantChart Model
      ↓
Layout Transform → Graph Structure with SVG Coordinates
      ↓
Renderer → SVG Document

Syntax

Basic Structure 

quadrantChart
    title Chart Title
    x-axis Low Value --> High Value
    y-axis Low Impact --> High Impact
    quadrant-1 Label for Top Right
    quadrant-2 Label for Top Left
    quadrant-3 Label for Bottom Left
    quadrant-4 Label for Bottom Right
    Item A: [0.3, 0.6]
    Item B: [0.7, 0.8]

Quadrant Numbering

Quadrants are numbered 1-4:

  • Quadrant 1: Top-right (x ≥ 0.5, y ≥ 0.5)

  • Quadrant 2: Top-left (x < 0.5, y ≥ 0.5)

  • Quadrant 3: Bottom-left (x < 0.5, y < 0.5)

  • Quadrant 4: Bottom-right (x ≥ 0.5, y < 0.5)

Coordinates

Data points use normalized coordinates in the range [0.0, 1.0]:

  • X-axis: 0.0 (left) to 1.0 (right)

  • Y-axis: 0.0 (bottom) to 1.0 (top)

quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    Point A: [0.2, 0.8]  # Top-left area
    Point B: [0.8, 0.2]  # Bottom-right area

Features

Title Declaration

Add a title to the chart using the title keyword.

Example 1. Adding a title
quadrantChart
    title Product Analysis Matrix
    x-axis Low Cost --> High Cost
    y-axis Low Value --> High Value

Axis Labels

Define axis labels with start and end labels using the arrow syntax -→.

Example 2. Defining axis labels
quadrantChart
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
Example 3. Using quoted labels with special characters
quadrantChart
    x-axis "Low Cost ❤" --> "High Cost"
    y-axis "Low Value" --> "High Value"

Quadrant Labels

Label each of the four quadrants using quadrant-1 through quadrant-4.

Example 4. Setting quadrant labels
quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    quadrant-1 Quick Wins
    quadrant-2 Major Projects
    quadrant-3 Fill Ins
    quadrant-4 Hard Slogs

Data Points

Add data points with normalized [x, y] coordinates.

Example 5. Basic data points
quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]

Point Styling

Customize point appearance with styling parameters.

Example 6. Point with radius
quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    Product A: [0.5, 0.5] radius: 10
Example 7. Point with color and radius
quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    Product B: [0.3, 0.7] radius: 8, color: #ff0000
Example 8. Point with all styling options
quadrantChart
    x-axis Left --> Right
    y-axis Bottom --> Top
    Product D: [0.1, 0.9] radius: 10, color: #ff0000, stroke-color: #00ff00, stroke-width: 3px

Available styling parameters:

radius

Size of the point circle (default: 6)

color

Fill color of the point (hex or named color)

stroke-color

Border color of the point

stroke-width

Width of the point border (can include "px" suffix)

Complete Example

Example 9. Campaign reach and engagement analysis
quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]

This produces a quadrant chart with:

  • A title at the top

  • X-axis labeled from "Low Reach" to "High Reach"

  • Y-axis labeled from "Low Engagement" to "High Engagement"

  • Four labeled quadrants with colored backgrounds

  • Six campaign data points positioned by their coordinates

Theming

The quadrant chart renderer integrates with Sirena’s theme system.

Configurable Colors

The following theme colors are used:

label_text

Text color for labels and titles

grid_line

Color for axis lines and quadrant borders

node_stroke

Default stroke color for points

primary

Default color for Quadrant 1 points

secondary

Default color for Quadrant 2 points

accent

Default color for Quadrant 3 points

success

Default color for Quadrant 4 points

Typography

The renderer uses theme typography settings:

font_family

Font family for all text

font_size_large

Size for chart title (default: 18)

font_size_normal

Size for quadrant labels (default: 14)

font_size_small

Size for axis labels and point labels (default: 11-12)

Quadrant Background Colors

Default quadrant colors (can be overridden in theme):

  • Quadrant 1 (top-right): #e3f2fd (light blue)

  • Quadrant 2 (top-left): #fff3e0 (light orange)

  • Quadrant 3 (bottom-left): #f3e5f5 (light purple)

  • Quadrant 4 (bottom-right): #e8f5e9 (light green)

Implementation Notes

Model Architecture

The [QuadrantChart](lib/sirena/diagram/quadrant.rb:81) class inherits from [Diagram::Base](lib/sirena/diagram/base.rb:1) and uses Lutaml::Model for serialization.

Key methods:

  • [diagram_type](lib/sirena/diagram/quadrant.rb:112) - Returns :quadrant

  • [valid?](lib/sirena/diagram/quadrant.rb:123) - Validates all points

  • [points_by_quadrant](lib/sirena/diagram/quadrant.rb:134) - Groups points by quadrant

The [QuadrantPoint](lib/sirena/diagram/quadrant.rb:12) class provides:

  • [valid?](lib/sirena/diagram/quadrant.rb:37) - Ensures coordinates are in [0,1] range

  • [quadrant](lib/sirena/diagram/quadrant.rb:53) - Determines which quadrant (1-4) the point is in

Grammar Rules

The Parslet grammar in [lib/sirena/parser/grammars/quadrant.rb](lib/sirena/parser/grammars/quadrant.rb:1) handles:

  • Optional title declarations

  • X-axis and Y-axis with quoted or unquoted labels

  • Quadrant labels (quadrant-1 through quadrant-4)

  • Data points with coordinates and optional styling

  • Class definitions (for future styling support)

  • Comments

Coordinate System

The transform converts normalized coordinates (0-1) to SVG coordinates:

  • X-axis: svg_x = margin + (x * chart_width)

  • Y-axis: svg_y = margin + ((1.0 - y) * chart_height) (inverted for SVG)

Default dimensions:

  • Width: 800px

  • Height: 600px

  • Margin: 80px

  • Chart area: 640x440px

SVG Structure

The renderer creates SVG elements in this order:

  1. Title (if present)

  2. Quadrant background rectangles

  3. Center axis lines (vertical and horizontal)

  4. Axis labels (x-left, x-right, y-bottom, y-top)

  5. Quadrant labels

  6. Data points (circles)

  7. Point labels (text)

Testing

The implementation includes comprehensive tests:

Parser Tests

17 test examples covering:

  • Simple quadrant charts

  • Multiple points

  • Point styling parameters

  • Quoted axis labels

  • Minimal diagrams

  • Quadrant determination

  • All 10 Mermaid fixture files

Run tests with:

bundle exec rspec spec/sirena/parser/quadrant_spec.rb

Test Coverage

  • ✅ All 10 Mermaid fixtures parse successfully

  • ✅ All 10 fixtures render to valid SVG

  • ✅ Point coordinates validated (0-1 range)

  • ✅ Quadrant assignment correct for all points

  • ✅ Styling parameters extracted properly

Known Limitations

  1. Class definitions (classDef) are parsed but not yet applied to rendering

  2. Point labels may overlap if points are close together

  3. No automatic label positioning to avoid overlaps

  4. Fixed canvas dimensions (800x600)

Future Enhancements

  1. Apply classDef styles to points

  2. Smart label positioning to avoid overlaps

  3. Configurable canvas dimensions

  4. Interactive tooltips for points

  5. Legend support

  6. Grid lines within quadrants

  7. Data value display on hover

Back to top

Copyright © 2025 Ribose. Sirena is open source under the MIT license.

This site uses Just the Docs, a documentation theme for Jekyll.