Messages: private API

PortfolioOptimisers.did_you_mean — Function
did_you_mean(name::AbstractString, candidates;
             sd::StringDistanceConfig = STRING_DISTANCE[]) -> String

Return a "did you mean" suffix that names the closest match to name in candidates. Return an empty string when candidates is empty, or when no candidate reaches the min_score threshold of sd. The suffix is " (did you mean X?)", with the match in the place of X.

Do not put the suffix in a code span that also holds escaped backticks. JuliaFormatter pairs the backticks wrongly and deletes the spaces around the code spans next to it, and the docstring then renders wrongly.

unknown_variable_msg adds this suffix to a "variable not in asset universe" message, to suggest the correct name for a typo. By default, the function reads the distance and the threshold from the active STRING_DISTANCE configuration. A caller with settings of its own passes them in sd, as suggest_declared_key does. The constructor of StringDistanceConfig checks min_score, so sd cannot hold a threshold that echoes every name. set_string_distance! sets the global default, and with_string_distance sets a task-scoped override. A cluster or a subset of a meta-optimiser can correctly omit a name, and that name has no close neighbour, so the threshold gives it no suggestion.

Algorithm

  1. Return an empty string when candidates is empty, because the function has nothing to search.
  2. Find match, the entry of candidates nearest to name under sd.dist. Keep it only when its normalised similarity reaches sd.min_score.
  3. Return an empty string when step 2 finds no match. Otherwise return the suffix that names match.

Arguments

  • name::AbstractString: The unknown name that the caller wrote.
  • candidates: The collection of valid names to search.
  • sd::StringDistanceConfig: The distance and the threshold. The default is the active STRING_DISTANCE configuration.

Returns

  • msg::String: The suffix " (did you mean X?)", or an empty string when no candidate reaches the threshold.

Related

source
PortfolioOptimisers.suggest_declared_key — Function
suggest_declared_key(key, candidates) -> String

Suggest the entry of candidates nearest to a mistyped declaration key. A declaration key is a macro block key, a dictionary key, a struct field name, or a keyword of a generated constructor.

The function passes did_you_mean a configuration that admits more matches than the global default. It overrides any scoped configuration of the caller. It uses Damerau-Levenshtein, where a transposed pair costs one edit and not two, at min_score = 0.5. The global default is strict so that a guessed name near a real asset name does not get the real name back. That risk does not apply here. The candidates are constants of the code, such as block keys, dictionary keys and field names, and they leak no data. At the default 0.7 under plain Levenshtein, a short key never matches. nuon scores 0.5 against noun, so the suggestion never shows.

Arguments

  • key: The mistyped declaration key. The function converts it to a String.
  • candidates: The collection of valid keys. The function converts each key to a String.

Returns

  • msg::String: The suffix that did_you_mean returns under this configuration.

Related

source
PortfolioOptimisers.unknown_variable_msg — Function
unknown_variable_msg(v, nx, key; candidates = nx, axis::AbstractString = "asset",
                     consequence::AbstractString = "term dropped") -> String

Build the warning or error text for a constraint or view variable v that is not in the universe nx, which the asset sets hold under key. The message names the variable and the size of the universe, and never the full universe. It ends with a did_you_mean suggestion when a close match exists.

candidates is the set of names that the function searches for the typo suggestion. The default is the universe nx. Some callers accept more names than the universe holds. name_to_val! is one of them, because a key can name a group and not an asset. Such a caller passes the asset names together with the group and set keys, so that the suggestion can name a mistyped group. The message always gives length(nx) as the size of the universe, whatever candidates holds.

axis names the universe that the function searched for the variable. The default is "asset", because each constraint resolved against the assets before ExposureConstraintEstimator existed. A re-based constraint resolves its names against the factor universe and passes "factor", so the message names the axis that the user wrote in.

consequence states what the failure removed, because the unit that the library drops depends on the shape. A value with the name as its key loses only that entry. name_to_val! is that case, and it uses the default "term dropped". A row is one statement over many names with one right-hand side, so the library drops the whole row. A fit of a + c == 0.05 as a == 0.05 states a constraint that the caller did not write. get_linear_constraints passes "row dropped". The text "term dropped" in that case sent a reader to look for a row that the library still fitted.

get_linear_constraints, the generation of Black-Litterman views, the generation of entropy-pooling views and name_to_val! all call this function. The text of the message, and the rule that it leaks no data, are thus in one place.

Arguments

  • v: The variable name that is not in the universe.
  • nx: The universe that the function searched. Only its length goes into the message.
  • key: The key of the universe in the asset sets.
  • candidates = nx: The names that the function searches for the typo suggestion.
  • axis::AbstractString = "asset": The name of the universe that the function searched.
  • consequence::AbstractString = "term dropped": What the failure removed. It is "row dropped" where the row is the unit.

Returns

  • msg::String: The diagnostic text, with a did_you_mean suffix when a close match exists.

Related

source
PortfolioOptimisers.misaligned_axis_msg — Function
misaligned_axis_msg(declared, names, axis, key, sym) -> String

Build the error text for a universe, declared under key, that does not agree with the axis sym of the data that the library uses it with. The function compares declared with names.

The position is the only link between a name and a column. A disagreement attaches every constraint row, bound and group to the wrong column, and the optimisation succeeds with the wrong answer. The message therefore names the repair, and not only the fault.

The message reports three kinds of disagreement differently, because they have different causes. Different lengths mean that the two describe different universes. The usual cause is old sets with new sliced data. Equal lengths with the same names mean that the two describe the same universe in a different order. Equal lengths with other names mean that the declared universe holds a name that the data does not have. In both cases the first position that differs is the full diagnosis. The message names the sizes and the first pair that differs, and never one of the universes in full. unknown_variable_msg follows the same rule to leak no data.

Algorithm

  1. Build detail through the branch that the two lengths select.
  2. When the lengths differ, detail names both counts and nothing more, because the two describe different universes.
  3. When the lengths are equal, find i, the first position at which the two differ. detail then names the common count, whether the order or the names differ, i, and the pair at i. The order differs when the two hold the same names, as issetequal finds.
  4. Build the message from detail, the axis, the key, and the repair to make.

Arguments

  • declared: The universe declared under key.
  • names: The axis of the data that the library uses the universe with.
  • axis: The name of the axis, for example "asset".
  • key: The key of the declared universe in the sets.
  • sym: The field of the returns data that holds the correct axis. The repair names it.

Returns

  • msg::String: The error text.

Related

source
PortfolioOptimisers.strict_diagnostic — Function
strict_diagnostic(msg::AbstractString, strict::Bool; id,
                  exception::Type{<:Exception} = ArgumentError) -> Nothing

Report a term that cannot give a row. Under strict, throw an exception. In the other case, log a warning. In both cases the library drops the term.

A builder of linear constraint rows passes exception = IsZeroError when it drops a row whose coefficients are all zero. Such a row does not depend on the weights, so it is true for all weights or for none. The builder drops it at construction time in both cases.

strict applies to three kinds of term that the library can drop. The first is a name that resolves against nothing. The second is a row whose coefficients hold no information, as with a zero centrality vector. The third is a holding that a factor attribution cannot attribute, in an asset that the prior did not estimate or at an observation with no return. The library refuses nothing else. A malformed entry always throws, because the library has no other meaning of it to use. Every such diagnostic of the library goes through this function, so one edit changes the strictness for all of them.

The warning passes maxlog = log_limit(:warn) and _id = id. The caller gives id through @log_id, because only the caller knows its site and the stable parts of its message. The default _id is the line of this function, and every caller shares that line.

Algorithm

  1. Throw an exception that holds msg when strict is true. The call ends there.
  2. Otherwise log msg as a warning, under the cap of log_limit and the _id of the caller, and return.

Arguments

  • msg: The diagnostic text, from unknown_variable_msg or from a function of its family.
  • strict: If true, the function throws an exception. If false, it logs a warning.
  • id: The _id of the warning, which @log_id makes at the site of the caller.
  • exception: The exception type that strict throws. It is IsZeroError for a row whose coefficients are all zero, and ArgumentError in the other cases.

Validation

  • The call raises an exception that holds msg when strict is true.

Returns

  • nothing.

Related

source
PortfolioOptimisers.missing_group_assets_msg — Function
missing_group_assets_msg(group, missing_assets, nx, key) -> String

Build the warning or error text for a group that resolves in the asset sets, but whose members missing_assets are not in the asset universe nx, which the sets hold under key. The message names the group, the missing member names, and the size of the universe. The member names are input from the caller, so they leak no data. The message never names the full universe or the dictionary of input values. It ends with a did_you_mean suggestion for the first missing member.

name_to_val! calls this function. The text of the message, and the rule that it leaks no data, are thus in one place, next to unknown_variable_msg and empty_row_msg.

Arguments

  • group: The group name that resolved in the asset sets.
  • missing_assets: The member names that are not in the asset universe.
  • nx: The asset universe. Only its length goes into the message.
  • key: The key of the asset universe in the asset sets.

Returns

  • msg::String: The diagnostic text, with a did_you_mean suffix for the first missing member.

Related

source
PortfolioOptimisers.empty_row_msg — Function
empty_row_msg(eqn, nx, key; noun::AbstractString = "constraint",
              axis::AbstractString = "asset") -> String

Build the warning or error text for a parsed equation eqn whose names all resolved against the universe nx, which the asset sets hold under key, but whose row is all zero. The library drops that row. The message names the equation and the size of the universe, and never the full universe or the parsed struct. noun is "constraint" for a linear constraint or "view" for a Black-Litterman or an entropy pooling view. axis names the universe, as in unknown_variable_msg.

A name that is not in the universe never gets to this message. The row is the unit, so a name that does not resolve removes the whole row at that name, and unknown_variable_msg reports it with consequence = "row dropped". A row that gets to this message summed to zero for a different reason. Its coefficients cancel, as in A - A == 0.0, which parses to the single term 0.0*A. Or the row holds no variable, as in 1 == 0.004. A typo message for either case sends the user to look for a typo that does not exist. empty_projected_row_msg and zero_centrality_msg follow the same rule.

get_linear_constraints, the generation of Black-Litterman views, and the covariance and correlation views of entropy pooling (ep_cov_views!, ep_rho_views!) call this function.

Arguments

  • eqn: The parsed equation that resolved and still summed to zero.
  • nx: The universe that the terms resolved against. Only its length goes into the message.
  • key: The key of the universe in the asset sets.
  • noun::AbstractString = "constraint": "constraint" for a linear constraint, and "view" for a Black-Litterman or an entropy pooling view.
  • axis::AbstractString = "asset": The name of the universe, as in unknown_variable_msg.

Returns

  • msg::String: The diagnostic text.

Related

source
PortfolioOptimisers.empty_projected_row_msg — Function
empty_projected_row_msg(eqn, nf, key, n; noun::AbstractString = "constraint") -> String

Build the warning or error text for a re-based equation eqn whose terms resolved against the factor universe nf, which the sets hold under key. The projection of the row through the loadings is all zero over n assets.

This failure occurs only under a re-basis, and it is different from the failure of empty_row_msg. In that failure, the coefficients of the row sum to zero. In this failure, they do not, and the projection through the basis makes them zero. The cause is a factor that no asset loads on. A message about the arithmetic of the equation sends the user to check coefficients that are correct.

Arguments

  • eqn: The re-based equation whose projection is an all-zero row.
  • nf: The factor universe that the terms resolved against. Only its length goes into the message.
  • key: The key of the factor universe in the sets.
  • n: The number of assets of the projected row.
  • noun::AbstractString = "constraint": "constraint" for a linear constraint, and "view" for a view.

Returns

  • msg::String: The diagnostic text.

Related

source
PortfolioOptimisers.zero_centrality_msg — Function
zero_centrality_msg(alg, n) -> String

Build the warning or error text for a centrality constraint whose centrality vector holds no information. The library drops the row that the constraint builds from it.

The vector is empty or all zero. In both cases the row is 0' w ⋄ B, which does not depend on the weights, so it constrains nothing that the weights can change. The cause is a property of the graph, and never a mistyped name. Two assets under BetweennessCentrality give the zero vector, because no vertex is on a shortest path between two other vertices. A message from unknown_variable_msg or from a function of its family sends the reader to look for a typo that does not exist. For that reason, this case has its own message.

The message names the centrality algorithm and the length of the vector, and never its entries. empty_row_msg follows the same rule to leak no data.

Arguments

  • alg: The centrality algorithm that made the vector. Only its type name goes into the message.
  • n: The length of the centrality vector. Zero means that the vector is empty.

Returns

  • msg::String: The diagnostic text.

Related

source
PortfolioOptimisers.gross_budget_bounds_msg — Function
gross_budget_bounds_msg(lb, ub) -> String

Build the error text for a gross budget gbgt whose weight bounds lb and ub admit no short position. With no negative bound, the gross exposure is equal to the net exposure. The net budget bgt then already sets the constraint, and gbgt adds nothing.

The message names the size of the bounds and the failed condition, and never the values of the bounds. unknown_variable_msg and the other functions of its family follow the same rule to leak no data. A scalar bound or an absent bound has no size, so the message then names the bounds with no count.

Algorithm

  1. Take n, the larger of the two bound lengths. A bound that is not a vector counts as zero.
  2. Build scope. It names the bounds alone when n is zero, and it names them with the asset count in the other case.
  3. Build the message from the fixed explanation and scope.

Arguments

  • lb: The lower weight bound. Only its length goes into the message.
  • ub: The upper weight bound. Only its length goes into the message.

Returns

  • msg::String: The error text.

Related

source
PortfolioOptimisers.failed_solve_msg — Function
failed_solve_msg(trials::AbstractDict; max_line_length::Integer = 200) -> String

Build the warning text for a JuMP model that no configured solver solved to a satisfactory status. JuMPResult and the res of an OptimisationFailure hold the trials. The text has one line for each failed stage of each solver trial. The line gives the solver name, the stage that failed, and the first line of the error, cut to max_line_length characters. The stage is set_optimizer, optimize!, assert_is_solved_and_feasible or termination_status.

The first line of the error of JuMP.assert_is_solved_and_feasible does not hold the termination status. So a solver that ran records its status under termination_status, from the public JuMP.termination_status, and first_error_line states in words what the status means. A reader sees that the problem is infeasible or unbounded without the raw trials. The solution summary also holds the status, but its type is private to JuMP, so the function does not read it.

The function never interpolates the whole trials dictionary, the solver settings, or the full exception data into the log. The returned trials still hold the raw data. unknown_variable_msg and the other functions of its family follow the same rule to leak no data. The function sorts the solver names and the stages, so the message is the same on each run.

Algorithm

  1. Start msg with the trial count, so that the reader sees how many solvers ran before the detail.
  2. For each solver name, in sorted order, read its entry into trial.
  3. Read stages, the stages of trial. An entry that is not a dictionary becomes the single stage :trial, so a solver that failed before the library recorded a stage still gives a line.
  4. For each stage, in sorted order, skip :settings and :err. The solver settings are input from the caller, and they never go into a log. :err holds the solution summary of optimise_JuMP_model!, which is many lines long, and the termination_status line states its status.
  5. Add one line for each other stage. The line gives the solver name, the stage, and the text of its value from first_error_line. For a termination status that text states what the status means.

Arguments

  • trials::AbstractDict: One entry for each solver trial, with the solver name as its key.
  • max_line_length::Integer = 200: The maximum number of characters of each error line.

Returns

  • msg::String: The warning text, with one line for each failed stage.

Related

source
PortfolioOptimisers.first_error_line — Function
first_error_line(err, max_line_length::Integer) -> String

Render the first line of an error for a log message, cut to max_line_length characters. A … at the end marks the cut. An exception renders through showerror, so the line holds the exception type and message. Each other value renders through repr.

A JuMP termination status is the one exception. Its method states in words what the status of a failed solve means, and what to review, and it does not cut the text, because the library writes that text and it is one line. A status that says the problem has no solution is the most common failure that a user can correct. An infeasible problem asks for weights that no constraint set admits, and an unbounded problem lets the objective improve without limit. The text names the status first, so a reader can also look it up in the documentation of MathOptInterface.

Algorithm

The method that Julia selects on the type of err is the algorithm.

  1. A termination status st:

    1. Build a table from each status that says the problem is infeasible, unbounded, or one of the two, to its meaning and the part of the problem to review. A status at reduced numerical accuracy points to the settings of the solver and the scale of the problem instead.
    2. When the table holds st, return the name of the status and its meaning.
    3. Otherwise return the name of the status alone, such as an iteration limit or a numerical error. Its name states it.
  2. Each other value:

    1. Render err into s, through showerror when err is an Exception and through repr in the other case.
    2. Take line, the text of s up to its first newline.
    3. Return line unchanged when it has at most max_line_length characters. Otherwise return its first max_line_length characters and ….

Arguments

  • err: The error to render, or the termination status that the solver reported.
  • max_line_length::Integer: The maximum number of characters of the returned line before the cut. The method on a termination status ignores it.

Returns

  • line::String: The rendered first line, cut when it is too long. For a termination status, the name of the status, and its meaning when the status is one of the six in the table.

Examples

julia> PortfolioOptimisers.first_error_line(PortfolioOptimisers.JuMP.MOI.INFEASIBLE, 200)"INFEASIBLE: no solution satisfies every constraint. Review the constraints and the input data."julia> PortfolioOptimisers.first_error_line(PortfolioOptimisers.JuMP.MOI.ITERATION_LIMIT, 200)"ITERATION_LIMIT"julia> PortfolioOptimisers.first_error_line(ErrorException("boom\nsecond line"), 200)"boom"

Related

source