croissant에 의미 추가하기
RoboCroissant 파일은 지식 베이스가 어떤 파일을 가지고 있고 각 파일에 어떤 열이 있는지 알려줍니다. 이 스킬은 데이터가 의미하는 것을 추가합니다: 어떤 열이 함께 유전자 또는 질병을 설명하는지, 행이 무엇을 주장하는지, 열의 ID가 어떤 식별자 접두사를 사용하는지, 코드가 무엇을 나타내는지. 이를 Croissant 1.1 구문을 사용하여 새로운 croissant에 기록하고, 각 진술이 만들어진 이유를 기록합니다.
계획(JSON, 레이아웃별)을 생성하면 스크립트가 이를 적용하고 확인합니다. croissant를 직접 편집하지 마십시오.
입력 및 출력
- 입력: croissant(
croissant.json또는croissant.json.gz)와 출력 디렉토리, 그리고 croissant 옆에 있는 유지 관리자의semantics_answers.json파일(있는 경우). - 출력, 출력 디렉토리 내:
semantics_plan.json— 계획(형식:reference/plan-format.md)croissant.semantic.json(또는 입력이 gzip된 경우.json.gz) — 결과check_report.md—check.py의 출력 (레코드 로드 실패 시check_report.load_errors.txt, 전체 mlcroissant 오류 포함)notes.md— 결정 사항, 생략된 레이아웃과 그 이유, 지식 베이스 유지 관리자를 위한 질문
입력 croissant는 절대 수정되지 않습니다. 다운로드, 도우미 스크립트 및 기타 임시 작업은 OUT/work/에 넣고 다른 곳에 두지 마십시오.
스크립트
모두 scripts/에 있으며, 직접 실행합니다(uv run --script 파일이며 자체 종속성을 설치합니다). 각 스크립트에 --help를 사용하십시오.
| 스크립트 | 용도 |
|---|---|
inventory.py CROISSANT [--layout ID] [--json F] [--common-columns] | 레이아웃(고유한 열 집합)을 나열하고, 가장 큰 것부터 표시합니다. 하나의 레이아웃 열, 레코드 집합 및 파일을 설명하고, 대부분의 레코드 집합이 공유하는 열을 나열합니다. |
sample.py CROISSANT --layout ID | 레이아웃의 세 파일에서 실제 행을 읽습니다. 각 열의 예제 값과 그 형태(CURIE 및 해당 접두사, 베어 ID, 목록, 코드)를 보여줍니다. |
dialects.py list/show/detect/read | 알려진 파일 형식(VCF, GAF, MITAB, CTD, ...)을 계산 가능한 방언(dialect)으로 제공합니다. 레이아웃의 파일을 읽는 방언을 찾고, croissant가 파일에 대해 말하는 것만 사용하여 레코드를 읽습니다. |
vocab.py class/slot/search/associations/prefix/identify/term/ols/infores | Biolink 클래스 및 슬롯(근접 제안 포함), 주어/목적어 쌍에 대한 연관 클래스, 식별자 접두사(Biolink + Bioregistry), 베어 ID에 맞는 접두사, ID 또는 텍스트로 온톨로지 용어, 소스 이름에 대한 infores ID를 조회합니다. |
apply_plan.py CROISSANT PLAN OUT | 계획을 새로운 croissant에 기록합니다. |
check.py CROISSANT PLAN OUT --report R --load-records | 먼저 --plan-only: 용어, 접두사, 방언 및 단위를 초 단위로 확인합니다. 그런 다음 전체 검사: Biolink 및 샘플링된 데이터에 대해 용어, 접두사, 코드 및 방언을 확인하고, MLCommons 검증기를 실행하고, mlcroissant를 통해 몇 개의 레코드를 읽고(전체 다운로드가 아닌 각 파일의 첫 번째 줄에서), 적용 범위를 보고합니다. |
워크플로우
-
조사. croissant 옆에
semantics_answers.json이 있으면 먼저 읽으십시오. 여기에는 이전 질문에 대한 지식 베이스 유지 관리자의 답변이 포함되어 있습니다(아래 "유지 관리자 답변" 참조). 해당 질문을 다시 묻지 마십시오.apply_plan.py및check.py가 자동으로 계획에 답변을 적용합니다. 그런 다음inventory.py CROISSANT를 실행하십시오. croissant의 지식 베이스(이름, 설명, url)를 기록하고 레코드 집합이 레이아웃에 어떻게 분포되어 있는지 확인하십시오. 대규모 지식 베이스에는 수백 개의 레이아웃이 있습니다. 목록의 맨 위부터 작업하십시오.지금 지식 베이스 자체의 infores ID를 찾으십시오(
vocab.py infores NAME; 전체 이름, 약어 및 URL을 시도하십시오). 이를 계획의infores로 설정하십시오. 이는 이러한 파일이 속한 리소스의 이름을 지정하며, 그래프 빌더는 이 파일에서 읽은 모든 것의 출처로 이를 인용합니다. 이것이 없으면 변환 단계에서 지식 베이스를 전혀 구축하지 않습니다. 여러 항목이 일치하는 경우, 이러한 파일을 게시하는 리소스에 대한 항목을 선택하고, 이를 재서비스하는 서비스는 선택하지 마십시오(infores:reactome,infores:automat-reactome아님).check.py는 이를 계획의 나머지 부분과 비교합니다. 단일 집계자 또는 provided_by 상수도 지식 베이스의 이름을 지정합니다(HCOP의 오솔로그는infores:hgnc에 의해 집계됨). 불일치는 해결해야 할 경고입니다.일치하는 항목이 없으면 하나를 제안하십시오:
infores:와 지식 베이스의 짧은 이름을 소문자 단어로 대시로 연결합니다(infores:bioplex,infores:expression-atlas). 계획에"infores_proposed": true를 포함하십시오. 그런 다음vocab.py infores-entry CROISSANT --id infores:NAME으로 카탈로그 항목을 작성하고, 문서에서 명확하게 알 수 있는 경우--knowledge-level및--agent-type을 추가하십시오. 이를notes.md의 등록할 Infores ID 제목 아래 상단 근처에 넣으십시오. 사용자가 infores 레지스트리에 풀 리퀘스트를 제출하여 등록해야 한다고 말하고(명령어가 위치를 출력함), ID가 검토 중에 변경될 수 있다고 말하십시오.check.py는 제안된 ID가 등록될 때까지 경고를 유지합니다. 설명하지 마십시오. -
처리할 레이아웃을 선택하십시오. 대부분의 레코드 집합과 핵심 콘텐츠(연관 및 주요 엔터티 테이블)를 포함하는 레이아웃을 목표로 하십시오. 일반적으로 상위 5~15개, 또는 나머지 레이아웃이 중요하지 않을 때까지(README와 같은 파일, 로그, 릴리스별 개수) 선택합니다. 작은 레이아웃이 많으면(
inventory.py가 알려줌) 레코드 집합이 핵심 열을 공유할 가능성이 높습니다.inventory.py --common-columns를 사용하고match.has_columns로 해당 열을 한 번 계획하십시오. 생략하는 모든 것은 이유와 함께 계획의skipped목록에 넣으십시오. 많은 레이아웃을 잘못 처리하는 것보다 적은 레이아웃을 잘 처리하는 것이 좋습니다. -
각 레이아웃에 대해, 결정하기 전에 데이터를 살펴보십시오.
inventory.py CROISSANT --layout ID로 열, 설명 및 파일 이름을 확인합니다.MIXED로 표시된 열은 레코드 집합에 따라 다른 원자 유형을 가집니다(파이프라인이 파일별로 유추함). 데이터에서 유형을 결정하고atomic을 설정하십시오.- 테이블의 경우,
dialects.py detect CROISSANT --layout ID가 알려진 형식 중에서 파일이 어떻게 작성되었는지(주석 줄, 헤더 유무, 구분자) 찾습니다. 잘 알려진 형식(VCF, GAF, MITAB)은 게시된 사양이 있습니다. 형식을 재발견하는 것보다 사양에 의존하십시오. 맞는 것이 없으면 방언을 인라인으로 설명하십시오(reference/dialects.md). 그런 다음--dialect NAME으로 샘플링하여 행이 형식이 말하는 방식대로 읽히도록 하고 추측하지 않도록 하십시오. sample.py CROISSANT --layout ID로 실제 값을 확인합니다. 레이아웃의 세 파일(이름상 가장 최근 것, 가장 큰 것, 가장 작은 것)을 읽습니다. 하나의 파일(종종 오래된 스냅샷 또는 필터링된 하위 집합)은 값을 숨길 수 있기 때문입니다(N/A플레이스홀더, 추가 코드 값, 다른 ID 유형).--files N은 더 많은 파일을 샘플링하고,--record-set ID는 특정 파일 하나를 샘플링합니다. 샘플링이 실패하면(방대한 파일, 아카이브, 파일 집합) 계획의basis에 이를 명시하고 신뢰도를 낮추십시오.- 코드 열(유형, 증거, 관계, 소스)의 경우 샘플은 드문 값을 놓칩니다.
sample.py CROISSANT --record-set ID --profile COL1,COL2는 전체 파일을 읽고 모든 고유 값을 계산합니다.--record-set을 반복하여 여러 파일의 값을 누적하십시오. 샘플이 아닌 프로필을 기반으로 매핑하십시오. - 지식 베이스 서버를 조심스럽게 다루십시오. 지식 베이스당 한 번에 하나의 샘플링 또는 검사 명령만 실행하고, 여러 개를 병렬로 실행하지 마십시오: 호스트는 봇 챌린지로 버스트를 차단하고, 이후 모든 요청이 실패합니다. 스크립트는 자체 요청 속도를 조절하고 다운로드를 캐시합니다(
~/.cache/croissant-semantics/downloads에,--refresh는 다시 다운로드). 따라서 재실행은 저렴합니다(더 큰--max-mb로 캐시된 복사본이 더 작은 것을 제공함). 스크립트가 봇 챌린지 또는 HTTP 403을 보고하면 해당 호스트 샘플링을 중단하고, 이를 우회하려고 시도하지 말고,notes.md에 어떤 검사를 실행할 수 없었는지 명시하십시오. 그러면 스크립트는 해당 호스트를 한 시간 동안 거부하고(실행 간), 캐시된 파일로 작업합니다. - 스프레드시트(xlsx 및 레거시 xls), SQLite 데이터베이스 및 parquet 파일도 샘플링되고 프로파일링됩니다: 시트 또는 테이블은 레코드 집합의 이름이 끝나는 것입니다("file.xlsx — Sheet1", "file.xlsx: Sheet1"). 샘플링은 알 수 없을 때 추측하기보다 실패합니다. 전체를 읽으므로 필요한 경우
--max-mb를 높이십시오(check.py에서도 마찬가지). mlcroissant는 스프레드시트나 데이터베이스를 읽을 수 없으므로 해당 레코드는 로드되지 않습니다. - XML, RDF(Turtle, RDF/XML, OWL), FASTA 및 테이블이 아닌 기타 파일은 샘플링할 수 없습니다: 스크립트가 그렇게 알려줍니다. 레이아웃이 중요한 경우
OUT/work/에서 작은 스크립트로 ID를 확인하십시오(RDF의 경우uv run --with rdflib, XML의 경우xml.etree.ElementTree.iterparse로 스트리밍).notes.md에 방법을 명시하십시오. 이러한 필드에는 일반적으로extract가 없으므로 어떤 도구도 읽을 수 없습니다: 보고해야 할 생성기 문제입니다. --layout과 함께--profile을 사용하면 각 레코드 집합을--record-set으로 지정하는 대신 레이아웃의--files레코드 집합(기본값 3 또는all)을 프로파일링합니다.--prefixes는 프로파일링된 모든 열 또는 나열된 열만(--prefixes COL1,COL2) 각 값의 접두사 또는 태그를 계산합니다.--by COL은 다른 열에 대해 교차 분석합니다(각 코드가 발생하는 개체 유형).--split SEP는 목록 셀의 항목을 계산합니다.--per-file은 각 레코드 집합을 자체적으로 프로파일링합니다(ID가 파일별로 고유한지 확인하기 위해).--stop-mb N은 각 파일을 N MB 후에 중지합니다(수 GB 파일의 경우, 개수는 시작 부분만 포함합니다. 종이나 ID별로 정렬된 파일에서는 하나의 그룹만 있을 수 있으므로 명시하십시오).- 신뢰하기 전에 주요 레이아웃의 ID 열을 프로파일링하십시오(
--profile COL --shapes). 데이터 검사는 몇 파일의 첫 번째 행만 읽으므로, 나중 행에 ID가 없거나 다른 ID 계열이 있는 열은 검사를 통과합니다. 여러 지식 베이스에서 수백 개의 행 모두에 ID가 있었지만 20-30%의 행에 ID가 없었습니다. match.has_columns항목이 많은 레이아웃을 포함하는 경우,check.py는 해당 파일 중 몇 개만 샘플링합니다. 이를 신뢰하기 전에 다른 레이아웃을 샘플링하십시오(--record-set-name,--files).- 스크립트는 운영 체제의 인증서 저장소를 사용합니다. 인증서 오류로 다운로드가 여전히 실패하면 출력과 함께 보고하십시오. 확인을 끄지 마십시오.
- 문서가 봇 확인("사람인지 확인", Cloudflare 또는 ALTCHA 챌린지) 뒤에 있는 경우, 이를 우회하려고 시도하지 마십시오. 데이터와 이름에서 계획을 세우고 문서로만 확인할 수 있는 의미에 대해 신뢰도를
medium으로 제한하십시오. croissant의 출처는 이후 확인 뒤에 놓인 페이지를 인용할 수 있습니다. 읽을 수 있었던 것만 인용하십시오. - 거대한 파일에서 첫 번째 행은 대표적이지 않을 수 있습니다(CTD의 3GB
genes_diseases는 수천 개의 추론된 행으로 시작합니다). 전체를 스트리밍하는 대신 동일한 레이아웃의 더 작은 파일(큐레이팅된 하위 집합)을 프로파일링하십시오. - 이름으로 레코드 집합을 선택하려면(셸에서
--record-set인수 목록을 만드는 대신)--record-set-name REGEX를 사용하십시오(zsh는 변수를 단어로 분할하지 않음).--per-file은 샘플링된 각 파일을 별도로 보여줍니다. 파일이 다른 레이아웃(파일당 하나의 ID 종류)에 유용합니다. - 데이터 검사는 몇 파일의 첫 번째 행을 읽습니다. 열의 나중 행은 다를 수 있습니다(200개의 IRI 이후의 빈 노드, 드문 코드). 전체 파일을 읽는
--profile로 ID 형식과 코드를 확인하십시오. inventory.py는 레이아웃 다음에 데이터와 함께 제공되는 문서 파일(README.pdf, 데이터 사전)을 나열합니다. 관련 파일을 읽으십시오:sample.py CROISSANT --dump FILE은 파일을 텍스트로 출력하고,--member NAME은 아카이브의 멤버를 출력하며(zip은 전체를 읽으므로 큰 파일의 경우--max-mb를 높이십시오),--sheet NAME은 스프레드시트의 시트를 출력합니다.sample.py는 선언된 유형이 값과 맞지 않는 열(sc:Integer열이27152464|29518214를 보유)과 행이 헤더보다 넓거나 좁은 파일을 표시합니다. 둘 다 일반적으로 파이프라인 문제입니다.atomic으로 유형을 수정하고 보고하십시오.- 스크립트가 소스를 읽을 수 없는 경우, 직접 파일을 가져와서(한 번에 하나씩,
OUT/work/에)--url-map OLD=file:///abs/path/로 스크립트를 가리키면 자체 프로파일러를 작성하는 대신 검사가 계속 실행됩니다. 다운로드는 캐시되며~/.cache/croissant-semantics/downloads/index.tsv는 각 캐시된 파일을 URL에 매핑합니다. - 레이아웃의 "열 이름"이 실제로 데이터인 경우(헤더 행이 없어 파이프라인이 첫 번째 데이터 행을 이름으로 사용하고 모든 파일이 자체 레이아웃이 됨), 건너뛰고
notes.md에 파이프라인 문제로 보고하십시오. - 데이터 URL이 사라진 경우(HTTP 404), 지식 베이스가 최신 릴리스로 이동했을 가능성이 높습니다. 다운로드 페이지에서 현재 URL을 찾아
--url-map OLD=NEW를sample.py및check.py에 전달하십시오(예:--url-map 202607=202610). 릴리스 이상의 변경이 있는 경우(다른 경로 또는 파일 이름) 파일당 하나의--url-map OLD_URL=NEW_URL로 전체 URL을 매핑하십시오. URL 자체에=가 포함된 경우(쿼리 문자열)OLD=>NEW를 작성하십시오.notes.md에 명시하십시오. 이것도 파이프라인 문제입니다. croissant가 테이블을 설명하는 곳에서 JSON을 반환하는 SPARQL 엔드포인트 URL은 일반적으로&format=csv(또는text/csv)를 매핑해야 합니다. - 아카이브: zip 및 tar 아카이브의 멤버가 샘플링됩니다. zip은 전체가 다운로드됩니다(
--max-mb까지). tar는 멤버를 찾을 때까지 스트리밍되므로 거대한 tar 내부 깊은 멤버는--max-mb를 초과할 수 있습니다. 한 번 실패한 아카이브는 다시 시도되지 않으며 반복적인 실패 후 샘플링이 중지됩니다. 필요한 경우 직접OUT/work/에 멤버를 추출하고notes.md에 확인한 내용과 방법을 기록하십시오. - 데이터에 로그인 또는 API 키가 필요한 경우(HTTP 401/403 또는 croissant의
conditionsOfAccess가 명시), 자격 증명을 찾지 마십시오. 문서와 열 이름만으로 계획을 세우십시오:source는documentation또는agent,confidence는 최대medium,notes.md에는 데이터에 대해 아무것도 확인되지 않았다고 명시하십시오. - 제공된 데이터 사전을 찾으십시오.
(참고: 전체 SKILL.md가 너무 길어 잘렸습니다. 위 내용은 제공된 내용을 기반으로 번역되었습니다.)