GitHub

Pretty printing: private API

PortfolioOptimisers.jl's types tend to contain quite a lot of information, these functions enable pretty printing so they are easier to interpret. A field that holds nothing is hidden by default and shown in this documentation; set_show_nothing_fields! is the switch, and show_fields is the hook a type overloads to hide a field of its own choice.

PortfolioOptimisers.@define_pretty_show — Macro
@define_pretty_show(T, flag::Bool = true)

Defines a Base.show method for T that prints the type name and one aligned line per field.

A field that is itself pretty-printable is rendered under its parent and indented, and an oversized one is collapsed to Name ⋯. The height at which a nested field collapses is the budget that compact_show_budget reads; see set_compact_show!. The fields that print are the ones pretty_show_fields resolves, so a field that holds nothing is hidden under the shipped default of SHOW_NOTHING_FIELDS, and a type hides a field of its own choice through show_fields.

Algorithm

The macro emits two definitions. Steps 3 to 9 are the body of the Base.show method it emits.

  1. When flag is true, define has_pretty_show_method(::T)::Bool = true. The return type is annotated, as it is on the four methods that has_pretty_show_method declares by hand.

  2. Define Base.show(io::IO, obj::T).

  3. Read fields, the field names that pretty_show_fields resolves for obj. When fields is empty, print T() and return. A type with no field reaches this step, and so does a type whose every field is hidden.

  4. When the IO context sets :compact or :multiline, print the type name alone and return.

  5. Print the wrapper name of the type, then compute padding, the length of the longest field name plus two.

  6. For each field in declaration order, read val with getproperty, so that a property a rule of @forward_properties swaps prints the swapped value.

  7. Choose the connector sym1, giving ┴ for the last printed line and ┼ otherwise. The last printed line is the last field of fields, so a hidden field never carries the marker. A nested value whose own resolved field list is empty prints on one line, so it takes ┴ too.

  8. Print the field name, right-aligned to padding.

  9. Print val through the first branch that matches it, giving the rest of the line:

    • nothing prints as nothing.
    • A value that has a pretty-show method is rendered into a buffer, giving alglines. When the number of non-empty lines exceeds compact_show_budget(io), print the wrapper name of the value followed by ⋯. Otherwise print the first line beside the connector, and indent the rest under │.
    • A non-empty vector whose every element has a pretty-show method prints the summary from pretty_show_vector_summary, then the lines from pretty_show_vector_body, each indented under │.
    • A matrix prints its size and its type.
    • A vector of more than six entries, or a vector of arrays, prints its length and its type.
    • A DataType prints DataType, which is its type, then the wrapper name of the value, so a parametrised type reports the wrapper it instantiates and Vector{Float64} prints as DataType: Array.
    • Any other value prints its type and repr(val).

Arguments

  • T: The type for which to define the pretty-printing method.
  • flag::Bool = true: When true, the macro also defines has_pretty_show_method(::T) = true, which is how a parent finds that T renders through this method. Pass false for a type whose parent must print it by repr instead.

Returns

  • Defines a Base.show(io::IO, obj::T) method for the given type.

Related

source
PortfolioOptimisers.show_fields — Function
show_fields(obj) -> NTuple{8, Symbol}

Name the fields of obj that @define_pretty_show considers for rendering, in declaration order.

The default method returns every declared field. A type that hides one of its fields overloads this method for itself and returns the others. The overload receives the instance, so it may hide a field whatever it holds — a partial-fit cache, which is running detail rather than configuration — or hide it by what it holds, as the moment estimators hide an opt-in cvg that is nothing: an opt-in the caller has not taken is not part of the configuration they chose, and a field added to a type this way moves no rendered docstring. That overload is the per-type arm of the field selection, and SHOW_NOTHING_FIELDS is the configured arm: pretty_show_fields resolves the two, and a per-name entry of the configuration overrides this method in either direction.

Arguments

  • obj: The value under rendering.

Returns

  • fields: The field names to consider, as a tuple or a vector of Symbol.

Related

source
show_fields(
    est::Union{MissingDataFilter, PriceGapFill, PricesToReturns}
) -> Tuple{Vararg{Symbol}}

Renders every field of a data step but its cache, which appears only where a state is set, so no rendering of a step that took no step moves.

Related

source
show_fields(
    me::SimpleExpectedReturns
) -> Union{Tuple{Symbol}, Tuple{Symbol, Symbol}}

Renders every field of a SimpleExpectedReturns except cache, and cvg only where a policy is set.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:SimpleExpectedReturns, true) to render it. cvg is read from the instance rather than from the type, because an opt-in that a caller has not taken is not part of the configuration they chose: an estimator whose cvg is nothing renders exactly as it did before the field existed, and one that carries a CoveragePolicy renders it.

Arguments

  • me: Expected returns estimator, read for its cvg field.

Returns

  • fields::Tuple: The field names to render, which is (:w,) with no policy and (:w, :cvg) with one.

Related

source
show_fields(_::GeneralCovariance) -> Tuple{Symbol, Symbol}

Renders every field of a GeneralCovariance except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:GeneralCovariance, true) to render it.

Arguments

  • ::GeneralCovariance: Covariance estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:ce, :w).

Related

source
show_fields(
    ce::Covariance
) -> Union{NTuple{4, Symbol}, NTuple{5, Symbol}}

Renders every field of a Covariance except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:Covariance, true) to render it.

Arguments

  • ::Covariance: Covariance estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:me, :ce, :alg, :w) with no policy and (:me, :ce, :alg, :w, :cvg) with one.

Related

source
show_fields(
    ve::SimpleVariance
) -> Union{Tuple{Symbol, Symbol, Symbol}, NTuple{4, Symbol}}

Renders every field of a SimpleVariance except cache, and cvg only where a policy is set.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:SimpleVariance, true) to render it. cvg is read from the instance rather than from the type, as it is for SimpleExpectedReturns, which states the reason.

Arguments

  • ve: Variance estimator, read for its cvg field.

Returns

  • fields::Tuple: The field names to render, which is (:me, :w, :corrected) with no policy and (:me, :w, :corrected, :cvg) with one.

Related

source
show_fields(
    _::PortfolioOptimisersCovariance
) -> Tuple{Symbol, Symbol}

Renders every field of a PortfolioOptimisersCovariance except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:PortfolioOptimisersCovariance, true) to render it.

Arguments

  • ::PortfolioOptimisersCovariance: Covariance estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:ce, :mp).

Related

source
show_fields(
    ske::Coskewness
) -> Union{NTuple{5, Symbol}, NTuple{6, Symbol}}

Renders every field of a Coskewness but the cvg it does not carry.

A cvg of nothing is the reduce-and-expand path every estimator took before the policy existed, so rendering it there would move every doctest in the library and tell a reader nothing. A policy that is set is configuration, and prints.

Arguments

  • ske: Coskewness estimator, read for its cvg field alone.

Returns

  • fields::Tuple: The field names to render, which is (:me, :mp, :alg, :w, :cache) with no policy and (:me, :mp, :alg, :w, :cvg, :cache) with one.

Related

source
show_fields(
    kte::Cokurtosis
) -> Union{NTuple{5, Symbol}, NTuple{6, Symbol}}

Renders every field of a Cokurtosis but the cvg it does not carry.

A cvg of nothing is the reduce-and-expand path every estimator took before the policy existed, so rendering it there would move every doctest in the library and tell a reader nothing. A policy that is set is configuration, and prints.

Arguments

  • kte: Cokurtosis estimator, read for its cvg field alone.

Returns

  • fields::Tuple: The field names to render, which is (:me, :mp, :alg, :w, :cache) with no policy and (:me, :mp, :alg, :w, :cvg, :cache) with one.

Related

source
show_fields(
    pe::EmpiricalPrior
) -> Union{NTuple{4, Symbol}, NTuple{5, Symbol}}

Renders every field of an EmpiricalPrior except cache, and max_scenarios only where it is set.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. max_scenarios is a cap most callers never set, and a nothing row for it would move every rendering of every host that carries a prior; it appears exactly where a caller chose one. Set set_show_nothing_fields!(:EmpiricalPrior, true) to render both.

Arguments

  • pe: Empirical prior estimator.

Returns

  • fields::Tuple: The field names to render, which is (:ce, :me, :horizon, :fill_limit) with no scenario cap and (:ce, :me, :horizon, :fill_limit, :max_scenarios) with one.

Related

source
show_fields(_::FactorPrior) -> NTuple{5, Symbol}

Renders every field of a FactorPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:FactorPrior, true) to render it.

Arguments

  • ::FactorPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :mp, :re, :ve, :rsd).

Related

source
show_fields(
    _::BayesianBlackLittermanPrior
) -> NTuple{8, Symbol}

Renders every field of a BayesianBlackLittermanPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:BayesianBlackLittermanPrior, true) to render it.

Arguments

  • ::BayesianBlackLittermanPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :f_mp, :mp, :views, :sets, :views_conf, :rf, :tau).

Related

source
show_fields(
    _::FactorBlackLittermanPrior
) -> NTuple{13, Symbol}

Renders every field of a FactorBlackLittermanPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:FactorBlackLittermanPrior, true) to render it.

Arguments

  • ::FactorBlackLittermanPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :f_mp, :mp, :re, :ve, :views, :sets, :views_conf, :w, :rf, :l, :tau, :rsd).

Related

source
show_fields(
    _::AugmentedBlackLittermanPrior
) -> NTuple{13, Symbol}

Renders every field of a AugmentedBlackLittermanPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:AugmentedBlackLittermanPrior, true) to render it.

Arguments

  • ::AugmentedBlackLittermanPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:a_pe, :f_pe, :mp, :re, :a_views, :f_views, :sets, :a_views_conf, :f_views_conf, :w, :rf, :l, :tau).

Related

source
show_fields(
    _::MeucciEntropyPoolingPrior
) -> NTuple{15, Symbol}

Renders every field of a MeucciEntropyPoolingPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:MeucciEntropyPoolingPrior, true) to render it.

Arguments

  • ::MeucciEntropyPoolingPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :mu_views, :var_views, :cvar_views, :sigma_views, :sk_views, :kt_views, :cov_views, :rho_views, :sets, :ds_opt, :dm_opt, :opt, :w, :alg).

Related

source
show_fields(_::EntropyPoolingPrior) -> NTuple{15, Symbol}

Renders every field of a EntropyPoolingPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:EntropyPoolingPrior, true) to render it.

Arguments

  • ::EntropyPoolingPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :mu_views, :var_views, :cvar_views, :evar_views, :rlvar_views, :sigma_views, :sk_views, :kt_views, :cov_views, :rho_views, :sets, :opt, :w, :alg).

Related

source
show_fields(_::OpinionPoolingPrior) -> NTuple{7, Symbol}

Renders every field of a OpinionPoolingPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:OpinionPoolingPrior, true) to render it.

Arguments

  • ::OpinionPoolingPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pes, :pe1, :pe2, :p, :w, :alg, :ex).

Related

source
show_fields(
    _::HighOrderFactorPriorEstimator
) -> NTuple{5, Symbol}

Renders every field of a HighOrderFactorPriorEstimator except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the estimator at every site that renders one. Set set_show_nothing_fields!(:HighOrderFactorPriorEstimator, true) to render it.

Arguments

  • ::HighOrderFactorPriorEstimator: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, which is (:pe, :kte, :ske, :ex, :rsd).

Related

source
show_fields(fees::Fees)

The fields the pretty-printer renders for a Fees: every field but imsk when the mark is nothing, and every field when it is set.

imsk is written by a door, never by a caller, so a fee a caller wrote carries nothing there and renders exactly as it did before the field existed. A fee a door reduced shows the mask it was reduced on, so a reader can tell the two states apart at the REPL.

Arguments

  • fees: The fee to render.

Returns

  • NTuple{N, Symbol}: The field names to print, in declaration order.

Related

source
show_fields(
    opt::Union{EqualWeighted, HierarchicalOptimiser, InverseVolatility, JuMPOptimiser, NestedClustered, RandomWeighted, Stacking, SubsetResampling}
) -> Tuple

Renders every field of a host of the online step except its cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for, and it prints under the optimiser at every site that renders one. Set set_show_nothing_fields! for the type to render it.

Arguments

  • opt: The host.

Returns

  • fields::Tuple: Every field name but cache.

Related

source
show_fields(
    p::Pipeline
) -> Union{Tuple{Symbol, Symbol}, Tuple{Symbol, Symbol, Symbol}}

Renders the names and the steps of a Pipeline, and its cache only where a state is set, so no rendering of a pipeline that took no step moves.

Related

source
PortfolioOptimisers.pretty_show_fields — Function
pretty_show_fields(obj) -> Any

Resolve the fields that @define_pretty_show renders for obj.

Three sources take part, and the precedence is fixed: a per-name entry of SHOW_NOTHING_FIELDS beats the show_fields method of the type, which beats the global default of SHOW_NOTHING_FIELDS. The name is the bare name of the type, so two types of one name in two modules share one entry.

Algorithm

  1. Read cfg, the active value of SHOW_NOTHING_FIELDS, and entry, its per-name entry for the name of the type of obj, giving nothing when no entry is set.
  2. Take fields: every declared field when entry is true, so that a per-name request to show everything overrides a show_fields overload, and the result of show_fields otherwise.
  3. Take show, which is entry when an entry is set and the global default of cfg otherwise.
  4. Return fields when show is true. Otherwise return the members of fields whose value, read with getproperty, is not nothing.

Arguments

  • obj: The value under rendering.

Returns

  • fields: The field names to render, in declaration order. Every declared field, the result of show_fields, or the members of that result whose value is not nothing.

Related

source
PortfolioOptimisers.has_pretty_show_method — Function
has_pretty_show_method(_) -> Bool

Default method indicating whether a type has a custom pretty-printing show method.

Overloading this method to return true indicates that type already has a custom pretty-printing method.

Arguments

  • ::Any: Any type.

Returns

  • flag::Bool: false by default, indicating no custom pretty-printing method.

Related

source
PortfolioOptimisers.pretty_show_vector_summary — Function
pretty_show_vector_summary(val::AbstractVector) -> String

Build the single-line summary for a vector field rendered by @define_pretty_show.

Returns a string of the form "N-element Vector{Name}". A vector is treated as homogeneous when every element shares the same wrapper-type name (so elements that differ only in type parameters are still homogeneous): a homogeneous vector uses that common wrapper name, otherwise the wrapper of the element type, falling back to the raw eltype for Unions.

Algorithm

  1. Collect names, the wrapper-type name of every element. Two elements that differ only in their type parameters share one name.
  2. Read et, the element type of the vector.
  3. Take tname from the branch that names selects: the common name when every entry of names is equal, the string of et when et is a Union, and the wrapper name of et otherwise.
  4. Build the summary from the length of the vector and tname.

Arguments

  • val: Non-empty vector whose elements all have a custom pretty-printing method.

Returns

  • summary::String: Single-line "N-element Vector{Name}" summary.

Related

source
PortfolioOptimisers.pretty_show_vector_element — Function
pretty_show_vector_element(v) -> String

Render a single vector element as a collapsed line for @define_pretty_show.

Every element of a listed vector is shown as just its wrapper-type name. When the element is a struct with fields, a trailing " ⋯" marks it as a collapsed struct (consistent with how an over-budget struct field collapses to Name ⋯); fieldless elements are left bare.

Algorithm

  1. Take s, the wrapper-type name of v.
  2. Return s unchanged when v has no field, and otherwise return s followed by " ⋯".

Arguments

  • v: The vector element to render.

Returns

  • line::String: The collapsed one-line rendering of v.

Related

source
PortfolioOptimisers.pretty_show_vector_body — Function
pretty_show_vector_body(
    io::IO,
    lines::AbstractVector{<:AbstractString}
) -> Any

Apply the shared collapse budget to the per-element lines of a vector rendered by @define_pretty_show.

The budget comes from compact_show_budget, so vector truncation honours the same :limit gate, global set_compact_show! setting, and per-call :po_compact override as struct collapsing. When the budget is nothing (disabled, unlimited output, or override-off) every line is returned. Otherwise, when the listing exceeds the budget it is split head-and-tail, mirroring how Base truncates long arrays, with a single "⋮" line marking the elision.

Algorithm

  1. Read budget from compact_show_budget, and n, the number of lines.
  2. Return lines unchanged when budget is nothing, or when n does not exceed it.
  3. Split the budget into nhead, its half rounded up, and ntail, the rest.
  4. Return the first nhead lines, a single "⋮" line, and the last ntail lines.

Arguments

Returns

  • body::Vector{String}: Lines to print, possibly truncated with a "⋮" separator.

Related

source