ruwwww/agent-skills

Astropy

概述

Astropy 是天文學的核心 Python 套件，為天文研究和數據分析提供必要功能。使用 astropy 進行座標轉換、單位和量值計算、FITS 檔案操作、宇宙學計算、精確時間處理、表格資料處理以及天文影像處理。

何時使用此技能

當任務涉及以下內容時，使用 astropy：

• 在天球座標系統之間轉換（ICRS、Galactic、FK5、AltAz 等）
• 處理物理單位和量值（將 Jy 轉換為 mJy、秒差距轉換為公里等）
• 讀取、寫入或操作 FITS 檔案（影像或表格）
• 宇宙學計算（光度距離、回溯時間、哈伯參數）
• 使用不同的時間尺度（UTC、TAI、TT、TDB）和格式（JD、MJD、ISO）進行精確時間處理
• 表格操作（讀取星表、交叉比對、篩選、合併）
• 像素座標與世界座標之間的 WCS 轉換
• 天文常數和計算

快速開始

import astropy.units as u
from astropy.coordinates import SkyCoord
from astropy.time import Time
from astropy.io import fits
from astropy.table import Table
from astropy.cosmology import Planck18

# 單位和量值
distance = 100 * u.pc
distance_km = distance.to(u.km)

# 座標
coord = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')
coord_galactic = coord.galactic

# 時間
t = Time('2023-01-15 12:30:00')
jd = t.jd  # 儒略日

# FITS 檔案
data = fits.getdata('image.fits')
header = fits.getheader('image.fits')

# 表格
table = Table.read('catalog.fits')

# 宇宙學
d_L = Planck18.luminosity_distance(z=1.0)

核心功能

1. 單位和量值 (astropy.units)

使用單位處理物理量值，執行單位轉換，並確保計算中的量綱一致性。

關鍵操作：

• 將值與單位相乘來建立量值
• 使用 .to() 方法在單位之間轉換
• 使用自動單位處理執行算術運算
• 使用等價關係進行領域特定的轉換（光譜、都卜勒、視差）
• 處理對數單位（星等、分貝）

參見： references/units.md 獲取完整的文件、單位系統、等價關係、效能最佳化和單位算術。

2. 座標系統 (astropy.coordinates)

表示天球位置並在不同座標框架之間轉換。

關鍵操作：

• 使用 SkyCoord 在任何框架（ICRS、Galactic、FK5、AltAz 等）中建立座標
• 在座標系統之間轉換
• 計算角分離和位置角
• 將座標與星表比對
• 包含距離以進行 3D 座標操作
• 處理自行和徑向速度
• 從線上資料庫查詢命名天體

參見： references/coordinates.md 獲取詳細的座標框架描述、轉換、觀測者相關框架 (AltAz)、星表比對和效能提示。

3. 宇宙學計算 (astropy.cosmology)

使用標準宇宙學模型執行宇宙學計算。

關鍵操作：

• 使用內建的宇宙學模型（Planck18、WMAP9 等）
• 建立自訂的宇宙學模型
• 計算距離（光度、共動、角直徑）
• 計算年齡和回溯時間
• 確定任何紅移處的哈伯參數
• 計算密度參數和體積
• 執行反向計算（找出給定距離的 z）

參見： references/cosmology.md 獲取可用的模型、距離計算、時間計算、密度參數和中微子效應。

4. FITS 檔案處理 (astropy.io.fits)

讀取、寫入和操作 FITS（可伸縮影像傳輸系統）檔案。

關鍵操作：

• 使用上下文管理器開啟 FITS 檔案
• 依索引或名稱存取 HDU（標頭資料單元）
• 讀取和修改標頭（關鍵字、註解、歷史記錄）
• 處理影像資料（NumPy 陣列）
• 處理表格資料（二進位和 ASCII 表格）
• 建立新的 FITS 檔案（單一或多擴展）
• 對大型檔案使用記憶體映射
• 存取遠端 FITS 檔案（S3、HTTP）

參見： references/fits.md 獲取全面的檔案操作、標頭操作、影像和表格處理、多擴展檔案以及效能考量。

5. 表格操作 (astropy.table)

支援單位、元資料和多種檔案格式的表格資料操作。

關鍵操作：

• 從陣列、列表或字典建立表格
• 以多種格式讀取/寫入表格（FITS、CSV、HDF5、VOTable）
• 存取和修改列和行
• 排序、篩選和索引表格
• 執行類似資料庫的操作（合併、分組、聚合）
• 堆疊和串聯表格
• 處理具有單位感知的列 (QTable)
• 使用遮罩處理缺失資料

參見： references/tables.md 獲取表格建立、I/O 操作、資料操作、排序、篩選、合併、分組和效能提示。

6. 時間處理 (astropy.time)

精確的時間表示以及時間尺度和格式之間的轉換。

關鍵操作：

• 以各種格式建立 Time 物件（ISO、JD、MJD、Unix 等）
• 在時間尺度之間轉換（UTC、TAI、TT、TDB 等）
• 使用 TimeDelta 執行時間算術
• 為觀測者計算恆星時
• 計算光行差時間修正（質心、日心）
• 高效地處理時間陣列
• 處理遮罩的（缺失）時間

參見： references/time.md 獲取時間格式、時間尺度、轉換、算術、觀測功能和精度處理。

7. 世界座標系統 (astropy.wcs)

在影像中的像素座標和世界座標之間轉換。

關鍵操作：

• 從 FITS 標頭讀取 WCS
• 將像素座標轉換為世界座標（反之亦然）
• 計算影像範圍
• 存取 WCS 參數（參考像素、投影、尺度）
• 建立自訂 WCS 物件

參見： references/wcs_and_other_modules.md 獲取 WCS 操作和轉換。

其他功能

references/wcs_and_other_modules.md 檔案也涵蓋：

NDData 和 CCDData

包含元資料、不確定性、遮罩和 WCS 資訊的 n 維資料集容器。

建模

用於建立和擬合天文資料數學模型的框架。

視覺化

具有適當拉伸和縮放的天文影像顯示工具。

常數

具有適當單位的物理和天文常數（光速、太陽質量、普朗克常數等）。

卷積

用於平滑和濾波的影像處理核心。

統計

包括 sigma 裁剪和離群值剔除的穩健統計函數。

安裝

# 針對當前穩定版本的可重現安裝
uv pip install "astropy==7.2.0"

# 繪圖和常見工作流程的建議選用相依性
uv pip install "astropy[recommended]==7.2.0"

# 廣泛天文學工作流程的完整選用相依性集
uv pip install "astropy[all]==7.2.0"

Astropy 7.2.0 需要 Python 3.11+，並依賴於 NumPy、PyERFA、PyYAML 和 packaging。請使用隔離的虛擬環境；請勿使用提升的權限安裝 Astropy。

請注意，[recommended] 和 [all] 擴展會以未固定版本引入傳遞相依性（matplotlib、scipy 等）。對於可重現的生產環境，請使用鎖定檔（專案中的 uv lock，或需求檔案的 uv pip compile）固定完整的相依性樹，並在部署前審閱已解析的版本。

常見工作流程

在系統之間轉換座標

from astropy.coordinates import SkyCoord
import astropy.units as u

# 建立座標
c = SkyCoord(ra='05h23m34.5s', dec='-69d45m22s', frame='icrs')

# 轉換到銀道座標
c_gal = c.galactic
print(f"l={c_gal.l.deg}, b={c_gal.b.deg}")

# 轉換到地平座標（需要時間和位置）
from astropy.time import Time
from astropy.coordinates import EarthLocation, AltAz

observing_time = Time('2023-06-15 23:00:00')
observing_location = EarthLocation(lat=40*u.deg, lon=-120*u.deg)
aa_frame = AltAz(obstime=observing_time, location=observing_location)
c_altaz = c.transform_to(aa_frame)
print(f"Alt={c_altaz.alt.deg}, Az={c_altaz.az.deg}")

讀取和分析 FITS 檔案

from astropy.io import fits
import numpy as np

# 開啟 FITS 檔案
with fits.open('observation.fits') as hdul:
    # 顯示結構
    hdul.info()

    # 取得影像資料和標頭
    data = hdul[1].data
    header = hdul[1].header

    # 存取標頭值
    exptime = header['EXPTIME']
    filter_name = header['FILTER']

    # 分析資料
    mean = np.mean(data)
    median = np.median(data)
    print(f"Mean: {mean}, Median: {median}")

宇宙學距離計算

from astropy.cosmology import Planck18
import astropy.units as u
import numpy as np

# 計算 z=1.5 處的距離
z = 1.5
d_L = Planck18.luminosity_distance(z)
d_A = Planck18.angular_diameter_distance(z)

print(f"光度距離: {d_L}")
print(f"角直徑距離: {d_A}")

# 該紅移處的宇宙年齡
age = Planck18.age(z)
print(f"z={z} 處的年齡: {age.to(u.Gyr)}")

# 回溯時間
t_lookback = Planck18.lookback_time(z)
print(f"回溯時間: {t_lookback.to(u.Gyr)}")

交叉比對星表

from astropy.table import Table
from astropy.coordinates import SkyCoord, match_coordinates_sky
import astropy.units as u

# 讀取星表
cat1 = Table.read('catalog1.fits')
cat2 = Table.read('catalog2.fits')

# 建立座標物件
coords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)
coords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)

# 尋找比對
idx, sep, _ = coords1.match_to_catalog_sky(coords2)

# 依分離閾值篩選
max_sep = 1 * u.arcsec
matches = sep < max_sep

# 建立比對後的星表
cat1_matched = cat1[matches]
cat2_matched = cat2[idx[matches]]
print(f"找到 {len(cat1_matched)} 組比對")

最佳實務

1. 始終使用單位：將單位附加到量值，以避免錯誤並確保量綱一致性
2. 對 FITS 檔案使用上下文管理器：確保檔案正確關閉
3. 偏愛陣列而非迴圈：將多個座標/時間作為陣列處理以獲得更好的效能
4. 檢查座標框架：在轉換前驗證框架
5. 使用適當的宇宙學：為您的分析選擇正確的宇宙學模型
6. 處理缺失資料：對具有缺失值的表格使用遮罩列
7. 明確指定時間尺度：對於精確計時，要明確時間尺度（UTC、TT、TDB）
8. 使用 QTable 進行單位感知的表格操作：當表格列具有單位時
9. 檢查 WCS 有效性：在使用轉換前驗證 WCS
10. 快取常用值：昂貴的計算（例如宇宙學距離）可以快取
11. 明確網路存取：SkyCoord.from_name()、EarthLocation.of_site(refresh_cache=True)、EarthLocation.of_address()、download_file()、遠端 FITS 讀取以及一些 IERS 時間/座標轉換可能會聯絡外部服務或更新本地快取。避免將敏感的目標名稱、位址、URL 或專有檔案位置傳送給第三方服務。在處理潛在敏感目標或資料位置時，請在使用者進行這些網路呼叫之前與使用者確認。
12. 為可重現性固定版本：在共享環境中使用固定版本，例如 astropy==7.2.0；在審閱版本說明後有意識地更新固定版本。

當前版本資訊

• 研究時的當前穩定版本：Astropy 7.2.0（發布於 2025-11-25；驗證截至 2026-06-10 為當前版本）
• Python 要求：3.11+
• Astropy 8.0 處於候選發布階段（8.0.0rc1，2026-05-26）。預期的關鍵變更：
  • 已棄用的 astropy.cosmology 子模組填充（astropy.cosmology.flrw、.core、.funcs、.connect、.parameter）已移除——直接從 astropy.cosmology 導入所有內容（例如 from astropy.cosmology import FlatLambdaCDM, z_at_value）
  • astropy.constants 預設值從 CODATA 2018 變更為 CODATA 2022；如果可重現性很重要，請透過 astropyconst 科學狀態固定常數版本
  • NumPy 2.0 成為最低支援版本；7.2.x LTS 分支將在 8.0 發布後保留 NumPy 1.x 支援六個月
  • 內建的測試執行器（astropy.test()、TestRunner）已正式棄用——直接呼叫 pytest
• 在新程式碼中要避免的近期 7.x 棄用專案：將表格索引識別碼作為第一個 .loc 元素傳遞（t.loc["b", 2]）——改用 t.loc.with_index("b")[2]（計劃在 9.0 中移除）；astropy.utils.isiterable()——改用 numpy.iterable()
• 近期 7.0 的移除：較舊的已棄用 FITS API，例如 (Bin)Table.update、_ExtensionHDU、_NonstandardExtHDU 和 CompImageHDU 的 tile_size 參數；CompImageHeader 已棄用。在 new examples 中避免使用這些舊式模式。
• 建議的選用擴展是 recommended 用於常見的繪圖/科學相依性，而 all 僅在需要廣泛的選用功能集時使用。

文件和資源

• 官方 Astropy 文件：https://docs.astropy.org/en/stable/
• 教學：https://learn.astropy.org/
• GitHub：https://github.com/astropy/astropy

參考檔案

有關特定模組的詳細資訊：

• references/units.md - 單位、量值、轉換和等價關係
• references/coordinates.md - 座標系統、轉換和星表比對
• references/cosmology.md - 宇宙學模型和計算
• references/fits.md - FITS 檔案操作和處理
• references/tables.md - 表格建立、I/O 和操作
• references/time.md - 時間格式、尺度和計算
• references/wcs_and_other_modules.md - WCS、NDData、建模、視覺化、常數和工具

引用科學代理技能

此技能是 Scientific Agent Skil 的一部分

…

[為翻譯而截斷]