Chains

Chains(c::Chains, section::Union{Symbol,AbstractString})
Chains(c::Chains, sections)

Return a new chain with only a specific section or multiple sections pulled out.

Examples

julia> chn = Chains(rand(100, 2, 1), [:a, :b], Dict(:internals => [:a]));

julia> names(chn)
2-element Vector{Symbol}:
 :a
 :b

julia> chn2 = Chains(chn, :internals);

julia> names(chn2)
1-element Vector{Symbol}:
 :a

Base.get(c::Chains, v::Symbol; flatten=false)
Base.get(c::Chains, vs::Vector{Symbol}; flatten=false)

Return a NamedTuple with v as the key, and matching parameter names as the values.

Passing flatten=true will return a NamedTuple with keys ungrouped.

Example

julia> chn = Chains([1:2 3:4]);

julia> get(chn, :param_1)
(param_1 = [1; 2;;],)

julia> get(chn, [:param_2])
(param_2 = [3; 4;;],)

julia> get(chn, :param_1; flatten=true)
(param_1 = 1,)

get(c::Chains; section::Union{Symbol,AbstractVector{Symbol}}, flatten=false)

Return all parameters in a given section(s) as a NamedTuple.

Passing flatten=true will return a NamedTuple with keys ungrouped.

Example

julia> chn = Chains([1:2 3:4], [:a, :b], Dict(:internals => [:a]));

julia> get(chn; section=:parameters)
(b = [3; 4;;],)

julia> get(chn; section=[:internals])
(a = [1; 2;;],)

names(chains::Chains, sections)

Return the parameter names of the sections in the chains.

names(chains::Chains, section::Symbol)

Return the parameter names of a section in the chains.

names(chains::Chains)

Return the parameter names in the chains.

range(chains::Chains)

Return the range of iteration indices of the chains.

sort(c::Chains[; lt=NaturalSort.natural])

Return a new column-sorted version of c.

By default the columns are sorted in natural sort order.

chains(c::Chains)

Return the names or symbols of each chain in a Chains object.

compute_duration(c::Chains; start=start_times(c), stop=stop_times(c))

Calculate the compute time for all chains in seconds.

The duration is calculated as the sum of start - stop in seconds.

compute_duration is more useful in cases of parallel sampling, where wall_duration may understate how much computation time was utilitzed.

get_params(c::Chains; flatten=false)

Return all parameters packaged as a NamedTuple. Variables with a bracket in their name (as in "P[1]") will be grouped into the returned value as P.

Passing flatten=true will return a NamedTuple with keys ungrouped.

Example

julia> chn = Chains(1:5);

julia> x = get_params(chn);

julia> x.param_1
2-dimensional AxisArray{Int64,2,...} with axes:
    :iter, 1:1:5
    :chain, 1:1
And data, a 5×1 Matrix{Int64}:
 1
 2
 3
 4
 5

get_sections(chains[, sections])

Return multiple Chains objects, each containing only a single section.

group(chains::Chains, name::Union{AbstractString,Symbol}; index_type::Symbol=:bracket)

Return a subset of the chain containing parameters with the same name, but a different index.

Bracket indexing format in the form of :name[index] is assumed by default. Use index_type=:dot for parameters with dot indexing, i.e. :sym.index.

header(c::Chains; section=missing)

Return a string containing summary information for a Chains object. If the section keyword is used, this function prints only the relevant section header.

Example

# Printing the whole header.
header(chn)

# Print only one section's header.
header(chn, section = :parameter)

max_stop(c::Chains)

Retrieve the maximum of the stop times (as DateTime) from chain.info.

It is assumed that the start times are stored in chain.info.stop_time as DateTime or unix timestamps of type Float64.

min_start(c::Chains)

Retrieve the minimum of the start times (as DateTime) from chain.info.

It is assumed that the start times are stored in chain.info.start_time as DateTime or unix timestamps of type Float64.

namesingroup(chains::Chains, sym::Union{AbstractString,Symbol}; index_type::Symbol=:bracket)

Return the parameters with the same name sym, but have a different index. Bracket indexing format in the form of :sym[index] is assumed by default. Use index_type=:dot for parameters with dot indexing, i.e. :sym.index.

If the chain contains a parameter of name :sym it will be returned as well.

Example

julia> chn = Chains(rand(100, 2, 2), ["A[1]", "A[2]"]);

julia> namesingroup(chn, :A)
2-element Vector{Symbol}:
 Symbol("A[1]")
 Symbol("A[2]")

julia> # Also works for specific elements.
       namesingroup(chn, Symbol("A[1]"))
1-element Vector{Symbol}:
 Symbol("A[1]")

julia> chn = Chains(rand(100, 3, 2), ["A.1", "A.2", "B"]);

julia> namesingroup(chn, :A; index_type=:dot)
2-element Vector{Symbol}:
 Symbol("A.1")
 Symbol("A.2")

pool_chain(c::Chains)

Combine all chains in c into a single chain by concatenating iterations.

Returns a new Chains object with a single chain containing all iterations from all chains.

replacenames(chains::Chains, dict::AbstractDict)

Replace parameter names by creating a new Chains object that shares the same underlying data.

Examples

julia> chn = Chains(rand(100, 2, 2), ["one", "two"]);

julia> chn2 = replacenames(chn, "one" => "A");

julia> names(chn2)
2-element Vector{Symbol}:
 :A
 :two

julia> chn3 = replacenames(chn2, Dict("A" => "one", "two" => "B"));

julia> names(chn3) 
2-element Vector{Symbol}:
 :one
 :B

resetrange(chains::Chains)

Generate a new chain from chains with iterations indexed by 1:n, where n is the number of samples per chain.

The new chain and chains share the same data in memory.

sections(c::Chains)

Retrieve a list of the sections in a chain.

set_section(chains::Chains, namemap)

Create a new Chains object from chains with the provided namemap mapping of parameter names.

Both chains share the same underlying data. Any parameters in the chain that are unassigned will be placed into the :parameters section.

setinfo(c::Chains, n::NamedTuple)

Return a new Chains object with a NamedTuple type n placed in the info field.

Example

new_chn = setinfo(chn, NamedTuple{(:a, :b)}((1, 2)))

setrange(chains::Chains, range::AbstractVector{Int})

Generate a new chain from chains with iterations indexed by range.

The new chain and chains share the same data in memory.

start_times(c::Chains)

Retrieve the contents of c.info.start_time, or missing if no start_time is set.

stop_times(c::Chains)

Retrieve the contents of c.info.stop_time, or missing if no stop_time is set.

wall_duration(c::Chains; start=min_start(c), stop=max_stop(c))

Calculate the wall clock time for all chains in seconds.

The duration is calculated as stop - start, where as default stop is the latest stopping time and start is the earliest starting time.