# REAST4CGEP

**Repository Path**: Tomhappy/REAST4CGEP

## Basic Information

- **Project Name**: REAST4CGEP
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# REAST: Graph Event Relation Augmented Structure Training for Causality Graph Event Prediction

This repository contains the source code for **REAST**, a method for predicting event relations in causality graphs using multi-modal RoBERTa encoders and Graph Attention Networks (GAT).

## Overview

REAST is designed for **Causality Graph Event Prediction (CGEP)** tasks. It leverages:
- **Multi-modal RoBERTa encoders**: Three RoBERTa instances for text and graph encoding with trainable virtual token embeddings
- **Graph Attention Network (GAT)**: For capturing graph structure and relational patterns
- **Contrastive Learning**: Node-level and path-level losses for improved event relation prediction
- **Prompt Learning**: Task-specific fine-tuning with masked language modeling objectives

## Project Structure

```
.
├── Model/                      # Model implementations
│   ├── model.py               # Main MLP model with GAT integration
│   ├── GAT.py                 # Graph Attention Network module
│   └── temp_model.py          # Temporary/alternative model
├── Handler/                   # Utility handlers
│   ├── tools_handler.py       # Tools for data processing
│   └── util_handler.py        # Helper utilities
├── main.py                    # Main training/inference script
├── parameter.py               # Argument parser and hyperparameter configuration
├── load_data.py               # Data loading utilities
├── util.py                    # General utilities (data correction, event replacement, etc.)
├── log.py                     # Logging module
├── predict/                   # Generated prediction results (train/dev/test splits)
├── out/                       # Generated logs
└── outmodel/                  # Generated model checkpoints
```

## Installation

### Requirements
- Python 3.7+
- PyTorch with CUDA support
- Transformers library
- NetworkX (for graph processing)

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd REAST4CGEP

# Install dependencies
pip install torch transformers numpy networkx tqdm tokenizers
```

## Usage

### Training

```bash
python main.py \
    --batch_size 1 \
    --t_lr 1e-6 \
    --pred_loss 0.5 \
    --node_path_ratio 2.0 \
    --temperature 0.3 \
    --seed 209
```

### Model Parameters

Configure hyperparameters via command-line arguments (see `parameter.py` for full list):

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--num_epoch` | 10 | Number of training epochs |
| `--batch_size` | 1 | Batch size |
| `--t_lr` | 1e-6 | Learning rate |
| `--wd` | 0.05 | Weight decay |
| `--pred_loss` | 0.5 | Weight of prediction loss |
| `--node_path_ratio` | 2.0 | Weight ratio for node-path loss |
| `--temperature` | 0.3 | Temperature for contrastive learning |
| `--lam` | 0.5 | Hyperparameter for graph weight blending |
| `--model_name` | roberta-base | Pretrained model name |

### Outputs

- **Logs**: Stored in `./out/` with timestamp and configuration details
- **Model Checkpoints**: Saved to `./outmodel/` for each epoch
- **Predictions**: Stored in `./predict/{train|dev|test}/` folders

## Key Features


### 1. Graph Attention Network (GAT)
- Processes sentence-level graphs with cosine similarity-based adjacency weighting
- Combines learned attention with task-specific graph structure
- Outputs refined node embeddings for event prediction

### 2. Contrastive Loss Functions
- **Node Loss**: Contrastive loss between graph and text representations
- **Path Loss**: Contrastive loss for path-level event relations
- Combined with masked language modeling loss for unified training

### 3. Virtual Token Management
Custom event tokens (e.g., `<a_1>`, `<a_2>`, ...) are:
- Added to the tokenizer vocabulary
- Initialized by averaging embeddings of component tokens
- Fine-tuned during training across all three RoBERTa instances

## Training Details

1. **Seed Setting**: All randomness (Python, NumPy, PyTorch) is seeded for reproducibility
2. **Device Management**: Automatically uses CUDA if available
3. **Data Processing**:
   - Multi-token events are corrected and made contiguous
   - Events are replaced with special tokens during training
   - Batch processing with configurable batch size
4. **Logging**: Real-time logging to console and file with timestamp

## Dataset
We provide the CGEPdata dataset via Baidu Netdisk for easy access.
**Dataset Name**: CGEPdata
**Download Link**: https://pan.baidu.com/s/1sCPYZKXWXWFeF3fqxXZTxA?pwd=je2d
**Extraction Code**: je2d
### Usage Instructions
1. Download the dataset from the link above using the extraction code.
2. Extract the dataset to the data/ directory in this project.
3. Ensure the folder structure is correct before running experiments.


## Citation

If you use this code in your research, please cite:

```bibtex
@article{reast2026,
  title={Graph Event Relation Augmented Structure Training for Causality Graph Event Prediction},
  author={...},
  year={2026}
}
```

## License

Please refer to the LICENSE file for licensing details.

## Contact

For questions or issues, please open an issue on the repository.