# Visualize transcripts on genomic scale

Source: `R/visualization.R`
`plot_transcripts_view.Rd`

Visualize exon-intron structure of transcripts on genomic scale.

    plot_transcripts_view(
      dturtle,
      genes = NULL,
      gtf,
      genome,
      one_to_one = NULL,
      tested_transcripts_only = "mixed",
      reduce_introns = TRUE,
      reduce_introns_fill = "white",
      reduce_introns_min_size = 50,
      include_ID_in_title = TRUE,
      fontsize_vec = c(10, 1.1, 0.6),
      arrow_colors = c("#7CAE00", "#00BFC4"),
      arrow_start = 0.88,
      extension_factors = c(0.025, 0.22),
      savepath = NULL,
      filename_ext = "_transcripts.png",
      add_to_table = FALSE,
      BPPARAM = BiocParallel::SerialParam(),
      ...
    )

## Arguments

dturtle | `dturtle` result object of `posthoc_and_stager()`.
genes | Character vector of genes to plot. If `NULL`, defaults to all found significant genes (`sig_genes`).
gtf | Either path to a `gtf/gff` file which will be read or a `granges` object of a already read in `gtf/gff` file. Such an object can be created with `import_gtf("GTF_PATH", feature_type=NULL, out_df=FALSE)`. See `import_gtf()` for more information.
genome | The genome on which to create the ideogram tracks. This has to be a valid `UCSC genome identifier` (e.g. 'hg38', 'mm10', 'danRer11', etc.). Can also be NULL to skip ideogram track generation.
one_to_one | Specify `TRUE`, if one_to_one mapping of gene/transcript identifiers with their respective names was enforced before (with `one_to_one_mapping()`). If a non default extension character (`ext`) has been used, please specify the used extension character.

tested_transcripts_only

Specify, if only transcripts which were tested in DTU analysis should be plotted. This are only the not-filtered transcripts of significant genes. Defaults to `mixed`, meaning if a gene has no tested transcripts (i.e. it was not significant), it defaults to all non-filtered transcripts of this gene. Can also be `FALSE` to allow all transcripts, or `TRUE` to exclude all untested transcripts.

reduce_introns | Logical if intron ranges shall be shrunken down, highlighting the exonic structure.
reduce_introns_fill | Optionally specify the background color of ranges where introns have been reduced.
reduce_introns_min_size | Specify the minimal size introns are reduced to (in bp).
include_ID_in_title | Logial, if the Gene-ID should be included in the plot title. Defaults to TRUE.
fontsize_vec | Vector of fontsizes to use. The first value is the side annotation text fontsize (in pt), the second value the cex factor for the title, the third value the cex factor for the feature & chromosome names.
arrow_colors | Specify the colors of the arrows indicating the direction of proportional changes. The first color string is for a positive change, the second for a negative one.
arrow_start | Advanced: Set the x coordinate of the arrow annotations (in NPC)
extension_factors | Advanced: Specify the extension factors to extend the plotted genomic range. The first value if for the extension of the front (left) side, the second for the back (right).
savepath | If you want your files to be saved to disk, specify a save path here. The directories will be created if necessary.
filename_ext | Optionally specify a file name extension here, which also defines the save image format. The file name will be 'gene_name+extension'.
add_to_table | If a `savepath` is provided, add the filepaths of the created plots to the corresponding entries in `dtu_table`. The name of the column that shall be created can be specified here.
BPPARAM | If multicore processing should be used, specify a `BiocParallelParam` object here. Among others, can be `SerialParam()` (default) for non-multicore processing or `MulticoreParam('number_cores')` for multicore processing. See `BiocParallel` for more information.
... | Arguments passed down to `png` or `cairo_pdf` or `pdf` or `jpeg`, depending on `filename_ext` ending and capabilities (cairo_pdf or pdf).

## Value

Returns list of saved plots, for adding to the DTU table. If no `savepath` is provided, returns a list of the created plots for further processing.

## Details

Reduced intron length is computed by taking the square root, but is not less than the specified `reduce_introns_min_size` length. If less `GRanges` are found than expected, try setting `one_to_one` to `TRUE` or the used extension character. When calling this function many times, try importing the GTF-File with `gtf <- import_gtf("GTF_PATH", feature_type=NULL, out_df=FALSE)` once and pass it to the `gtf` parameter to improve performance.

## See also

`run_drimseq()` and `posthoc_and_stager()` for DTU object creation. `create_dtu_table()` and `plot_dtu_table()` for table visualization.

Other DTUrtle visualization: `create_dtu_table()`, `plot_dimensional_reduction()`, `plot_proportion_barplot()`, `plot_proportion_pheatmap()`