1// Note(alexwlchan, 2026-11-04): This file was retrieved from
2// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/internal/benchtab/table.go
4// The only modification is updating the import for internal/texttab.
6// Copyright 2020 The Go Authors. All rights reserved.
7// Use of this source code is governed by a BSD-style
8// license that can be found in the LICENSE file.
18 "alexwlchan.net/gotools/internal/texttab"
19 "golang.org/x/perf/benchmath"
20 "golang.org/x/perf/benchproc"
21 "golang.org/x/perf/benchunit"
24// A Table summarizes and compares benchmark results in a 2D grid.
25// Each cell summarizes a Sample of results with identical row and
26// column Keys. Comparisons are done within each row between the
27// Sample in the first column and the Samples in any remaining
30 // Opts is the configuration options for this table.
33 // Unit is the benchmark unit of all samples in this Table.
36 // Assumption is the distributional assumption used for all
37 // samples in this table.
38 Assumption benchmath.Assumption
40 // Rows and Cols give the sequence of row and column Keys
41 // in this table. All row Keys have the same Projection and all
42 // col Keys have the same Projection.
43 Rows, Cols []benchproc.Key
45 // Cells contain the cells in the body of this table. Each key in
46 // this map is a pair of some Key from Rows and some Key
47 // from Cols. However, not all Pairs may be present in the
49 Cells map[TableKey]*TableCell
51 // Summary is the final row of this table, which gives summary
52 // information across all benchmarks in this table. It is
54 Summary map[benchproc.Key]*TableSummary
56 // SummaryLabel is the label for the summary row.
60// TableKey is a map key used to index a single cell in a Table.
62 Row, Col benchproc.Key
65// TableCell is a single cell in a Table. It represents a sample of
66// benchmark results with the same row and column Key.
67type TableCell struct {
68 // Sample is the set of benchmark results in this cell.
69 Sample *benchmath.Sample
71 // Summary is the summary of Sample, as computed by the
72 // Table's distributional assumption.
73 Summary benchmath.Summary
75 // Baseline is the baseline cell used for comparisons with
76 // this cell, or nil if there is no comparison. This is the
77 // cell in the first column of this cell's row, if any.
80 // Comparison is the comparison with the Baseline cell, as
81 // computed by the Table's distributional assumption. If
82 // Baseline is nil, this value is meaningless.
83 Comparison benchmath.Comparison
86// TableSummary is a cell that summarizes a column of a Table.
87// It appears in the last row of a table.
88type TableSummary struct {
89 // HasSummary indicates that Summary is valid.
91 // Summary summarizes all of the TableCell.Summary values in
95 // HasRatio indicates that Ratio is valid.
97 // Ratio summarizes all of the TableCell.Comparison values in
101 // Warnings is a list of warnings for this summary cell.
105// RowScaler returns a common scaler for the values in row.
106func (t *Table) RowScaler(row benchproc.Key, unitClass benchunit.Class) benchunit.Scaler {
107 // Collect the row summaries.
109 for _, col := range t.Cols {
110 cell, ok := t.Cells[TableKey{row, col}]
112 values = append(values, cell.Summary.Center)
115 return benchunit.CommonScale(values, unitClass)
118// ToText renders t to a textual representation, assuming a
120func (t *Table) ToText(w io.Writer, color bool) error {
123 // Each logical column expands to centerCols columns, plus
124 // deltaCols columns if there's a baseline.
126 const centerCols = 3 // <center ±> <CI> <warnings>
127 const deltaCols = 3 // <P%> <(p=0.PPP n=N)> <warnings>
129 // startCol returns the index of the first centerCol of
130 // logical column exp.
131 startCol := func(exp int) int {
135 // The width of experiment 0 is just centerCols. All
136 // later experiments are centerCols+deltaCols.
137 return labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
140 var warningList []string
141 warningSet := make(map[string]int)
142 warn := func(msgs ...[]error) {
143 var footnotes []string
144 for _, msgs1 := range msgs {
145 for _, msg := range msgs1 {
147 i, ok := warningSet[s]
151 warningList = append(warningList, s)
153 footnotes = append(footnotes, superscript(i+1))
156 s := strings.Join(footnotes, " ")
160 // Construct the header.
161 kt := benchproc.NewKeyHeader(t.Cols)
162 rEdge := startCol(len(t.Cols) + 1)
165 // Process this level.
166 var nextNodes []*benchproc.KeyHeaderNode
168 for _, node := range nodes {
169 l := startCol(node.Start)
170 r := startCol(node.Start + node.Len)
171 // Configuration headers can span a lot of
172 // columns, so we add a vertical rule to more
173 // clearly delineate the columns they span. We
174 // also add some space so that each logical
175 // column in the rest of the table is better
177 o.Col(l).Span(r-l, node.Value, texttab.Center, texttab.LeftMargin(" │ "))
178 nextNodes = append(nextNodes, node.Children...)
180 // Add a vertical bar down the right side to match the other
182 o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
186 // Add the column labels row, set margins, and create stretch
189 for i := range t.Cols {
193 // Show the unit over the center column group, since
194 // these are values in that unit.
195 o.Span(centerCols, t.Unit, texttab.Center, texttab.LeftMargin(" │ "))
198 // All but the first column will have A/B
201 // Separate center and delta column groups by
203 o.Span(deltaCols, "vs base", texttab.Left, texttab.LeftMargin(" "))
206 // Make all of the interior columns in this column
207 // group shrink columns, leaving on the leftmost and
208 // rightmost to stretch.
209 for j := l + 1; j < o.CurCol(); j++ {
213 o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
215 // Emit measurements.
216 unitClass := benchunit.ClassOf(t.Unit)
217 for _, row := range t.Rows {
220 // TODO: Should I put each row key value in a
221 // column? With the keys as headers?
222 o.Cell(row.StringValues())
224 // Get a common scalar across this row.
225 scalar := t.RowScaler(row, unitClass)
227 for exp, col := range t.Cols {
228 cell, ok := t.Cells[TableKey{row, col}]
234 o.Cell(scalar.Format(cell.Summary.Center), texttab.Right)
235 // Put ± in the margin so 1) the ±s line up,
236 // 2) the geomean value (which doesn't have ±)
237 // aligns with the summary column, 3) we can
238 // right align the range column.
239 o.Cell(cell.Summary.PctRangeString(), texttab.Right, texttab.LeftMargin(" ± "))
240 warn(cell.Sample.Warnings, cell.Summary.Warnings)
241 if exp > 0 && cell.Baseline != nil {
242 d := cell.Comparison.FormatDelta(cell.Baseline.Summary.Center, cell.Summary.Center)
243 // TODO: Color the delta for whether
245 o.Cell(d, texttab.Right)
246 o.Cell("(" + cell.Comparison.String() + ")")
247 warn(cell.Comparison.Warnings)
255 o.Cell(t.SummaryLabel)
256 for exp, col := range t.Cols {
257 tsum, ok := t.Summary[col]
264 o.Cell(benchunit.Scale(tsum.Summary, unitClass), texttab.Right)
267 o.Col(startCol(exp) + centerCols)
269 o.Cell(fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100), texttab.Right)
275 o.Col(startCol(exp+1) - 1)
281 if err := o.Format(w); err != nil {
286 if len(warningList) > 0 {
287 for i, msg := range warningList {
288 if _, err := fmt.Fprintf(w, "%s %s\n", superscript(i+1), msg); err != nil {
297var superDigits = []rune("⁰¹²³⁴⁵⁶⁷⁸⁹")
299func superscript(i int) string {
301 return string(superDigits[0])
306 for i > 0 && pos > 0 {
308 buf[pos] = superDigits[i%10]
311 return string(buf[pos:])
314// ToCSV renders t to CSV format. Warnings are written in text format
315// to the "warnings" Writer, and prefixed with spreadsheet-style cell
316// references. These references assume the table begins on row
318func (t *Table) ToCSV(o *csv.Writer, startRow int, warnings io.Writer) (rowCount int) {
320 const centerCols = 2 // <center> <CI>
321 const deltaCols = 2 // <P%> <(p=0.PPP n=N)>
322 startCol := func(exp int) int {
324 // Baseline, so no delta.
327 // Center and delta columns.
328 l := labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
331 row := make([]string, startCol(len(t.Cols)))
333 clearTo := func(col int) {
335 row = append(row, "")
343 warn := func(msgs []error) {
344 // Construct a spreadsheet-style cell label.
345 colName := make([]byte, 10)
346 colNamePos := len(colName)
347 for x := len(row); x > 0; {
349 colName[colNamePos] = 'A' + byte(x%26)
352 if colNamePos == len(colName) {
354 colName[colNamePos] = 'A'
356 colName = colName[colNamePos:]
358 for _, msg := range msgs {
359 fmt.Fprintf(warnings, "%s%d: %s\n", colName, startRow+rowCount, msg)
363 // Emit column configurations header.
364 colFields := t.Cols[0].Projection().FlattenedFields()
365 for _, field := range colFields {
366 for exp, key := range t.Cols {
367 clearTo(startCol(exp))
368 row = append(row, key.Get(field))
370 clearTo(startCol(len(t.Cols)))
374 // Emit column headers.
375 for exp := range t.Cols {
376 clearTo(startCol(exp))
377 row = append(row, t.Unit, "CI")
379 row = append(row, "vs base", "P")
385 for _, rowKey := range t.Rows {
386 row = append(row, rowKey.StringValues())
387 for exp, colKey := range t.Cols {
388 cell, ok := t.Cells[TableKey{rowKey, colKey}]
393 clearTo(startCol(exp))
394 warn(cell.Sample.Warnings)
395 warn(cell.Summary.Warnings)
397 fmt.Sprint(cell.Summary.Center),
398 cell.Summary.PctRangeString(),
400 if exp > 0 && cell.Baseline != nil {
401 warn(cell.Comparison.Warnings)
403 cell.Comparison.FormatDelta(cell.Baseline.Summary.Center, cell.Summary.Center),
404 cell.Comparison.String(),
412 row = append(row, t.SummaryLabel)
413 for exp, key := range t.Cols {
414 tsum, ok := t.Summary[key]
419 clearTo(startCol(exp))
422 row = append(row, fmt.Sprint(tsum.Summary))
425 clearTo(startCol(exp) + centerCols)
427 row = append(row, fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100))
429 row = append(row, "?")
433 clearTo(startCol(len(t.Cols)))