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
- New
- AddBullets
- AddChart
- AddCode
- AddCsvTable
- AddFigure
- AddFigureFile
- AddFigureSlot
- AddNote
- AddNumbered
- AddPageBreak
- AddParagraph
- AddPlaceholderTable
- AddResultTableChart
- AddRunStatus
- AddSection
- AddTable
- GetError
- GetFigureCount
- GetSectionCount
- GetTableCount
- Save
- SetAuthor
- SetContents
- SetDate
- SetPaper
- SetTitle
- ToHtml
- ToMarkdown
AddBullets #
Adds a bulleted list.
method : public : AddBullets(items:String[]) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| items | String | one text per bullet |
Return
| Type | Description |
|---|---|
| Bool | false for Nil or an empty list |
AddChart #
Adds a System.ML.Lab chart as inline SVG.
method : public : AddChart(caption:String, chart:Chart) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| chart | Chart | the chart, for example ResultTable->ToChart(...) |
Return
| Type | Description |
|---|---|
| Bool | false for Nil |
AddCode #
Adds a block of code or output, shown as written in a fixed-width font.
method : public : AddCode(text:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| text | String | the text, line breaks kept |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| csv | String | CSV text with a heading row and at least one record |
Return
| Type | Description |
|---|---|
| Bool | false 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
method : public : AddFigure(caption:String, svg:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| svg | String | the SVG, for example Figure->ToSvg() |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| figure | Figure | the figure |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| path | String | the file |
Return
| Type | Description |
|---|---|
| Bool | false 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
method : public : AddFigureSlot(caption:String, stem:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| stem | String | the path without its extension |
Return
| Type | Description |
|---|---|
| Bool | true 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| text | String | the text |
Return
| Type | Description |
|---|---|
| Bool | false for Nil |
AddNumbered #
Adds a numbered list.
method : public : AddNumbered(items:String[]) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| items | String | one text per entry |
Return
| Type | Description |
|---|---|
| Bool | false for Nil or an empty list |
AddPageBreak #
Starts a new printed page here (HTML only; Markdown has no page).
method : public : AddPageBreak() ~ NilAddParagraph #
Adds a paragraph. Blank lines in the text start new paragraphs; a single line break is a space.
method : public : AddParagraph(text:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| text | String | the text; "" adds nothing |
Return
| Type | Description |
|---|---|
| Bool | false 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[]) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| parameter | String | the heading of the row-name column |
| columns | String | the column names, at least one |
| rows | String | the row names |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| table | ResultTable | the table |
| columns | String | the columns to draw; Nil or empty draws all of them |
| kind | String | "bar" or "line" |
Return
| Type | Description |
|---|---|
| Bool | false 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[]) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| table | ResultTable | the table |
| columns | String | the columns to draw; Nil or empty draws all of them |
| kind | String | "bar" or "line" |
| title | String | the title drawn in the chart; Nil or "" uses the table's title |
| skip_rows | String | row names to leave out; Nil leaves none out |
Return
| Type | Description |
|---|---|
| Bool | false 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[]) ~ IntParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| paths | String | the expected files, listed in this order |
Return
| Type | Description |
|---|---|
| Int | how 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| level | Int | 1 to 4 |
| heading | String | the heading text |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| level | Int | 1 to 4 |
| heading | String | the heading text |
Return
| Type | Description |
|---|---|
| Bool | false 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption; "" uses the table's title |
| table | ResultTable | the table |
Return
| Type | Description |
|---|---|
| Bool | false 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[,]) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| caption | String | the caption |
| cells | String | rows by columns, at least a heading row and one column |
Return
| Type | Description |
|---|---|
| Bool | false 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() ~ StringReturn
| Type | Description |
|---|---|
| String | the reason, "" when it succeeded |
GetFigureCount #
How many figures have been added.
method : public : GetFigureCount() ~ IntReturn
| Type | Description |
|---|---|
| Int | the count |
GetSectionCount #
How many sections have been added.
method : public : GetSectionCount() ~ IntReturn
| Type | Description |
|---|---|
| Int | the count |
GetTableCount #
How many tables have been added.
method : public : GetTableCount() ~ IntReturn
| Type | Description |
|---|---|
| Int | the count |
New # constructor
Constructor
New(title:String)Parameters
| Name | Type | Description |
|---|---|---|
| title | String | the document title, "" for none |
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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| path | String | the file to write |
Return
| Type | Description |
|---|---|
| Bool | false, with GetError() saying why, for another extension or a file that cannot be written |
SetAuthor #
Sets the author line.
method : public : SetAuthor(author:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| author | String | the 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| on | Bool | true 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| date | String | the date as written |
SetPaper #
Sets the paper size of the printed HTML.
method : public : SetPaper(paper:String) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| paper | String | "A4", "Letter", or "" to let the print dialog decide (the default) |
Return
| Type | Description |
|---|---|
| Bool | false for any other name |
SetTitle #
Sets the title.
method : public : SetTitle(title:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| title | String | the 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() ~ StringReturn
| Type | Description |
|---|---|
| String | the HTML |