Merge remote-tracking branch 'origin/main' into dev-v0.9.1

Project.toml

@@ -44,6 +44,7 @@ SoleData = "0.9.1"
 SoleLogics = "0.3.0"
 StatsBase = "0.34"
 Suppressor = "0.2"
+ThreadSafeDicts = "0.1.0"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

src/models/base.jl

@@ -146,17 +146,23 @@ function apply(
     map(i_instance->apply(m, d, i_instance; kwargs...), 1:ninstances(d))
 end
 
+# Symbolic models encode a *rule-based thought process*,
+# and provide a form of transparent and interpretable computation.
 """
     issymbolic(::AbstractModel)::Bool
 
 Return whether a model is symbolic or not.
 A model is said to be `symbolic` when its application relies on checking formulas
 of a certain logical language (see [`SoleLogics`](@ref) package) on the instance.
 Symbolic models provide a form of transparent and interpretable modeling,
-as a symbolic model can be synthethised into a set of mutually exclusive logical rules.
-
-Instead, a model is said to be functional when it encodes an algebraic mathematical
-function (e.g., a neural network).
+as a symbolic model can be synthethised into a set of mutually exclusive logical rules
+that can often be translated into natural language.
+
+Examples of purely symbolic models are [`Rule`](@ref)s, [`Branch`](@ref),
+[`DecisionList`](@ref)s and [`DecisionTree`](@ref)s.
+Examples of non-symbolic models are those encoding algebraic mathematical
+functions (e.g., neural networks). Note that [`DecisionForest`](@ref)s are
+not purely symbolic, as they rely on an algebraic aggregation step.
 
 See also
 [`apply`](@ref),

src/models/symbolic-utils.jl

@@ -225,11 +225,6 @@ listimmediaterules(m::MixedSymbolicModel) = listimmediaterules(root(m))
 ############################################################################################
 
 # TODO @Michi esempi
-# TODO
-# The keyword argument `force_syntaxtree`, when set to true, causes the logical antecedents
-# in the returned rules to be represented as `SyntaxTree`s, as opposed to other syntax
-# structure (e.g., `LeftmostConjunctiveForm`).
-
 """
     listrules(
         m::AbstractModel;
@@ -244,6 +239,10 @@ The behavior of any symbolic model can be synthesised and represented as a
 set of mutually exclusive (and jointly exaustive, if the model is closed) rules,
 which can be useful for many purposes.
 
+The keyword argument `force_syntaxtree`, when set to true, causes the logical antecedents
+in the returned rules to be represented as `SyntaxTree`s, as opposed to other syntax
+structure (e.g., `LeftmostConjunctiveForm`).
+
 # Examples
 ```julia-repl
 julia> using SoleLogics