StatsProcedures
StatsProcedures.AbstractStatsProcedure
— TypeAbstractStatsProcedure{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.PooledStatsProcedure
— TypePooledStatsProcedure
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 ofAbstractStatsProcedure
s.steps::Vector{SharedStatsStep}
: sortedSharedStatsStep
s.
StatsProcedures.SharedStatsStep
— TypeSharedStatsStep{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}
: thestep
that may be shared.ids::Vector{Int}
: indices of procedures that sharestep
.
StatsProcedures.StatsSpec
— TypeStatsSpec{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 theStatsStep
s inT
(default values are merged intoargs
if not found inargs
).
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 tostdout
or the specifiedIO
stream when it is called.keep=nothing
: names (of typeSymbol
) of additional objects to be returned.keepall::Bool=false
: return all objects returned by each step.
StatsProcedures.StatsStep
— TypeStatsStep{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 byStatsStep
withF.instance
.ById::Bool
: whether arguments from multipleStatsSpec
s should be grouped byobject-id
orisequal
.
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.
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_kwargs
— Method_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.combinedargs
— Methodcombinedargs(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
.
StatsProcedures.copyargs
— Methodcopyargs(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
.
StatsProcedures.default
— Methoddefault(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
.
StatsProcedures.groupargs
— Methodgroupargs(s::StatsStep, ntargs::NamedTuple)
Return a tuple of arguments that allow classifying multiple ntargs
s into groups. Equality (defined by isequal
) of the returned tuples across ntargs
s imply that it is possible to exectute step s
for only once to obtain results for these ntargs
s.
This function is important for proceed
to work properly. However, in most cases, there is no need to define new methods for concrete StatsStep
s. Instead, one should define methods for required
, default
or transformed
. See also combinedargs
and copyargs
.
StatsProcedures.pool
— Methodpool(ps::Vector{AbstractStatsProcedure})
Return a PooledStatsProcedure
with identical StatsStep
s shared among several procedures in ps
as SharedStatsStep
s. Steps are sorted based on dependencies specified with prerequisites
.
StatsProcedures.prerequisites
— Methodprerequisites(p::AbstractStatsProcedure, s::StatsStep)
Return a tuple of StatsStep
s 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.
StatsProcedures.proceed
— Methodproceed(sps::AbstractVector{<:StatsSpec}; kwargs...)
Conduct the procedures for the StatsSpec
s in sps
while trying to avoid repeating identical steps for the StatsSpec
s. See also @specset
.
Keywords
verbose::Union{Bool,IO}=false
: print the name of each step tostdout
or the specifiedIO
stream when it is called.keep=nothing
: names (of typeSymbol
) of additional objects to be returned.keepall::Bool=false
: return all objects generated by procedures along with arguments from theStatsSpec
s.pause::Int=0
: break the iteration overStatsStep
s after finishing the specified number of steps (for debugging).
Returns
Vector
: results for each specification in the same order ofsps
.
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.required
— Methodrequired(s::StatsStep)
Return a tuple of Symbol
s representing the names of arguments used to form groupargs
that do not have defaults. See also default
and transformed
.
StatsProcedures.transformed
— Methodtransformed(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
.
StatsProcedures.@specset
— Macro@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 StatsSpec
s with shared default values for arguments and then conduct the procedures by calling proceed
. The vector of StatsSpec
s and a vector of result objects are returned, unless alternative behavior is specified with the option
s.
Arguments
[option option=val ...]
: optional settings for@specset
including keyword arguments forproceed
.default_args...
: optional default values for arguments shared by allStatsSpec
s.code block
: abegin/end
block or afor
loop containing arguments for constructingStatsSpec
s.
Notes
@specset
transforms Expr
s 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, Macro
s that generate Expr
s 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 callproceed
and only return the vector ofStatsSpec
s.verbose::Union{Bool,IO}=false
: print the name of each step tostdout
or the specifiedIO
stream when it is called.keep=nothing
: names (of typeSymbol
) of additional objects to be returned.keepall::Bool=false
: return all objects generated by procedures along with arguments from theStatsSpec
s.pause::Int=0
: break the iteration overStatsStep
s after finishing the specified number of steps (for debugging).