virtual_cell_biomed_ai_dataset

# Virtual Cell Biomedical AI Dataset Collector 这个工程用于在已有两个医学公开数据集目录之外，继续收集 Virtual Cell、single-cell、cell imaging、spatial omics、Perturb-seq、Cell Painting 等方向的数据集，并提供完整下载、校验、整理、dataset card 生成，以及上传到 ModelScope 私有 dataset repo 的工具链。 本项目不主动收集传统 EHR、ICU、胸片、CT、MRI、病理切片、临床表格等数据集，除非它们明确属于虚拟细胞、单细胞、细胞图像、空间组学或扰动实验方向，且没有出现在既有目录中。 ## Project Layout ```text configs/ datasets_registry.yaml excluded_existing_datasets.yaml modelscope.yaml.example scripts/ discover_datasets.py download_datasets.py validate_datasets.py build_manifest.py build_dataset_cards.py upload_to_modelscope.py src/dataset_ops/ data/ raw/ metadata/ logs/ docs/ ``` ## Setup ```bash pip install -r requirements.txt ``` 如果 Windows 上 `python` 不在 PATH 中，请先安装 Python 或把解释器加入 PATH，然后再运行下面的命令。 ## One-Command Auto Pipeline 当前推荐执行方式是先 dry-run，再由用户手动启动真实下载。pipeline 不依赖 preflight；preflight 失败不会阻止下载，真实下载由磁盘空间保护控制。 PowerShell 设置 ModelScope 环境变量： ```powershell $env:MODELSCOPE_TOKEN="你的token" $env:MODELSCOPE_NAMESPACE="你的namespace" $env:MODELSCOPE_DATASET_NAME="你的私有数据集仓库名" ``` 先 dry-run： ```bash python scripts/run_auto_pipeline.py --max-total-gb 380 --min-free-gb 20 --resume --upload --metadata-upload-always --dry-run ``` 真实执行： ```bash python scripts/run_auto_pipeline.py --max-total-gb 380 --min-free-gb 20 --resume --upload --metadata-upload-always ``` 查看状态： ```bash python scripts/status.py ``` 中断后继续运行同一条真实执行命令即可；`--resume` 会跳过已存在且大小匹配的 S3 对象，并对 HTTP 下载使用 Range 断点续传。下载器会在每个文件前检查 `--max-total-gb` 和 `--min-free-gb`，剩余空间低于保护线时停止新任务。 如果 ModelScope SDK 不能自动创建 private dataset repo，请先在 ModelScope 手动创建私有数据集仓库，再运行 pipeline。token 只从环境变量读取，不能写入代码或配置文件。 ## Exclusion List First 在生产使用前，先把两个已有医学数据集目录里的名称、别名、URL、accession 写入： ```text configs/excluded_existing_datasets.yaml ``` 发现脚本和人工更新 registry 时都必须查这个文件。命中同名或疑似同版本的数据集时，不要自动下载；同名不同版本也要标记为 `possible_duplicate` 后人工确认。 ## Add A New Dataset 在 `configs/datasets_registry.yaml` 新增条目时，必须填写所有字段。判断规则： - `access_level: A_direct`: 官方明确开放、无需注册、无需登录、无需申请、可脚本下载。 - `access_level: B_register`: 需要注册或登录。 - `access_level: C_application`: 需要 DUA、伦理培训、申请或审核。 - `access_level: D_partial`: 门户级集合、部分文件开放、需要人工选择版本/项目/前缀，或访问路径不适合直接全量自动下载。 只有 `A_direct` 且 `auto_download_allowed: true` 的数据集会进入自动下载队列。`complete_download_required` 必须保持 `true`，本项目不做抽样下载。 ## License And ModelScope Upload 上传 raw 数据前必须同时满足： - `access_level: A_direct` - `modelscope_raw_upload_allowed: true` - license 明确，不是 unknown/unclear - `redistribution_allowed` 或 `private_hosting_allowed` 至少一个为 true - 上游 license 没有禁止第三方托管、二次分发或私有平台保存 如果 license 不清楚，默认只上传 metadata、dataset card、官方入口、下载说明和引用方式，不上传 raw。即使 ModelScope repo 是私有仓库，也不能上传受控访问、登录后获取、DUA 限制、申请制、协议限制或患者级受限数据。 ## Discover Candidates ```bash python scripts/discover_datasets.py ``` 输出： ```text data/metadata/discovered_candidates.csv ``` 这个脚本只生成候选清单，不会自动写入下载队列。候选集必须人工确认后再加入 `datasets_registry.yaml`。 ## Dry Run Downloads ```bash python scripts/download_datasets.py --dry-run --all python scripts/download_datasets.py --dry-run --name DATASET_NAME ``` 真实下载前请确认存储空间、license、访问限制和完整镜像范围。本轮不要真实下载超过 1GB 的数据文件；大文件全量下载必须等人工确认后执行。 ## Preflight Size Check ```bash python scripts/download_datasets.py --preflight --all python scripts/download_datasets.py --preflight --all --max-total-gb 1000 --max-dataset-gb 200 ``` preflight 不会下载任何数据内容。HTTP/HTTPS URL 优先使用 `HEAD` 读取 `Content-Length`；`s3://` URL 使用匿名 public bucket listing 统计 prefix 下的文件数和大小。为避免超大桶一次扫描过久，默认每个 S3 URL 最多列出 1,000 个对象；达到上限时报告会把结果标为 lower bound。需要完整列举时可使用： ```bash python scripts/download_datasets.py --preflight --all --s3-max-objects 0 ``` 输出： ```text data/metadata/preflight_size_report.csv data/metadata/preflight_size_report.json ``` 如果超过 `--max-total-gb` 或 `--max-dataset-gb`，脚本只写 warning，不会真实下载。 ## Full Download And Resume ```bash python scripts/download_datasets.py --all --resume python scripts/download_datasets.py --name czi_subcell_opencell_evaluation --resume ``` 下载器支持 HTTP/HTTPS、FTP，以及通过 `fsspec` 访问公开 S3/GCS/FTP 路径。S3/GCS 需要安装 `s3fs`/`gcsfs`。每个任务失败后会写入日志并继续处理下一个数据集。 下载日志： ```text data/metadata/download_log.jsonl ``` ## Manifest ```bash python scripts/build_manifest.py ``` 输出： ```text data/metadata/manifest.jsonl data/metadata/summary.csv data/metadata/metadata.json ``` manifest 会扫描 `data/raw/` 下的本地文件并计算 sha256。没有 raw 文件时也会生成空 manifest 和 registry summary。 ## Dataset Cards ```bash python scripts/build_dataset_cards.py ``` 每个数据集会生成： ```text data/metadata/cards/DATASET_NAME/dataset_card.md ``` 如果不允许上传 raw，card 会明确写入： ```text Raw data is not redistributed in this ModelScope repository due to license or access restrictions. ``` ## ModelScope Private Upload 不要把 token 写进代码。使用环境变量： ```bash export MODELSCOPE_TOKEN="..." export MODELSCOPE_NAMESPACE="your_namespace" export MODELSCOPE_DATASET_NAME="your_private_dataset_repo" ``` Windows PowerShell: ```powershell $env:MODELSCOPE_TOKEN="..." $env:MODELSCOPE_NAMESPACE="your_namespace" $env:MODELSCOPE_DATASET_NAME="your_private_dataset_repo" ``` dry-run: ```bash python scripts/upload_to_modelscope.py --dry-run --metadata-only ``` 上传单个数据集： ```bash python scripts/upload_to_modelscope.py --dataset DATASET_NAME ``` 上传所有 registry 条目： ```bash python scripts/upload_to_modelscope.py --all ``` 如果 SDK 当前版本不支持创建私有 dataset repo 或 visibility 参数，请先在 ModelScope 手动创建私有 dataset repo，再运行上传脚本。脚本仍会在上传前执行 `src/dataset_ops/license_policy.py` 的保护规则。 ## Recommended First Run ```bash python scripts/download_datasets.py --dry-run --all python scripts/build_manifest.py python scripts/build_dataset_cards.py python scripts/upload_to_modelscope.py --dry-run --metadata-only ``` For the current automatic workflow, prefer: ```bash python scripts/run_auto_pipeline.py --max-total-gb 380 --min-free-gb 20 --resume --upload --metadata-upload-always --dry-run python scripts/status.py ``` ## Troubleshooting - `Missing dependency`: 运行 `pip install -r requirements.txt`。 - `python not found`: 安装 Python 或把解释器加入 PATH。 - S3 下载失败: 确认已安装 `s3fs`，并且 bucket 是公开匿名访问。 - GCS 下载失败: 确认已安装 `gcsfs`；如果路径是 requester-pays 或 Marketplace，则不要自动下载，改为 metadata-only。 - ModelScope token 错误: 确认 `MODELSCOPE_TOKEN`、`MODELSCOPE_NAMESPACE`、`MODELSCOPE_DATASET_NAME` 已设置。 - 上传被拦截: 查看 `data/logs/modelscope_upload_log.jsonl` 和 dataset card 的 compliance notes。