Update README.md

README.md

@@ -1,3 +1,115 @@
----
-license: cc-by-nc-4.0
----
+---
+license: cc-by-nc-4.0
+tags:
+- mental-health
+- social-media
+- life-events
+---
+
+# PsyEvent: Life Event Recognition System
+
+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).
+
+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
+
+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.
+
+Both models share the same architecture (`BERTDiseaseClassifier`) defined in `model.py`.
+
+## Usage
+
+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.
+
+### 1. Installation
+
+```bash
+pip install transformers torch huggingface_hub
+```
+### 2. Define the Model Architecture
+
+You can download the model.py file from this repository, or simply define the class in your code as shown below:
+```python
+import torch
+from torch import nn
+from transformers import AutoModel, AutoConfig, AutoTokenizer
+
+class BERTDiseaseClassifier(nn.Module):
+    def __init__(self, model_type, num_symps) -> None:
+        super().__init__()
+        self.model_type = model_type
+        self.num_symps = num_symps
+        self.encoder = AutoModel.from_pretrained(model_type)
+        self.dropout = nn.Dropout(self.encoder.config.hidden_dropout_prob)
+        self.clf = nn.Linear(self.encoder.config.hidden_size, num_symps)
+    
+    def forward(self, input_ids=None, attention_mask=None, token_type_ids=None, **kwargs):
+        outputs = self.encoder(input_ids, attention_mask, token_type_ids)
+        x = outputs.last_hidden_state[:, 0, :]   # [CLS] pooling
+        x = self.dropout(x)
+        logits = self.clf(x)
+        return logits
+```
+
+### 3. Load the Models
+Use the subfolder parameter to select which model you want to load.
+```python
+import torch
+from transformers import AutoConfig, AutoTokenizer
+from huggingface_hub import hf_hub_download
+# from model import BERTDiseaseClassifier
+
+repo_id = "shallowblueQAQ/psyevent-model"
+subfolder = "LE_detection"
+# subfolder = "Self-status_determination"
+
+# 1. Load Config & Tokenizer
+config = AutoConfig.from_pretrained(repo_id, subfolder=subfolder)
+tokenizer = AutoTokenizer.from_pretrained(repo_id, subfolder=subfolder)
+
+# 2. Initialize Model Architecture
+model = BERTDiseaseClassifier(model_type=config._name_or_path, num_symps=len(config.id2label))
+
+# 3. Load Weights
+weights_path = hf_hub_download(repo_id=repo_id, subfolder=subfolder, filename="pytorch_model.bin")
+model.load_state_dict(torch.load(weights_path, map_location="cpu"))
+model.eval()
+
+# 4. Inference
+text = "I lost my job yesterday and I feel terrible."
+inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=128)
+
+with torch.no_grad():
+    logits = model(**inputs)
+    probs = torch.sigmoid(logits)
+
+# Display Predictions (Multi-label)
+threshold = 0.5
+for i, prob in enumerate(probs[0]):
+    if prob > threshold:
+        print(f"Detected: {config.id2label[i]} ({prob:.4f})")
+```
+
+## Data Availability & Privacy Statement
+
+This model was trained on a subset of the **SMHD (Self-reported Mental Health Diagnoses)** dataset. 
+
+**Due to the strict Data Usage Agreement of SMHD, we are prohibited from publishing or sharing any proportion of the original dataset (including our annotated subset).** Researchers interested in reproducing this work or using the data must apply for access directly from the original creators of [SMHD (Cohan et al., 2018)](https://aclanthology.org/C18-1126/). We only provide the model weights and inference code here.
+
+### Citation
+If you use this model or dataset, please cite our paper:
+```bibtex
+@inproceedings{lv2025tracking,
+  title={Tracking life’s ups and downs: Mining life events from social media posts for mental health analysis},
+  author={Lv, Minghao and Chen, Siyuan and Jin, Haoan and Yuan, Minghao and Ju, Qianqian and Peng, Yujia and Zhu, Kenny and Wu, Mengyue},
+  booktitle={Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)},
+  pages={6950--6965},
+  year={2025}
+}
+```