FITS 裁切圖上的暫現源真假甄別與星系形態分類

v2.13.0 新增

fits_cutout 顯示類型在瀏覽器中顯示 FITS 影像：可以每個條目顯示一幅影像，也可以把一個暫現源候選體的科學影像、參考影像和差分影像裁切圖（cutout）並排顯示，下方附該候選體的光變曲線。時域天文學研究者用這個顯示類型做真假甄別（real-bogus vetting）。在真假甄別中，標註者把來自 ZTF 或 Rubin 等巡天的每個候選體判為真實的天體物理暫現源或虛假檢測。這些標籤成為真假甄別分類器的訓練集。例如，ZTF 的 Braai 分類器就是用 30,000 多組已標註的科學、參考和差分影像三聯圖訓練的（Duev et al., MNRAS 489, 3582）。星系形態分類每個條目使用一幅影像，並配一棵 Galaxy Zoo 式的問題樹。顯示類型本身不儲存任何內容，甄別問題是一個普通方案，通常是一道 radio，用 R、B、U 三個鍵選擇 Real、Bogus 和 Unsure。

FITS（Flexible Image Transport System，靈活影像傳輸系統）是天文影像和表格的標準檔案格式。FITS 頭部中的世界座標系（World Coordinate System，WCS）關鍵字把影像的每個畫素對映到天球上的一個位置。差分影像是經過定標的科學曝光減去同一天區的參考影像（模板）得到的影像，真實的暫現源在差分影像中表現為一個新出現的點源。ZTF 警報包以 gzip 壓縮的 FITS 影像儲存科學、參考和差分裁切圖（警報模式），Rubin 的工作人員表示 Rubin 警報也將包含全部三幅裁切圖（Rubin 論壇）。

• 讀取： astropy（BSD-3-Clause）在 Potato 伺服器上讀取 FITS 檔案，擷取條目位置周圍的區域，對裁切圖做亮度縮放，再發送一幅 PNG 以及這幅裁切圖的 WCS 描述。伺服器在讀取第一個 FITS 檔案時才匯入 astropy，啟動時不載入 astropy。
• 格式： .fits、.fit、.fts 以及 gzip 壓縮的 .fits.gz。顯示類型顯示由 hdu 指定的 HDU，否則顯示第一個包含二維（或更高維）影像的 HDU；資料立方體顯示其第一個平面。以 .fits.gz 名稱寫入磁碟的 ZTF 裁切圖無需解壓即可開啟。
• 裁切圖： 中心是 FITS 畫素座標（x、y）或天球座標（ra、dec），尺寸是畫素數或 "40 arcsec" 這樣的角度。對於未壓縮的檔案，只讀取裁切圖覆蓋的那些行。
• 快取： 每幅轉換後的裁切圖以一個 PNG 和一個 JSON 檔案寫入 <task_dir>/.potato_cache/fits/。快取鍵涵蓋檔案的路徑、大小、修改時間和縮放選項，未改動的檔案只轉換一次。快取保留最近使用的 4,000 項，刪除這個資料夾是安全的。
• 離線： FITS 檔案和光變曲線從媒體目錄讀取。URL 和媒體目錄之外的路徑一律拒絕，光變曲線圖使用 Potato 自帶的 Plotly。

這個顯示類型需要 astro 可選依賴（astropy>=5.3）：

pip install 'potato-annotation[astro]'

配置中有 fits_cutout 欄位而沒有安裝 astropy 時，啟動會失敗，提示資訊中給出安裝命令。

配置

下面的配置在裁切圖三聯圖上進行真假甄別。每個候選體都必須給出真假標籤；只有在標註者選了 Bogus 之後，才會出現第二個問題，詢問虛假檢測的原因：

annotation_task_name: "Transient candidate vetting"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/candidates.json]
item_properties: {id_key: id, text_key: summary}
 
instance_display:
  fields:
    - key: candidate            # item field holding the triplet
      type: fits_cutout
      label: "Cutouts"
      display_options:
        size: 48                # pixels, used when an item gives no size
        interval: zscale
        stretch: linear
        panels:
          - {key: science, label: Science}
          - {key: reference, label: Reference}
          - {key: difference, label: Difference, stretch: asinh}
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: radio
    name: vetting
    description: "Is this a real astrophysical transient?"
    humanize_labels: false
    labels:
      - {name: "Real", key_value: "r"}
      - {name: "Bogus", key_value: "b"}
      - {name: "Unsure", key_value: "u"}
    label_requirement: {required: true}
 
  - annotation_type: multiselect
    name: bogus_reason
    description: "What makes the candidate bogus?"
    humanize_labels: false
    labels:
      - "Subtraction residual (dipole)"
      - "Cosmic ray or hot pixel"
      - "Satellite or asteroid trail"
      - "Bad column or image edge"
      - "Other"
    display_logic:
      show_when:
        - {schema: vetting, operator: equals, value: "Bogus"}

panels 列表選擇顯示哪些裁切圖及其順序，每個面板可以設定自己的縮放。這裡的差分面板使用 asinh 拉伸，科學麵板和參考面板沿用顯示類型的 zscale 區間和線性拉伸。humanize_labels: false 讓每個標籤按原樣顯示，螢幕上的“Bogus”因此與 display_logic 條件中的值一致。被隱藏的問題在頁面和伺服器上都不參與必答檢查。

每個條目給出三個相對於 media_directory 的 FITS 路徑、候選體的位置以及可選的光變曲線：

{
  "id": "cand-001",
  "summary": "cand-001: ra 150.11920, dec +2.20583, band r",
  "candidate": {
    "science": "cutouts/cand-001_sci.fits",
    "reference": "cutouts/cand-001_ref.fits",
    "difference": "cutouts/cand-001_diff.fits",
    "ra": 150.11920, "dec": 2.20583,
    "size": 48,
    "light_curve": "lightcurves/cand-001.csv"
  }
}

對於星系形態分類，存放單個路徑的條目欄位顯示一幅影像：

{"id": "gal-17", "image": "galaxies/gal-17.fits"}

ZTF 光變曲線

Potato 按常見的列名查詢光變曲線的各列，而 ZTF 的測光列 magpsf 和 sigmapsf 不在這些名稱之中。不做對映時，一條含有 jd, fid, magpsf, sigmapsf, diffmaglim 列的 ZTF 光變曲線會把每個帶 diffmaglim 的行畫成上限。下面這段部分配置為上文配置中的 fits_cutout 欄位新增兩個選項，並逐一指定各列：

instance_display:
  fields:
    - key: candidate
      type: fits_cutout
      display_options:
        light_curve_columns: {time: jd, band: fid, mag: magpsf, err: sigmapsf, limit: diffmaglim}
        time_label: JD

圖上的“this image”標記取自科學影像的 MJD-OBS，只有當 MJD-OBS 落在第一個點之前 1,000 個時間單位到最後一個點之後 1,000 個時間單位的範圍內時，Potato 才畫出這個標記。在 JD 座標軸上，MJD-OBS 比每個時間都小約 2,400,000，因此不會畫出標記；在每個條目上以 JD 給出 epoch 即可放置標記。ZTF 的濾光片編號 1、2、3 會成為波段名“1”“2”“3”；如果在波段列中改寫為 g、r 和 i，每個波段就會使用其慣用的顏色。

用問題樹做星系形態分類

Galaxy Zoo 式的決策樹按固定順序提問，每個答案決定下一個問題。Galaxy Zoo DECaLS 的決策樹以“Smooth or Featured?”開頭（Walmsley et al., MNRAS 509, 3966）。在 Potato 中，樹上的每個問題是一個 radio 方案，每個後續問題上的 display_logic 只在出現引向該問題的答案之後才顯示這個問題。

display_logic 的兩條規則決定了樹的寫法。第一，被隱藏的問題會保留標註者在它被隱藏之前給出的答案。第二，問題是否可見只根據答案計算，與父問題是否顯示在螢幕上無關。因此每個條件都要用 all 列出從第一個問題開始的整條路徑。只寫父問題的條件，會在標註者更改前面的某個答案之後，讓後面的問題仍留在螢幕上。

下面的配置在單幅星系影像上提出一棵含四個問題的樹：

annotation_task_name: "Galaxy morphology"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/galaxies.json]
item_properties: {id_key: id, text_key: id}
 
instance_display:
  fields:
    - key: image
      type: fits_cutout
      label: "Galaxy"
      display_options:
        interval: percentile
        percentile: 99.5
        stretch: asinh
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: radio
    name: shape
    description: "Is the galaxy simply smooth and rounded, with no sign of a disk?"
    humanize_labels: false
    labels: ["Smooth", "Features or a disk", "Star or artifact"]
    label_requirement: {required: true}
 
  - annotation_type: radio
    name: edge_on
    description: "Could this be a disk viewed edge-on?"
    labels: ["Yes", "No"]
    label_requirement: {required: true}
    display_logic:
      show_when:
        - {schema: shape, operator: equals, value: "Features or a disk"}
 
  - annotation_type: radio
    name: bulge_edge_on
    description: "Does the edge-on disk have a bulge at its center? If so, what shape?"
    humanize_labels: false
    labels: ["Rounded", "Boxy", "No bulge"]
    label_requirement: {required: true}
    display_logic:
      show_when:
        - all:
            - {schema: shape, operator: equals, value: "Features or a disk"}
            - {schema: edge_on, operator: equals, value: "Yes"}
 
  - annotation_type: radio
    name: spiral
    description: "Is there any sign of a spiral arm pattern?"
    labels: ["Yes", "No"]
    label_requirement: {required: true}
    display_logic:
      show_when:
        - all:
            - {schema: shape, operator: equals, value: "Features or a disk"}
            - {schema: edge_on, operator: equals, value: "No"}

條目中沒有位置時，顯示類型顯示整幅影像。百分位區間加 asinh 拉伸可以在同一檢視中同時顯示星系闇弱的外盤和明亮的核心。zscale 區間是為闇弱源調校的，可能使明亮的核心飽和。YAML 中要給 "Yes" 和 "No" 加引號，因為不加引號的 Yes 和 No 會被讀作布林值。上游示例在甄別問題之後放了一棵同類的樹，這棵樹詢問每個真實候選體的宿主星系。

條目資料

條目的欄位是一個 FITS 路徑，或帶有下列鍵的對映：

縮放選項分四個層級生效，從低到高依次為：(1) 顯示選項，(2) panels 項，(3) 條目，(4) 條目中針對某一幅影像的對映。後面的層級覆蓋前面的層級。有位置但各處都沒有給出尺寸的條目得到 64 畫素的裁切圖，裁切圖每邊最多 4,096 畫素。沒有位置的條目顯示整幅影像，上限為 max_image_pixels；寬或高超過 1,024 畫素的影像按塊平均縮小到 1,024。只有尺寸而沒有位置會報錯。沒有 panels 列表時，顯示類型顯示條目中具有的 science、reference 和 difference，否則顯示 image。

光變曲線檔案

光變曲線檔案每個點一行：

mjd,band,mag,magerr,limit
60570.0,r,,,21.3
60600.0,g,20.21,0.07,
60603.0,g,19.37,0.05,

有星等的行是一次檢測，沒有星等但有 limit 的行是一個上限。沒有可用時間的行會被跳過並計數。沒有 light_curve_columns 時，列名按下列名單依次匹配，不區分大小寫：

JSON 光變曲線是點物件的列表，或一個把列表放在 points 或 data 下的物件。TSV 檔案依據 .tsv 副檔名或檔案中的製表符識別，以 # 開頭的行會被跳過。超過 2 MB 的檔案會被拒絕，第 20,000 行之後的行會被丟棄。波段按 u、g、r、i、z、y、J、H、K、W1、W2、c、o 的順序排列，其他波段名排在這些波段之後。

顯示選項

選項寫在 display_options 下，或直接寫在欄位上，伺服器在啟動時檢查每個值：

engine 選項只接受 potato 一個值。由於 FITS 檔案總是在伺服器上讀取，這個顯示類型拒絕 allow_remote。

檢視器控制元件

各面板共享縮放、平移和同一個十字準線，縮放級別從 1× 到 16×：

裁切圖獲得焦點時，標註按鍵（甄別配置中的 R、B 和 U）照常可用。方向鍵只在裁切圖獲得焦點時移動十字準線，在其他地方，方向鍵照常在條目之間切換。空白畫素（NaN 或 BLANK）以及裁切圖中超出影像邊緣的部分是透明的，顯示為棋盤格，面板下方的狀態行會說明屬於哪種情況。

面板尺寸相同、畫素比例尺相差在 1% 以內、天球上的中心相差不到半個畫素時，各面板視為已對齊。對於未對齊的面板，會有一條說明指出這一點，十字準線按天球位置放到每個面板上，所用的是各面板的線性 TAN WCS。光變曲線圖把科學影像的歷元標為“this image”，把上限畫成空心的向下三角形，並在圖下方的表格中列出每個點。

傳送給瀏覽器的 WCS

瀏覽器從不讀取 FITS。對每幅裁切圖，伺服器傳送 PNG 的 URL 和一份 WCS 描述，其中包括裁切圖的 CRPIX、CRVAL 和 CD 矩陣、畫素比例尺、北向和東向，以及在整幅裁切圖上每隔 16 個輸出畫素取樣一次的天球位置網格。讀數對網格做插值，因此能跟隨 astropy 能讀取的任何投影，包括 SIP 畸變。網格把每個天球位置存為單位向量，對單位向量插值能讓讀數在赤經 0/360 處和天極附近保持連續。線性關鍵字不含 SIP 項，未對齊面板的十字準線放置使用的就是這些線性關鍵字。銀道座標影像把座標軸標為 l 和 b，黃道座標影像標為 λ 和 β。

儲存的答案與匯出

顯示類型不儲存任何內容。頁面上的每個方案像任何 radio 或 multiselect 問題一樣儲存標註者的答案，這些答案通過通用格式匯出：

python -m potato.export -c config.yaml -f csv -o exports/csv

CSV 中每位標註者、每個條目一行，每個方案和標籤一列，例如 vetting.Real 和 bogus_reason.Cosmic ray or hot pixel。-f jsonl 以 JSON lines 寫出同樣的記錄。樹中某個問題後來被隱藏時，它的答案仍保留在儲存的標註中。分析前，請根據前面答案的路徑篩選後續問題的答案。

Potato 的一致性指標覆蓋這些方案。vetting 這樣的 radio 問題可以得到百分比一致率、Cohen's kappa、Fleiss' kappa 和 Krippendorff's alpha；bogus_reason 這樣的 multiselect 問題可以得到平均 Jaccard 係數和使用 MASI 距離的 Krippendorff's alpha。2.13 新增的 consensus 匯出同樣覆蓋 radio 和 multiselect，這個匯出列出每個候選體的得票比例，以及根據 consensus_aggregation 塊中的閾值給出的 retired 或 needs_review 狀態。一致性指標和共識匯出都不檢查 display_logic，隱藏問題上保留的答案在兩者中都會被計入。請把 num_annotators_per_item 設為甄別每個候選體的標註者人數。

示例

python potato/flask_server.py start examples/image/astronomy-real-bogus/config.yaml -p 8000

這個示例有四個合成的候選體：盤星系中的一顆超新星、一個減除偶極子、一個宇宙線和一個無宿主的點源。每個候選體有三幅 96 × 96 的 FITS 影像，共用一個每畫素 1″ 的 TAN WCS，另有一條光變曲線。第四個候選體的影像經過 gzip 壓縮，同一資料夾中的 generate_data.py 會重新寫出這些檔案。

用程式設計智慧體搭建研究

potato-skill 1.2.0 面向 Potato 2.13.1，認得 fits_cutout 這個顯示類型名稱，並指導研究設計這一側，例如向標註者問什麼、每個候選體由幾名標註者甄別、培訓和注意力檢查，以及匯出。這個技能目前還沒有記錄 FITS 條目格式、顯示選項和 astro 可選依賴。安裝 potato-skill，把研究描述給你的智慧體，再讓智慧體參考本頁的 Markdown 副本 https://www.potatoannotator.com/docs/annotation-types/astronomy.md，以瞭解格式和選項。

延伸閱讀

• 單選與多選 - 提出甄別問題和樹問題的方案
• 時間序列 - 在光變曲線上標記凌星和耀發
• 匯出格式 - Potato 的匯出格式和匯出命令
• 標註者間一致性詳解 - 選擇和解讀一致性係數
• 你需要多少位標註者？ - 為每個條目選擇標註者人數

有關實現細節，請參閱源文件。