Update README.md

README.md

@@ -6,7 +6,10 @@ tags:
 - life-events
 ---
 
-# PsyEvent: Life Event Recognition System
+
+# 🧠 PsyEvent: Life Event Recognition System
+
+## 📖 Model Overview
 
 This repository contains the models described in the paper **["Tracking Life's Ups and Downs: Mining Life Events from Social Media Posts for Mental Health Analysis"](https://aclanthology.org/2025.acl-long.345/)** (ACL 2025).
 
@@ -14,16 +17,21 @@ The system consists of two distinct models housed in this repository:
 1.  **Life Events Detection (`LE_detection`)**: A multi-label classifier that identifies 12 categories of life events from social media posts.
 2.  **Self-Status Determination (`Self-status_determination`)**: A binary classifier that determines whether the detected life event is currently being experienced by the user themselves (Self) or someone else.
 
-## Model Organization
+### Architecture
+Both models are based on **BERT-large** (340M parameters) with a custom classification head.
+
+## 📂 Repository Structure
 
 This repository uses **subfolders** to store the weights for each model. You must specify the `subfolder` argument when loading.
 
-- `LE_detection/`: Contains the Life Event Detection model.
-- `Self-status_determination/`: Contains the Self-Status Determination model.
+| Subfolder | Task Description | Type |
+| :--- | :--- | :--- |
+| `LE_detection/` | Detects **which** life events are present. | Multi-label Classification |
+| `Self-status_determination/` | Detects **who** is experiencing the event. | Binary Classification |
 
 Both models share the same architecture (`BERTDiseaseClassifier`) defined in `model.py`.
 
-## Usage
+## 🚀 Quick Start (Copy & Run)
 
 Since these models use a custom architecture (BERT + Linear Head on `[CLS]` token without pooling), **you must define or import the model class locally** before loading the weights.
 
@@ -96,6 +104,42 @@ for i, prob in enumerate(probs[0]):
         print(f"Detected: {config.id2label[i]} ({prob:.4f})")
 ```
 
+## 📊 Dataset & Categories
+The model was trained on PsyEvent, a dataset of 7,965 annotated sentences derived from SMHD. It covers 12 major life event categories:
+
+| Life Event Categories | Representative Examples (from paper Appendix D) |
+| :--- | :--- |
+| `🏥 Health` | personal injury , accident or illness; became disabled; mental illenss. |
+| `💰 Financial` | loan; home purchase; car purchase; other major purchase. |
+| `🏠 Relocation` | move to a different town/city; move out of parent's home; lost home / became homeless; major travel. |
+| `💼 Career`| started a new job; promotion; voluntary/involuntary job loss; retirement. |
+| `🎓 Education`| begin or end school/college; change in school/college; left school (without graduating). |
+| `💔 Relationship Change`| began/ended serious romantic relationship; marriage; divorce; serious argument. |
+| `🕯️ Death`| death of spouse/child/parent/friend/pet. |
+| `👶 New Birth`| gave birth / became a parent; adopted a child; became a grandparent. |
+| `⚖️ Legal`| got arrested; lawsuit or legal action; went to jail or prison; released from jail or prison. |
+| `🌈 Identity`| came out as LGBTQ+; gender transition; change in political/religious/spiritual beliefs. |
+| `🌱 Lifestyle Change`| change in physical habits; new pet; joined the military; vacation. |
+| `🌍 Societal`| natural disaster; war; major political event that had personal impact. |
+
+## Performance (AUC)
+LE detection model performance on each life event category:
+| Life Event Categories | AUC(%) |
+| :--- | :--- |
+| Health | 92.1 |
+| Financial | 95.7 |
+| Relocation | 97.7 |
+| Legal | 96.1 |
+| Relationship Change | 95.0 |
+| New Birth | 92.6 |
+| Death | 99.7 |
+| Career | 93.5 |
+| Education | 99.2 |
+| Lifestyle Change | 87.9 |
+| Identity | 95.5 |
+| Societal | 97.4 |
+| Avg. | 95.2 |
+
 ## Data Availability & Privacy Statement
 
 This model was trained on a subset of the **[SMHD (Self-reported Mental Health Diagnoses)](https://aclanthology.org/C18-1126/)** dataset.