데이터 소스

Parthenon에서 데이터 소스는 OMOP CDM 데이터베이스에 대한 연결을 의미합니다. 각 소스에는 하나 이상의 daimon이 있습니다. daimon은 CDM 임상 데이터, 용어 테이블, Achilles 결과, 임시 작업 테이블을 담고 있는 PostgreSQL 스키마를 가리키는 이름 있는 포인터입니다. 이 아키텍처는 기존 OHDSI WebAPI의 source/daimon 모델을 반영하므로 HADES 패키지, Atlas 내보내기, 더 넓은 OHDSI 도구 체계와 호환됩니다.

데이터 소스는 Parthenon의 모든 기능의 기반입니다. 용어를 탐색하거나, 코호트를 만들거나, 분석을 실행하기 전에 적어도 하나의 데이터 소스가 구성되고 연결되어 있어야 합니다.

Source/Daimon 모델

모든 데이터 소스는 두 가지 구성 요소로 이루어집니다:

소스 레코드

소스 레코드는 데이터베이스 연결 자체를 정의합니다:

• Source Name: 사람이 읽을 수 있는 레이블입니다. 예: "Claims Database 2024", "Eunomia Demo".
• Source Key: API 호출과 URL에 사용되는 짧은 소문자 식별자입니다. 예: claims-2024, eunomia.
• Connection Details: PostgreSQL 서버의 host, port, database name, credentials.
• CDM Version: 데이터의 OMOP CDM 버전입니다. 현재 표준은 v5.4입니다.

Daimons

각 소스에는 논리적 데이터 범주를 실제 데이터베이스 스키마에 매핑하는 하나에서 네 개의 daimons가 있습니다:

Daimon 유형	목적	일반적인 스키마	필수
CDM	임상 데이터 테이블: person, condition_occurrence, drug_exposure, measurement, procedure_occurrence, observation, visit_occurrence 등	omop, cdm 또는 eunomia	예
Vocabulary	개념 및 용어 테이블: concept, concept_ancestor, concept_relationship, vocabulary, domain, concept_class, concept_synonym	CDM과 동일한 스키마(흔함) 또는 전용 vocab 스키마	예
Results	사전 계산된 분석: Achilles 결과, Data Quality Dashboard 출력, 생성된 코호트 테이블(cohort, cohort_inclusion)	achilles_results, results 또는 eunomia_results	권장
Temp	코호트 생성 중간 테이블과 임시 분석 출력용 작업 공간	temp, scratch 또는 results와 동일	선택

모든 daimon이 같은 스키마를 가리킬 수 있습니다

많은 OMOP CDM 배포, 특히 Atlas나 ETL 도구로 구성된 배포에서는 모든 테이블이 하나의 스키마에 있습니다. 네 daimon이 모두 같은 스키마 이름을 가리키는 것은 완전히 유효하며 흔한 구성입니다. Parthenon은 이를 올바르게 처리합니다.

Daimon 사용 방식

Parthenon이 쿼리를 실행할 때 선택된 소스의 daimon 구성에 따라 PostgreSQL search_path를 동적으로 설정합니다. 예를 들어:

• 용어 검색은 vocabulary daimon의 스키마로 search path를 설정합니다.
• 코호트 생성은 results daimon의 스키마에 씁니다.
• 환자 프로필 쿼리는 CDM daimon의 스키마에서 읽습니다.
• Achilles 결과는 results daimon의 스키마에서 읽습니다.

이 방식 덕분에 하나의 Parthenon 인스턴스가 서로 다른 스키마 구조를 가진 여러 데이터베이스와 코드 변경 없이 작업할 수 있습니다.

데이터 소스 보기

상단 내비게이션에서 Data Sources로 이동하세요. 소스 목록은 구성된 모든 데이터 소스를 다음 정보와 함께 표시합니다:

• 소스 이름 및 키: 클릭하면 상세 보기가 열립니다.
• 연결 상태 표시기: 녹색(연결됨), 노란색(오래됨), 빨간색(실패).
• CDM 버전: 소스가 보고한 OMOP CDM 버전.
• Daimon 요약: 구성된 daimon 유형을 보여 주는 아이콘.
• 환자 수: CDM의 전체 person 수(Achilles가 있으면 사용).

소스 상세 보기

소스를 클릭하면 상세 패널이 열리며 다음을 포함합니다:

• 전체 연결 메타데이터(host, database, dialect, CDM version).
• 구성된 모든 daimon과 해당 스키마 이름 및 우선순위.
• 소스에 로드된 용어 버전(예: v5.0 2026-02-25).
• 빠른 링크:
  • 이 소스의 Data Explorer 보고서;
  • Data Quality Dashboard 결과;
  • Achilles Characterization 개요.

데이터 소스 추가

관리자 접근 필요

admin 또는 super-admin 역할을 가진 사용자만 데이터 소스를 생성, 수정 또는 삭제할 수 있습니다.

새 데이터 소스를 추가하려면:

1. Data Sources로 이동해 오른쪽 상단의 Add Data Source를 클릭합니다.

2. 기본 정보를 입력합니다:

   • Source Name: 설명적인 사람이 읽을 수 있는 레이블.
   • Source Key: 짧은 식별자. 소문자, 숫자, 하이픈만 허용되며 공백은 허용되지 않습니다.
   • CDM Version: OMOP CDM 버전을 선택합니다. v5.4를 권장합니다.

3. 데이터베이스 연결을 구성합니다:

   • Host: PostgreSQL 서버 hostname 또는 IP 주소.
   • Port: 일반적으로 5432.
   • Database: 데이터베이스 이름. 예: ohdsi.
   • Username: CDM 스키마에 읽기 접근 권한이 있는 데이터베이스 사용자.
   • Password: 애플리케이션 데이터베이스에 AES-256으로 암호화되어 저장됩니다.

4. 각 스키마 매핑에 대해 + Add Daimon을 클릭해 daimons를 추가합니다:

   • daimon type(CDM, Vocabulary, Results, Temp)을 선택합니다.
   • PostgreSQL 스키마 이름인 schema name을 입력합니다. 예: omop.
   • priority를 설정합니다. 아래 소스 우선순위를 참조하세요.

5. Save를 클릭합니다. Parthenon은 저장하기 전에 연결을 자동으로 테스트합니다.

연결 문자열 호환성

Atlas에서 마이그레이션하는 경우 jdbc:postgresql://dbhost:5432/ohdsi?currentSchema=omop 같은 JDBC 연결 문자열이 있을 수 있습니다. Parthenon은 편의를 위해 이를 허용하며 JDBC URL에서 host, port, database, default schema를 자동 추출합니다. 개별 필드를 사용해 연결 정보를 따로 입력할 수도 있습니다.

예: 일반적인 OMOP 데이터베이스 구성

모든 CDM 테이블, 용어, 결과가 omop 스키마에 있는 데이터베이스의 경우:

필드	값
Source Name	Acumenus OMOP
Source Key	acumenus-omop
Host	pgsql.acumenus.net
Port	5432
Database	ohdsi
CDM Daimon	Schema: omop, Priority: 1
Vocabulary Daimon	Schema: omop, Priority: 1
Results Daimon	Schema: achilles_results, Priority: 1

예: CDM과 vocabulary 스키마가 분리된 경우

서로 다른 스키마를 사용하는 배포의 경우:

필드	값
CDM Daimon	Schema: cdm_data, Priority: 1
Vocabulary Daimon	Schema: vocabulary, Priority: 1
Results Daimon	Schema: results, Priority: 1
Temp Daimon	Schema: temp, Priority: 1

소스 수정 및 삭제

• 소스 행의 연필 아이콘을 클릭해 수정 양식을 엽니다. 소스 키를 제외한 모든 필드를 수정할 수 있습니다.
• 휴지통 아이콘을 클릭해 소스를 삭제합니다.

삭제 보호 장치

데이터 소스 삭제는 파괴적인 작업입니다. 이 소스에 대해 생성된 코호트가 있으면 삭제가 차단됩니다. 소스를 제거하기 전에 종속 코호트 생성을 먼저 삭제하거나 재할당해야 합니다. 이는 존재하지 않는 데이터 소스를 참조하는 고아 분석 결과를 방지합니다.

소스 우선순위

여러 소스가 같은 daimon 유형을 제공할 때 priority 필드는 드롭다운과 소스를 명시하지 않은 API 호출에서 기본으로 사용할 소스를 결정합니다. 숫자가 낮을수록 우선순위가 높습니다.

사용 사례: 운영 데이터베이스(priority 1)와 개발 sandbox(priority 2)를 모두 구성할 수 있습니다. 연구자는 기본적으로 운영 데이터베이스를 보지만, 운영 결과에 영향을 주지 않고 새 코호트 정의를 테스트할 때 sandbox로 전환할 수 있습니다.

소스	CDM 우선순위	Vocabulary 우선순위	Results 우선순위
Production Claims	1	1	1
Development Sandbox	2	2	2
Eunomia Demo	3	3	3

연결 상태

데이터 소스 목록은 각 소스에 대해 실시간 연결 표시기를 보여 줍니다:

표시기	의미
녹색 점	최근 5분 안에 연결 테스트 성공
노란색 점	마지막 성공 테스트가 5분보다 오래됨
빨간색 점	가장 최근 연결 시도 실패

연결 테스트

소스 상세 페이지에서 Test Connection을 클릭하면 즉시 연결 검사를 강제로 실행합니다. 테스트는 다음을 확인합니다:

1. 데이터베이스 host 및 port에 대한 TCP 연결.
2. 제공된 자격 증명으로 인증.
3. CDM daimon 스키마 접근.
4. CDM 스키마에 person 테이블 존재 여부(기본 CDM 검증).
5. vocabulary daimon 스키마 접근 및 concept 테이블 존재 여부.

어떤 단계가 실패하면 해당 실패 지점을 나타내는 상세 오류 메시지가 표시됩니다.

방화벽 및 네트워크 구성

Parthenon이 Docker에서 실행 중이라면 데이터베이스 host가 Docker 네트워크 내부에서 도달 가능한지 확인하세요. host로 localhost 또는 127.0.0.1을 사용하면 호스트 머신이 아니라 Docker 컨테이너 자체에 연결하려고 시도합니다. macOS/Windows에서는 보통 host.docker.internal, Linux에서는 실제 서버 IP 또는 적절한 hostname을 사용하세요.

다중 소스 아키텍처

Parthenon은 다중 소스 연구 환경을 위해 설계되었습니다. 원하는 수의 데이터 소스를 구성할 수 있으며, 대부분의 플랫폼 기능에는 소스 간 전환을 위한 소스 선택기가 포함됩니다:

• Vocabulary Browser: 개념 검색 결과는 선택된 소스의 vocabulary daimon에서 나옵니다. 소스마다 다른 용어 버전을 가질 수 있습니다.
• Cohort Generation: 코호트를 생성할 때 실행할 소스를 선택합니다. 같은 코호트 정의를 여러 소스에서 생성해 네트워크 연구에 사용할 수 있습니다.
• Data Explorer: Achilles 대시보드와 DQD 보고서는 소스별입니다. 상단 드롭다운으로 소스를 전환할 수 있습니다.
• Analyses: 각 분석 구성은 대상 소스를 지정합니다. Evidence Synthesis 같은 다중 데이터베이스 분석은 여러 소스의 결과를 집계할 수 있습니다.

소스 간 고려 사항

용어 일관성

신뢰할 수 있는 소스 간 비교를 위해 모든 소스가 같은 용어 버전을 사용하도록 하세요. 용어 버전 v5.0 2025-01-01에 대해 해결된 개념 세트는 새 개념, 폐기된 용어, 재분류된 도메인 때문에 v5.0 2025-06-01에 대해 약간 다른 concept ID 목록을 만들 수 있습니다. 각 소스의 용어 버전은 소스 상세 보기와 Vocabulary Browser 헤더에 표시됩니다.

Eunomia 데모 데이터셋

Parthenon은 OHDSI Eunomia 데이터셋을 기본 지원합니다. Eunomia는 테스트와 데모를 위해 설계된 2,694명 규모의 합성 GiBleed(위장관 출혈) 코호트입니다. Eunomia는 다음을 포함하는 완전하고 자체 완결적인 OMOP CDM v5.4 데이터베이스를 제공합니다:

• 인구통계 및 임상 데이터를 가진 2,694명의 합성 환자.
• 20개 CDM 테이블에 걸친 343,000개 이상의 임상 이벤트 행.
• 포함된 임상 데이터에 충분한 OMOP 용어 하위 집합(444개 개념, 480개 관계).
• Data Explorer 대시보드용 사전 계산 Achilles 결과.

Eunomia 설정

관리자는 두 개의 Artisan 명령으로 Eunomia 데이터셋을 로드할 수 있습니다:

# Eunomia CDM 데이터를 eunomia 스키마에 로드
php artisan parthenon:load-eunomia --fresh

# 올바른 daimon 구성으로 Eunomia 데이터 소스 생성
php artisan eunomia:seed-source

--fresh 플래그는 로드 전에 Eunomia 스키마를 삭제하고 다시 만듭니다. eunomia:seed-source 명령은 eunomia 및 eunomia_results 스키마를 가리키는 daimons를 가진 "OHDSI Eunomia"라는 소스를 생성합니다.

교육과 데모에 적합

Eunomia는 실제 환자 데이터에 접근하지 않고 플랫폼을 배워야 하는 신규 연구자 온보딩에 이상적입니다. GI bleed 이벤트, 관련 약물, 검사 값 같은 현실적인 임상 시나리오를 제공하며 용어 탐색, 코호트 작성, 특성화, 발생률 계산 등 모든 플랫폼 기능과 함께 작동합니다.

데이터 소스 문제 해결

연결 거부

• 데이터베이스 host가 Parthenon 서버 또는 Docker 컨테이너에서 도달 가능한지 확인하세요.
• PostgreSQL이 지정된 port에서 수신 중인지 확인하세요.
• 데이터베이스 방화벽 규칙이 Parthenon 서버 IP의 인바운드 연결을 허용하는지 확인하세요.

인증 실패

• username과 password를 다시 확인하세요.
• 데이터베이스 사용자가 대상 데이터베이스에 CONNECT 권한을 가지고 있는지 확인하세요.
• 비밀번호 만료 또는 계정 잠금 정책을 확인하세요.

스키마를 찾을 수 없음

• 스키마 이름이 정확히 일치하는지 확인하세요. PostgreSQL 스키마 이름은 따옴표로 감싸면 대소문자를 구분합니다.
• 데이터베이스 사용자가 해당 스키마에 USAGE 권한을 가지고 있는지 확인하세요.
• psql에서 \dn을 실행해 사용 가능한 스키마를 나열하세요.

CDM 테이블 누락

• 연결 테스트는 CDM 스키마의 person과 vocabulary 스키마의 concept을 기대합니다.
• ETL이 완료되어 필요한 테이블이 채워졌는지 확인하세요.
• 스키마 search path가 올바르게 해석되는지 확인하세요: SHOW search_path;

Achilles 결과가 표시되지 않음

• results daimon이 올바른 스키마를 가리키는지 확인하세요.
• Achilles가 이 소스에 대해 실행되었는지 확인하세요. achilles_results의 행을 확인합니다.
• Data Explorer는 대시보드 렌더링을 위해 최소한 핵심 분석(analysis IDs 1-5, 101-120)이 필요합니다.

다음 단계

데이터 소스를 구성하고 연결했으면 임상 용어를 탐색할 준비가 된 것입니다. 3장: Vocabulary Browser로 진행해 OMOP 개념 검색, 계층 탐색, 모든 코호트 정의와 분석의 기반이 되는 용어 이해 방법을 알아보세요.