[MRIQC 3] MRIQC 실행하기: 사전 작업부터 결과 확인까지
20 May 2024 #bio #brainImaging
MRIQC는 입력된 MRI 이미지의 quality를 분석 및 평가하고, 관련 내용을 report로 정리해줍니다. MRIQC를 사용하기 위해서는 BIDS 형식에 맞게 저장된 MRI 이미지가 필요합니다. 이번 포스트에서는 DICOM 파일을 가지고 MRIQC를 실행하고 분석 결과를 얻는 일련의 과정을 상세히 설명해보겠습니다.
nii2dcm
여기서는 DICOM 파일을 사용하지만, NIfTI 형식의 파일 또한 일반적인 MRI 파일 포맷 중 하나입니다. NIfTI 파일을 사용하는 경우 NIfTI를 지원하는 BIDS converter를 사용하거나, NIfTI를 DICOM으로 변환한 뒤 DICOM 지원 BIDS converter를 사용할 수 있습니다. 개인적인 경험으로는 NIfTI 지원 BIDS converter들이 안정적으로 작동하지 않았습니다 (제가 실패한 것일 수도 있습니다만). nii2dcm 라이브러리를 사용해 NIfTI를 DICOM으로 변환할 수 있습니다. 아래 코드를 실행할 수 있습니다:
nii2dcm NIFTI_FILE_DIR OUTPUT_DIR -d MR
NIFTI_FILE_DIR: 변환하고자 하는 NIfTI 파일 경로OUTPUT_DIR: 변환된 DICOM 파일을 저장할 경로
Heudiconv
저는 BIDS converter로 Heudiconv를 사용했습니다. 공식 페이지에서 제공하는 튜토리얼를 참고하며 제가 성공적으로 실행한 방법을 정리했습니다. 사용 방법은 다음과 같습니다.
Heudiconv 설치
pip를 통해 설치합니다:
pip install heudiconv
heuristic.py 작성
각 이미지가 BIDS 형식에 맞춰 저장되도록 규칙을 정의하는 코드를 작성합니다. 튜토리얼에 제공된 데이터 저장소에서 heuristic.py 파일을 참고하거나 직접 수정할 수 있습니다. 이 파일은 입력된 이미지 파일의 모달리티를 판단하고, 각 모달리티별로 BIDS 형식에 맞는 파일 경로를 생성하여 이미지를 새로 저장합니다. 필요한 경우 판단 조건과 저장 경로를 수정할 수 있습니다.
참고 및 수정할 함수는 heuristic.py 내 infotodict() 입니다.
- 사용할 이미지의 모달리티를 인지합니다: T1WI, T2WI, DWI 등
- 사용할 모달리티가 아닌 경우 관련 코드를 삭제하거나 주석 처리합니다.
- 사용할 이미지의 모달리티가 저장될 경로 형식을 확인하고 필요한 경우 수정합니다.
- 각 모달리티를 구분할 수 있는 기준(차원, 현재 파일명 특징 등)을 조건문에 명시하여 수정합니다.
제가 수정한 예시 코드는 아래와 같습니다. T1WI과 DWI를 사용하는 경우, 이미지가 저장될 경로와 이미지의 모달리티를 판단한 조건을 설정하였습니다.
Heudiconv 실행
설치 후 아래와 같이 파라미터를 설정하여 실행합니다. Heudiconv는 여러 개의 subject 데이터, 즉 DICOM 파일 묶음 여러 개를 한 번에 처리할 수 있습니다.
heudiconv --files DICOM_FILE_DIRS -o OUTPUT_DIR -f HEURISTIC.PY -s SUB_ID -ss SES_ID -c dcm2niix -b minmeta --overwrite
DICOM_FILE_DIRS: 여러 subject의 DICOM 파일을 글로빙(globbing) 형식으로 입력 (e.g. dataset/sub-001/ses-001/*/*.dcm)OUTPUT_DIR: 변환된 BIDS 형식의 폴더가 저장될 경로HEURISTIC.PY: 위에서 작성한heuristic.py파일의 경로SUB_ID: Subject id (e.g. 001)SES_ID: Session id (e.g. 001)
실행 예시는 다음과 같습니다. 아래 코드를 입력할 경우:
heudiconv --files data/*/*.dcm -o bids/data/ -f heuristic.py -s 0 -ss 0 -c dcm2niix -b minmeta --overwrite
bids/data/ 아래 다음과 같이 BIDS 형식의 폴더가 생성됩니다.
MRIQC
BIDS 형식으로 저장된 MRI 이미지가 준비되었다면, 이를 MRIQC에 입력할 수 있습니다. MRIQC는 PyPI를 통해 다운로드하여 사용하거나, docker 컨테이너를 통해 사용할 수 있습니다.
With PyPI
우선 아래 코드를 통해 설치해줍니다:
python -m pip install -U mriqc
설치 후 실행 코드는 아래와 같습니다:
mriqc BIDS_ROOT_DIR OUTPUT_DIR participant --participant-label SUB_ID
BIDS_ROOT_DIR: BIDS format 폴더의 루트 경로OUTPUT_DIR: MRIQC 결과를 저장할 경로participant OR group:participant로 지정할 경우 subject를 단위로,group으로 지정할 경우 루트 경로 하 모든 이미지를 대상으로 MRIQC 분석 결과를 얻습니다.SUB_ID:participant모드의 경우--participant-label에 subject id를 입력하여 분석할 subject를 지정할 수 있습니다. 복수의 id를 한번에 입력할 수 있습니다 (e.g.--participant-label 001 002 003)
With Docker
저는 Docker를 통해 MRIQC를 사용했습니다. Docker 컨테이너는 프로그램의 실행에 필요한 모든 종속성을 포함하기 때문에 일관된 환경을 보장하는 장점이 있습니다. 아래 코드를 입력하면 participant level에서 MRIQC를 실행할 수 있습니다:
docker run -it --rm -v BIDS_ROOT_DIR:/data:ro -v OUTPUT_DIR:/out nipreps/mriqc:latest /data /out participant --participant_label SUB_ID [--verbose-reports]
nipreps/mriqc 이미지가 다운로드되어 있지 않아도 코드를 실행할 시 자동으로 다운로드됩니다.
BIDS_ROOT_DIR: BIDS format 폴더의 루트 경로.-vflag에 따라 컨테이너 내부의/data폴더와 연결됩니다.ro옵션은 ‘read only’로, 로컬 경로에서 컨테이너 경로로 읽기만 가능하다는 의미를 가집니다.OUTPUT_DIR: MRIQC 결과를 저장할 경로. 컨테이너 내/out폴더와 연결됩니다. 컨테이너의/out폴더 내용을 로컬로 복사해보면OUTPUT_DIR과 동일한 결과가 저장되어 있는 것을 확인할 수 있습니다.- 컨테이너 내부 파일 내용 복사하기: 위
docker run실행 시--rm(작업 완료 후 삭제) 옵션을 삭제하고, 작업 완료 후docker cp CONTAINER_NAME:FILE_PATH LOCAL_PATH실행
- 컨테이너 내부 파일 내용 복사하기: 위
SUB_ID: Subject id. 여러 개의 id를 입력할 수 있습니다. (e.g.--participant_label 001 002 003)--verbose-reports(Optional): 이 flag를 입력하면 기본적으로 보고되는 visual report plot 외 다른 plot 4가지가 추가적으로 보고됩니다.
위 코드 실행 후 docker image 및 container 리스트를 확인하면 실행된 MRIQC 관련 항목을 볼 수 있습니다.
MRIQC Results
MRIQC 분석이 완료되면 OUTPUT_DIR 하에 위와 같은 파일들이 생깁니다. 이 중 figures 폴더 내 plot 이미지 파일 및 파일명을 이름으로 가지는 JSON과 HTML 파일, 위 예시에서는 sub-0_ses-0_T1w.json 과 sub-0_ses-0_T1w.html에 분석 결과가 담깁니다. Plot 이미지들과 JSON 파일을 기반으로 하여 HTML 파일로 결과 report가 작성됩니다.
해당 HTML 파일을 열면 위와 같은 report를 볼 수 있습니다. Visualized plot과 quality metric score를 종합하여 report를 해석하면 이미지의 quality를 알 수 있습니다.