Merge pull request #267 from ZanMervic/scoring_sheet

OWScoringSheet: Documentation

doc/index.rst

@@ -7,6 +7,9 @@ Widgets
 .. toctree::
    :maxdepth: 1
 
+   widgets/scoring-sheet
+   widgets/scoring-sheet-viewer
+
 
 Indices and tables
 ==================

doc/widgets.json

@@ -0,0 +1,29 @@
+[
+    [
+     "Prototypes",
+     [
+      {
+       "text": "Scoring Sheet",
+       "doc": "widgets/scoring-sheet.md",
+       "icon": "../orangecontrib/prototypes/widgets/icons/ScoringSheet.svg",
+       "keywords": [
+        "prototypes",
+        "explain",
+        "model",
+        "scoring sheet"
+       ]
+      },
+      {
+       "text": "Scroing Sheet Viewer",
+       "doc": "widgets/scoring-sheet-viewer.md",
+       "icon": "../orangecontrib/prototypes/widgets/icons/ScoringSheetViewer.svg",
+       "keywords": [
+        "prototypes",
+        "explain",
+        "visualization",
+        "scoring sheet viewer"
+       ]
+      }
+     ]
+    ]
+   ]

doc/widgets/scoring-sheet-viewer.md

@@ -0,0 +1,28 @@
+Scoring Sheet Viewer
+================
+A widget for visualizing the scoring sheet predictions.
+
+**Inputs**
+
+- Classifier: a trained scoring sheet model
+- Data: dataset used to visualize the predictions on different instances
+
+**Outputs**
+
+- Features: features used in the scoring sheet
+
+![](images/scoring-sheet-viewer-widget.png)
+
+**Scoring Sheet Viewer** widget offers a simple and intuitive way of visualizing the predictions of the scoring sheet model. The widget takes as input a trained scoring sheet model and a optional dataset (instance) on which we want to visualize the predictions. The widget presents us with a table that visualizes each feature's contribution to the final score, where a higher score indicates a greater chance for an individual to be classified with the target class. Each feature's contribution can be positive or negative, indicating whether it increases or decreases the risk.
+
+
+Example
+-------
+
+![](images/scoring-sheet-viewer-workflow.png)
+
+In this example, we first sample the data, with a portion used to train the Scoring Sheet model and a part routed to the Table widget. This setup allows us to select instances and observe how the scoring sheet performs with new, unseen data.
+
+Let's analyze and learn to interpret the scoring sheet using the example. It features five decision parameters, with points ranging from -5 to 5. We have set the target class to '1,' indicating the 'presence' of heart disease. Positive-value decision parameters increase the risk of heart disease, while those with negative values reduce it.
+
+Consider a selected instance from the Data Table widget. It has a 'slope peak exc ST' attribute value of 'upsloping', which reduces the heart disease risk by 3 points. However, it also has the 'chest pain' attribute set to 'asymptomatic', increasing the risk by 5 points. This combination results in a total score of 2, corresponding to a 71.6% probability of having heart disease.

doc/widgets/scoring-sheet.md

@@ -0,0 +1,39 @@
+Scoring Sheet
+================
+A classification model for explainable predictions.
+
+**Inputs**
+
+- Data: dataset used to train the model
+- Preprocessor: preprocessing methods
+
+**Outputs**
+
+- Learner: scoring sheet ([fasterrisk](https://github.com/jiachangliu/FasterRisk)) learning algorithm
+- Model: a trained scoring sheet model
+
+**Scoring Sheet** widget offers a machine learning model, which can be easily interpreted using the `Scoring Sheet Viewer` widget. The backbone of the widget is the <a href="https://github.com/jiachangliu/FasterRisk" target="_blank">fasterrisk</a> algorithm, for more information you can read the <a href="https://arxiv.org/abs/2210.05846" target="_blank">paper</a>.
+
+![](images/scoring-sheet-widget.png)
+
+The Scoring Sheet widget has four different parameters which we can tune to suit our needs:
+
+- Number of Attributes After Feature Selection - This widget requires all features to be binary, resulting in a preprocessing pipeline that discretizes continuous features and one-hot encodes categorical ones. This parameter helps to manage (reduce) the potentially large number of resulting features and ensures a faster learning process by selecting only the best ones for model training.
+
+- Maximum Number of Decision Parameters - Limits the number of decision parameters in the model, balancing complexity and explainability. More parameters can increase accuracy but make the model harder to explain.
+
+- Maximum Points per Decision Parameter - Controls the range of points each decision parameter can contribute. A wider range can increase model complexity and accuracy but may reduce explainability.
+
+- Number of Input Features Used - Specifies how many original features (before binarization) the decision parameters can originate from. This is useful for ensuring each parameter originates from a unique feature or when only a subset of features is desired.
+
+
+Example
+-------
+
+![](images/scoring-sheet-workflow.png)
+
+The workflow above shows the most straightforward way of using the Scoring Sheet widget. After training the Scoring Sheet model using our dataset, we input it into the Scoring Sheet Viewer widget, which presents us with a scoring sheet. 
+
+![](images/scoring-sheet-workflow-2.png)
+
+The second way of using the Scoring Sheet widget is to use it as any other classification model. In this case, we can use the Test & Score widget to evaluate the model's performance. In the evaluation results, we can see the model's performance for its predictions.