PyramidTile Documentation

Overview

The PyramidTile is a powerful visualization component designed for the Vantage analytics platform. It generates a pyramid chart that visually represents hierarchical data, making it easier for users to infer insights from relative values associated with different categories. Pyramid charts are ideal for illustrating the proportional representation of values, facilitating comparisons across various segments or dimensions of the data.

Settings

The PyramidTile has several configurable settings that allow users to customize its appearance and behavior. Below is a comprehensive breakdown of each setting.

Properties

• title

  • Input Type: String
  • Description: The main title displayed at the top of the tile. This provides a quick reference for the purpose of the visualization.
  • Default Value: undefined

• subtitle

  • Input Type: String
  • Description: A secondary title that appears below the main title, providing further context or details about the pyramid chart.
  • Default Value: undefined

• footerText

  • Input Type: String
  • Description: Text displayed at the bottom of the tile, often used for additional notes, insights, or data source references.
  • Default Value: undefined

• footerColor

  • Input Type: String (color format)
  • Description: Defines the color of the footer text. Users can specify colors in hex, RGB, or any recognized CSS color format.
  • Default Value: undefined

• data

  • Input Type: Array of objects
  • Description: The data to be visualized in the pyramid chart. Each object should contain keys for labels and values. The chart expects sorted data, usually preprocesses before rendering.
  • Default Value: [] (empty array)

• dataRefIds

  • Input Type: Array of strings
  • Description: References to external data sources. This allows the tile to fetch data from different datasets. If provided, it takes precedence over the data setting.
  • Default Value: [] (empty array)

• config

  • Input Type: Object
  • Description: A configuration object for additional settings, including:

    • showLegend

      • Input Type: Boolean
      • Description: Controls the display of the legend for the chart. If true, the legend is shown; if false, it is hidden.
      • Default Value: true

    • workflows

      • Input Type: Array of Objects
      • Description: Represents any workflows associated with the tile for data processing. This is typically used when fetching data dynamically.
      • Default Value: [] (empty array)

• clickUrl

  • Input Type: String
  • Description: If provided, this URL will be opened when a user clicks on the pyramid chart. This is useful for linking detailed reports or external resources.
  • Default Value: undefined

Behavior and How It Works

1. Data Fetching & Processing

   • The PyramidTile utilizes custom hooks like useTileData and useFullDataset for loading data. It first checks for dataRefIds, and if not available, uses the tile's provided data.
   • Data is processed and validated through a mapping mechanism that ensures the correct structure is maintained.

2. Rendering Logic

   • Once the data is validated and sorted in descending order to create a pyramid shape, the component renders the pyramid chart using the charting engine library components such as FunnelChart, Funnel, and LabelList.
   • The component displays loading states, error messages for data compatibility, and handles user interactions appropriately (e.g., directing to URLs on click).

3. AI Integrations and Data Caching

   • Processed data is temporarily cached in a global state via useDashboardStore to enhance performance and accommodate AI features or contextual analytics, potentially powering advanced insights.

Use Cases & Examples

Use Cases

1. Sales Funnel Analysis

   • Businesses can leverage the PyramidTile to visualize the different stages of a sales funnel to identify drop-off points and conversion rates.

2. Hierarchical Data Representation

   • Organizations with hierarchical structures (e.g., employee levels within departments) can utilize the pyramid chart for a clear depiction of distribution across levels.

3. Resource Allocation Tracking

   • Teams can use the tile to visualize resource allocation across different projects, helping to identify areas of over or underutilization.

Example Configuration

Use Case: Sales Funnel Analysis

Suppose a company wants to visualize the conversion process across different sales stages. They have data structured as follows:

[
  { "label": "Leads", "value": 1000 },
  { "label": "Consultations", "value": 300 },
  { "label": "Proposals", "value": 150 },
  { "label": "Closed Deals", "value": 80 }
]

Configuration Data:

{
  "title": "Sales Funnel Analysis",
  "subtitle": "Visualizing Conversion Rates",
  "footerText": "Data as of Q1 2023",
  "footerColor": "#4CAF50",
  "data": [
    { "label": "Leads", "value": 1000 },
    { "label": "Consultations", "value": 300 },
    { "label": "Proposals", "value": 150 },
    { "label": "Closed Deals", "value": 80 }
  ],
  "dataRefIds": [],
  "config": {
    "showLegend": true,
    "workflows": []
  },
  "clickUrl": "https://company.com/sales-report"
}

In this configuration, the PyramidTile will visualize the sales process effectively, allowing stakeholders to grasp the effectiveness of their sales strategies at a glance.