Adding explanaotry notes to app and exports

Co-Authored-By: Paula-ZE <209988446+paula-ze@users.noreply.github.com>

Z-Score_Calculator.py

@@ -178,6 +178,26 @@ def main():
             f"Sample size: {res['n']}**."
         )
 
+        # Z-Score Classification Guide
+        with st.expander("📊 Z-Score Classification Guide"):
+            st.markdown("""
+            **How to interpret your Z-Score:**
+            
+            | Z-Score Range | Classification | Percentile Range |
+            |:-------------:|:--------------:|:----------------:|
+            | z < -2.0 | Very Low | < 2.3% |
+            | -2.0 ≤ z < -0.5 | Below Average | 2.3% - 30.9% |
+            | **-0.5 ≤ z < 0.5** | **Average** | **30.9% - 69.1%** |
+            | 0.5 ≤ z < 2.0 | Above Average | 69.1% - 97.7% |
+            | z ≥ 2.0 | Very High | > 97.7% |
+            
+            **Context matters:**
+            - For **steps, sleep duration, and active minutes**: Higher values are generally better ✓
+            - For **heart rate**: Lower resting values are generally better ✓
+            
+            *A z-score of 0 means you are exactly at the population average for your demographic group.*
+            """)
+
         # Detailed statistics table
         st.subheader("Detailed Statistics")
         stats_df = pd.DataFrame(

batch_utils.py

@@ -398,7 +398,45 @@ def generate_pdf_report(patient_info: dict, measurements: dict, z_scores: dict =
         f"({patient_info.get('gender', 'N/A')}), age group, and BMI category."
     )
     elements.append(Paragraph(cohort_text, normal_style))
-    elements.append(Spacer(1, 0.3*inch))
+    elements.append(Spacer(1, 0.2*inch))
+    
+    # Z-Score Classification Guide
+    elements.append(Paragraph("Z-Score Classification Guide", heading_style))
+    
+    classification_data = [
+        ["Z-Score Range", "Classification", "Percentile"],
+        ["z < -2.0", "Very Low", "< 2.3%"],
+        ["-2.0 ≤ z < -0.5", "Below Average", "2.3% - 30.9%"],
+        ["-0.5 ≤ z < 0.5", "Average", "30.9% - 69.1%"],
+        ["0.5 ≤ z < 2.0", "Above Average", "69.1% - 97.7%"],
+        ["z ≥ 2.0", "Very High", "> 97.7%"],
+    ]
+    
+    class_table = Table(classification_data, colWidths=[1.8*inch, 1.5*inch, 1.5*inch])
+    class_table.setStyle(TableStyle([
+        ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#e67e22')),
+        ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+        ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+        ('FONTSIZE', (0, 0), (-1, -1), 9),
+        ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
+        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+        ('GRID', (0, 0), (-1, -1), 0.5, colors.grey),
+        ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
+        ('TOPPADDING', (0, 0), (-1, -1), 6),
+        # Highlight the "Average" row
+        ('BACKGROUND', (0, 3), (-1, 3), colors.HexColor('#fef9e7')),
+    ]))
+    elements.append(class_table)
+    elements.append(Spacer(1, 0.1*inch))
+    
+    context_note = Paragraph(
+        "<b>Context:</b> For steps, sleep, and activity - higher is better. "
+        "For heart rate - lower resting values are better. "
+        "A z-score of 0 = population average for your demographic group.",
+        ParagraphStyle('ContextNote', parent=normal_style, fontSize=8, textColor=colors.HexColor('#555555'))
+    )
+    elements.append(context_note)
+    elements.append(Spacer(1, 0.2*inch))
     
     # Disclaimer
     disclaimer = Paragraph(

pages/1_Batch_Analysis.py

@@ -256,6 +256,27 @@ if uploaded_file is not None and 'df' in dir() and df is not None and normative_
             "Please ensure your columns match the template format."
         )
 
+# Z-Score Classification Guide
+st.markdown("---")
+with st.expander("📊 Z-Score Classification Guide"):
+    st.markdown("""
+    **How to interpret Z-Scores:**
+    
+    | Z-Score Range | Classification | Percentile Range |
+    |:-------------:|:--------------:|:----------------:|
+    | z < -2.0 | Very Low | < 2.3% |
+    | -2.0 ≤ z < -0.5 | Below Average | 2.3% - 30.9% |
+    | **-0.5 ≤ z < 0.5** | **Average** | **30.9% - 69.1%** |
+    | 0.5 ≤ z < 2.0 | Above Average | 69.1% - 97.7% |
+    | z ≥ 2.0 | Very High | > 97.7% |
+    
+    **Context matters:**
+    - For **steps, sleep duration, and active minutes**: Higher values are generally better ✓
+    - For **heart rate**: Lower resting values are generally better ✓
+    
+    *A z-score of 0 means you are exactly at the population average for your demographic group.*
+    """)
+
 # Footer
 st.markdown("---")
 st.markdown(

pages/2_PDF_Report.py

@@ -288,10 +288,31 @@ The generated PDF report includes:
    - Visual gauge charts showing position in distribution
    - Interpretation (Very Low → Average → Very High)
 4. **Reference Population Info** - Details about the comparison cohort
+5. **Classification Guide** - Explanation of z-score interpretation
 
 *All reports include a disclaimer noting educational/research purpose.*
 """)
 
+# Z-Score Classification Guide
+with st.expander("📊 Z-Score Classification Guide"):
+    st.markdown("""
+    **How to interpret Z-Scores:**
+    
+    | Z-Score Range | Classification | Percentile Range |
+    |:-------------:|:--------------:|:----------------:|
+    | z < -2.0 | Very Low | < 2.3% |
+    | -2.0 ≤ z < -0.5 | Below Average | 2.3% - 30.9% |
+    | **-0.5 ≤ z < 0.5** | **Average** | **30.9% - 69.1%** |
+    | 0.5 ≤ z < 2.0 | Above Average | 69.1% - 97.7% |
+    | z ≥ 2.0 | Very High | > 97.7% |
+    
+    **Context matters:**
+    - For **steps, sleep duration, and active minutes**: Higher values are generally better ✓
+    - For **heart rate**: Lower resting values are generally better ✓
+    
+    *A z-score of 0 means you are exactly at the population average for your demographic group.*
+    """)
+
 # Footer
 st.markdown("---")
 st.markdown(