Why Edge TTS?

Most TTS APIs are either paid (Google Cloud, AWS Polly) or produce robotic-sounding audio. Microsoft Edge TTS offers high-quality neural voices for free, with support for dozens of languages including Brazilian Portuguese. The edge-tts Python package wraps this service cleanly, making it easy to integrate.

How It Works

The tool reads a .txt file, sends the text to Edge TTS, and saves the resulting audio as .mp3. Under the hood it is straightforward:

Text File (.txt)
    │
    ├── Read & validate UTF-8 content
    │
    ├── Edge TTS API
    │     ├── Neural voice synthesis
    │     └── Streaming audio chunks
    │
    └── Output MP3 file

Quick Start

Install and run in three steps:

git clone https://github.com/geocarvalho/simple-txt-to-speech.git
cd simple-txt-to-speech
pip install edge-tts

Basic conversion with default settings:

python bin/reader.py -i my_article.txt -o my_article.mp3

Key Features

Customizable speech rate — speed up or slow down the output by a percentage. I usually set +15% for articles I already know well and -10% for dense technical content:

python bin/reader.py -i notes.txt -o notes.mp3 -r 15

Multi-language voice selection — list available voices filtered by locale. This is great for language learning or creating content in Portuguese:

python bin/reader.py --list-voices --locale pt-BR

Some voice options I use regularly:

Progress tracking — a real-time progress bar shows conversion status, useful for longer texts:

[████████████████████░░░░░░░░░░░░░░░░░░] 60% (1.2 MB)
✓ Success! Audio saved to: result/result.mp3

Use Cases

• Commute listening — convert blog posts or papers to audio for the drive
• Accessibility — make text content available as audio for visually impaired users
• Language learning — generate native-sounding audio from vocabulary lists or texts
• Proofreading — hearing your own writing read back helps catch awkward phrasing

What’s Next

Some ideas for future improvements:

• Support for PDF and Markdown input formats
• Chapter splitting for long texts
• Batch processing of multiple files
• A simple web interface

The tool is intentionally minimal — a single Python script with one dependency. Check out the repository for the full source and feel free to contribute.

Single-cell RNA-seq is a different beast from bulk RNA-seq. Instead of measuring the average expression across millions of cells, it captures the transcriptome of individual cells. This is powerful for rare disease research because it reveals cell-type-specific expression patterns, identifies rare cell populations, and can expose disease mechanisms that are diluted away in bulk data.

Pipeline Overview

The pipeline is intentionally lean compared to the bulk RNA-seq and WGS pipelines. Cell Ranger, the 10x Genomics analysis suite, handles the heavy lifting — alignment, cell calling, UMI deduplication, and gene-barcode matrix generation. The pipeline wraps it with QC and storage optimization:

FASTQ R1/R2
    │
    ├── FastP (QC assessment)
    │
    ├── Cell Ranger Count
    │     ├── Alignment to transcriptome
    │     ├── Cell calling & UMI counting
    │     ├── Gene-barcode matrices
    │     ├── Loupe Browser file
    │     └── BAM (optional)
    │           └── Samtools BAM → CRAM
    │
    └── MultiQC (aggregated report)

Why Keep It Simple?

The bulk RNA-seq pipeline has 15+ tools. This one has four. That’s by design.

Cell Ranger is an opinionated, end-to-end tool from 10x Genomics. It handles alignment (using STAR internally), barcode error correction, UMI counting, cell/empty droplet classification, and secondary analysis (clustering, t-SNE, UMAP) all in one step. Trying to replicate or replace parts of this with individual tools (like STARsolo + custom barcode handling) adds complexity without clear benefits for our use case.

The downstream single-cell analysis — normalization, clustering, differential expression, cell type annotation — happens interactively in R (Seurat) or Python (Scanpy) by the researchers, not in the pipeline. The pipeline’s job is to go from raw FASTQ to clean count matrices reliably and reproducibly.

The Tools

FastP — Quality Assessment

FastP runs in QC-only mode — no trimming is applied. This is important: Cell Ranger expects untrimmed reads with the full 10x barcode and UMI structure intact. Trimming could damage the barcode sequence in Read 1 or the UMI, breaking cell assignment. FastP is here purely to assess read quality and generate reports that feed into MultiQC.

Cell Ranger Count — The Core

Cell Ranger count is the primary analysis step. Given paired FASTQ files and a transcriptome reference, it:

1. Extracts barcodes and UMIs from Read 1 (the structure depends on the chemistry version).
2. Aligns Read 2 to the transcriptome using an embedded STAR aligner.
3. Corrects barcode errors using a whitelist of valid barcodes for the specific chemistry.
4. Deduplicates UMIs to remove PCR duplicates at the molecular level.
5. Calls cells — distinguishes real cells from empty droplets using an algorithm that looks at the total UMI count distribution.
6. Generates count matrices — both raw (all barcodes) and filtered (cells only), in HDF5 format.
7. Runs secondary analysis — PCA, clustering, t-SNE/UMAP, and differential expression.
8. Creates a Loupe file for interactive visualization in the 10x Loupe Browser.

The pipeline supports several key parameters:

• chemistry: Auto-detected by default, but can be forced to a specific 10x chemistry version (SC3Pv3, SC5P-R2, etc.) when auto-detection fails or for non-standard libraries.
• expect_cells: The expected number of recovered cells (default 5000). This guides the cell calling algorithm — setting it too low might filter out real cells, too high might include empty droplets.
• create_bam: When true, Cell Ranger produces a BAM file with cell barcode and UMI tags, which the pipeline then converts to CRAM. When false (default), alignment files are skipped entirely, saving significant compute time and storage.

Cell Ranger is the most resource-intensive step, requiring 32 CPUs and 128 GB of RAM.

Samtools — BAM to CRAM Conversion

When create_bam is enabled, Samtools converts the Cell Ranger BAM to CRAM format using the reference genome extracted from the transcriptome directory. This provides 40-60% file size reduction. The original BAM is not published to S3 — only the CRAM makes it to the output, saving storage costs.

This is optional because many downstream single-cell analyses only need the count matrices, not the alignments. But when you need alignments — for example, to run Velocyto for RNA velocity analysis, or to inspect specific loci in IGV — having the CRAM available avoids re-running Cell Ranger.

MultiQC — Aggregated Reporting

MultiQC collects FastP and Cell Ranger metrics into a single HTML report. The Cell Ranger web summary is already comprehensive, but MultiQC provides a standardized view that’s consistent with our bulk RNA-seq and WGS pipeline reports, making it easier to assess quality across different assay types.

AWS HealthOmics Deployment

Same pattern as the other pipelines — zip the repository, import as a private workflow, and launch runs with run_parameters.json pointing to S3 paths:

cd /path/to/nl-snrna-seq_wf/
rm nl-snrna-seq_wf.zip; zip -r nl-snrna-seq_wf.zip *

Docker images live in ECR, and outputs go to /mnt/workflow/pubdir → S3. The transcriptome reference (e.g., refdata-gex-GRCh38-2024-A) also lives in S3 and is mounted into the Cell Ranger process.

Output Structure

output/
├── QC/
│   ├── <sample>_fastp.html
│   ├── <sample>_fastp.json
│   └── multiqc_report.html
└── CELLRANGER/
    ├── web_summary.html
    ├── metrics_summary.csv
    ├── filtered_feature_bc_matrix.h5
    ├── raw_feature_bc_matrix.h5
    ├── molecule_info.h5
    ├── cloupe.cloupe
    ├── <sample>.cram (if create_bam: true)
    ├── <sample>.cram.crai (if create_bam: true)
    └── analysis/

The key outputs for downstream analysis:

• filtered_feature_bc_matrix.h5: The filtered count matrix — this is what goes into Seurat or Scanpy.
• raw_feature_bc_matrix.h5: The raw matrix with all barcodes, useful for custom cell calling with tools like CellBender or EmptyDrops.
• molecule_info.h5: Per-molecule information needed for sample aggregation (cellranger aggr) across multiple samples.
• cloupe.cloupe: For quick interactive exploration in the 10x Loupe Browser before diving into code-based analysis.

How It Fits With the Other Pipelines

The three pipelines at the Nelson Lab form a complementary toolkit for rare disease genomics:

A pathogenic variant found in WGS might show reduced expression in bulk RNA-seq, and single-cell data can reveal whether that effect is cell-type-specific — for example, only affecting motor neurons but not glial cells. This multi-omics approach is increasingly important for solving the hardest undiagnosed cases.

Lessons Learned

Don’t fight Cell Ranger. For 10x data, Cell Ranger is the path of least resistance. The alternative (STARsolo + custom scripts) can work but requires careful handling of barcode whitelists, chemistry detection, and cell calling — all of which Cell Ranger handles robustly.

Skip the BAM by default. Most single-cell workflows only need count matrices. Making BAM generation optional (create_bam: false) cuts runtime and storage significantly. Only enable it when you actually need alignments.

Don’t trim 10x reads. This is a common mistake. The barcode + UMI structure in Read 1 must be intact for Cell Ranger. FastP runs in assessment-only mode for this reason.

Keep the pipeline focused. The temptation is to add Seurat/Scanpy analysis into the pipeline. Resist it — single-cell analysis is inherently interactive and exploratory. The pipeline should produce clean, reproducible count matrices and let researchers drive the analysis.

The pipeline is open source at github.com/uclanelsonlab/nl-snrna-seq_wf. Contributions and feedback are welcome.

Pipeline Architecture

One key design goal was flexibility in input formats. Clinical labs send data in different states — sometimes raw FASTQ, sometimes already-aligned BAM or CRAM files. Instead of forcing a single entry point, the pipeline uses subworkflows that converge into a shared analysis path:

Inputs
  ├── FASTQ R1/R2 → Fastp → BWA-MEM2 → Sort
  ├── BAM ──────────────────────────── → Sort
  └── CRAM ─────── → CRAM-to-BAM ──── → Sort
                                          │
                              ┌────────────┘
                              ▼
                     Picard MarkDuplicates
                     Samtools Index
                              │
              ┌───────────────┼───────────────────┐
              ▼               ▼                   ▼
         QC & Metrics    Variant Calling    SV & Repeat Analysis
              │               │                   │
              ▼               ▼                   ▼
        ┌─────────┐    ┌───────────┐    ┌─────────────────┐
        │ Picard   │    │DeepVariant│    │ Manta (SVs)     │
        │ Qualimap │    │    ↓      │    │ CNVpytor (CNVs) │
        │ Mosdepth │    │ AutoMap   │    │ ExpansionHunter │
        │ MultiQC  │    │ (ROH)    │    │ EH Denovo       │
        └─────────┘    │    ↓      │    └─────────────────┘
                        │ BCFtools  │
                        │    ↓      │
                        │ HapCUT2   │
                        │ (phasing) │
                        └───────────┘
                              │
                              ▼
                        BAM → CRAM

This subworkflow architecture means you can re-analyze existing alignments without re-running the expensive alignment step, and CRAM files received from external labs can enter the pipeline directly.

Running on AWS HealthOmics

The pipeline is structured to run as a private workflow on AWS HealthOmics. Deployment is straightforward:

cd /path/to/nl-wgs_wf/
rm nl-wgs_wf.zip; zip -r nl-wgs_wf.zip *

You import the zip file into HealthOmics along with parameters.json for the parameter definitions, and use run_parameters.json to specify S3 paths when launching runs. All Docker images live in AWS ECR, and outputs go to /mnt/workflow/pubdir which syncs back to S3.

The same benefits from the RNA-seq pipeline apply here: managed compute, HIPAA compliance, no infrastructure to maintain, and native Nextflow support.

The Tools and Why They’re There

Fastp — Quality Control

Fastp handles adapter trimming and quality filtering on the raw FASTQ input. Same reasons as in the RNA-seq pipeline: it’s fast, single-pass, and produces JSON output that feeds directly into MultiQC.

BWA-MEM2 — Alignment

BWA-MEM2 is the SIMD-accelerated successor to BWA-MEM. For WGS data with billions of reads, the speed improvement over the original BWA-MEM is significant — roughly 2-3x faster on modern hardware. It produces identical alignments to BWA-MEM but takes better advantage of CPU vector instructions. Read group information is added during alignment so samples are properly identified throughout the pipeline.

Picard — Duplicate Marking and Metrics

We use Picard for multiple purposes:

• MarkDuplicates: Flags PCR duplicates. For WGS (unlike our RNA-seq pipeline where we used Sambamba), we chose Picard here because it integrates better with the GATK/DeepVariant ecosystem and we already need Picard for metrics collection.
• CollectMultipleMetrics: Alignment summary, insert size distribution, quality score distribution, and more.
• CollectWgsMetrics: WGS-specific metrics including coverage uniformity, mean coverage, and the percentage of bases reaching various depth thresholds.

These metrics are critical for assessing whether a genome has sufficient quality and coverage for clinical interpretation.

Qualimap — BAM Quality Control

Qualimap provides additional BAM-level QC including coverage across chromosomes, GC content distribution, and mapping quality statistics. It complements Picard metrics with different visualizations and is particularly useful for spotting coverage anomalies.

DeepVariant — SNV/Indel Calling

DeepVariant is our primary variant caller for SNVs and small indels. Unlike traditional callers like GATK HaplotypeCaller, DeepVariant uses a deep learning model trained on truth sets to evaluate evidence for variants. It consistently performs well in precisionFDA Truth Challenges and produces both VCF and gVCF outputs.

For WGS we use the standard WGS model (unlike the RNA-seq pipeline where we needed a custom model). DeepVariant is the most resource-intensive step at 192 GB RAM and 48 CPUs, but produces high-quality variant calls.

AutoMap — Runs of Homozygosity

AutoMap detects runs of homozygosity (ROH) from the DeepVariant VCF output. ROH regions are important in rare disease because:

• They can indicate consanguinity, which increases the likelihood of autosomal recessive conditions.
• Homozygous pathogenic variants in ROH regions are strong candidates for disease causation.
• Large ROH blocks may point to uniparental disomy (UPD).

AutoMap outputs both TSV files with ROH coordinates and PDF visualizations across the genome.

HapCUT2 — Haplotype Phasing

HapCUT2 phases heterozygous variants into haplotype blocks. The phasing workflow is:

1. BCFtools filters the DeepVariant VCF to retain only diploid genotypes (0/0, 0/1, 1/1).
2. HapCUT2 extractHAIRS extracts haplotype-informative reads from the BAM.
3. HapCUT2 assembles these into phased haplotype blocks.

Phasing is valuable for rare disease because it tells you which variants are on the same chromosome (cis) versus opposite chromosomes (trans). For compound heterozygous variants in a recessive gene, you need to confirm the two variants are on different alleles — phasing provides this evidence directly from the sequencing data.

Manta — Structural Variant Detection

Manta detects structural variants (SVs) including large deletions, duplications, inversions, and insertions. Manta is fast, well-validated, and specifically designed for germline analysis. It uses split-read and paired-end evidence to call SVs with high sensitivity.

SVs are particularly important in rare diseases because they can disrupt genes in ways not captured by SNV callers — a large deletion removing an entire exon, an inversion disrupting a gene, or a translocation creating a fusion.

CNVpytor — Copy Number Variant Analysis

CNVpytor detects copy number variants (CNVs) from read depth signals. It analyzes coverage across the genome at multiple bin sizes to identify regions with significantly more or fewer reads than expected. CNVpytor also produces Manhattan plots for visual inspection.

CNVpytor complements Manta: Manta excels at breakpoint-resolved SVs from paired-end/split-read evidence, while CNVpytor catches larger CNVs that may not have clear breakpoint signatures but show clear read depth changes.

ExpansionHunter and ExpansionHunterDenovo — Repeat Expansions

Repeat expansion disorders are an important class of rare diseases (Huntington’s disease, Fragile X, various ataxias, ALS). We use two complementary tools:

• ExpansionHunter genotypes known repeat expansion loci from a curated variant catalog. It can detect expansions beyond the read length by analyzing spanning reads, flanking reads, and in-repeat reads. This is the targeted approach — you look at known disease loci.
• ExpansionHunterDenovo takes the untargeted approach: it profiles the genome for any locus showing evidence of repeat expansion, even if it’s not in a known catalog. This is powerful for discovering novel repeat expansions in undiagnosed patients.

Mosdepth — Coverage Analysis

Mosdepth runs on the CRAM output to calculate coverage over specific BED regions, particularly mitochondrial regions. Mitochondrial coverage in WGS data reflects the mitochondrial copy number, which can be clinically relevant, and adequate coverage is needed for mitochondrial variant calling.

MultiQC — Aggregated Reporting

MultiQC aggregates reports from Fastp, Picard (multiple metrics + WGS metrics), Qualimap, DeepVariant, and Mosdepth into a single HTML report for quick sample-level QC assessment.

RNA-seq vs WGS: Complementary Pipelines

These two pipelines were designed to work together for rare disease diagnostics:

A variant found in WGS gains evidence when RNA-seq shows it’s expressed and doesn’t cause nonsense-mediated decay. Conversely, an aberrant splicing event found in RNA-seq points to where to look in the WGS data for the causal variant.

Lessons Learned

Support multiple input formats from day one. Clinical collaborators send data in whatever format they have. The subworkflow architecture that accepts FASTQ, BAM, and CRAM saved us from constant format-conversion requests.

Combine targeted and untargeted repeat analysis. ExpansionHunter catches known loci reliably, but ExpansionHunterDenovo has found novel expansions that would have been missed otherwise.

Phasing is underused in clinical genomics. Adding HapCUT2 was a late addition but immediately proved its value for resolving compound heterozygotes without requiring parental samples.

Complement SV callers. No single SV caller catches everything. Manta + CNVpytor gives better coverage across the SV size spectrum than either alone.

Runs of homozygosity are a quick win. AutoMap runs fast and immediately flags consanguinity and candidate regions for recessive disease — information that’s useful even before looking at individual variants.

The pipeline is open source at github.com/uclanelsonlab/nl-wgs_wf. Contributions and feedback are welcome.

Why AWS HealthOmics?

AWS HealthOmics is a purpose-built service for storing, querying, and analyzing genomic data at scale. We chose it for several reasons:

• Managed infrastructure: No need to provision or manage EC2 instances, auto-scaling groups, or job schedulers. HealthOmics handles compute orchestration for you.
• Native Nextflow support: HealthOmics supports Nextflow workflows natively as a “private workflow”, so we could keep the same DSL2 codebase we developed locally.
• ECR integration: All Docker images are stored in AWS Elastic Container Registry (ECR), which HealthOmics pulls from directly, avoiding Docker Hub rate limits and ensuring reproducibility.
• S3 storage: Input FASTQ files, reference genomes, and STAR indices live in S3 buckets. Outputs are written to /mnt/workflow/pubdir, which HealthOmics automatically syncs back to S3.
• HIPAA compliance: Since we process clinical patient data from programs like the Undiagnosed Diseases Network (UDN), HealthOmics provides a compliant environment out of the box.

The main trade-off is that HealthOmics has its own constraints — fixed compute tiers, specific Nextflow version requirements, and some limitations on how processes can communicate. But for a production clinical pipeline, the reliability and compliance benefits far outweigh these.

Pipeline Overview

The pipeline takes paired-end RNA-seq FASTQ files and produces a comprehensive set of outputs for rare disease analysis:

FASTQ R1/R2
    │
    ├── Fastp (QC + trimming)
    │     ├── BWA → rRNA contamination check
    │     └── BWA → Globin RNA contamination check
    │
    ├── STAR (splice-aware alignment)
    │     ├── Samtools Index
    │     └── Sambamba MarkDup
    │           ├── FeatureCounts (gene counts)
    │           ├── RNA-SeQC (QC metrics)
    │           ├── Qualimap (QC metrics)
    │           ├── IRFinder (intron retention)
    │           ├── Mosdepth (coverage analysis)
    │           │     └── Bedtools (CDS filtering)
    │           │           └── DeepVariant (variant calling)
    │           ├── BAM2SJ (splice junctions)
    │           └── Samtools CRAM (compression)
    │                 └── Mosdepth BED (XBP1 + MT coverage)
    │
    ├── Kallisto (transcript quantification)
    │
    └── MultiQC (aggregated report)

The Tools and Why They’re There

Fastp — Quality Control and Trimming

Fastp is the first step: adapter trimming, quality filtering, and length filtering. We chose fastp over alternatives like Trimmomatic or Cutadapt because it’s significantly faster (written in C++), produces clean HTML/JSON reports, and handles paired-end reads natively in a single pass. The JSON output feeds directly into MultiQC for aggregated reporting.

BWA — Contamination Detection (rRNA and Globin RNA)

Before alignment, we check for two common sources of contamination in blood-derived RNA samples:

• rRNA contamination: Ribosomal RNA should be depleted during library prep, but incomplete depletion wastes sequencing capacity. We align trimmed reads against an rRNA reference using BWA-MEM and compute flagstats to get the percentage of reads mapping to rRNA.
• Globin RNA contamination: Blood samples are dominated by hemoglobin transcripts. If globin depletion wasn’t performed (or failed), a large fraction of reads will be globin. Same approach: align against a globin reference and check flagstats.

High contamination rates in either category are a red flag that the sample may need to be re-prepped or that results should be interpreted with caution.

STAR — Splice-Aware Alignment

STAR is the gold standard for RNA-seq alignment. It’s splice-aware, meaning it can align reads that span exon-exon junctions — critical for RNA data. STAR also outputs gene-level read counts directly (ReadsPerGene.out.tab) and detects novel splice junctions.

One interesting aspect of our pipeline is that we maintain six different STAR indices for read lengths of 69, 75, 100, 120, 150, and 151 bp. This is because STAR’s sjdbOverhang parameter should ideally be read_length - 1, and our lab processes samples from multiple sequencing platforms and protocols. The pipeline selects the appropriate index based on the detected read length, ensuring optimal alignment regardless of the input data source.

STAR is by far the most resource-intensive step, requiring 192 GB of RAM and 48 CPUs — driven by the size of the human genome index in memory.

Sambamba — Duplicate Marking

Sambamba marks PCR duplicates in the aligned BAM. We chose Sambamba over Picard’s MarkDuplicates because it’s multi-threaded and significantly faster on large files, which matters when you’re paying per minute on cloud compute. The marked BAM is the starting point for all downstream analyses.

Subread FeatureCounts — Gene-Level Quantification

FeatureCounts from the Subread package assigns aligned reads to genomic features (genes) based on GENCODE annotations. It produces a count matrix that feeds into downstream differential expression tools like DESeq2 or aberrant expression detection with OUTRIDER. FeatureCounts is fast, handles multi-mapping reads well, and works at the exon level which gives us flexibility.

Kallisto — Transcript-Level Quantification

Kallisto provides transcript-level abundance estimates using pseudoalignment — it doesn’t perform traditional alignment at all, instead using k-mer matching against a transcriptome index. This makes it extremely fast and complementary to STAR+FeatureCounts. We use Kallisto’s transcript-level quantification for analyses that need isoform resolution, while FeatureCounts handles gene-level counting.

RNA-SeQC — Quality Assessment

RNA-SeQC from the Getz Lab at the Broad Institute computes a comprehensive set of quality metrics: mapping rates, rRNA rates, exonic/intronic/intergenic ratios, 3’/5’ coverage bias, GC bias, and gene-level TPM values. These metrics are essential for identifying problematic samples before they contaminate downstream analyses, especially when building cohort-level models for rare disease detection.

Qualimap — Additional QC

Qualimap provides additional RNA-seq-specific quality metrics and visualizations, complementing RNA-SeQC. Having multiple QC tools gives us a more complete picture of sample quality.

IRFinder — Intron Retention Detection

IRFinder detects intron retention events, where introns that should be spliced out are instead retained in the mature mRNA. Intron retention is increasingly recognized as a mechanism in rare diseases — it can lead to premature stop codons, nonsense-mediated decay, or altered protein function. This is particularly relevant for our work since aberrant splicing is one of the key things RNA-seq can reveal that exome/genome sequencing alone cannot.

Mosdepth — Coverage Analysis

Mosdepth calculates sequencing depth and coverage quickly from BAM/CRAM files. We run it in two modes:

1. Genome-wide per-base coverage: This output feeds into Bedtools to identify coding regions with adequate coverage for variant calling.
2. Targeted BED regions: We specifically check coverage over the XBP1 gene and mitochondrial regions. XBP1 is relevant because its unconventional splicing is a biomarker for certain conditions, and mitochondrial coverage is important for mitochondrial disease diagnostics — a significant subset of rare diseases.

Bedtools — CDS Region Filtering

Bedtools takes the per-base coverage from Mosdepth and intersects it with GENCODE CDS (coding sequence) annotations, filtering for regions that meet a minimum coverage threshold. The resulting BED file defines the genomic regions where we have enough data to confidently call variants. This ensures DeepVariant only runs on well-covered coding regions, improving both accuracy and efficiency.

DeepVariant — Variant Calling

DeepVariant is Google’s deep learning-based variant caller. We use a custom model trained on RNA-seq data rather than the default WGS/WES models — this is important because RNA-seq has fundamentally different characteristics (splice junctions, allele-specific expression, variable coverage across exons). The pipeline accepts custom model files (model_data, model_index, model_meta, model_info) as parameters.

Variant calling from RNA-seq complements WGS/WES by providing expression-aware variant detection. A variant found in both DNA and RNA data, especially with biallelic expression, gives higher confidence for pathogenicity assessment.

BAM2SJ — Splice Junction Analysis

BAM2SJ reconstructs splice junctions from the aligned BAM, producing a table of junction coordinates, read support, and strand information. This output is used downstream for aberrant splicing detection with tools like FRASER, which identifies samples with statistically unusual splicing patterns compared to a control cohort — a powerful approach for finding disease-causing splice variants.

Samtools — CRAM Compression

After all analyses are complete, we convert the final BAM to CRAM format using samtools. CRAM files are typically 40-60% smaller than BAM files, which significantly reduces S3 storage costs when you’re processing hundreds of samples.

MultiQC — Aggregated Reporting

MultiQC collects outputs from Fastp, STAR, FeatureCounts, RNA-SeQC, Qualimap, Kallisto, and the contamination checks into a single interactive HTML report. This is invaluable for quickly assessing sample quality and identifying issues across a batch of samples.

The Rare Disease Context

This pipeline was built to support the Undiagnosed Diseases Network (UDN) and similar rare disease programs. RNA-seq adds a critical layer of evidence beyond DNA sequencing:

• Aberrant expression: Genes with significantly reduced expression may harbor regulatory or deep intronic variants not visible on exome.
• Aberrant splicing: Novel or increased usage of cryptic splice sites can point to pathogenic variants affecting splicing machinery.
• Intron retention: Retained introns can indicate splicing defects caused by variants in splice regions.
• Allele-specific expression: Monoallelic expression of a heterozygous variant suggests the other allele may be silenced or degraded.

The combination of STAR alignment, IRFinder, BAM2SJ, and the downstream OUTRIDER/FRASER analyses provides a comprehensive view of these RNA-level effects.

Lessons Learned

Pre-build multiple STAR indices. Different sequencing platforms produce different read lengths. Having indices ready for common lengths avoids pipeline failures and re-processing.

Always check contamination first. A 30% rRNA contamination rate means you effectively sequenced 30% less of your transcriptome. Catching this early saves time on interpretation.

Coverage-guided variant calling matters. Running DeepVariant on the entire genome wastes compute and produces low-confidence calls in poorly covered regions. The Mosdepth → Bedtools → DeepVariant chain focuses resources where the data supports confident calling.

CRAM saves real money. At hundreds of samples per year, the storage savings from CRAM over BAM are significant on S3.

AWS HealthOmics simplifies compliance but adds constraints. You trade flexibility for managed infrastructure and compliance. Worth it for clinical workflows, but be prepared to work within the platform’s limitations.

The pipeline is open source and available at github.com/uclanelsonlab/nl-rna-seq_wf. Contributions and feedback are welcome.

In this post, I’ll walk you through the steps to convert a CRAM file into high-quality, paired-end FASTQ files using Dockerized bioinformatics tools like samtools, fastp, and bbmap. You’ll also learn how to validate references, check file integrity, and repair read pairs.

Prerequisites

• At least moderate familiarity with the command line.
• Docker is installed and running on your machine.
• Access to the corresponding FASTA reference file (critical for decompression).
• A CRAM file aligned to hg38 (no-alt or UCSC version depending on the lab standard).

Step 1: Identify the Reference Genome

Before working with a CRAM, you need to know exactly which reference genome was used for alignment. This is critical — using the wrong reference will cause decompression to fail or produce incorrect results.

Option A: Using ref-solver (recommended)

ref-solver is a tool by Fulcrum Genomics that identifies the exact human reference genome used to align a BAM/SAM/CRAM file. It matches the sequence dictionary against a catalog of 15+ known human reference genomes using MD5 checksums, detecting naming conventions (chr1 vs 1), contig sets (with/without ALT contigs), and mitochondrial sequence differences.

Install via cargo or conda:

cargo install ref-solver
# or
conda install -c bioconda ref-solver

Then identify the reference:

ref-solver identify sample.sorted.noalt.hg38.cram

Example output:

#1 hg38 (UCSC) (EXACT)
   ID: hg38_ucsc
   Assembly: GRCh38
   Source: UCSC
   Match Type: Exact
   Score: 100.0%

You can also pipe from samtools or get JSON output for scripting:

samtools view -H sample.sorted.noalt.hg38.cram | ref-solver identify -

ref-solver identify sample.sorted.noalt.hg38.cram --format json

If you have a candidate reference FASTA and want to compare directly:

ref-solver score sample.sorted.noalt.hg38.cram reference.fa.fai

This is especially useful when you receive CRAM files from external sources (collaborators, sequencing vendors, public repositories) where the reference might be labeled generically as “GRCh38” but could be any of the many variations (UCSC, NCBI, Broad, DRAGEN, etc.). You can also explore the web UI at whatsmygenome.acgt.bio.

Option B: Using samtools samples

A simpler check using samtools to verify if a specific reference file matches your CRAM:

docker run -v $PWD:$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 samtools samples \
  -h -f $PWD/hg38.fa $PWD/sample.sorted.noalt.hg38.cram

If you see a . in the last column of the output, your reference does not match.

Step 2: Validate Your CRAM

Ensure the file isn’t truncated or corrupted:

docker run -v $PWD:$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 samtools quickcheck \
  $PWD/sample.sorted.noalt.hg38.cram \
  && echo OK

Step 3: Convert to FASTQ

Now convert the name-sorted BAM to paired-end FASTQ files:

docker run -v $PWD:$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 samtools fastq \
  -@ 36 \
  --reference $PWD/ucsc/hg38.fa \
  -1 $PWD/sample.R1.fastq.gz \
  -2 $PWD/sample.R2.fastq.gz \
  $PWD/sample.sorted.noalt.hg38.cram

Step 4: Repair Paired-end Reads

Trimming or filtering can sometimes desynchronize paired-end reads. Fix that with bbmap’s repair.sh:

docker run -v $PWD:$PWD quay.io/biocontainers/bbmap:39.26--he5f24ec_0 repair.sh \
    in1=$PWD/sample.R1.fastq.gz \
    in2=$PWD/sample.R2.fastq.gz \
    out1=$PWD/sample_R1.fixed.fastq.gz \
    out2=$PWD/sample_R2.fixed.fastq.gz \
    outs=$PWD/sample_singletons.fastq.gz repair

Step 5: Check FASTQ with Fastp

Use fastp to trim adapters, filter low-quality reads, and generate QC reports.

docker run -v $PWD:$PWD quay.io/biocontainers/fastp:1.0.0--heae3180_0 fastp \
  -w 36 \
  -i $PWD/sample_R1.fixed.fastq.gz \
  -I $PWD/sample_R2.fixed.fastq.gz \
  -o $PWD/results/sample_R1.fastp.fastq.gz \
  -O $PWD/results/sample_R2.fastp.fastq.gz \
  -j $PWD/results/sample.fastp.json \
  -h $PWD/results/sample.fastp.html \
  --detect_adapter_for_pe

Final Output

After these steps, you will have:

• Quality control reports (.json, .html) from fastp.
• Singleton reads (optional): sample_singletons.fastq.gz
• Cleaned and validated FASTQ files: sample_R1.fixed.fastq.gz and sample_R2.fixed.fastq.gz

Troubleshooting Tips

• Repairing reads is important if your pipeline expects synchronized pairs (e.g., for STAR, BWA, etc).
• If Fastp removes too many reads, inspect the quality thresholds or adapter settings.
• If samtools fastq fails, double-check that the BAM is name-sorted.
• For example, in one case, a company used hg38_no_alt.fasta that was not available, and I could not find it anywhere on the internet. It worked just fine with the UCSC hg38.fasta. In situations like this, ref-solver identify can help you narrow down which reference genome variant was actually used.
• Try to use the exact reference genome used during alignment, but in case you have a derived reference, one possible solution is to use the base reference used to create the derived reference. Use ref-solver score to compare your candidate reference against the CRAM header and confirm compatibility.

Conclusion

CRAM files are efficient for storage, but getting back to raw reads for reanalysis requires care. With this step-by-step pipeline, you can reliably convert and clean CRAMs into FASTQ using reproducible Docker-based commands.

Extra: Nextflow Simple Pipeline

Here’s a Nextflow pipeline that automates the entire workflow:

1. check_cram_reference
2. validate_cram
3. sort_cram_to_bam
4. bam_to_fastq
5. fastp_cleanup
6. repair_reads

Directory Structure (suggested)

project/
├── main.nf
├── nextflow.config
├── data/
│   ├── input.cram
│   └── reference.fa

main.nf

nextflow.enable.dsl=2

params.cram        = "data/input.cram"
params.reference   = "data/reference.fa"
params.sample_id   = "sample"
params.outdir      = "results"

workflow {
    Channel
        .fromPath(params.cram)
        .set { cram_ch }

    check_cram_reference(cram_ch, file(params.reference))
        | validate_cram
        | sort_cram_to_bam
        | bam_to_fastq
        | fastp_cleanup
        | repair_reads
}

process check_cram_reference {
    tag "$sample_id"

    input:
    path cram
    path reference

    output:
    path "cram.ok", emit: ok

    script:
    sample_id = cram.getBaseName().tokenize('.')[0]
    """
    mkdir -p refcheck
    docker run -v \$PWD:\$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 \\
        samtools samples -h -f $reference $cram > refcheck/${sample_id}_ref_check.txt
    touch cram.ok
    """
}

process validate_cram {
    tag "$sample_id"

    input:
    path cram_ok

    output:
    path "${params.cram}", emit: cram

    script:
    """
    docker run -v \$PWD:\$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 \\
        samtools quickcheck ${params.cram} && echo OK
    cp ${params.cram} .
    """
}

process sort_cram_to_bam {
    tag "$sample_id"

    input:
    path cram
    path reference from file(params.reference)

    output:
    path "sorted.bam", emit: bam

    script:
    """
    docker run -v \$PWD:\$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 \\
        samtools sort -@ 4 -O bam -n --reference $reference \\
        -o sorted.bam $cram
    """
}

process bam_to_fastq {
    tag "$sample_id"

    input:
    path bam
    path reference from file(params.reference)

    output:
    tuple path("R1.fastq.gz"), path("R2.fastq.gz")

    script:
    """
    docker run -v \$PWD:\$PWD quay.io/biocontainers/samtools:1.22--h96c455f_0 \\
        samtools fastq -@ 4 --reference $reference \\
        -1 R1.fastq.gz -2 R2.fastq.gz $bam
    """
}

process fastp_cleanup {
    tag "$sample_id"

    input:
    tuple path(r1), path(r2)

    output:
    tuple path("clean_R1.fastq.gz"), path("clean_R2.fastq.gz")

    script:
    """
    mkdir -p ${params.outdir}/fastp
    docker run -v \$PWD:\$PWD quay.io/biocontainers/fastp:1.0.0--heae3180_0 \\
        fastp -w 4 -i $r1 -I $r2 \\
        -o clean_R1.fastq.gz -O clean_R2.fastq.gz \\
        -j ${params.outdir}/fastp/fastp.json \\
        -h ${params.outdir}/fastp/fastp.html \\
        --detect_adapter_for_pe
    """
}

process repair_reads {
    tag "$sample_id"

    input:
    tuple path(r1), path(r2)

    output:
    tuple path("fixed_R1.fastq.gz"), path("fixed_R2.fastq.gz"), path("singletons.fastq.gz")

    script:
    """
    docker run -v \$PWD:\$PWD quay.io/biocontainers/bbmap:39.26--he5f24ec_0 \\
        repair.sh \\
        in1=$r1 in2=$r2 \\
        out1=fixed_R1.fastq.gz \\
        out2=fixed_R2.fastq.gz \\
        outs=singletons.fastq.gz \\
        repair
    """
}

nextflow.config

params {
  cram      = "data/input.cram"
  reference = "data/reference.fa"
  sample_id = "sample"
  outdir    = "results"
}

process.container = ''
process.executor = 'local'
process.errorStrategy = 'terminate'

Run the Pipeline

nextflow run main.nf --cram data/input.cram --reference data/reference.fa --sample_id SAMPLE01

Published originally on Medium.

This analysis was performed as part of a case study published in Haematologica, where we investigated fraternal twins with HJV mutations causing hemochromatosis but with highly discordant iron overload severity. One of the twins carried a BUB1B variant associated with mosaic variegated aneuploidy syndrome, which motivated a genome-wide aneuploidy assessment from WGS data to rule out chromosomal abnormalities as a contributing factor.

In this post, I walk through the practical approach used for assessing aneuploidy from germline WGS data using two complementary tools: AStra and QDNAseq.

Why Assess Aneuploidy from WGS?

In rare disease programs like the Undiagnosed Diseases Network (UDN), patients typically receive WGS as part of their evaluation. When a case involves phenotypes that could be explained by chromosomal abnormalities — such as developmental delay, growth restriction, or congenital anomalies — checking for aneuploidy directly from the existing sequencing data is a practical first step before pursuing more targeted assays.

Tools

AStra

AStra generates genome-wide aneuploidy profiles and aneuploidy spectra from WGS data. It corrects for GC content and mappability biases, segments the genome, and calls gains and losses relative to a diploid reference. The aneuploidy spectrum — a frequency distribution of read depths — provides a clear visual summary of the ploidy state.

Reference: Khalil AIS, Chattopadhyay A, Sanyal A. Analysis of Aneuploidy Spectrum From Whole-Genome Sequencing Provides Rapid Assessment of Clonal Variation Within Established Cancer Cell Lines. Cancer Inform. 2021;20:11769351211049236. PMID: 34671179

The figure below from Khalil et al. shows an example of AStra output on MCF7 cancer cell line strains. On the left, the aneuploidy profile shows copy number states per genomic segment. On the right, the aneuploidy spectrum shows the read depth frequency distribution, where the red line denotes the RD median and the dotted black lines denote CN states.

Figure 1: From Khalil, A. I. S., Chattopadhyay, A., & Sanyal, A. (2021). Genome-wide aneuploidy profiles (left) and aneuploidy spectra (right) for MCF7 strain C, G, H, and P.

QDNAseq

QDNAseq is a Bioconductor R package for DNA copy number analysis from shallow or standard-depth WGS. It uses fixed-size bins across the genome, applies corrections for mappability and GC content, and produces segmented copy number profiles with gain/loss calls.

Reference: Sie D, et al. QDNAseq: A bioinformatics pipeline for DNA copy number analysis from shallow whole genome sequencing with noise levels near the probabilistic lower limit imposed by read counting. Clinical Cancer Research. 2016;22(1_Supplement):52-52.

Approach

The analysis follows a trio design (proband + mother + father), which provides built-in controls — unaffected parents are expected to be diploid, and any deviation in the proband relative to both parents is more likely to be real.

WGS BAM/CRAM (Proband + Parents)
    │
    ├── AStra
    │     ├── GC & mappability correction
    │     ├── Segmentation & CN calling
    │     ├── Aneuploidy profile (per chromosome)
    │     └── Aneuploidy spectrum (genome histogram)
    │
    └── QDNAseq
          ├── Bin-level read counting
          ├── GC & mappability correction
          ├── Segmentation
          └── CN profile with gain/loss calls

Running both tools independently serves as mutual validation. If both agree on the ploidy state, confidence in the result is high.

Interpreting the Results

Aneuploidy Profile

The aneuploidy profile shows copy number states across all chromosomes. For a normal diploid sample, the profile should be flat at CN=2 across all autosomes, with expected differences on sex chromosomes.

Key things to look for:

• Whole-chromosome gains or losses (trisomy, monosomy)
• Segmental aneuploidies (partial gains/losses of chromosome arms)
• Consistency between proband and parents — deviations present in the proband but absent in both parents suggest a de novo event

Below is an example from the QDNAseq documentation (low-grade glioma sample LGG150, chromosomes 7–10) showing how CN profiles look after correcting for GC content, mappability, segmenting, and calling gains and losses. This helps illustrate how to interpret the actual trio results in Figure 5.

Figure 2: Example from QDNAseq documentation — CN profile after correcting for GC content, mappability, segmenting, and calling gains and losses.

Aneuploidy Spectrum

The aneuploidy spectrum is a histogram of read depth values across the genome. In a diploid sample, the distribution should have a single sharp peak centered at CN=2. Additional peaks or broad shoulders would indicate the presence of cells with different copy number states.

For all three samples, the aneuploidy spectrum shows no significant deviation — each has a clean, single-peak distribution.

Figure 3: AStra aneuploidy spectrum histogram for all samples. No significant change in the aneuploidy profile across the trio.

QDNAseq Read Count Profile

QDNAseq provides a complementary view with bin-level resolution. The segmented profile should align with AStra’s results. Gains appear as segments above the baseline, and losses appear below.

Figure 4: QDNAseq histogram for aneuploidy spectrum for all samples. The read depth (RD) median (red line) and CN states (black line) refer to CN=2 (diploid).

QDNAseq CN Profile

The full QDNAseq CN profile across the genome for all three samples confirms the diploid state, with no gains or losses called in any sample.

Figure 5: QDNAseq CN profile after calling gains and losses across the genome for all samples.

Example: Diploid Confirmation in a Trio

In a recent case, a proband and both parents were analyzed:

Both AStra and QDNAseq confirmed diploid states across all three samples with no significant deviations. The aneuploidy spectra showed clean, single-peak distributions centered at CN=2. The slightly lower CN=2 coverage in the father is within normal variation and likely reflects noise in regions with low mappability.

This result effectively rules out aneuploidy as the cause of the proband’s phenotype, redirecting the diagnostic effort toward sequence-level variants (SNVs, indels, structural variants) instead.

When This Analysis Is Most Useful

• Phenotypes suggestive of chromosomal abnormalities — developmental delay, intellectual disability, multiple congenital anomalies, growth abnormalities
• Cases without prior karyotype or CMA — extracting aneuploidy information from existing WGS avoids additional testing
• Mosaic aneuploidy screening — AStra’s spectrum can reveal low-level mosaicism as secondary peaks in the read depth distribution
• Quality control — unexpected aneuploidies can indicate sample swaps or contamination

Practical Tips

1. Always analyze the trio together. Parents provide a baseline — if something looks off in the proband, check if the same pattern appears in a parent before calling it significant.
2. Use both tools. AStra excels at the spectrum-level overview while QDNAseq provides finer bin-level resolution. Agreement between both increases confidence.
3. Check sex chromosomes separately. The expected CN differs by sex (XX vs XY), so sex chromosome aneuploidies like Turner (45,X) or Klinefelter (47,XXY) require sex-aware interpretation.
4. Consider sequencing depth. Shallow WGS (~0.1-1x) works for large-scale aneuploidies but may miss smaller segmental events. Standard clinical WGS (~30-40x) provides sufficient resolution for both.

References

1. Khalil AIS, Chattopadhyay A, Sanyal A. Analysis of Aneuploidy Spectrum From Whole-Genome Sequencing Provides Rapid Assessment of Clonal Variation Within Established Cancer Cell Lines. Cancer Inform. 2021;20:11769351211049236. PMID: 34671179
2. Sie D, et al. QDNAseq: A bioinformatics pipeline for DNA copy number analysis from shallow whole genome sequencing. Clinical Cancer Research. 2016;22(1_Supplement):52-52.

Nesse artigo vamos falar sobre o que é a anotação de dados advindos de sequenciamento, o problema dos transcritos que são muito importantes biologicamente, mas em termos de interpretação tornam as coisas mais desafiadoras. Sobre os bancos de dados de referência genômica, como o gnomAD e como os utilizamos. Também falaremos um pouco sobre previsões in silico. No final, vamos discutir outros bancos de dados que podem ser úteis na análise de pacientes com doenças raras.

Quando fazemos o sequenciamento de painéis de genes, exoma ou genoma o resultado final mais “bruto” dos pipelines de bioinformática normalmente é um arquivo de chamada de variantes, que é apenas uma lista de todos os locais onde a sequência difere do sequência de referência, que é a sequência genômica humana de referência que foi determinada como padrão. Existem muitos tipos diferentes de variantes que podemos encontrar. Essas variantes vão cair em diferentes transcritos e terão frequências diferentes na população em geral e podemos prever que terão diferentes consequências com base em previsões de algoritmos chamados in silico.

Tipos de variantes, onde em rosa temos o mRNA e em roxo a proteína resultante (Elise Valkanas, 2019).

Só para lhe dar um exemplo do que eu quero dizer com tipos de variantes, a tabela acima se restringe a variantes do tipo substituição, onde apenas um nucleotídeo é substituído por outro nucleotídeo. Essa é o tipo de variante mais comum, sendo aproximadamente 80% das variantes reportadas nos bancos de variantes públicos. Voltando a imagem, a sequência de referência é listada no topo. Dentro das substituições temos a variante missense é algo que muda o DNA, o RNA e o aminoácido. A variante sinônima também deve mudar o DNA e o RNA, mas não muda a proteína. Em seguida, a variante frameshift insere uma base no DNA e RNA, todos os aminoácidos seguintes mudem, e uma variante nonsense muda um aminoácido ou uma base que causa um códon de parada (stop codon) e trunca a proteína.

Falando um pouco mais sobre tipos de variantes ainda temos deleção, inserção, duplicação, deleção-inserção, inversão e variantes estruturais.

• As inserções (AAC-GTT > AACAGTT) são variantes onde um ou mais nucleotídeos são inseridos na sequência. Quando a sequência inserida é uma repetição (tandem copy) da sequência original de DNA, chamamos de duplicação. Mesma ideia, quando uma duplicação afeta mais de 50 pb nós nos referimos como CNVs.
• As deleções (AACGTT > AAC-TT) são variantes onde um ou mais nucleotídeos são deletados da sequência, sendo o segundo tipo de variante mais comum. Quando uma deleção afeta mais de 50 pares de bases (pb), nós referimos a ela como variante no número de cópias (Copy Number Variants, CNVs).

Ambas duplicação e deleções ocorrem frequentemente em pequenas regiões repetitivas do DNA.

• As variantes estruturais acabam sendo um termo comumente utilizado para grandes mudanças no cromossomo como translocações e transposições. É importante ressaltar aqui que esse tipo de variante é extremamente difícil de ser detectada utilizando sequenciamento de sequências curtas (short reads, tipo Illumina ou MGI), mesmo que existam algoritmos para isso o tamanho das sequências por si já são um fator limitante para detecção de grandes variantes estruturais e até mesmo as pequenas. Se a variante estrutural for muito grande é possível visualizar por meio de tecnologias de mapeamento óptico ou microscopia (cariótipo).
• As inversões (AACGTT > ACGTTT) ocorrem quando um pedaço da sequência se inverte, a nova sequência é exatamente o reverso-complemento da sequência deletada. Elas possuem um tamanho mínimo de dois nucleotídeos, sendo os casos de um uma simples substituição não é mesmo?!
• As deleção-inserção (AACGTT > AATATT) é a combinação de deleções seguidas de inserções na mesma localização do DNA, parecido com a substituição, um ou mais nucleotídeos são substituídos por um ou mais nucleotídeos.

Se é do seu interesse ver mais estudos sobre variantes estruturais eu tenho um repositório no GitHub com o que acabei achando de material sobre essas variantes e como analisá-las usando sequenciamento genético, só clicar aqui.

Nomenclatura HGVS

Existem dois tipos de nomenclaturas sendo a primeira a que vemos nos arquivos VCF, mas a mais comum clinicamente é a nomenclatura da Human Genome Variation Society (HGVS). Ela utiliza a letra “c.” para explicar a mudança no DNA e a letra “p.” para a mudança no aminoácido. A nomenclatura HGVS e a VCF não se encaixam perfeitamente. A HGVS faz anotações em relação ao transcrito, então é muito importante saber qual transcrito você está se referindo. Já a VCF faz anotações baseadas nas coordenadas genômicas no genoma de referência utilizado e sempre se refere à fita positiva ou superior (fita 5’) do DNA.

• As variantes em sítios de splicing são escritas como a posição “c.” mais próxima e se é negativo ou positivo (c.345–2A>T).
• As variantes frameshift são escritas indicando quantas bases estão após a mudança até encontrar um códon de parada (p.Glu54fs ou p.Glu54Glyfs ou Glu54GlyfsX5).
• As variantes nonsense ou stop loss são representadas de três maneiras diferentes, mas todas indicam a introdução de um códon de parada (p.Arg24* ou p.Arg24X ou p.Arg24Ter).
• Para uma variante INDEL descrevemos as bases que são deletadas com a notação “c.” e a mudança real para a proteína. É importante mencionar que INDELs em frame são quando você deleta três bases, ou seja, um aminoácido, mas mantém os aminoácidos seguintes mantendo o quadro de leitura da proteína (c.1115_1117delCCT, p.Ser372del).
• Para variantes missense ou não-sinônimas, se apresenta a posição do códon, como por exemplo a troca de uma isoleucina para valina (p.Ile123Val).
• Para variantes sinônimas ou silenciosas usamos principalmente a notação “p.”, por exemplo, p.= ou p.Ile123= ou p.Ile123Ile para uma isoleucina que se mantém uma isoleucina mesmo com a troca do aminoácido.

Comparação da anotação para a variante Phe508del no gene CFTR (Anne O’Donnell-Luria, 2019).

• HGVS: NM_000492.3(CFTR) c.1521_1523delCTT ou chr7 g.117199646_117199648del
• VCF: chr7 117199644 ATCT A

Novamente, a HGVS se refere ao transcrito e alinha tudo à direita (linha azul na imagem acima), enquanto a notação no VCF se alinha tudo à esquerda (linha vermelha na imagem acima), o que pode causar algumas discrepâncias entre os dois sistemas. Como exemplo, podemos usar a variante Phe508del no gene CFTR que é a variante mais comum para fibrose cística. Na anotação presente no VCF, ancoramos à esquerda na letra A, que não é deletada, e depois deletamos as letras CTT (linha vermelha na imagem acima). Já na nomenclatura HGVS, ancoramos à direita, e como sobram as duas letras T, não podemos dizer quais letras foram deletadas (linha azul na imagem acima). Por isso, na notação HGVS, é relatado que as letras CTT foram deletadas. Isso é importante porque se você estiver procurando em um banco de dados que usa HGVS e o banco de dados estiver usando a notação VCF, pode parecer que você está procurando variantes diferentes. Portanto, é crucial que seus dados estejam anotados de uma maneira que se alinhe com outros dados, para obter a anotação correta em cada variante. Assim, é comum termos ambas as anotações quando criamos bancos ou planilhas para análise.

Genomas de referência

Os genomas de referência são outra complicação, onde temos uma sequência de referência do genoma humano consensual e pesquisadores trabalham na melhoria e preenchimento dessa sequência. Em sua maior parte, os genes não mudam, mas o espaço entre eles está sendo preenchido com detalhes adicionais. Além disso, haplótipos — regiões que variam bastante entre diferentes populações — estão sendo preenchidos, o que torna os genomas cada vez mais complexos. Recentemente foi publicado mais uma versão do genoma humano chamado telomere-to-telomere (T2T), resolvendo várias regiões complexas do genoma que ficaram indisponíveis por anos, aumentando o número de promessas de descobertas e de uso clinicamente [4–6].

Apenas para mostrar um exemplo, esta é a mesma variante no gene CFTR que falamos anteriormente:

• hg37: chr7 117199644 ATCT A
• hg38: chr7 117559590 ATCT A

HG37 é um genoma de referência que foi usado por muito tempo e ainda existem bancos de dados que são baseados apenas nele, enquanto que o HG38 é a referência atualmente recomendada clinicamente. No exemplo acima você verá que as alterações de base são as mesmas, mas as posições são diferentes. Elas estão, na verdade, separadas por 350 kilobases (KB). Se você olhar para uma variante no genoma de referência errado ela pode parecer estar em um gene ou localização totalmente diferente do que você esperava, por isso é muito importante saber em qual construção do genoma você está trabalhando.

Se você tiver o arquivo BAM ou CRAM é possível identificar o genoma que foi utilizado para o alinhamento olhando o cabeçalho do arquivo por meio de ferramentas de bioinformática como o SAMtools. Mas se você quer visualizar variantes, basta abrir o arquivo na ferramenta IGV que se for o genoma errado você verá um alinhamento colorido que indica variantes na posição em comparação com o genoma:

Exemplo de BAM alinhado no hg38 aberto na ferramenta IGV usando o genoma de referência hg19 (George Carvalho, 2023).

Métricas de qualidade para variantes

Exemplo de variante com algumas métricas de qualidade comumente usadas (Anne O’Donnell-Luria, 2019).

Existem vários tipos de métricas de qualidade que são usadas para identificar variantes presentes em um arquivo VCF. No exemplo acima, temos um ID para a amostra (GCGS_FAM8_23), o nucleotídeo referência A (que não aparece em negrito) e o G que representa a variante alternativa. O conjunto A/G indica que o paciente é heterozigoto para a variante G na posição onde se espera um A. Se fosse homozigoto para a variante, seria G/G (ambos em negrito), e se fosse homozigoto para a referência, seria A/A.

• VQSR (Variant Quality Score Recalibration): Não está presente nesse exemplo, mas é uma métrica bem sofisticada baseada em modelos Gaussianos por mistura para avaliar se uma variante é mais parecida com uma variante real ou com um artefato. Quando olhamos para os dados, é possível encontrar uma lista de pontuações de VQSR para cada variante [7].
• AB (Allele Balance ou equilíbrio alélico): é outra característica importante e representa o número de leituras com a variante alternativa em relação ao número total de leituras cobrindo a posição onde se encontra. Neste exemplo, 31% das leituras apresentam a variante alternativa, o que está dentro do esperado para algo heterozigoto de linha germinativa — cerca de 50%. No entanto, vale lembrar que sempre há uma distribuição de leituras e, quanto menor a porcentagem, maior a chance de que essa variante seja somática neste paciente.
• DP (Depth ou profundidade): É o número de leituras que cobrem uma determinada posição onde a variante se encontra, aqui com 54 leituras nessa posição. Para WGS consideramos DP=10 e WES consideramos DP=100 como valores mínimos para se reportar uma variante.
• GQ (Genotype Quality ou qualidade do genótipo): Essa métrica varia de 0 a 99, sendo que 99 representa a qualidade máxima. Geralmente, olhamos para as variantes com GQ>20. Porém, é importante ressaltar que é possível ter variantes reais com pontuações mais baixas e artefatos com pontuações mais altas.

Versões dos transcritos de um gene

Versões de transcritos para o gene CFTR no site gnomAD (George, 2023).

Os transcritos são importantes na interpretação das variantes graças a sua localização no gene podendo ter diferentes impactos. É importante mencionar que existem dois bancos de dados principais para transcritos:

• Ensembl, que é o EMBL-EBI ou GENCODE e mais voltado para anotações europeias.
• RefSeq, que é baseado no NCBI americano.

O RefSeq tende a ter menos opções de transcritos, enquanto Ensembl tende a ter mais. Geralmente, o transcrito canônico é o que todos nós falamos e nos referimos como o principal transcrito, mas isso geralmente é apenas porque é o maior e inclui todos os éxons. Isso não significa necessariamente que ele seja a transcrição clinicamente mais relevante. É importante lembrar que existem grupos trabalhando na definição dos transcritos clinicamente mais relevantes, como o projeto MANE. Ele é um projeto colaborativo que tem como objetivo convergir na anotação de genes e transcritos humanos e definir um conjunto representativo de transcritos e proteínas correspondentes para genes codificantes de proteínas em todo o genoma humano [8]. Cada transcrito MANE representa uma correspondência exata nas regiões exônicas entre um transcrito no RefSeq e sua contraparte na anotação Ensembl/GENCODE, de modo que os dois identificadores possam ser usados simultaneamente. Além disso, um transcrito MANE corresponde perfeitamente ao genoma de referência GRCh38 e é escolhido com base em critérios biologicamente relevantes, como níveis de expressão do transcrito e a conservação das regiões codificadoras.

Ferramentas de predição de impacto

Exemplo de ferramentas de predição de impacto de variantes (Anne O’Donnell-Luria, 2019).

No geral, muitas dessas ferramentas de predição de impacto (análise in silico) usam os mesmos dados de treinamento e métricas semelhantes para os modelos, o que significa que há muita circularidade em usar vários preditores in silico. Por outro lado, é melhor ter mais dados do que menos. Por isso, tendemos a olhar para muitas ferramentas, mas não os consideramos de forma aditiva. Apenas pensamos um pouco sobre o consenso e alguns deles confiamos um pouco mais do que outros. No entanto, para um efeito específico de uma variante, é realmente difícil saber qual é o mais importante. Não vou entrar em detalhes sobre nenhum deles, mas direi que alguns são apenas para variantes missense e outros para todos os tipos de variantes e isso é útil apenas para ter uma pontuação para cada variante. Além disso, existe a ferramenta SpliceAI que foi desenvolvida pela Illumina para predição de junções de splicing, permitindo a predição do impacto de variantes não codificantes como as sinônimas e intrônicas que podem alterar o mecanismo de splicing [9].

Conservação

(Seção a ser expandida em futuras atualizações.)

Referências

1. Jaganathan, Kishore, et al. “Predicting splicing from primary sequence with deep learning.” Cell 176.3 (2019): 535–548
2. Morales, Joannella, et al. “A joint NCBI and EMBL-EBI transcript set for clinical genomics and research.” Nature 604.7905 (2022): 310–315
3. GATK technical documentation — Variant Quality Score Recalibration (VQSR)
4. Aganezov, Sergey, et al. “A complete reference genome improves analysis of human genetic variation.” Science 376.6588 (2022): eabl3533
5. Alkan, Can, et al. “Implications of the first complete human genome assembly.” Genome Research (2022)
6. Miga, Karen H., and Beth A. Sullivan. “Expanding studies of chromosome structure and function in the era of T2T genomics.” Human Molecular Genetics 30.R2 (2021): R198-R205
7. Patrinos, George P. Clinical DNA Variant Interpretation: Theory and Practice. Academic Press, 2021
8. Interpreting Genomes for Rare Disease: Variant and Gene Interpretation — Anne O’Donnell-Luria, MD, PhD, 2019
9. Interpreting genomes for rare disease: variant and gene interpretation, 2019

Publicado originalmente no Medium.

No campo do diagnóstico de doenças raras, as tecnologias de sequenciamento desempenharam um papel vital na identificação de mutações genéticas e genes causadores de doenças. No entanto, antes de mergulharmos nos componentes práticos do artigo, é crucial ter uma compreensão básica do processo de seleção de casos para sequenciamento. Este artigo abordará o processo de seleção, tanto para famílias que são mais propensas a fornecer um diagnóstico genético quanto para estudos de pesquisa interessados em identificar novos genes de doenças. Também discutiremos brevemente o processo de sequenciamento, as três diferentes tecnologias de sequenciamento com seus pontos positivos e negativos. O objetivo final é fornecer uma compreensão aprofundada das tecnologias de sequenciamento e seu papel no diagnóstico de doenças raras.

Doenças que caem no espectro de arquitetura genética (Daniel MacArthur, 2019).

Doenças raras são apenas uma ponta do espectro de doenças humanas e existem doenças que se encaixam em todo esse espectro de arquitetura genética. Por um lado, temos as doenças em que tradicionalmente trabalhamos no meu grupo: doenças monogênicas muito graves, que podem ser relativamente leves, mas são monogênicas no sentido de que segregam dentro de famílias específicas de maneira dominante, recessiva ou pelo cromossomo X. Elas são normalmente causadas por um número muito pequeno de variantes por família, ou seja, uma ou duas variantes, tipicamente em um único gene, que contribuem para aquela doença e normalmente seguem um padrão mendeliano. Por exemplo, no caso da família dominante mencionada, você tem um único pai afetado que transmitiu a variante da doença para 50% de seus filhos, mas existem algumas ressalvas a serem abordadas futuramente.

Por outro lado, no outro extremo do espectro de doenças, temos as doenças comuns e complexas, que são as que causam a maior mortalidade e morbidade em toda a população humana, como diabetes tipo 2, doenças cardíacas ou câncer. Essas doenças geralmente, mas nem sempre, são massivamente poligênicas, o que significa que em qualquer caso individual existe uma ampla gama de fatores de risco genéticos normalmente pequenos, bem como fatores de risco ambientais que contribuem para o risco daquela pessoa desenvolver a doença. Claro, em alguns casos extremos dessas condições, também existem formas monogênicas, e, em geral, as variantes causais para essas doenças tendem a ser substancialmente mais comuns, mas têm efeitos muito menores do que o que vemos para doenças raras.

É importante ressaltar que este artigo se concentrará principalmente nas doenças raras e monogênicas. Vamos focar em entender as tecnologias de sequenciamento que são usadas para identificar variantes causais para essas doenças e as melhores práticas para interpretar essas variantes.

Manolio et al. (2009), Nature. 461:747–753.

As variantes genéticas que contribuem para o desenvolvimento de doenças seguem um espectro que pode ser representado em dois eixos. No eixo X, temos a frequência alélica da variante, onde as variantes extremamente raras estão localizadas no final esquerdo do espectro e as variantes mais comuns no final direito. Já no eixo Y, temos o tamanho do efeito, que representa a probabilidade de uma pessoa que carrega essa variante desenvolver a doença. As variantes que possuem grande probabilidade de causar a doença estão localizadas no topo do espectro e convergem para o conceito de penetrância. Já as variantes com menor efeito estão localizadas na parte inferior do espectro, que é o que normalmente se pensa em estudos de associação genômica em larga escala (GWAS).

No entanto, é importante ressaltar que no canto superior direito do espectro, onde estaríamos esperando encontrar variantes com grande efeito, quase não existem variantes comuns. Isso se deve ao fato de que, se houvesse uma variante que aumentasse significativamente o risco de doença, a seleção natural provavelmente a eliminaria da população. Por outro lado, no canto inferior esquerdo do espectro, existem variantes extremamente raras e com efeitos muito pequenos que são impossíveis de detectar com as amostras e tecnologias atuais. Para detectar essas variantes, precisaríamos ter milhões de amostras.

As variantes que podemos detectar e estudar estão localizadas no meio do espectro, onde estão as variantes raras com efeitos enormes associadas às doenças mendelianas no canto superior esquerdo e as variantes comuns com efeitos pequenos que são encontradas em estudos GWAS no canto inferior direito. À medida que aplicamos abordagens de sequenciamento de próxima geração em distúrbios complexos mais comuns, estamos começando a descobrir uma variedade de variantes no meio do espectro.

Estratégia geral

Ao se deparar com casos de doenças raras, nossa estratégia geral é começar com uma família afetada pela doença. Geralmente, essa família já passou por extensos exames prévios, como painéis de genes ou sequenciamento de genes individuais, em busca de causas conhecidas da doença. No entanto, mesmo após anos de tentativas de diagnóstico sem sucesso, nossa primeira abordagem para a análise genética dessas famílias é sequenciar os exomas de todos os membros da família.

Esse método de sequenciamento de exoma (WES) é quase sempre a nossa primeira linha de abordagem para a descoberta genética. Isso ocorre porque, em muitos casos, cerca de 25% a 40%, dependendo da doença em questão, somos capazes de encontrar um diagnóstico usando essa técnica. Quando não conseguimos encontrar um diagnóstico, continuamos a analisar os dados do exoma periodicamente, geralmente a cada 6 a 12 meses, para verificar se alguma nova descoberta genética altera o diagnóstico para aquela família em particular.

Em casos em que não conseguimos encontrar um diagnóstico após vários anos de análise do exoma ou para casos em que há uma forte suspeita de que a condição seja de origem genética, mas o exoma é completamente silencioso, usamos o sequenciamento completo do genoma (WGS) e sempre que possível também realizamos o sequenciamento de RNA dos tecidos afetados.

Estratégia para seleção das famílias para provável diagnóstico ou pesquisa de gene

No contexto do diagnóstico, vemos que o WES é realmente nosso teste de frente. Obviamente, painéis e várias outras formas de pré-seleção foram críticos em muitos contextos de diagnóstico, mas ir direto para o exoma ou, possivelmente, para um array, achamos que é agora uma abordagem realmente eficiente para ir o mais rápido possível em direção a um diagnóstico genético. Somos um pouco agnósticos em relação à tecnologia exata que usamos, mas em geral, se estivermos em uma situação em que o dinheiro é limitante — e vamos encarar, isso é típico, embora nem sempre — geralmente somos a favor do WES porque é a abordagem mais eficaz em termos de custo para encontrar o máximo de diagnósticos para um determinado gasto. Mas se estamos limitados pelas amostras — especialmente se temos uma família em que o caso específico é extremamente urgente ou clinicamente urgente em alguns casos, ou se temos uma doença específica em que temos um número muito pequeno de famílias que podemos obter — sabemos que queremos sequenciá-las e analisá-las o mais minuciosamente possível, então às vezes vamos direto para o WGS. Isso ocorre normalmente em uma situação em que as amostras são mais limitantes do que o dinheiro.

No contexto da descoberta de genes, nosso objetivo aqui é realmente obter o maior número possível de famílias afetadas por uma doença específica. Tentamos nos concentrar o máximo possível e aumentar nosso tamanho de amostras sem diluir muito a homogeneidade clínica dos casos. No contexto da descoberta de genes, investimos muito tempo em perguntar a colaboradores e famílias sobre pré-seleção, tentando obter famílias onde muito trabalho foi feito para descartar outras causas de doenças. Vamos nos concentrar em estruturas familiares solucionáveis. Isso é principalmente sobre evitar pequenas famílias dominantes e se concentrar em casos em que achamos que há uma chance razoável de realmente poder obter um diagnóstico com outra estrutura familiar que vemos. Quase sempre favoreceremos WES, pelo menos como uma abordagem de primeira linha na descoberta de genes, porque, novamente, a probabilidade de descobrir um novo gene por dinheiro gasto é substancialmente maior no contexto do WES.

Tipos de famílias que focamos os estudos

Quais tipos de famílias são estudadas (Daniel MacArthur, 2019).

Estudo genético de famílias é uma das ferramentas mais poderosas para entender as causas de doenças hereditárias. Existem diferentes tipos de famílias que podem ser estudadas, cada uma com suas próprias vantagens e desafios. Um dos tipos de famílias mais interessantes é aquela com pais não afetados e vários filhos afetados. Isso sugere uma doença recessiva, o que muitas vezes pode ser resolvido com apenas uma única família. Identificar o gene candidato responsável pela doença pode ser relativamente fácil nesses casos. Outra explicação possível é mosaicismo e transmissão. No entanto, isso também pode ser resolvido com uma mutação de novo recorrente presente em ambos os filhos.

No entanto, o tipo de família mais comum é um trio com pais não afetados e um filho afetado. Nesses casos, é menos provável que possamos identificar o gene causal com apenas uma única família. Mas se a doença for causada por uma mutação de novo, temos uma boa chance de identificar o gene causal. Além disso, temos uma chance razoável de identificar causas recessivas.

Para famílias dominantes com doenças de início tardio ou compatíveis com a reprodução, geralmente precisamos de famílias substancialmente maiores para ter alguma chance real de descobrir novos genes da doença. Em geral, tendemos a nos concentrar em famílias dominantes muito maiores sempre que pudermos ter acesso a elas. Nessas situações, tentaríamos sequenciar os dois indivíduos afetados mais distantes geneticamente com WES e também tentaríamos realizar microarray para análise de linkage na família inteira.

O último tipo de design de estudo é a coleta de amostras de pacientes com condições de início tardio, pois muitas vezes os pais não estão disponíveis ou são muito difíceis de se obter acesso. Para doenças como distrofia muscular de Lynn Girdle e algumas doenças de retina, estamos construindo uma coleção de amostras de muitos indivíduos afetados pela mesma condição clínica. Em seguida, comparamos centenas de casos com milhares de controles que foram sequenciados na mesma plataforma e procuramos genes que tenham um excesso de mutações patogênicas raras nos casos em relação aos controles.

Em resumo, a escolha do tipo de família ou design de estudo depende da doença que está sendo estudada e da disponibilidade de famílias maiores e amostras de pacientes. Cada tipo de família tem suas próprias vantagens e desafios, mas todos eles podem ser usados para entender melhor as causas de doenças genéticas.

Outras considerações ao escolher famílias para estudo

Seleção de famílias para estudos de sequenciamento é uma questão complexa. Normalmente a preferência é por famílias com pais não afetados e múltiplos filhos afetados, sugerindo uma desordem recessiva. Nesses casos, geralmente é possível identificar o gene candidato que causa a doença. O segundo tipo de família mais comum é o trio, com pais não afetados e um filho afetado. Embora seja menos provável identificar a causa exata com uma única família, há uma boa chance de identificar mutações de novo. Para famílias dominantes com doenças de início tardio ou compatíveis com a reprodução, são necessárias famílias maiores para descobrir novos genes. Famílias pequenas com apenas uma transmissão tendem a ter pouca sorte em descobrir novos genes. Para doenças de início tardio, está se tornando mais comum coletar grandes grupos de pacientes para análises.

Além disso, a regulamentação é crítica. As famílias precisam ter dado consentimento apropriado para pesquisa e compartilhamento de dados. A disponibilidade de DNA de outros membros da família também é importante em alguns casos. A apresentação clínica incomum pode ser um critério para selecionar uma família. Para WGS é preferível ter acesso a amostras de tecido relevantes para doença para análises de RNA, que podem fornecer informações importantes sobre o impacto funcional das variantes.

Uma grande consideração em nosso contexto de pesquisa, porque a rede é extremamente rigorosa em garantir que as amostras que passam por aqui tenham o consentimento apropriado tanto para sequenciamento quanto para compartilhamento de dados, é a questão regulatória. Portanto, temos as famílias sido adequadamente consentidas para pesquisa e, importantemente, outras consentidas para depósito de seus dados em bancos de dados de acesso controlado como dbGaP, para que outros pesquisadores possam realmente acessar seus dados.

Olhamos muito para a disponibilidade de DNA de outros membros da família e, para alguns projetos de família, isso é absolutamente crítico. Há um critério um pouco vago e incerto aqui, que é a singularidade da apresentação clínica e, tipicamente, descobrimos que, nos casos em que há uma apresentação fortemente sindrômica ou outras características incomuns desse caso em particular, temos muito mais chances de encontrar um novo gene de doença do que se parecer um caso padrão, por exemplo de distrofias musculares.

E o último ponto, para o qual voltarei mais tarde, é que preferimos muito, especialmente para WGS, amostras onde é possível obter acesso a amostras de tecido relevantes para a doença que possamos usar para RNA-seq e a razão para isso é que descobrimos que o RNA-seq nos dá ideias sobre o impacto funcional direto de variantes que afetam a expressão em splicing, o que muitas vezes pode ser muito difícil de prever apenas a partir da sequência de DNA.

Lição 1: Pequenas análises baseadas em famílias geralmente são insuficientes para a descoberta de doenças geneticamente complexas. Isso ocorre porque, assim que você sai da causa monogênica muito estrita da doença, sua descoberta cai precipitadamente. Precisamos olhar para centenas ou possivelmente milhares de amostras para ter o poder de rejeitar essas causas mais complexas geneticamente da doença.

Lição 2: Temos que ser muito cautelosos em relação a relatórios de triagem prévia. A precisão das triagens prévias para testes de painel, por exemplo, depende muito de quem fez a triagem, ou seja, qual laboratório estava envolvido na realização e execução desse teste de painel específico, qual tecnologia foi usada e quando foi feito.

Como funciona o sequenciamento

Sequenciar bilhões de sequências por corrida de sequenciamento (Daniel MacArthur, 2019).

Para entender o processo de sequenciamento de terceira geração (trabalhando aqui particularmente com short-read da Illumina), é importante saber que ele basicamente envolve a coleta de uma amostra de DNA de uma pessoa, a quebra dessa amostra em pequenos fragmentos ou leituras individuais de DNA, a leitura de cada um desses segmentos e, em seguida, a união desses segmentos para formar uma imagem da sequência subjacente do genoma ou exoma dessa pessoa. Na prática, se falando de short-read sequencing a maioria das leituras que obtemos pode ter de 100 a 150 pares de bases de comprimento, tanto para WES ou WGS. A partir dessas leituras, podemos formar um conjunto de dados que é representado por um mar de leituras.

Comparar as sequências com o genoma de referência (Daniel MacArthur, 2019).

Outro passo importante desse processo é o uso de uma sequência de referência. Essa sequência é definida como um padrão de referência usado universalmente. Atualmente, existem duas sequências de referência amplamente utilizadas na comunidade: a build 37 (hg19 ou GRCh37) e a build 38 (GRCh38 ou hg38). Muitos estão fazendo a transição da build 37 para a build 38, que já está sendo utilizada em bancos de dados de referência como o gnomAD.

NGS nos permite sequenciar uma mesma posição múltiplas vezes (Daniel MacArthur, 2019).

Para iniciar esse processo, é necessário utilizar uma sequência de referência padrão que representa uma média da sequência da população humana. A seguir, são utilizados algoritmos de alinhamento, como o BWA, para alinhar todas as leituras individuais de DNA contra essa sequência de referência. Embora esse processo de alinhamento não seja simples e possa apresentar erros, quando realizado adequadamente, é possível identificar variantes de sequência comuns ou raras diretamente a partir dos dados de leitura. O número de leituras de DNA em diferentes partes da sequência de referência pode variar, e em algumas áreas é possível identificar uma base que difere pelo menos em algumas leituras daquela do indivíduo de referência. Isso é chamado de variantes ou polimorfismos e a medida de confiança de que essa variante é real é dada pela relação entre o número de bases de referência e as bases não referenciadas, chamada frequência alélica.

Mapear dados de leituras curtas em relação à sequência de referência é um grande desafio. Normalmente, as leituras possuem cerca de 150 pares de bases, o que pode resultar em ambiguidade na hora de alinhar as leituras com a sequência de referência, especialmente em regiões altamente repetitivas. Além disso, a cobertura do genoma pode variar bastante em diferentes partes do genoma, o que afeta a confiança na chamada de variante de um determinado local. A qualidade da posição tende a ser substancialmente pior para inserções e deleções (INDELs) em comparação com variantes de nucleotídeo único (SNPs). A sensibilidade para INDELs ainda está longe da perfeição, mesmo com dados de sequenciamento de boa qualidade, e a taxa de erro para INDELs é certamente muito maior do que para SNPs. Para piorar, a detecção de variantes estruturais (SVs), como deleções, duplicações (CNVs) e outros rearranjos de DNA em larga escala, é muito difícil.

Tipos de arquivos — FASTQ, BAM/CRAM, VCF (Daniel MacArthur, 2019).

Em relação à interpretação de dados de sequenciamento, existem três tipos de arquivos importantes a serem considerados: FASTQ, BAM/CRAM e VCF. O arquivo FASTQ contém os dados brutos de leitura que são gerados pela máquina de sequenciamento. Uma vez que essas leituras são alinhadas à sequência de referência, obtemos um arquivo BAM ou CRAM, que consiste em uma lista de leituras ordenadas pela sua posição em relação ao genoma de referência. O último tipo de arquivo é o VCF, que contém todas as variantes identificadas no arquivo BAM ou CRAM.

Fazer um genoma ter sentido requer a comparação com muitos outros (Daniel MacArthur, 2019).

Para compreender as variações que surgem de cada um desses arquivos VCF, é necessário compará-los com bancos de dados populacionais como o gnomAD. Esses conjuntos de dados consistem em indivíduos de referência que foram agregados onde é possível verificar para qualquer variante encontrada no paciente, a frequência com que ela foi observada em uma coleção de dezenas de milhares de indivíduos — 140.000 indivíduos no caso do gnomAD — e o quão comum ela é em diferentes populações.

Tecnologias disponíveis

1. Microarrays

Genotipagem por Microarrays, região de interesse em vermelho (Daniel MacArthur, 2019).

Para explorar as variações presentes no genoma de um indivíduo, existem várias tecnologias disponíveis. Uma dessas tecnologias é a genotipagem por meio de microarray. Esta tecnologia permite a investigação de posições específicas no genoma, geralmente posições que contêm variações comuns na população em geral. Os microarrays são extremamente baratos, com centenas de milhares de marcadores podendo ser testados por apenas ~$20. Podendo ser extremamente útil para análises de linkage em famílias. No entanto, os microarrays têm uma limitação importante: eles não detectam a maioria das variações raras, pois suas posições não incluem a maioria das variantes que são geralmente causadoras de doenças raras.

2. WES

Sequenciamento de Exoma, região de interesse em vermelho (Daniel MacArthur, 2019).

Uma tecnologia muito mais útil para o nosso contexto é WES que é uma tecnologia focada na parte codificante do genoma humano que conhecidamente dá origem a proteínas, representando cerca de 2% do total do genoma, mas contém praticamente todas as partes que realmente entendemos a função biológica. A grande vantagem do WES é seu custo, o preço para sequenciar o exoma pode chegar a menos de $200. Isso permite que você obtenha sequenciamento para todos os tipos de variantes, incluindo variantes muito raras presentes nas regiões codificantes de proteínas do genoma. O lado negativo do WES é que ele só fornece o que você está procurando, ou seja, apenas as regiões codificantes do genoma, sendo todo o resto descartado.

Sequenciamento com alvo (target sequencing), região de interesse em vermelho (Daniel MacArthur, 2019).

A ideia básica do WES é usar beads ou alguma outra sonda que contenha sequências individuais que se hibridizam apenas com as partes de sequência que estamos interessados em sequenciar, neste caso, as regiões codificantes de proteínas.

A cobertura do exoma é alta mas possui alta variabilidade (Daniel MacArthur, 2019).

Um dos desafios na análise de dados de sequenciamento de exoma é a grande diferença na cobertura de um exon para outro. Podemos ver que a cobertura média dessas regiões é de 50X a 60X, mas há uma enorme variação. Alguns exons têm cobertura de até 150X, enquanto outros têm cobertura muito baixa ou nenhuma cobertura em uma amostra específica.

A cobertura do genoma é bem uniforme quando comparado ao exoma (Daniel MacArthur, 2019).

Para comparar, é assim que a cobertura de sequenciamento se parece nos dados de sequenciamento do genoma. A cobertura, em média, é menor do que nas sequências do exoma, mas a uniformidade é maravilhosa. Há uma faixa muito estreita de cobertura, onde quase todos os éxons no genoma tendem a ser cobertos dentro de uma precisão bastante apertada.

Por que WES como primeira alternativa?

Então, vale a pena perguntar por que fazemos sequenciamento de exoma. A resposta óbvia é que é muito barato e podemos fazer um exoma familiar de trio por menos do que o custo de um único WGS hoje em dia. A cobertura mais alta dos segmentos principais significa que temos, talvez, 60X ou às vezes uma cobertura ainda maior em exons individuais. Mas a grande vantagem do sequenciamento de exoma é que ele nos fornece cobertura custo-efetiva das partes do genoma que podemos realmente interpretar. E quase todas as mutações conhecidas de doenças raras são encontradas nessas regiões codificadoras de proteínas. Achamos que é provável que mais de 85% de todas as variantes causais verdadeiras para condições mendelianas caiam dentro do exoma.

3. WGS

Sequenciamento de genoma completo, região de interesse em vermelho (Daniel MacArthur, 2019).

O sequenciamento de todo o genoma de uma pessoa é substancialmente mais caro do que o sequenciamento do exoma. Ele cobre quase todas as 3 bilhões de bases do genoma humano, com exceção das partes altamente repetitivas que são desafiadoras de serem mapeadas. No entanto, o sequenciamento do genoma inteiro tem muitas vantagens, como a possibilidade de identificar facilmente variações no número de cópias (CNVs) e variações estruturais (SVs), além da capacidade de descobrir variantes não codificantes.

Exemplo de casos resolvidos por WGS

Pacientes com distrofia muscular de Duchenne que foram diagnosticados graças à análise de WGS (Daniel MacArthur, 2019).

Vou dar um exemplo de um caso que só poderia ser resolvido usando o sequenciamento completo do genoma. Esse caso foi descoberto em um estudo sobre distrofia muscular de Duchenne, que é a forma mais comum de distrofia muscular. Ela afeta principalmente meninos, exceto em casos raros. A doença é causada por mutações no gene DMD, encontrado no cromossomo X.

Caso sem diagnóstico com inversão de éxon do gene DMD (Daniel MacArthur, 2019).

Na imagem acima, temos parte do gene DMD, que é um gene enorme no cenário genômico. Podemos observar duas coisas. Primeiro, há uma seção de leituras que está completamente ausente aqui. Então, neste menino, parece haver uma deleção, mas ela está no íntron do gene. No entanto, há também esse interessante grupo de leituras que estão se alinhando na orientação oposta ao que esperaríamos. Isso é característico de uma inversão.

Caso de inversão do éxon no gene DMD (Daniel MacArthur, 2019).

Uma vez que resolvida a posição das leituras individuais, fica claro o que aconteceu: pequenas deleções de um lado e uma maior em verde. Além disso, o éxon encontrado nessa região foi invertido, resultando na sua exclusão da transcrição. Isso resultou em uma mudança no quadro de leitura, levando à perda completa do RNA e da proteína no paciente em questão. Apenas com o WGS é possível detectar rearranjos como este.

WGS não resolve tudo

Com o tempo descobrimos que mesmo sequenciando todo o genoma, nem sempre conseguimos solucionar todos os casos que sequenciamos. O WGS completo fornece apenas um aumento de 5% a 10% no poder de diagnóstico para casos que já tiveram WES. Para a grande maioria dos casos que foram negativos para o exoma, o sequenciamento do genoma não fornecerá a resposta.

4. RNA-seq

Sequenciamento de RNA, região de interesse em vermelho (Daniel MacArthur, 2019).

A tecnologia de sequenciamento de RNA, embora ainda não amplamente utilizada em diagnósticos, é muito poderosa e esperamos que seja cada vez mais adotada. O sequenciamento de RNA é diferente das outras tecnologias mencionadas, pois se concentra no RNA mensageiro em vez dos componentes de DNA do genoma. Ele sequencia todas as regiões expressas do genoma e fornece informações diretas sobre o impacto de variantes genéticas na expressão gênica e splicing. Sua capacidade de detectar interrupções no splicing tem sido poderosa para identificar variantes de splicing não anotadas.

Dois casos não diagnosticados de miopatia relacionada ao colágeno

Paciente com miopatia relacionada ao colágeno VI (Daniel MacArthur, 2019).

A miopatia do colágeno é uma doença rara em que os distúrbios nos genes do colágeno seis (COL6), geralmente dominantes, mas às vezes recessivos, resultam em uma variedade de fenótipos musculares relativamente graves. O médico da paciente na imagem tinha certeza do diagnóstico de miopatia do colágeno 6, mas não conseguiram identificar uma variante causal, apesar de terem feito o sequenciamento de todas as três cadeias do colágeno 6, WES e WGS.

Gráfico de sashimi onde RNA-seq identifica um ganho de splicing intrônico no gene COL6A1 (Daniel MacArthur, 2019).

Foram obtidas amostras de RNA muscular desses dois pacientes e sequenciado o RNA. Na última fileira do gráfico de sashimi, vemos o RNA-seq de um controle em uma região do genoma que contém três éxons do gene COL6A1. O que chamou a atenção em ambos os casos diagnosticados com colagenopatia 6 foi que ambos tinham um novo pseudo éxon que aparecia no meio de um intron e que não foi visto em nenhum outro indivíduo normal para quem o sequenciamento de RNA muscular foi feito — cerca de 180 pessoas.

A variante GC>GT gera um sítio doador de splicing (Daniel MacArthur, 2019).

Ao analisarmos a sequência do genoma nessa região específica, encontramos em ambos os pacientes uma mutação de GC para GT, resultando em uma variante doador de splice GT no meio de um íntron. Essa mutação GT resultou na criação de um novo local de splice e, portanto, na criação de um novo exon no meio da sequência intrônica. Curiosamente, essa inclusão de exon parece ser específica para o músculo e essa variante se tornou a mutação mais comum nos casos não diagnosticados de miopatia do colágeno 6.

Quando considerar RNA-seq?

O sequenciamento de RNA é mais útil em casos onde há um gene candidato forte, mas a causa genética ainda não está clara. Especialmente em casos de famílias recessivas, onde há apenas uma mutação em um gene recessivo que se encaixa perfeitamente no fenótipo, mas não há uma segunda variante codificadora que explique o caso daquela família em particular.

Um segundo fator chave é a disponibilidade de tecido. É realmente importante sequenciar o tecido certo. Outra coisa a considerar é que muitas das mutações causais descobertas com RNA-seq afetarão o splicing, muitas vezes fora das regiões de splicing canônicas. Portanto, é útil ter dados de WGS em paralelo com o RNA-seq.

Alguns pontos a serem discutidos

Será que o WGS vai substituir WES como teste de entrada?

WES é mais eficiente em termos de custo do que o WGS, vale a pena pensar sobre o momento em que WGS se tornará a tecnologia mais eficiente em termos de custo. Acreditamos que isso provavelmente acontecerá em algum momento nos próximos anos, embora vale mencionar que à medida que o preço do WGS diminui, o preço do WES continua a acompanhar.

Quais classes de genes relacionados a doenças podem ser descobertas apenas por WGS?

Exemplos disso poderiam ser casos em que todas as mutações causais para aquela doença específica são em regiões do genoma que não codificam proteínas por algum motivo, ou podem estar em alguma região que é inacessível por WES.

Como lidar com a descoberta de genes em casos de doenças em que a causa genética subjacente não é monogênica?

Especialmente em condições genéticas complexas, onde é provável que haja vários genes que contribuam para esse fenótipo. Nesse caso, a única resposta é o tamanho da amostra. Só com grupos de mais de 1000 indivíduos é que poderíamos começar a obter o poder necessário.

Quais tipos de tecidos são uma boa opção para RNA-seq?

Um caso a se considerar é a utilização de RNA-seq de alta profundidade do sangue. Além disso, sempre que possível, obter fibroblastos seria muito útil. Eles parecem ser um tipo de tecido mais útil em geral do que o sangue. Acredita-se que isso seja especialmente verdadeiro para condições neurológicas, em que fibroblastos parecem ser um melhor substituto para o cérebro do que o sangue.

Referências

1. Manolio, Teri A., et al. “Finding the missing heritability of complex diseases.” Nature 461.7265 (2009): 747–753.
2. Interpreting Genomes for Rare Disease: Intro to Next Generation Sequencing — Daniel MacArthur, PhD, 2019
3. Interpreting genomes for rare disease: variant and gene interpretation, 2019

Publicado originalmente no Medium.

Foi originalmente desenvolvida para a área de Genômica pelo instituto BROAD, mas pode ser usado em diversas outras áreas que trabalhem com dados.

WDL se lê “Widdle”.

Não vou entrar em comparações entre linguagens de workflow, que são várias. Para quem tem interesse, existe essa lista feita pelo pessoal do CWL (Common Workflow Language). Particularmente, eu tenho mais interesse por Nextflow (pretendo escrever tutoriais usando isso posteriormente). Mas comecei usando CWL, depois Nextflow, dei uma olhada em Snakemake e hoje tenho estudado WDL.

Isso depende muito do grupo que você está trabalhando e parecido com linguagens de programação você deve entender onde melhor aplicadas elas seriam. WDL por exemplo tem uma relação muito forte com o pessoal da ferramenta GATK e o Terra (baseado no Google Cloud), assim já existem diversos scripts que você pode reutilizar, por exemplo no BioWDL você já encontra alguns.

Aprendendo WDL

Iremos trabalhar os tutoriais do “learn-wdl”, para isso faça download do repositório e abra a pasta com seu editor de código.

Para o Visual Studio Code recomendo baixar a extensão “WDL DevTools”.

git clone https://github.com/openwdl/learn-wdl.git

Ambiente do WDL

Usei como referência esse material do learn-wdl. Eu estou trabalhando em cima do Ubuntu Xenial (16.04). Primeiramente você precisa ter os seguintes pré-requisitos:

Java:

java -version
# openjdk version "1.8.0_275"
# OpenJDK Runtime Environment (build 1.8.0_275-8u275-b01-0ubuntu1~16.04-b01)
# OpenJDK 64-Bit Server VM (build 25.275-b01, mixed mode)

Para instalar você pode usar os seguintes comandos:

sudo apt install openjre-8-headless
# ou
sudo apt update
sudo apt install default-jdk

Docker:

docker --version
# Docker version 17.06.1-ce, build 874a737

Para instalar o Docker:

curl -sS https://get.docker.com/ | sh
sudo usermod -aG docker $USER

Caso não funcione pra você procure na documentação do Docker.

Cromwell e Womtool:

sudo java -jar cromwell-56.jar --version
# cromwell 56

sudo java -jar womtool-56.jar --version
# womtool 56

Para instalar:

mkdir cromwell; cd cromwell
curl -L -o cromwell-56.jar https://github.com/broadinstitute/cromwell/releases/download/56/cromwell-56.jar
curl -L -o womtool-56.jar https://github.com/broadinstitute/cromwell/releases/download/56/womtool-56.jar

É bom copiar o caminho desses .jar para usarmos depois pra rodar os scripts.

Também é bom dar uma olhada no github para obter a release mais recente das duas ferramentas.

1. Como fazer um “hello world”

Volte a pasta do learn-wdl. No caso eu fui para:

cd ../learn-wdl/1_script_examples/1_hello_worlds/1_hello

Vamos analisar o código hello.wdl que temos as três principais partes do WDL:

version 1.0

workflow HelloWorld {
  call WriteGreeting
}

task WriteGreeting {
  command {
     echo "Hello World"
  }
  output {
     File output_greeting = stdout()
  }
}

• Linhas 7–15 nós temos a task que é um comando simples em bash para printar um “Hello” que vai ser um output com nome output_greeting.
• Linhas 3–5 temos a definição do workflow que simplesmente chama uma task definida.

2. Executando o script

• Cromwell é um serviço em Java que organiza a execução (job scheduler) e pode ser configurado para rodar em diferentes serviços (AWS, GCP, etc).
• WDL é o script que descreve o workflow.

Para começar vamos usar o Cromwell no modo Run que é normalmente utilizado para rodar protótipos, rodando workflows individuais. Podemos usar em uma máquina local (como fizemos anteriormente) ou em uma máquina virtual na nuvem.

Para trabalhar em produção normalmente se trabalha com o modo Server. Usando uma máquina na nuvem que vai ser utilizada como o organizador de execuções (Java scheduler), assim poderemos rodar múltiplos workflows.

Então como rodamos o script?

sudo java -jar /caminho/para/cromwell-56.jar run hello.wdl

Verás que o output é bem verboso, que no meio em algum momento ele printou nosso “Hello World” com sucesso!

3. Sobre o modo Server

Quando vamos rodar nossas análises, nós normalmente utilizamos o modo Server. Você pode utilizar do jeito mais comum que é na “nuvem pública” ou no seu próprio HPC (High Performance Computing):

• Terra.bio — Cromwell já disponível no ambiente da GCP.
• Azure — conjuntos de VMs com Azure batch.
• AWS — conjuntos de VMs com AWS batch.
• GCP — conjunto de VMs (máquinas virtuais) com life sciences APIs.

A ideia é você usar grupos de VMs que são ativadas dinamicamente. Os criadores indicam usar o Terra.bio por ter sido criado pela BROAD. Para mais informações veja o tutorial do learn-wdl no YouTube [1].

4. Lidando com erros

Vamos analisar agora com o script x_hello-error.wdl que possui um erro.

• Para o modo Run que estamos usando aqui a ferramenta womtool.jar vai ajudar a detectar possíveis erros no nosso script.
• Primeiramente tenha certeza de estar usando a versão mais atual do Cromwell. Assim você terá certeza que as especificações de linguagem e features são suportadas.

Agora vamos tentar rodar esse script e ver o que ele retorna.

cd ../2_hello_docker
sudo java -jar /caminho/para/cromwell-56.jar run x_hello-error.wdl
# ...
# Workflow f7b32c3a-6c99-4fdc-b161-4781fde97a2d transitioned to state Failed

Verás que ao final do processo uma mensagem indicando um Failed. Mas se você for para o meio do processo verá:

Failed to process workflow definition 'HelloWorld' (reason 1 of 1):
Cannot generate outputs for 'call WriteGreeting'.
No such callable exists in [WriteGreetings]

Com essa informação já podemos resolver o problema do script, mas vamos ver o que o womtool nos mostrará.

sudo java -jar /caminho/para/womtool-56.jar validate x_hello-error.wdl
# Failed to process workflow definition 'HelloWorld' (reason 1 of 1):
# Cannot generate outputs for 'call WriteGreeting'.
# No such callable exists in [WriteGreetings]

Ele nos mostra o mesmo resultado, porém não precisamos ficar procurando no meio dos processos do comando do Cromwell, facilitando nossa vida. Existem outros comandos que podem ser vistos na documentação ou usando o --help.

Abrindo o arquivo para resolver o bug:

version 1.0

workflow HelloWorld {
  call WriteGreeting
}

task WriteGreetings {
  command {
    echo "Hello World"
  }
  output {
    File output_greeting = stdout()
  }
  runtime {
    docker: "ubuntu:latest"
  }
}

Vemos a adição de um “s” na task WriteGreetings que deveria ser WriteGreeting. Resolvendo isso e rodando novamente obtemos sucesso no processo.

sudo java -jar /caminho/para/womtool-56.jar validate x_hello-error.wdl
# Success!

Para o modo Server no Terra.bio ao tentar fazer upload de um script no FireCloud ele vai mostrar o mesmo output do womtool.

Dependendo do ambiente na nuvem é preciso ter no script a descrição de runtime com os atributos docker que na primeira versão não tínhamos.

5. Variáveis no script

O script exemplo agora é o ~/learn-wdl/1_script_examples/1_hello_worlds/3_hello_input_task/input-task.wdl

version 1.0

workflow HelloInput {
  call WriteGreeting
}

task WriteGreeting {
  input {
    String name
  }
  command {
    echo 'hello ${name}!'
  }
  output {
    File response = stdout()
  }
  runtime {
    docker: 'ubuntu:latest'
  }
}

Primeiramente precisamos validar o script usando o womtool-56.jar como visto anteriormente:

sudo java -jar /caminho/para/womtool-56.jar validate input-task.wdl
# Success!

Feito isso, vamos tentar rodar ele usando o Cromwell:

sudo java -jar /caminho/para/cromwell-56.jar run input-task.wdl
# ...
# Workflow b13559c0-223d-4b08-9548-0a3a2ed1f111 transitioned to state Failed

Como vemos que falhou e subindo mais um pouco acharemos o motivo:

Required workflow input 'HelloInput.WriteGreeting.name' not specified

Então claramente ele quebrou porque não recebeu a variável esperada, nesse caso o womtool pode nos ajudar. Nele existe um modo inputs que indica se o script possui variáveis a serem dadas de entrada.

sudo java -jar /caminho/para/womtool-56.jar inputs input-task.wdl
# {
#   "HelloInput.WriteGreeting.name": "String"
# }

Esse comando nos retorna o que precisamos dar de entrada, no caso deveria ser um inputs.json no formato indicado pelo resultado do comando. Para facilitar nossa vida, podemos jogar isso para um arquivo e manipular "String" com o que queremos e então rodar o script novamente passando esse arquivo dessa vez.

sudo java -jar /caminho/para/womtool-56.jar inputs input-task.wdl > inputs.json
vim inputs.json

cat inputs.json
# {
#   "HelloInput.WriteGreeting.name": "Input"
# }

sudo java -jar /caminho/para/cromwell-56.jar run input-task.wdl --inputs inputs.json
# ...
# echo 'hello Input!'

Pensando no modo Server existe esse artigo no Terra super bem exemplificado de como usar variáveis lá. Além disso, esse artigo fala sobre os tipos de variáveis disponíveis que é bem útil na hora de você implementar seu pipeline mais na frente.

Tente fazer o mesmo com o script em ~/learn-wdl/1_script_examples/1_hello_worlds/4_hello_input_workflow/input-workflow.wdl.

6. Arquivos e variáveis de ambiente

Agora trabalharemos em cima do script ~/learn-wdl/1_script_examples/1_hello_worlds/5_hello_file/hello-file.wdl.

version 1.0

workflow HelloFile {
    input {
        File file_input
        Int mem_gb
    }
    call InputFile {
        input:
            file_input=file_input,
            mem_gb=mem_gb
    }
}

task InputFile {
    input {
        File file_input
        Int mem_gb
    }
    command {
        bash echo 'The file is ${file_input}!' ${mem_gb}
    }
    output {
        File result = stdout()
    }
    runtime {
        docker: "ubuntu:latest"
        memory: mem_gb + "GB"
        continueOnReturnCode: 126
    }
}

Aqui vamos usar o conceito anterior de passar um .json como entrada, no caso o arquivo que está na mesma pasta.

sudo java -jar /caminho/para/cromwell-56.jar run hello-file.wdl --inputs hello-file.json
# ...
# [warn] Local: Key/s [memory] is/are not supported by backend.
# Unsupported attributes will not be part of job executions.

Apesar de rodar com sucesso, temos essa observação de warn a ser analisada em meio a todos os processos printados na tela. Isso se chama memory assignment, só para mostrar que os parâmetros dependem do ambiente de execução.

Só pra lembrar que não precisa estar na pasta dos scripts para rodá-los, você pode passar o caminho+script que ele será rodado normalmente.

sudo java -jar /caminho/para/cromwell-56.jar run /caminho/para/hello-file.wdl \
    --inputs /caminho/para/hello-file.json

É comum usarmos arquivos que estejam salvos em buckets na nuvem, então é possível por esses arquivos no seu .json de entrada (com a devida permissão de acesso ao arquivo no bucket) para o script em WDL. Por exemplo:

{
    "HelloFile.file_input": "https://storage.googleapis.com/wdl-quickstart/wdl-data/input.txt",
    "HelloFile.mem_gb": 5
}

Isso é interessante uma vez que vamos rodar pipelines em VMs que estarão disponíveis apenas para gerar os resultados do pipeline, então arquivos que devem persistir para uso no pipeline podem ser incorporados assim.

7. Scripts mais legíveis

Abrindo o script em ~/learn-wdl/1_script_examples/1_hello_worlds/6_alias_task/hello-again.wdl vemos:

version 1.0

workflow HelloWorldWithDocker {
    call WriteGreeting as wg1
    call WriteGreeting as wg2
}

task WriteGreeting {
    command {
        echo "Hello Docker"
    }
    output {
        File output_greeting = stdout()
    }
    runtime {
        docker: "ubuntu:latest"
    }
}

Aqui é apenas para observar a possibilidade de criar alias com as task que usamos, no exemplo está repetida a call mas com alias diferentes que podemos ver no output quando rodamos o script.

sudo java -jar /caminho/para/cromwell-56.jar run /caminho/para/hello-again.wdl
# ...
# {
#   "outputs": {
#     "HelloWorldWithDocker.wg1.output_greeting": ".../call-wg1/execution/stdout",
#     "HelloWorldWithDocker.wg2.output_greeting": ".../call-wg2/execution/stdout"
#   }
# }

Existe outro exemplo em ~/learn-wdl/1_script_examples/1_hello_worlds/6_alias_task/hello-task.wdl caso queira refazer o processo. Mas para esse script nós vamos rodar um script que o importará para fazer a chamada das task contidas, isso se chama subworkflow. O script maior é o ~/learn-wdl/1_script_examples/1_hello_worlds/6_alias_task/hello-workflow.wdl

version 1.0

import "hello-task.wdl" as HelloTask

workflow HelloWorldWithDocker {
    call HelloTask.WriteGreeting
    call HelloTask.WriteGreeting as wg
}

Rodamos esse script que tem duas call para a mesma task só para exemplificar que sem o alias essa chamada daria erro por estar repetida. Além de introduzir o conceito de import e poder reutilizar scripts menores em processos maiores.

sudo java -jar /caminho/para/cromwell-56.jar run /caminho/para/hello-workflow.wdl
# ...
# {
#   "outputs": {
#     "HelloWorldWithDocker.WriteGreeting.output_greeting": ".../call-WriteGreeting/execution/stdout",
#     "HelloWorldWithDocker.wg.output_greeting": ".../call-wg/execution/stdout"
#   }
# }

Use os scripts em ~/learn-wdl/1_script_examples/1_hello_worlds/7_subworkflow/hello-workflow.wdl para treinar tudo que vimos sobre rodar workflow e inputs.

Aqui eu termino a primeira parte da introdução, de acordo com o curso do learn-wdl olhamos todos os arquivos da pasta ~/learn-wdl/1_script_examples/1_hello_worlds/. Na parte dois que estou escrevendo olharemos a pasta ~/learn-wdl/1_script_examples/2_language_patterns/, pelo menos essa é a ideia. Esse tutorial pode mudar a medida que eu for estudando, então se ligue nas referências.

Referências

1. What do I need to set up to write and execute WDL workflows?
2. How to set up GCE VM for WDL
3. Learn WDL Course playlist

Publicado originalmente no Medium.

Nesse tutorial vamos ver o PyCaret criado por Moez Ali. PyCaret é uma biblioteca aberta com pouco uso de código em Python. Ela permite que você prepare seus dados e compare modelos selecionando o melhor de acordo com uma métrica de interesse em poucos minutos. Ela pode ser usada para problemas de classificação, regressão, clusterização, detecção de anomalias, processamento de linguagem natural, mineração de regras de associação, etc.

No site deles existem alguns tutoriais bem interessantes, vale a pena dar uma olhada pra ver se é possível usar em algum projeto do seu interesse. Nas referências desse post vou deixar alguns materiais que levei em conta ao escrever esse. Aqui nós vamos usar dados bem simples do UCI “Heart failure clinical records Data Set” que já estão prontos (fora da realidade) para serem processados para um problema de classificação.

Eu recomendo você usar o Google Colab para testar essa ferramenta, o meu colab que usei para criar esse post pode ser visto aqui. Recomendo você criar do zero um novo e ir rodando aos poucos e à medida que tiver dúvidas ir jogando no google e pesquisando na documentação do PyCaret.

Na versão 2.x está disponível o uso de GPU para treinar os modelos, mas pra que usar o PyCaret?

• O pessoal usa os modelos criados pelo PyCaret nos dashboards do PowerBI.
• Testar modelos para projetos que você ache interessante usar aprendizagem de máquina (protótipos).

Instalando o PyCaret

Como estamos usando o Colab, basta usar o comando pip para instalar a ferramenta:

!pip install pycaret

Abrindo os dados de exemplo

Como eu disse antes vamos trabalhar com dados já bonitinhos para a criação de modelos e isso tá longe da realidade ok?! Esse é só um caso para a gente ver algumas utilidades do PyCaret. Os dados eu encontrei dentro de outro github e estou reaproveitando o link para abrirmos aqui. Primeiro importaremos as bibliotecas necessárias e logo depois usaremos a biblioteca Pandas (sim, subentendo que você já conheça) para abrir os dados no formato de Dataframe.

from sklearn.model_selection import train_test_split
import pycaret.classification as pc
import pandas as pd

data_url = "https://raw.githubusercontent.com/lorenzodenisi/Heart-Failure-Clinical-Records/master/heart_failure_clinical_records_dataset.csv"
data_df = pd.read_csv(data_url)
data_df.head()

Com os dados disponíveis, vemos se está tudo ok vendo o tamanho do Dataframe (299 amostras e 13 colunas) e se existe algum dado faltante (não deveria).

data_df.shape
data_df.isnull().sum()

Agora é bom dar uma olhada nas colunas para saber qual delas vamos usar como classe de interesse.

data_df.columns

No nosso caso vamos usar a coluna “DEATH_EVENT” como classe alvo, sempre é bom ver se estamos trabalhando com dados desbalanceados (apesar que não vamos levar isso em consideração agora).

data_df["DEATH_EVENT"].value_counts().plot(kind="bar")

Bora dividir os dados em treino e teste. Esse teste a gente só vai usar no final pra rodar a predição do modelo.

train, test = train_test_split(data_df, test_size=0.2, random_state=42)

Usando PyCaret, finalmente

Como visto antes importamos o pycaret.classification por estarmos trabalhando com um problema de classificação, para outros problemas como regressão por exemplo seria uma outra importação, para mais informações sobre isso dá uma olhada na documentação. Para ver os métodos e atributos disponíveis:

dir(pc)

Por estarmos usando o Google Colab é preciso fazer uma ativação do ambiente:

from pycaret.utils import enable_colab
enable_colab()

Agora podemos iniciar a brincadeira, para isso passamos os dados e a coluna alvo para o método setup:

clf = pc.setup(data=train, target="DEATH_EVENT")

Aqui você precisa dar enter se os tipos das colunas foram inferidos corretamente, senão é possível modificar após escrever quit a partir de parâmetro no setup, mais informações aqui. Além disso é possível aqui ignorar alguma coluna que você não queira usar como feature para os modelos, basta:

pc.setup(data=train, target="DEATH_EVENT", ignore_features=["ages", "diabetes"])

Não é o nosso caso ignorar colunas, então vamos seguir com o comando anterior.

Comparando modelos

Esse é o primeiro passo recomendado em qualquer experimento supervisionado. É bem simples e muito útil, ele mostra um relatório com cada modelo e as métricas obtidas. Com o parâmetro sort você pode especificar a métrica utilizada para ordenar os modelos, por definição é accuracy para classificação (R2 para regressão) mas vou utilizar F1 aqui.

Essa função treina todos os modelos disponíveis usando os parâmetros predefinidos e avalia seu desempenho usando validação cruzada, fold=10. Ela retorna o melhor modelo de acordo com a métrica estabelecida no sort. Alguns algoritmos são excluídos da análise pelo seu tempo de processamento, para evitar sua exclusão basta adicionar turbo=False.

model = pc.compare_models(sort="F1", turbo=False)

É possível adicionar uma lista com os modelos que você gostaria de excluir no processamento com o parâmetro exclude, mas não é o nosso caso. Mais informações na documentação.

pc.compare_models(exclude=["svm"])

Os nomes dos modelos estão na primeira coluna, na versão anterior era necessária usar a biblioteca neatutils para saber como ficava as abreviações.

Criando um modelo, a partir do vencedor

Aqui iremos de fato trabalhar o modelo vencedor da comparação anterior. Para isso usamos o create_model passando a abreviação do modelo vencedor ou a variável contendo a comparação que retornou o melhor modelo de acordo com a métrica escolhida, no nosso caso o F1-score.

Como visto anteriormente o modelo vencedor para os nossos dados foi o Random Forest. No caso de classificação essa função recebe apenas o modelo e retorna uma tabela com os k-fold da validação cruzada junto com o modelo treinado. O número de folds pode ser definido pelo parâmetro fold, mas por pré-definição teremos fold=10. A quantidade de valores decimais também pode ser ajustada pelo round, sendo quatro decimais por pré-definição. Aqui ainda é possível usar um parâmetro de ensemble, mais detalhes na documentação.

best_model = pc.create_model(model)

Tunando os hiperparâmetros

Com a função tune_model, os hiperparâmetros são tunados usando o Random grid search com grids predefinidos que podem ser customizados. Para aprendizado supervisionado, essa retorna uma tabela com k-fold validação cruzada com as métricas de avaliação junto com o modelo treinado.

tuned_model = pc.tune_model(best_model)

O número de fold pode ser alterado, mas por pré-definição é de 10. A quantidade de decimais também pode ser alterada pelo round, sendo de 4 por pré-definição. O número de iterações aleatórias feitas pelo Random grid search pode ser mudado pelo parâmetro n_iter, sendo de 10 por pré-definição. Aumentando esse valor o tempo de treinamento também aumenta. Além disso, é possível adicionar a métrica que deve ser otimizada pelo parâmetro optimize, para classificação é accuracy e regressão R2.

tuned_model_opt = pc.tune_model(best_model, optimize="F1", n_iter=25)

Se comparado, vemos que sem passar os parâmetros já tínhamos o “melhor” modelo. Seguiremos com ele então.

Avaliando o modelo

Para avaliar o modelo você pode usar o evaluate_model que mostrará todas as métricas e gráficos associados ao modelo em uma interface com abas para seleção ou você pode usar o plot_model e ir selecionando cada métrica ou gráfico individualmente.

pc.evaluate_model(tuned_model)

Por pré-definição o plot_model mostra o gráfico de AUC, mas você pode especificar o plot do seu interesse usando o parâmetro plot. Mais detalhes de possibilidades na documentação.

pc.plot_model(tuned_model)

pc.plot_model(tuned_model, plot="error")

Otimizando os limites (FN e FP)

Para problemas de classificação o custo de resultados falso-positivos (FP ou erro tipo 1) é normalmente diferente dos falso-negativos (FN ou erro tipo 2). Assim, se você está trabalhando em um projeto em que os erros tipo 1 e tipo 2 possuem impacto diferentes, é possível otimizar sua classificação para um valor limite (threshold) de probabilidade melhorando a função de perda (loss function) apenas definindo o custo de FP e FN separadamente.

Para isso usamos a função optimize_threshold que pega o modelo treinado e a função de perda representada pelos FP, FN, TP (verdadeiro-positivos) e TN (verdadeiro-negativos). Essa função retorna um gráfico interativo onde a função de perda no eixo-y é representada por uma função de probabilidade de diferentes valores limites no eixo-x. Uma linha vertical representa o melhor valor da probabilidade limite para seu classificador. Mais detalhes na documentação.

opt_prob = pc.optimize_threshold(tuned_model, true_negative=1500, false_negative=5000)

Não sei o motivo, mas para mim não apareceu nenhuma imagem. Testa aí e me diz se foi.

Interpretando o modelo

Aqui ele chama de interpretar o modelo, pra mim nada mais é que quais features o modelo deu mais importância. Talvez precise instalar a biblioteca shap que é uma abordagem de teoria dos jogos, mais info aqui.

!pip install shap
pc.interpret_model(tuned_model)

Finalizando o modelo

Esse é o último passo de um experimento supervisionado já que quando iniciamos o projeto usando o setup parte dos dados não é utilizado no treinamento. Com ele o modelo é treinado uma última vez com os dados completos, mais detalhes na documentação. Essa função recebe o modelo treinado e retorna o modelo treinado nos dados completos.

final_model = pc.finalize_model(tuned_model)

Salvando e abrindo o modelo

É bem simples de salvar seu modelo treinado, basta usar a função save_model passando o modelo treinado que será salvo todo o pipeline no formato pickle para usar posteriormente.

pc.save_model(final_model, "rf_saved_model_02152021")

Já para abrir o modelo é mais simples ainda, basta usar a função load_model com o nome do modelo que você usou.

loaded_rf = pc.load_model("rf_saved_model_02152021")

Como saída ele mostra o pipeline completo e os valores dos parâmetros do modelo.

Usando o modelo para predição

Vamos fazer uma predição usando os dados de teste que separamos no começo da análise. Também usarei o modelo que foi salvo e reaberto.

prediction = pc.predict_model(loaded_rf, data=test)
print(prediction.head())

Em Label vemos a predição feita pelo modelo final e na coluna vemos o DEATH_EVENT com a realidade. Um modelo simples que erra em alguns casos, mas acerta a maioria.

É possível melhorar esse modelo? Sim, mas por não ser o foco desse post recomendo olhar as referências e ver o que pessoal fez que pode melhorar os resultados desse projetinho.

Confesso que achei que ele seria útil nos dados que tou usando no meu projeto de mestrado. Porém, depois de 3 dias rodando ele estourou memória tentando rodar os meus dados /risos

MemoryError: Unable to allocate 1.04 TiB for an array with shape
(377799, 377799) and data type float64

Então voltarei a forma clássica de criar modelos para esses pequenos dados que tenho trabalhado. Deixo aqui o material que utilizei pra brincar um pouco com a biblioteca com o intuito de ser útil para alguém.

Referências

• Creating the Whole Machine Learning Pipeline with PyCaret
• Machine Learning Made Easy by PyCaret
• Machine Learning with PyCaret in Python
• A Gentle Introduction to PyCaret for Machine Learning
• PyCaret 2.x — A biblioteca de aprendizagem de máquinas para quem tem prazo
• Talks # 7: Moez Ali: Machine learning with PyCaret
• Machine Learning with PyCaret and Python

Publicado originalmente no Medium.