cttools-chrysanthemum 0.2.6

CTtools: chrysanthemum transcriptome workflows for prebuilt and custom references

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.6 (Released 2026-05-06)

---

Installation / 安装

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

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)

Activate and verify / 激活并验证:

conda activate cttools
cttools --help

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 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:

# 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 / 快速使用

# 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:

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
cn_diploid_bramble_head	C. nankingense (Cn_AB), diploid complete	DOI
cn_diploid_bramble_hap	C. nankingense (Cn_A), diploid haplotype	DOI
wild_chrysanthemum	C. seticuspe (CsGojo)	Nakano M, et al. 2021
cultivated_hexaploid_hap	C. morifolium (Cmo_hap), haplotype (internal)	DOI

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 for the complete version history.

Related Documents / 相关文档

• INSTALLATION.md — Bilingual complete installation guide
• BEST_PRACTICES.md — Best practices and workflow checklist
• TECHNICAL_DESIGN_REPORT.md — Technical design and architecture
• CHANGELOG.md — Version history