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

# CTtools

CTtools is a private transcriptome workflow toolkit for chrysanthemum projects.

Author: YifanDong

**Current Version**: 0.2.3 (Released 2026-05-05)

**See [RELEASE_NOTES_v0.2.3.md](RELEASE_NOTES_v0.2.3.md) for latest updates and [CHANGELOG.md](CHANGELOG.md) for version history.**

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

- Build LSF/bsub scripts for RNA-seq workflows.
- Support two modes:
	- `custom`: user-provided references (recommended)
	- `prebuilt`: use registry-managed species resources
- Support stage-level script generation so users can run full workflow or only selected parts.
- Install Conda environments from YAML files.

## Stage-Level Execution

You can generate scripts for full pipeline or partial pipeline via `--stages`.

- `prebuilt` allowed stages: `star`, `rsem`, `matrix`
- `custom` allowed stages: `agat`, `rsem_prep`, `star`, `rsem`, `matrix`

### Auto-Submit Feature (v0.2.2+)

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

```bash
# Generate and automatically submit custom workflow
python -m cttools lsf-workflow custom \
	--reference-fasta ./reference.fa \
	--reference-gff ./reference.gff \
	--reads-dir ./raw_reads \
	--out-root ./analysis_output \
	--script-dir ./lsf_scripts \
	--submit

# Generate and automatically submit prebuilt workflow
python -m cttools lsf-workflow prebuilt \
	--species Chrysanthemum_morifolium \
	--reads-dir ./raw_reads \
	--out-root ./analysis_output \
	--script-dir ./lsf_scripts \
	--submit
```

### Standard Examples

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

# custom partial workflow (only mapping)
python -m cttools lsf-workflow custom \
	--reads-dir ./raw_reads \
	--out-root ./analysis_output \
	--script-dir ./lsf_scripts \
	--stages star

# prebuilt partial workflow (only matrix generation)
python -m cttools lsf-workflow prebuilt \
	--species cn_diploid_bramble_head \
	--reads-dir ./raw_reads \
	--out-root ./analysis_output \
	--script-dir ./lsf_scripts \
	--stages matrix

# install the software environment
python -m cttools env install \
	--file ./cttools.yml \
	--name cttools \
	--mode create
```

## Environment Installation

CTtools includes a Conda environment installer with complete dependencies.

**Starting from v0.2.2**, the environment is standardized as `cttools`.

**Starting from v0.2.3**, generated LSF scripts no longer source `/etc/profile`, which avoids the `COLORTERM: unbound variable` failure on hardened cluster shells.

Recommended command:

```bash
python -m cttools env install --file ./cttools.yml --name cttools
```

Useful options:

- `--mode create`: create a new environment from the YAML file (default)
- `--mode update`: update an existing environment
- `--prefix /path/to/env`: install into a specific prefix instead of a named env
- `--dry-run`: print the conda command without executing it to preview the operation

The command prints JSON output so it can be used in automation scripts.

**Note**: If you have an older environment named `rsem_env` from previous versions, it's recommended to create a new `cttools` environment to benefit from the latest dependency versions.

## Species Naming and Citation Attribution

The built-in prebuilt species registry has been updated to include official naming and citation notes to avoid attribution ambiguity.

- `Chrysanthemum morifolium (Cmo), hexaploid cultivar zhongshanzigui`
- `Chrysanthemum nankingense (Cn_A), diploid haplotype assembly`
- `Chrysanthemum nankingense (Cn_AB), diploid complete assembly`
- `Chrysanthemum seticuspe (CsGojo)`

Citation notes in registry:

- Song, A., Su, J., Wang, H. et al. Analyses of a chromosome-scale genome assembly reveal the origin and evolution of cultivated chrysanthemum. Nat Commun 14, 2021 (2023). DOI: `https://doi.org/10.1038/s41467-023-37730-3`
- Nakano M, Hirakawa H, Fukai E, et al. Communications Biology, 2021, 4(1):1167

## Quick Start

```bash
python -m pip install -e .
python -m cttools --help
python -m cttools registry list
python -m cttools env install --file ./cttools.yml --name cttools --dry-run
```

## Repository Layout

- `src/cttools/`: core package
- `resources/`: external registry template
- `src/cttools/resources/`: packaged registry used by default
- `docs/`: architecture and requirement notes
- `tests/`: unit and integration tests
