Update README.md

README.md

@@ -1,77 +1,80 @@
----
-license: mit
-base_model: microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract
-tags:
-- text-classification
-- medical
-- cardiac-arrest
-- clinical-nlp
-- bert
-- healthcare
-- pubmedbert
-library_name: transformers
-pipeline_tag: text-classification
-widget:
-- text: "HISTORY OF PRESENT ILLNESS: This is a 67-year-old male with a history of coronary artery disease who presented after out-of-hospital cardiac arrest. The patient was at home when he suddenly collapsed. His wife witnessed the event and called 911. EMS arrived and found the patient in ventricular fibrillation."
-  example_title: "Clear OHCA Case"
-- text: "HISTORY OF PRESENT ILLNESS: This is a 45-year-old female presenting with acute onset chest pain. The patient was at work when she developed sudden onset substernal chest pain, described as pressure-like, 8/10 in intensity. No loss of consciousness. Vital signs stable on arrival."
-  example_title: "Non-OHCA Case"
-metrics:
-- name: F1-Score
-  type: f1
-  value: 0.632
-- name: Sensitivity
-  type: recall
-  value: 1.000
-- name: Specificity
-  type: specificity
-  value: 0.741
-model-index:
-- name: ohca-classifier-v3-trained
-  results:
-  - task:
-      type: text-classification
-      name: Medical Text Classification
-    dataset:
-      type: medical-discharge-notes
-      name: MIMIC-Based OHCA Dataset
-    metrics:
-    - name: F1-Score
-      type: f1
-      value: 0.632
-    - name: Sensitivity
-      type: recall
-      value: 1.000
-    - name: Specificity
-      type: specificity
-      value: 0.741
----
-
-# OHCA Classifier v3.0 - Clinical Ready Model
-
-🏥 **Ready-to-use BERT classifier for detecting Out-of-Hospital Cardiac Arrest (OHCA) in medical discharge notes**
-
-## 🚀 Quick Start (5 Minutes)
-
-**Want to test immediately?** Install and run:
+# OHCA Classifier v3.0 - Trained Model
 
-```bash
-pip install transformers torch pandas
-```
+## Model Description
+
+This is a trained BERT-based classifier for detecting Out-of-Hospital Cardiac Arrest (OHCA) cases in medical discharge notes. The model is fine-tuned from PubMedBERT and achieves high sensitivity for OHCA detection with configurable thresholds for different clinical needs.
+
+## Model Details
+
+- **Model Name**: OHCA Classifier v3.0 - Trained
+- **Base Model**: microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract
+- **Task**: Binary text classification (OHCA vs Non-OHCA)
+- **Language**: English
+- **Domain**: Medical/Clinical text
+- **Model Version**: 3.0
+- **Author**: Mona Moukaddem
+- **Model Size**: 109M parameters
+- **License**: MIT
+
+## Performance Metrics
+
+| Metric | Value | Description |
+|---|---|---|
+| Optimal Threshold | 0.996 | Found via validation set optimization |
+| F1-Score | 0.632 | Harmonic mean of precision and recall |
+| Sensitivity (Recall) | 1.000 | 100% - Catches all OHCA cases at optimal threshold |
+| Specificity | 0.741 | 74.1% - Correctly identifies non-OHCA cases |
+| AUC-ROC | High | Excellent discrimination ability |
+
+## Threshold Selection Guide
+
+**For Clinical Screening (Recommended): 0.90**
+- Good balance of sensitivity and specificity
+- Reduces false positives while maintaining high sensitivity
+- Suitable for most clinical workflows and screening applications
 
-Then copy-paste this working example:
+**For Ultra-Conservative Screening: 0.996**
+- Optimal threshold from validation set optimization
+- Maximizes sensitivity (100%) 
+- May produce more false positives in some populations
+- Use when missing OHCA cases is extremely costly
+
+**For Research/Validation: Variable**
+- Adjust based on your specific requirements
+- Consider your population's OHCA prevalence
+- Validate performance on your own dataset
+
+## Training Data
+
+| Dataset Characteristic | Value |
+|---|---|
+| Total Cases | 330 |
+| OHCA Cases | 59 (17.9%) |
+| Non-OHCA Cases | 271 (82.1%) |
+| Training Split | 264 cases |
+| Validation Split | 66 cases |
+| Data Source | MIMIC-III derived discharge notes |
+
+## Usage
+
+### Quick Start
 
 ```python
 from transformers import AutoTokenizer, AutoModelForSequenceClassification
 import torch
 
-# Load model
+# Load the model
 model_name = "monajm36/ohca-classifier-v3-trained"
 tokenizer = AutoTokenizer.from_pretrained(model_name)
 model = AutoModelForSequenceClassification.from_pretrained(model_name)
 
-def predict_ohca(text, threshold=0.90):  # Using practical 90% threshold
-    inputs = tokenizer(text, truncation=True, padding=True, 
+# Threshold options
+recommended_threshold = 0.90  # Recommended for clinical screening
+optimal_threshold = 0.996     # From validation set optimization
+
+def predict_ohca(text, threshold=0.90):
+    """Predict OHCA from medical text"""
+    inputs = tokenizer(text, truncation=True, padding=True,
                       max_length=512, return_tensors="pt")
     
     with torch.no_grad():
@@ -79,306 +82,250 @@ def predict_ohca(text, threshold=0.90):  # Using practical 90% threshold
         probs = torch.softmax(outputs.logits, dim=-1)
         ohca_prob = probs[0][1].item()
     
-    prediction = "OHCA" if ohca_prob >= threshold else "Non-OHCA"
+    prediction = 1 if ohca_prob >= threshold else 0
     
+    # Clinical priority based on probability
     if ohca_prob >= 0.996:
-        priority = "🔴 Immediate Review"
-    elif ohca_prob >= 0.95:
-        priority = "🔴 High Priority" 
+        priority = "Immediate Review"
     elif ohca_prob >= 0.90:
-        priority = "🟡 Priority Review"
-    elif ohca_prob >= 0.80:
-        priority = "🟠 Consider Review"
+        priority = "Priority Review"  
+    elif ohca_prob >= 0.70:
+        priority = "Consider Review"
     else:
-        priority = "🟢 Routine"
+        priority = "Routine"
+        
+    confidence = "High" if ohca_prob >= 0.90 else "Medium" if ohca_prob >= 0.50 else "Low"
     
     return {
-        "prediction": prediction,
-        "probability": round(ohca_prob, 4),
-        "confidence": f"{ohca_prob*100:.1f}%",
-        "clinical_priority": priority
+        "prediction": "OHCA" if prediction == 1 else "Non-OHCA",
+        "probability": ohca_prob,
+        "confidence": confidence,
+        "clinical_priority": priority,
+        "threshold_used": threshold
     }
 
-# Test with realistic case
-ohca_text = """HISTORY OF PRESENT ILLNESS: This is a 67-year-old male with a history of coronary artery disease who presented after out-of-hospital cardiac arrest. The patient was at home when he suddenly collapsed. His wife witnessed the event and called 911. EMS arrived and found the patient in ventricular fibrillation. CPR was initiated immediately with defibrillation. Return of spontaneous circulation was achieved after 15 minutes."""
-
-result = predict_ohca(ohca_text)
+# Example usage
+text = "Patient presents with cardiac arrest at home, found down by family"
+result = predict_ohca(text)  # Uses recommended 0.90 threshold
 print(f"Prediction: {result['prediction']}")
-print(f"Confidence: {result['confidence']}")  
+print(f"Probability: {result['probability']:.3f}")
 print(f"Clinical Priority: {result['clinical_priority']}")
-# Expected Output: OHCA, ~98% confidence, Priority Review
 ```
 
----
-
-## ⚠️ Critical: Understanding Thresholds
-
-**Important:** The model's training used a 99.6% threshold, but this may be **too conservative for clinical practice**. 
-
-Here's what different thresholds mean:
-
-| Threshold | Use Case | Trade-off |
-|-----------|----------|-----------|
-| **99.6%** | Research, ultra-conservative | May miss obvious OHCA cases |
-| **95%** | High-confidence clinical screening | Good balance, still conservative |
-| **90%** | **Recommended for most clinical use** | Practical screening threshold |
-| **85%** | Sensitive screening | Catches more cases, more false positives |
-
-### Test Different Thresholds
+### Pipeline Usage
 
 ```python
-# Test the same case with different thresholds
-text = "Your discharge note text here..."
-thresholds = [0.996, 0.95, 0.90, 0.85]
-
-for threshold in thresholds:
-    result = predict_ohca(text, threshold)
-    print(f"Threshold {threshold*100:.1f}%: {result['prediction']} ({result['confidence']})")
+from transformers import pipeline
+
+# Create classification pipeline
+classifier = pipeline("text-classification", model="monajm36/ohca-classifier-v3-trained")
+
+# Classify medical text
+text = "Patient presents with cardiac arrest at home"
+result = classifier(text)
+print(result)
+# Output: [{'label': 'LABEL_1', 'score': 0.998}]
+# LABEL_0 = Non-OHCA, LABEL_1 = OHCA
+
+# For clinical use, apply appropriate threshold:
+probability = result[0]['score'] if result[0]['label'] == 'LABEL_1' else 1 - result[0]['score']
+is_ohca_90 = probability >= 0.90    # Recommended threshold
+is_ohca_996 = probability >= 0.996  # Optimal threshold
 ```
 
----
-
-## 📊 Analyze Your Data
-
-### Single CSV File Analysis
+### Batch Processing
 
 ```python
 import pandas as pd
 
-def analyze_discharge_notes(csv_file, text_column='clean_text', threshold=0.90):
-    """Analyze your discharge notes - works with any CSV format"""
-    
-    # Load data
-    df = pd.read_csv(csv_file)
-    print(f"📋 Loaded {len(df)} records")
-    
-    # Analyze each note
+def process_medical_notes(df, text_column='clean_text', threshold=0.90):
+    """Process multiple medical notes"""
     results = []
-    for idx, text in enumerate(df[text_column]):
-        if idx % 100 == 0:  # Progress update
-            print(f"   Processed {idx}/{len(df)}...")
-            
-        result = predict_ohca(str(text), threshold)
+    
+    for text in df[text_column]:
+        result = predict_ohca(text, threshold=threshold)
         results.append(result)
     
-    # Add results to your data
+    # Add results to dataframe
     df['ohca_prediction'] = [r['prediction'] for r in results]
-    df['ohca_probability'] = [r['probability'] for r in results] 
-    df['ohca_confidence'] = [r['confidence'] for r in results]
+    df['ohca_probability'] = [r['probability'] for r in results]
     df['clinical_priority'] = [r['clinical_priority'] for r in results]
     
-    # Save results with timestamp
-    from datetime import datetime
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_file = f"ohca_analysis_{timestamp}.csv"
-    df.to_csv(output_file, index=False)
-    
-    # Clinical summary
-    total = len(df)
-    ohca_cases = len(df[df['ohca_prediction'] == 'OHCA'])
-    immediate = len(df[df['clinical_priority'].str.contains('Immediate')])
-    high_priority = len(df[df['clinical_priority'].str.contains('High Priority|Priority Review')])
-    
-    print(f"\n🏥 CLINICAL SUMMARY:")
-    print(f"   Total cases analyzed: {total:,}")
-    print(f"   Predicted OHCA: {ohca_cases:,} ({ohca_cases/total*100:.1f}%)")
-    print(f"   🔴 Immediate review needed: {immediate:,}")
-    print(f"   🟡 High priority cases: {high_priority:,}")
-    print(f"   📁 Results saved: {output_file}")
-    
     return df
 
-# Usage
-results = analyze_discharge_notes('your_discharge_notes.csv', threshold=0.90)
-
-# Filter high-priority cases
-high_priority = results[results['clinical_priority'].str.contains('Immediate|High Priority')]
-high_priority.to_csv('high_priority_ohca_cases.csv', index=False)
+# Example with DataFrame
+medical_notes = pd.DataFrame({
+    'patient_id': [1, 2, 3],
+    'clean_text': [
+        "Patient found in cardiac arrest at home by spouse",
+        "Patient complains of chest pain, vital signs stable",
+        "Witnessed cardiac arrest in emergency department"
+    ]
+})
+
+results = process_medical_notes(medical_notes)
+print(results[['patient_id', 'ohca_prediction', 'ohca_probability']])
 ```
 
-### Your Data Format
+### Compare Different Thresholds
 
-The CSV should have at minimum:
-- **Text column**: Discharge note content (any column name works)
-- **ID column**: Case identifier (optional but recommended)
+```python
+def compare_thresholds(text):
+    """Compare predictions at different thresholds"""
+    thresholds = [0.50, 0.70, 0.90, 0.996]
+    
+    for threshold in thresholds:
+        result = predict_ohca(text, threshold=threshold)
+        print(f"Threshold {threshold}: {result['prediction']} "
+              f"(p={result['probability']:.3f}, priority={result['clinical_priority']})")
 
-Example:
-```csv
-case_id,discharge_text
-12345,"HISTORY OF PRESENT ILLNESS: 67-year-old male with cardiac arrest at home..."
-12346,"HISTORY OF PRESENT ILLNESS: 45-year-old female with chest pain..."
+# Example comparison
+text = "Patient found down at home, family performed CPR"
+compare_thresholds(text)
 ```
 
----
+## Clinical Decision Support
 
-## 🔬 Model Details
+The model provides configurable sensitivity for OHCA detection, making it suitable for clinical screening where different thresholds may be appropriate based on clinical context and cost of missed cases.
 
-### Architecture
-- **Base Model**: PubMedBERT (specialized for medical text)
-- **Task**: Binary classification (OHCA vs Non-OHCA)
-- **Parameters**: 109M
-- **Max Length**: 512 tokens
-- **Language**: English medical text
+### Clinical Workflow Integration
 
-### Training Data
-- **Total Cases**: 330 medical discharge notes
-- **OHCA Cases**: 59 (17.9%)
-- **Data Source**: MIMIC-III derived
-- **Validation**: Patient-level splits (prevents data leakage)
+| Probability Range | Clinical Priority | Recommended Action |
+|---|---|---|
+| ≥ 0.996 | 🔴 Immediate Review | Very high confidence - Urgent review required |
+| 0.90 - 0.995 | 🟡 Priority Review | High confidence - Clinical team review |
+| 0.70 - 0.89 | 🟠 Consider Review | Moderate confidence - Consider for review |
+| < 0.70 | 🟢 Routine | Low probability - Standard processing |
 
-### Performance (at 99.6% threshold)
-| Metric | Value | Clinical Meaning |
-|--------|--------|------------------|
-| **Sensitivity** | 100% | Catches ALL true OHCA cases |
-| **Specificity** | 74.1% | Correctly identifies non-OHCA cases |
-| **F1-Score** | 0.632 | Balanced precision and recall |
+### Threshold Selection for Clinical Use
 
-**Note**: These metrics are at the ultra-conservative 99.6% threshold. At 90% threshold, you'll have different (likely more practical) performance characteristics.
+**Use 0.90 threshold when:**
+- Screening large volumes of discharge notes
+- Balancing sensitivity with manageable false positive rates
+- Implementing in routine clinical workflows
 
----
+**Use 0.996 threshold when:**
+- Ultra-high sensitivity is required
+- Cost of missing OHCA cases is extremely high
+- You have resources to review more false positives
 
-## 🏥 Clinical Workflow Integration
+## Quality Assurance
 
-### Recommended Clinical Process
+- **High Sensitivity**: Configurable thresholds ensure no OHCA cases are missed
+- **Optimal Threshold**: 0.996 maximizes sensitivity on validation data
+- **Clinical Threshold**: 0.90 provides practical balance for screening
+- **Patient-Level Training**: Prevents data leakage and overfitting
+- **Clinical Validation**: Designed for real-world medical text processing
 
-1. **Batch Analysis**: Run model on all discharge notes
-2. **Priority Triage**: 
-   - 🔴 **Immediate Review** (≥99.6%): Urgent medical review
-   - 🔴 **High Priority** (≥95%): Clinical team review within 24h
-   - 🟡 **Priority Review** (≥90%): Review within 48h
-   - 🟠 **Consider Review** (≥80%): Weekly review process
-   - 🟢 **Routine** (<80%): Standard processing
+## Model Architecture
 
-3. **Quality Assurance**: Sample manual review to validate model performance on your specific data
+```
+PubMedBERT (microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract)
+├── 12 Transformer layers
+├── 768 hidden dimensions  
+├── 12 attention heads
+├── 109M parameters
+└── Classification head (2 classes: OHCA vs Non-OHCA)
+```
 
-### Large Dataset Processing
+## Training Details
 
-```python
-def process_large_dataset(csv_file, chunk_size=1000):
-    """Process very large datasets in chunks"""
-    import pandas as pd
-    
-    # Process in chunks to manage memory
-    chunk_results = []
-    
-    for chunk_num, chunk in enumerate(pd.read_csv(csv_file, chunksize=chunk_size)):
-        print(f"Processing chunk {chunk_num + 1}...")
-        
-        results = []
-        for text in chunk['clean_text']:  # Adjust column name
-            result = predict_ohca(text)
-            results.append(result)
-        
-        chunk['ohca_prediction'] = [r['prediction'] for r in results]
-        chunk['ohca_probability'] = [r['probability'] for r in results]
-        chunk['clinical_priority'] = [r['clinical_priority'] for r in results]
-        
-        chunk_results.append(chunk)
-    
-    # Combine all chunks
-    final_results = pd.concat(chunk_results, ignore_index=True)
-    final_results.to_csv('large_dataset_results.csv', index=False)
-    
-    return final_results
-```
+| Training Parameter | Value |
+|---|---|
+| Framework | PyTorch + Transformers |
+| Optimizer | AdamW |
+| Learning Rate | Default (with linear scheduling) |
+| Epochs | 3 |
+| Batch Size | 8 (with gradient accumulation) |
+| Max Sequence Length | 512 tokens |
+| Class Balancing | Weighted loss + minority oversampling |
+| Validation Strategy | Patient-level splits (prevents data leakage) |
+| Hardware | CPU training |
+
+## Evaluation Strategy
+
+- **Patient-Level Data Splits**: Ensures all notes from the same patient stay in one split
+- **Optimal Threshold Finding**: Uses validation set to find best decision threshold
+- **Independent Test Set**: Unbiased evaluation on held-out data
+- **Clinical Metrics**: Focus on sensitivity for medical screening applications
+
+## Limitations and Considerations
 
----
+### Limitations
 
-## 🚨 Limitations & Important Considerations
+- Trained on specific medical text format (discharge notes)
+- May not generalize to different hospital systems without fine-tuning
+- Performance may vary with different patient populations
+- Designed specifically for English medical text
+- Limited to text-based OHCA detection (no multimodal inputs)
 
-### Clinical Limitations
-- **Intended for screening**: Assists, does not replace clinical judgment
-- **Text-only**: Based solely on discharge note text
-- **English medical text**: Designed for US healthcare documentation
-- **Hospital variation**: May need validation on your specific system
+### Ethical Considerations
 
-### Ethical Use
-- **Human oversight required**: All predictions should be clinically reviewed
-- **Bias monitoring**: Evaluate performance across patient demographics
-- **HIPAA compliance**: Ensure proper data handling in your environment
-- **Documentation**: Maintain audit trail of model-assisted decisions
+- **Clinical Use**: This model is intended to assist, not replace, clinical judgment
+- **Bias Monitoring**: Regular evaluation across different patient demographics recommended
+- **Human Oversight**: All high-probability predictions should be reviewed by medical professionals
+- **Privacy**: Ensure compliance with healthcare data regulations (HIPAA, etc.)
 
 ### Performance Variations
-Model accuracy may vary based on:
-- Documentation styles and quality
-- Patient populations and demographics  
-- Types of cardiac arrest presentations
-- Clinical terminology variations
 
----
+Model performance may vary across different:
+- Hospital systems and documentation styles
+- Patient demographics and populations
+- Types of cardiac arrest presentations
+- Clinical documentation quality and completeness
 
-## 📚 Related Resources
+## Related Work
 
-- **Source Code**: [GitHub - OHCA Classifier v3.0](https://github.com/monajm36/ohca-classifier-3.0)
-- **Training Pipeline**: Full methodology for custom model development
-- **Research Paper**: Enhanced methodology with patient-level splits
-- **Community**: Issues and discussions on GitHub
+This model is based on the OHCA Classifier v3.0 methodology with significant improvements over previous versions:
 
-## 🏆 Advanced Features
+- **Enhanced Methodology**: Patient-level splits, optimal threshold finding
+- **Source Code**: Available at [monajm36/ohca-classifier-3.0](https://github.com/monajm36/ohca-classifier-3.0)
+- **Training Pipeline**: Complete v3.0 training workflow for custom model development
+- **Research Foundation**: Built on established medical NLP and machine learning best practices
 
-### Custom Threshold Optimization
+## Installation and Dependencies
 
-```python
-def find_optimal_threshold(labeled_data_csv):
-    """Find best threshold for your specific dataset"""
-    import pandas as pd
-    from sklearn.metrics import classification_report
-    
-    # Load your labeled validation data
-    df = pd.read_csv(labeled_data_csv)  # Should have 'text' and 'true_label' columns
-    
-    # Test different thresholds
-    thresholds = [0.99, 0.95, 0.90, 0.85, 0.80, 0.75]
-    best_threshold = 0.90
-    best_f1 = 0
-    
-    for threshold in thresholds:
-        predictions = []
-        for text in df['text']:
-            result = predict_ohca(text, threshold)
-            pred = 1 if result['prediction'] == 'OHCA' else 0
-            predictions.append(pred)
-        
-        # Calculate metrics
-        report = classification_report(df['true_label'], predictions, output_dict=True)
-        f1 = report['1']['f1-score']  # F1 for OHCA class
-        
-        print(f"Threshold {threshold}: F1 = {f1:.3f}")
-        
-        if f1 > best_f1:
-            best_f1 = f1
-            best_threshold = threshold
-    
-    print(f"\nRecommended threshold for your data: {best_threshold}")
-    return best_threshold
+```bash
+pip install transformers torch pandas numpy
 ```
 
----
+**Minimum Requirements:**
+- Python 3.8+
+- PyTorch 1.9+
+- Transformers 4.20+
+- 4GB RAM for inference
+- GPU optional (model works on CPU)
 
-## 📞 Support & Citation
+## Citation
 
-### Getting Help
-- **Issues**: Report problems on [GitHub](https://github.com/monajm36/ohca-classifier-3.0/issues)
-- **Questions**: Use GitHub discussions for clinical workflow questions
-- **Updates**: Watch the repository for model improvements
-
-### Citation
+If you use this model in your research or clinical work, please cite:
 
 ```bibtex
 @software{ohca_classifier_v3_trained,
-  title={OHCA Classifier v3.0: Clinical-Ready BERT Model for Cardiac Arrest Detection},
+  title={OHCA Classifier v3.0: Trained BERT Model for Cardiac Arrest Detection in Medical Text},
   author={Mona Moukaddem},
   year={2025},
   url={https://huggingface.co/monajm36/ohca-classifier-v3-trained},
-  note={Production-ready classifier with flexible thresholds for clinical deployment}
+  note={High-sensitivity BERT classifier for out-of-hospital cardiac arrest detection in discharge notes}
 }
 ```
 
-### License
-MIT License - Free for clinical and research use
+## License
+
+This model is released under the MIT License. See LICENSE file for details.
+
+## Contact and Support
+
+- **Repository**: [GitHub - OHCA Classifier v3.0](https://github.com/monajm36/ohca-classifier-3.0)
+- **Issues**: Please report issues on the GitHub repository
+- **Model Card**: This model card follows the framework proposed by Mitchell et al. (2019)
 
----
+## Acknowledgments
 
-**🏥 Ready to get started? Copy the Quick Start code above and test it on your data!**
+- **Base Model**: Microsoft Research for PubMedBERT
+- **Dataset**: MIMIC-III for training data foundation
+- **Framework**: Hugging Face Transformers library
+- **Medical Domain**: Clinical expertise in cardiac arrest detection
+- **Methodology**: Data science community for best practices in medical ML
 
-*This model is designed for clinical decision support. Always validate performance on your specific data and maintain appropriate clinical oversight.*
+This model is intended for research and clinical decision support. Always consult with medical professionals for patient care decisions.