🌐 CAMEF: Causal-Augmented Multi-Modality Event-Driven Financial Forecasting

CAMEF is a novel framework for forecasting financial market trends by integrating time-series data and macroeconomic policy texts, enhanced by causal learning through LLM-generated counterfactuals. It was accepted at KDD 2025.

• 📄 Proceedings Paper
• 📄 arXiv Paper
• 📊 Poster
• 📊 Slides
• 📚 Citation (BibTeX):

  @inproceedings{10.1145/3711896.3736872,
    author = {Zhang, Yang and Yang, Wenbo and Wang, Jun and Ma, Qiang and Xiong, Jie},
    title = {CAMEF: Causal-Augmented Multi-Modality Event-Driven Financial Forecasting by Integrating Time Series Patterns and Salient Macroeconomic Announcements},
    year = {2025},
    isbn = {9798400714542},
    publisher = {Association for Computing Machinery},
    address = {New York, NY, USA},
    url = {https://doi.org/10.1145/3711896.3736872},
    doi = {10.1145/3711896.3736872},
    booktitle = {Proceedings of the 31st ACM SIGKDD Conference on Knowledge Discovery and Data Mining V.2},
    pages = {3867–3878},
    numpages = {12},
    keywords = {causal learning, financial dataset, multimodal learning, time-series forecasting},
    location = {Toronto ON, Canada},
    series = {KDD '25}
  }
  

📦 Dataset Access

We provide the processed CAMEF dataset, which includes both raw and cleaned versions of key macroeconomic announcements and high-frequency financial time-series data spanning from 2004 to 2024.

📰 Macroeconomic Policy Texts

Six types of macroeconomic announcements:

• FOMC Minutes
• Unemployment Insurance Claims
• Employment Situation Reports
• GDP Advance Releases
• Consumer Price Index (CPI) Reports
• Producer Price Index (PPI) Reports

📈 Time-Series Financial Data

High-frequency (5-minute level) trading data for five major U.S. financial assets:

• S&P 500 Index
• NASDAQ 100 Index
• Dow Jones Industrial Average (DJIA)
• U.S. 1-Month Treasury Yield
• U.S. 10-Year Treasury Yield

🧠 Generated Counterfactual Policy Texts

We utilized the LLaMA-3 language model to generate 10 counterfactual versions of each policy event, guided by sentiment-manipulating prompts. These counterfactuals simulate different market conditions and enrich causal learning.

Downloads

Resource	Link
Dataset (dataset.zip)	Google Drive
Trained CAMEF models	Google Drive folder

📁 Download the full dataset from Google Drive 📝 Source: All data are collected from publicly available government and financial databases.

📦 Sample Data Provided To help users quickly understand the dataset structure and contents, we include a few example files under the dataset_sample/ folder in this repository. These are representative subsets from the full dataset.

Dataset Folder Structure

events/
├── processed_events_and_counterfactuals/
│   ├── 1/  # FOMC Minutes
│   ├── 2/  # Unemployment Insurance Claims
│   ├── 3/  # Employment Situation Reports
│   ├── 4/  # GDP Advance Releases
│   ├── 5/  # Consumer Price Index (CPI) Reports
│   └── 6/  # Producer Price Index (PPI) Reports
│
│   └── [event_date]/
│       ├── 20021017.txt_full_summary.txt
│       ├── 20021017.txt_report_sent0.txt
│       ├── 20021017.txt_report_sent1.txt
│       ├── ... up to sent9.txt
│       ├── 20021017.txt_chunk_summaries.txt
│       └── 20021017.txt_sentiment_report.txt
│
├── raw_dataset/
│   ├── raw/
│   ├── html_process/
│   └── test/

📄 File Naming Convention

• *.txt_full_summary.txt: The LLaMA3-generated main summary of the original policy text, used as the core input event script.
• *_report_sent[0-9].txt: Counterfactual policy texts generated from the main summary, each reflecting a different sentiment level.
• *_sentiment_report.txt: Analytical text generated by LLaMA3 describing the sentiment and implications of the original policy.
• *_chunk_summaries.txt: Optional section-wise summaries of the raw document.

Code Quick Start

The RoBERTa-based CAMEF implementation lives in the CAMEF/ folder. Training and evaluation scripts use the CAMEF model class in CAMEF/model/CAMEF.py.

Repository Layout

CAMEF/
├── moment.yml
├── train.py
├── test.py
├── model/
│   ├── __init__.py
│   └── CAMEF.py
└── data/
    ├── __init__.py
    └── dataloader.py

Data files and pretrained model weights are not stored in git. Download them from the links above or pass explicit paths with command-line arguments.

Environment

Create the conda environment from CAMEF/moment.yml:

conda env create -f CAMEF/moment.yml
conda activate moment

If the moment environment already exists and you want to update it:

conda env update -n moment -f CAMEF/moment.yml --prune
conda activate moment

The model uses CUDA automatically when available. CPU execution is possible but will be very slow.

Required Data

Download the dataset from Google Drive (dataset.zip), then extract it so you have:

• Event text files under data/event
• Time-series CSV files under data/series

For example, the default SP500 run expects data/series/SP500.csv with columns date, date_int, and OHLC value columns (d is usually 4).

If you keep data outside the repo, pass explicit paths:

--event-dir /path/to/event --series-dir /path/to/series

Required Pretrained Models

The training and testing scripts need:

• RoBERTa text encoder: default FacebookAI/roberta-base
• GPT-2 decoder backbone: default openai-community/gpt2
• MOMENT encoder: Hugging Face AutonLab/MOMENT-1-large via --moment-model

Evaluate A Trained Model

Trained CAMEF checkpoints are available from the trained models Google Drive folder.

Download the folder for the dataset and forecast length you want (for example, CAMEF_SP500_Len35), then run test.py from the CAMEF/ directory:

cd CAMEF
python test.py \
  --checkpoint /path/to/downloaded/CAMEF_SP500_Len35/best_model.pth \
  --moment-model AutonLab/MOMENT-1-large \
  --event-dir data/event \
  --series-dir data/series \
  --series-id SP500 \
  --seq-len 35 \
  --pred-len 35 \
  --batch-size 10 \
  --split test

Google Drive folders follow the pattern CAMEF_<DATASET>_Len<PRED_LEN>, such as CAMEF_SP500_Len35, CAMEF_NASDAQ_Len70, or CAMEF_INDU_Len140. Make sure --series-id, --seq-len, and --pred-len match the downloaded model folder.

To save per-sample inputs, targets, and predictions:

cd CAMEF
python test.py \
  --checkpoint /path/to/downloaded/CAMEF_SP500_Len35/best_model.pth \
  --moment-model AutonLab/MOMENT-1-large \
  --event-dir data/event \
  --series-dir data/series \
  --series-id SP500 \
  --seq-len 35 \
  --pred-len 35 \
  --save-samples-dir outputs/sample_predictions

When testing a checkpoint, keep architecture settings consistent with training: --seq-len, --pred-len, --bert-model, --gpt-model, --moment-model, --window, --stride.

Train From Scratch

cd CAMEF
python train.py \
  --moment-model AutonLab/MOMENT-1-large \
  --event-dir data/event \
  --series-dir data/series \
  --series-id SP500 \
  --seq-len 35 \
  --pred-len 35 \
  --batch-size 10 \
  --epochs 10 \
  --output-path outputs/sp500_len35

Training writes:

• outputs/sp500_len35/best_model.pth
• outputs/sp500_len35/lastest_model.pth
• outputs/sp500_len35/log.txt
• outputs/sp500_len35/tokenizer/

Useful options:

• --bert-model: use a local RoBERTa path instead of the Hugging Face id.
• --gpt-model: use a local GPT-2 path instead of the Hugging Face id.