화학 구조 주석과 OCSR 교정

v2.13.0에서 추가

chemical_structure 주석 스킴은 주석자에게 구조 편집기를 제공하고, molecule 디스플레이는 주석자가 원자를 선택할 수 있는 작은 분자를 그립니다. 화학 데이터셋 구축자는 이 둘을 구조 교정에 사용합니다. 구조 교정에서 주석자는 특허나 논문의 그림에서 인식된 구조를 그림과 비교하고 잘못 읽힌 원자와 결합을 고칩니다. 화학 교육 연구자와 교수자는 이 편집기로 학생이 그린 구조(예를 들어 화합물 이름이 설명하는 구조)를 수집합니다. Potato는 서버에서 각 그림을 정답 키와 대조해 채점합니다. 큐레이터는 반응 중심이나 대사 부위처럼 원자를 표시할 때 viewer_selection 스킴과 함께 molecule 디스플레이를 사용합니다. 각 답은 그림의 표준 SMILES와 함께 molfile로 저장되며, chemistry 내보내기는 모든 주석자의 구조를 CSV 파일과 SD 파일로 씁니다.

광학 화학 구조 인식(OCSR)은 화학 구조의 이미지를 기계가 읽을 수 있는 구조로 바꿉니다. Potato는 OCSR 모델을 실행하지 않으며, 다른 도구가 만든 인식된 구조를 불러옵니다. SMILES는 아세트산을 CC(=O)O로 쓰는 것처럼 구조를 짧은 한 줄 텍스트로 씁니다. MDL molfile은 화학 표 파일 계열의 연결표 텍스트 형식이며, SD 파일은 각 molfile 뒤에 이름 붙은 데이터 필드가 있는 molfile을 여러 개 담습니다. InChIKey는 IUPAC InChI 식별자의 27자 해시이며, 같은 구조를 그린 두 그림은 같은 InChIKey를 줍니다.

OCSR 결과를 원본 그림과 대조해 확인합니다

• 편집기: Potato 저장소는 편집기로 OpenChemLib JS 9.25.0(BSD-3-Clause)을 포함합니다. 편집기는 결합, 고리, 원소, 전하, 입체 쐐기, 지우개, 실행 취소 도구 모음이 있는 캔버스에 그립니다. 캔버스 아래의 텍스트 상자는 입력하거나 붙여넣은 SMILES 문자열 또는 molfile을 받으며, 이 텍스트 상자가 편집기로 들어가는 키보드 경로입니다.
• RDKit.js(선택): RDKit JavaScript MinimalLib 2026.3.6(BSD-3-Clause)은 7 MB의 WebAssembly 빌드이며 커밋되어 있지 않습니다. potato vendor fetch rdkit는 빌드를 내려받아 npm 레지스트리의 무결성 해시와 대조합니다. RDKit.js가 있으면 브라우저가 RDKit 표준 SMILES, InChI, InChIKey도 계산하고 RDKit이 정제할 수 없는 구조에 표시를 붙입니다. 그러면 molecule 디스플레이는 engine: rdkit으로 그릴 수 있습니다.
• chemistry 엑스트라(선택): 이 엑스트라는 서버에 rdkit Python 패키지를 설치합니다. 이 패키지가 정답 키를 채점하고, chemistry 내보내기는 RDKit.js 없이 저장된 답의 InChI와 InChIKey를 이 패키지로 채웁니다.
• WebGL 없음: 두 툴킷 모두 2D로 그립니다.
• 오프라인: 구조는 항목 또는 미디어 디렉터리의 파일에서 오며, 정답 키는 브라우저에 도달하지 않습니다.

설치마다 사용할 수 있는 기능은 다음과 같습니다.

서버 측 채점에는 엑스트라가 필요하고 RDKit.js는 별도로 가져옵니다.

pip install 'potato-annotation[chemistry]'
potato vendor fetch rdkit     # optional, InChIKeys in the browser

가져온 뒤 서버를 재시작하세요. RDKit.js가 없는 동안 potato validate는 rdkit: auto로 둔 각 chemical_structure 스킴에 경고하고 가져오기 명령을 알려 줍니다.

설정

아래 설정은 OCSR 교정을 구성합니다. 각 항목은 원본 그림을 인식된 구조 옆에 보여 주며, 주석자는 인식기가 잘못 읽은 원자를 표시하고, 편집기에서 구조를 고치고, 판정을 내립니다.

annotation_task_name: "Structure recognition check"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/structures.json]
item_properties: {id_key: id, text_key: note}
 
instance_display:
  layout:
    direction: horizontal
  fields:
    - key: page_image             # the figure cropped from the patent or paper
      type: image
      label: "Source image"
    - key: ocsr_smiles            # what the OCSR tool produced
      type: molecule
      label: "Recognized structure"
      display_options:
        height: 300
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: viewer_selection
    name: wrong_atoms
    description: "Mark the atoms the recognizer got wrong"
    viewer_field: ocsr_smiles
    labels: ["wrong element", "wrong bond or charge", "wrong stereo"]
 
  - annotation_type: chemical_structure
    name: corrected
    description: "Correct the structure so it matches the source image"
    prefill_field: ocsr_smiles
    answer_field: true_smiles     # graded in the export, never sent to the page
    label_requirement: {required: true}
 
  - annotation_type: radio
    name: verdict
    description: "How good was the recognition?"
    labels: ["Correct", "Minor errors", "Wrong structure"]
    label_requirement: {required: true}

편집기는 ocsr_smiles에서 시작합니다. 미리 채워진 구조를 주석자가 그대로 두면 changed: false인 저장된 답이 됩니다. 따라서 올바른 인식은 수정이 필요 없습니다. verdict 문항은 승인된 구조와 주석자가 확인하지 않은 항목을 구별합니다. Potato는 페이지가 받는 모든 데이터에서 true_smiles 필드를 제거합니다. 내보내기에서 answer_correct는 교정된 각 구조가 true_smiles와 일치하는지 알려 줍니다. answer_correct를 changed와 비교하면 놓친 오류(변경되지 않았고 틀림)와 새로 만든 오류(변경되었고 틀림)를 구별할 수 있습니다.

각 항목은 media_directory 기준으로 그림의 이름을 지정하고 두 구조를 제공합니다.

{"id": "fig1_aspirin", "note": "Compound 1 as printed.", "page_image": "fig1_aspirin.png",
 "ocsr_smiles": "CC(=O)Oc1ccccc1C(=O)N", "true_smiles": "CC(=O)Oc1ccccc1C(=O)O"}

이름에서 구조 그리기

이름-구조 연습에는 스킴 하나와 항목마다 정답 키가 필요합니다. 아래 설정은 화합물 이름을 항목 텍스트로 보여 줍니다.

annotation_task_name: "Name to structure"
task_dir: .
output_annotation_dir: annotation_output
data_files: [data/names.json]
item_properties: {id_key: id, text_key: name}
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: chemical_structure
    name: drawn
    description: "Draw the structure this name describes"
    answer_field: expected
    rdkit: false                  # OpenChemLib only, no RDKit.js warning
    editor_height: 420
    label_requirement: {required: true}

{"id": "q2", "name": "(S)-2-aminopropanoic acid", "expected": "C[C@H](N)C(=O)O"}

학생은 마우스로 그리거나 SMILES 문자열을 입력하고 Enter를 누를 수 있습니다. rdkit: false이면 페이지는 OpenChemLib만 불러오고 InChIKey를 저장하지 않습니다. chemistry 엑스트라가 내보낼 때 그림을 채점합니다.

분자에 원자 표시하기

원자 표시는 molecule 디스플레이와 viewer_selection 스킴을 짝짓습니다. 아래 설정은 큐레이터에게 대사 부위를 표시하게 하고, 참고용으로 모델이 예측한 부위를 호박색으로 그립니다.

annotation_task_name: "Sites of metabolism"
task_dir: .
output_annotation_dir: annotation_output
data_files: [data/molecules.json]
item_properties: {id_key: id, text_key: note}
 
instance_display:
  fields:
    - key: smiles
      type: molecule
      display_options:
        show_atom_numbers: true
        highlight_field: predicted_site   # a model's predicted atoms, drawn in amber
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: viewer_selection
    name: som
    description: "Mark each atom where the compound is metabolized"
    viewer_field: smiles
    labels: ["hydroxylation", "N-dealkylation", "glucuronidation"]
    min_selections: 1
    label_requirement: {required: true}

{"id": "m1", "note": "Predicted sites in amber.", "smiles": "CC(=O)Nc1ccc(O)cc1", "predicted_site": [0, 8]}

highlight_field가 지정하는 항목 필드는 0부터 시작하는 원자 인덱스를 목록 또는 "0, 8" 같은 텍스트로 담습니다. 강조 표시는 고정되어 있으며, 큐레이터는 강조 표시와 무관하게 원자를 선택합니다. min_selections와 label_requirement를 함께 쓰면 큐레이터가 원자를 하나 이상 선택할 때까지 다음 버튼이 막혀 있습니다.

구조 데이터

구조 필드는 SMILES 문자열, molfile 텍스트, 또는 미디어 디렉터리에 있는 .mol, .sdf, .smi, .smiles 파일의 이름을 담습니다. 서버는 .sdf 파일의 첫 레코드와 .smi 파일의 비어 있지 않은 첫 줄의 첫 토큰을 읽습니다. 구조 텍스트와 구조 파일은 1 MB로 제한됩니다. SMILES 문자열에는 공백이 없으므로 공백이 있으면서 molfile이 아닌 값은 거부됩니다. 디스플레이는 URL을 가져오지 않으며, Potato는 미디어 디렉터리 밖의 파일 경로를 거부합니다.

옵션

정답 키

정답 키는 SMILES 문자열 하나, molfile, 또는 매핑입니다. 매핑의 모든 부분이 통과해야 합니다.

정확 모드는 표준 InChIKey를 비교합니다. 표준 InChI는 일부 호변이성질체를 하나의 구조로 취급합니다. 따라서 2-피리돈을 그린 그림은 2-하이드록시피리딘 키에 대해 통과합니다. 전하는 계산에 포함되며, 에톡시드는 ignore_stereo가 있어도 에탄올에 대해 실패합니다. 부분 구조 키는 카르복실산에 대한 {"substructure": "C(=O)[OH]"}처럼 답의 특징을 채점합니다.

answer_field 값은 SMILES 문자열 하나일 수 있습니다. 골드 스탠다드 항목과 훈련 항목에는 스킴 이름 아래에 매핑 형태로 씁니다.

{"id": "gold_1", "gold_label": {"corrected": {"smiles": "CC(=O)Oc1ccccc1C(=O)O"}}}
{"id": "train_1", "correct_answers": {"drawn": {"substructure": "C(=O)[OH]"}}}

품질 관리와 훈련 단계는 내보내기와 같은 비교로 이 키를 채점합니다. 편집기는 주석 단계에서만 prefill_field를 읽습니다. 따라서 훈련 항목은 빈 캔버스로 열립니다.

rdkit Python 패키지가 없으면 smiles, molfile, SMARTS 키는 모든 답을 틀린 것으로 채점하며, 서버는 누락된 패키지를 한 번 기록합니다. 패키지가 없어도 inchikey 키는 주석자의 브라우저에서 RDKit.js가 InChIKey를 계산한 답과는 여전히 일치합니다. 패키지가 설치되어 있으면 서버는 저장된 molfile에서 InChIKey를 다시 계산하고 브라우저의 값은 무시합니다.

구조 그리기와 교정

결합을 추가하려면 주석자는 왼쪽 도구 모음에서 결합 유형, 고리, 원소, 전하를 고른 뒤 캔버스의 빈 곳을 클릭하거나 원자에서 드래그합니다. 원자를 가리킨 채 원소 기호(o, n, s)를 입력하면 원소가 바뀝니다. 텍스트 상자는 SMILES 문자열 또는 molfile을 받으며, Load(SMILES 문자열이면 Enter)가 그림을 대체합니다. OpenChemLib가 읽을 수 없는 텍스트는 거부되고 그림은 유지됩니다. Clear는 캔버스를 비우고, Restore the given structure는 미리 채워진 구조를 되살립니다.

편집기 아래의 SMILES, 분자식, InChIKey는 주석자가 그리는 동안 갱신됩니다. 원자가 문제는 "C (atom 2) has 5 bonds; it allows 4." 형태로 거기에 나열됩니다. require_valid가 있으면 문제가 나열된 동안에는 필수 항목을 제출할 수 없습니다.

원자 선택

주석자는 그림에서 원자를 클릭해 선택하고, 다시 클릭해 선택을 해제합니다. 원자 목록에서는 Tab으로 목록에 들어가고, 화살표 키, Home, End로 원자 사이를 이동하며, Space 또는 Enter로 원자를 전환합니다. labels가 있으면 주석자가 먼저 레이블을 고르고, 나열된 각 원자에는 레이블 메뉴와 Remove 버튼이 있습니다. 페이지는 원자를 원소와 molfile 번호로 부릅니다. 예를 들어 O4는 원본의 네 번째 원자입니다.

저장되는 원자 인덱스는 원본에 쓰인 그대로의 원자의 0부터 시작하는 위치입니다. 원자는 SMILES 문자열 또는 molfile 원자 블록에 나타나는 순서로 셉니다. molfile 원자 번호는 인덱스 더하기 1입니다. 어느 엔진이 분자를 그리든 인덱스는 같은 입력을 removeHs=False로 읽은 RDKit의 원자 인덱스와 같습니다. OpenChemLib는 SMILES 문자열의 명시적 수소([H]C(Cl)(Br)F)를 이웃 원자에 합칩니다. 따라서 engine: openchemlib에서는 그런 SMILES 문자열을 선택에 사용할 수 없습니다. 디스플레이는 그 SMILES 문자열을 선택에 사용할 수 없다고 알리며 원자를 전혀 제공하지 않습니다. 개별 수소를 선택할 수 있어야 하면 molfile 또는 engine: rdkit을 사용하세요. 암묵적 수소(CCO)는 선택할 수 없습니다.

저장되는 답

chemical_structure 스킴은 항목당 JSON 객체 하나를 저장합니다.

{"molfile": "\nOCL MolfileCreator  2D\n\n  0  0  0 ... V3000\n...M  END\n",
 "smiles": "CC(Oc1ccccc1C(O)=O)=O",
 "idcode": "dklB@@QmR[fUxUZBBF@@",
 "formula": "C9H8O4",
 "rdkit_smiles": "CC(=O)Oc1ccccc1C(=O)O",
 "inchi": "InChI=1S/C9H8O4/c1-6(10)13-8-5-3-2-4-7(8)9(11)12/h2-5H,1H3,(H,11,12)",
 "inchikey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
 "changed": true,
 "problems": [],
 "toolkits": {"openchemlib": "9.25.0", "rdkit": "2026.03.6"}}

molfile은 V3000입니다. smiles는 OpenChemLib의 표준 이성질체 SMILES이고 idcode는 OpenChemLib의 표준 ID 코드입니다. rdkit_smiles, inchi, inchikey는 RDKit.js가 실행된 경우에만 있습니다. 표준 SMILES는 툴킷마다 다릅니다. 구조는 InChIKey 또는 ID 코드로 비교하고, smiles와 rdkit_smiles를 서로 비교하지 마세요. changed는 그림이 미리 채워진 구조의 ID 코드를 가지고 있는 동안 false입니다.

molecule 디스플레이의 viewer_selection 스킴은 선택한 원자를 저장합니다.

{"viewer": "molecule", "items": [{"atom": 12, "element": "N", "label": "wrong element"}]}

내보내기

chemistry 내보내기는 chemical_structure 스킴과 molecule 디스플레이에 연결된 viewer_selection 스킴을 다룹니다.

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

identifiers_from은 RDKit.js가 InChI와 InChIKey를 계산했으면 browser, 내보내기가 rdkit Python 패키지로 두 식별자를 모두 계산했으면 server, RDKit.js도 패키지도 없었으면 none입니다. 내보내기는 식별자가 없는 답에 대해 경고를 나열합니다. answer_correct는 answer_field가 있는 스킴에서 1 또는 0이며, answer_reason은 "a different structure (ignoring stereo)"나 "missing the substructure C(=O)[OH]"처럼 채점기의 이유를 줍니다. RDKit의 SDMolSupplier와 다른 SD 리더는 필드를 속성으로 하여 SD 파일을 엽니다.

Potato의 합의도 지표는 chemical_structure나 viewer_selection 스킴을 다루지 않습니다. 첫 번째 설정의 verdict radio 문항은 평소처럼 합의도를 얻습니다. 주석자의 구조를 비교하려면 chemical_structures.csv의 행을 instance_id와 schema로 대응시키고 inchikey를, RDKit이 없었다면 idcode를 비교하세요. 원자 선택에는 molecule_atoms.csv에서 항목별 집합 겹침을 계산합니다(예를 들어 atom 인덱스에 대한 Jaccard).

속성 모델 학습

v2.14.0의 새 기능

분자에 대한 radio, select, likert, slider 문항으로 rdkit-property 모델을 학습시킬 수 있습니다. 모델의 입력은 항목의 텍스트가 아니라 구조입니다. 구조는 항목의 molecule 표시 필드에서 오거나 같은 항목의 chemical_structure 스킴에서 옵니다. 스킴에서는 주석자가 그린 구조를 쓰고, 주석자마다 다르면 가장 많이 나온 그림을 쓰며, 아무도 그리지 않았으면 prefill_field 구조를 씁니다. 각 분자는 Morgan 핑거프린트와 RDKit의 2D 기술자가 되고, 로지스틱 회귀, 릿지 회귀, 랜덤 포레스트 중 하나가 답을 학습합니다. 슬라이더의 예측은 슬라이더의 단계에 맞춰 반올림됩니다. model_training.writeback.schemas가 문항을 지정하면 모델의 답이 사전 레이블로 문항에 되돌아갑니다. 학습에는 chemistry 추가 패키지가 필요합니다. 과학 모델에서 실행 과정을 단계별로 보여 줍니다.

예제

python potato/flask_server.py start examples/advanced/chemical-structure-correction/config.yaml -p 8000

이 예제에는 흔한 의약품의 구조 이미지 다섯 장과 각 이미지에 대해 인식된 SMILES 문자열이 있습니다. 인식된 문자열 중 네 개는 잘못된 헤테로 원자나 뒤집힌 입체 중심 같은 전형적인 인식 오류를 담도록 손으로 편집했습니다. 같은 디렉터리의 generate_images.py가 실제 SMILES에서 이미지를 그립니다.

코딩 에이전트로 연구 설정하기

potato-skill 1.2.0은 Potato 2.13.1을 대상으로 하며 chemical_structure와 molecule을 이름으로 압니다. 이 스킬은 연구 설계 측면을 안내합니다. 주석자에게 무엇을 물을지, 구조당 몇 명의 주석자가 확인할지, 훈련과 주의 점검, 내보내기가 여기에 포함됩니다. 이 스킬은 아직 구조 데이터 형식, 정답 키 모드, 디스플레이 옵션, chemistry 엑스트라를 문서화하지 않습니다. potato-skill을 설치하고 에이전트에게 연구를 설명한 뒤, 형식과 옵션은 이 페이지의 Markdown 사본을 가리켜 알려 주세요. Markdown 사본은 https://www.potatoannotator.com/docs/annotation-types/chemical-structures.md에 있습니다.

더 읽을거리

• 단백질 구조 - 같은 viewer_selection 스킴을 쓰는 잔기 선택
• 인스턴스 표시 - 디스플레이 필드를 설정하는 방법
• 품질 관리 - 골드 스탠다드 항목과 주의 점검
• 내보내기 형식 - Potato의 내보내기 형식과 내보내기 명령
• 과학 모델 - 분자에 대한 문항으로 rdkit-property 모델 학습시키기
• 생명과학 - 생명과학과 바이오큐레이션을 위한 Potato

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