amsStylePlot - AMS实验风格科学绘图工具

一个专门为AMS（Alpha Magnetic Spectrometer）实验数据分析设计的Python绘图工具包，提供符合高能物理学期刊标准的科学绘图功能。

📖 项目简介

amsStylePlot 是一个基于ROOT框架的科学绘图工具，专门用于处理和可视化AMS宇宙射线探测器的数据。该工具包提供了标准化的绘图风格，支持多子图布局、时间序列数据绘制和误差分析可视化。

🎯 主要特性

• AMS标准绘图风格：符合高能物理学期刊要求的专业图表样式
• 多子图支持：灵活的多面板布局，支持任意数量的子图
• 时间序列绘图：专门优化的时间轴处理和日期格式化
• 误差分析：完整的统计、系统和时间相关误差可视化
• 高质量输出：支持PDF和PNG格式的高分辨率图像输出
• 宇宙射线数据处理：针对质子流强和刚度谱分析的专用功能

🚀 快速开始

环境要求

• Python 3.7+
• ROOT 6.0+ (CERN ROOT Data Analysis Framework)
• NumPy
• pandas
• datetime

安装

1. 克隆项目仓库：

git clone https://github.com/yourusername/amsStylePlot.git
cd amsStylePlot

2. 确保已安装ROOT框架：

# 在Ubuntu/Debian系统上
sudo apt-get install root-system

# 或者使用conda
conda install -c conda-forge root

3. 安装Python依赖：

pip install numpy pandas

基本使用

from amsStylePlot import amsStylePlot
import ROOT

# 创建画布和数据
x_data = [1, 2, 3, 4, 5]
y_data = [2.1, 3.8, 5.2, 7.1, 8.9]
errors = [0.1, 0.2, 0.1, 0.3, 0.2]

# 使用amsStylePlot绘制图表
graph = amsStylePlot(
    x_data=x_data,
    y_data=y_data,
    errors=errors,
    x_title="X轴标题",
    y_title="Y轴标题",
    output_path="output.pdf",
    n_subplots=1,
    subplot_idx=1
)

📁 项目结构

amsStylePlot/
├── amsStylePlot.py         # 核心绘图模块
├── main.py                 # 主程序示例
├── data/                   # 数据文件目录
│   ├── 2011-01-01-2024-07-31_hourly_FDs_pred_ams.csv  # AMS小时流强数据
│   ├── maximum_error_data.csv                          # 最大误差数据
│   └── table-s1-s2824.csv                             # AMS质子流强历史数据
├── test_outputs/           # 输出结果目录
│   ├── real_data_test_n4_m2.pdf                      # 示例输出(PDF)
│   └── real_data_test_n4_m2.png                      # 示例输出(PNG)
└── README.md              # 项目说明文档

🔬 科学背景

AMS实验简介

Alpha Magnetic Spectrometer (AMS-02) 是安装在国际空间站上的精密宇宙射线探测器，用于研究宇宙射线的组成、能谱和时间变化。该项目处理的数据包括：

• 质子流强数据：测量不同刚度区间的质子流强随时间的变化
• 刚度谱分析：覆盖1-100 GV的30个刚度区间
• 误差分析：包括统计误差、系统误差和时间相关误差

数据说明

1. 质子流强数据 (table-s1-s2824.csv)

• 时间范围：2011年5月20日至2024年7月31日
• 刚度区间：30个区间，1.00-100 GV
• 数据类型：质子流强及其统计、时间相关和系统误差
• 单位：m⁻²sr⁻¹s⁻¹GV⁻¹

2. 小时流强数据 (2011-01-01-2024-07-31_hourly_FDs_pred_ams.csv)

• 时间分辨率：1小时
• 数据内容：预测的禁戒深度(Forbush Decrease)数据
• 用途：分析宇宙射线流强的短期变化

3. 误差分析数据 (maximum_error_data.csv)

• 内容：各刚度区间的标准偏差
• 用途：误差带绘制和不确定性分析

🎨 绘图功能详解

核心函数：amsStylePlot

def amsStylePlot(x_data, y_data, errors=None, x_title="", y_title="", 
                output_path="", n_subplots=1, subplot_idx=1, **kwargs):
    """
    AMS风格绘图函数
    
    参数:
        x_data: X轴数据数组
        y_data: Y轴数据数组  
        errors: 误差数据数组（可选）
        x_title: X轴标题
        y_title: Y轴标题
        output_path: 输出文件路径
        n_subplots: 总子图数量
        subplot_idx: 当前子图编号
    
    返回:
        ROOT.TGraphErrors: 创建的图形对象
    """

特色功能

1. 多子图布局

• 自动计算子图边距和间距
• 支持任意数量的垂直排列子图
• 智能的轴标签和标题位置调整

2. 时间轴处理

from amsStylePlot import datetime_to_root_time

# 将Python datetime转换为ROOT时间格式
root_time = datetime_to_root_time(datetime_obj)

3. 误差带绘制

• 支持对称和非对称误差
• 自动颜色和样式配置
• 透明度控制

4. 专业样式

• 黑色背景主题
• 高对比度配色方案
• 符合期刊标准的字体和线宽

📊 使用示例

示例1：基本质子流强绘图

import pandas as pd
from amsStylePlot import amsStylePlot

# 读取数据
data = pd.read_csv('data/table-s1-s2824.csv')

# 选择特定刚度区间的数据
rigidity_data = data[(data['rigidity_min GV'] == 1.0) & 
                    (data['rigidity_max GV'] == 1.16)]

# 绘制流强随时间的变化
amsStylePlot(
    x_data=range(len(rigidity_data)),
    y_data=rigidity_data['proton_flux m^-2sr^-1s^-1GV^-1'].values,
    errors=rigidity_data['proton_flux_error_statistical m^-2sr^-1s^-1GV^-1'].values,
    x_title="时间 (天)",
    y_title="质子流强 (m^{-2}sr^{-1}s^{-1}GV^{-1})",
    output_path="proton_flux_time_series.pdf"
)

示例2：多刚度区间对比

# 创建4个子图，比较不同刚度区间
rigidity_bins = [(1.0, 1.16), (2.15, 2.40), (5.37, 5.90), (48.5, 69.7)]

for i, (r_min, r_max) in enumerate(rigidity_bins):
    subset = data[(data['rigidity_min GV'] == r_min) & 
                  (data['rigidity_max GV'] == r_max)]
    
    amsStylePlot(
        x_data=range(len(subset)),
        y_data=subset['proton_flux m^-2sr^-1s^-1GV^-1'].values,
        errors=subset['proton_flux_error_statistical m^-2sr^-1s^-1GV^-1'].values,
        x_title="时间 (天)" if i == 3 else "",
        y_title=f"流强 ({r_min:.2f}-{r_max:.2f} GV)",
        output_path="multi_rigidity_comparison.pdf",
        n_subplots=4,
        subplot_idx=i+1
    )

🔧 高级配置

自定义样式参数

# 通过kwargs传递ROOT绘图参数
amsStylePlot(
    x_data=x_data,
    y_data=y_data,
    marker_style=20,      # 圆形标记
    marker_size=0.8,      # 标记大小
    line_color=2,         # 红色线条
    line_width=2,         # 线宽
    fill_color=3,         # 填充颜色
    fill_alpha=0.3        # 透明度
)

输出格式控制

# 同时输出PDF和PNG格式
amsStylePlot(
    ...,
    output_path="result.pdf",
    save_png=True,        # 同时保存PNG
    dpi=300              # PNG分辨率
)

📈 数据分析工作流

1. 数据预处理：使用pandas读取和清洗AMS数据
2. 时间序列分析：提取特定时间段和刚度区间的数据
3. 误差分析：计算和可视化统计、系统误差
4. 多维对比：创建多子图布局比较不同条件
5. 高质量输出：生成符合期刊标准的图表

👨‍💻 作者信息

• 作者：Pengwei Zhao
• 邮箱：pengwei.zhao@cern.ch
• 机构：CERN (欧洲核子研究中心)

🤝 贡献指南

欢迎提交问题报告和功能建议！如果您想贡献代码：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• CERN ROOT团队提供的优秀绘图框架
• AMS实验合作组提供的宝贵科学数据
• 高能物理学社区的技术支持和反馈

📚 相关资源

• CERN ROOT官方文档
• AMS实验官网
• 高能物理绘图标准

---

注意：本工具专门为AMS实验数据分析设计，某些功能可能需要根据具体的数据格式和分析需求进行调整。如有问题，请联系作者或提交Issue。