Merge branch 'main' into dev

.cirrus.yml

@@ -1,5 +1,5 @@
 freebsd_instance:
-  image_family: freebsd-13-2
+  image_family: freebsd-14-0
 task:
   name: FreeBSD
   artifacts_cache:

.github/workflows/Documentation.yaml

@@ -0,0 +1,23 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+      - dev
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.9'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+        run: julia --project=docs/ docs/make.jl

Project.toml

@@ -1,7 +1,7 @@
 name = "Sole"
 uuid = "7b3b3b3f-8b15-4a80-a798-b383498bc2cf"
-authors = ["Michele Ghiotti", "Federico Manzella", "Mauro Milella", "Giovanni Pagliarini", "Eduard I. Stan", "Guido Sciavicco"]
-version = "0.5.0"
+authors = ["Michele Ghiotti", "Federico Manzella", "Mauro Milella", "Giovanni Pagliarini", "Edoardo Ponsanesi", "Eduard I. Stan", "Guido Sciavicco"]
+version = "0.6.0"
 
 [deps]
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
@@ -13,9 +13,9 @@ SoleModels = "4249d9c7-3290-4ddd-961c-e1d3ec2467f8"
 
 [compat]
 SoleBase = "0.12"
-SoleData = "0.14"
+SoleData = "0.15"
 SoleLogics = "0.10"
-SoleModels = "0.7"
+SoleModels = "0.8"
 Reexport = "1.2"
 Random = "1"
 julia = "1"

README.md

@@ -35,53 +35,71 @@ These levels of **transparency** (or *interpretability*) are generally not avail
 </a>
 </div>
 
-## Sole.jl
+## The Sole.jl framework
 
-*Sole.jl* is a collection of Julia packages for symbolic learning and reasoning; *Sole.jl* covers **a relatively wide range of functionality** that is of interest for the symbolic community, but it also fills some gaps with a few functionalities for standard machine learning pipelines (e.g., feature selection on multimodal (un)structured data). At the time of writing, the framework comprehends the following packages:
-+ [*SoleLogics.jl*](https://github.com/aclai-lab/SoleLogics.jl) lays the **logical foundations** for symbolic learning. It provides a useful codebase for [*computational logic*](https://en.wikipedia.org/wiki/Computational_logic), which features easy manipulation of:
+*Sole* is a collection of Julia packages for symbolic learning and reasoning.
+Although at an embryonic stage, *Sole.jl* covers a range of functionality that is of interest for the symbolic community, but it also fills some gaps with a few functionalities for standard machine learning pipelines. At the time of writing, the framework comprehends the three core packages:
++ [*SoleLogics.jl*](https://github.com/aclai-lab/SoleLogics.jl) provides the **logical layer** for symbolic learning. It provides a useful codebase for [*computational logic*](https://en.wikipedia.org/wiki/Computational_logic), which features easy manipulation of:
 	+ Propositional and (multi)modal logics (atoms, logical constants, alphabet, grammars, fuzzy algebras);
 	+ [Logical formulas](https://en.wikipedia.org/wiki/Well-formed_formula) (random generation, parsing, minimization);
 	+ [Logical interpretations](https://en.wikipedia.org/wiki/Interpretation_(logic)) (or models, e.g., [Kripke structures](https://en.wikipedia.org/wiki/Kripke_structure_(model_checking)));
 	+ Algorithms for [model checking](https://en.wikipedia.org/wiki/Model_checking) (that is, checking that a formula is satisfied by an interpretation).
-+ [*SoleData.jl*](https://github.com/aclai-lab/SoleData.jl) provides a **data layer** built on top of DataFrames.jl/Tables.jl. Its codebase is machine learning oriented and allows to:
-	+ Instantiate and manipulate [*multimodal*](https://en.wikipedia.org/wiki/Multimodal_learning) datasets for (un)supervised machine learning;
-	+ Deal with [*(un)structured* data](https://en.wikipedia.org/wiki/Unstructured_data) (e.g., graphs, images, time-series, etc.);
-	+ Describe datasets via basic statistical measures;
-	+ Save to/load from *npy/npz* format, as well as a custom CSV-based format (with interesting features such as *lazy loading* of datasets);
-	+ Perform basic data processing operations (e.g., windowing, moving average, etc.).
++ [*SoleData.jl*](https://github.com/aclai-lab/SoleData.jl) provides the **data layer** for representing *logisets*, that is, the logical counterpart to machine learning datasets:
+ 	+ Optimized data structures, useful when learning models from datasets;
+        + Support for [multimodal data](https://en.wikipedia.org/wiki/Multimodal_learning).
++ [*SoleModels.jl*](https://github.com/aclai-lab/SoleModels.jl) defines the building blocks of **symbolic modeling**, featuring:
+	+ Definitions for (logic-agnostic) symbolic models (mainly, decision rules/lists/trees/forests);
+	+ Support for mixed, neuro-symbolic computation.
+
+Additional packages include:
++ [*SoleDecisionTreeInterface.jl*](https://github.com/aclai-lab/SoleDecisionTreeInterface.jl), which enables the use of Sole on decision trees learned via [DecisionTree.jl](https://github.com/JuliaAI/DecisionTree.jl) (e.g., extract and evaluate rules);
++ [*ModalDecisionTrees.jl*](https://github.com/aclai-lab/ModalDecisionTrees.jl) which allows you to learn decision trees based on temporal logics on time-series datasets, and spatial logics on (small) image datasets;
++ [*ModalDecisionLists.jl*](https://github.com/aclai-lab/ModalDecisionLists.jl) which implements a sequential covering algorithm to learn decision lists;
+
+## Want to know more?
+The formal foundations of the framework are given in [giopaglia](https://github.com/giopaglia/)'s PhD thesis:
+[*Modal Symbolic Learning: from theory to practice*, G. Pagliarini (2024)](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=FRo4yrcAAAAJ&citation_for_view=FRo4yrcAAAAJ:LkGwnXOMwfcC)
+
+Additionally, there's a [10-hour PhD course on YouTube](https://www.youtube.com/playlist?list=PLyuPAlvJWIqLvYpGhenzXCA1JMW2HQwBv), as well as [material](https://github.com/aclai-lab/modal-symbolic-learning-course/) for it (including Jupyter Notebooks displaying symbolic AI workflows with Sole).
+
+<!--
 + [*SoleFeatures.jl*](https://github.com/aclai-lab/SoleFeatures.jl) provides tools for filter-based **feature selection** on [*(un)structured* data](https://en.wikipedia.org/wiki/Unstructured_data). At this time, the package provides:
 	+ 3 native feature selection methods, plus a wrapper around python implementations from *scikit-learn* and *scikit-feature*;
 	+ Generalized feature selection methods that also apply to dimensional data (e.g., images or time-series), via a step of window-based flattening;
 	+ Specific methods for time-series feature selection, based on [Catch22.jl](https://github.com/brendanjohnharris/Catch22.jl/);
 	+ An easily extendible codebase, with abstraction layers similar to those of *scikit-learn*.
-+ [*SoleModels.jl*](https://github.com/aclai-lab/SoleModels.jl) defines the building blocks of **symbolic modeling and learning**. It is the core of the framework, and it features:
-	+ Definitions for symbolic models (decision trees/forests, rules, etc.);
-	+ Optimized data structures, useful when learning models from datasets;
-	+ Support for mixed, neuro-symbolic computation.
 + [*SolePostHoc.jl*](https://github.com/aclai-lab/SolePostHoc.jl) provides some tools for **analyzing and post-processing the learned symbolic models**. It features:
 	+ Tools for inspecting and simplifying the models;
 	+ Rule extraction from decision forests;
 	+ Feature importance estimation.
+  (e.g., feature selection on multimodal (un)structured data)
+-->
 
-Altogether, *Sole.jl* makes for a powerful tool built with an eye to **formal correctness**, and is of use for both machine learning practitioners and computational logicians.
+<!-- Altogether, *Sole.jl* makes for a novel tool built with an eye to **formal correctness**, and is of use for both machine learning practitioners and computational logicians. -->
 
+<!-- Link to https://github.com/Julia-XAI/ExplainableAI.jl -->
+
+<!--
 **Q:** Ok, so what symbolic learning methods do you people provide?
-**A:** At the moment, [*ModalDecisionTrees.jl*](https://github.com/aclai-lab/ModalDecisionTrees.jl) is the only package compatible with Sole.jl, and it provides novel decision tree algorithms based on multimodal temporal and spatial logics for time-series and image classification. Checkout the related [talk at JuliaCon22](https://live.juliacon.org/talk/RQP9TG).
+**A:** At the moment, [*ModalDecisionTrees.jl*](https://github.com/aclai-lab/ModalDecisionTrees.jl) is the only package compatible with Sole.jl, and it provides novel decision tree algorithms based on modal temporal and spatial logics for time-series and image classification. Checkout the related [talk at JuliaCon22](https://live.juliacon.org/talk/RQP9TG).
 
 **Q:** Why the name?
 **A:** *Sole* stands for SymbOlic LEarning; it also means "sun" in Italian, a hint to the enlightening power of transparent modeling.
+-->
 
 <!-- ![](Sole%20code%20organization.png "Code organization")
 <p align="center">
   <img src="Sole%20code%20organization.png" alt="Code organization">
 </p>
  -->
 
+<!--
 ## Want to contribute?
 
 Read these first:
 * [Blue Code Style](https://github.com/invenia/BlueStyle);
 * [ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac).
+ -->
 
 ## About