update description.

Author: ghar1821

src/metrics/ratio_inconsistent_peaks/config.vsh.yaml

@@ -20,15 +20,33 @@ info:
       description: |
         The metric compares the number of cell type specific marker expression peaks between unintegrated and batch integrated data.
         The number of peaks is calculated using the `scipy.signal.find_peaks` function.
-        The metric is calculated as the absolute difference between the number of peaks in the unintegrated and batch-normalized data.
         The (cell type) marker expression profiles are first smoothed using kernel density estimation (KDE) (`scipy.stats.gaussian_kde`),
-        and then peaks are then identified using the `scipy.signal.find_peaks` function.
+        and then peaks are identified using the `scipy.signal.find_peaks` function.
         For peak calling, the `prominence` parameter is set to 0.1 and the `height` parameter is set to 0.05*max_density.
-        Ratio of inconsistent peaks is defined as number of cases where the number of peaks differ between the two splits in the batch
-        normalized data divided by the total number of cases.
-        Cases where there are different number of peaks between the two splits in the unintegrated data are ignored from the denominator.
-        A lower score indicates better performance, means there are less cases with inconsistent peaks after batch integration.
         
+        Case Definitions:
+        - Case 1: Consistent peaks in both unintegrated AND integrated data (ideal outcome).
+          Example: A marker shows 2 peaks for both splits in unintegrated AND integrated data.
+        - Case 2: Inconsistent peaks in unintegrated data, consistent in integrated data (excluded from metric).
+          Example: A marker shows 1 peaks in unintegrated split 1 but 3 peaks in unintegrated split 2, 
+          and the same for integrated (1 peak in split 1 and 3 peaks in split 2).
+          Excluded from calculation because there are differences in unintegrated that cannot be accounted for.
+        - Case 3: Consistent peaks in unintegrated data but inconsistent in integrated data (problematic - batch integration introduced inconsistency).
+          Example: A marker shows 2 peaks in both unintegrated splits, but after integration shows 2 peaks in split 1 and 1 peak in split 2. 
+          Batch correction broke the consistency. 
+        - Case 4: Inconsistent peaks in both unintegrated AND integrated data (excluded from metric).
+          Example: A marker is inconsistent in unintegrated data (2 and 3 peaks in split 1 and split 2) and 
+          remains inconsistent after integration (1 and 2 peaks in split 1 and split 2). 
+          Excluded from calculation because there are differences in unintegrated that cannot be accounted for.
+        
+        Ratio of inconsistent peaks is defined as the number of Case 3 occurrences divided by the total of Case 1 and Case 3 occurrences.
+        Cases 2 and 4 (where unintegrated data has inconsistent peaks) are excluded from the denominator, but is reported
+        in the final anndata output for diagnostic.
+        A lower score indicates better performance, meaning there are fewer cases with inconsistent peaks after batch integration.
+        
+        For edge cases where methods return only zero values for a given marker/donor/cell type, but is not the 
+        case in the unintegrated data, it is automatically assigned as Case 3.
+      
       references:
         doi: 
           - 10.1038/s41592-019-0686-2