StatsProcedures

StatsProcedures.AbstractStatsProcedureType
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.
StatsProcedures.PooledStatsProcedureType
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

StatsProcedures.StatsSpecType
StatsSpec{T<:AbstractStatsProcedure}

Record the 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::Bool=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::Bool=false: print the name of each step 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.
StatsProcedures.StatsStepType
StatsStep{Alias, F<:Function, ById}

Specify the function for moving 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.
  • ById::Bool: whether arguments from multiple StatsSpecs should be grouped by object-id or isequal.

Methods

(step::StatsStep{A,F})(ntargs::NamedTuple; verbose::Bool=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. The value from ntargs supersedes the keyword argument in case both are specified.

Returns

  • NamedTuple: named intermediate results.
Base.:==Method
==(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 .

StatsProcedures.:≊Method
≊(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

StatsProcedures.:≊Method
≊(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.

StatsProcedures._args_kwargsMethod
_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.

StatsProcedures.combinedargsMethod
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 proceed.

StatsProcedures.groupargsMethod
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.

StatsProcedures.poolMethod
pool(ps::AbstractStatsProcedure...)

Construct a PooledStatsProcedure by determining how each StatsStep is shared among several procedures in ps.

It is unsafe to share the same StatsStep in different procedures due to the relative position of this step to the other common steps among these procedures. The fallback method implemented for a collection of AbstractStatsProcedure avoids sharing steps of which the relative positions are not compatible between a pair of procedures.

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

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

Keywords

  • verbose::Bool=false: print the name of each step 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.

StatsProcedures.@specsetMacro
@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::Bool=false: print the name of each step 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).