StatsProcedures

AbstractStatsProcedure{Alias, T<:NTuple{N,StatsStep} where N}

Supertype for all types specifying the procedure for statistical estimation or inference.

Fallback methods for indexing and iteration are defined for all subtypes of AbstractStatsProcedure.

Parameters

• Alias::Symbol: alias of the type for pretty-printing.
• T<:NTuple{N,StatsStep}: steps involved in the procedure.

PooledStatsProcedure

A collection of procedures and shared steps.

An instance of PooledStatsProcedure is indexed and iterable among the shared steps in a way that helps avoid repeating identical steps. See also pool.

Fields

• procs::Vector{AbstractStatsProcedure}: a collection of AbstractStatsProcedures.
• steps::Vector{SharedStatsStep}: sorted SharedStatsSteps.

SharedStatsStep{Alias, F<:Function, ById}

A StatsStep that is possibly shared by multiple instances of procedures that are subtypes of AbstractStatsProcedure. See also PooledStatsProcedure and pool.

Fields

• step::StatsStep{Alias, F, ById}: the step that may be shared.
• ids::Vector{Int}: indices of procedures that share step.

StatsSpec{T<:AbstractStatsProcedure}

Specification for a statistical procedure of type T.

An instance of StatsSpec is callable and its fields provide all information necessary for conducting the procedure. An optional name for the specification can be specified.

Fields

• name::String: a name for the specification (takes "" if not specified).
• args::NamedTuple: arguments for the StatsSteps in T (default values are merged into args if not found in args).

Methods

(sp::StatsSpec{T})(; verbose::Union{Bool,IO}=false, keep=nothing, keepall::Bool=false)

Execute the procedure of type T with the arguments specified in args. By default, a dedicated result object for T is returned if it is available. Otherwise, the last value returned by the last StatsStep is returned.

Keywords

• verbose::Union{Bool,IO}=false: print the name of each step to stdout or the specified IO stream when it is called.
• keep=nothing: names (of type Symbol) of additional objects to be returned.
• keepall::Bool=false: return all objects returned by each step.

StatsStep{Alias, F<:Function, ById}

Specification for a step in an AbstractStatsProcedure. An instance of StatsStep is callable.

Parameters

• Alias::Symbol: alias of the type for pretty-printing.
• F<:Function: type of the function to be called by StatsStep with F.instance.
• ById::Bool: whether arguments from multiple StatsSpecs should be grouped by object-id or isequal.

Methods

(step::StatsStep{A,F})(ntargs::NamedTuple; verbose::Union{Bool,IO}=false)

Call an instance of function of type F with arguments extracted from ntargs via groupargs and combinedargs.

A message with the name of the StatsStep is printed to stdout if a keyword verbose takes the value true or ntargs contains a key-value pair verbose=true. Alternative IO stream can be specified by setting the value of verbose. The value from ntargs supersedes the keyword argument in case both are specified.

Returns

• NamedTuple: named intermediate results.

==(x::StatsSpec{T}, y::StatsSpec{T})

Test whether two instances of StatsSpec with the same parameter T also have the same field args.

See also ≊.

≊(x::NamedTuple, y::NamedTuple)

Test whether two instances of NamedTuple contain the same set of key-value pairs while ignoring the order.

See https://discourse.julialang.org/t/check-equality-of-two-namedtuples-with-order-of-the-fields-ignored

≊(x::StatsSpec{T}, y::StatsSpec{T})

Test whether two instances of StatsSpec with the same parameter T also have the field args containing the same sets of key-value pairs while ignoring the orders.

_args_kwargs(exprs)

Return an expression of Vector{Any} and an expression of Dict{Symbol,Any} where the latter collects any Expr in exprs with head being :(=) and the former collects the rest.

combinedargs(s::StatsStep, allntargs::Any)

Return a tuple of arguments obtained by combining a collection of arguments across multiple specifications.

The element type of allntargs can be assumed to be NamedTuple. This function allows combining arguments that differ across specifications in the same group classified based on groupargs into objects that are accepted by the call of s. See also copyargs and proceed.

copyargs(s::StatsStep)

Return a tuple of indices of arguments that are mutable objects that may be modified in-place by s. This allows making copys of mutable objects that are initially shared across multiple specifications. See also groupargs, combinedargs and proceed.

default(s::StatsStep)

Return a NamedTuple of arguments with keys showing the names and values representing the defaults to be used to form groupargs. See also required and transformed.

groupargs(s::StatsStep, ntargs::NamedTuple)

Return a tuple of arguments that allow classifying multiple ntargss into groups. Equality (defined by isequal) of the returned tuples across ntargss imply that it is possible to exectute step s for only once to obtain results for these ntargss.

This function is important for proceed to work properly. However, in most cases, there is no need to define new methods for concrete StatsSteps. Instead, one should define methods for required, default or transformed. See also combinedargs and copyargs.

pool(ps::Vector{AbstractStatsProcedure})

Return a PooledStatsProcedure with identical StatsSteps shared among several procedures in ps as SharedStatsSteps. Steps are sorted based on dependencies specified with prerequisites.

prerequisites(p::AbstractStatsProcedure, s::StatsStep)

Return a tuple of StatsSteps that must be completed prior to executing step s when conducting procedure p. If p consists of more than one StatsStep, this method must be defined for each step in p in order to allow pool to share a StatsStep across multiple procedures.

proceed(sps::AbstractVector{<:StatsSpec}; kwargs...)

Conduct the procedures for the StatsSpecs in sps while trying to avoid repeating identical steps for the StatsSpecs. See also @specset.

Keywords

• verbose::Union{Bool,IO}=false: print the name of each step to stdout or the specified IO stream when it is called.
• keep=nothing: names (of type Symbol) of additional objects to be returned.
• keepall::Bool=false: return all objects generated by procedures along with arguments from the StatsSpecs.
• pause::Int=0: break the iteration over StatsSteps after finishing the specified number of steps (for debugging).

Returns

• Vector: results for each specification in the same order of sps.

By default, either a dedicated result object for the corresponding procedure or the last value returned by the last StatsStep becomes an element in the returned Vector for each StatsSpec. When either keep or keepall is specified, a NamedTuple with additional objects is formed for each StatsSpec.

required(s::StatsStep)

Return a tuple of Symbols representing the names of arguments used to form groupargs that do not have defaults. See also default and transformed.

transformed(s::StatsStep, ntargs::NamedTuple)

Return a tuple of arguments transformed from fields in ntargs to be used to form groupargs. See also required and default.

@specset [option option=val ...] default_args... begin ... end
@specset [option option=val ...] default_args... for v in (...) ... end
@specset [option option=val ...] default_args... for v in (...), w in (...) ... end

Construct a vector of StatsSpecs with shared default values for arguments and then conduct the procedures by calling proceed. The vector of StatsSpecs and a vector of result objects are returned, unless alternative behavior is specified with the options.

Arguments

• [option option=val ...]: optional settings for @specset including keyword arguments for proceed.
• default_args...: optional default values for arguments shared by all StatsSpecs.
• code block: a begin/end block or a for loop containing arguments for constructing StatsSpecs.

Notes

@specset transforms Exprs that construct StatsSpec to collect the sets of arguments from the code block and infers how the arguments entered by users need to be processed based on the names of functions called within StatsSpec. For end users, Macros that generate Exprs for these function calls should be provided.

Optional default arguments are merged with the arguments provided for each individual specification and supersede any default value associated with each StatsStep via default. These default arguments should be specified in the same pattern as how arguments are specified for each specification inside the code block, as @specset processes these arguments by calling the same functions found in the code block.

Options for the behavior of @specset can be provided in a bracket [...] as the first argument with each option separated by white space. For options that take a Boolean value, specifying the name of the option is enough for setting the value to be true.

The following options are available for altering the behavior of @specset:

• noproceed::Bool=false: do not call proceed and only return the vector of StatsSpecs.
• verbose::Union{Bool,IO}=false: print the name of each step to stdout or the specified IO stream when it is called.
• keep=nothing: names (of type Symbol) of additional objects to be returned.
• keepall::Bool=false: return all objects generated by procedures along with arguments from the StatsSpecs.
• pause::Int=0: break the iteration over StatsSteps after finishing the specified number of steps (for debugging).