# CellAUC

**Repository Path**: coding_playground/cellauc

## Basic Information

- **Project Name**: CellAUC
- **Description**: CellAUC 是一个专为评价化合物抑制细胞系活性而设计的Python分析工具包。它基于曲线下面积（AUC）方法，可处理时间依赖性和剂量依赖性细胞实验数据，提供全面的统计分析和高质量可视化功能。
- **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-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CellAUC: 化合物抑制细胞系活性评价工具

**CellAUC** 是一个专为评价化合物抑制细胞系活性而设计的Python分析工具包。它基于曲线下面积（AUC）方法，可处理时间依赖性和剂量依赖性细胞实验数据，提供全面的统计分析和高质量可视化功能，支持多化合物、多浓度和多细胞株的复杂实验设计。

## 功能特点

### 核心分析功能
- **总AUC计算**：计算完整时间或浓度范围内的曲线下面积
- **统计比较**：使用曼-惠特尼U检验进行组间比较，自动标记显著性差异
- **多细胞株分析**：支持按细胞株分组计算AUC，生成细胞株×化合物AUC矩阵
- **无对照组支持**：支持在没有对照组的情况下进行分析，提高灵活性

### 可视化功能
- **AUC汇总图表**：提供多种图表类型（箱型图、柱状图、散点图、小提琴图、蜂群图）
- **热力图展示**：生成细胞株×化合物AUC热力图，直观展示化合物在不同细胞株上的活性

### 数据处理与输出
- **示例数据生成**：提供模拟的时间依赖性和剂量依赖性数据用于测试，支持生成包含多个细胞株的示例数据
- **完整结果导出**：自动生成CSV数据文件和高质量PNG图表
- **统计显著性标记**：自动计算并标记与对照组的显著性差异
- **矩阵数据导出**：导出细胞株×化合物AUC矩阵，方便进一步分析

## 安装

### 前提条件
- Python 3.8 或更高版本
- 必要的Python库

### 安装步骤

1. 克隆或下载此仓库到本地
2. 安装所需的Python库

```bash
pip install -r requirements.txt
```

## 使用方法

### 命令行接口

CellAUC提供了命令行接口，可直接运行分析并生成结果：

```bash
python cellauc.py --type dose --fig box --palette husl
```

#### 命令行参数
- `--input`: 输入CSV文件路径（可选，不提供则生成示例数据）
- `--type`: 分析类型（`time` 或 `dose`）
- `--fig`: 绘图类型（`box`, `bar`, `strip`, `violin`, `swarm`）
- `--palette`: 颜色方案（`husl`, `tab10`, `Set2`, `viridis`, `plasma`等）
- `--by-cell-line`: 启用按细胞株分组分析（默认关闭）
- `--sample-data-with-cell-lines`: 生成包含多个细胞株的示例数据（默认关闭）

#### 使用示例

基础剂量依赖性分析：
```bash
python cellauc.py --input your_data.csv --type dose --fig bar
```

按细胞株分组的剂量依赖性分析：
```bash
python cellauc.py --input your_data.csv --type dose --fig box --by-cell-line
```

使用小提琴图进行多细胞株分析：
```bash
python cellauc.py --input your_data.csv --type dose --fig violin --by-cell-line
```

## 输入数据格式

### 时间依赖性实验数据格式

时间依赖性数据应包含以下列：

| well_id       | compound    | time_hour | viability_percentage |
|---------------|-------------|-----------|----------------------|
| Control_Rep1  | Control     | 0         | 100.2                |
| Control_Rep1  | Control     | 24        | 98.5                 |
| Control_Rep1  | Control     | 48        | 96.8                 |
| Compound_A_Rep1 | Compound_A | 0         | 101.3                |
| Compound_A_Rep1 | Compound_A | 24        | 85.2                 |
| Compound_A_Rep1 | Compound_A | 48        | 72.5                 |

### 剂量依赖性实验数据格式

剂量依赖性数据应包含以下列：

| well_id       | compound    | concentration_um | viability_percentage |
|---------------|-------------|------------------|----------------------|
| Control_Rep1  | Control     | 0.001            | 99.8                 |
| Control_Rep1  | Control     | 0.01             | 100.5                |
| Control_Rep1  | Control     | 0.1              | 99.2                 |
| Drug_X_Rep1   | Drug_X      | 0.001            | 98.2                 |
| Drug_X_Rep1   | Drug_X      | 0.01             | 85.6                 |
| Drug_X_Rep1   | Drug_X      | 0.1              | 45.3                 |

### 多细胞株实验数据格式

当进行多细胞株分析时，数据应包含额外的`cell_line`列：

| cell_line | compound    | concentration_um | well_id       | viability_percentage |
|-----------|-------------|------------------|---------------|----------------------|
| Cell_01   | Control     | 0.001            | Cell01_Control_Rep1 | 99.5 |
| Cell_01   | Control     | 0.01             | Cell01_Control_Rep1 | 100.2 |
| Cell_01   | Compound_A  | 0.001            | Cell01_CompoundA_Rep1 | 98.8 |
| Cell_01   | Compound_A  | 0.01             | Cell01_CompoundA_Rep1 | 75.3 |
| Cell_02   | Control     | 0.001            | Cell02_Control_Rep1 | 99.9 |
| Cell_02   | Compound_A  | 0.01             | Cell02_CompoundA_Rep1 | 82.5 |

## 输出结果说明

当以命令行方式运行时，CellAUC会在`result/[timestamp]`目录下生成以下结果：

### 数据文件
- `sample_cell_data_xxx.csv`：生成的示例数据（如果未提供输入文件）
- `individual_sample_auc_data.csv`：每个样本的AUC值
- `group_average_auc_data.csv`：各组的平均AUC值

### 多细胞株分析额外输出
当使用`--by-cell-line`参数时，还会生成：
- `compound_average_auc_data.csv`：每个化合物在所有细胞株上的平均AUC值
- `cell_line_average_auc_data.csv`：每个细胞株对所有化合物的平均AUC值
- `cell_line_compound_auc_matrix.csv`：细胞株×化合物AUC值矩阵

### 图表文件
- `total_auc_comparison_xxx.png`：总AUC比较图
- `cell_line_compound_auc_heatmap.png`：细胞株×化合物AUC热力图（仅在启用多细胞株分析时生成）

## 辅助工具

### 1. data_prepare.py

用于将简化格式的数据转换为CellAUC所需的复杂数据格式，支持从宽格式转换为长格式。

**功能说明**：将包含复合列名（如compound_concentration）的简单数据格式转换为标准的CellAUC输入格式，自动创建well_id列。

#### 使用方法
```bash
python data_prepare.py --input your_test.csv --output complex_cell_data.csv
```

#### 命令行参数
- `--input`: 输入的测试数据CSV文件路径（默认为test.csv）
- `--output`: 输出的复杂格式数据文件路径（默认为complex_cell_data.csv）

#### 输入输出示例
输入格式（test.csv）：
```
cell_line,compound1_0.001,compound1_0.01,compound2_0.001
Cell01,0.98,0.75,0.99
Cell02,1.01,0.82,0.97
```

输出格式（complex_cell_data.csv）：
```
cell_line,compound,concentration_um,well_id,viability_percentage
Cell01,compound1,0.001,Cell01_compound1_0.001_Rep1,98.0
Cell01,compound1,0.01,Cell01_compound1_0.01_Rep1,75.0
Cell01,compound2,0.001,Cell01_compound2_0.001_Rep1,99.0
```

### 2. merge_cell_info.py

用于将细胞株信息（如谱系、疾病类型等）合并到AUC矩阵中，生成包含更多生物学背景信息的分析数据。

#### 使用方法
```bash
python merge_cell_info.py --input cell_line_compound_auc_matrix.csv --info cell_info.csv --output merged_auc_matrix.csv
```

#### 命令行参数
- `--input`: 输入的AUC矩阵CSV文件路径
- `--info`: 包含细胞株信息的CSV文件路径
- `--output`: 输出的合并CSV文件路径

#### 输入文件格式
- **AUC矩阵文件**：包含细胞株列和各化合物的AUC值列
- **细胞信息文件**：包含细胞株列和相关生物学信息列（如lineage、disease等）

### 3. ranking.py

用于可视化细胞系-化合物AUC矩阵数据，支持按疾病类型着色，提供多种图表类型。

**功能说明**：加载包含细胞株、化合物AUC值和疾病信息的数据，生成按疾病类型着色的可视化图表，帮助分析化合物活性与疾病类型的关系。

#### 使用方法
```bash
python ranking.py --input merged_auc_matrix_with_info.csv --plot-type box --palette husl
```

#### 命令行参数
- `--input`, `-i`: 输入CSV文件路径，应包含细胞株、疾病类型和化合物AUC值
- `--output`, `-o`: 输出图形文件路径（可选）
- `--palette`, `-p`: 颜色方案，支持husl, tab10, Set2, viridis, plasma等（默认为husl）
- `--figsize`, `-f`: 图形大小，格式为"宽,高"（默认为"12,8"）
- `--plot-type`, `-t`: 绘图类型，支持scatter（散点图）、box（箱线图）、bar（条形图）（默认为box）
- `--cell-line-col`: 细胞系列名（默认为cell_line）
- `--disease-col`: 疾病列名（默认为disease）

#### 图表类型说明
- **散点图(scatter)**：每个点代表一个细胞系-化合物组合，直观展示所有数据点
- **箱线图(box)**：展示每个化合物在不同疾病类型中的分布，包含中位数、四分位数和异常值
- **条形图(bar)**：展示每个化合物在不同疾病类型中的平均值和标准差

## 应用场景

### 时间依赖性细胞毒性研究
- 评估化合物随时间推移的细胞毒性
- 比较不同化合物的时间依赖性效应
- 确定最佳实验终点时间

### 剂量-响应关系研究
- 比较不同化合物的效力
- 评估化合物的剂量-效应关系

### 多细胞株筛选研究
- 高通量筛选化合物对多种细胞株的活性
- 识别化合物的细胞株特异性效应
- 分析化合物在不同细胞背景下的效力差异
- 生成细胞株×化合物AUC矩阵，支持药物重定位和靶点验证研究

### 生物学背景整合分析
- 结合细胞株的谱系、疾病类型等信息，深入分析化合物活性与细胞生物学特征的关系
- 通过合并细胞信息，支持更复杂的分层分析和生物标志物发现

## 与TumorAUC的关系

CellAUC是基于TumorAUC项目的扩展，针对细胞系活性评价进行了优化：

1. **更适合细胞数据**：修改了数据结构和分析逻辑，更适合细胞实验数据
2. **增强的可视化**：优化了图表样式和统计标记

## 技术依赖

- **pandas**: 数据处理和分析
- **numpy**: 数值计算
- **scipy**: 科学计算（包括统计检验和曲线拟合）
- **matplotlib**: 基础绘图功能
- **seaborn**: 高级统计可视化

## 许可证

GPL-3.0

## 联系方式

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