Preferences: private API

PortfolioOptimisers.PREFERENCE_KEYS — Constant
PREFERENCE_KEYS

The Preferences.jl keys that the package reads at load time to set the global configuration defaults, through apply_preferences!.

  • "equation_max_length" and "equation_max_depth": Positive integers for EQUATION_LIMITS.
  • "max_n_sim", "max_n_subsets", "max_frontier", "max_bins", "max_hop_count", "max_search_grid" and "max_ep_grid": Positive integers for RESOURCE_LIMITS.
  • "suggestion_min_score": A real number for the threshold of STRING_DISTANCE.
  • "suggestion_distance": A name from PREFERENCE_DISTANCES for the distance of STRING_DISTANCE.
  • "compact_show": A boolean or an integer for COMPACT_SHOW.
  • "show_nothing_fields": A boolean for the global switch of SHOW_NOTHING_FIELDS.
  • "show_nothing_fields_by_type": A table of booleans, one for each type name, for the per-name entries of SHOW_NOTHING_FIELDS.
  • "max_warn", "max_info" and "max_debug": Positive integers for LOG_LIMITS.

Preferences.jl cannot list the keys that a project set. The package thus cannot find a misspelled key, and it ignores that key with no message, so the package default applies. A misspelled or invalid value under one of these keys stops the load. The package also cannot refuse a name in the "show_nothing_fields_by_type" table that matches no type. A type outside the package can print through @define_pretty_show, so the package accepts an unknown name, and the entry has no effect.

The package applies each valid value, and it warns about a value that widens a guard, through relaxed_preferences_msg. A preference file is data. It comes with a cloned project, and it applies before any user code runs.

Related

source
PortfolioOptimisers.PREFERENCE_DISTANCES — Constant
PREFERENCE_DISTANCES

Allowlist that maps each name that the "suggestion_distance" preference accepts to its StringDistances.StringDistance object. One Dict holds the accepted names and the objects that they select, as the function allowlist of the equation parser does. An unknown name stops the load with an ArgumentError, and the message has a did_you_mean suggestion.

The accepted names are "levenshtein", "damerau_levenshtein", "jaro", "jaro_winkler" and "ratcliff_obershelp".

Related

source
PortfolioOptimisers.apply_preferences! — Function
apply_preferences!(prefs::AbstractDict{<:AbstractString})

Apply the load-time preference values to the global configuration defaults. These are EQUATION_LIMITS, RESOURCE_LIMITS, STRING_DISTANCE, COMPACT_SHOW, SHOW_NOTHING_FIELDS and LOG_LIMITS. The package __init__ calls this function with the values of PREFERENCE_KEYS that Preferences.load_preference reads. The function skips a nothing value, which is a preference that the project did not set, and the package default stays.

An invalid value raises an ArgumentError that names the key and the value. The package then does not load, and it does not run with a wrong value. The function applies each value through its set_*! function, so a preference gets the same validation as a call at run time.

The function applies a valid value of any size. A cap turns a kill by the out-of-memory killer into an error with a type. It does not judge a size, and a project on a large machine can correctly raise a cap. A value that widens a guard gives a @warn with the text of relaxed_preferences_msg, because a preference needs no code to change a guard. A LocalPreferences.toml is data, it comes with a cloned project, and it applies before any user code runs. A widened guard is a raised cap of RESOURCE_LIMITS or EQUATION_LIMITS, or a lowered suggestion threshold of STRING_DISTANCE. A value that tightens a guard, or that is equal to the default that it replaces, gives no message. The function compares each value with the default that is active when it applies the preference. At load, that is the package default.

To keep a configuration, put the keys in the LocalPreferences.toml of the active project, as in this example:

[PortfolioOptimisers]
equation_max_length = 512
equation_max_depth = 64
max_n_sim = 50_000
max_n_subsets = 1_000
max_frontier = 1_000
max_bins = 500
max_hop_count = 100
max_search_grid = 10_000
max_ep_grid = 500
suggestion_min_score = 0.8
suggestion_distance = "damerau_levenshtein"
compact_show = 4
show_nothing_fields = true
max_warn = 1
max_info = 1
max_debug = 10

[PortfolioOptimisers.show_nothing_fields_by_type]
SimpleVariance = false

Algorithm

  1. Start relaxations as an empty vector. It collects one (key, default, value) triple for each guard that the preferences widen.
  2. Read the two equation keys. When one of them is set, check that every set value is a positive integer, and read the current default of EQUATION_LIMITS. Record a triple for each value above its default, and apply both values through set_equation_limits!. A key that the project did not set keeps the value that it already has.
  3. Read the seven resource keys, and do step 2 again with RESOURCE_LIMITS and set_resource_limits!.
  4. Read "suggestion_min_score". When it is set, check that it is a real number. Record a triple when it is below the current threshold, and apply it through set_string_distance!. A lower threshold widens the guard, which is the opposite direction to a cap.
  5. Read "suggestion_distance". When it is set, check that it is a string, and find it in PREFERENCE_DISTANCES. An unknown name raises an error, and the message has a did_you_mean suggestion. Apply the distance that the name selects through set_string_distance!.
  6. Read "compact_show". When it is set, check that it is a boolean or an integer, and apply it through set_compact_show!. This key is not a guard, so it records no triple.
  7. Pass prefs to apply_show_preferences!, which reads "show_nothing_fields" and "show_nothing_fields_by_type". Neither key is a guard, so neither records a triple.
  8. Pass prefs to apply_log_preferences!, which reads "max_warn", "max_info" and "max_debug". A cap never hides the first message of a site, so none of the three records a triple.
  9. When relaxations is not empty, log the text of relaxed_preferences_msg as a warning, under the cap that step 8 set.

Arguments

  • prefs: One entry for each key of PREFERENCE_KEYS. A nothing value means that the project set no preference for that key, and the package default stays.

Validation

  • Each of the nine cap keys is a positive integer that is not a Bool.
  • "suggestion_min_score" is a real number that is not a Bool.
  • "suggestion_distance" is a string, and it names an entry of PREFERENCE_DISTANCES.
  • "compact_show" is a Bool or an Integer.
  • "show_nothing_fields" is a Bool, and "show_nothing_fields_by_type" is a table of Bool values. apply_show_preferences! checks both.
  • Each of "max_warn", "max_info" and "max_debug" is a positive integer that is not a Bool. apply_log_preferences! checks them.
  • A breach of a rule above raises an ArgumentError that names the key and the value, and the package does not load.

Returns

  • nothing.

Related

source
PortfolioOptimisers.apply_show_preferences! — Function
apply_show_preferences!(
    prefs::AbstractDict{<:AbstractString}
)

Apply the two load-time preferences of SHOW_NOTHING_FIELDS, the global switch and the per-name table. apply_preferences! calls this function, and its docstring states the rules for all preferences. The function skips a nothing value, which is a preference that the project did not set, and the package default stays.

An invalid value raises an ArgumentError that names the key and the value, as in apply_preferences!. The function does not refuse a name in the table that matches no type. PREFERENCE_KEYS gives the reason.

Algorithm

  1. Read "show_nothing_fields". When it is set, check that it is a Bool, and apply it through the one-argument form of set_show_nothing_fields!.
  2. Read "show_nothing_fields_by_type". When it is set, check that it is a table and that every value is a Bool. Convert each key to a Symbol, and apply each entry through the per-name form of set_show_nothing_fields!.

Arguments

  • prefs: The dictionary that apply_preferences! gets. The function reads only the two keys above.

Validation

  • "show_nothing_fields" is a Bool.
  • "show_nothing_fields_by_type" is a dictionary, and every value in it is a Bool.
  • A breach of either rule raises an ArgumentError that names the key and the value.

Returns

  • nothing.

Related

source
PortfolioOptimisers.apply_log_preferences! — Function
apply_log_preferences!(
    prefs::AbstractDict{<:AbstractString}
)

Apply the three load-time preferences of LOG_LIMITS, "max_warn", "max_info" and "max_debug". apply_preferences! calls this function, and its docstring states the rules for all preferences. A nothing value is a preference that the project did not set, and the package default stays.

An invalid value raises an ArgumentError that names the key and the value, as in apply_preferences!. A valid value gives no message. A cap limits only the repeats of a message and never hides the first one. A cap thus widens no guard, and records no triple for relaxed_preferences_msg. TOML has no nothing, so a project gets the package default back when it deletes the key.

Algorithm

  1. Read the three keys. When none is set, return.
  2. Check that every set value is a positive integer that is not a Bool.
  3. Apply the three values through set_log_limits!. A key that the project did not set keeps the value that it already has.

Arguments

  • prefs: The dictionary that apply_preferences! gets. The function reads only the three keys above.

Validation

  • Each of "max_warn", "max_info" and "max_debug" is a positive integer that is not a Bool.
  • A breach raises an ArgumentError that names the key and the value.

Returns

  • nothing.

Related

source
PortfolioOptimisers.__init__ — Function
__init__()

Load hook of the package. It reads the preferences of PREFERENCE_KEYS for the active project with Preferences.load_preference, and applies them to the global configuration defaults through apply_preferences!. An invalid preference value stops the load, and the package does not run with a wrong value.

A preference is the one way to change a guard with no code. A LocalPreferences.toml is data, it comes with a cloned project or a template, and this hook reads it before any user code runs. The package thus applies a valid value, and it warns about a value that widens a guard, through relaxed_preferences_msg.

The hook also registers plots_extension_hint for MethodError. A call to a plot function before its package extension loads then names the packages that load its extension.

Algorithm

  1. Register plots_extension_hint with Base.Experimental.register_error_hint.
  2. Read every key of PREFERENCE_KEYS with Preferences.load_preference. The value is nothing for a key that the active project did not set.
  3. Pass the dictionary to apply_preferences!, which checks each value and applies it.

Returns

  • nothing.

Related

source
PortfolioOptimisers.relaxed_preferences_msg — Function
relaxed_preferences_msg(
    relaxations::AbstractVector
) -> String

Build the warning text for the load-time preferences that widened a guard, for apply_preferences!. The text has one line for each key, with the key, the default that it replaced, and the value that the project set.

A preference file is data. It comes with a cloned project or a template, git often does not track it, and __init__ applies it at using PortfolioOptimisers, before any user code runs. A value that tightens a guard needs no warning, so the warning names only the widened guards. These are a cap of RESOURCE_LIMITS or EQUATION_LIMITS that the file raised, and a suggestion threshold of STRING_DISTANCE that it lowered. A lower threshold admits more candidates, so it can leak more asset names.

The function never interpolates the whole preference dictionary, so a key that the message does not name stays out of the log. unknown_variable_msg follows the same rule to leak no data.

Algorithm

  1. Start msg with the number of widened guards and the sentence that says when a preference applies.
  2. Add one line for each triple. The line names the key, the default that it replaced, and the value that the project set.
  3. End msg with the two repairs. The user can delete the key, or widen the guard for one scope with a with_* function.

Arguments

  • relaxations: One (key, default, value) triple for each widened guard, in the order of PREFERENCE_KEYS.

Returns

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

Related

source