# 高纯度星表产品说明

本目录存放本项目处理后形成的高纯度星表产品。发布产品按目标类别组织为三类：QSO、GALAXY 和 STAR。每一类提供一张总表作为正式引用对象，同时提供按天区拆分的子表，便于按观测区域下载和使用。

## 产品组成

正式发布包含以下三张主表：

- `qso_high_purity_catalog`
- `galaxy_high_purity_catalog`
- `star_high_purity_catalog`

每张主表同时提供 Parquet 和压缩 CSV 两种格式：

- Parquet 文件用于完整数据分析和保持字段类型；
- CSV.gz 文件用于通用读取、快速查看和跨平台交换。

按天区拆分的文件作为同一版本的派生产品，不作为独立版本引用。用户在论文或数据产品中引用本发布时，应优先引用三张主表及其版本号。

## 目录结构

```text
data_catalog_release/
  catalogs/
    qso/
      qso_high_purity_catalog.parquet
      qso_high_purity_catalog.csv.gz
      qso_cosmos_priority_candidates.parquet
      qso_cosmos_priority_candidates.csv.gz
      by_field/
    galaxy/
      galaxy_high_purity_catalog.parquet
      galaxy_high_purity_catalog.csv.gz
      by_field/
    star/
      star_high_purity_catalog.parquet
      star_high_purity_catalog.csv.gz
      by_field/
  docs/
    README_CATALOGS_zh.md
    catalog_schema.csv
    catalog_inventory.csv
    field_counts.csv
    SHA256SUMS.txt
```

其中 `by_field/` 子目录用于存放按天区拆分后的同源子表。子表均从对应主表直接筛选得到，不重新计算分数或阈值。

## 天区拆分原则

本版本同时发布总表和按天区子表。总表用于保证产品口径清晰、版本唯一、引用简单；按天区子表用于满足实际观测和下载需求，特别是用户只关注某个指定天区时，可以避免读取完整星表。

按天区拆分时，保留主表中的全部关键字段，包括 Gaia DR3 `source_id`、坐标、天区、评分、阈值、选择标记、消光分箱、验证标签、数据来源和质量控制字段。

## QSO 产品说明

QSO 主表是本项目的主要科学产品。该表给出 Gaia 源级别的高纯度 QSO 候选体，适用于后续光谱观测候选源选择、天区内目标优先级排序和选择函数复核。

QSO 主表对应论文中的推荐高纯度工作点。阈值按三档前景消光分箱给出，并在表中保留每个源使用的分箱和阈值。表内的纯度和完备度解释应限定在本项目的冻结光谱标记基准内，不应直接外推为全天 QSO 面密度或全天完备度。

COSMOS 深场对象作为 QSO 产品下的伴随优先级表单独发布，即 `qso_cosmos_priority_candidates`。该表不与主验证星表混同解释。COSMOS 表的含义是深场中的高优先级候选清单，而不是 COSMOS 全部 AGN 或 QSO 的完备样本。

## GALAXY 和 STAR 产品说明

GALAXY 和 STAR 表是同一处理框架下形成的辅助分类产品。它们用于提供高纯度星系和恒星候选源，并可作为 QSO 候选源分析中的污染源诊断和质量控制参考。

这两类产品当前不包含 COSMOS 天区。`catalog_inventory.csv` 和 `field_counts.csv` 中按实际发布范围记录天区和行数，避免将其解释为深场分类产品。

GALAXY 表的测试集纯度略低于 0.98 的目标线，应保持保守表述：该产品主要体现相对于 Gaia DR3 参考分类的更高标签恢复率，而不是声明为严格 0.98 纯度星系总表。

STAR 表在当前基准中表现更稳定，可作为恒星候选层和前景污染诊断层使用。尽管如此，该表仍应按本项目的天区、输入特征和验证标签范围解释，不应外推为全天恒星星表。

## 字段说明

完整字段定义见 `catalog_schema.csv`。字段组包括：

- `identifiers`：源标识、坐标、天区；
- `field`：天区名称、天区层级、样本角色；
- `features`：Gaia、光学、红外和消光相关特征；
- `scores`：项目计算得到的类别评分；
- `thresholds`：阈值模式、阈值数值、选择标记；
- `validation`：光谱标签、红移、验证样本划分；
- `provenance`：数据来源、处理版本、模型和阈值版本；
- `multiwavelength_support`：多波段支持信息，主要用于 COSMOS 伴随表。

发布表中保留验证和来源字段。即使普通用户只使用候选清单，这些字段仍是复核选择函数和追踪样本来源的必要信息。

## 使用建议

常规使用时，建议优先使用各类别主表中的推荐高纯度选择标记。用户可根据观测资源进一步按评分排序，或结合天区、星等、消光、输入特征覆盖情况进行二次筛选。

对于需要严格控制污染的观测计划，应优先采用保守阈值标记。对于光纤资源较充足、希望提高候选源覆盖率的计划，可参考评分排序扩展目标清单。

不同天区的验证强度不同。核心验证天区的纯度和完备度指标可用于论文中的主要性能解释；应用天区和 COSMOS 深场应按各自说明理解，不能直接作为全天源密度或全天完备度估计。

## 发布完整性检查

正式发布前应完成以下检查：

- 三类主表均可正常读取；
- Parquet 和 CSV.gz 行数一致；
- 按天区子表的总行数与对应主表一致；
- `catalog_inventory.csv` 记录每个文件的行数、列数、格式和说明；
- `field_counts.csv` 记录每类产品在各天区的行数；
- `catalog_schema.csv` 覆盖所有发布字段；
- `SHA256SUMS.txt` 包含发布文件的校验值；
- 不包含上游原始大文件、临时文件、缓存文件或未完成下载文件。

## 引用口径

引用本数据产品时，应注明使用的版本号、目标类别和选择标记。例如：

```text
QSO high-purity catalog, release 20260521-V3, selected with the recommended conservative flag.
```

若使用按天区子表，应同时注明该子表来自同一版本的主表筛选结果。

## 本版本文件概览

- QSO 主表：13,785 行；按天区子表 4 个。
- QSO COSMOS 优先级表：39 行；单独解释为深场优先级清单。
- GALAXY 主表：17,752 行；按天区子表 6 个。
- STAR 主表：96,667 行；按天区子表 6 个。

本版本的文件清单、字段说明、天区行数和校验值分别见 `catalog_inventory.csv`、`catalog_schema.csv`、`field_counts.csv` 和 `SHA256SUMS.txt`。
