Chart classes and data models

This page documents the primary chart constructors and the structured data models used by the clean API.

Bar and comparison charts

ASCII horizontal bar chart for performance comparisons.

class textcharts.bar_chart.BarData(label, value, group=None, error=None, is_best=False, is_worst=False)[source]

Bases: object

Data for a single bar.

Parameters:

  • label (str)

  • value (float)

  • group (str | None)

  • error (float | None)

  • is_best (bool)

  • is_worst (bool)

label: str
value: float
group: str | None = None
error: float | None = None
is_best: bool = False
is_worst: bool = False
class textcharts.bar_chart.BarChart(data, title=None, metric_label='Value', sort_by='value', options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Horizontal bar chart rendered in ASCII/Unicode.

Example output: ` Performance Comparison (ms) ──────────────────────────────────────── DuckDB     ████████████████████████  240.5 Polars     ████████████████████      200.1 Pandas     ████████████████████████████████  320.8 `

Parameters:

  • data (Sequence[BarData])

  • title (str | None)

  • metric_label (str)

  • sort_by (str)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

render()[source]

Render the bar chart as a string.

Return type:

str

textcharts.bar_chart.from_data(data, title=None, metric_label='Value', sort_by='value', options=None, subject=None)[source]

Create BarChart from objects with label/value attributes.

Parameters:

  • data (Sequence)

  • title (str | None)

  • metric_label (str)

  • sort_by (str)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

BarChart

ASCII paired comparison bar chart for side-by-side run comparison.

class textcharts.comparison_bar.ComparisonBarData(label, baseline_value, comparison_value, baseline_name='Baseline', comparison_name='Comparison')[source]

Bases: object

Data for a single query comparison between two runs.

Parameters:

  • label (str)

  • baseline_value (float)

  • comparison_value (float)

  • baseline_name (str)

  • comparison_name (str)

label: str
baseline_value: float
comparison_value: float
baseline_name: str = 'Baseline'
comparison_name: str = 'Comparison'
class textcharts.comparison_bar.ComparisonBar(data, title=None, metric_label='Value', options=None, subtitle=None, subject=None, lower_is_better=True)[source]

Bases: ChartBase

Paired comparison bar chart showing side-by-side bars per query.

Parameters:

  • data (Sequence[ComparisonBarData])

  • title (str | None)

  • metric_label (str)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

  • lower_is_better (bool)

STABLE_THRESHOLD_PCT = 2.0
render()[source]

Render the paired comparison bar chart as a string.

Return type:

str

textcharts.comparison_bar.from_data(data, title=None, metric_label='Value', options=None, subject=None)[source]

Create ComparisonBar from comparison data.

Accepts ComparisonBarData objects or dicts with compatible keys.

Parameters:

  • data (Sequence)

  • title (str | None)

  • metric_label (str)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

ComparisonBar

ASCII diverging bar chart for regression/improvement distribution.

class textcharts.diverging_bar.DivergingBarData(label, pct_change)[source]

Bases: object

Data for a single item in a diverging bar chart.

Parameters:

  • label (str)

  • pct_change (float)

label: str
pct_change: float
class textcharts.diverging_bar.DivergingBar(data, title=None, clip_pct=200.0, options=None, subtitle=None, subject=None, lower_is_better=True)[source]

Bases: ChartBase

Diverging bar chart showing percentage changes centered on zero.

Parameters:

  • data (Sequence[DivergingBarData])

  • title (str | None)

  • clip_pct (float)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

  • lower_is_better (bool)

DEFAULT_CLIP_PCT = 200.0
render()[source]

Render the diverging bar chart as a string.

Return type:

str

textcharts.diverging_bar.from_data(data, title=None, options=None, subject=None)[source]

Create DivergingBar from regression data.

Accepts DivergingBarData objects or dicts with compatible keys.

Parameters:

  • data (Sequence)

  • title (str | None)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

DivergingBar

ASCII stacked bar chart for benchmark phase time decomposition.

class textcharts.stacked_bar.StackedBarSegment(phase_name, value, color=None)[source]

Bases: object

A single segment within a stacked bar.

Parameters:

  • phase_name (str)

  • value (float)

  • color (str | None)

phase_name: str
value: float
color: str | None = None
class textcharts.stacked_bar.StackedBarData(label, segments=<factory>, total=None)[source]

Bases: object

Stacked bar data for a single platform.

Parameters:
label: str
segments: list[StackedBarSegment]
total: float | None = None
class textcharts.stacked_bar.StackedBar(data, title=None, options=None, subtitle=None, metric_label='', value_formatter=None, subject=None)[source]

Bases: ChartBase

Stacked horizontal bar chart showing phase-level time decomposition.

Each bar represents a platform and the segments show time spent in each benchmark phase. Each phase uses a distinct fill character and color.

Example output: ` Phase Breakdown by Platform ────────────────────────────────────────────────────── DuckDB   ░░▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓██████              12.4s Polars   ░░░▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓████████████          15.2s SQLite   ░░░░▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓████████████████     28.7s ────────────────────────────────────────────────────── ░ DataGen  ▒ Load  ▓ Power  █ Throughput `

Parameters:

  • data (Sequence[StackedBarData])

  • title (str | None)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • metric_label (str)

  • value_formatter (Callable[[float], str] | None)

  • subject (str | None)

render()[source]

Render the stacked bar chart as a string.

Return type:

str

textcharts.stacked_bar.from_data(data, title=None, options=None, subject=None)[source]

Create StackedBar from phase breakdown data.

Parameters:

  • data (Sequence[StackedBarData]) – Sequence of StackedBarData instances.

  • title (str | None) – Optional chart title.

  • options (ChartOptions | None) – Chart rendering options.

  • subject (str | None) – Domain noun phrase prepended to default title.

Returns:

Configured StackedBar instance.

Return type:

StackedBar

Distribution charts

ASCII vertical bar histogram for frequency distribution visualization.

class textcharts.histogram.HistogramBar(label, value, platform=None, error=None, is_best=False, is_worst=False)[source]

Bases: object

Data for a single histogram bar.

Parameters:

  • label (str)

  • value (float)

  • platform (str | None)

  • error (float | None)

  • is_best (bool)

  • is_worst (bool)

label: str
value: float
platform: str | None = None
error: float | None = None
is_best: bool = False
is_worst: bool = False
class textcharts.histogram.Histogram(data, title=None, y_label='Value', sort_by='label', max_per_chart=33, show_mean_line=True, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Vertical bar histogram for frequency distribution visualization.

Parameters:

  • data (Sequence[HistogramBar])

  • title (str | None)

  • y_label (str)

  • sort_by (str)

  • max_per_chart (int)

  • show_mean_line (bool)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

DEFAULT_MAX_BARS = 33
render()[source]

Render the histogram as a string (may contain multiple charts).

Return type:

str

textcharts.histogram.from_data(data, title=None, y_label='Value', sort_by='label', max_per_chart=33, show_mean_line=True, options=None, subject=None)[source]

Create Histogram from objects with label/value attributes.

Parameters:

  • data (Sequence)

  • title (str | None)

  • y_label (str)

  • sort_by (str)

  • max_per_chart (int)

  • show_mean_line (bool)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

Histogram

ASCII box plot for distribution visualization.

class textcharts.box_plot.BoxPlotStats(min_val, q1, median, q3, max_val, mean, std, outliers)[source]

Bases: object

Computed statistics for a box plot.

Parameters:

  • min_val (float)

  • q1 (float)

  • median (float)

  • q3 (float)

  • max_val (float)

  • mean (float)

  • std (float)

  • outliers (list[float])

min_val: float
q1: float
median: float
q3: float
max_val: float
mean: float
std: float
outliers: list[float]
textcharts.box_plot.compute_quartiles(values)[source]

Compute box plot statistics from a sequence of values.

Parameters:

values (Sequence[float])

Return type:

BoxPlotStats

class textcharts.box_plot.BoxPlotSeries(name, values)[source]

Bases: object

Data series for box plot.

Parameters:

  • name (str)

  • values (Sequence[float])

name: str
values: Sequence[float]
class textcharts.box_plot.BoxPlot(series, title=None, y_label='Value', show_stats=True, show_mean=True, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

ASCII box plot for showing distributions.

Parameters:

  • series (Sequence[BoxPlotSeries])

  • title (str | None)

  • y_label (str)

  • show_stats (bool)

  • show_mean (bool)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

BOX_TOP = '┬'
BOX_BOTTOM = '┴'
BOX_LEFT = '├'
BOX_RIGHT = '┤'
WHISKER_H = '─'
WHISKER_V_TOP = '╷'
WHISKER_V_BOTTOM = '╵'
MEDIAN_LINE = '│'
OUTLIER = 'o'
render()[source]

Render the box plot as a string.

Return type:

str

textcharts.box_plot.from_series(series, title=None, y_label='Value', show_stats=True, show_mean=True, options=None, subject=None)[source]

Create BoxPlot from objects with name/values attributes.

Parameters:

  • series (Sequence)

  • title (str | None)

  • y_label (str)

  • show_stats (bool)

  • show_mean (bool)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

BoxPlot

ASCII percentile ladder chart for tail-latency visualization.

class textcharts.percentile_ladder.PercentileData(name, p50, p90, p95, p99)[source]

Bases: object

Percentile latency data for a single platform.

Parameters:

  • name (str)

  • p50 (float)

  • p90 (float)

  • p95 (float)

  • p99 (float)

name: str
p50: float
p90: float
p95: float
p99: float
textcharts.percentile_ladder.compute_percentile(values, p)[source]

Compute the p-th percentile using linear interpolation.

Parameters:

  • values (Sequence[float]) – Sequence of numeric values (will be sorted internally).

  • p (float) – Percentile in range [0, 100].

Returns:

Interpolated percentile value.

Return type:

float

class textcharts.percentile_ladder.PercentileLadder(data, title=None, metric_label='', options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

ASCII percentile ladder chart showing P50/P90/P95/P99 latency bands.

Each platform gets a single row with layered horizontal bar segments where each percentile extends further right, creating a “ladder” appearance.

Example output: ` Percentile Latency by Platform (ms) ──────────────────────────────────────────────────────── DuckDB   ░░░░░░░░░▒▒▒▒▒▓▓██          12 | 45 | 78 | 120 Polars   ░░░░░░░░░░▒▒▒▒▒▒▓▓▓▓██████  15 | 52 | 95 | 310 ──────────────────────────────────────────────────────── ░ P50   ▒ P90   ▓ P95   █ P99 `

Parameters:

  • data (Sequence[PercentileData])

  • title (str | None)

  • metric_label (str)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

BAND_COLORS = ('#1b9e77', '#e6ab02', '#d95f02', '#e7298a')
render()[source]

Render the percentile ladder chart as a string.

Return type:

str

textcharts.percentile_ladder.from_series(platform_queries, title=None, metric_label='ms', options=None, subject=None)[source]

Create PercentileLadder from raw query timing data.

Parameters:

  • platform_queries (Sequence[tuple[str, Sequence[float]]]) – Sequence of (platform_name, query_times) tuples.

  • title (str | None) – Optional chart title.

  • metric_label (str) – Unit label for values.

  • options (ChartOptions | None) – Chart rendering options.

  • subject (str | None)

Returns:

Configured PercentileLadder instance.

Return type:

PercentileLadder

ASCII CDF (Cumulative Distribution Function) chart for latency distribution.

class textcharts.cdf_chart.CDFSeriesData(name, values)[source]

Bases: object

CDF series data for a single platform.

Parameters:

  • name (str)

  • values (list[float])

name: str
values: list[float]
class textcharts.cdf_chart.CDFChart(data, title=None, x_label='Value', y_label='Cumulative Share', height=15, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

CDF chart showing cumulative distribution of query latency.

Parameters:

  • data (Sequence[CDFSeriesData])

  • title (str | None)

  • x_label (str)

  • y_label (str)

  • height (int)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

PLOT_HEIGHT = 15
render()[source]

Render the CDF chart as a string.

Return type:

str

textcharts.cdf_chart.from_series(platform_queries, title=None, x_label='Value', y_label='Cumulative Share', options=None, subject=None)[source]

Create CDFChart from raw query timing data.

Parameters:

  • platform_queries (Sequence[tuple[str, Sequence[float]]]) – Sequence of (platform_name, query_times) tuples.

  • title (str | None) – Optional chart title.

  • options (ChartOptions | None) – Chart rendering options.

  • x_label (str)

  • y_label (str)

  • subject (str | None)

Returns:

Configured CDFChart instance.

Return type:

CDFChart

Trend and relationship charts

ASCII line chart for time series visualization.

class textcharts.line_chart.LinePoint(series, x, y, label=None)[source]

Bases: object

Data point for line chart.

Parameters:

  • series (str)

  • x (float | str)

  • y (float)

  • label (str | None)

series: str
x: float | str
y: float
label: str | None = None
class textcharts.line_chart.LineChart(points, title=None, x_label='X', y_label='Y', show_trend=False, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

ASCII line chart for time series and trend visualization.

Parameters:

  • points (Sequence[LinePoint])

  • title (str | None)

  • x_label (str)

  • y_label (str)

  • show_trend (bool)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

MARKERS = ['*', '+', 'o', 'x', '^', 'v', '#', '@']
render()[source]

Render the line chart as a string.

Return type:

str

textcharts.line_chart.from_points(points, title=None, x_label='Run', y_label='Y', show_trend=False, options=None, subject=None)[source]

Create LineChart from objects with series/x/y attributes.

Parameters:

  • points (Sequence)

  • title (str | None)

  • x_label (str)

  • y_label (str)

  • show_trend (bool)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

LineChart

ASCII scatter plot for two-dimensional data.

class textcharts.scatter_plot.ScatterPoint(name, x, y, is_pareto=False)[source]

Bases: object

Data point for scatter plot.

Parameters:

  • name (str)

  • x (float)

  • y (float)

  • is_pareto (bool)

name: str
x: float
y: float
is_pareto: bool = False
class textcharts.scatter_plot.ScatterPlot(points, title=None, x_label='X', y_label='Y', show_pareto=True, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

ASCII scatter plot for two-dimensional data visualization.

Parameters:

  • points (Sequence[ScatterPoint])

  • title (str | None)

  • x_label (str)

  • y_label (str)

  • show_pareto (bool)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

MARKERS = ('*', '+', 'o', 'x', '^', 'v', '#', '@')
MARKER_FRONTIER = '─'
render()[source]

Render the scatter plot as a string.

Return type:

str

textcharts.scatter_plot.from_points(points, title=None, x_label='X', y_label='Y', show_pareto=True, options=None, subject=None)[source]

Create ScatterPlot from objects with name/x/y attributes.

Parameters:

  • points (Sequence)

  • title (str | None)

  • x_label (str)

  • y_label (str)

  • show_pareto (bool)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

ScatterPlot

ASCII normalized speedup chart showing relative performance vs a baseline.

class textcharts.normalized_speedup.SpeedupData(name, ratio, is_baseline=False)[source]

Bases: object

Normalized speedup data for a single platform.

Parameters:

  • name (str)

  • ratio (float)

  • is_baseline (bool)

name: str
ratio: float
is_baseline: bool = False
class textcharts.normalized_speedup.NormalizedSpeedup(data, title=None, baseline_name=None, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Normalized speedup chart showing platform performance relative to a baseline.

Parameters:

  • data (Sequence[SpeedupData])

  • title (str | None)

  • baseline_name (str | None)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

render()[source]

Render the normalized speedup chart as a string.

Return type:

str

textcharts.normalized_speedup.from_ratios(platform_times, baseline=None, title=None, options=None, subject=None)[source]

Create NormalizedSpeedup from platform timing data.

Parameters:

  • platform_times (Sequence[tuple[str, float]]) – Sequence of (platform_name, total_time_ms) tuples.

  • baseline (str | None) – Name of baseline platform, or “slowest”/”fastest” for auto-selection.

  • title (str | None) – Optional chart title.

  • options (ChartOptions | None) – Chart rendering options.

  • subject (str | None)

Returns:

Configured NormalizedSpeedup instance.

Return type:

NormalizedSpeedup

Tabular and matrix charts

ASCII heatmap for query x platform comparison.

class textcharts.heatmap.Heatmap(matrix, row_labels, col_labels, title=None, value_label='', x_label='Columns', show_values=True, color_scheme='diverging', options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

ASCII heatmap showing query execution times across platforms.

Parameters:

  • matrix (Sequence[Sequence[float | None]])

  • row_labels (Sequence[str])

  • col_labels (Sequence[str])

  • title (str | None)

  • value_label (str)

  • x_label (str)

  • show_values (bool)

  • color_scheme (str)

  • options (ChartOptions | None)

  • subtitle (str | None)

  • subject (str | None)

COLOR_SCALE_SEQUENTIAL = ['#1b9e77', '#66a61e', '#e6ab02', '#d95f02', '#e7298a']
COLOR_SCALE_DIVERGING = ['#2166ac', '#67a9cf', '#f7f7f7', '#ef8a62', '#b2182b']
BG_SCALE_SEQUENTIAL = ['#1b9e77', '#66a61e', '#e6ab02', '#d95f02', '#e7298a']
FG_ON_BG_SEQUENTIAL = ['#000000', '#000000', '#000000', '#000000', '#ffffff']
BG_SCALE_DIVERGING = ['#4393c3', '#92c5de', '#d1e5f0', '#fdb863', '#d6604d']
FG_ON_BG = ['#000000', '#000000', '#000000', '#000000', '#ffffff']
render()[source]

Render the heatmap as a string.

Return type:

str

textcharts.heatmap.from_matrix(matrix, queries, platforms, title=None, value_label='', x_label='Platform', show_values=True, color_scheme='diverging', options=None, subject=None)[source]

Create Heatmap from matrix data (compatible with QueryHeatmap).

Parameters:

  • matrix (Sequence[Sequence[float]])

  • queries (Sequence[str])

  • platforms (Sequence[str])

  • title (str | None)

  • value_label (str)

  • x_label (str)

  • show_values (bool)

  • color_scheme (str)

  • options (ChartOptions | None)

  • subject (str | None)

Return type:

Heatmap

ASCII rank table chart for competitive ranking.

class textcharts.rank_table.RankTableData(items, groups, values)[source]

Bases: object

Data for a rank table chart.

Parameters:

  • items (list[str])

  • groups (list[str])

  • values (dict[tuple[str, str], float])

items: list[str]
groups: list[str]
values: dict[tuple[str, str], float]
class textcharts.rank_table.RankTable(data, title=None, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Rank table showing per-item competitive rankings across groups.

Each cell shows the ordinal rank (1st, 2nd, 3rd…) of each platform for each query, with aggregate win/loss tallies and geometric mean rank.

Example output: ` Query Rankings (1st = fastest) ────────────────────────────────────── Query    DuckDB  Polars  SQLite  Pandas Q1        1st     2nd     3rd     4th Q2        2nd     1st     3rd     4th ────────────────────────────────────── 1st wins    15      5       2       0 GeoRank   1.2    1.8     2.8     3.9 `

Parameters:
render()[source]

Render the rank table as a string.

Return type:

str

textcharts.rank_table.from_matrix(matrix, items, groups, title=None, options=None, subject=None)[source]

Create RankTable from the same matrix format as Heatmap.

Parameters:

  • matrix (Sequence[Sequence[float]]) – 2D matrix of numeric values [item_idx][group_idx].

  • items (Sequence[str]) – Item labels (row labels).

  • groups (Sequence[str]) – Group labels (column labels).

  • title (str | None) – Optional chart title.

  • options (ChartOptions | None) – Chart rendering options.

  • subject (str | None)

Returns:

Configured RankTable instance.

Return type:

RankTable

ASCII sparkline table for compact multi-metric comparison.

class textcharts.sparkline_table.SparklineColumn(name, values, higher_is_better=False)[source]

Bases: object

A single metric column in the sparkline table.

Parameters:

  • name (str)

  • values (dict[str, float])

  • higher_is_better (bool)

name: str
values: dict[str, float]
higher_is_better: bool = False
class textcharts.sparkline_table.SparklineTableData(rows, columns=<factory>)[source]

Bases: object

Complete data for a sparkline table.

Parameters:
rows: list[str]
columns: list[SparklineColumn]
class textcharts.sparkline_table.SparklineTable(data, title=None, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Sparkline table showing compact multi-metric comparison.

Each row is an entry, each column is a metric with an inline sparkline bar showing the relative value. Best values are highlighted.

Example output: ` Comparison Overview ────────────────────────────────────────────────────────────── Row        Total(ms)   GeoMean    P99(ms)   Load(s)   Success DuckDB     ▇  1,240    ▇  56      ▅ 120     ▂  2.1    ████ 100% Polars     ▆  1,580    ▆  72      ▇ 310     ▁  1.2    ████ 100% SQLite     ▃  4,820    ▃ 219      ▃ 450     ▅  8.4    ███░  95% `

Parameters:
render()[source]

Render the sparkline table as a string.

Return type:

str

textcharts.sparkline_table.from_data(rows, metrics, title=None, options=None, subject=None)[source]

Create SparklineTable from metric data.

Parameters:

  • rows (list[str]) – List of row names.

  • metrics (list[tuple[str, dict[str, float], bool]]) – List of (metric_name, {row: value}, higher_is_better) tuples.

  • title (str | None) – Optional chart title.

  • options (ChartOptions | None) – Chart rendering options.

  • subject (str | None)

Returns:

Configured SparklineTable instance.

Return type:

SparklineTable

ASCII summary box renderer for aggregate statistics.

class textcharts.summary_box.SummaryStats(title='Summary', primary_value=None, secondary_value=None, total_value=None, primary_baseline=None, primary_comparison=None, total_baseline=None, total_comparison=None, baseline_name='Baseline', comparison_name='Comparison', num_items=0, num_improved=0, num_stable=0, num_regressed=0, best_items=<factory>, worst_items=<factory>, primary_label='Primary', secondary_label='Secondary', total_label='Total', count_label='Items', metric_label='ms', value_formatter=None, lower_is_better=True, environment=None, platform_config=None)[source]

Bases: object

Aggregate statistics for a summary box.

For single-run summaries, only the primary fields are used. For comparison summaries, both baseline and comparison fields are used.

Parameters:

  • title (str)

  • primary_value (float | None)

  • secondary_value (float | None)

  • total_value (float | None)

  • primary_baseline (float | None)

  • primary_comparison (float | None)

  • total_baseline (float | None)

  • total_comparison (float | None)

  • baseline_name (str)

  • comparison_name (str)

  • num_items (int)

  • num_improved (int)

  • num_stable (int)

  • num_regressed (int)

  • best_items (list[tuple[str, float]])

  • worst_items (list[tuple[str, float]])

  • primary_label (str)

  • secondary_label (str)

  • total_label (str)

  • count_label (str)

  • metric_label (str)

  • value_formatter (Callable[[float], str] | None)

  • lower_is_better (bool)

  • environment (dict[str, str] | None)

  • platform_config (dict[str, str] | None)

title: str = 'Summary'
primary_value: float | None = None
secondary_value: float | None = None
total_value: float | None = None
primary_baseline: float | None = None
primary_comparison: float | None = None
total_baseline: float | None = None
total_comparison: float | None = None
baseline_name: str = 'Baseline'
comparison_name: str = 'Comparison'
num_items: int = 0
num_improved: int = 0
num_stable: int = 0
num_regressed: int = 0
best_items: list[tuple[str, float]]
worst_items: list[tuple[str, float]]
primary_label: str = 'Primary'
secondary_label: str = 'Secondary'
total_label: str = 'Total'
count_label: str = 'Items'
metric_label: str = 'ms'
value_formatter: Callable[[float], str] | None = None
lower_is_better: bool = True
environment: dict[str, str] | None = None
platform_config: dict[str, str] | None = None
property is_comparison: bool

Whether this is a comparison summary (two runs).

class textcharts.summary_box.SummaryBox(stats, options=None, subtitle=None, subject=None)[source]

Bases: ChartBase

Bordered summary panel with aggregate statistics.

Displays key metrics in a box-drawing bordered panel. Supports both single-run and comparison summaries.

Example output: ` ┌──────────────────────────────────────┐ │            Summary                   │ ├──────────────────────────────────────┤ │  Primary:  142.3ms → 98.7ms  -30.6% │ │  Total:    3.2s → 2.1s       -34.4% │ ├──────────────────────────────────────┤ │  5 improved  12 stable  5 regressed  │ ├──────────────────────────────────────┤ │  Best:  Q6 (-57.2%), Q14 (-38.1%)   │ │  Worst: Q21 (+726%), Q17 (+23.4%)   │ └──────────────────────────────────────┘ `

Parameters:
render()[source]

Render the summary box as a string.

Return type:

str