Report model

PortfolioOptimisers.AbstractReportBlock — Type
abstract type AbstractReportBlock <: AbstractResult

Abstract supertype of the blocks of a Portfolio Report: a text, a table, a figure or a section.

A block holds its content and knows no format. A writer asks each block to show itself as the format of the writer, so a format is a set of show methods, one for each block. Report holds the blocks of a report, and write_report writes it. The two formats of the library are Markdown and one self-contained HTML file. A new format adds a method of show for its MIME to every block, and a new block adds a method for every format.

Interfaces

A concrete block subtypes AbstractReportBlock and implements one method of show for each format.

Base.show

  • Base.show(io::IO, mime::MIME"text/markdown", b::MyBlock) -> Nothing: Write the block as Markdown.
  • Base.show(io::IO, mime::MIME"text/html", b::MyBlock) -> Nothing: Write the block as an HTML fragment, with every string of the caller escaped.

Arguments

  • io: The stream. The writer of a report sets two keys of its IOContext: :report_level, the heading level of the block, and :report_figure_mime, the image MIME of a figure.
  • mime: The format.
  • b: The block.

Returns

  • nothing.

Related

source
PortfolioOptimisers.ReportText — Type
struct ReportText{__T_text} <: AbstractReportBlock

A block of plain text in a Portfolio Report.

The text is not Markdown and not HTML. Every writer escapes it, so a string of the caller cannot add markup to the report. A blank line splits the text into paragraphs.

Fields

  • text: The text of the block.

Constructors

ReportText(text::AbstractString) -> ReportText

Related

source
PortfolioOptimisers.ReportTable — Type
struct ReportTable{__T_df, __T_caption, __T_sortable, __T_digits, __T_key} <: AbstractReportBlock

A table of a Portfolio Report, from a DataFrame.

A number shows with digits significant digits. An HTML cell keeps the full value, so a sort reads the value and not its rounded text. missing, nothing and NaN show as —, and a sort puts them last. A table with a key names a column whose value is the name of an entry of the report, and a click on a row of the HTML table selects that entry.

Fields

  • df: The table.
  • caption: The caption of the table, or an empty string for none.
  • sortable: Whether the reader of the HTML file can sort the table by a click on a header.
  • digits: The number of significant digits of a number.
  • key: The column whose value names the entry of a row, or nothing.

Constructors

ReportTable(df::DataFrames.AbstractDataFrame; caption::AbstractString = "",            sortable::Bool = false, digits::Integer = 4,            key::Option{<:Symbol} = nothing) -> ReportTable

Validation

  • digits > 0. Otherwise the constructor raises a DomainError.
  • key is nothing or a column of df. Otherwise the constructor raises an ArgumentError.

Related

source
PortfolioOptimisers.ReportFigure — Type
struct ReportFigure{__T_fig, __T_caption} <: AbstractReportBlock

A figure of a Portfolio Report.

The figure is any object that shows itself as an SVG or a PNG image, showable(MIME"image/svg+xml"(), fig) or showable(MIME"image/png"(), fig). The block does not depend on a plotting package, so a figure of any package that implements show for an image MIME works. A writer embeds the image in the report as a data URI, so the report needs no file beside it.

Fields

  • fig: The figure.
  • caption: The caption of the figure, or an empty string for none.

Constructors

ReportFigure(fig; caption::AbstractString = "") -> ReportFigure

Validation

  • fig shows itself as an SVG or a PNG image. Otherwise the constructor raises an ArgumentError that names the type of fig.

Related

source
PortfolioOptimisers.ReportSection — Type
struct ReportSection{__T_title, __T_blocks} <: AbstractReportBlock

A titled list of blocks of a Portfolio Report.

A section can hold another section. Its heading is one level below the heading of the block that holds it.

Fields

  • title: The title of the section.
  • blocks: The blocks of the section, in order.

Constructors

ReportSection(title::AbstractString,              blocks::AbstractVector{<:AbstractReportBlock}) -> ReportSection

Related

source
PortfolioOptimisers.ReportEntry — Type
struct ReportEntry{__T_name, __T_sections, __T_group, __T_meta} <: AbstractResult

One portfolio of a Portfolio Report, a candidate of the comparison.

group and meta are labels of the caller. The library gives them no meaning, and a writer shows them as given. The HTML file lists the entries of a group under the name of the group in its selector, and can hide a group.

Fields

  • name: The name of the entry, unique in its report.
  • sections: The sections of the entry, in order.
  • group: The group of the entry, or nothing.
  • meta: The labels of the entry, as pairs of strings.

Constructors

ReportEntry(name::AbstractString, sections::AbstractVector{<:ReportSection};            group::Option{<:AbstractString} = nothing,            meta::Option{<:AbstractVector{<:Pair}} = nothing) -> ReportEntry

Related

source
PortfolioOptimisers.Report — Type
struct Report{__T_title, __T_entries, __T_overview, __T_meta} <: AbstractResult

A Portfolio Report: a document that compares portfolios, in a form that no format decides.

The overview compares the entries, and each entry shows one portfolio. portfolio_report builds a report from prediction results, and a caller can build one by hand from blocks. write_report writes a report as Markdown or as one self-contained HTML file, and show with the MIME text/markdown or text/html writes it to a stream.

Fields

  • title: The title of the report.
  • entries: The entries of the report, one for each portfolio.
  • overview: The blocks above the entries, which compare them.
  • meta: The labels of the report, as pairs of strings.

Constructors

Report(title::AbstractString, entries::AbstractVector{<:ReportEntry};       overview::AbstractVector{<:AbstractReportBlock} = AbstractReportBlock[],       meta::Option{<:AbstractVector{<:Pair}} = nothing) -> Report

Validation

  • The names of the entries are unique, because the selector and the links of the HTML file read them. Otherwise the constructor raises an ArgumentError that names each repeated name.

Related

source
Base.show — Method
Base.show(io::IO, b::Union{AbstractReportBlock, ReportEntry, Report})

Show a block, an entry or a report on one line, with its type, its name and the size of its content.

A report holds figures and tables, which can be large. The one line keeps the REPL readable. show with the MIME text/markdown or text/html writes the content.

Arguments

  • io: The stream.
  • b: The block, the entry or the report.

Returns

  • nothing.

Related

source