# Embedding Atlas 项目说明

## 环境准备

项目使用 [uv](https://github.com/astral-sh/uv) 管理依赖，所有必需依赖已经记录在 `pyproject.toml` 的 `[project.dependencies]` 中。建议的设置流程如下：

```bash
# 可选：配置清华镜像（也可以写入 pyproject.toml 的 [tool.uv.pip]）
export UV_PIP_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# 同步依赖并创建虚拟环境（默认 .venv）
uv lock            # 首次或需要更新锁文件时执行
uv sync            # 生成或更新虚拟环境

# 进入虚拟环境
source .venv/bin/activate

# 或直接使用 uv run
uv run streamlit run app.py
```

如需固定镜像源，可在 `pyproject.toml` 中追加：

```toml
[tool.uv.pip]
index-url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
```

运行前如果需要离线或国内镜像 Hugging Face，可以设置：

```bash
export HF_HUB_OFFLINE=1
export HF_ENDPOINT=https://hf-mirror.com
```

## 命令行生成嵌入可视化交互

```bash
uv run embedding-atlas data/drugbank_pre_filtered_mordred_qed_id_selfies.csv --text smiles
uv run embedding-atlas data/drugbank_pre_filtered_mordred_qed_id_selfies.csv --export-application data/my_visualization.zip
```

`embedding-atlas` 更多用法示例：

```bash
# 本地文件
embedding-atlas dataset.parquet
# Hugging Face 数据集
embedding-atlas huggingface_org/dataset_name
# 指定文本列
embedding-atlas dataset.parquet --text text_column
# 使用预计算坐标
embedding-atlas dataset.parquet --x projection_x --y projection_y
```

## 划分 MolGen 第一轮微调数据集

```bash
uv run python script/split_drugbank.py \
  --in-csv data/drugbank_pre_filtered_mordred_qed_id_selfies.csv \
  --out-dir splits_v2 --seed 20250922 \
  --train-ratio 0.8 --val-ratio 0.1 --test-ratio 0.1 \
  --n_qed_bins 5 --n_mw_bins 5 --largest-first
```

产物：`split_train.csv` / `split_val.csv` / `split_test.csv`
其中 `split_val` 和 `split_test` 中的分子不会出现在训练集里，且整体 QED/MW 分布接近训练集，便于后续“用未见参考分子做条件生成并观察邻域覆盖”。

## 合并分割的数据集进行可视化

合并数据集：

```bash
uv run python script/merge_splits.py --input-dir splits_v2/ --output data/drugbank_split_merge.csv
```

可视化：

```bash
uv run embedding-atlas data/drugbank_split_merge.csv --text smiles
```