### Example usage of frame_psite

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/frames.R

This snippet demonstrates the initial setup for generating fake samples and replicates for the frame_psite analysis.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
```

--------------------------------

### Access example reads list

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Retrieves the example dataset for demonstration purposes.

```R
example_reads_list[["Samp_example"]]
```

--------------------------------

### bamtobed example usage

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/bamtobed.html

Example demonstrating how to specify input and output directories for the conversion process.

```R
## path_bam <- "path/to/BAM/files"
## path_bed <- "path/to/output/directory"
## bamtobed(bamfolder = path_bam, bedfolder = path_bed)
```

--------------------------------

### Install riboWaltz

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/vignettes/my-vignette.R

Use devtools to install the package from GitHub.

```R
install.packages("devtools")
```

```R
library(devtools)
install_github("LabTranslationalArchitectomics/riboWaltz", dependencies = TRUE)
```

```R
install_github("LabTranslationalArchitectomics/riboWaltz", dependencies = TRUE,
               build_vignettes = TRUE)
```

--------------------------------

### Install devtools

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Install the devtools package required for installing riboWaltz from GitHub.

```R
install.packages("devtools")
```

--------------------------------

### Initialize riboWaltz example dataset

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/vignettes/my-vignette.Rmd

Sets up a sample data.table list to demonstrate filtering functionality.

```R
library(data.table)
example_reads_list <- list()
example_reads_list[["Samp_example"]] <- data.table(row_ID = c(1, 2, 3, 4, 5, 6),
                                                   transcript = rep("ENSMUST00000000001.4", 6),
                                                   end5 = c(92, 92, 92, 94, 94, 95),
                                                   end3 = c(119, 119, 122, 122, 123, 123))
example_reads_list[["Samp_example"]][, length := end3 - end5 + 1
                                     ][, cds_start := 142
                                       ][, cds_stop := 1206]
```

```R
print(example_reads_list[["Samp_example"]], row.names=FALSE)
```

--------------------------------

### Example usage of bedtolist

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/bedtolist.html

Basic example showing how to call bedtolist with a path to BED files and an annotation object.

```R
## path_bed <- "path/to/BED/files"
## bedtolist(bedfolder = path_bed, annotation = mm81cdna)
```

--------------------------------

### Examples of cds_coverage usage

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/cds_coverage.html

Examples demonstrating how to compute P-site coverage for whole CDS, restricted CDS regions, and entire transcripts.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## compute and add p-site datails
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Compute the number of in-frame P-sites per whole coding sequences.
## psite_cds <- cds_coverage(reads_psite_list, mm81cdna)
## 
## ## Compute the number of in-frame P-sites per coding sequences exluding
## ## the first 15 nucleotides and the last 10 nucleotides.
## psite_cds <- cds_coverage(reads_psite_list, mm81cdna,
##                           start_nts = 15, stop_nts = 10)
## 
## ## Compute the number of P-sites per transcripts.
## psite_cds <- cds_coverage(reads_psite_list, mm81cdna,
##                           whole_transcript = TRUE)
```

--------------------------------

### Generate a metaheatmap with metaheatmap_psite

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/metaheatmap_psite.html

This example demonstrates how to prepare sample data and generate a metaheatmap using the metaheatmap_psite function.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
##                       "S2" = c("Samp3", "Samp4", "Samp5"),
##                       "S3" = c("Samp6"))
##
## Generate metaheatmap
## example_metaheatmap <- metaheatmap_psite(reads_psite_list, mm81cdna,
##                                          sample = input_samples,
##                                          multisamples = "average",
##                                          utr5l = 20, cdsl = 40, utr3l = 20,
##                                          colour = "#333f50"))
```

--------------------------------

### Generate Example Dataset

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Creates a set of 5 data tables by extracting random reads from the original reads_list example dataset.

```R
for(i in 2:6){
   samp_name <- paste0("Samp", i)
   set.seed(i)
   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
}
```

--------------------------------

### Filtering Examples

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/length_filter.html

Examples demonstrating custom length range filtering and periodicity-based filtering.

```R
data(reads_list)

## Keep reads of length between 27 and 30 nucleotides (included):
filtered_list <- length_filter(reads_list, length_filter_mode = "custom",
                               length_range = 27:30)

## Keep reads of lengths satisfying a periodicity threshold (70%):
filtered_list <- length_filter(reads_list, length_filter_mode = "periodicity",
                               periodicity_threshold = 70)
```

--------------------------------

### Install riboWaltz from GitHub

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz

Use the remotes package to install the latest version of riboWaltz directly from the GitHub repository.

```R
install.packages("remotes")
remotes::install_github("LabTranslationalArchitectomics/riboWaltz")
```

--------------------------------

### Install riboWaltz with vignettes

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Install riboWaltz while also building the package vignettes.

```R
install_github("LabTranslationalArchitectomics/riboWaltz", dependencies = TRUE, 
        build_vignettes = TRUE)
```

--------------------------------

### Example usage of create_annotation

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/create_annotation.html

Demonstrates how to call the function using a GTF file path, data source, and organism name.

```R
## gtf_file <- "path/to/GTF/file.GTF"
## create_annotation(gtfpath = gtf_file, dataSource = "gencode6", organism = "Mus musculus")
```

--------------------------------

### Generate metaprofiles with metaprofile_psite

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/metaprofile_psite.html

Example demonstrating the workflow from computing P-site offsets to generating a faceted metaprofile plot for grouped samples.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
##                       "S2" = c("Samp3", "Samp4", "Samp5"),
##                       "S3" = c("Samp6"))
##
## ## Generate metaprofiles
## example_metaprofile <- metaprofile_psite(reads_psite_list, mm81cdna,
##                                          sample = input_samples,
##                                          multisamples = "average",
##                                          plot_style = "facet",
##                                          utr5l = 20, cdsl = 40, utr3l = 20,
##                                          colour = c("#333f50", "#39827c", "gray70"))
```

--------------------------------

### Compute and visualize P-site distribution per transcript region

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/percentage_regions.R

Example usage of the region_psite function setup, including data preparation and sample definition.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
```

--------------------------------

### Define Input Samples

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/codon_usage.R

Example of defining a list of samples and replicates for input into the codon usage analysis.

```R
input_samples <- list("S1" = c("Samp1", "Samp2"),
                      "S2" = c("Samp3", "Samp4", "Samp5"),
                      "S3" = c("Samp6"))
```

--------------------------------

### Generate p-site region distribution plot

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/region_psite.html

This example demonstrates the workflow from preparing sample data to generating a stacked bar plot of p-site distributions.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
##                       "S2" = c("Samp3", "Samp4", "Samp5"),
##                       "S3" = c("Samp6"))
##
## Generate bar plot
## example_psite_per_region <- region_psite(reads_psite_list, mm81cdna,
##                                          sample = input_samples,
##                                          multisamples = "average",
##                                          plot_style = "stack",
##                                          cl = 85,
##                                          colour = c("#333f50", "gray70", "#39827c"))
```

--------------------------------

### Generate read extremity metaheatmaps

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/vignettes/my-vignette.Rmd

Creates metaheatmaps for 5' and 3' read extremities around start and stop codons.

```r
example_ends_heatmap <- rends_heat(reads_list, mm81cdna,
                                   sample = "Samp1",
                                   cl = 85, utr5l = 25, cdsl = 40, utr3l = 25)
example_ends_heatmap[["plot_Samp1"]]
```

```r
knitr::include_graphics("example_ends_heatmap.png")
```

--------------------------------

### Convert BAM files to BED format

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/combine_bam.R

Uses the BEDTools suite to convert BAM files to BED format. Requires a UNIX-based system and BEDTools installed.

```R
## path_bam <- "path/to/BAM/files"
## path_bed <- "path/to/output/directory"
## bamtobed(bamfolder = path_bam, bedfolder = path_bed)
```

```R
bamtobed <- function(bamfolder, bedfolder = NULL) {
  if (length(bedfolder) == 0) {
    bedfolder <- paste(bamfolder, "/bed", sep = "")
  }
  if (!dir.exists(bedfolder)) {
    dir.create(bedfolder)
  }
  bamtobed <- paste("bam_folder=\"", bamfolder, "\" && out_folder=\"", bedfolder, "\" && bam_files=$(find $bam_folder -type \"f\" -name \"*.bam\" | sort) && for name in $bam_files; do outname=$(echo $name | rev | cut -d'/' -f 1 | cut -d '.' -f 2- | rev); printf \"from \\t\\t $name \\t\\t to \\t\\t $out_folder/$outname.bed\\n\"; bedtools bamtobed -i $name | cut -f1,2,3,6 | awk -F'\\t' '{OFS = \"\\t\"; $5=$4; $2=$2+1; $4=$3-$2+1; print}' > $out_folder/$outname.bed; done",
                    sep = "")
  system(bamtobed)
}
```

--------------------------------

### psite(data, flanking = 6, start = TRUE, extremity = "auto", plot = FALSE, plot_dir = NULL, plot_format = "png", cl = 99, txt = FALSE, txt_file = NULL)

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/psite.html

Identifies the exact position of the ribosome P-site within each read and returns a data table with P-site information. Optionally generates occupancy metaprofiles.

```APIDOC
## psite

### Description
Identifies the exact position of the ribosome P-site within each read. It returns a data table containing sample information, read percentages, and P-site distances.

### Parameters
- **data** (list or GRangesList) - Required - Input data from bamtolist, bedtolist, duplicates_filter, or length_filter.
- **flanking** (integer) - Optional - Minimum number of nucleotides that must flank the reference codon. Default is 6.
- **start** (logical) - Optional - Whether to use the translation initiation site as the reference codon. Default is TRUE.
- **extremity** (string) - Optional - Correction step basis: "5end", "3end", or "auto". Default is "auto".
- **plot** (logical) - Optional - Whether to plot occupancy metaprofiles. Default is FALSE.
- **plot_dir** (string) - Optional - Directory to store metaprofiles. Default is "offset_plot".
- **plot_format** (string) - Optional - File format for plots: "png" or "pdf". Default is "png".
- **cl** (integer) - Optional - Confidence level (1-100) for generating metaprofiles. Default is 99.
- **txt** (logical) - Optional - Whether to write correction step info to a text file. Default is FALSE.
- **txt_file** (string) - Optional - Path and name for the text output file. Default is "best_offset.txt".

### Returns
- **data.table** - A data table containing P-site position information for all samples and read lengths.
```

--------------------------------

### Generate Codon Usage Plots with codon_usage_psite

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/codon_usage_psite.html

Examples demonstrating how to compute codon usage plots using P-site information, including bar plots for transcript/chromosome alignments and scatterplots for sample comparisons.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
##                       "S2" = c("Samp3", "Samp4", "Samp5"),
##                       "S3" = c("Samp6"))
##
## Generate bar plots, alignment on transcript sequences
## example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna,
##                                        sample = input_samples,
##                                        multisamples = "average",
##                                        plot_style = "facet",
##                                        fastapath = "path/to/transcriptome/FASTA/file",
##                                        fasta_genome = FALSE)
##
## Generate bar plots,  alignment on chromosome sequences
## example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna,
##                                        sample = input_samples,
##                                        multisamples = "average",
##                                        plot_style = "facet",
##                                        fastapath = "path/to/chromosome/FASTA/file",
##                                        fasta_genome = TRUE) 
##
## Generate scatterplot comparing two samples
## example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna,
##                                        sample = input_samples,
##                                        contrast_sample = c("S1", "S2"),
##                                        fastapath = "path/to/transcriptome/FASTA/file",
##                                        fasta_genome = FALSE,
##                                        frequency_normalization = FALSE)
```

--------------------------------

### metaprofile_psite(data, annotation, sample, multisamples, plot_style, scale_factors, transcripts, length_range, cl, utr5l)

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/metaplots.R

Generates metaprofiles displaying the abundance of P-sites around the start and stop codon of annotated CDSs.

```APIDOC
## metaprofile_psite

### Description
This function generates metaprofiles displaying the abundance of P-sites around the start and the stop codon of annotated CDSs. It supports multiple samples and replicates, allowing for various visualization styles.

### Parameters
- **data** (list or GRangesList) - Required - Either list of data tables or GRangesList object from psite_info.
- **annotation** (data table) - Required - Data table as generated by create_annotation.
- **sample** (character string/vector/list) - Required - Specifies the name of the sample(s) and replicate(s) of interest.
- **multisamples** (string) - Optional - Specifies how to handle multiple samples and replicates ('average' or 'independent'). Default is 'average'.
- **plot_style** (string) - Optional - Specifies how to organize and display multiple metaprofiles ('split', 'facet', 'overlap', or 'mirror'). Default is 'split'.
- **scale_factors** (string/numeric vector) - Optional - Specifies how metaprofiles should be scaled ('auto', named numeric vector, or 'none'). Default is 'auto'.
- **transcripts** (character vector) - Optional - List of transcript names to include. Default is NULL.
- **length_range** (integer/vector) - Optional - Restricts the plot to a chosen range of read lengths. Default is NULL.
- **cl** (integer) - Optional - Confidence level [1,100] for restricting the plot to an automatically-defined range of read lengths. Default is 100.
- **utr5l** (integer) - Optional - Positive integer specifying the length (in nucleotides) of the 5' UTR.
```

--------------------------------

### Prepare sample list

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/vignettes/my-vignette.R

Populates a list of read data for multiple samples.

```R
for(i in 2:6){
    samp_name <- paste0("Samp", i)
	set.seed(i)
	reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
}
```

--------------------------------

### Importing BAM files with bamtolist

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/bamtolist.html

Demonstrates how to define sample names and import multiple BAM files into a list of data tables.

```R
## ## Let's suppose there are two BAM files ("Samp1.bam" and "Samp2.bam") in
## ## "path/to/BAM/files". We want to acquire them and assign to the 
## ## corresponding data tables the names "Control" and "Treated",
## ## respectively.
## ## We first define the "name_samples" character string vector as follow:
## name_of_bams <- c("Control", "Treated")
## names(name_of_bams) <- c("Samp1", "Samp2")
##
## ## Then, we can acquire the two files: 
## path_bam <- "path/to/BAM/files"
## reads_list <- bamtolist(bamfolder = path_bam, name_samples = name_of_bams,
##                           annotation = annotation_dt)
##
## ## read_list will be a list of two data tables, named "Control" (with
## ## mapping reads from "Samp1.bam") and "Treated" (with mapping reads
## ## from"Samp2.bam")
```

--------------------------------

### Access Help Documentation

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/vignettes/my-vignette.R

Access help for specific functions or the entire package.

```R
?function_name
```

```R
help(package = riboWaltz)
```

--------------------------------

### Configure Column Names for Start or Stop Sites

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/psites.R

Renames columns and sets plot labels based on whether the analysis is for start or stop codons.

```R
if(start == TRUE | start == T){
      setnames(offset_temp, c("length", "total_percentage", "start_percentage", "around_start", "offset_from_5", "offset_from_3", "corrected_offset_from_5", "corrected_offset_from_3", "sample"))
      xlab_plot<-"Distance from start (nt)"
    } else {
      setnames(offset_temp, c("length", "total_percentage", "stop_percentage", "around_stop", "offset_from_5", "offset_from_3", "corrected_offset_from_5", "corrected_offset_from_3", "sample"))
      xlab_plot<-"Distance from stop (nt)"
    }
```

--------------------------------

### bamtolist(bamfolder, name_samples, annotation, ...)

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/bamtolist.html

Imports BAM files and converts them into a list of data tables or a GRangesList object for downstream riboWaltz analysis.

```APIDOC
## bamtolist

### Description
Imports BAM files from a specified folder and processes them into a list of data tables or a GRangesList object. This function is essential for preparing RiboSeq alignment data for P-site offset calculation and other riboWaltz analyses.

### Parameters
- **bamfolder** (character) - Required - Path to the directory containing the BAM files.
- **name_samples** (character vector) - Required - A named vector where values are the desired sample names and names are the corresponding BAM filenames (without extension).
- **annotation** (data.table) - Required - The annotation data table used to match reference sequences.
- **indel_threshold** (numeric) - Optional - Threshold for filtering reads based on small differences between RNA fragment width and reference sequence length.
- **refseq_sep** (character) - Optional - Separator used to parse and modify reference sequence identifiers.

### Return Value
A list of data tables or a GRangesList object containing the processed read information.

### Example
```r
name_of_bams <- c("Control", "Treated")
names(name_of_bams) <- c("Samp1", "Samp2")
path_bam <- "path/to/BAM/files"
reads_list <- bamtolist(bamfolder = path_bam, name_samples = name_of_bams, annotation = annotation_dt)
```
```

--------------------------------

### Generate Read Length Distribution Plots

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/read_length_plot.R

Initializes sample data for read length distribution analysis.

```R
data(reads_list)

## Generate fake samples and replicates
for(i in 2:6){
  samp_name <- paste0("Samp", i)
  set.seed(i)
```

--------------------------------

### Compute P-site offsets and information

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/codon_usage.R

Demonstrates how to generate sample replicates and compute P-site offsets and information for RiboSeq data.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## Generate fake samples and replicates
## for(i in 2:6){
##   samp_name <- paste0("Samp", i)
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
```

--------------------------------

### Generate P-site frame bar plots

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/frames.R

Example usage of frame_psite to generate bar plots from processed ribosome profiling data.

```R
##   set.seed(i)
##   reads_list[[samp_name]] <- reads_list[["Samp1"]][sample(.N, 5000)]
## }
##
## ## Compute and add p-site details
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## ## Define the list of samples and replicate to use as input
## input_samples <- list("S1" = c("Samp1", "Samp2"),
##                       "S2" = c("Samp3", "Samp4", "Samp5"),
##                       "S3" = c("Samp6"))
##
## Generate bar plots
## example_frames <- frame_psite(reads_psite_list, mm81cdna,
##                               sample = input_samples,
##                               multisamples = "average",
##                               plot_style = "facet",
##                               region = "all",
##                               colour = c("#333f50", "#39827c", "gray70"))
```

--------------------------------

### Compute codon coverage in R

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/codon_coverage.html

Example usage of codon_coverage to calculate coverage based on ribosome footprints or P-sites using pre-processed data.

```R
## data(reads_list)
## data(mm81cdna)
##
## ## compute and add p-site datails
## psite_offset <- psite(reads_list, flanking = 6, extremity = "auto")
## reads_psite_list <- psite_info(reads_list, psite_offset)
##
## Compute the codon coverage based on the number of ribosome footprint per
## codon, setting the minimum overlap between reads and triplets to 3 nts:
## coverage_dt <- codon_coverage(reads_psite_list, mm81cdna, min_overlap = 3)
## 
## Compute the coverage based on the number of P-sites per codon:
## coverage_dt <- codon_coverage(reads_psite_list, mm81cdna, psite = TRUE)
```

--------------------------------

### Define input samples list

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Create a list of sample groupings for comparative analysis.

```R
input_samples <- list("S1" = c("Samp1", "Samp2"),
              "S2" = c("Samp3", "Samp4", "Samp5"))
```

--------------------------------

### Generate Codon Usage Bar Plots

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/codon_usage.R

Examples of generating bar plots for codon usage, demonstrating alignment on transcript versus chromosome sequences.

```R
example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna,
                                       sample = input_samples,
                                       multisamples = "average",
                                       plot_style = "facet",
                                       fastapath = "path/to/transcriptome/FASTA/file",
                                       fasta_genome = FALSE)
```

```R
example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna,
                                       sample = input_samples,
                                       multisamples = "average",
                                       plot_style = "facet",
                                       fastapath = "path/to/chromosome/FASTA/file",
                                       fasta_genome = TRUE)
```

--------------------------------

### Generate P-site metaprofiles

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/vignettes/my-vignette.R

Creates metaprofiles for specific samples based on UTR and CDS lengths.

```R
input_samples <- list("S1" = c("Samp1", "Samp2")))

example_metaprofile <- metaprofile_psite(reads_psite_list, mm81cdna,
                                         sample = input_samples,
                                         multisamples = "average",
                                         utr5l = 20, cdsl = 40, utr3l = 20,
                                         colour = "#333f50")
example_metaprofile[["plot_S1"]]
```

--------------------------------

### Analyze Codon Usage with codon_usage_psite

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/vignettes/my-vignette.Rmd

Examples of generating codon usage bar plots for single or multiple samples, with options for frequency normalization and stop codon inclusion.

```r
input_samples <- list("S1" = c("Samp1", "Samp2"))
example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna, sample = input_samples, multisamples = "average", plot_style = "facet", fastapath = "path/to/transcriptome/FASTA/file", fasta_genome = FALSE, frequency_normalization = FALSE) example_cu_barplot[["plot_S1"]]
```

```r
input_samples <- list("S1" = c("Samp1", "Samp2"), "S2" = c("Samp3", "Samp4", "Samp5"))
example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna, sample = input_samples, multisamples = "average", plot_style = "facet", fastapath = "path/to/transcriptome/FASTA/file", fasta_genome = FALSE, frequency_normalization = FALSE) example_cu_barplot[["plot"]]
```

```r
input_samples <- list("S1" = c("Samp1", "Samp2"))
example_cu_barplot <- codon_usage_psite(reads_psite_list, mm81cdna, sample = input_samples, multisamples = "average", plot_style = "facet", fastapath = "path/to/transcriptome/FASTA/file", fasta_genome = FALSE, frequency_normalization = TRUE, include_stop_codons = FALSE) example_cu_barplot[["plot_S1"]]
```

--------------------------------

### Define Input Samples

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Creates a vector of sample names for comparison.

```R
input_samples <- c("Samp1", "Samp2")
```

--------------------------------

### Compute and Normalize Codon Usage

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/codon_usage.R

This script processes ribosome profiling data to calculate codon counts, normalize them, and categorize codons into CDS, start, or stop classes.

```R
cod_aa <- data.table(codon=c("GCC", "GCG", "GCU", "GCA", "AGA", "CGG", "AGG", "CGA", "CGC", "CGU", "AAC", "AAU", "GAC", "GAU", "UGC", "UGU", "CAA", "CAG", "GAG", "GAA", "GGC", "GGU", "GGA", "GGG", "CAC", "CAU", "AUA", "AUC", "AUU", "CUG", "CUA", "UUA", "CUU", "UUG", "CUC", "AAA", "AAG", "AUG", "UUC", "UUU", "CCG", "CCC", "CCU", "CCA", "AGC", "UCG", "UCU", "UCA", "UCC", "AGU", "UAG", "UAA", "UGA", "ACA", "ACC", "ACG", "ACU", "UGG", "UAU", "UAC", "GUA", "GUG", "GUU", "GUC"),
                       aa=c("A", "A", "A", "A", "R", "R", "R", "R", "R", "R", "N", "N", "D", "D", "C", "C", "Q", "Q", "E", "E", "G", "G", "G", "G", "H", "H", "I", "I", "I", "L", "L", "L", "L", "L", "L", "K", "K", "M", "F", "F", "P", "P", "P", "P", "S", "S", "S", "S", "S", "S", "*", "*", "*", "T", "T", "T", "T", "W", "Y", "Y", "V", "V", "V", "V"))
  cod_lev <- gsub("U", "T", cod_aa$codon)
  
  # compute triplet coverage
  final_dt <- data.table()
  for(samp in as.character(unlist(sample))) {
    dt <- data[[samp]][as.character(transcript) %in% c_transcripts & psite_from_start %% 3 == 0]
    
    if(site == "psite"){
      dt <- dt[psite_region == "cds"]
      temp_table <- data.table(table(factor(dt$p_site_codon, levels = cod_lev)))
    } else {
      if(site == "asite"){
        dt <- dt[psite_from_start >= -3 & psite_from_stop <= -3]
        temp_table <- data.table(table(factor(dt$a_site_codon, levels = cod_lev)))
      } else {
        dt <- dt[psite_from_start >= 3 & psite_from_stop <= 3]
        temp_table <- data.table(table(factor(dt$e_site_codon, levels = cod_lev)))
      }
    }
    colnames(temp_table) <- c("codon", "count")
    
    temp_table[, codon := gsub("T", "U", codon)]
    
    if(frequency_normalization == TRUE | frequency_normalization == T){
      temp_table[, norm_count := count / seq_freq[codon]]
    } else {
      temp_table[, norm_count := count]
    }
    
    temp_table[, scaled_count := norm_count - min(norm_count)
    ][, scaled_count := scaled_count / max(scaled_count)
    ][, tmp_samp := samp]
    
    final_dt <- rbind(final_dt, temp_table)
  }
  
  output <- list()
  output[["count_dt"]] <- copy(final_dt[, c("tmp_samp", "codon", "count", "norm_count", "scaled_count")])
  if(!(frequency_normalization == TRUE | frequency_normalization == T)){
    output[["count_dt"]][, norm_count := NULL]
  }
  setnames(output[["count_dt"]], "tmp_samp", "sample")
  
  if(length(contrast_sample) == 1){
    codon_values <- codon_values[, list(codon, value)]
    codon_values[, scaled_user_count := value - min(value)
    ][, scaled_user_count := scaled_user_count / max(scaled_user_count)
    ][, codon := gsub("T", "U", codon)]
  }
  
  #add codon classes
  final_dt <- final_dt[, class := "cds"
  ][codon == "AUG", class := "start"
  ][codon %in% c("UAA", "UGA", "UAG"), class := "stop"]
  
  # compute mean samples if a list is provided
  if(is.list(sample)){
    
    samp_dt <- data.table(stack(sample))
    setnames(samp_dt, c("tmp_samp", "sample"))
    
    # set names of samples as specified in parameter sample
    final_dt <- merge.data.table(final_dt, samp_dt, sort = FALSE)[, tmp_samp := NULL]
    
    # compute mean and se
    plot_dt <- final_dt[, .(mean_scaled_count = mean(scaled_count),
                            se_scaled_count = sd(scaled_count/sqrt(.N))), by = .(codon, class, sample)]
    
    if(is.null(contrast_sample)){
      if(any(lengths(sample) != 1)){
        output[["plot_dt"]] <- copy(plot_dt[, c("sample", "codon", "class", "mean_scaled_count", "se_scaled_count")])
        setnames(output[["plot_dt"]], c("codon", "mean_scaled_count", "se_scaled_count"), c("x", "y", "y_se"))
      } else {
        output[["plot_dt"]] <- copy(final_dt[, c("sample", "codon", "class", "scaled_count")])
        setnames(output[["plot_dt"]], c("codon", "scaled_count"), c("x", "y"))
      }
    }
  } else {
    plot_dt <- final_dt[, sample := tmp_samp
    ][, se_scaled_count := NA]
    setnames(plot_dt, "scaled_count", "mean_scaled_count")
    
    if(is.null(contrast_sample)){
      output[["plot_dt"]] <- copy(plot_dt[, c("sample", "codon", "class", "mean_scaled_count")])
      setnames(output[["plot_dt"]], c("codon", "mean_scaled_count"), c("x", "y"))
    } 
  }
  
  plot_dt[, sample := factor(sample, levels = unique(sample))]
  
  #define plot dt and output dt when a scatter plot is generated
  if(!is.null(contrast_sample)) {
    if(length(contrast_sample) == 1){
      plot_scatter_dt <- merge.data.table(plot_dt, codon_values, by = "codon")
    } else {
      plot_scatter_dt <- plot_dt[sample == contrast_sample[1]]
      plot_scatter_dt[, scaled_user_count := plot_dt[sample == contrast_sample[2], mean_scaled_count]]
    }
    
    plot_dt <- plot_scatter_dt
    output[["plot_dt"]] <- copy(plot_dt[, c("codon", "class", "mean_scaled_count", "scaled_user_count")]
    )[order(codon, class)]
    setnames(output[["plot_dt"]], c("mean_scaled_count", "scaled_user_count"), c("x", "y"))
  }
```

--------------------------------

### Import Data

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/vignettes/my-vignette.R

Convert BAM or BED files into a list of data tables.

```R
reads_list <- bamtolist(bamfolder = "path/to/BAM/files", annotation = annotation_dt)
```

```R
bamtobed(bamfolder = "path/to/BAM/files", bedfolder = "path/to/output/directory")
```

```R
reads_list <- bedtolist(bedfolder = "path/to/BED/files", annotation = annotation_dt)
```

--------------------------------

### Visualize P-site Profiles

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/vignettes/my-vignette.Rmd

Include graphics showing P-site profiles for specific read lengths.

```R
knitr::include_graphics("meta_psite_length28.png")
knitr::include_graphics("meta_psite_length31.png")
```

--------------------------------

### rends_heat(data, annotation, sample, ...)

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/rends_heat.html

Generates metaheatmaps displaying the abundance of the 5' and 3' extremity of reads mapping around the start and the stop codon of annotated CDSs.

```APIDOC
## rends_heat

### Description
Generates four metaheatmaps displaying the abundance of the 5' and 3' extremity of reads mapping around the start and the stop codon of annotated CDSs, stratified by their length. Supports multiple samples and replicates.

### Usage
rends_heat(data, annotation, sample, multisamples = "average", plot_style = "split", scale_factors = "auto", transcripts = NULL, length_range = NULL, cl = 100, utr5l = 50, cdsl = 50, utr3l = 50, log_colour = F, colour = "black")

### Parameters
- **data** - The input data object.
- **annotation** - The annotation object.
- **sample** - The sample identifier.
- **multisamples** - Handling of multiple samples (default: "average").
- **plot_style** - Style of the plot (default: "split").
- **scale_factors** - Scaling factors (default: "auto").
- **transcripts** - Optional list of transcripts (default: NULL).
- **length_range** - Optional range of read lengths (default: NULL).
- **cl** - CDS length parameter (default: 100).
- **utr5l** - 5' UTR length parameter (default: 50).
- **cdsl** - CDS length parameter (default: 50).
- **utr3l** - 3' UTR length parameter (default: 50).
- **log_colour** - Whether to use log scale for colours (default: F).
- **colour** - Colour scheme (default: "black").
```

--------------------------------

### Inspect P-site Offsets

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/vignettes/my-vignette.Rmd

View the first 10 rows of the computed P-site offsets table.

```R
head(psite_offset, 10)
```

--------------------------------

### bamtolist(bamfolder, annotation, transcript_align = TRUE, name_samples = NULL, indel_threshold = 5, refseq_sep = NULL, output_class = "datatable")

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/combine_bam.R

Imports BAM files from a specified folder and converts them into a list of data tables. It handles read alignment processing, filters based on indel thresholds, and allows for the modification of reference sequence identifiers.

```APIDOC
## bamtolist

### Description
Imports BAM files from a specified directory and converts them into a list of data tables for further analysis in riboWaltz. It processes read alignments and allows for customization of sample names and reference sequence identifiers.

### Parameters
- **bamfolder** (character) - Required - Path to the folder containing the BAM files.
- **annotation** (data.table) - Required - Annotation table to be used for processing.
- **transcript_align** (logical) - Optional - Whether the reads are aligned to transcript coordinates. Defaults to TRUE.
- **name_samples** (character vector) - Optional - A named character vector to assign custom names to the samples. The names of the vector should match the BAM filenames (without .bam extension).
- **indel_threshold** (numeric) - Optional - Threshold for discarding reads with stretches of deletions. Defaults to 5.
- **refseq_sep** (character) - Optional - Character used to modify or lighten the identifiers of reference sequences.
- **output_class** (character) - Optional - The class of the output objects. Defaults to "datatable".
```

--------------------------------

### Visualize read extremity localization with rends_heat

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Generates metaheatmaps for 5' and 3' read extremities around start and stop codons. Use the cl parameter to restrict the range of read lengths.

```R
example_ends_heatmap <- rends_heat(reads_list, mm81cdna,
                                   sample = "Samp1", cl = 85,
                                   utr5l = 25, cdsl = 40, utr3l = 25,
                                   colour = "#333f50")
example_ends_heatmap[["plot_Samp1"]]
```

--------------------------------

### bamtobed usage syntax

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/bamtobed.html

Standard function signature for converting BAM files to BED files.

```R
bamtobed(bamfolder, bedfolder = NULL)
```

--------------------------------

### rends_heat(data, annotation, sample, multisamples, plot_style, scale_factors, transcripts, length_range, cl, utr5l, cdsl, utr3l, log_colour, colour)

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/man/rends_heat.html

Generates heatmaps representing the signal of read extremities around start and stop codons for specified samples.

```APIDOC
## rends_heat

### Description
Generates heatmaps of read extremities mapping around the start and stop codons. It supports multiple samples, replicates, and various scaling and visualization options.

### Parameters
- **data** (list/GRangesList) - Required - Data tables or GRangesList object from bamtolist, bedtolist, length_filter or psite_info.
- **annotation** (data.table) - Required - Data table generated by create_annotation.
- **sample** (character/list) - Required - Name of the sample(s) and replicate(s) of interest.
- **multisamples** (string) - Optional - How to handle multiple samples: "average" or "independent". Default is "average".
- **plot_style** (string) - Optional - Organization of heatmaps: "split" or "facet". Default is "split".
- **scale_factors** (string/numeric) - Optional - Scaling method: "auto", "none", or named numeric vector. Default is "auto".
- **transcripts** (character vector) - Optional - Transcripts to include. Default is NULL.
- **length_range** (integer vector) - Optional - Range of read lengths to include. Default is NULL.
- **cl** (integer) - Optional - Confidence level (1-100) for read length range. Default is 100.
- **utr5l** (integer) - Optional - Length of 5' UTR region. Default is 50.
- **cdsl** (integer) - Optional - Length of CDS regions. Default is 50.
- **utr3l** (integer) - Optional - Length of 3' UTR region. Default is 50.
- **log_colour** (logical) - Optional - Use logarithmic colour scale. Default is FALSE.
- **colour** (string) - Optional - Colour of the plot. Default is "black".

### Value
Returns a list containing:
- **plot_dt**: ggplot object(s) and data table with x/y axis values.
- **count_dt**: Data table with raw and scaled read extremity counts.
```

--------------------------------

### Log and Export Offset Information

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/src/R/psites.R

Logs the best offset to the console and optionally appends it to a text file.

```R
cat(sprintf("best offset: %i nts from the %s\n", abs(best_offset), gsub("end", "' end", line_plot)))
    
    if(txt == T | txt == TRUE){
      cat(sprintf("%s\t%s\t%i\n", n, gsub("end", "'end", line_plot), abs(best_offset)), file = txt_file, append = TRUE)
    }
```

--------------------------------

### Generate P-site Metaheatmap

Source: https://rdrr.io/github/LabTranslationalArchitectomics/riboWaltz/f/README.md

Visualizes P-site abundance along CDS using a continuous color scale, suitable for multiple samples.

```R
input_samples <- list("S1" = c("Samp1", "Samp2"),
                      "S2" = c("Samp3", "Samp4", "Samp5"),
                      "S3" = c("Samp6"))

example_metaheatmap <- metaheatmap_psite(reads_psite_list, mm81cdna,
                                         sample = input_samples,
                                         multisamples = "average",
                                         utr5l = 20, cdsl = 40, utr3l = 20,
                                         colour = "#333f50")
example_metaheatmap[["plot"]]
```