OBO 파일과 OLS4의 온톨로지 용어 레이블

v2.13.0에서 추가

radio, multiselect, span, image_annotation 스킴의 label_source 블록은 온톨로지에 대한 검색 상자를 추가합니다. 주석자는 고정된 레이블 목록을 스크롤하는 대신 이름, 동의어, ID를 입력하고 용어를 고릅니다. 선택한 각 용어는 용어의 ID, 이름, IRI, 용어가 나온 온톨로지 릴리스와 함께 저장됩니다. 바이오큐레이터는 이 기능을 Cell Ontology를 쓰는 세포 유형 주석, Human Phenotype Ontology(HPO)를 쓰는 표현형 주석, MONDO를 쓰는 질병 정규화, 그리고 ChEBI 용어를 쓰는 화학물질 언급 태깅, UBERON 용어를 쓰는 슬라이드의 조직 영역, GO 용어를 쓰는 유전자 산물에 사용합니다. Potato의 합의도 지표와 내보내기는 용어 ID를 읽습니다. "B cell"을 검색한 주석자와 ID CL:0000236을 입력한 주석자는 두 답이 같은 ID를 저장하므로 일치합니다.

OBO 플랫 파일 형식은 OBO Foundry 온톨로지의 일반 텍스트 릴리스 형식입니다. Potato는 OBO 1.4를 읽습니다. Ontology Lookup Service(OLS4)는 EMBL-EBI의 생의학 온톨로지 검색 서비스이자 API이며, 조직이 자체 OLS4 서버를 운영할 수도 있습니다.

• 로컬 파일: service: file이면 Potato는 작업 디렉터리 안의 OBO 1.4 파일을 검색합니다. 파일 소스는 오프라인에서 작동합니다.
• OLS4: service: ols4이면 Potato는 OLS4 서버를 검색합니다. 모든 검색은 입력한 텍스트를 그 서버로 보내며, 스킴이 allow_network: true를 설정하지 않으면 Potato는 시작을 거부합니다. 요청은 Potato 서버가 보내며 주석자의 브라우저는 Potato와만 통신합니다.
• 저장되는 레코드: 선택한 각 용어는 {obo_id, label, iri, ontology_version}으로 저장됩니다. Potato의 합의도 지표는 obo_id를 비교합니다.
• 내보내기: --format ontology_terms를 쓴 python -m potato.export는 선택한 용어마다 한 행을 씁니다.
• 추가 설치 없음: Potato는 자체 리더로 OBO를 파싱하며, OLS4 호출은 Potato가 이미 의존하는 requests 패키지를 사용합니다.

설정

아래 설정은 Potato 예제의 합성 샘플 온톨로지 위에서 스킴 세 개를 구성합니다. 첫 번째 스킴은 검색 상자만으로 주요 세포 유형 하나를 묻고, 두 번째 스킴은 검색 상자 위에 고정된 None 선택지를 제공하며, 세 번째 스킴은 텍스트 스팬에 면역 세포 용어만으로 태그를 붙입니다.

annotation_task_name: "Cell types from an ontology"
task_dir: .
output_annotation_dir: annotation_output
data_files: [data/cell-descriptions.jsonl]
item_properties: {id_key: id, text_key: text}
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: radio
    name: main_cell_type
    description: "Which cell type does the description mainly talk about?"
    labels: []                  # search box only
    label_requirement: {required: true}
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
 
  - annotation_type: multiselect
    name: other_cell_types
    description: "Which other cell types are mentioned?"
    labels: [None]              # a fixed option above the search box
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
 
  - annotation_type: span
    name: immune_cell_mentions
    description: "Highlight each immune cell mention and tag its type"
    labels: []
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
      root: SCL:0000001         # immune cell and its is_a descendants

labels: []이거나 labels 키가 없으면 검색 상자가 답할 수 있는 유일한 방법입니다. 목록이 있으면 고정된 레이블이 평소처럼 표시되고 검색 상자는 고정된 레이블 아래에 놓입니다. 고정된 레이블은 일반 레이블 이름으로 저장되며, 검색에서 선택한 용어만 온톨로지 용어로 저장됩니다. 첫 번째 스킴은 required를 설정하므로 Potato는 주석자가 용어를 고를 때까지 다음 버튼을 막아 둡니다. 세 번째 스킴에서는 Potato가 검색을 root인 면역 세포 용어와 그 아래의 모든 is_a 용어로 제한합니다. 뉴런 용어는 스팬 검색에 나타나지 않습니다.

Potato는 온톨로지 파일을 포함해 배포하지 않습니다. 필요한 .obo 릴리스를 작업 디렉터리에 내려받고 파일을 프로젝트와 함께 보관하세요. HPO 릴리스는 http://purl.obolibrary.org/obo/hp.obo이고 Cell Ontology 릴리스는 http://purl.obolibrary.org/obo/cl.obo입니다. 예제의 scl-sample.obo는 현재 용어 19개, 폐기된 용어 하나, 접두사 SCL을 가진 가상의 온톨로지입니다. SCL ID는 Cell Ontology의 ID가 아닙니다.

이미지 주석 스킴에서는 같은 블록이 그리기 도구 옆에 놓입니다. 아래의 부분 블록은 위 설정에 네 번째 스킴을 추가합니다.

  - annotation_type: image_annotation
    name: cells_in_image
    description: "Box each cell and name its type"
    tools: [bbox, polygon]
    labels: []
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo

파일 대신 OLS4 검색하기

아래의 부분 블록은 위 설정의 annotation_schemes를 EBI의 OLS4 서버에서 Cell Ontology를 검색하는 스킴 하나로 대체합니다. ontology 값은 cl, hp, go, mondo, chebi, uberon 같은 OLS4 온톨로지 ID입니다.

annotation_schemes:
  - annotation_type: radio
    name: cell_type
    description: "Which cell type is described?"
    labels: []
    label_source:
      ontology: cl
      service: ols4
      allow_network: true       # required for ols4
      root: CL:0000000          # optional, sent to OLS4 as childrenOf
      timeout_s: 5

자체 호스팅한 OLS4 서버를 검색하려면 base_url을 설정하세요. allow_network 키는 의도적인 옵트인입니다. 검색 텍스트가 사내 네트워크에 머물러야 하는 연구는 service: file을 사용합니다. OLS4 블록에 allow_network: true가 없으면 Potato는 시작을 거부합니다.

옵션

label_source가 받는 모든 키입니다.

다음 조건 중 하나라도 성립하면 서버와 python -m potato.validate_cli는 설정을 거부하고 문제가 되는 키를 밝힙니다.

• label_source가 radio, multiselect, span, image_annotation 이외의 스킴 유형에 있습니다.
• service가 file 또는 ols4가 아니거나, 키가 다른 서비스에 속합니다(file과 함께 쓴 base_url).
• 키를 알 수 없습니다.
• 파일이 없거나, task_dir 밖에 있거나, max_file_mb보다 크거나, OWL 파일이거나, 용어가 없습니다.
• root가 파일의 용어가 아니거나 폐기로 표시되어 있습니다.
• service: ols4가 allow_network: true 없이 설정되어 있습니다.

OBO 파일 파싱

Potato는 data-version, ontology, default-namespace 헤더 태그를 읽습니다. 각 [Term] 스탠자에서 리더는 id, name, namespace, synonym, def, is_a, alt_id, is_obsolete와, 오래된 파일에 있는 exact_synonym 같은 OBO 1.0 동의어 태그를 가져옵니다. [Typedef] 스탠자는 건너뛰며, relationship:과 intersection_of: 줄은 엣지가 아닙니다. 따라서 Potato는 is_a만으로 root 하위 트리를 만듭니다. 예를 들어 UBERON 하위 트리는 루트의 하위 클래스를 가지며, 루트와 part_of로만 연결된 구조는 가지지 않습니다.

저장되는 ontology_version은 샘플의 scl/releases/2026-10-01처럼 파일의 data-version 헤더입니다. 헤더가 없는 파일은 sha256:에 파일 해시의 처음 16진수 12자리를 붙인 값을 받습니다. 파일은 한 번 파싱되어 메모리에 보관되며, 파일의 크기나 수정 시각이 바뀌면 Potato가 다시 파싱합니다. 이전 파일 위에 복사한 새 릴리스는 재시작 없이 다음 검색부터 적용됩니다.

폐기된 용어는 검색과 모든 하위 트리에서 제외되며, Potato는 replaced_by 태그를 따라 새 용어로 가지 않습니다. alt_id 검색은 주 용어를 찾고 Potato는 주 ID를 저장합니다. OWL 파일은 메시지와 함께 거부됩니다. 대부분의 OBO Foundry 온톨로지는 .owl 파일 옆에 .obo 릴리스를 게시합니다. .obo 릴리스를 내려받거나 ROBOT으로 OWL 파일을 변환하세요.

robot convert --input cl.owl --output cl.obo

NCBITaxon 같은 큰 온톨로지에는 슬림 또는 부분 집합 파일을 사용하거나, max_file_mb를 높이거나, OLS4로 온톨로지를 검색하세요.

용어 검색과 선택

주석자는 이름, 동의어, 용어 ID의 두 글자 이상을 입력합니다. 파일 검색은 용어 ID(CL:0000236, CL_0000236, alt_id, 전체 PURL)를 가장 먼저 순위에 올리고, 이어서 정확히 일치하는 이름, 입력한 텍스트로 시작하는 이름, 입력한 각 단어로 단어가 시작하는 이름 순으로 올립니다. 동의어도 같은 세 방식으로 일치시키며, 그다음에 이름의 어느 곳에서든 발견된 텍스트, 이어서 동의어의 어느 곳에서든 발견된 텍스트가 옵니다. 모든 동의어 범위(EXACT, BROAD, NARROW, RELATED)가 계산되며, 동의어로 찾은 일치 항목은 용어 이름 아래에 그 동의어를 표시합니다. 결과에는 용어 ID와 정의의 처음 240자도 표시됩니다. 샘플 온톨로지에서 white blood를 입력하면 동의어 "white blood cell"로 leukocyte를 찾고, SCL:0000099를 입력하면 용어의 alt_id로 T cell을 찾습니다.

일치하는 용어가 max_results보다 많으면 상태 줄이 표시된 개수와 전체 개수를 알려 주고 주석자에게 더 입력하라고 요청합니다. 상자 아래의 줄은 소스를 밝힙니다. 이 줄은 파일 소스에서는 온톨로지와 파일의 버전을, OLS4 소스에서는 온톨로지 이름 뒤에 "via OLS4"를 표시합니다.

• 키보드: 위와 아래 키는 일치 항목 사이를 이동하고, Enter는 강조된 항목을 선택하고, Escape는 목록을 닫으며, 두 번째 Escape는 상자를 지웁니다. 일치 항목을 클릭하거나 탭해도 선택되며, 각 일치 항목은 높이가 44픽셀 이상인 탭 대상입니다.
• radio: 선택한 용어는 선택된 옵션으로 나타나며, 다른 용어를 선택하면 이전 용어가 대체됩니다.
• multiselect: 선택한 각 용어는 체크된 체크박스로 나타나며, 체크를 해제하면 용어가 제거됩니다.
• span: 선택한 용어가 활성 스팬 레이블이 되고, 주석자는 이어서 텍스트를 강조합니다. 강조 위의 칩은 용어 이름을 보여 줍니다.
• image_annotation: 선택한 용어가 레이블 버튼이자 활성 레이블이 되고, 주석자는 이어서 그립니다. 이미지에서 이미 사용한 용어는 페이지를 불러올 때 버튼으로 나타납니다.

포켓 모드는 검색 상자를 보여 주지 않습니다. 따라서 label_source 스킴이 있는 과제는 항상 일반 주석 페이지를 사용합니다. 일반 페이지는 휴대폰에서도 작동합니다.

네트워크 접근과 OLS4 캐싱

Potato는 service: file 스킴에 대해 어느 시점에도 네트워크 요청을 하지 않습니다. .obo 파일이 작업 디렉터리에 있으면 파일 소스는 에어갭 배포에서 실행됩니다. 검색은 Potato 서버의 파싱된 파일에 대해 실행됩니다. allow_network: true가 없는 OLS4 스킴은 서버가 그 설정으로 시작을 거부하고 대신 로컬 파일을 제안하므로 네트워크에 도달할 수 없습니다.

service: ols4와 allow_network: true이면 Potato 서버는 각 검색을 obsoletes=false로 OLS4에 보냅니다. 그러면 OLS4는 결과에서 폐기된 용어를 제외합니다. 검색 응답은 서버 메모리에 6시간 동안, 서로 다른 검색 최대 512개까지 캐시되며, 온톨로지의 릴리스 문자열도 6시간 동안 캐시됩니다. 브라우저는 응답을 5분 동안 재사용할 수 있습니다. OLS4가 반환하는 모든 용어는 <output_annotation_dir>/ontology_cache/<ontology>-ols4-terms.json에도 기록됩니다. 새로 고친 뒤 Potato는 스팬 칩과 이미지 레이블 버튼의 용어 이름을 그 파일에서 읽으며, 내보내기도 같은 파일을 읽습니다.

OLS4가 느리거나 도달할 수 없으면 검색 상자는 "Search failed: OLS4 did not answer within 5 s." 또는 "Search failed: OLS4 request failed"로 시작하는 메시지를 표시하며, 주석자는 여전히 고정된 레이블에 답할 수 있습니다. 이전 6시간 안에 응답된 검색은 캐시에서 제공됩니다. 이미 선택한 용어는 저장된 상태로 남습니다. radio 또는 multiselect 답이 전체 레코드를 담고 있고 스팬과 이미지 답은 디스크의 용어 파일로 해석되기 때문입니다. Potato가 OLS4에서 온톨로지의 릴리스를 읽을 수 없으면 선택은 다음 릴리스 조회(최대 6시간 뒤)까지 빈 ontology_version으로 저장됩니다. 네트워크 장애 중에도 실행되어야 하는 연구는 .obo 파일을 내려받아 service: file로 전환하세요.

저장되는 답

선택한 용어는 아래 레코드로 저장됩니다.

{"obo_id": "SCL:0000005", "label": "CD4-positive T cell",
 "iri": "http://purl.obolibrary.org/obo/SCL_0000005",
 "ontology_version": "scl/releases/2026-10-01"}

파일 소스에서 iri는 ID로 만든 OBO PURL이고, OLS4에서는 iri가 OLS4가 반환하는 IRI입니다. radio 또는 multiselect 답은 선택한 시점의 ontology_version을 유지합니다. .obo 파일이 교체된 뒤에도 답은 주석자가 검색한 릴리스를 가리킵니다.

스팬과 도형은 ID만 저장합니다. 내보내기는 service: file에서는 .obo 파일에서, service: ols4에서는 ontology_cache의 OLS4 용어 파일에서 이름, IRI, 버전을 찾습니다. 파일 모드의 스팬과 도형에 대해서는 내보내기가 내보낼 때의 .obo 파일 버전을 씁니다.

내보내기

ontology_terms 형식은 선택한 용어마다 한 행으로 ontology_terms.csv와 ontology_terms.jsonl을 씁니다.

python -m potato.export --config config.yaml --format ontology_terms --output out/

위 설정의 첫 항목에서 주석자 한 명에 대한 ontology_terms.csv는 다음과 같습니다.

user_id,instance_id,schema,annotation_type,ontology,obo_id,label,iri,ontology_version,start,end,text,shape_index,shape_type,known
ana,cells_01,main_cell_type,radio,scl,SCL:0000005,CD4-positive T cell,http://purl.obolibrary.org/obo/SCL_0000005,scl/releases/2026-10-01,,,,,,true
ana,cells_01,other_cell_types,multiselect,scl,SCL:0000011,macrophage,http://purl.obolibrary.org/obo/SCL_0000011,scl/releases/2026-10-01,,,,,,true
ana,cells_01,immune_cell_mentions,span,scl,SCL:0000011,macrophage,http://purl.obolibrary.org/obo/SCL_0000011,scl/releases/2026-10-01,128,150,large phagocytic cells,,,true

start, end, text 열은 스팬에, shape_index와 shape_type은 이미지 도형에 채워집니다. known 열은 ID가 현재 파일 또는 OLS4 용어 파일에 없으면 false입니다. 더 새로운 릴리스가 제거했거나 폐기한 용어는 false를 받습니다. 내보내기는 그런 행의 개수와 함께 경고를 출력합니다. 같은 스킴의 고정된 레이블은 ontology_terms의 행이 아닙니다. 일반 csv 내보내기는 radio 또는 multiselect 용어를 JSON 레코드를 담은 <schema>.<obo_id>라는 열로 쓰며, 스팬과 도형은 obo_id를 레이블로 유지합니다. 다른 형식은 내보내기 형식을 참고하세요.

일치도

Potato의 일치도 지표는 obo_id를 비교합니다. radio 스킴은 명목 레이블로 채점하고(일치율, Cohen의 카파, Fleiss의 카파, Krippendorff의 알파), multiselect 스킴은 용어 ID 집합에 대한 Jaccard 겹침과 MASI 가중 알파로, span 스킴은 스팬 위치와 obo_id로, image_annotation 스킴은 각 도형의 기하와 용어 ID로 채점합니다. 같은 용어를 고른 두 주석자는 레코드의 ontology_version 값이 달라도 일치합니다. 부모 용어와 자식 용어는 서로 다른 레이블로 취급하며, 일치도 코드는 온톨로지 계층을 따른 부분 점수를 주지 않습니다. 예를 들어 T cell과 CD4-positive T cell은 불일치로 채점됩니다. 계층을 인식하는 비교에는 ontology_terms를 내보내고 같은 .obo 릴리스에 대해 obo_id 열에서 측정값을 계산하세요.

예제

python potato/flask_server.py start examples/classification/ontology-labels/config.yaml -p 8000

이 예제에는 짧은 세포 설명 네 개, 합성 scl-sample.obo 온톨로지, 위 설정의 스킴 세 개가 있습니다.

더 읽을거리

• 생명과학 - 바이오큐레이션과 생명과학 주석을 위한 Potato
• 의료 - 임상 및 생의학 주석을 위한 Potato
• 엔티티 링킹 - 스팬 레이블이 고정된 범주로 남는, 언급을 지식 베이스 항목에 연결하기
• 라디오 및 다중 선택 - label_source를 받는 단일 선택 및 다중 선택 스킴
• 내보내기 형식 - Potato의 내보내기 형식과 내보내기 명령

구현 세부 사항은 소스 문서를 참고하세요.