v2026.11.2
All Bundles
Bundle

What a student needs to turn a study into a hand-in: Replicates collects the value of each metric per seed and per setting and reports the count, mean, sample standard deviation, range and a t confidence interval, with a paired comparison of two settings; ResultTables converts between a System.ML.Lab ResultTable and the other results (replicates, an OLS fit, t-tests, a grid of strings); Report builds one document with numbered sections, tables, figures, code and notes, written as Markdown or as one self-contained HTML file with a print stylesheet that prints cleanly to PDF from a browser.

No call here ends the program on bad input: a call that cannot do what it was asked returns false (or Nil) and the object keeps the reason, read with GetError(), which is "" when there is nothing to report. Output is deterministic: the same calls give the same bytes, and nothing reads a clock. Compile with -lib ml_report,ml_lab,ml,stats,plot,csv,json,gen_collect.

Report

A document builder for a hand-in. Add sections, paragraphs, lists, tables, figures, code and notes in order, then write Markdown or one self-contained HTML file.

Sections nest to four levels and are numbered automatically ("1", "1.2"), or labelled by you ("Chapter 4", then "Experiment 1" inside it, shown as "Chapter 4 / Experiment 1"). Tables and figures are numbered in order of appearance and captioned ("Table 2. ...", "Figure 1. ..."). The HTML has a table of contents, inline SVG or base64 PNG figures that scale to the page width, tables whose rows do not split across printed pages, and a print stylesheet: open it in a browser and choose Print, Save as PDF. Text is plain text; every character that could be markup is escaped in both formats, so cell and paragraph text can hold <, &, quotes, backticks and pipes.

Figures in Markdown are files beside the text: Save("report.md") writes report-figure-1.svg, and so on, next to it. A PNG file is referenced where it is.

Word: Word opens an HTML file but does not draw its inline SVG reliably; use PNG figures (AddFigureFile, with a PNG from System.Plot.SDL's PlotPng), or print the HTML to PDF from a browser, or convert the Markdown with an external tool such as pandoc. This library was not tested against Word.

Example

report := Report->New("Assignment 3");
report->SetAuthor("A. Student");
report->AddSection(1, "Chapter 4", "Clustering");
report->AddSection(2, "Experiment 1", "Choosing k");
report->AddParagraph("Five seeds per setting.");
report->AddTable("Silhouette by k", table);
report->Save("report.html");

Operations

AddBullets #

Adds a bulleted list.

method : public : AddBullets(items:String[]) ~ Bool

Parameters

NameTypeDescription
itemsStringone text per bullet

Return

TypeDescription
Boolfalse for Nil or an empty list

AddChart #

Adds a System.ML.Lab chart as inline SVG.

method : public : AddChart(caption:String, chart:Chart) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
chartChartthe chart, for example ResultTable->ToChart(...)

Return

TypeDescription
Boolfalse for Nil

AddCode #

Adds a block of code or output, shown as written in a fixed-width font.

method : public : AddCode(text:String) ~ Bool

Parameters

NameTypeDescription
textStringthe text, line breaks kept

Return

TypeDescription
Boolfalse for Nil

AddCsvTable #

Adds a table from CSV text. CSV written by ResultTable->ToCsv becomes a formatted ResultTable table (as AddTable with a ResultTable); any other CSV is shown as a grid of text, its heading row first. Nothing here ends the program: text that is not CSV is refused.

method : public : AddCsvTable(caption:String, csv:String) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
csvStringCSV text with a heading row and at least one record

Return

TypeDescription
Boolfalse for Nil or empty text, CSV that does not parse, or a heading with no column

AddFigure #

Adds a figure from SVG text, numbered and captioned below. The text must be one document (an XML declaration before it is dropped); it is refused if it holds a script, a javascript: link or an event handler attribute. Ids inside it are made unique to the figure.

method : public : AddFigure(caption:String, svg:String) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
svgStringthe SVG, for example Figure->ToSvg()

Return

TypeDescription
Boolfalse for Nil, text that is not SVG, or SVG with active content

AddFigure #

Adds a System.Plot figure as inline SVG.

method : public : AddFigure(caption:String, figure:Figure) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
figureFigurethe figure

Return

TypeDescription
Boolfalse for Nil

AddFigureFile #

Adds a figure from a file: a .svg file is read as AddFigure reads SVG, and a .png file is embedded in the HTML as a base64 data URI (and referenced by its path in Markdown).

method : public : AddFigureFile(caption:String, path:String) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
pathStringthe file

Return

TypeDescription
Boolfalse when the file is missing, empty, not a PNG or SVG by its extension, or a PNG without the PNG signature

AddFigureSlot #

Adds the figure in .svg (or, if there is none, .png), or, when neither file exists, a note that says the figure has not been produced yet and which file to drop in. A figure file that exists but is refused (a script in the SVG, a bad PNG) adds a note with the reason instead.

method : public : AddFigureSlot(caption:String, stem:String) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
stemStringthe path without its extension

Return

TypeDescription
Booltrue when the figure was added; false when it is not there yet (GetError() is "") or was refused (GetError() says why)

AddNote #

Adds a note set apart from the text, for a caveat or an assumption.

method : public : AddNote(text:String) ~ Bool

Parameters

NameTypeDescription
textStringthe text

Return

TypeDescription
Boolfalse for Nil

AddNumbered #

Adds a numbered list.

method : public : AddNumbered(items:String[]) ~ Bool

Parameters

NameTypeDescription
itemsStringone text per entry

Return

TypeDescription
Boolfalse for Nil or an empty list

AddPageBreak #

Starts a new printed page here (HTML only; Markdown has no page).

method : public : AddPageBreak() ~ Nil

AddParagraph #

Adds a paragraph. Blank lines in the text start new paragraphs; a single line break is a space.

method : public : AddParagraph(text:String) ~ Bool

Parameters

NameTypeDescription
textStringthe text; "" adds nothing

Return

TypeDescription
Boolfalse for Nil

AddPlaceholderTable #

Adds a table whose every cell reads "not run yet", for a result that has not been produced: the row names down the left, the column names across the top, so the report has its final shape before the experiments run.

method : public : AddPlaceholderTable(caption:String, parameter:String, columns:String[], rows:String[]) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
parameterStringthe heading of the row-name column
columnsStringthe column names, at least one
rowsStringthe row names

Return

TypeDescription
Boolfalse for no columns or a Nil argument

AddResultTableChart #

Draws columns of a ResultTable with System.Plot and adds the chart as a figure: the row names are the categories of a bar chart ("bar"), or the row values are x of a line chart ("line", the row number where a row value is not a number or repeats).

method : public : AddResultTableChart(caption:String, table:ResultTable, columns:String[], kind:String) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
tableResultTablethe table
columnsStringthe columns to draw; Nil or empty draws all of them
kindString"bar" or "line"

Return

TypeDescription
Boolfalse for a Nil or empty table, an unknown column or kind, or a value that is not finite

AddResultTableChart #

As AddResultTableChart, with the chart's own title and a way to leave rows out: the title is drawn above the plot (the caption is the figure's caption below it), and a row whose name is in skip_rows (a total row, a baseline, a row that has no value yet) is not drawn and is not checked for a finite value.

method : public : AddResultTableChart(caption:String, table:ResultTable, columns:String[], kind:String, title:String, skip_rows:String[]) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
tableResultTablethe table
columnsStringthe columns to draw; Nil or empty draws all of them
kindString"bar" or "line"
titleStringthe title drawn in the chart; Nil or "" uses the table's title
skip_rowsStringrow names to leave out; Nil leaves none out

Return

TypeDescription
Boolfalse for a Nil table, no row left to draw, an unknown column or kind, or a drawn value that is not finite

AddRunStatus #

Adds a table of expected result files and whether each exists ("present" or "not run yet"): the run status of a study at a glance, the same list every time the report is built.

method : public : AddRunStatus(caption:String, paths:String[]) ~ Int

Parameters

NameTypeDescription
captionStringthe caption
pathsStringthe expected files, listed in this order

Return

TypeDescription
Inthow many exist, -1 for a Nil or empty list

AddSection #

Starts a section, numbered automatically: "1" for level 1, "1.1" for the first level 2 inside it.

method : public : AddSection(level:Int, heading:String) ~ Bool

Parameters

NameTypeDescription
levelInt1 to 4
headingStringthe heading text

Return

TypeDescription
Boolfalse when the level is outside 1 to 4 or the heading is Nil

AddSection #

Starts a labelled section. A label such as "Chapter 4" replaces the number, and the labels of the sections it sits in come first, so level 2 "Experiment 1" under "Chapter 4" reads "Chapter 4 / Experiment 1".

method : public : AddSection(level:Int, heading:String) ~ Bool

Parameters

NameTypeDescription
levelInt1 to 4
headingStringthe heading text

Return

TypeDescription
Boolfalse when the level is outside 1 to 4 or the heading or label is Nil

AddTable #

Adds a table from a ResultTable, numbered and captioned. The cells read as ResultTable->ToMarkdown() spells them (the column's decimals, "mean ± std", NaN as n/a); the table's footnote is written under it.

method : public : AddTable(caption:String, table:ResultTable) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption; "" uses the table's title
tableResultTablethe table

Return

TypeDescription
Boolfalse for Nil

AddTable #

Adds a table from a grid of text whose first row is the heading. A column whose cells all look like numbers is right-aligned.

method : public : AddTable(caption:String, cells:String[,]) ~ Bool

Parameters

NameTypeDescription
captionStringthe caption
cellsStringrows by columns, at least a heading row and one column

Return

TypeDescription
Boolfalse for Nil or an empty grid

GetError #

Why the last call that returns Bool was refused; nothing is added by a refused call.

method : public : GetError() ~ String

Return

TypeDescription
Stringthe reason, "" when it succeeded

GetFigureCount #

How many figures have been added.

method : public : GetFigureCount() ~ Int

Return

TypeDescription
Intthe count

GetSectionCount #

How many sections have been added.

method : public : GetSectionCount() ~ Int

Return

TypeDescription
Intthe count

GetTableCount #

How many tables have been added.

method : public : GetTableCount() ~ Int

Return

TypeDescription
Intthe count

New # constructor

Constructor

New(title:String)

Parameters

NameTypeDescription
titleStringthe document title, "" for none

New # constructor

Constructor: an untitled report.

New()

Save #

Writes the report, choosing the format by the extension: .html or .htm for HTML, .md or .markdown for Markdown. For Markdown the SVG figures are written beside it as NAME-figure-1.svg, and so on.

method : public : Save(path:String) ~ Bool

Parameters

NameTypeDescription
pathStringthe file to write

Return

TypeDescription
Boolfalse, with GetError() saying why, for another extension or a file that cannot be written

SetAuthor #

Sets the author line.

method : public : SetAuthor(author:String) ~ Nil

Parameters

NameTypeDescription
authorStringthe author

SetContents #

Turns the table of contents on (the default) or off. It is written only when there is a section.

method : public : SetContents(on:Bool) ~ Nil

Parameters

NameTypeDescription
onBooltrue for a table of contents

SetDate #

Sets the date line; it is text you choose, so the output never depends on the clock.

method : public : SetDate(date:String) ~ Nil

Parameters

NameTypeDescription
dateStringthe date as written

SetPaper #

Sets the paper size of the printed HTML.

method : public : SetPaper(paper:String) ~ Bool

Parameters

NameTypeDescription
paperString"A4", "Letter", or "" to let the print dialog decide (the default)

Return

TypeDescription
Boolfalse for any other name

SetTitle #

Sets the title.

method : public : SetTitle(title:String) ~ Nil

Parameters

NameTypeDescription
titleStringthe title

ToHtml #

The report as one self-contained HTML5 file: styles inline, SVG figures inline, PNG figures as data URIs, no script and no external request. Print it to PDF from a browser.

method : public : ToHtml() ~ String

Return

TypeDescription
Stringthe HTML

ToMarkdown #

The report as Markdown (CommonMark with pipe tables). Figures are referenced as figure-1.svg, figure-2.svg, ... beside the text; Save writes them.

method : public : ToMarkdown() ~ String

Return

TypeDescription
Stringthe Markdown

ToMarkdown #

The report as Markdown with a chosen file-name stem for the figure files: "name" gives name-figure-1.svg.

method : public : ToMarkdown(stem:String) ~ String

Parameters

NameTypeDescription
stemStringthe stem, "" for figure-1.svg

Return

TypeDescription
Stringthe Markdown