Skip to main content

internal/benchtab/table.go

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
3//
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.
10package benchtab
12import (
13 "encoding/csv"
14 "fmt"
15 "io"
16 "strings"
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
28// columns.
29type Table struct {
30 // Opts is the configuration options for this table.
31 Opts TableOpts
33 // Unit is the benchmark unit of all samples in this Table.
34 Unit string
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
48 // map.
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
53 // keyed by Cols.
54 Summary map[benchproc.Key]*TableSummary
56 // SummaryLabel is the label for the summary row.
57 SummaryLabel string
60// TableKey is a map key used to index a single cell in a Table.
61type TableKey struct {
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.
78 Baseline *TableCell
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.
90 HasSummary bool
91 // Summary summarizes all of the TableCell.Summary values in
92 // this column.
93 Summary float64
95 // HasRatio indicates that Ratio is valid.
96 HasRatio bool
97 // Ratio summarizes all of the TableCell.Comparison values in
98 // this column.
99 Ratio float64
101 // Warnings is a list of warnings for this summary cell.
102 Warnings []error
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.
108 var values []float64
109 for _, col := range t.Cols {
110 cell, ok := t.Cells[TableKey{row, col}]
111 if ok {
112 values = append(values, cell.Summary.Center)
113 }
114 }
115 return benchunit.CommonScale(values, unitClass)
118// ToText renders t to a textual representation, assuming a
119// fixed-width font.
120func (t *Table) ToText(w io.Writer, color bool) error {
121 var o texttab.Table
123 // Each logical column expands to centerCols columns, plus
124 // deltaCols columns if there's a baseline.
125 const labelCols = 1
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 {
132 if exp == 0 {
133 return labelCols
134 }
135 // The width of experiment 0 is just centerCols. All
136 // later experiments are centerCols+deltaCols.
137 return labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
138 }
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 {
146 s := msg.Error()
147 i, ok := warningSet[s]
148 if !ok {
149 i = len(warningList)
150 warningSet[s] = i
151 warningList = append(warningList, s)
152 }
153 footnotes = append(footnotes, superscript(i+1))
154 }
155 }
156 s := strings.Join(footnotes, " ")
157 o.Cell(s)
158 }
160 // Construct the header.
161 kt := benchproc.NewKeyHeader(t.Cols)
162 rEdge := startCol(len(t.Cols) + 1)
163 nodes := kt.Top
164 for len(nodes) > 0 {
165 // Process this level.
166 var nextNodes []*benchproc.KeyHeaderNode
167 o.Row()
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
176 // separated.
177 o.Col(l).Span(r-l, node.Value, texttab.Center, texttab.LeftMargin(" │ "))
178 nextNodes = append(nextNodes, node.Children...)
179 }
180 // Add a vertical bar down the right side to match the other
181 // separators.
182 o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
183 nodes = nextNodes
184 }
186 // Add the column labels row, set margins, and create stretch
187 // columns.
188 o.Row()
189 for i := range t.Cols {
190 l := startCol(i)
191 o.Col(l)
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(" │ "))
197 if i > 0 {
198 // All but the first column will have A/B
199 // comparisons.
200 //
201 // Separate center and delta column groups by
202 // 2 spaces.
203 o.Span(deltaCols, "vs base", texttab.Left, texttab.LeftMargin(" "))
204 }
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++ {
210 o.SetShrink(j, true)
211 }
212 }
213 o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
215 // Emit measurements.
216 unitClass := benchunit.ClassOf(t.Unit)
217 for _, row := range t.Rows {
218 o.Row()
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}]
229 if !ok {
230 continue
231 }
233 o.Col(startCol(exp))
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
244 // it's good or bad.
245 o.Cell(d, texttab.Right)
246 o.Cell("(" + cell.Comparison.String() + ")")
247 warn(cell.Comparison.Warnings)
248 }
249 }
250 }
252 // Emit summary row.
253 if len(t.Rows) > 1 {
254 o.Row()
255 o.Cell(t.SummaryLabel)
256 for exp, col := range t.Cols {
257 tsum, ok := t.Summary[col]
258 if !ok {
259 continue
260 }
262 if tsum.HasSummary {
263 o.Col(startCol(exp))
264 o.Cell(benchunit.Scale(tsum.Summary, unitClass), texttab.Right)
265 }
266 if exp > 0 {
267 o.Col(startCol(exp) + centerCols)
268 if tsum.HasRatio {
269 o.Cell(fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100), texttab.Right)
270 } else {
271 o.Cell("?")
272 }
273 }
275 o.Col(startCol(exp+1) - 1)
276 warn(tsum.Warnings)
277 }
278 }
280 // Emit table.
281 if err := o.Format(w); err != nil {
282 return err
283 }
285 // Emit warnings.
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 {
289 return err
290 }
291 }
292 }
294 return nil
297var superDigits = []rune("⁰¹²³⁴⁵⁶⁷⁸⁹")
299func superscript(i int) string {
300 if i == 0 {
301 return string(superDigits[0])
302 }
304 var buf [20]rune
305 pos := len(buf)
306 for i > 0 && pos > 0 {
307 pos--
308 buf[pos] = superDigits[i%10]
309 i /= 10
310 }
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
317// "startRow".
318func (t *Table) ToCSV(o *csv.Writer, startRow int, warnings io.Writer) (rowCount int) {
319 const labelCols = 1
320 const centerCols = 2 // <center> <CI>
321 const deltaCols = 2 // <P%> <(p=0.PPP n=N)>
322 startCol := func(exp int) int {
323 if exp == 0 {
324 // Baseline, so no delta.
325 return labelCols
326 }
327 // Center and delta columns.
328 l := labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
329 return l
330 }
331 row := make([]string, startCol(len(t.Cols)))
332 row = row[:0]
333 clearTo := func(col int) {
334 for len(row) < col {
335 row = append(row, "")
336 }
337 }
338 emit := func() {
339 o.Write(row)
340 row = row[:0]
341 rowCount++
342 }
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; {
348 colNamePos--
349 colName[colNamePos] = 'A' + byte(x%26)
350 x /= 26
351 }
352 if colNamePos == len(colName) {
353 colNamePos--
354 colName[colNamePos] = 'A'
355 }
356 colName = colName[colNamePos:]
357 // Print warnings.
358 for _, msg := range msgs {
359 fmt.Fprintf(warnings, "%s%d: %s\n", colName, startRow+rowCount, msg)
360 }
361 }
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))
369 }
370 clearTo(startCol(len(t.Cols)))
371 emit()
372 }
374 // Emit column headers.
375 for exp := range t.Cols {
376 clearTo(startCol(exp))
377 row = append(row, t.Unit, "CI")
378 if exp > 0 {
379 row = append(row, "vs base", "P")
380 }
381 }
382 emit()
384 // Emit table.
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}]
389 if !ok {
390 continue
391 }
393 clearTo(startCol(exp))
394 warn(cell.Sample.Warnings)
395 warn(cell.Summary.Warnings)
396 row = append(row,
397 fmt.Sprint(cell.Summary.Center),
398 cell.Summary.PctRangeString(),
399 )
400 if exp > 0 && cell.Baseline != nil {
401 warn(cell.Comparison.Warnings)
402 row = append(row,
403 cell.Comparison.FormatDelta(cell.Baseline.Summary.Center, cell.Summary.Center),
404 cell.Comparison.String(),
405 )
406 }
407 }
408 emit()
409 }
411 // Emit summary row.
412 row = append(row, t.SummaryLabel)
413 for exp, key := range t.Cols {
414 tsum, ok := t.Summary[key]
415 if !ok {
416 continue
417 }
419 clearTo(startCol(exp))
420 warn(tsum.Warnings)
421 if tsum.HasSummary {
422 row = append(row, fmt.Sprint(tsum.Summary))
423 }
424 if exp > 0 {
425 clearTo(startCol(exp) + centerCols)
426 if tsum.HasRatio {
427 row = append(row, fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100))
428 } else {
429 row = append(row, "?")
430 }
431 }
432 }
433 clearTo(startCol(len(t.Cols)))
434 emit()
436 return