Skip to contents

This function reads GTF/GFF annotation files (e.g., from GENCODE, Ensembl, RefSeq) and converts them to a standardized data frame format compatible with ez_* functions.

Usage

import_gtf(
  file,
  region = NULL,
  features = c("gene", "exon", "transcript", "CDS", "start_codon", "stop_codon"),
  gene_id_col = "gene_id",
  gene_name_col = "gene_name",
  transcript_id_col = "transcript_id",
  verbose = FALSE
)

Arguments

file

Path to GTF/GFF file. Can be gzipped (.gtf.gz, .gff.gz) or uncompressed.

region

Optional genomic region in format "chr:start-end" to filter features. If NULL (default), imports all features in the file. Example: "chr19:16000000-16100000"

features

Character vector of feature types to retain (e.g., c("gene", "exon")). Default: c("gene", "exon", "transcript", "CDS", "start_codon", "stop_codon"). Set to "all" to keep all features found in the file.

gene_id_col

Column name/attribute to extract as gene_id. Default: "gene_id". This is typically "gene_id" in GENCODE/Ensembl GTF files.

gene_name_col

Column name/attribute to extract as gene_name. Default: "gene_name". Falls back to gene_id if gene_name is not available in the annotation.

transcript_id_col

Column name/attribute for transcript IDs. Default: "transcript_id".

verbose

If TRUE, print import progress messages. Default: FALSE

Value

A data frame with standardized columns:

seqnames

Chromosome name (e.g., "chr19", "1")

start

Start coordinate (1-based, as in GTF)

end

End coordinate (1-based, inclusive, as in GTF)

width

Feature width (end - start)

strand

Strand information: "+" (forward), "-" (reverse), or "*" (unknown)

type

Feature type: "gene", "exon", "transcript", "CDS", etc.

gene_id

Gene identifier (e.g., "ENSG00000000003")

gene_name

Gene symbol/name (e.g., "PTPRC"), fallback to gene_id if unavailable

transcript_id

Transcript identifier (e.g., "ENST00000000005"), may contain NA

...

Additional columns from GTF attributes (varies by source)

Details

The function automatically extracts gene identifiers, gene names, and transcript IDs from the GTF attributes column, handling missing values gracefully.

Examples

if (FALSE) { # \dontrun{
# Download GENCODE v47 (replace with actual URL/file):
# url <- "https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/
#        gencode.v47.primary_assembly.annotation.gtf.gz"

# Import entire GTF
gtf_df <- import_gtf("gencode.v47.annotation.gtf.gz")
head(gtf_df)
table(gtf_df$type)  # View feature type distribution

# Import only genes and exons (reduces memory usage)
gtf_df <- import_gtf("gencode.v47.annotation.gtf.gz",
                     features = c("gene", "exon"))

# Import region of interest (e.g., PTPRC locus)
gtf_df <- import_gtf("gencode.v47.annotation.gtf.gz",
                     region = "chr19:16000000-16100000")
subset(gtf_df, gene_name == "PTPRC")

# Use imported GTF with ez_gene
library(ezGenomeTracks)
ez_gene(gtf_df, "chr19:16000000-16100000", label = "gene_name")
} # }