diff --git a/abl/reasoning/kb.py b/abl/reasoning/kb.py index b1ce152..b8a8d4a 100644 --- a/abl/reasoning/kb.py +++ b/abl/reasoning/kb.py @@ -24,8 +24,8 @@ class KBBase(ABC): list so that each aligns with its corresponding index in the base model: the first with the 0th index, the second with the 1st, and so forth. max_err : float, optional - The upper tolerance limit when comparing the similarity between a candidate's logical - result and the ground truth. This is only applicable when the logical result is of a numerical type. + The upper tolerance limit when comparing the similarity between a candidate's reasoning + result and the ground truth. This is only applicable when the reasoning result is of a numerical type. This is particularly relevant for regression problems where exact matches might not be feasible. Defaults to 1e-10. use_cache : bool, optional @@ -68,7 +68,7 @@ class KBBase(ABC): def logic_forward(self, pseudo_label): """ How to perform (deductive) logical reasoning, i.e. matching each pseudo label to - their logical result. Users are required to provide this. + their reasoning result. Users are required to provide this. Parameters ---------- @@ -86,7 +86,7 @@ class KBBase(ABC): pseudo_label : List[Any] Pseudo label sample (to be revised by abductive reasoning). y : any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. max_revision_num : int The upper limit on the number of revised labels for each sample. require_more_revision : int @@ -102,7 +102,7 @@ class KBBase(ABC): def _check_equal(self, logic_result, y): """ - Check whether the logical result of a candidate is equal to the ground truth + Check whether the reasoning result of a candidate is equal to the ground truth (or, within the maximum error allowed for numerical results). Returns @@ -127,7 +127,7 @@ class KBBase(ABC): pseudo_label : List[Any] Pseudo label sample (to be revised). y : Any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. revision_idx : array-like Indices of where revisions should be made to the pseudo label sample. @@ -172,7 +172,7 @@ class KBBase(ABC): pseudo_label : List[Any] Pseudo label sample (to be revised). y : Any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. max_revision_num : int The upper limit on the number of revisions. require_more_revision : int @@ -219,7 +219,7 @@ class GroundKB(KBBase): """ Knowledge base with a ground KB (GKB). Ground KB is a knowledge base prebuilt upon class initialization, storing all potential candidates along with their respective - logical result. Ground KB can accelerate abductive reasoning in `abduce_candidates`. + reasoning result. Ground KB can accelerate abductive reasoning in `abduce_candidates`. Parameters ---------- @@ -292,7 +292,7 @@ class GroundKB(KBBase): pseudo_label : List[Any] Pseudo label sample (to be revised by abductive reasoning). y : any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. max_revision_num : int The upper limit on the number of revised labels for each sample. require_more_revision : int, optional @@ -320,8 +320,8 @@ class GroundKB(KBBase): def _find_candidate_GKB(self, pseudo_label, y): """ - Retrieve compatible candidates from the prebuilt GKB. For numerical logical results, - return all candidates whose logical results fall within the + Retrieve compatible candidates from the prebuilt GKB. For numerical reasoning results, + return all candidates whose reasoning results fall within the [y - max_err, y + max_err] range. """ if isinstance(y, (int, float)): @@ -397,8 +397,8 @@ class PrologKB(KBBase): def logic_forward(self, pseudo_labels): """ Consult prolog with the query `logic_forward(pseudo_labels, Res).`, and set the - returned `Res` as the logical results. To use this default function, there must be - a Prolog `log_forward` method in the pl file to perform logical. reasoning. + returned `Res` as the reasoning results. To use this default function, there must be + a `logic_forward` method in the pl file to perform reasoning. Otherwise, users would override this function. Parameters @@ -437,7 +437,7 @@ class PrologKB(KBBase): pseudo_label : List[Any] Pseudo label sample (to be revised by abductive reasoning). y : any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. revision_idx : array-like Indices of where revisions should be made to the pseudo label sample. @@ -461,7 +461,7 @@ class PrologKB(KBBase): pseudo_label : List[Any] Pseudo label sample (to be revised). y : Any - Ground truth of the logical result for the sample. + Ground truth of the reasoning result for the sample. revision_idx : array-like Indices of where revisions should be made to the pseudo label sample. diff --git a/docs/Intro/Basics.rst b/docs/Intro/Basics.rst index 86c8d90..93142b6 100644 --- a/docs/Intro/Basics.rst +++ b/docs/Intro/Basics.rst @@ -57,9 +57,9 @@ Use ABL-Package Step by Step In a typical Abductive Learning process, as illustrated below, data inputs are first mapped to pseudo labels through a machine learning model. These pseudo labels then pass through a knowledge base :math:`\mathcal{KB}` -to obtain the logical result by deductive reasoning. During training, +to obtain the reasoning result by deductive reasoning. During training, alongside the aforementioned forward flow (i.e., prediction --> deduction reasoning), -there also exists a reverse flow, which starts from the logical result and +there also exists a reverse flow, which starts from the reasoning result and involves abductive reasoning to generate pseudo labels. Subsequently, these labels are processed to minimize inconsistencies with machine learning, which in turn revise the outcomes of the machine learning model, and then @@ -70,7 +70,7 @@ To implement this process, the following five steps are necessary: 1. Prepare datasets - Prepare the data's input, ground truth for pseudo labels (optional), and ground truth for logical results. + Prepare the data's input, ground truth for pseudo labels (optional), and ground truth for reasoning results. 2. Build the learning part @@ -80,7 +80,7 @@ To implement this process, the following five steps are necessary: 3. Build the reasoning part Build a knowledge base by building a subclass of ``KBBase``, defining how to - map pseudo labels to logical results. + map pseudo labels to reasoning results. Also, instantiate a ``ReasonerBase`` for minimizing of inconsistencies between the knowledge base and pseudo labels. diff --git a/docs/Intro/Quick-Start.rst b/docs/Intro/Quick-Start.rst index b7100ba..3b8d0f4 100644 --- a/docs/Intro/Quick-Start.rst +++ b/docs/Intro/Quick-Start.rst @@ -123,8 +123,11 @@ Read more about `building the learning part `_. Building the Reasoning Part --------------------------- -To build the reasoning part, we first create a class that inherits from ``KBBase`` to define the knowledge base. -We pass the list of pseudo labels to the ``__init__`` function and specify how to deduce logical results in the ``logic_forward`` function. +To build the reasoning part, we first Build a knowledge base by +creating a subclass of ``KBBase``, which defines how to map pseudo +labels to reasoning results. In the subclass, we initialize the +``pseudo_label_list`` parameter and override the ``logic_forward`` +function specifying how to perform (deductive) reasoning. .. code:: python @@ -146,7 +149,10 @@ Out: AddKB is a KB with pseudo_label_list=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], max_err=1e-10, use_cache=True. -Then, we create a reasoner. Aside from the knowledge base, the instantiation of ``ReasonerBase`` also needs to set an extra argument called ``dist_func``, which measures the consistency between the knowledge base and machine learning. +Then, we create a reasoner by defining an instance of class +``ReasonerBase`` and passing the knowledge base as an parameter. +The reasoner can be used to minimize inconsistencies between the +knowledge base and the prediction from the learning part. .. code:: python diff --git a/docs/Intro/Reasoning.rst b/docs/Intro/Reasoning.rst index 7dfd753..a3af967 100644 --- a/docs/Intro/Reasoning.rst +++ b/docs/Intro/Reasoning.rst @@ -13,7 +13,7 @@ Reasoning part In ABL-Package, constructing the reasoning part involves two steps: 1. Build a knowledge base by creating a subclass of ``KBBase``, which - defines how to map pseudo labels to logical results. + defines how to map pseudo labels to reasoning results. 2. Define a reasoner by creating an instance of class ``ReasonerBase`` to minimize inconsistencies between the knowledge base and pseudo labels predicted by the learning part. @@ -32,7 +32,7 @@ and override the ``logic_forward`` function: - **pseudo_label_list** is the list of possible pseudo labels (also, the output of the machine learning model). - **logic_forward** defines how to perform (deductive) reasoning, - i.e. matching each pseudo label to their logical result. + i.e. matching each pseudo label to their reasoning result. After that, other operations, including how to perform abductive reasoning, will be **automatically** set up. @@ -65,9 +65,9 @@ You can also initialize the following parameters when building your knowledge base: - **max_err** (float, optional), specifying the upper tolerance limit - when comparing the similarity between a candidate’s logical result + when comparing the similarity between a candidate’s reasoning result and the ground truth during abductive reasoning. This is only - applicable when the logical result is of a numerical type. This is + applicable when the reasoning result is of a numerical type. This is particularly relevant for regression problems where exact matches might not be feasible. Defaults to 1e-10. See :ref:`an example `. - **use_cache** (bool, optional), indicating whether to use cache for @@ -133,7 +133,7 @@ knowledge base. In this way, the knowledge built will have a Ground KB .. admonition:: What is Ground KB? Ground KB is a knowledge base prebuilt upon class initialization, - storing all potential candidates along with their respective logical + storing all potential candidates along with their respective reasoning result. The key advantage of having a Ground KB is that it may accelerate abductive reasoning. @@ -177,7 +177,7 @@ Perform abductive reasoning in your knowledge base As mentioned in :ref:`What is Abductive Reasoning? `, abductive reasoning enables the inference of candidate pseudo labels as potential -explanations for the logical result. Also, in Abductive Learning where +explanations for the reasoning result. Also, in Abductive Learning where an observation (a pseudo label predicted by the learning part) is available, we aim to let the candidate do not largely revise the previously identified pseudo label. @@ -188,7 +188,7 @@ for conducting abductive reasoning, where the parameters are: - **pseudo_label**, the pseudo label sample to be revised by abductive reasoning, usually generated by the learning part. -- **y**, the ground truth of the logical result for the sample. The +- **y**, the ground truth of the reasoning result for the sample. The returned candidates should be compatible with it. - **max_revision_num**, an int value specifying the upper limit on the number of revised labels for each sample.