# grouping

**Repository Path**: coding_playground/grouping

## Basic Information

- **Project Name**: grouping
- **Description**: 这是一个用于动物模型实验中自动分组的工具，能够根据动物的体重、肿瘤体积等指标，使用模拟退火算法实现均衡分组，确保各组之间的差异最小化。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: gradio_version
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-11
- **Last Updated**: 2025-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 动物模型自动分组程序

这是一个用于动物模型实验中自动分组的工具，能够根据动物的体重、肿瘤体积等指标，使用模拟退火算法实现均衡分组，确保各组之间的差异最小化。

## 功能特点

- 支持两种试验类型：药效试验(efficacy)和毒理试验(toxicity)
- 基于模拟退火算法实现最优分组，确保各组间指标均衡
- 支持读取历史分组数据，为新动物分配最佳分组
- 自动计算并保存各组统计信息(平均值、标准差等)
- 支持配置文件自定义参数
- 提供命令行接口和Gradio Web界面

## 安装指南

### 1. 确保已安装Python

本程序需要Python 3.6或更高版本。如果尚未安装Python，请先下载并安装：https://www.python.org/downloads/

### 2. 安装依赖包

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

依赖包包括：
- pandas：数据处理
- numpy：数值计算
- random、math：算法实现
- logging：日志记录
- argparse：命令行参数解析
- configparser：配置文件读取
- gradio：Web界面(可选)

## 使用方法

### 命令行方式

```bash
python grouping.py <input_file> [options]
```

#### 参数说明

- `input_file`：原始数据CSV文件路径（必需）
- `--last_grouping`：上一次分组结果的CSV文件路径（可选）
- `--config_dir`：配置文件目录，默认为当前目录（可选）
- `--experiment_type`：试验类型，可选值为'efficacy'(药效试验)或'toxicity'(毒理试验)，默认为'efficacy'（可选）

#### 示例

1. 药效试验分组
```bash
python grouping.py test.csv --experiment_type efficacy
```

2. 毒理试验分组
```bash
python grouping.py test.csv --experiment_type toxicity
```

3. 使用历史分组数据
```bash
python grouping.py new_mice.csv --last_grouping results/old_mice/grouped_mouse_data_run1.csv --experiment_type efficacy
```

### Web界面方式

通过Gradio提供的Web界面可以更直观地使用程序：

```bash
python gradio_interface.py
```

或使用启动脚本：

```bash
python launch_gradio.py
```

启动后，可以通过浏览器访问界面进行操作。

## 数据格式要求

程序支持的CSV文件需要包含以下字段：

### 通用字段
- `id`或`ear_tag`：动物耳标或编号
- `weight`：体重

### 试验类型特定字段
- 药效试验(efficacy)：
  - `tumor_volume`：肿瘤体积
- 毒理试验(toxicity)：
  - `gender`：性别，值为'F'(雌性)或'M'(雄性)

## 配置文件说明

程序使用两个配置文件：

### 1. group.ini

```ini
[grouping]
num_groups = 5          # 分组数量
group_sizes = 6,6,6,6,6 # 每组动物数量，用逗号分隔
runs = 10               # 运行次数，取最优结果
```

### 2. config.ini

```ini
[simulated_annealing]
initial_temp = 100      # 初始温度
final_temp = 0.1        # 最终温度
alpha = 0.95            # 降温系数
max_iter = 10000        # 最大迭代次数
```

## 分组算法说明

程序采用模拟退火算法进行分组优化，主要步骤如下：

1. **初始分组**：将动物均匀分配到各组
2. **计算统计量**：计算各组的体重和肿瘤体积的平均值和标准差
3. **评估分组质量**：使用目标函数评估分组方案的均衡性
4. **模拟退火优化**：通过随机交换动物并逐步降低温度，寻找最优分组方案
5. **结果保存**：保存分组结果和统计信息

## 结果输出

程序会在`results`文件夹下创建与输入文件同名的子文件夹，并保存以下结果文件：

- `grouped_mouse_data_run{run_number}.csv`：包含分组信息的动物数据
- `group_stats_run{run_number}.csv`：各组统计信息，包括平均值、标准差、动物数量和目标函数值

## 函数说明

### 核心函数

#### read_mouse_data(file_path, experiment_type)
从CSV文件读取动物数据并根据试验类型验证必要字段

#### calculate_group_stats(groups, data)
计算每个组的肿瘤体积和体重的平均值和标准差

#### objective_function(stats, overall_volume_mean, overall_volume_std, overall_weight_mean, overall_weight_std, experiment_type)
计算目标函数值，评估分组均衡性

#### simulated_annealing(data, num_groups, initial_temp, final_temp, alpha, max_iter, overall_weight_mean, overall_weight_std, overall_volume_mean, overall_volume_std, experiment_type)
使用模拟退火算法优化分组方案

#### read_last_grouping(file_path)
从CSV文件读取上一次的分组结果

#### find_best_group_for_new_mice(groups, new_mice_indices, data, experiment_type)
为多个新动物找到最佳分组，基于已有的历史分组

#### save_results(data, groups, result_folder, run_number, overall_stats, experiment_type)
保存分组结果和统计信息

## 日志记录

程序会输出日志信息，包括：
- 数据读取情况
- 总体统计信息
- 分组过程
- 结果保存路径
- 错误信息

## 注意事项

1. 确保输入数据格式正确，特别是必要字段的名称和格式
2. 对于毒理试验，性别字段只能包含'F'和'M'
3. 当动物数量无法平均分配到各组时，程序会尽量使各组数量接近
4. 分组结果的优劣可以通过目标函数值判断，值越小表示分组越均衡

## 问题反馈

如有任何问题或建议，请联系开发人员。