From 616ed95eb2eb9d3d331e2b6b25bc5e497f7ef74d Mon Sep 17 00:00:00 2001 From: troyyyyy Date: Wed, 29 Nov 2023 10:22:56 +0800 Subject: [PATCH] [ENH] add docs: ABL overview intro --- docs/Brief-Introduction/Components.rst | 2 +- docs/Overview/Abductive Learning.rst | 24 +++++++++++++++++++++++- docs/Overview/Introduction.rst | 12 ------------ docs/README.rst | 10 ++++++---- docs/index.rst | 2 +- 5 files changed, 31 insertions(+), 19 deletions(-) delete mode 100644 docs/Overview/Introduction.rst diff --git a/docs/Brief-Introduction/Components.rst b/docs/Brief-Introduction/Components.rst index 5f29e15..3f08245 100644 --- a/docs/Brief-Introduction/Components.rst +++ b/docs/Brief-Introduction/Components.rst @@ -1,4 +1,4 @@ -ABL-Package Components +Components ================== .. contents:: Table of Contents diff --git a/docs/Overview/Abductive Learning.rst b/docs/Overview/Abductive Learning.rst index e11941a..72cd629 100644 --- a/docs/Overview/Abductive Learning.rst +++ b/docs/Overview/Abductive Learning.rst @@ -1,5 +1,27 @@ Abductive Learning ================== -.. contents:: Table of Contents +Traditional supervised machine learning, e.g. classification, is predominantly data-driven. Here, a set of training examples \left\{\left(x_1, y_1\right), \ldots,\left(x_m, y_m\right)\right\} is given, where x_i \in \mathcal{X} is the i-th training instance, y_i \in \mathcal{Y} is the corresponding ground-truth label. These data are then used to train a classifier model f: \mathcal{X} \mapsto \mathcal{Y} to accurately predict the unseen data. + +（可能加一张图，比如左边是ML，右边是ML+KB） + +In Abductive Learning (ABL), we assume that, in addition to data as examples, there is also a knowledge base \mathcal{KB} containing domain knowledge at our disposal. We aim for the classifier f: \mathcal{X} \mapsto \mathcal{Y} to make correct predictions on unseen data, and meanwhile, the logical facts grounded by \left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\} should be compatible with \mathcal{KB}. + +The process of ABL is as follows: + +1. Upon receiving data inputs \left\{x_1,\dots,x_m\right\}, pseudo-labels \left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\} are obtained, predicted by a data-driven classifier model. +2. These pseudo-labels are then converted into logical facts \mathcal{O} that are acceptable for logical reasoning. +3. Conduct joint reasoning with \mathcal{KB} to find any inconsistencies. +4. If found, the logical facts contributing to minimal inconsistency can be identified and then modified through abductive reasoning, returning modified logical facts \Delta(\mathcal{O}) compatible with \mathcal{KB}. +5. These modified logical facts are converted back to the form of pseudo-labels, and used for further learning of the classifier. +6. As a result, the classifier is updated and replaces the previous one in the next iteration. + +This process is repeated until the classifier is no longer updated, or the logical facts \mathcal{O} are compatible with the knowledge base. + +The following figure illustrates this process: + +一张图 + +We can observe that in the above figure, the left half involves machine learning, while the right half involves logical reasoning. Thus, the entire abductive learning process is a continuous cycle of machine learning and logical reasoning. This effectively form a dual-driven (data & knowledge driven) learning system, integrating and balancing the use of machine learning and logical reasoning in a unified model. + diff --git a/docs/Overview/Introduction.rst b/docs/Overview/Introduction.rst deleted file mode 100644 index 09cea8c..0000000 --- a/docs/Overview/Introduction.rst +++ /dev/null @@ -1,12 +0,0 @@ -A Brief Introduction to ABL-Package -================== - -.. contents:: Table of Contents - -ABL-Package Components ----------------------------------------- - - - -Use ABL-Package step by step ------------------------------- \ No newline at end of file diff --git a/docs/README.rst b/docs/README.rst index a7adb92..8d5f804 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -1,16 +1,18 @@ ABL-Package -^^^^^^ +=========== -ABL(Abductive Learning) is ... +ABL-Package is an open source library for Abductive Learning that supports building a model leveraging information from both data and (logical) domain knowledge. Using ABL-Package, users may form a dual-driven (data & knowledge driven) learning system, integrating and balancing the use of machine learning and logical reasoning in a unified model. + +插一张图片 Installation -------------- +------------ ABL is distributed on PyPI and can be installed with ``pip``: .. code:: console - $ pip install ABL + $ pip install abl Alternatively, to install ABL by source code, download this project and sequentially run following commands in your terminal/command line. diff --git a/docs/index.rst b/docs/index.rst index bbb3c21..a96258a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ .. toctree:: :maxdepth: 2 - :caption: A Brief Introduction to ABL-Package + :caption: A Brief Introduction Brief-Introduction/Components Brief-Introduction/Usage