# TomurAUC

**Repository Path**: coding_playground/tomurauc

## Basic Information

- **Project Name**: TomurAUC
- **Description**: TumorAUC是一个专业的肿瘤生长动力学分析工具，使用曲线下面积(AUC)方法来量化和比较实验动物中肿瘤生长的动力学特征。该工具基于Duan等人(2012)的方法，可处理删失数据，并生成高质量的统计分析和可视化结果。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-06
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TumorAUC: 肿瘤生长动力学分析工具

TumorAUC是一个专业的肿瘤生长动力学分析工具，使用曲线下面积(AUC)方法来量化和比较实验动物中肿瘤生长的动力学特征。该工具基于Duan等人(2012)的方法，可处理删失数据，并生成高质量的统计分析和可视化结果。

## 功能特点

- 计算总AUC和分段AUC，用于分析不同时间段的肿瘤生长动态
- 处理删失数据，对实验结束前死亡的动物进行适当的数据处理
- 提供Mann-Whitney U检验统计分析方法，自动执行Control组与所有实验组的比较
- 统计显著性标记：自动根据p值添加显著性标记（*、**、***、ns）
- 详细的统计检验日志：记录所有比较组的p值和显著性水平
- 支持多种图表类型：箱型图、柱状图、小提琴图、散点图和蜂群图
- 自定义颜色方案，支持多种内置调色板和自定义颜色
- 同一组数据在所有图表中保持一致的颜色，便于比较和解读
- 体重变化分析功能：自动计算每只小鼠的体重变化百分比
- 体重曲线可视化：展示各组体重随时间的变化趋势
- 体重变化统计：支持多种图表展示不同实验组间的体重变化比较
- 详细的体重数据导出：包括个体小鼠和小组平均体重变化数据
- 体重稳定性(RMSD)分析：计算每只小鼠体重的均方根偏差，评估体重波动程度

## 安装

### 依赖项

TumorAUC需要以下Python库：

- pandas
- numpy
- scipy
- matplotlib
- seaborn
- argparse

### 安装命令

```bash
pip install pandas numpy scipy matplotlib seaborn
```

## 使用方法

### 命令行使用

```bash
python tumorauc.py --input 数据文件.csv --seg 分段数目 --fig 图表类型 --palette 颜色方案 --metric 分析指标
```

#### 参数说明

- `--input`: 包含肿瘤生长数据的CSV文件路径（默认为'sample_tumor_data.csv'）
- `--seg`: 分段数目，用于将实验期平均分成若干段（默认为3）
- `--fig`: 图表类型，可选值：box(箱型图)、bar(柱状图)、strip(散点图)、violin(小提琴图)、swarm(蜂群图)（默认为box）
- `--palette`: 颜色方案，支持多种内置调色板和自定义颜色（默认为husl）
- `--metric`: 分析指标，可选值：tumor(肿瘤体积)、weight(体重)（默认为tumor）

### 输入数据格式

输入CSV文件应包含以下列：

- `mouse_id`: 小鼠的唯一标识符
- `group`: 实验组名称
- `day`: 测量的时间点（天）
- `tumor_volume_mm3`: 肿瘤体积测量值
- `weight_g`: 小鼠体重测量值（可选，如果提供，将进行体重分析）

### 示例数据

项目中包含了示例数据文件`sample_tumor_data.csv`，可用于测试和参考。

## 配色方案

TumorAUC支持多种配色方案，以下是每种方案的示例和说明：

### 1. husl（默认）

HUSL(Harmonic Unified Standard Lightness)配色方案提供均匀分布的色相，在视觉上平衡且和谐。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette husl
```

**示例图：**
- 肿瘤生长曲线：`example_palette_husl_tumor_growth_curves.png`
- 总AUC比较：`example_palette_husl_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_husl_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_husl_segmented_auc_14-28_comparison_bar.png`

### 2. tab10

Tab10是一种离散的分类配色方案，包含10个不同的颜色，颜色对比明显，适合多组数据的可视化。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette tab10
```

**示例图：**
- 肿瘤生长曲线：`example_palette_tab10_tumor_growth_curves.png`
- 总AUC比较：`example_palette_tab10_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_tab10_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_tab10_segmented_auc_14-28_comparison_bar.png`

### 3. Set2

Set2是一种适用于分类数据的配色方案，颜色柔和且易于区分，特别适合科学出版物。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette Set2
```

**示例图：**
- 肿瘤生长曲线：`example_palette_Set2_tumor_growth_curves.png`
- 总AUC比较：`example_palette_Set2_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_Set2_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_Set2_segmented_auc_14-28_comparison_bar.png`

### 4. viridis

Viridis是一种从蓝色到绿色再到黄色的渐变色方案，具有良好的色彩感知度和色盲友好性。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette viridis
```

**示例图：**
- 肿瘤生长曲线：`example_palette_viridis_tumor_growth_curves.png`
- 总AUC比较：`example_palette_viridis_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_viridis_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_viridis_segmented_auc_14-28_comparison_bar.png`

### 5. plasma

Plasma是一种从蓝色到紫色再到黄色的渐变色方案，视觉冲击力强，适合强调数据差异。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette plasma
```

**示例图：**
- 肿瘤生长曲线：`example_palette_plasma_tumor_growth_curves.png`
- 总AUC比较：`example_palette_plasma_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_plasma_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_plasma_segmented_auc_14-28_comparison_bar.png`

### 6. custom

自定义配色方案，使用预定义的10种科学期刊常用颜色。

```bash
python tumorauc.py --input sample_tumor_data.csv --fig bar --palette custom
```

**示例图：**
- 肿瘤生长曲线：`example_palette_custom_tumor_growth_curves.png`
- 总AUC比较：`example_palette_custom_total_auc_comparison_bar.png`
- 0-14天AUC比较：`example_palette_custom_segmented_auc_0-14_comparison_bar.png`
- 14-28天AUC比较：`example_palette_custom_segmented_auc_14-28_comparison_bar.png`

## 输出文件

程序会自动创建一个带时间戳的`result`文件夹（格式为`result/YYYYMMDD_HHMMSS`），并将所有输出文件保存在该文件夹中。

### 图表输出

- `tumor_growth_curves.png`: 肿瘤生长曲线图表（当--metric=tumor时生成）
- `total_<metric>_auc_comparison_<图表类型>.png`: 总AUC比较图表（metric为tumor或weight）
- `segmented_<metric>_auc_<开始天>-<结束天>_comparison_<图表类型>.png`: 每个时间段的分段AUC比较图表（metric为tumor或weight）
- `body_weight_curves.png`: 体重变化曲线图表
- `weight_change_comparison_<图表类型>.png`: 体重变化百分比比较图表

### 数据输出

- `individual_mouse_auc_data.csv`: 包含每只小鼠的总AUC和分段AUC数据的CSV文件
- `group_average_auc_data.csv`: 包含各实验组平均AUC值的CSV文件
- `individual_mouse_weight_change.csv`: 包含每只小鼠的体重变化数据的CSV文件
- `group_average_weight_change.csv`: 包含各实验组平均体重变化数据和体重RMSD(均方根偏差)的CSV文件，用于评估体重稳定性

## 配色方案示例生成器

项目包含了一个配色方案示例生成器脚本 `color_palette_examples.py`，可以自动为所有配色方案生成示例图表：

```bash
python color_palette_examples.py
```

运行此脚本后，将在当前目录生成所有配色方案的示例图表，文件名格式为：`example_palette_<配色方案>_<图表类型>.png`。这样您可以直观地比较不同配色方案的效果，选择最适合您研究数据的配色方案。

## 示例

### 示例1：使用默认设置

```bash
python tumorauc.py
```

这将使用默认的样本数据、3个时间段、箱型图、husl配色方案和tumor指标。

### 示例2：自定义分段数目和图表类型

```bash
python tumorauc.py --seg 4 --fig violin
```

这将使用4个时间段和小提琴图来可视化结果。

### 示例3：使用特定的输入文件和配色方案

```bash
python tumorauc.py --input my_tumor_data.csv --palette tab10
```

这将使用指定的输入文件和tab10配色方案。

### 示例4：使用weight指标分析体重变化

```bash
python tumorauc.py --metric weight --fig bar
```

这将使用体重作为分析指标，并使用柱状图展示结果。

## 颜色一致性

TumorAUC确保同一组数据在所有图表中使用相同的颜色，这有助于保持结果的一致性和可读性。颜色映射在分析初始化时创建，并在所有后续图表中保持一致。

## 引用

如果您在研究中使用TumorAUC，请引用以下文献：

Duan, F., et al. (2012). Area under the curve as a tool to measure kinetics of tumor growth in experimental animals. Journal of Immunological Methods, 382(1-2), 224-228.

## 许可证

GPL-3.0

## 联系方式

如有问题或建议，请在此项目页面提交issue。