Metadata-Version: 2.1
Name: ERTool
Version: 0.1.9
Summary: A Python package for simple and efficient implementation of Evidential Reasoning (ER) methods.
Home-page: UNKNOWN
Author: Tongyue Shi
Author-email: tyshipku@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: matplotlib

# ERTool

<kbd>***ERTool***</kbd> is a Python package designed for simple and efficient implementation of Evidential Reasoning (ER) methods. It aims to provide an intuitive and flexible approach for integrating ER processes, particularly suitable for data analysis and decision support systems.

## Features

- Easy-to-use implementation of Evidential Reasoning.
- Efficient in handling complex ER tasks.
- Flexible interface suitable for various application scenarios.

## Installation

You can install <kbd>***ERTool***</kbd> directly from PyPI using pip:

```
pip install ertool
```

## Using Instruction

### dempster_shafer
```python
ertool.er.dempster_shafer(DBF, numOfEvidence, numOfProposition) -> B
```

<kbd>dempster_shafer()</kbd> can implement the original Dempster-Shafer evidence theory.

#### Input Variables
- ***DBF***: A two-dimensional numpy array of floats. It stands for "Degrees of Belief" and is one of the main inputs to the algorithm, used to represent the initial belief degrees for each category or proposition.
- ***numOfEvidence***: An integer. It indicates the number of evidence nodes. In the DBF array, this typically corresponds to the number of rows.
- ***numOfProposition***: An integer. It indicates the number of categories or propositions. In the DBF array, this typically corresponds to the number of columns.

#### Output Values
- ***B Array***: Upon completion of the algorithm, the B array is the final calculation result. It reflects the degrees of belief that have been weighted and normalized.
- ***False (Boolean)***: It returns B Array if the algorithm successfully executes and completes all computations. If any error is encountered during execution (e.g., division by zero), it returns False.


### er_algorithm

```python
ertool.er.er_algorithm(W, DBF, numOfEvidence, numOfProposition) -> B
```
<kbd>er_algorithm()</kbd> can implement the Evidential Reasoning (ER) algorithm.

#### Input Variables
- ***W***: A one-dimensional numpy array of floats. It represents the weights of each child node. These weights are used in the algorithm to adjust the influence of each child node.
- ***DBF***: A two-dimensional numpy array of floats. It stands for "Degrees of Belief" and is one of the main inputs to the algorithm, used to represent the initial belief degrees for each category or proposition.
- ***numOfEvidence***: An integer. It indicates the number of evidence nodes. In the DBF array, this typically corresponds to the number of rows.
- ***numOfProposition***: An integer. It indicates the number of categories or propositions. In the DBF array, this typically corresponds to the number of columns.

#### Output Values
- ***B Array***: Upon completion of the algorithm, the B array is the final calculation result. It reflects the degrees of belief that have been weighted and normalized.
- ***False (Boolean)***: It returns B Array if the algorithm successfully executes and completes all computations. If any error is encountered during execution (e.g., division by zero), it returns False.

### show_er_result

```python
ertool.er.show_er_result(B, P = None)
```
<kbd>er_algorithm()</kbd> can visualize the rusult of evidential reasoning algorithm.

#### Input Variables
- ***B***: The ER rusult of belief degree.
- ***P***: The name array of propositions.


## Quick Start
Here is a basic usage example of <kbd>***ERTool***</kbd>.

Consider a medical scenario. 
There are three medical experts (weights 10, 8, and 5). For one patient, the three experts rated the different likelihood of the diagnosis of cold, common pneumonia, COVID-19, and uncertain. As shown in the table.

| Experts & Diseases | Expert 1 | Expert 2 | Expert 3 |
| :---:        |    :----:   |  :---: |  :---: | 
| Cold | 90% | 0 | 0 |
| Common Pneumonia |0 | 90% | 0|
| COVID-19 | 0 | 0 | 90% |
| Uncertain | 10% | 10% | 10% |

In this case, the ***numOfEvidence*** is 3 (the number of experts) and the ***numOfProposition*** is 4 (cold, common pneumonia, COVID-19, and uncertain).

The ***W*** array is the weights array of every expert and the <kbd>***ERTool***</kbd> package can normalize them automatically.

We can write the code using the <kbd>***ERTool***</kbd> package:

```python
import ertool
import numpy as np

W = np.array([10,8,5])
DBF = np.array([[0.9, 0, 0, 0.1], 
                [0, 0.9, 0, 0.1], 
                [0, 0, 0.9, 0.1]])

# List or numpy array are both OK.
# W = [10,8,5]
# DBF = [[0.9, 0, 0, 0.1], 
#        [0, 0.9, 0, 0.1], 
#        [0, 0, 0.9, 0.1]]

numOfEvidence = 3
numOfProposition = 4
B = ertool.er.er_algorithm(W, DBF, numOfEvidence, numOfProposition)
print("The result:", B)

P = ['Cold', 'Common Pneumonia', 'COVID-19', 'Uncertain']
ertool.er.show_er_result(B, P)
```
With the code, we can calculate the probability that the patient will be diagnosed with each disease using evidential reasoning.

```
B: [0.43591353 0.30223338 0.15741322 0.10443986 0.]
```
![Output](/readme_img/output.png "Rusult of ER Algorithm")
According to the result, we can know that combining the opinions of the three experts, the probability of the patient being diagnosed with cold, common pneumonia, COVID-19 and uncertain are 0.43591353, 0.30223338, 0.15741322 and 0.10443986. The global ignorance is the last value of B, and it is zero in this example.


## Contributing
Contributions to <kbd>***ERTool***</kbd> are welcome. Please contact us for how to contribute to the project.

## Contact
This project is supported by the **[National Institute of Health Data Science](https://www.nihds.pku.edu.cn/en/), [Peking University](https://english.pku.edu.cn/)**. For any questions or suggestions, please contact us at *tyshipku@gmail.com*. 

