Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,239 @@
+---
+license: apache-2.0
+language:
+- zh
+tags:
+- medical
+- perioperative
+- complications
+- lora
+- adapter
+- clinical-ai
+datasets:
+- perioperative-complications
+pipeline_tag: text-classification
+---
+
+# PeriComp: Perioperative Complication Detection LoRA Adaptors
+
+![PeriComp Performance](../figure6b.png)
+*Figure: Performance comparison of fine-tuned models across different sizes*
+
+## 🩺 Model Overview
+
+**PeriComp** is a collection of specialized LoRA (Low-Rank Adaptation) adaptors designed for **perioperative complication detection** from clinical narratives. These adaptors enhance smaller open-source language models to achieve expert-level performance in identifying and grading 22 distinct perioperative complications based on European Perioperative Clinical Outcome (EPCO) definitions.
+
+### 🎯 Key Features
+
+- **Expert-level Performance**: Matches or exceeds human clinician accuracy
+- **Multi-scale Detection**: Simultaneous identification and severity grading (mild/moderate/severe)
+- **Comprehensive Coverage**: 22 distinct perioperative complications
+- **Resource Efficient**: Optimized for deployment on standard clinical infrastructure
+- **Privacy Preserving**: Fully deployable on-premises without data transmission
+
+## 📊 Model Collection
+
+This collection includes five optimized LoRA adaptors:
+
+| Model | Base Model | Parameters | F1 Score | Use Case |
+|-------|------------|------------|----------|----------|
+| **PeriComp-4B** | Qwen3-4B | 4B | 0.55 | Resource-constrained environments |
+| **PeriComp-8B** | Qwen3-8B | 8B | 0.61 | Balanced performance/efficiency |
+| **PeriComp-14B** | Qwen3-14B | 14B | 0.65 | High-performance deployment |
+| **PeriComp-32B** | Qwen3-32B | 32B | 0.68 | Maximum accuracy requirements |
+| **PeriComp-QwQ-32B** | QwQ-32B | 32B | 0.70 | Reasoning-enhanced performance |
+
+## 🔬 Research Background
+
+Perioperative complications affect millions of patients globally, with traditional manual detection suffering from:
+- **27% under-reporting rate** in clinical registries
+- **High variability** in expert performance across institutions
+- **Cognitive load limitations** with complex documentation
+
+Our research demonstrates that targeted task decomposition combined with LoRA fine-tuning enables smaller models to achieve expert-level diagnostic capabilities while maintaining practical deployability.
+
+![Strict Performance Evaluation](../figure7.png)
+*Figure: Strict performance evaluation requiring exact complication type and severity matching*
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install transformers peft torch
+```
+
+### Basic Usage
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+
+# Load base model and tokenizer
+model_name = "Qwen/Qwen3-8B"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+base_model = AutoModelForCausalLM.from_pretrained(model_name)
+
+# Load PeriComp adaptor
+adaptor_name = "your-username/Qwen3-8B-PeriComp"
+model = PeftModel.from_pretrained(base_model, adaptor_name)
+
+# Prepare clinical input
+clinical_text = '''
+Patient Demographics: 65-year-old male
+Procedure: Laparoscopic cholecystectomy
+Postoperative Course: POD#2 - Patient reports abdominal pain, 
+fever 38.5°C, elevated WBC count 15,000/μL...
+'''
+
+# Generate complication assessment
+inputs = tokenizer(clinical_text, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=512)
+result = tokenizer.decode(outputs[0], skip_special_tokens=True)
+```
+
+### Targeted Strategy Usage
+
+For optimal performance with smaller models, use our targeted strategy:
+
+```python
+# Define complications to assess
+complications = [
+    "acute_kidney_injury",
+    "surgical_site_infection", 
+    "paralytic_ileus",
+    # ... other complications
+]
+
+# Assess each complication individually
+results = {}
+for complication in complications:
+    prompt = f"Assess for {complication}: {clinical_text}"
+    # ... inference code
+    results[complication] = assessment
+```
+
+## 📈 Performance Metrics
+
+### Validation Results (Micro-averaged F1 Scores)
+
+- **Center 1 (Primary)**: Complex tertiary care cases
+- **Center 2 (External)**: Community hospital validation
+
+| Model | Center 1 F1 | Center 2 F1 | Human Expert F1 |
+|-------|-------------|-------------|-----------------|
+| PeriComp-4B | 0.55 | 0.52 | 0.526 |
+| PeriComp-8B | 0.61 | 0.58 | 0.526 |
+| PeriComp-14B | 0.65 | 0.62 | 0.526 |
+| PeriComp-32B | 0.68 | 0.65 | 0.526 |
+| PeriComp-QwQ-32B | 0.70 | 0.67 | 0.526 |
+
+### Key Advantages
+
+✅ **Consistent Performance**: No degradation with document complexity  
+✅ **24/7 Availability**: Continuous monitoring capability  
+✅ **Standardized Assessment**: Eliminates inter-observer variability  
+✅ **Comprehensive Detection**: All 22 EPCO-defined complications  
+✅ **Privacy Compliant**: On-premises deployment option  
+
+## 🔧 Technical Details
+
+### Training Methodology
+
+- **Base Architecture**: Qwen3 series and QwQ-32B
+- **Fine-tuning Method**: LoRA (Low-Rank Adaptation)
+- **Training Data**: 146 complex surgical cases
+- **Validation**: Dual-center external validation (52 cases)
+- **Task Strategy**: Targeted decomposition approach
+
+### LoRA Configuration
+
+```python
+lora_config = {
+    "lora_rank": 16,
+    "lora_alpha": 32,
+    "learning_rate": 1e-4,
+    "target_modules": ["q_proj", "k_proj", "v_proj", "o_proj"]
+}
+```
+
+## 📋 Supported Complications
+
+The models detect and grade 22 perioperative complications:
+
+1. **Cardiovascular**: Myocardial injury, cardiac arrhythmias
+2. **Respiratory**: Pneumonia, respiratory failure  
+3. **Renal**: Acute kidney injury
+4. **Gastrointestinal**: Paralytic ileus, anastomotic leakage
+5. **Infectious**: Surgical site infections, sepsis
+6. **Neurological**: Delirium, stroke
+7. **Hematological**: Bleeding, thromboembolism
+8. **And more...**
+
+Each complication is graded as:
+- **Mild**: Minor intervention required
+- **Moderate**: Significant medical management
+- **Severe**: Life-threatening, intensive intervention
+
+## 🏥 Clinical Applications
+
+### Primary Use Cases
+
+- **Automated Screening**: Continuous 24/7 complication monitoring
+- **Quality Assurance**: Systematic complication registry validation  
+- **Clinical Decision Support**: "Second opinion" for complex cases
+- **Research**: Standardized outcome assessment for clinical studies
+
+### Deployment Scenarios
+
+- **Resource-limited Settings**: Use PeriComp-4B/8B models
+- **Standard Clinical Environment**: PeriComp-14B recommended
+- **High-accuracy Requirements**: PeriComp-32B for maximum performance
+- **Reasoning-enhanced Tasks**: PeriComp-QwQ-32B for complex diagnostic reasoning
+
+## ⚠️ Important Considerations
+
+### Clinical Validation Required
+
+⚠️ **These models are research tools and require clinical validation before use in patient care**
+
+### Limitations
+
+- Training on Chinese medical records (generalizability considerations)
+- Performance depends on documentation quality and completeness
+- Not a replacement for clinical judgment
+
+### Best Practices
+
+- Use as **screening tool** with clinical oversight
+- Validate outputs against clinical judgment
+- Consider local adaptation for specific institutional practices
+
+## 📚 Citation
+
+If you use PeriComp in your research, please cite:
+
+```bibtex
+@article{pericomp2025,
+  title={Enhancing Local Language Models for Perioperative Complication Detection: A Targeted Strategy with LoRa Fine-tuning},
+  author={[Authors]},
+  journal={[Journal]},
+  year={2025}
+}
+```
+
+## 📧 Contact & Support
+
+For questions, issues, or collaboration opportunities:
+
+- **Research Team**: Department of Anesthesiology, First Affiliated Hospital of Sun Yat-sen University, Guangzhou, China
+- **Technical Issues**: gaoshw5@mail.sysus.edu.cn
+- **Clinical Applications**: Perioperative Complications Detection
+
+## 📄 License
+
+This work is licensed under Apache License 2.0. See LICENSE for details.
+
+---
+
+*PeriComp: Advancing perioperative patient safety through AI-powered complication detection*