Skip to content

Commit 4472849

Browse files
johausmannjohausmann
committed
feat(T2T): add initial implementation plan for T2T support
1 parent 6f5f053 commit 4472849

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

‎plans/T2T_implementation_plan.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Implementation Plan: T2T (CHM13v2.0) Support for OBLX
2+
3+
This document outlines the necessary technical changes to integrate
4+
Telomere-to-Telomere (T2T) assembly support into the OBLX resource acquisition
5+
and index build pipeline.
6+
7+
## 1. Configuration & Schema
8+
9+
To enable T2T as a valid target, the following configuration updates are
10+
required:
11+
12+
- **Schema Update**: Add `T2T` to the `genome_build` enum in
13+
`workflow/schemas/config.schema.yaml`.
14+
- **Constants**: Define T2T-specific resource URLs (S3 and Ensembl HPRC) within
15+
the workflow or as config defaults.
16+
17+
## 2. Resource Acquisition Pipeline (`workflow/rules/pull_resources.smk`)
18+
19+
### Architectural Approach: Rule Inheritance
20+
21+
To keep the codebase clean and DRY, we will utilize Snakemake's
22+
`use rule ... as ... with:` syntax (available in v6.0+). This allows us to
23+
inherit the shell execution logic from existing HG38 rules while overriding only
24+
the inputs (URLs) and outputs (filenames) for T2T.
25+
26+
### A. Reference Genome & Annotation
27+
28+
| Status | Rule(s) | Change Description | Implementation Detail / URLs |
29+
| :------------ | :-------------------------------------------- | :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30+
| **New** | `download_t2t_genome` | Implement S3 download of reference genome. | Use `use rule download_gencode_data as ... with:`. <br> URL: `https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/analysis_set/chm13v2.0_maskedY_rCRS.fa.gz` |
31+
| **New** | `download_t2t_annotation` | Implement Ensembl FTP download for HPRC GENCODEv38. | Use `use rule download_gencode_data as ... with:`. <br> GTF: `https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_009914755.4/ensembl/geneset/2022_07/genes.gtf.gz` <br> GFF3: `https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_009914755.4/ensembl/geneset/2022_07/genes.gff3.gz` |
32+
| **New** | `synthesize_t2t_transcriptome` | Download cDNA -> use `gffread` to include ncRNA. | New distinct rule. <br> URL: `https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_009914755.4/ensembl/geneset/2022_07/cdna.fa.gz` |
33+
| **Redefined** | `download_gencode_data`, `download_ucsc_data` | Parameterize or branch logic to avoid HG38-specific hardcoded paths when `genome_build == 'T2T'`. | Refactor as base rules using config variables. |
34+
35+
### B. Variant Databases
36+
37+
| Status | Rule(s) | Change Description | Implementation Detail / URLs |
38+
| :------------ | :--------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39+
| **New** | `download_t2t_gnomad` | Implement download of trimmed liftover VCFs from Ensembl. | New rule. <br> Exomes: `https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_009914755.4/vep/genome/vep_gnomad_exomes/gnomad.exomes.v4.1.sites.GCA_009914755.4.trimmed_liftover.vcf.gz` <br> Genomes: `https://ftp.ebi.ac.uk/pub/ensemblorganisms/Homo_sapiens/GCA_009914755.4/vep/genome/vep_gnomad_genomes/gnomad.genomes.v4.1.sites.GCA_009914755.4.trimmed_liftover.vcf.gz` |
40+
| **New** | `download_t2t_dbsnp` | Implement S3 download of release 155 liftovered VCF. | Use `use rule download_dbsnp_human as ... with:`. <br> URL: `https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/annotation/liftover/chm13v2.0_dbSNPv155.vcf.gz` |
41+
| **Redefined** | `download_gnomad`, `af_only_gnomad`, `download_dbsnp_human`, `prepare_dbsnp` | These rules are specific to HG38/GRCh38; they must be bypassed or replaced by the T2T counterparts. | Use a conditional switch in the target rule selection logic. |
42+
43+
### C. Masking & Mappability
44+
45+
| Status | Rule(s) | Change Description | Implementation Detail / URLs |
46+
| :------------ | :--------------------------------- | :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47+
| **New** | `download_t2t_repeatmasker` | Implement download of RepeatMasker BED or BigBed. | Use `use rule download_repeat_masker as ... with:`. <br> S3: `https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/annotation/chm13v2.0_RepeatMasker_4.1.2p1.2022Apr14.bed` <br> UCSC: `https://hgdownload.soe.ucsc.edu/gbdb/hs1/t2tRepeatMasker/chm13v2.0_rmsk.bb` |
48+
| **New** | `download_t2t_accessibility_mask` | Implement S3 download of combined accessibility mask. | New rule. <br> URL: `https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/annotation/accessibility/hs1.combined_mask.bed` |
49+
| **New** | `download_t2t_problematic_regions` | Download GIAB BigBed -> convert to BED via `bigBedToBed`. | Use `use rule download_ucsc_data as ... with:`. <br> URL: `https://hgdownload.soe.ucsc.edu/gbdb/hs1/problematic/GIAB/alldifficultregions.bb` |
50+
| **Redefined** | `download_repeat_masker` | Branch logic to support T2T sources instead of HG38-only paths. | Base rule -> inherited T2T rule. |
51+
52+
## 3. Liftover Pipeline (GRCh38 -> T2T)
53+
54+
Since native T2T resources for some tools are unavailable, a new sequence of
55+
rules is required:
56+
57+
1. **New Rule**: `download_t2t_chain` -> Fetch `grch38-chm13v2.chain`.
58+
- URL:
59+
`https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/chain/v1_nflo/grch38-chm13v2.chain`
60+
1. **Rule Dependency**: Ensure HG38 `download_gatk_bundle` and
61+
`download_exome_probesets` can run independently to provide source files.
62+
1. **New Rule**: `liftover_gatk_resources` -> Execute `CrossMap vcf` for Mills,
63+
1000G, and HapMap.
64+
1. **New Rule**: `liftover_exome_probesets` -> Execute `CrossMap bed` for Twist
65+
capture kit BEDs.
66+
67+
## 4. Genome Masking & Processing (`workflow/rules/genome_masking.smk`)
68+
69+
| Status | Rule(s) | Change Description |
70+
| :----------- | :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
71+
| **Bypassed** | `mask_GRC_assembly_errors`, `mask_pseudoautosomal` | These are HG38-specific. Implement logic to skip these when using T2T, as the reference is pre-masked and uses a different mask model. |
72+
73+
## 5. Generic Rules (Unmodified)
74+
75+
The following rule sets remain unmodified as they operate on generic inputs
76+
provided by the path resolver:
77+
78+
- **Index Building**: `bwa_mem_index`
79+
([`../workflow/rules/bwa-mem.smk`](../workflow/rules/bwa-mem.smk)), `star`
80+
index rules, etc. These simply take the FASTA output from the pull phase.
81+
- **Interval Generation**: `gencode_exome_bed`, `gencode_cds_bed`
82+
([`../workflow/rules/intervals.smk`](../workflow/rules/intervals.smk)). These
83+
process GTF -> BED and are assembly-agnostic provided a valid GTF is input.
84+
- **Index Helpers**: `chrom_sizes`
85+
([`../workflow/rules/intervals.smk`](../workflow/rules/intervals.smk)) as it
86+
relies on the `.fai` file.
87+
88+
## 6. Documentation Updates
89+
90+
To reflect T2T support, the following documentation changes are required:
91+
92+
### A. [`../docs/oblx/docs/configuration.md`](../docs/oblx/docs/configuration.md)
93+
94+
- **Parameter List**: Update `genome_build` to include `T2T`.
95+
- **Example Section**: Add a new "Example T2T" configuration block showing the
96+
use of `genome_build: T2T`.
97+
98+
### B. [`../docs/oblx/docs/pull_resources.md`](../docs/oblx/docs/pull_resources.md)
99+
100+
- **Output Structure**: Update the directory tree to show that filenames may
101+
differ for T2T or add a dedicated "T2T Output" section detailing the specific
102+
files produced for this build.
103+
- **Reference Files Section**: Clarify that `ref_genome` for T2T is pre-masked
104+
(CHM13v2.0 maskedY) and does not undergo the HG38 GRC-masking process
105+
described in the current doc.
106+
- **GATK & Exome Sections**: Add a note explaining that resources for T2T are
107+
generated via liftover from GRCh38 using `CrossMap`.
108+
109+
### C. [`../docs/oblx/docs/resources/human_resources.tsv`](../docs/oblx/docs/resources/human_resources.tsv)
110+
111+
- **Resource Table**: Add new entries for the T2T reference genome, annotations,
112+
and liftovered VCFs to ensure traceability.
113+
114+
## 7. Integration & Testing
115+
116+
- **Path Mapping**: Update `get_pull_resources_output` in
117+
[`../workflow/Snakefile`](../workflow/Snakefile) to conditionally map T2T
118+
paths vs standard GRChx paths.
119+
- **Validation**: Perform a dry-run (`snakemake -n`) with a custom config
120+
specifying `genome_build: T2T` to verify the full dependency chain (HG38
121+
Source -> CrossMap -> T2T Reference).

0 commit comments

Comments
 (0)