EB_Dashboard/DOCUMENTATION/DOCUMENTATION_32_QUICK_START.md

# 🚀 Endobest Dashboard - Quick Start Guide

**Quick Reference for Running the Dashboard**

---

## ⚡ 5-Minute Start

### Prerequisites
- Python 3.7+
- Internet connection
- Valid Ziwig credentials
- Configuration file in `config/Endobest_Dashboard_Config.xlsx`

### Three Simple Ways to Run

#### 1️⃣ Full Data Collection (Recommended)
```bash
python eb_dashboard.py
```
- ✅ Collects fresh data from all APIs
- ✅ Runs quality checks
- ✅ Generates JSON + Excel
- ⏱️ Takes 2.5-5 minutes
- 💡 **Use this for:** Regular data updates, first run

#### 2️⃣ Excel Export Only (Fast)
```bash
python eb_dashboard.py --excel-only
```
- ✅ Uses existing JSON data
- ✅ Regenerates Excel files
- ✅ NO data collection
- ⏱️ Takes 5-15 seconds
- 💡 **Use this for:** Testing new Excel configs, quick re-export

#### 3️⃣ Quality Check Only
```bash
python eb_dashboard.py --check-only
```
- ✅ Validates existing data
- ✅ Runs coherence + regression tests
- ✅ NO export
- ⏱️ Takes 5-10 seconds
- 💡 **Use this for:** Verify data before sharing

---

## 🔑 Default Credentials

The script uses built-in defaults (press Enter to accept):

```
Login: ziwig-invest2@yopmail.com
Password: pbrrA765$bP3beiuyuiyhiuy!agx
Number of threads: [1-20, default 12]
```

---

## 📁 What Gets Created

### Output Files
```
your_directory/
├── endobest_inclusions.json          (Patient data, ~6-7 MB)
├── endobest_inclusions_old.json      (Backup from previous run)
├── endobest_organizations.json       (Organization stats, ~17-20 KB)
├── endobest_organizations_old.json   (Backup)
├── [Excel files]                     (If configured, e.g., Endobest_Output_2025-01-15.xlsx)
└── dashboard.log                     (Execution log)
```

### File Locations
All files are created in the directory where you run the script.

---

## ⚙️ Configuration (Excel File)

**File:** `config/Endobest_Dashboard_Config.xlsx`

### Tables Available

| Table | Purpose | When to Edit |
|-------|---------|--------------|
| **Inclusions_Mapping** | Define which patient fields to extract | When adding new fields to reports |
| **Excel_Workbooks** | Define Excel files to create | When changing workbook templates |
| **Excel_Sheets** | Configure data in Excel sheets | When modifying filters, sorts, column mapping |
| **Regression_Check** | Define quality check rules | When allowing new data changes |

**Changes take effect on next run** (no restart needed)

---

## 🔍 Monitoring Progress

### During Execution
```
Overall Progress [████████████░░░░░░░░░░░░░░] 847/1200
  1/15 - Center 1 [██████████░░░░░░░░░░░░░░░░]  73/95
  2/15 - Center 2 [██████░░░░░░░░░░░░░░░░░░░░]  42/110
  3/15 - Center 3 [████░░░░░░░░░░░░░░░░░░░░░░]  28/85
```

### Checking Results
```bash
# View recent log entries
tail -n 50 dashboard.log

# Check for errors
grep ERROR dashboard.log

# View specific run
grep "2025-01-15" dashboard.log
```

---

## ✅ Quality Checks

### Two Validation Types

**1. Coherence Check**
- Compares API statistics vs. actual collected data
- Example: API says 145 patients, but only found 143 records
- Action: Warns if discrepancy > 10%

**2. Non-Regression Check**
- Compares current data vs. previous run
- Detects unexpected changes
- Action: Warns if changes violate configured rules

### What Happens if Issues Found

```
⚠ CRITICAL issues detected in quality checks!
Do you want to write the results anyway?
  [Y/N]:
```

- **YES** → Continue with export (override)
- **NO** → Cancel export, keep previous files

---

## 🐛 Troubleshooting

### "Login failed"
- Check credentials
- Verify internet connection
- Try again (sometimes transient network issue)

### "Template file not found"
- Check `config/templates/` folder
- Verify filename matches Excel config exactly

### "No data in Excel sheets"
- Check filter conditions aren't too strict
- Verify data exists: run `--check-only` first
- Check JSON files have content

### "Script is slow"
- Increase worker threads (up to 20)
- Check internet bandwidth usage
- First run always slower (no optimization)

### "Need detailed error info"
```bash
python eb_dashboard.py --debug
# Check dashboard.log for verbose output
```

---

## 📊 Sample Output

### First 10 Lines of endobest_inclusions.json
```json
[
  {
    "Patient_Identification": {
      "Organisation_Id": "12345-uuid",
      "Organisation_Name": "Hospital A",
      "Center_Name": "HOSP-A",
      "Patient_Id": "PAT-001",
      "Pseudo": "ENDO-001",
      "Patient_Name": "Doe, John",
      "Patient_Birthday": "1975-05-15",
      "Patient_Age": 49
    },
    "Inclusion": {
      "Consent_Signed": true,
      "Inclusion_Date": "15/10/2024",
      ...
```

---

## 📈 Performance Expectations

### Typical Timings
| Operation | Small (50 orgs) | Medium (100+ orgs) | Large (200+ orgs) |
|-----------|---|---|---|
| Data Collection | 5-10 min | 10-20 min | 20-30 min |
| Quality Checks | 5-10 sec | 10-15 sec | 15-20 sec |
| Excel Export | 5-10 sec | 10-15 sec | 15-20 sec |
| **TOTAL** | **5-10 min** | **10-20 min** | **20-30 min** |

**Tip:** Excel export is fast in `--excel-only` mode (5-15 seconds always)

---

## 🎯 Common Tasks

### Task 1: Regular Data Collection
```bash
python eb_dashboard.py
# Full process: collect → checks → export
# Repeat weekly or as scheduled
```

### Task 2: Reconfigure Excel Reports
```bash
# 1. Edit config/Endobest_Dashboard_Config.xlsx
# 2. Add/modify rows in Excel_Sheets table
# 3. Run fast export:
python eb_dashboard.py --excel-only
# New Excel files generated in seconds
```

### Task 3: Verify Data Quality
```bash
python eb_dashboard.py --check-only
# Runs validation without modifying files
# Great for pre-distribution checks
```

### Task 4: Debug Issues
```bash
python eb_dashboard.py --debug
# Verbose logging sent to dashboard.log
# Check log for detailed error information
```

---

## 📚 Next Steps

### For Basic Usage
→ See **DOCUMENTATION_98_USER_GUIDE.md**

### For Configuration Details
→ See **DOCUMENTATION_99_CONFIG_GUIDE.md**

### For Field Mapping
→ See **DOCUMENTATION_11_FIELD_MAPPING.md**

### For Excel Export
→ See **DOCUMENTATION_13_EXCEL_EXPORT.md**

### For Architecture Understanding
→ See **DOCUMENTATION_10_ARCHITECTURE.md**

---

## 🆘 Emergency Contacts / Support

### Check Documentation First
1. **This Quick Start** - Common questions
2. **DOCUMENTATION_98_USER_GUIDE.md** - FAQ section
3. **dashboard.log** - Error details

### Common Issue Solutions

| Issue | Solution |
|-------|----------|
| Script hangs | Press Ctrl+C, check network |
| Login fails | Verify credentials, check internet |
| Slow collection | Increase worker threads (up to 20) |
| Excel template issues | Check `config/templates/` folder |
| Quality check warnings | Review regression config rules |

---

## ⚡ Pro Tips

1. **First Run:** Always run full collection, even if slow
2. **Testing Configs:** Use `--excel_only` for quick feedback
3. **Batch Processing:** Schedule with task scheduler or cron
4. **Performance:** More threads = faster (but check bandwidth)
5. **Backups:** Old JSON files kept automatically (`_old` suffix)

---

## 🔐 Data Privacy

⚠️ **Important:**
- JSON files contain patient data
- Keep files in secure location
- Delete backups if not needed
- Follow hospital/research protocols

---

**For complete technical details, see DOCUMENTATION_30_ARCHITECTURE_SUMMARY.md**

**Questions? Check the comprehensive documentation in the project folder.**