생성형 심전도-언어 모델(ELM) 벤치마킹을 위한 통합 프레임워크

<h2 align="center"> 생성형 심전도-언어 모델(ELMs) 벤치마킹을 위한 통합 프레임워크 </h2>

소식 (News)

[2026년 2월 23일] 저장소를 https://github.com/ELM-Research/ELM으로 영구 이전 및 리팩토링했습니다. https://github.com/willxxy/ECG-Bench는 아카이브될 예정입니다.
[2026년 2월 19일] 이 저장소를 ELM 학습 전용으로 변경하고 ECG 인코더 사전 학습(pretraining) 기능을 제거할 예정입니다. 별도의 ECG 인코더 사전 학습 저장소를 생성했습니다. 확인해 보세요!
[2026년 2월 17일] 현재 더 쉬운 사용을 위해 다른 리팩토링 작업을 진행 중입니다. 기다려 주셔서 감사드리며, 완료되는 대로 업데이트하겠습니다!
[2025년 11월 13일] tests/test_openai.py에서 ECG-QA PTB-XL 및 MIMIC-IV-ECG 데이터셋의 분할을 사용하여 OpenAI API를 통해 GPT 모델 변형으로 새로운 기준선(baseline)을 만들었습니다. 루트 디렉토리에서 python -m tests.test_openai를 실행하여 기준선을 테스트해 보세요!
[2025년 11월 7일] tests/test_opentslm.py에서 ECG-QA PTB-XL 및 MIMIC-IV-ECG 데이터셋의 분할을 사용하여 OpenTSLM 모델로 새로운 기준선을 만들었습니다. 먼저 OpenTSLM 저장소를 tests/ 폴더 안에 git clone한 후, ECG-Bench의 루트 디렉토리에서 python -m tests.test_opentslm을 실행하세요!
[2025년 11월 7일] ELM에 대한 Platonic Representation Hypothesis의 단순 분석을 개발했습니다. 분석 실행은 scripts/run_plat_rep.sh를 참고하세요.

• [2025년 11월 7일] 우리는 Signal2Vec을 구현하여 ECG-Byte의 임베딩을 생성했으며, 이를 활용한 ELM 아키텍처도 구현했습니다! ECG-Byte 토크나이저를 위한 Signal2Vec 임베딩 학습은 scripts/train_signal2vec.sh 스크립트를 확인하세요. Signal2Vec으로 ELM을 학습시키려면 --encoder=signal2vec 및 --signal2vec_embeddings=$PATH_TO_PT_FILE을 지정하십시오.
• [2025년 10월 18일] 사용자가 직접 전처리할 필요가 없도록 전처리된 ECG 파일을 출시했습니다.

<details> <summary><strong id=

개요 <a name="overview"></a>

본 저장소는 심전도-언어 모델(ELMs)을 훈련하고 평가하기 위한 통합 프레임워크를 제공합니다. 이 프레임워크는 ELM 개발 연구자들을 대상으로 하며, 특히 ECG 표현 방식과 훈련 패러다임에 중점을 둡니다. 우리는 코드베이스가 모듈화되고 확장 가능하도록 목표하며, 이를 통해 신속한 실험과 새로운 아이디어의 쉬운 통합을 지원하고자 합니다. 현재 프레임워크는 아직 베타 단계이지만, 디자인과 안정성을 적극적으로 개선하고 있습니다. 성능은 코드베이스가 계속 변경됨에 따라 달라질 수 있다는 점에 유의해 주십시오.

저희는 더 많은 기능, ELMs, 데이터셋을 지원하기 위해 저장소를 지속적으로 업데이트할 것을 기대합니다. 언제든지 저장소에 기여해 주시기 바랍니다!
문의사항이나 버그가 있다면 wjhan{@}andrew{dot}cmu{edu}로 연락하거나 해당 세부 정보를 포함하여 이슈를 제출해 주십시오.

ECG 입력 표현 방식

현재 저장소는 아래와 같이 정의된 4가지의 ECG 입력 표현 방식을 고려합니다:

ECG 신호 (--ecg_signal):
원시(raw) ECG 신호는 X_sig $ ext{에 속하는 } ext{R}^{(C imes L)} ext{ 행렬로 표현되며, 여기서 } C ext{는 리드(leads)의 개수이고 } L ext{은 리드당 시간 샘플 수입니다. 다른 모든 양식(modalities)은 } X_{sig} ext{로부터 파생됩니다.

ECG 이미지 (--ecg_image):
X_sig로부터 플로팅을 통해 생성된 ECG 이미지는 텐서 X_img $ ext{에 속하는 } ext{R}^{(H imes W imes C')}$ 형태로 표현됩니다. 여기서 $H$와 $W$는 각각 이미지의 높이와 너비를 나타내며, $C'$는 색상 채널의 개수입니다.

쌓인 ECG 신호 (--ecg_stacked_signal):
또한, X_sig를 색상 차원(ECG 이미지에서 볼 수 있듯이)을 따라 세 번 쌓아 $ ext{R}^{(C imes L imes 3)}$에 속하는 합성 삼채널 버전인 X_sig*도 생성합니다.

ECG 심볼 (--ecg_token):
우리는 ECG-Byte의 압축 스키마를 사용하여 ECG 신호를 텍스트로 변환합니다. 먼저, 정규화되고 이산화된 ECG 신호 X_sig가 기호 집합 $A = ext{"{a}, ext{"{b}, ext{…}, ext{"{z}}$를 사용하여 심볼 시퀀스로 매핑됩니다. 이 시퀀스는 이후 일차원 배열 X_symb $ ext{에 속하는 } ext{A}^{(C * L)}$로 평탄화됩니다. 마지막으로, 바이트 쌍 인코딩(BPE) 프로세스가 X_symb를 확장된 어휘 집합 $V$의 토큰 시퀀스로 압축하여 최종 텍스트 표현인 X_ID $ ext{에 속하는 } ext{V}^{(m)}$을 생성하며, 여기서 $m$은 토큰 시퀀스의 길이입니다.

ELM 및 구성 요소

우리는 다음 ELM들을 구현합니다:

ECG-Byte: End-to-End 심전도 언어 모델링을 위한 토크나이저
LLaVA와 유사한 ELM (예: 신경망 인코더 + 투영 계층 + LLM)
인코더가 없는 ELM (예: 투영 계층 + LLM)

또한, 다음 ECG 전용 인코더들의 구현도 제공합니다:

HuggingFace를 활용하여, 우리는 ECG 인코더로 사용될 일반적인 사전 훈련 모델들도 제공합니다:

저희는 다음 사전 학습된 LLM들을 중심으로 HuggingFace API를 활용하여 래퍼(wrapper)를 생성했습니다:

또한, GPT 2와 OPT LLM도 보유하고 있지만, 현재는 이들에 대한 채팅 템플릿(chat templates)이 없습니다.

설치 (Installation)

모든 설치 및 실험은 NVIDIA A5000 및 A6000 GPU를 장착한 Ubuntu 20.04.5 LTS에서 완료되었습니다.

Rust 설치: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain=1.82.0 -y
PATH 설정을 위해 새 터미널을 엽니다.
새 터미널을 연 후, rustc --version을 실행하여 Rust 설치를 확인합니다.
conda create -n ecg python=3.10 명령어로 conda 가상 환경을 생성합니다.
환경 활성화: conda activate ecg
pip install uv 명령어로 uv 패키지 매니저를 설치합니다.
git clone https://github.com/willxxy/ECG-Bench.git
cd ECG-Bench
기본 설치: uv pip install -e .
flash attention을 포함한 설치: `uv pip install -e
또 다른 고려 사항은 HuggingFace에서 gated 모델(예: Llama 3.2, Gemma)을 사용한다는 것입니다. 따라서 API 키를 받아 환경 변수 export HF_TOKEN=$API_KEY를 내보내야 합니다.

참고: 작업 디렉터리는 저장소의 루트(ECG-Bench) 디렉터리입니다.

ECG 데이터셋 <a name="data"></a>

저희는 이 저장소에서 다양한 데이터셋에 대한 전처리 파이프라인도 제공합니다.
전처리된 ECG 파일를 다운로드하여 전체 전처리 섹션을 건너뛰고 메인 방법론 섹션으로 이동할 수 있다는 점에 유의하십시오.
저희는 2초, 5초, 10초 녹음본을 250 Hz로 샘플링한 전처리된 ECG를 제공합니다.
data 폴더가 위치해야 하는 구조는 다음과 같습니다:

ECG-Bench
└── ecg_bench
    └── data
...

여기서 ...은 동일한 preprocessed_1250_250, preprocessed_500_250, preprocessed_2500_250 폴더를 나타냅니다.
.zip 파일은 데이터 이름 폴더와 해당 전처리된 폴더들을 이미 압축 해제해야 합니다.

데이터셋:

Hugging Face Dataset 5-Fold Stratified Splits

Hugging Face에서는 환자별로 계층화된(stratified) 5분할 데이터셋을 제공하며, 학습 세트와 테스트 세트 간에 환자 중복이 없습니다.
현재까지 다음 데이터셋들을 공개했습니다:

250 Hz 샘플링 레이트