OneKGPd：1000 Genomes 計畫的個體層級查詢
範圍
此技能查詢的是 1000 Genomes 計畫資料集——即 GRCh38 組合上的 3,202 個全基因體定序個體的擴展高覆蓋度群體。所有結果皆來自此群體，且此技能傳回的樣本名稱（例如 HG00096 或 NA21130）可識別其參與者。
查詢會針對群體中每個個體的基因型資料進行解析。這支援兩類互補的問題：在一個區域內選取所攜帶的變異（可針對整個群體或指定的個體子集），以及選取攜帶符合特定條件的變異之個體。變異選取可依據等位基因頻率、預測後果、臨床重要性、AlphaMissense 分類以及下列列出的其他註解軸進行過濾。也提供兩個命名個體之間的親緣關係查詢。
變異攜帶的基因型狀態——異型合子或同型合子——是查詢可指定的條件；結果會以變異或樣本名稱的形式傳回，而非原始基因型。
使用時機
需要以下情況時，請使用此技能：
- 在整個群體中，尋找一個或多個區域內符合某些條件的變異 (
select-variants)。 - 在特定個體集合中，尋找一個或多個區域內符合某些條件的變異 (
select-variants-in-samples)。 - 在一個或多個區域內，尋找哪些 1000 Genomes 個體攜帶符合某些條件的變異 (
select-samples)。 - 計算有多少個體攜帶特定變異 (
count-samples)。 - 將任何變異查詢限制為僅異型合子或僅同型合子攜帶，或同時查詢兩者（預設）。
- 識別在單一位置上為同型合子參考型的個體 (
select-samples-hom-ref)。 - 判斷兩個命名之 1000 Genomes 個體的親緣關係——包含親等（雙胞胎 / 一等 / 二等 / 三等 / 無關）及 KING 親屬係數 (
kinship)。 - 取得資料集總計——樣本數、性別比例、變異數、組合 (
dataset-info)。 - 變異選取可依據 KGP 等位基因頻率、gnomAD 4.1 外顯子組和 gnomAD 4.1 基因組等位基因頻率、AlphaMissense 分數與 AlphaMissense 分類、ClinVar 重要性（202502）以及 VEP 註解（影響、生物型、特徵類型、變異類別、後果）來指定。
請勿將此技能用於：
- 解析基因符號、rsID 或轉錄本至座標，或取得參考序列。請先解析座標（請參閱下方的座標來源），然後使用解析後的 GRCh38 區域查詢此技能。
- 非 1000 Genomes 計畫的任何其他群體——此技能僅服務該資料集。
先決條件
uv：此技能的腳本使用uv run執行，它會讀取腳本的內聯相依性元資料並佈建一個暫時環境。請確保uv已安裝且在 PATH 中 (https://docs.astral.sh/uv/)。- 資料使用條款：1000 Genomes 計畫資料是開放的；使用者應了解 1000 Genomes 計畫 / IGSR 的資料使用條款 (https://www.internationalgenome.org/data)。
- 存取限制：無需 API 金鑰、
.env檔案或速率限制令牌。 - 無需憑證
核心規則
- 使用包裝腳本：一律執行提供的輔助腳本，而不是自行構建客戶端呼叫或網路請求。使用
scripts/onekgpd_api.py進行變異/樣本/親緣關係查詢（它處理連線、串流、分頁和 JSON 序列化），以及使用scripts/onekgpd_meta.py進行樣本/群體中繼資料查詢（離線，請參閱樣本與群體中繼資料）。 - 座標必須先透過權威來源解析——請參閱座標來源（強制性的第一步）。這是強制性的，而非建議。
- 先計數再選取：每個變異和樣本選取都有對應的計數指令。請先呼叫計數指令來評估結果集大小，只有在數量可管理時才進行選取。
- 接合性預設為兩者：選取和計數指令預設包含異型合子和同型合子攜帶。當問題特別針對某一狀態時，使用
--het-only或--hom-only縮小範圍。（不需要傳入任何參數即可獲得兩者。） - 輸出：腳本會將完整的 JSON 寫入檔案（
--output，預設在/tmp/下），並將簡潔的摘要列印到 stdout。請勿將大型 JSON 檔案讀入上下文——使用jq或一個小的uv run python腳本來擷取欄位。
座標來源（強制性的第一步）
在進行任何基於區域的查詢之前，請先針對權威來源（例如 Ensembl）將基因或特徵解析為 GRCh38 座標，並使用這些已解析的座標進行查詢。組合必須明確，且基因範圍必須在使用前解析為精確位置。這是結構性的，而非建議：伺服器端沒有護欄可以捕捉錯誤定位的區域，因此未經驗證的座標會在不報錯的情況下產生非預期位置的結果。
# 請先透過權威來源將基因符號解析為 GRCh38 區域，
# 然後將驗證過的座標傳遞給下方的 OneKGPd 查詢。
[!CAUTION] 資料集是 GRCh38。GRCh37 座標，或任何未能正確對應至 GRCh38 上預期特徵的區域，都會在不引發錯誤的情況下傳回非預期位置的結果。請在查詢前驗證組合和解析後的座標。
指令選擇指南
將問題與指令配對。計數指令成本較低，應在其對應的選取指令之前執行。
- 哪些個體在一個區域內攜帶符合條件的變異 →
count-samples然後select-samples - 在整個群體中，一個區域內攜帶了哪些變異 →
count-variants然後select-variants - 在一個命名的個體集合內，一個區域中攜帶了哪些變異 →
count-variants-in-samples然後select-variants-in-samples - 誰在單一位置上為同型合子參考型 →
count-samples-hom-ref然後select-samples-hom-ref - 兩個命名個體之間的親緣關係（親等 + 係數） →
kinship - 資料集總計（樣本數、性別比例、總變異數、組合） →
dataset-info
註解過濾器（共用於變異和樣本選取/計數）
所有變異和樣本選取指令（count-variants、select-variants、它們的 -in-samples 形式、count-samples、select-samples）都接受相同的註解過濾器。不同的過濾欄位以 AND 組合；同一個欄位的多個值以 OR 組合。列舉值不區分大小寫（例如 missense_variant 或 MISSENSE_VARIANT）。
這些是在伺服器端套用的選取條件。選取變異時傳回的欄位列於傳回變異的指令下方；用於過濾的條件不一定會反映在傳回的變異上。
--af-lt/--af-gt：1000 Genomes 資料集等位基因頻率範圍--gnomad-exomes-af-lt/--gnomad-exomes-af-gt：gnomAD v4.1 外顯子組 AF 範圍--gnomad-genomes-af-lt/--gnomad-genomes-af-gt：gnomAD v4.1 基因組 AF 範圍--clin-significance：ClinVar 重要性詞彙，CSV 格式（例如PATHOGENIC,LIKELY_PATHOGENIC）--consequence：Sequence Ontology 後果詞彙，CSV 格式（例如MISSENSE_VARIANT,STOP_GAINED）--impact：VEP 影響力，CSV 格式（HIGH,MODERATE,LOW,MODIFIER）--variant-type、--feature-type、--bio-type：SO 變異類別 / VEP 特徵 / VEP 生物型，CSV 格式--alpha-missense-class：AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS（CSV 格式）--alpha-missense-score-lt/--alpha-missense-score-gt：AlphaMissense 分數範圍--biallelic-only/--multiallelic-only--exclude-males/--exclude-females--min-len-bp/--max-len-bp：替代等位基因長度範圍（鹼基對）
[!NOTE]
--alpha-missense-class和--alpha-missense-score-*互斥（當設定分數範圍時，引擎會忽略類別）。--biallelic-only和--multiallelic-only互斥。--exclude-males和--exclude-females互斥。將*-gt範圍設定為大於或等於其對應的*-lt範圍會定義一個空範圍，且不會傳回任何結果。
[!NOTE] 等位基因頻率欄位使用
0.0表示「不存在於該來源中」。因此，--gnomad-exomes-af-gt 0會選取存在於 gnomAD 外顯子組中的變異；傳回的gnomad_exomes_af為0.0表示該變異不存在於 gnomAD 外顯子組中。gnomAD 基因組 AF 採用相同慣例。 相反地，--gnomad-exomes-af-lt/--gnomad-genomes-af-lt範圍包含未註解的變異：