Metadata-Version: 2.4
Name: cttools-chrysanthemum
Version: 0.2.7
Summary: CTtools: chrysanthemum transcriptome workflows for prebuilt and custom references
Author: YifanDong
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: requires-python

# CTtools

CTtools is a private transcriptome workflow toolkit for chrysanthemum projects. It generates LSF/bsub scripts for RNA-seq analysis — it does **not** run pipelines directly, but produces audit-friendly, modifiable shell scripts for HPC submission.

Author: YifanDong

**Current Version**: 0.2.7 (Released 2026-05-06)

---

## Installation / 安装

### One-step bootstrap / 一步安装 (v0.2.7+)

`cttools.yml` now includes `cttools-chrysanthemum` itself — create the environment and get the tool installed together:

```bash
# Export YAML from the wheel, then create env (tool + all dependencies)
cttools env save -o ./cttools.yml
cttools env install --name cttools
conda activate cttools
cttools --help
```

### 3-step quick start / 三步快速开始

```bash
pip install cttools-chrysanthemum      # 1. Install Python package
cttools env save -o ./cttools.yml      # 2. Export Conda environment file
cttools env install --name cttools     # 3. Create Conda env (prefers mamba)
```

> **mamba / micromamba**: `env install` auto-detects package manager in order: micromamba > mamba > conda. Install mamba first for faster resolution: `conda install mamba -c conda-forge`.

> **No pip?** Use `cttools env save -o ./cttools.yml` after pip install, or unzip the `.whl` file to extract `cttools.yml` directly from `cttools/resources/`.

> See [INSTALLATION.md](INSTALLATION.md) for the complete bilingual installation guide, troubleshooting, and alternative workflows.

---

## Design Priority / 设计理念

CTtools encourages users to provide their own reference genome (`FASTA`), annotation (`GFF/GTF`) and protein file (`PEP`) for transparent, reproducible analyses.

Prebuilt species resources are supported as convenience presets, but **custom reference workflows are the default recommendation**.

## Core Capabilities / 核心功能

- Generate LSF/bsub scripts for RNA-seq workflows (verified cluster format)
- Two modes:
  - `custom`: user-provided references (recommended)
  - `prebuilt`: registry-managed species resources
- Stage-level execution: run full workflow or only selected stages
- Conda environment management with mamba auto-detection for speed
- Export the bundled Conda environment YAML to disk (`cttools env save`)
- Extract `cttools.yml` from wheel via `cttools env save` or unzip (no separate download needed)
- Auto-submit generated scripts to HPC via `--submit` flag

## Stage-Level Execution / 分阶段执行

### Prebuilt mode (3 stages)

`star` → `rsem` → `matrix`

### Custom mode (5 stages, recommended)

`agat` → `rsem_prep` → `star` → `rsem` → `matrix`

Select specific stages with `--stages`:

```bash
# Only reference preparation
cttools lsf-workflow custom \
    --reference-fasta ./ref.fa --reference-gff ./ref.gff \
    --stages agat rsem_prep

# Only mapping and quantification (resume from existing reference)
cttools lsf-workflow custom \
    --reads-dir ./reads --out-root ./out \
    --stages star rsem matrix
```

## Quick Start / 快速使用

```bash
# Editable install (development)
pip install -e .
cttools --help
cttools registry list

# Preview conda command without executing
cttools env install --name cttools --dry-run

# Custom full workflow (recommended)
cttools lsf-workflow custom \
    --reference-fasta ./reference.fa \
    --reference-gff ./reference.gff \
    --reads-dir ./raw_reads \
    --out-root ./analysis_output \
    --script-dir ./lsf_scripts

# Prebuilt partial workflow
cttools lsf-workflow prebuilt \
    --species cn_diploid_bramble_head \
    --reads-dir ./raw_reads \
    --out-root ./analysis_output \
    --script-dir ./lsf_scripts \
    --stages matrix
```

### Auto-Submit Feature / 自动提交 (v0.2.2+)

Use `--submit` to automatically submit generated scripts to the HPC cluster:

```bash
cttools lsf-workflow custom \
    --reference-fasta ./reference.fa \
    --reference-gff ./reference.gff \
    --reads-dir ./raw_reads \
    --out-root ./analysis_output \
    --submit
```

## Environment Management / 环境管理

| Command | Description |
|---------|-------------|
| `cttools env show` | Print the bundled `cttools.yml` content |
| `cttools env save -o ./file.yml` | Export the YAML to disk |
| `cttools env install --name cttools` | Create conda env (auto-finds YAML) |
| `cttools env install --dry-run` | Preview what conda would run |
| `cttools env install --mode update` | Update an existing environment |

**Note**: Starting from v0.2.3, generated LSF scripts no longer source `/etc/profile`, avoiding `COLORTERM: unbound variable` failures on hardened cluster shells.

## Species Registry / 物种登记表

| ID | Species | Reference |
|----|---------|-----------|
| `cultivated_hexaploid` | C. morifolium (Cmo), hexaploid "zhongshanzigui" | [DOI](https://doi.org/10.1038/s41467-023-37730-3) |
| `cn_diploid_bramble_head` | C. nankingense (Cn_AB), diploid complete | [DOI](https://doi.org/10.1038/s41467-023-37730-3) |
| `cn_diploid_bramble_hap` | C. nankingense (Cn_A), diploid haplotype | [DOI](https://doi.org/10.1038/s41467-023-37730-3) |
| `wild_chrysanthemum` | C. seticuspe (CsGojo) | Nakano M, et al. 2021 |
| `cultivated_hexaploid_hap` | C. morifolium (Cmo_hap), haplotype (internal) | [DOI](https://doi.org/10.1038/s41467-023-37730-3) |

List all species: `cttools registry list`

## Repository Layout / 项目结构

```
src/cttools/              Core package
  cli.py                  CLI entry point (argparse dispatch)
  workflows/              LSF script generation (lsf_builder, lsf_workflow, runner)
  resources/              Species registry TSV + cttools.yml (shipped in wheel)
  deg/                    Differential expression gene splitting
  enrichment/             GO/KO annotation background tables
  gene_search/            PEP FASTA parser
  preprocess/             EggNOG annotation parser
  quant/                  STAR/RSEM command builders
  utils/                  FASTQ auto-discovery
  visualization/          Expression matrix row selector
resources/                External registry template (source of truth)
tests/                    Unit and integration tests
scripts/                  Build, release, and validation utilities
docs/                     Architecture and requirement notes
```

## Version History / 版本历史

See [CHANGELOG.md](CHANGELOG.md) for the complete version history.

## Related Documents / 相关文档

- [INSTALLATION.md](INSTALLATION.md) — Bilingual complete installation guide
- [BEST_PRACTICES.md](BEST_PRACTICES.md) — Best practices and workflow checklist
- [TECHNICAL_DESIGN_REPORT.md](TECHNICAL_DESIGN_REPORT.md) — Technical design and architecture
- [CHANGELOG.md](CHANGELOG.md) — Version history
