Scales - Cristalyse Documentation - Flutter Data Visualization Library

Overview

Scales in Cristalyse transform data values to visual positions or dimensions on a chart. They handle both continuous and categorical data, ensuring intuitive and precise data representation.

Linear Scales

Linear scales map continuous data to a range, such as pixels:

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'value')
  .scaleXContinuous(min: 0, max: 100) // X-axis with fixed visual range
  .scaleYContinuous(min: 0, max: 200) // Y-axis with fixed visual range
  .geomLine()
  .build()

Axis Titles

New in v1.10.0: Add descriptive titles to your axes for better data context!

All scale methods now accept an optional title parameter to display descriptive axis labels:

CristalyseChart()
  .data(temperatureData)
  .mapping(x: 'hour', y: 'temperature')
  .scaleXContinuous(title: 'Time (hours)')
  .scaleYContinuous(title: 'Temperature (°C)')
  .geomLine()
  .build()

Title Features:

Smart Positioning: Automatically positioned with optimal spacing
Rotated Text: Y-axis titles rotate -90°, Y2-axis titles rotate +90°
Theme-Aware: Inherits text style from theme with slightly larger font
Optional: Only renders when provided (fully backward compatible)

Dual-Axis Example:

CristalyseChart()
  .data(businessData)
  .mapping(x: 'month', y: 'revenue')
  .mappingY2('conversion')
  .geomBar(yAxis: YAxis.primary)
  .geomLine(yAxis: YAxis.secondary)
  .scaleXOrdinal(title: 'Month')
  .scaleYContinuous(title: 'Revenue ($K)')  // Left axis
  .scaleY2Continuous(title: 'Conversion Rate (%)') // Right axis
  .build()

Configuration

Domain: Data range mapped to chart space.
Range: Pixel space where the data is plotted.
Limits: Optional min/max parameters to constrain the displayed scale range.
Title: Optional descriptive label for the axis (v1.10.0+)
Invertible: Values can map back to the data space.

Scale Limits and Data Filtering

Use min and max parameters to control scale behavior:

// Data-driven scaling (default behavior)
CristalyseChart()
  .data(temperatureData) // Values: [15.2, 22.8, 19.5, 16.1]
  .mapping(x: 'hour', y: 'temp')
  .scaleYContinuous() // Scale automatically fits data range
  .geomLine()
  .build()

// Fixed range scaling with limits
CristalyseChart()
  .data(temperatureData)
  .mapping(x: 'hour', y: 'temp')
  .scaleYContinuous(min: 10, max: 30) // Fixed 10-30°C range
  .geomLine()
  .build()

Use limits for consistent ranges across multiple charts and to set explicit meaningful baselines (like 0 for revenue). Without limits, the behavior varies by geometry. Geometries that are value comparisons (Bar Charts, Area Charts) have zero baseline by default. For other geometries, the scale domain is fit to the actual data range (15.2-22.8°C). With limits, the scale domain uses the specified range (10-30°C), including overriding a zero baseline for e.g. Bar Charts and Area Charts. Data points beyond the limits still render proportionally beyond the visual range.

Ordinal Scales

Ordinal scales map categorical data to discrete locations:

CristalyseChart()
  .data(data)
  .mapping(x: 'category', y: 'value')
  .scaleXOrdinal() // X-axis for categories
  .geomBar()
  .build()

With Axis Title:

CristalyseChart()
  .data(salesData)
  .mapping(x: 'product', y: 'revenue')
  .scaleXOrdinal(title: 'Product Category')
  .scaleYContinuous(title: 'Revenue ($K)')
  .geomBar()
  .build()

Configuration

Domain: List of categories.
Range: Space for categories to be displayed.
BandWidth: Space allocated to each category.
Title: Optional descriptive label for the axis (v1.10.0+)

Color Scales

Color scales are used to encode data using color gradients:

CristalyseChart()
  .data(data)
  .mapping(x: 'x', y: 'y', color: 'intensity')
  .geomPoint()
  .theme(
    ChartTheme.defaultTheme().copyWith(
      colorPalette: [Colors.blue, Colors.red], // Gradient
    ),
  )
  .build()

Size Scales

Size scales map data values to sizes, useful for scatter plots:

CristalyseChart()
  .data(data)
  .mapping(x: 'x', y: 'y', size: 'value')
  .geomPoint()
  .build()

Label Formatting

Transform axis labels by passing a callback to the labels parameter on any axis scale that takes any number and returns a string.

Direct NumberFormat Usage

For simple cases, you can use NumberFormat from Dart’s intl package:

import 'package:intl/intl.dart';

// Revenue chart with currency formatting
CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .scaleYContinuous(labels: NumberFormat.simpleCurrency().format) // $1,234.56
  .build()

// Conversion rate chart with percentage formatting
CristalyseChart()
  .data(conversionData)
  .mapping(x: 'month', y: 'rate')
  .scaleYContinuous(labels: NumberFormat.percentPattern().format) // 23%
  .build()

// User growth chart with compact formatting
CristalyseChart()
  .data(userGrowthData)
  .mapping(x: 'date', y: 'users')
  .scaleYContinuous(labels: NumberFormat.compact().format) // 1.2K, 1.5M
  .build()

Custom Callbacks for Advanced Cases

When you need custom logic beyond NumberFormat, use a factory pattern to create a callback based on that logic.

// Create formatter once based on passed locale, reuse callback
static String Function(num) createCurrencyFormatter({String locale = 'en_US'}) {
  final formatter = NumberFormat.simpleCurrency(locale: locale); // Created once
  return (num value) => formatter.format(value); // Reused callback
}

// Usage
final currencyLabels = createCurrencyFormatter();
// uses default here, but could internationalize

// Revenue chart with currency formatting
CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .scaleYContinuous(labels: currencyLabels) // pass callback
  .build()

Conditional Formatting (Value-Based Logic)

// Time duration formatting (seconds to human readable)
static String Function(num) createDurationFormatter() {
  return (num seconds) {
    final roundedSeconds = seconds.round(); // Round to nearest second first
    
    if (roundedSeconds >= 3600) {
      final hours = roundedSeconds / 3600;
      if (hours == hours.round()) {
        return '${hours.round()}h';  // Clean: "1h", "2h", "24h"
      }
      return '${hours.toStringAsFixed(1)}h';  // Decimal: "1.5h", "2.3h"
    } else if (roundedSeconds >= 60) {
      final minutes = (roundedSeconds / 60).round();
      return '${minutes}m';  // "1m", "30m", "59m"
    }
    return '${roundedSeconds}s';  // "5s", "30s", "59s"
  };
}

final usageLabels = createDurationFormatter();

CristalyseChart()
  .data(usageData)
  .mapping(x: 'day', y: 'usage')
  .scaleYContinuous(labels: usageLabels) // pass callback
  .build()

Chart-Optimized Formatting (Clean Integers)

// Implement chart-friendly integer/decimal distinction w/ NumberFormat
static String Function(num) createChartCurrencyFormatter() {
  final formatter = NumberFormat.simpleCurrency(locale: 'en_US');
  return (num value) {
    if (value == value.roundToDouble()) {
      return formatter.format(value).replaceAll('.00', ''); // $42
    }
    return formatter.format(value); // $42.50
  };
}

final currencyLabels = createChartCurrencyFormatter();

CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .scaleYContinuous(labels: currencyLabels)
  .build()

Business Logic Formatting

// Handle negative values differently (P&L charts)
static String Function(num) createProfitLossFormatter() {
  final formatter = NumberFormat.compact(); // Created once
  return (num value) {
    final abs = value.abs();
    final formatted = formatter.format(abs); // Reuse formatter
    return value >= 0 ? formatted : '($formatted)';
  };
}

final currencyLabels = createProfitLossFormatter();

CristalyseChart()
  .data(salesData)
  .mapping(x: 'quarter', y: 'revenue')
  .scaleYContinuous(labels: currencyLabels)
  .build()

// Custom units (basis points for finance - converts decimal rates to bp)
static String Function(num) createBasisPointFormatter() {
  return (num value) => '${(value * 10000).toStringAsFixed(0)}bp';
}

final bpLabels = createBasisPointFormatter();

CristalyseChart()
  .data(yieldData) // Data has decimal rates like 0.0025, 0.0150
  .mapping(x: 'maturity', y: 'yield_rate') // yield_rate is decimal (0.0025 = 25bp)
  .scaleYContinuous(labels: bpLabels) // Converts 0.0025 → "25bp"
  .build()

Tick Configuration

New in v1.14.0: Control how tick marks and labels are generated on your axes!

TickConfig allows you to customize tick generation on continuous scales:

TickConfig(
  ticks: [0, 25, 50, 75, 100],  // Optional: specify explicit tick positions
  simpleLinear: true,            // Optional: use simple linear ticks instead of Wilkinson's algorithm
)

Explicit Tick Specification

Provide your own tick positions for precise control:

CristalyseChart()
  .data(temperatureData)
  .mapping(x: 'hour', y: 'temp')
  .scaleYContinuous(
    tickConfig: TickConfig(
      ticks: [-10, 0, 10, 20, 30],  // Custom tick positions
    ),
  )
  .geomLine()
  .build()

Use cases:

Industry-standard reference points (e.g., freezing point at 0°C)
Domain-specific intervals (e.g., percentiles at 25, 50, 75)
Matching ticks across multiple related charts

Simple Linear Ticking

Generate evenly-spaced ticks instead of using Wilkinson’s algorithm:

CristalyseChart()
  .data(timeSeriesData)
  .mapping(x: 'timestamp', y: 'value')
  .scaleXContinuous(
    tickConfig: TickConfig(simpleLinear: true),
  )
  .scaleYContinuous(
    tickConfig: TickConfig(simpleLinear: true),
  )
  .geomLine()
  .build()

Differences:

Wilkinson’s Algorithm (default): Intelligently chooses “nice” numbers for human-readable labels. Tick intervals vary based on data range (e.g., 10, 25, 50, 100).
Simple Linear: Always generates evenly-spaced ticks. Tick interval is constant based on the scale range divided by number of ticks.

When to use Simple Linear:

Time-based charts where consistent intervals matter (e.g., hourly or daily splits)
Scientific/technical charts where precision is preferred over “niceness”
When you need predictable, uniform spacing

Dual-Axis Example

CristalyseChart()
  .data(businessData)
  .mapping(x: 'month', y: 'revenue')
  .mappingY2('conversion')
  .scaleXOrdinal()
  .scaleYContinuous(
    tickConfig: TickConfig(ticks: [0, 50000, 100000, 150000]),
  )
  .scaleY2Continuous(
    tickConfig: TickConfig(simpleLinear: true),
  )
  .geomBar(yAxis: YAxis.primary)
  .geomLine(yAxis: YAxis.secondary)
  .build()

Scale Customization

Customize scales to fit your data representation needs:

CristalyseChart()
  .data(data)
  .mapping(x: 'day', y: 'hours')
  .scaleXOrdinal()
  .scaleYContinuous(min: 0, max: 24, labels: (v) => '${v}h') // Custom hour labels
  .build()

Best Practices

Scaling Data

Choose linear scales for time-series and numerical data.
Use ordinal scales for categorical data like labels or segments.
Opt for consistent scale units across charts.

Performance

Ensure domain and range values are correctly configured.
Minimize dynamic scale recalculation for better performance.
Use scale inversions in interactive applications for better feedback.

Advanced Usage

Dual Axis Charts

Implement dual axes for complex comparisons:

CristalyseChart()
  .data(dualAxisData)
  .mapping(x: 'month', y: 'revenue')
  .mappingY2('conversion_rate')
  .scaleYContinuous(min: 0, max: 100)
  .scaleY2Continuous(min: 0, max: 1)
  .geomBar(yAxis: YAxis.primary)
  .geomLine(yAxis: YAxis.secondary)
  .build()

Conditional Scales

Dynamically adjust scales based on data:

CristalyseChart()
  .data(dynamicData)
  .mapping(x: 'date', y: 'value')
  .scaleXContinuous(min: startDate, max: endDate)
  .scaleYContinuous(min: minValue, max: maxValue)
  .geomArea()
  .build()

Example Gallery

Time-Series Analysis

Vivid depiction of temporal trends and changes over time.

Categorical Comparison

Clear comparison of discrete categories using ordinal scaling.

Revenue vs. Conversion

Dual-axis chart illustrating financial performance metrics.

Dynamic Data Scaling

Interactive scales adapting to real-time data changes.

Next Steps

Data Mapping

Effective data field-to-visual property mapping techniques.

Custom Themes

Create custom themes to match brand identity.

Performance Scaling

Optimize visual performance with tailored scaling strategies.

Interactions

Engage users with interactive scaled charts.

Technical Details

Review the source code behind scale transformations and extend as needed within the scale.dart file.

​Overview

​Linear Scales

​Axis Titles

​Configuration

​Scale Limits and Data Filtering

​Ordinal Scales

​Configuration

​Color Scales

​Size Scales

​Label Formatting

​Direct NumberFormat Usage

​Custom Callbacks for Advanced Cases

​Conditional Formatting (Value-Based Logic)

​Chart-Optimized Formatting (Clean Integers)

​Business Logic Formatting

​Tick Configuration

​Explicit Tick Specification

​Simple Linear Ticking

​Dual-Axis Example

​Scale Customization

​Best Practices

​Scaling Data

​Performance

​Advanced Usage

​Dual Axis Charts

​Conditional Scales

​Example Gallery

Time-Series Analysis

Categorical Comparison

Revenue vs. Conversion

Dynamic Data Scaling

​Next Steps

Data Mapping

Custom Themes

Performance Scaling

Interactions

​Technical Details

Overview

Linear Scales

Axis Titles

Configuration

Scale Limits and Data Filtering

Ordinal Scales

Configuration

Color Scales

Size Scales

Label Formatting

Direct NumberFormat Usage

Custom Callbacks for Advanced Cases

Conditional Formatting (Value-Based Logic)

Chart-Optimized Formatting (Clean Integers)

Business Logic Formatting

Tick Configuration

Explicit Tick Specification

Simple Linear Ticking

Dual-Axis Example

Scale Customization

Best Practices

Scaling Data

Performance

Advanced Usage

Dual Axis Charts

Conditional Scales

Example Gallery

Next Steps

Technical Details