Merge pull request #213 from Display-Lab/detector_description_1

Detector description 1

Author: zachll

prioritization_algorithms/motivational_potential_model.csv

@@ -0,0 +1,10 @@
+Causal_pathway,Comparison_size,Trend_slope,Measure_achievement_recency,Loss_recency,Message_recency,Message_received_count,Measure_recency
+Better,0.5,--,--,--,-0.1,-0.1,-0.5
+Worse,0.5,--,--,--,-0.1,-0.5,-0.5
+Improving,--,0.8,--,--,-0.1,-0.1,0
+Worsening,--,0.8,--,--,-0.1,-0.5,0
+Achievement,0.5,0.8,-0.5,--,-0.1,-0.1,-0.5
+Loss,0.5,0.8,--,-0.5,-0.1,-0.5,-0.5
+Approach,0.5,0.8,-0.5,--,-0.1,-0.1,0
+Sustain better,0.5,--,--,--,-0.1,-0.1,-0.5
+Sustain worse,0.5,--,--,--,-0.1,-0.5,-0.5

signal_detectors/Comparison_detect.md

@@ -0,0 +1,16 @@
+# Comparison Signal Detector
+## Concept
+The comparison signal detector function compares the performance level of a feedback recipient for a specfic measure against the level of a benchmark, such as the peer performance benchmarks or the goal value for that particular measure. This function evaluates differently for both types of gaps, both positive and negative, relative to the performance level and the list of comparator values that are pre-defined by the pipeline. When the recipient's performance level is above that of a comparator, the comparison _detect method denotes that there exists a positive gap in performance level, which is a kind of motivating information. When this detector is activated, the positive or negative gap motivating information is used to influence the rank of corresponding precision feedback message templates.
+
+## Example
+Below are examples of performance data that leads to the detection of a comparison signal.
+
+|Month|Performance Level|Peer Average|75th Percentile Benchmark|90th Percentile Benchmark|MPOG Goal|
+|-----|-----------------|------------|-------------------------|-------------------------|--|
+|Oct  |       85%| 85| 88| 92|90|
+|Nov  | ***85%***| 85| 88| 92|90|
+|Dec  | ***91%***| 85| 88| 92|90|
+
+- For the month of December, this performance data will generate a positive gap signal relative to the 50th and 75th peer performance percentile benchmarks, as well as a negative gap signal between the performance level and the 90th percentile benchmark. 
+
+## Implementation

signal_detectors/Trend_detect.md

@@ -0,0 +1,19 @@
+# Trend Motivating Information Detector
+## Concept
+The trend motivating information detector function compares the performance level of a feedback recipient for a specfic measure as it changes over time. The trend detector currently evaluates over a three month window, and detects monotonic and non-monotonic performance trend information. The signal detects when the performance level has a positive or negative slope over time, and extracts the magnitude of teh trend as motivating information to be used as a moderator.
+## Example
+Below are examples of performance data that leads to the detection of a trend signal.
+
+|Month|Performance Level|Peer Average|75th Percentile Benchmark|90th Percentile Benchmark|MPOG Goal|
+|-----|-----------------|------------|-------------------------|-------------------------|--|
+|Oct  |       85%| 85| 88| 92|90|
+|Nov  | ***85%***| 85| 88| 92|90|
+|Dec  | ***91%***| 85| 88| 92|90|
+
+- For the month of December, this performance data will generate a positive trend signal. The magnitude of the trend will be evaluated as 3, the formula below denotes how this magnitude is determined:
+     - trend magnitude = (month t0 - month t2)/2
+     - trend magnitude = **(91 - 85)/2 = 3**
+
+## Implementation
+The method operates with the current formula:
+Month t0 performance - Month t2 performance / 2

signal_detectors/readme.md

@@ -1,8 +1,8 @@
-# Motivating information detectors
-Motivating information detectors are signal detection functions that identify motivating performance information in performance data. 
+# Signal detectors
+Signal detectors are functions that identify specific types of motivating performance information in performance data. 
 
 ## Motivating performance information 
-Motivating performance information is the information that healthcare professionals seek when viewing a performance dashboard or feedback report, to interpret their performance data. This including comparisons, trends, achievements, and losses that can guide future efforts to improve or sustain performance. These types of information are defined in the Performance Summary Display Ontology. 
+Motivating performance information is the information that healthcare professionals seek when viewing a performance dashboard or feedback report, to interpret their performance data. This including comparisons, trends, achievements, and losses that can guide future efforts to improve or sustain performance. These types of information are defined in the [Performance Summary Display Ontology](https://bioportal.bioontology.org/ontologies/PSDO). 
 
 ### Comparisons
 1. Positive gap
@@ -11,10 +11,23 @@ Motivating performance information is the information that healthcare profession
 4. Consecutive negative gaps
 
 ### Trends
-1. Improving trends
-2. Worsening trends
+1. Improving trend
+2. Worsening trend
+
 
 ### Performance events 
 1. Achievement
 2. Loss
 
+# Implementation
+A [Precision Feedback Pipeline](https://github.com/Display-Lab/precision-feedback-pipeline) uses several signal detectors in series to identify motivating performance information, according to the following workflow (top-down):
+1) [extract_signals](https://github.com/Display-Lab/precision-feedback-pipeline/blob/main/bitstomach/bitstomach.py)
+- Loops over performance measures, calling each signal detection method
+- Adds signals to a knowledge graph as new instances of motivating information
+2) [comparison _detect](https://github.com/Display-Lab/precision-feedback-pipeline/blob/main/bitstomach/signals/_comparison.py)
+- detects comparison signals in the performance data from a list of pre-defined comparators. Comparisons result from differences between performance levels and the values of the pre-defined comparator level list. This method calculates the simple difference between the comparator and performance level, and returns a list of resources representing each detected signal
+3) [trend _detect](https://github.com/Display-Lab/precision-feedback-pipeline/blob/main/bitstomach/signals/_trend.py)
+- detects trend signals, where trend equates to the performance level rate of change month over month. This method can detect monotonic positive and negative trends over three months. The method records the slope as a moderator PSDO.performance_trend_content
+
+In esteemer, the moderator methods reads motivating information identified by signal detectors from the graph, extracting the values and types of moderators from the motivating information that then affect the score of a message template.
+