Advanced usage
Mining Policies
It is possible to limit the action of the mining, to force an AbstractMiner to only consider a subset of the available data.
ModalAssociationRules.worldfilter — Functionworldfilter(::AbstractMiner)Return the world filter policy wrapped within the AbstractMiner. This specifies how the worlds of a modal instance must be iterated.
See also AbstractMiner, data(::AbstractMiner), SoleLogics.WorldFilter.
worldfilter(miner::Miner)See also worldfilter(::AbstractMiner).
worldfilter(bulldozer::Bulldozer) = bulldozer.worldfilterSee also worldfilter(::AbstractMiner).
We can also constrain the generation of new itemsets and rules, by defining a vector of policies. For what regards itemsets, the following dispatches are available:
ModalAssociationRules.itemset_policies — Functionfunction itemset_policies(::AbstractMiner)Return the mining policies vector wrapped within an AbstractMiner. Each mining policies is a meta-rule describing which Itemset are accepted during the mining phase and which are discarded.
These policies often require to be tailored ad-hoc for a specific mining algorithm, and have the role of pruning unwanted explorations of the search space as early as possible.
Keep in mind that you may need to modify some existing policies to make them correct and effective for your custom algorithm.
As far as the algorithms already implemented in this package are concerned, generation policies are applied before saving an itemset inside the miner: thus, they reduce the waste of memory, but not necessarily of computational time.
See also AbstractMiner, generaterules, arule_policies.
function itemset_policies(miner::Miner)itemset_policies(bulldozer::Bulldozer)See also itemset_policies(::AbstractMiner).
ModalAssociationRules.islimited_length_itemset — Functionfunction islimited_length_itemset(; maxlength::Union{Nothing,Integer}=nothing)::FunctionClosure returning a boolean function F with one argument itemset::Itemset.
F is true if the length of the given itemset does not exceed the given thresholds.
Arguments
maxlength::Union{Nothing,Integer}=nothing: maximumitemset's length; whennothing, defaults totypemax(Int16).
See also Itemset, itemset_policies.
ModalAssociationRules.isanchored_itemset — Functionfunction isanchored_itemset(;
npropositions::Integer=1,
ignoreuntillength::Integer=1
)::FunctionClosure returning a boolean function F with one argument rule::Itemset.
F is true if the given itemset contains atleast npropositions propositional anchors (that is, propositions without modal operators).
Arguments
npropositions::Integer=1: minimum number of propositional anchors (propositions with no modal operators) in the antecedent of the given rule.ignoreuntillength::Integer=1: avoid applying the policy to isolatedItems, orItemsetshort enough.
See Item, Itemset, itemset_policies, isanchored_arule.
ModalAssociationRules.isdimensionally_coherent_itemset — Functionfunction isdimensionally_coherent_itemset(;)::FunctionClosure returning a boolean function F with one argument itemset::Itemset.
This is needed to ensure the Itemset is coherent with the dimensional definition of local support. All the propositions (or anchors) in an itemset must be VariableDistances wrapping references of the same size.
See also Itemset, itemset_policies, SoleData.VariableDistance.
The following are referred to association rules:
ModalAssociationRules.arule_policies — Functionarule_policies(::AbstractMiner)Return the association rules generation policies vector wrapped within an AbstractMiner. Each generation policies is a meta-rule describing which ARule are accepted during the generation algorithm and which are discarded.
See also AbstractMiner, generaterules, itemset_policies.
arule_policies(miner::Miner)ModalAssociationRules.islimited_length_arule — Functionfunction islimited_length_arule(;
antecedent_maxlength::Union{Nothing,Integer}=nothing,
consequent_maxlength::Union{Nothing,Integer}=1
)::FunctionClosure returning a boolean function F with one argument rule::ARule.
F is true if the length of rule's antecedent (and consequent) does not exceed the given thresholds.
Arguments
antecedent_maxlength::Union{Nothing,Integer}=nothing: maximum antecedent length of the given rule; whennothing, defaults totypemax(Int16);consequent_maxlength::Union{Nothing,Integer}=1: maximum consequent length of the given rule; whennothing, defaults totypemax(Int16).
See also antecedent, ARule, arule_policies, consequent.
ModalAssociationRules.isanchored_arule — Functionfunction isanchored_arule(; npropositions::Integer=1)::FunctionClosure returning a boolean function F with one argument rule::ARule.
F is true if the given rule contains atleast npropositions propositional anchors (that is, propositions without modal operators).
Arguments
npropositions::Integer=1: minimum number of propositional anchors (propositions with no modal operators) in the antecedent of the given rule.
See antecedent, ARule, arule_policies, generaterules, Item, Miner.
ModalAssociationRules.isheterogeneous_arule — Functionfunction isheterogeneous_arule(;
antecedent_nrepetitions::Integer=1,
consequent_nrepetitions::Integer=0,
consider_thresholds::Bool=false
)::FunctionClosure returning a boolean function F with one argument rule::ARule.
F is true if the given rule is heterogeneous, that is, across all the Item in rule antecedent and consequent, the number of identical variables V is at most nrepetitions.
Arguments
antecedent_nrepetitions::Integer=1: maximum allowed number of identical variables in the antecedent of the given rule.consequent_nrepetitions::Integer=0: maximum allowed number of identical variables between the antecedent and the consequent of the given rule.consider_thresholds::Bool=false: if true, both identical variables and thresholds are considered in the counting.
See antecedent, ARule, consequent, generaterules, Item, Miner.
To apply the policies, simply call the following.
Missing docstring for Base.filter!(targets::Vector{Union{ARule,Itemset}}, policies_pool::Vector{Function}). Check Documenter's build log for details.
Anchored semantics
To ensure the mining process is fair when dealing with modal operators, we must ensure that the miner is compliant with anchored semantics constraints.
ModalAssociationRules.isanchored_miner — Functionisanchored_miner(miner::AbstractMiner)Check if miner is provided of both isdimensionally_coherent_itemset and isanchored_itemset policy and, in particular, if ignoreuntillength parameter is set to 1 or above in the latter.
See also AbstractMiner, isanchored_itemset, isdimensionally_coherent_itemset.
ModalAssociationRules.anchored_apriori — Functionanchored_apriori(miner::AbstractMiner; kwargs...)::NothingAnchored version of apriori algorithm, that is exactly apriori but assuring that miner possess atleast isanchored_itemset policy, with ignoreuntillength parameter set to 1 or higher.
TODO - insert a reference to TIME2025 article.
See also AbstractMiner, anchored_semantics, apriori.
ModalAssociationRules.anchored_fpgrowth — Functionfunction anchored_fpgrowth(miner::M; kwargs...)::M where {M<:AbstractMiner}Implementation of fpgrowth with anchored semantics. Essentially, Items are SoleData.VariableDistances wrapping motifs.
More information about motifs: <insert-link> More information about the implementation: <insert-link>
See also AbstractMiner, anchored_semantics, 'fpgrowth`.
ModalAssociationRules.anchored_eclat — Functionfunction anchored_eclat(miner::M; kwargs...)::M where {M<:AbstractMiner}Implementation of eclat with anchored semantics.
See also AbstractMiner, anchored_semantics, eclat.
Each algorithm above is simply a small wrapper around anchored_semantics:
ModalAssociationRules.anchored_semantics — Functionanchored_semantics(miner::M; kwargs...)::M where {M<:AbstractMiner}Logic to be executed before the the algorithm wrapped within the miner; the goal is to make such an algorithm coherent with anchored semantics.
Utilities
The following utilities often involve performing some combinatoric trick between Itemsets and ARules, and might be useful to avoid reinventing the wheel.
ModalAssociationRules.combine_items — Functioncombine_items(itemsets::AbstractVector{<:Itemset}, newlength::Integer)Return a generator which combines Itemsets from itemsets into new itemsets of length newlength by taking all combinations of two itemsets and joining them.
See also Itemset.
combine_items(variable::AbstractVector{<:Item}, fixed::AbstractVector{<:Item})Return a generator of Itemset, which iterates the combinations of Items in variable and prepend them to fixed vector.
ModalAssociationRules.grow_prune — Functiongrow_prune(
candidates::AbstractVector{Itemset},
frequents::AbstractVector{Itemset},
k::Integer
)Return a generator, which yields only the candidates for which every (k-1)-length subset is in frequents.
See also Itemset.
ModalAssociationRules.anchored_grow_prune — Functionanchored_grow_prune(
candidates::AbstractVector{Itemset},
frequents::AbstractVector{Itemset},
k::Integer
)Return a generator, which yields only the candidates for which every (k-1)-length subset is in frequents.
Differently from grow_prune, this method supports anchored semantics. This means that, for example, the following Itemsets are not pruned [[L]min[V1] > -0.5, min[V3] > -3.6], [min[V3] > -3.6, [L]min[V3] > -3.6] and can be merged in [[L]min[V1] > -0.5, min[V3] > -3.6, [L]min[V3] > -3.6], since it would be impossible to generate [[L]min[V1] > -0.5, [L]min[V3] > -3.6].
See also grow_prune, Itemset.