Experiment support for a parameter sweep: a deterministic stratified hold-out split, class-ratio resampling of the training half against a fixed test set, a wall-clock stopwatch and label helpers. Compile with -lib ml,ml_lab,csv,json, or with the ai alias group. Design: docs/ML_LAB_SUPPORT_DESIGN.md.
ResultTable
A table of results: a title, one row per parameter value (a display name and a numeric value), named numeric columns, optional per-cell standard deviations, and a footnote of fixed settings. Renders as aligned text, Markdown, CSV and JSON, and reads CSV and JSON back.
Numbers render with a fixed number of decimals per column (4 by default), so the output is byte-stable; CSV and JSON carry up to 10 decimals with trailing zeros trimmed, so a value survives a round trip to within 1e-10.
Example
t := ResultTable->New("Random forest: trees", "n_estimators");
t->AddColumn("test_accuracy");
t->AddColumn("fit_ms", 1);
t->AddRow("10", 10.0, [0.9412, 12.5]);
t->SetFootnote("max_depth=8; seed=42");
t->ToMarkdown()->PrintLine();
t->Save("rf_trees.csv");Operations
- New
- AddColumn
- AddIntegerColumn
- AddPValueColumn
- AddRow
- AddScientificColumn
- ColumnIndex
- FormatNumber
- FormatValue
- FromCsv
- FromJson
- Get
- GetColumn
- GetColumnFormat
- GetColumnNames
- GetColumnPrecision
- GetColumnStds
- GetFootnote
- GetParameter
- GetRowName
- GetRowNames
- GetRowValue
- GetRowValues
- GetStd
- GetTitle
- HasStds
- IsFinite
- Save
- SetFootnote
- Size
- ToChart
- ToCsv
- ToJson
- ToMarkdown
- ToText
AddColumn #
Adds a numeric column rendered with 4 decimals. Columns must be added before rows.
method : public : AddColumn(name:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
AddColumn #
Adds a numeric column.
method : public : AddColumn(name:String, precision:Int) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
| precision | Int | decimals when rendered as text or Markdown |
AddColumn #
Adds a numeric column with a number format. The format changes only how ToText and ToMarkdown spell a cell; CSV and JSON values are unchanged. "fixed" is the default (precision decimals); "sci" is scientific notation with precision decimals in the mantissa (1.23e-05); "p" is fixed, but a value from 0 up to 10^-precision is written "<0.0001" (precision 4), so a tiny p-value does not read as 0.0000; "int" rounds to a whole number and writes no decimals (a count), whatever the precision. ToCsv writes a "sci" or "p" column's value below 1e-4 in exponent form with its full digits (1.23e-12) instead of the 10 decimals that would write a tiny p-value as 0; FromCsv reads it back. ToJson keeps its 10 decimals.
method : public : AddColumn(name:String, precision:Int, format:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
| precision | Int | decimals (mantissa decimals for "sci", the "<" threshold for "p") |
| format | String | "fixed", "sci", "p" or "int"; raises LabError for another name |
AddIntegerColumn #
Adds a column of whole numbers (counts), written without decimals.
method : public : AddIntegerColumn(name:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
AddPValueColumn #
Adds a column of p-values: 4 decimals, and "<0.0001" below that.
method : public : AddPValueColumn(name:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
AddRow #
Adds a row without deviations.
method : public : AddRow(name:String, value:Float, cells:Float[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | the parameter value's display name |
| value | Float | the parameter's numeric value |
| cells | Float | one value per column |
AddRow #
Adds a row with a standard deviation per cell, from repeated runs.
method : public : AddRow(name:String, value:Float, cells:Float[], stds:Float[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | the parameter value's display name |
| value | Float | the parameter's numeric value |
| cells | Float | one mean per column |
| stds | Float | one standard deviation per column, or Nil for none |
AddScientificColumn #
Adds a column in scientific notation.
method : public : AddScientificColumn(name:String, precision:Int) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
| precision | Int | decimals of the mantissa |
ColumnIndex #
The index of a column by name.
method : public : ColumnIndex(name:String) ~ IntParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
Return
| Type | Description |
|---|---|
| Int | the index, or -1 |
FormatNumber # function
A number for CSV and JSON: up to 10 decimals, trailing zeros and a trailing point trimmed, never "-0".
function : FormatNumber(value:Float) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| value | Float | the number |
Return
| Type | Description |
|---|---|
| String | its text |
FormatValue # function
A number as ToText and ToMarkdown spell it in a column of the given format (see AddColumn). A value that is not finite is "n/a".
function : FormatValue(value:Float, precision:Int, format:String) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| value | Float | the number |
| precision | Int | decimals |
| format | String | "fixed", "sci", "p" or "int"; anything else is "fixed" |
Return
| Type | Description |
|---|---|
| String | the text |
FromCsv # function
Reads a table written by ToCsv. The title and footnote come back empty.
function : FromCsv(text:String) ~ ResultTableParameters
| Name | Type | Description |
|---|---|---|
| text | String | CSV text |
Return
| Type | Description |
|---|---|
| ResultTable | the table; raises LabError when the text is not a ToCsv table |
FromJson # function
Reads a table written by ToJson.
function : FromJson(text:String) ~ ResultTableParameters
| Name | Type | Description |
|---|---|---|
| text | String | JSON text |
Return
| Type | Description |
|---|---|
| ResultTable | the table; raises LabError when the text is not a ToJson table |
Get #
A cell.
method : public : Get(row:Int, col:Int) ~ FloatParameters
| Name | Type | Description |
|---|---|---|
| row | Int | row index |
| col | Int | column index |
Return
| Type | Description |
|---|---|
| Float | the value (the mean, for repeated runs) |
GetColumn #
One column's values, in row order.
method : public : GetColumn(name:String) ~ Float[]Parameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
Return
| Type | Description |
|---|---|
| Float | one value per row; raises LabError for an unknown column |
GetColumnFormat #
The number format of a column.
method : public : GetColumnFormat(name:String) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
Return
| Type | Description |
|---|---|
| String | "fixed", "sci", "p" or "int"; "" for an unknown column |
GetColumnNames #
Column headings, in order.
method : public : GetColumnNames() ~ String[]Return
| Type | Description |
|---|---|
| String | the numeric columns' names |
GetColumnPrecision #
The decimals a column is rendered with.
method : public : GetColumnPrecision(name:String) ~ IntParameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
Return
| Type | Description |
|---|---|
| Int | the precision (see AddColumn), -1 for an unknown column |
GetColumnStds #
One column's standard deviations, in row order.
method : public : GetColumnStds(name:String) ~ Float[]Parameters
| Name | Type | Description |
|---|---|---|
| name | String | column heading |
Return
| Type | Description |
|---|---|
| Float | one deviation per row (zeros when the table holds none); raises LabError for an unknown column |
GetFootnote #
The footnote.
method : public : GetFootnote() ~ StringReturn
| Type | Description |
|---|---|
| String | footnote text, empty when unset |
GetParameter #
The swept parameter's name.
method : public : GetParameter() ~ StringReturn
| Type | Description |
|---|---|
| String | the first column's heading |
GetRowName #
A row's display name.
method : public : GetRowName(row:Int) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| row | Int | row index |
Return
| Type | Description |
|---|---|
| String | the name |
GetRowNames #
The row names, in row order.
method : public : GetRowNames() ~ String[]Return
| Type | Description |
|---|---|
| String | one name per row |
GetRowValue #
A row's numeric parameter value.
method : public : GetRowValue(row:Int) ~ FloatParameters
| Name | Type | Description |
|---|---|---|
| row | Int | row index |
Return
| Type | Description |
|---|---|
| Float | the value |
GetRowValues #
The parameter values, in row order: the x axis of a chart.
method : public : GetRowValues() ~ Float[]Return
| Type | Description |
|---|---|
| Float | one value per row |
GetStd #
A cell's standard deviation.
method : public : GetStd(row:Int, col:Int) ~ FloatParameters
| Name | Type | Description |
|---|---|---|
| row | Int | row index |
| col | Int | column index |
Return
| Type | Description |
|---|---|
| Float | the deviation, 0.0 when the table holds none |
HasStds #
Whether any row carries standard deviations.
method : public : HasStds() ~ BoolReturn
| Type | Description |
|---|---|
| Bool | true after an AddRow with deviations |
IsFinite # function
True when a value is a finite number: neither NaN nor positive or negative infinity. A table cell, a deviation or a chart point that is not finite is "missing": ToText and ToMarkdown write n/a, ToCsv an empty field, ToJson null, and a Chart skips the point.
function : IsFinite(value:Float) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| value | Float | the number |
Return
| Type | Description |
|---|---|
| Bool | true for a finite number |
New # constructor
Constructor
New(title:String, parameter:String)Parameters
| Name | Type | Description |
|---|---|---|
| title | String | shown above the table |
| parameter | String | the swept parameter's name, the first column's heading |
Save #
Writes the table in the form the file extension names: .md Markdown, .csv CSV, .json JSON, anything else the aligned text.
method : public : Save(path:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| path | String | file to write |
Return
| Type | Description |
|---|---|
| Bool | true when written |
SetFootnote #
Sets the footnote of fixed settings printed under the table.
method : public : SetFootnote(text:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| text | String | the footnote |
ToChart #
A line chart of named columns against the parameter: x is the parameter value (or the row names as categories when a row name is not its number), one series per metric, error bars from the deviations when the table holds them.
method : public : ToChart(metrics:String[]) ~ ChartParameters
| Name | Type | Description |
|---|---|---|
| metrics | String | column names to draw; an empty array draws every column |
Return
| Type | Description |
|---|---|
| Chart | the chart; raises LabError for an unknown column or an empty table |
ToChart #
A line chart of named columns, optionally on a log x axis (for C, gamma or a learning rate).
method : public : ToChart(metrics:String[], log_x:Bool) ~ ChartParameters
| Name | Type | Description |
|---|---|---|
| metrics | String | column names to draw; an empty array draws every column |
| log_x | Bool | true for a base-10 log x axis |
Return
| Type | Description |
|---|---|
| Chart | the chart; raises LabError for an unknown column or an empty table |
ToCsv #
RFC 4180 CSV: a header of the parameter name, "
method : public : ToCsv() ~ StringReturn
| Type | Description |
|---|---|
| String | the CSV, records ending in LF |
ToJson #
JSON, built with Data.JSON: {"title","parameter","footnote","columns":[], "precision":[],"rows":[{"name","value","cells":{column: value}, "stds":{column: deviation}}]}; "stds" is present only when the table holds deviations.
method : public : ToJson() ~ StringReturn
| Type | Description |
|---|---|
| String | the JSON text |