Add 5' truncation support and overlap file export

[guillermo1996]

Summary

This PR extends the truncateTxome() function to support truncation from the 5' end. It also introduces named wrapper functions for each ending site and adds the option to export a table of similar transcripts post truncation.

Key Changes

• Adds the parameter txEnd to the function truncateTxome(). This parameter controls the transcript termination from which the truncation starts. Defaults to "3prime" to keep the original truncation behaviour. Accepted values are: 3, 3', 3p, 3prime, 3_prime, 5, 5', 5p, 5prime and 5_prime.
• Adds the wrappers truncate3primeTxome() and truncate5primeTxome().
• Adds the parameter overlapFile to the function truncateTxome(). If provided, the function will export a CSV with two columns query_transcript and subject_transcript. These represent pairs of similar transcripts after truncation. Defaults to NULL to not export any file.
• Added the internal function .suppressTxDbGenomeWarning() to silence a specific TxDb genome-info warning. Implemented to remove unnecessary warnings during the truncation pipeline.
• Added unit tests for 5' truncation (test-5prime-truncation.R) and transcript overlap export (test-overlap-file.R). Renamed previous 3' truncation tests to test-3prime-truncation.R.

Usage example

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}

BiocManager::install("guillermo1996/txendcutr@5prime_extension_v2") # Or clone the branch and run `devtools::load_all()`

## load libraries
library(txcutr)
library(TxDb.Scerevisiae.UCSC.sacCer3.sgdGene)
library(txdbmaker)

## load annotation
txdb <- TxDb.Scerevisiae.UCSC.sacCer3.sgdGene

## restrict to certain chr transcripts
seqlevels(txdb) <- c("chrI")

## first 100 nts per tx (5' truncation)
txdb_5p_w100 <- truncateTxome(txdb, maxTxLength = 100, txEnd = "5prime")
txdb_5p_w100

## using convenience wrapper — equivalent to truncateTxome(..., txEnd = "3prime")
txdb_3p <- truncate3primeTxome(txdb, maxTxLength = 100)

## export overlap information to a CSV file
gr_collapse_test <- GRanges(
  seqnames = rep("chr1", 11), strand = "+",
  ranges = IRanges(
    start = c(1000, 1000, 2000, 2000, 1000, 1000, 1500, 1500, 2500, 1500, 2500), 
    end = c(6000, 5000, 5000, 5000, 5000, 1400, 5000, 6000, 6000, 6000, 6000)
  ),
  type = c("gene", "gene", "transcript", "exon", "transcript", "exon", "exon", "transcript", "exon", "transcript", "exon"),
  ID = c( "gene_1", "gene_2", "tx_1", "exon_1", "tx_2", "exon_2", "exon_3", "tx_3", "exon_4", "tx_4", "exon_5"),
  Parent = c(NA, NA, "gene_1", "tx_1", "gene_1", "tx_2", "tx_2", "gene_1", "tx_3", "gene_2", "tx_4"),
  gene_id = c("gene_1", "gene_2", "gene_1", "gene_1", "gene_1", "gene_1", "gene_1", "gene_1", "gene_1", "gene_2", "gene_2"),
  tx_id = c(NA, NA, "tx_1", "tx_1", "tx_2", "tx_2", "tx_2", "tx_3", "tx_3", "tx_4", "tx_4")
); txdb_overlap <- txdbmaker::makeTxDbFromGRanges(gr_collapse_test)

overlap_output_path <- tempfile()
txdb_w100 <- truncateTxome(txdb_overlap, maxTxLength = 100, overlapFile = overlap_output_path)
read.csv(overlap_output_path)

Compatibility

Both new parameters default to values that replicate previous txcutr behaviour, making this PR fully backwards-compatible.

Other Notes

• This is the first of two planned PRs. Once merged, a follow-up will address optimisations to the truncation algorithm and update NEWS and README accordingly (README, vignettes, and NEWS are not modified in this PR).
• Code coverage is not updated in this PR.