Naming Simulations

savename([prefix,], c [, suffix]; kwargs...)

Create a shorthand name, commonly used for saving a file or as a figure title, based on the parameters in the container c (Dict, NamedTuple or any other Julia composite type, e.g. created with Parameters.jl). If provided use the prefix and end the name with .suffix (i.e. you don't have to include the . in your suffix).

The function chains keys and values into a string of the form:

key1=val1_key2=val2_key3=val3

while the keys are always sorted alphabetically. If you provide the prefix/suffix the function will do:

prefix_key1=val1_key2=val2_key3=val3.suffix

assuming you chose the default connector, see below. Notice that prefix can be any path, and in addition if it ends with / or \ then the connector after prefix is ommited (although joinpath should be preferred instead of putting paths in prefix). See default_prefix for more.

savename can be very conveniently combined with @dict or @ntuple. See also parse_savename.

Keywords

• allowedtypes = default_allowed(c) : Only values of type subtyping anything in allowedtypes are used in the name. By default this is (Real, String, Symbol).
• accesses = allaccess(c) : You can also specify which specific keys you want to use with the keyword accesses. By default this is all possible keys c can be accessed with, see allaccess.
• digits = 3 : Floating point values are rounded to digits. In addition if the following holds:

  round(val; digits = digits) == round(Int, val)

  then the integer value is used in the name instead.
• scientific = nothing : Number of significant digits used for rounding of floating point values using scientific notation (e.g. 1.65e-7). If nothing, normal rounding is done.
• connector = "_" : string used to connect the various entries.
• expand::Vector{String} = default_expand(c) : keys that will be expanded to the savename of their contents, to allow for nested containers. By default is empty. Notice that the type of the container must also be allowed in allowedtypes for expand to take effect! Empty containers are always skipped and the savename of the nested arguments is always called with its default arguments (so customization here is possible only by rolling your own container type). If the savename of the nested containers is "", it is also skipped.

Examples

d = (a = 0.153456453, b = 5.0, mode = "double")
savename(d; digits = 4) == "a=0.1535_b=5_mode=double"
savename("n", d) == "n_a=0.153_b=5_mode=double"
savename("n/", d) == "n/a=0.153_b=5_mode=double"
savename(d, "n") == "a=0.153_b=5_mode=double.n"
savename("data/n", d, "n") == "data/n_a=0.153_b=5_mode=double.n"
savename("n", d, "n"; connector = "-") == "n-a=0.153-b=5-mode=double.n"
savename(d, allowedtypes = (String,)) == "mode=double"

rick = (never = "gonna", give = "you", up = "!");
savename(rick) == "give=you_never=gonna_up=!" # keys are sorted!

@dict vars...

Create a dictionary out of the given variables that has as keys the variable names and as values their values.

Notice: @dict a b is the correct way to call the macro. @dict a, b is incorrect. If you want to use commas you have to do @dict(a, b).

Examples

julia> ω = 5; χ = "test"; ζ = π/3;

julia> @dict ω χ ζ
Dict{Symbol,Any} with 3 entries:
  :ω => 5
  :χ => "test"
  :ζ => 1.0472

@savename vars...

Convenient combination of chaining a call to @dict on vars and savename.

Examples

julia> a = 0.153456453; b = 5.0; mode = "double"
julia> @savename a b mode
"a=0.153_b=5_mode=double"

@strdict vars...

Same as @dict but the key type is String.

@ntuple vars...

Create a NamedTuple out of the given variables that has as keys the variable names and as values their values.

Examples

julia> ω = 5; χ = "test"; ζ = 3.14;

julia> @ntuple ω χ ζ
(ω = 5, χ = "test", ζ = 3.14)

ntuple2dict(nt) -> dict

Convert a NamedTuple to a dictionary.

dict2ntuple(dict) -> ntuple

Convert a dictionary (with Symbol or String as key type) to a NamedTuple.

allaccess(c)

Return all the keys c can be accessed using access. For dictionaries/named tuples this is keys(c), for everything else it is fieldnames(typeof(c)).

access(c, key)

Access c with given key. For AbstractDict this is getindex, for anything else it is getproperty.

access(c, keys...)

When given multiple keys, access is called recursively, i.e. access(c, key1, key2) = access(access(c, key1), key2) and so on. For example, if c, c.k1 are NamedTuples then access(c, k1, k2) == c.k1.k2.

default_allowed(c) = (Real, String, Symbol)

Return the (super-)Types that will be used as allowedtypes in savename or other similar functions.

default_prefix(c) = ""

Return the prefix that will be used by default in savename or other similar functions.

Notice that if default_prefix is defined for c but a prefix is also given to savename then the two values are merged via joinpath for convenience (if they are not the same of course).

E.g. defining default_prefix(c::MyType) = "lala" and calling

savename(datadir(), mytype)

will in fact return a string that looks like

"path/to/data/lala_p1=..."

This allows savename to work well with produce_or_load.

default_expand(c) = String[]

Keys that should be expanded in their savename within savename. Must be Vector{String} (as all keys are first translated into strings inside savename).

parse_savename(filename::AbstractString; kwargs...)

Try to convert a shorthand name produced with savename into a dictionary containing the parameters and their values, a prefix and suffix string. Return prefix, parameters, suffix.

Parsing the key-value parts of filename is performed under the assumption that the value is delimited by = and the closest connector. This allows the user to have connector (eg. _) in a key name (variable name) but not in the value part.

Keywords

• connector = "_" : string used to connect the various entries.
• parsetypes = (Int, Float64) : tuple used to define the types which should be tried when parsing the values given in filename. Fallback is String.