arc-creator

遵循 nfdi4plants ARC 规范创建并填充注释研究背景 (ARC)。在创建新 ARC、添加研究/分析/工作流程/运行、注释 ISA 元数据、将研究数据组织到 ARC 结构或将 ARC 推送到 DataHUB 时使用。以交互方式引导用户完成所有必需和可选的元数据字段。

# ARC Creator

Create FAIR Digital Objects following the nfdi4plants ARC specification v3.0.0.

## Prerequisites

- `git` and `git-lfs` installed
- ARC Commander CLI at `~/bin/arc` (optional but recommended)
- For DataHUB sync: Personal Access Token for git.nfdi4plants.org or datahub.hhu.de

## Interactive ARC Creation Workflow

Guide the user through these phases in order. Ask questions conversationally — don't dump all questions at once. Batch 2-4 related questions per message.

### Phase 1: Investigation Setup

Ask the user:
1. **Investigation identifier** (short, lowercase-hyphenated, e.g. `cold-stress-arabidopsis`)
2. **Title** (concise name for the investigation)
3. **Description** (textual description of the research goals)
4. **Where to store the ARC locally** (suggest `/home/uranus/arc-projects/<identifier>/`)

Then run `scripts/create_arc.sh <path> <identifier>` and set investigation metadata via:
```bash
arc investigation update -i "<id>" --title "<title>" --description "<desc>"
```

### Phase 2: Studies

For each study, ask:
1. **Study identifier** (e.g. `plant-growth`)
2. **Title and description**
3. **Organism** (for Characteristic [Organism])
4. **Growth conditions** (temperature, light, medium, etc.)
5. **Source materials** (what goes in — seeds, cell lines, etc.)
6. **Sample materials** (what comes out — leaves, roots, extracts, etc.)
7. **Protocols** — does the user have protocol documents to include?
8. **Factors** — what experimental variables are being tested? (e.g., temperature, genotype, treatment)

Create with:
```bash
arc study init --studyidentifier "<id>"
arc study update --studyidentifier "<id>" --title "<title>" --description "<desc>"
```

Copy protocol files to `studies/<id>/protocols/`.
Copy resource files to `studies/<id>/resources/`.

### Phase 3: Assays

For each assay, ask:
1. **Assay identifier** (e.g. `proteomics-ms`, `rnaseq`, `sugar-measurement`)
2. **Measurement type** (e.g., protein expression profiling, transcription profiling, metabolite profiling)
3. **Technology type** (e.g., mass spectrometry, nucleotide sequencing, plate reader)
4. **Technology platform** (e.g., Illumina NovaSeq, Bruker timsTOF)
5. **Data files** — where are the raw data files? (will go into `assays/<id>/dataset/`)
6. **Processed data** — any processed output files?
7. **Protocols** — assay-specific protocols?
8. **Performers** — who performed this assay? (name, affiliation, role)

Create with:
```bash
arc assay init -a "<id>" --measurementtype "<type>" --technologytype "<tech>"
```

Copy data to `assays/<id>/dataset/`, protocols to `assays/<id>/protocols/`.

### Phase 4: Workflows (optional)

Ask if there are computational analysis steps. For each:
1. **Workflow identifier** (e.g. `deseq2-analysis`, `heatmap-generation`)
2. **Description** of what it does
3. **Code files** (scripts, notebooks)
4. **Dependencies** (Python packages, R libraries, Docker image)

Place code in `workflows/<id>/`.
Note: `workflow.cwl` is REQUIRED by spec but often created later. Inform user.

### Phase 5: Runs (optional)

Ask if there are computation outputs. For each:
1. **Run identifier**
2. **Which workflow produced it**
3. **Output files** (figures, tables, processed data)

Place outputs in `runs/<id>/`.

### Phase 6: Contacts & Publications

Ask:
1. **Investigation contacts** (name, email, affiliation, role — at minimum the PI)
2. **Publications** (if any — DOI, PubMed ID, title, authors)

Add via:
```bash
arc investigation person register --lastname "<last>" --firstname "<first>" --email "<email>" --affiliation "<aff>"
```

### Phase 7: Git Commit & DataHUB Sync

1. Configure git user:
```bash
git config user.name "<name>"
git config user.email "<email>"
```

2. Commit:
```bash
git add -A
git commit -m "Initial ARC: <investigation title>"
```

3. Ask if the user wants to push to a DataHUB. If yes:
   - Ask which host (git.nfdi4plants.org, datahub.hhu.de, etc.)
   - Create remote repo (via browser or API)
   - Set remote and push

## ISA Metadata Reference

For detailed ISA-XLSX fields, annotation table columns, and ontology references, read `references/arc-spec.md`.

## Key Reminders

- **Assay data is immutable** — never modify files in `assays/<id>/dataset/` after initial placement
- **Studies describe materials**, assays describe measurements
- **Workflows are code**, runs are outputs
- **Git LFS** for files > 100 MB: `git lfs track "*.fastq.gz" "*.bam" "*.raw"`
- **Don't store ARCs on OneDrive/Dropbox** — Git + cloud sync causes conflicts
- ARC Commander CLI reference: `arc <subcommand> --help`

---

## 中文说明

# ARC Creator

遵循 nfdi4plants ARC 规范 v3.0.0 创建 FAIR 数字对象。

## 前置条件

- 已安装 `git` 和 `git-lfs`
- 位于 `~/bin/arc` 的 ARC Commander CLI（可选，但推荐）
- 用于 DataHUB 同步：git.nfdi4plants.org 或 datahub.hhu.de 的个人访问令牌

## 交互式 ARC 创建工作流程

按顺序引导用户完成以下各个阶段。以对话方式提问 — 不要一次性抛出所有问题。每条消息中将 2-4 个相关问题合并提出。

### 阶段 1：Investigation 设置

向用户询问：
1. **Investigation 标识符**（简短、小写连字符格式，例如 `cold-stress-arabidopsis`）
2. **标题**（investigation 的简洁名称）
3. **描述**（对研究目标的文字描述）
4. **本地存储 ARC 的位置**（建议 `/home/uranus/arc-projects/<identifier>/`）

然后运行 `scripts/create_arc.sh <path> <identifier>`，并通过以下方式设置 investigation 元数据：
```bash
arc investigation update -i "<id>" --title "<title>" --description "<desc>"
```

### 阶段 2：Studies

对于每个 study，询问：
1. **Study 标识符**（例如 `plant-growth`）
2. **标题和描述**
3. **Organism**（用于 Characteristic [Organism]）
4. **生长条件**（温度、光照、培养基等）
5. **源材料**（输入物 — 种子、细胞系等）
6. **样本材料**（产出物 — 叶片、根、提取物等）
7. **Protocols** — 用户是否有要纳入的实验方案文档？
8. **Factors** — 正在测试哪些实验变量？（例如温度、基因型、处理方式）

使用以下命令创建：
```bash
arc study init --studyidentifier "<id>"
arc study update --studyidentifier "<id>" --title "<title>" --description "<desc>"
```

将实验方案文件复制到 `studies/<id>/protocols/`。
将资源文件复制到 `studies/<id>/resources/`。

### 阶段 3：Assays

对于每个 assay，询问：
1. **Assay 标识符**（例如 `proteomics-ms`、`rnaseq`、`sugar-measurement`）
2. **测量类型**（例如蛋白质表达谱分析、转录谱分析、代谢物谱分析）
3. **技术类型**（例如质谱、核苷酸测序、酶标仪）
4. **技术平台**（例如 Illumina NovaSeq、Bruker timsTOF）
5. **数据文件** — 原始数据文件在哪里？（将放入 `assays/<id>/dataset/`）
6. **处理后数据** — 是否有处理后的输出文件？
7. **Protocols** — 特定于该 assay 的实验方案？
8. **Performers** — 谁执行了该 assay？（姓名、单位、角色）

使用以下命令创建：
```bash
arc assay init -a "<id>" --measurementtype "<type>" --technologytype "<tech>"
```

将数据复制到 `assays/<id>/dataset/`，实验方案复制到 `assays/<id>/protocols/`。

### 阶段 4：Workflows（可选）

询问是否存在计算分析步骤。对于每一项：
1. **Workflow 标识符**（例如 `deseq2-analysis`、`heatmap-generation`）
2. **描述**其功能
3. **代码文件**（脚本、notebook）
4. **依赖项**（Python 包、R 库、Docker 镜像）

将代码放入 `workflows/<id>/`。
注意：规范要求必须有 `workflow.cwl`，但它通常在稍后创建。请告知用户。

### 阶段 5：Runs（可选）

询问是否存在计算输出。对于每一项：
1. **Run 标识符**
2. **由哪个 workflow 产生**
3. **输出文件**（图、表、处理后数据）

将输出放入 `runs/<id>/`。

### 阶段 6：联系人与出版物

询问：
1. **Investigation 联系人**（姓名、邮箱、单位、角色 — 至少要有 PI）
2. **出版物**（如有 — DOI、PubMed ID、标题、作者）

通过以下方式添加：
```bash
arc investigation person register --lastname "<last>" --firstname "<first>" --email "<email>" --affiliation "<aff>"
```

### 阶段 7：Git 提交与 DataHUB 同步

1. 配置 git 用户：
```bash
git config user.name "<name>"
git config user.email "<email>"
```

2. 提交：
```bash
git add -A
git commit -m "Initial ARC: <investigation title>"
```

3. 询问用户是否要推送到 DataHUB。如果是：
   - 询问使用哪个主机（git.nfdi4plants.org、datahub.hhu.de 等）
   - 创建远程仓库（通过浏览器或 API）
   - 设置 remote 并推送

## ISA 元数据参考

有关详细的 ISA-XLSX 字段、注释表列和本体引用，请阅读 `references/arc-spec.md`。

## 关键提示

- **Assay 数据不可变** — 初次放置后切勿修改 `assays/<id>/dataset/` 中的文件
- **Studies 描述材料**，assays 描述测量
- **Workflows 是代码**，runs 是输出
- **Git LFS** 用于大于 100 MB 的文件：`git lfs track "*.fastq.gz" "*.bam" "*.raw"`
- **不要将 ARC 存储在 OneDrive/Dropbox 上** — Git + 云同步会导致冲突
- ARC Commander CLI 参考：`arc <subcommand> --help`