## Latest release version
install.packages("ggDNAvis")

## Current development build (may have unexpected bugs!)
devtools::install_github("ejade42/ggDNAvis")

## Specific version from github
devtools::install_github("ejade42/ggDNAvis", ref = "v0.3.0")

## Load this package
library(ggDNAvis)

## Load useful tidyverse packages
## These are ggDNAvis dependencies, so will always be installed when installing ggDNAvis
library(dplyr)
library(ggplot2)

## Function for viewing tables throughout this document
github_table <- function(data) {
    quoted <- as.data.frame(
        lapply(data, function(x) {paste0("`", x, "`")}),
        check.names = FALSE
    )
    kable_output <- knitr::kable(quoted)
    return(kable_output)
}

## Set up file locations
output_location <- "README_files/output/"
github_location <- "https://raw.githubusercontent.com/ejade42/ggDNAvis/main/README_files/output/"
knitr::opts_chunk$set(fig.path = output_location)

## Print current ggDNAvis version
cat("Loaded ggDNAvis version is:", as.character(packageVersion("ggDNAvis")))

## Create input sequence. This can be any DNA/RNA string
sequence <- paste(c(rep("GGC", 72), rep("GGAGGAGGCGGC", 15)), collapse = "")

## Create visualisation
## This lists out all arguments
## Usually it's fine to leave most of these as defaults
visualise_single_sequence(
    sequence = sequence,
    sequence_colours = sequence_colour_palettes$bright_pale,
    background_colour = "white",
    line_wrapping = 60,
    spacing = 1,
    margin = 0.5,
    sequence_text_colour = "black",
    sequence_text_size = 16,
    index_annotation_colour = "darkred",
    index_annotation_size = 12.5,
    index_annotation_interval = 15,
    index_annotations_above = TRUE,
    index_annotation_vertical_position = 1/3,
    outline_colour = "black",
    outline_linewidth = 3,
    outline_join = "mitre",
    return = FALSE,
    filename = paste0(output_location, "summary_single_sequence.png"),
    render_device = ragg::agg_png,
    pixels_per_base = 100
)

## View image
knitr::include_graphics(paste0(github_location, "summary_single_sequence.png"))

## Read and merge data
fastq_data <- read_fastq("inst/extdata/example_many_sequences_raw.fastq", calculate_length = TRUE)
metadata   <- read.csv("inst/extdata/example_many_sequences_metadata.csv")
merged_fastq_data <- merge_fastq_with_metadata(fastq_data, metadata)

## Extract character vector
## These arguments should all be considered, as they are highly specific to your data
sequences_for_visualisation <- extract_and_sort_sequences(
    sequence_dataframe = merged_fastq_data,
    sequence_variable = "forward_sequence",
    grouping_levels = c("family" = 8, "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = TRUE
)

## Create visualisation
## Usually it's fine to leave most of these as defaults
visualise_many_sequences(
    sequences_vector = sequences_for_visualisation,
    sequence_colours = sequence_colour_palettes$bright_deep,
    background_colour = "white",
    margin = 0.5,
    sequence_text_colour = "white",
    sequence_text_size = 16,
    outline_colour = "black",
    outline_linewidth = 3,
    outline_join = "mitre",
    return = FALSE,
    filename = paste0(output_location, "summary_many_sequences.png"),
    render_device = ragg::agg_png,
    pixels_per_base = 100
)

## View image
knitr::include_graphics(paste0(github_location, "summary_many_sequences.png"))

## Read and merge data
modification_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")
metadata          <- read.csv("inst/extdata/example_many_sequences_metadata.csv")
merged_modification_data <- merge_methylation_with_metadata(modification_data, metadata,
                                                            reversed_location_offset = 1)

## Extract list of character vectors
## These arguments should all be considered, as they are highly specific to your data
methylation_for_visualisation <- extract_methylation_from_dataframe(
    modification_data = merged_modification_data,
    locations_colname = "forward_C+m?_locations",
    probabilities_colname = "forward_C+m?_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 8, "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = TRUE
)

## Create visualisation
## Usually it's fine to leave most of these as defaults
visualise_methylation(
    modification_locations     = methylation_for_visualisation$locations,
    modification_probabilities = methylation_for_visualisation$probabilities,
    sequence_lengths           = methylation_for_visualisation$lengths,
    background_colour = "white",
    other_bases_colour = "grey",
    low_colour = "blue",
    high_colour = "red",
    low_clamp = 0.1*255,
    high_clamp = 0.9*255,
    outline_colour = "black",
    outline_linewidth = 3,
    outline_join = "mitre",
    modified_bases_outline_colour = NA,
    modified_bases_outline_linewidth = NA,
    modified_bases_outline_join = NA,
    other_bases_outline_colour = NA,
    other_bases_outline_linewidth = NA,
    other_bases_outline_join = NA,
    margin = 0.5,
    return = FALSE,
    filename = paste0(output_location, "summary_methylation.png"),
    render_device = ragg::agg_png,
    pixels_per_base = 20
)

## View image
knitr::include_graphics(paste0(github_location, "summary_methylation.png"))

## Create scalebar and save to ggplot object
## Usually it's fine to leave most of these as defaults
scalebar <- visualise_methylation_colour_scale(
    low_colour = "blue",
    high_colour = "red",
    low_clamp = 0.1*255,
    high_clamp = 0.9*255,
    full_range = c(0, 255),
    precision = 10^3,
    background_colour = "white",
    x_axis_title = "Methylation probability",
    do_x_ticks = TRUE,
    do_side_scale = FALSE,
    side_scale_title = NULL,
    outline_colour = "black",
    outline_linewidth = 1
)

## Write png from object (the object is just a standard ggplot)
ggsave(paste0(output_location, "summary_methylation_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "summary_methylation_scalebar.png"))

## View the first 4 rows of example_many_sequences data
github_table(head(example_many_sequences, 4))

## Function to convert integer scores to corresponding percentages
convert_8bit_to_decimal_prob <- function(x) {
    return(c(  x   / 256, 
             (x+1) / 256))
}

## Convert comma-condensed string back to numerical vector
## string_to_vector() and vector_to_string() are crucial ggDNAvis helpers
probabilities <- string_to_vector("250,3,50,127")

## For each probability, print 8-bit score then percentage range
for (probability in probabilities) {
    percentages <- round(convert_8bit_to_decimal_prob(probability), 4) * 100
    cat("8-bit probability: ", probability, "\n", sep = "")
    cat("Decimal probability: ", percentages[1], "% - ", percentages[2], "%", "\n\n", sep = "")
}

vector_to_string(c(1, 2, 3, 4))

string_to_vector("1,2,3,4") # the default vector type is numeric

vector_to_string(c("these", "are", "some", "words"))

string_to_vector("these,are,some,words", type = "character")

vector_to_string(c(TRUE, FALSE, TRUE))

string_to_vector("TRUE,FALSE,TRUE", type = "logical")

string_to_vector(c("1,2,3", "4,5,6"))

lapply(c("1,2,3", "4,5,6"), string_to_vector)

## Look at first 16 lines of FASTQ
fastq_raw <- readLines("inst/extdata/example_many_sequences_raw.fastq")
for (i in 1:16) {
    cat(fastq_raw[i], "\n")
}

## Load data from FASTQ
fastq_data <- read_fastq("inst/extdata/example_many_sequences_raw.fastq", calculate_length = TRUE)

## View first 4 rows
github_table(head(fastq_data, 4))

## Load metadata from CSV
metadata <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## View first 4 rows
github_table(head(metadata, 4))

## Use files from last step to construct vectors of forward and reverse IDs
forward_reads <- readLines("forward_reads.txt")
reverse_reads <- readLines("reverse_reads.txt")

## Use rep() to add a direction column
constructed_metadata <- data.frame(
    read = c(forward_reads, reverse_reads),
    direction = c(rep("forward", length(forward_reads)),
                  rep("reverse", length(reverse_reads)))
)

## Merge fastq data with metadata
## This function reverse-complements reverse reads to get all forward versions
merged_fastq_data <- merge_fastq_with_metadata(fastq_data, metadata)

## View first 4 rows
github_table(head(merged_fastq_data, 4))

## Subset to only the columns present in example_many_sequences
merged_fastq_data <- merged_fastq_data[, c("family", "individual", "read", "forward_sequence", "sequence_length", "forward_quality")]

## Rename "forward_sequence" to "sequence" and same for quality
colnames(merged_fastq_data)[c(4,6)] <- c("sequence", "quality")

## View first 4 rows of data produced from files
github_table(head(merged_fastq_data, 4))

## View first 4 rows of example_many_sequences (with modification columns excluded)
github_table(head(example_many_sequences[, 1:6], 4))

## Check if equal
identical(merged_fastq_data, example_many_sequences[, 1:6])

## Use write_fastq with filename = NA and return = TRUE to create the FASTQ, 
## but return it as a character vector rather than writing to file.
output_fastq <- write_fastq(merged_fastq_data, 
                            filename = NA, return = TRUE,
                            read_id_colname = "read", 
                            sequence_colname = "sequence",
                            quality_colname = "quality")
## View first 16 lines
for (i in 1:16) {
    cat(output_fastq[i], "\n")
}

## Look at first 16 lines of FASTQ
modified_fastq_raw <- readLines("inst/extdata/example_many_sequences_raw_modified.fastq")
for (i in 1:16) {
    cat(modified_fastq_raw[i], "\n")
}

## Load data from FASTQ
methylation_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")

## View first 4 rows
github_table(head(methylation_data, 4))

## Load metadata from CSV
metadata <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## View first 4 rows
github_table(head(metadata, 4))

## Merge fastq data with metadata
## This function reverse-complements reverse reads to get all forward versions
## And correctly flips location and probability information
## See ?merged_methylation_data and ?reverse_locations_if_needed for details
merged_methylation_data <- merge_methylation_with_metadata(methylation_data, metadata)

## View first 4 rows
github_table(head(merged_methylation_data, 4))

## Merge fastq data with metadata, offsetting reversed locations by 1
merged_methylation_data <- merge_methylation_with_metadata(methylation_data, 
                                                           metadata, 
                                                           reversed_location_offset = 1)

## View first 4 rows
github_table(head(merged_methylation_data, 4))

## Subset to only the columns present in example_many_sequences
merged_methylation_data <- merged_methylation_data[, c("family", "individual", "read", "forward_sequence", "sequence_length", "forward_quality", "forward_C+m?_locations", "forward_C+m?_probabilities", "forward_C+h?_locations", "forward_C+h?_probabilities")]

## Rename "forward_sequence" to "sequence" and same for quality
colnames(merged_methylation_data)[c(4,6:10)] <- c("sequence", "quality", "methylation_locations", "methylation_probabilities", "hydroxymethylation_locations", "hydroxymethylation_probabilities")

## View first 4 rows of data produced from files
github_table(head(merged_methylation_data, 4))

## View first 4 rows of example_many_sequences
github_table(head(example_many_sequences, 4))

## Check if equal
identical(merged_methylation_data, example_many_sequences)

## Use write_modified_fastq with filename = NA and return = TRUE to create 
## the FASTQ, but return it as a character vector rather than writing to file.
output_fastq <- write_modified_fastq(merged_methylation_data, 
                                     filename = NA, return = TRUE,
                                     read_id_colname = "read", 
                                     sequence_colname = "sequence",
                                     quality_colname = "quality",
                                     locations_colnames = c("hydroxymethylation_locations",
                                                            "methylation_locations"),
                                     probabilities_colnames = c("hydroxymethylation_probabilities",
                                                                "methylation_probabilities"),
                                     modification_prefixes = c("C+h?", "C+m?"))
## View first 16 lines
for (i in 1:16) {
    cat(output_fastq[i], "\n")
}

## Define sequence variable
sone_2019_f1_1_expanded_ggt_added <- "GGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGTGGTGGTGGTGGTGGTGGTGGTGGTGGTGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGCGGAGGAGGAGGCGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGAGGAGGAGGCGGCGGCGGCGGCGGCGGC"

## Use all default settings
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added)

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added, 
                          filename = paste0(output_location, "single_sequence_01.png"), 
                          return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_01.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added, 
                          filename = paste0(output_location, "single_sequence_02.png"), 
                          return = FALSE,
                          pixels_per_base = 20)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_02.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_03.png"), 
                          return = FALSE,
                          sequence_colours = c("black", "white", "#00FFFF", "#00FF00"),
                          sequence_text_colour = "magenta",
                          index_annotation_colour = "yellow",
                          background_colour = "red",
                          outline_colour = "orange")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_03.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_04.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale,
                          sequence_text_colour = "white")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_04.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_05.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale,
                          sequence_text_colour = "black")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_05.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_06.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale2,
                          sequence_text_colour = "black")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_06.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_07.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_deep,
                          sequence_text_colour = "white")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_07.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_08.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$sanger,
                          sequence_text_colour = "white",
                          outline_colour = "darkgrey")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_08.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_09.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$ggplot_style,
                          margin = 2,
                          spacing = 2,
                          line_wrapping = 60,
                          index_annotation_interval = 20,
                          index_annotations_above = FALSE,
                          index_annotation_vertical_position = 1/2,
                          outline_linewidth = 0)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_09.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_10.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale,
                          margin = 0,
                          spacing = 0,
                          line_wrapping = 45,
                          sequence_text_size = 0,
                          index_annotation_interval = 0,
                          pixels_per_base = 20,
                          outline_linewidth = 5)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_10.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_11.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale,
                          margin = 0.3,
                          spacing = 0,
                          line_wrapping = 45,
                          sequence_text_size = 0,
                          index_annotation_interval = 0,
                          pixels_per_base = 20,
                          outline_linewidth = 3)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_11.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_12.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_pale,
                          margin = 0,
                          spacing = 0,
                          line_wrapping = 45,
                          sequence_text_size = 0,
                          index_annotation_interval = 0,
                          pixels_per_base = 20,
                          outline_linewidth = 0)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_12.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_13.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$bright_deep,
                          sequence_text_colour = "white",
                          line_wrapping = 65,
                          index_annotation_interval = 15)

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_13.png"))

## Create image
visualise_single_sequence(sone_2019_f1_1_expanded_ggt_added,
                          filename = paste0(output_location, "single_sequence_14.png"), 
                          return = FALSE,
                          sequence_colours = sequence_colour_palettes$sanger,
                          sequence_text_colour = "white",
                          index_annotation_colour = "magenta",
                          spacing = 0,
                          outline_colour = "magenta")

## View image
knitr::include_graphics(paste0(github_location, "single_sequence_14.png"))

## Reminder of how to load data from file
fastq_data <- read_fastq("inst/extdata/example_many_sequences_raw.fastq", calculate_length = TRUE)
metadata   <- read.csv("inst/extdata/example_many_sequences_metadata.csv")
merged_fastq_data <- merge_fastq_with_metadata(fastq_data, metadata)

## Subset and change colnames to make it match example_many_sequences
merged_fastq_data <- merged_fastq_data[, c("family", "individual", "read", "forward_sequence", "sequence_length", "forward_quality")]
colnames(merged_fastq_data)[c(4,6)] <- c("sequence", "quality")

## Prove equivalance to example_many_sequences
identical(merged_fastq_data, example_many_sequences[, 1:6])

## Look at first 4 rows of the data as a reminder
github_table(head(merged_fastq_data, 4))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(merged_fastq_data)

## View the character vector
sequences_for_visualisation

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_01.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_01.png"))

## Extract sequences to a character vector
## Remember that example_many_sequences is identical to the data 
## read from FASTQ and metadata CSV in the previous code section
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = c("family" = 8,
                                                                              "individual" = 2),
                                                          sort_by = "sequence_length",
                                                          desc_sort = TRUE)

## We will not view the character vector in the interests of avoiding clutter.

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_02.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_02.png"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = c("individual" = 1),
                                                          sort_by = "sequence_length",
                                                          desc_sort = FALSE)

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_03.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_03.png"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = NA,
                                                          sort_by = "sequence_length",
                                                          desc_sort = TRUE)

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_04.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_04.png"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = NA,
                                                          sort_by = NA)

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_05.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_05.png"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = c("family" = 2,
                                                                              "individual" = 1),
                                                          sort_by = NA)

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_06.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_06.png"))

## Reorder families
example_many_sequences_reordered <- example_many_sequences
example_many_sequences_reordered$family_reordered <- factor(example_many_sequences_reordered$family,
                                                            levels = c("Family 2", 
                                                                       "Family 3", 
                                                                       "Family 1"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences_reordered,
                                                          sequence_variable = "sequence",
                                                          grouping_levels = c("family_reordered" = 0),
                                                          sort_by = "sequence_length")

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_07.png"),
                         return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_07.png"))

## Extract qualities to character vector,
## sorted alphabetically by quality string
extracted_and_sorted_qualities <- extract_and_sort_sequences(example_many_sequences,
                                                             sequence_variable = "quality",
                                                             grouping_levels = c("family" = 2),
                                                             sort_by = "quality",
                                                             desc_sort = FALSE)

## View character vector
print(extracted_and_sorted_qualities, quote = F)

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences)

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_08.png"),
                         return = FALSE,
                         sequence_colours = c("orange", "#00FF00", "magenta", "black"),
                         sequence_text_colour = "cyan",
                         background_colour = "yellow",
                         outline_colour = "red",
                         outline_join = "round",
                         outline_linewidth = 15,
                         sequence_text_size = 40,
                         margin = 5)

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_08.png"))

## Extract sequences to a character vector
sequences_for_visualisation <- extract_and_sort_sequences(example_many_sequences,
                                                          grouping_levels = c("family" = 4,
                                                                              "individual" = 1))

## Use the character vector to make the image
visualise_many_sequences(sequences_for_visualisation,
                         filename = paste0(output_location, "many_sequences_09.png"),
                         return = FALSE,
                         sequence_colours = sequence_colour_palettes$bright_pale,
                         sequence_text_size = 0,
                         margin = 0.1,
                         pixels_per_base = 20,
                         outline_join = "round")

## View image
knitr::include_graphics(paste0(github_location, "many_sequences_09.png"))

modified_fastq_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")
metadata            <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## Merge with offset = 1 (map C to C of palindromic CG sites when reversing)
## See the reading from modified FASTQ section for a full discussion
merged_modification_data <- merge_methylation_with_metadata(modified_fastq_data, metadata,
                                                            reversed_location_offset = 1)

## Subset and change colnames to make it match example_many_sequences
merged_modification_data <- merged_modification_data[, c("family", "individual", "read", "forward_sequence", "sequence_length", "forward_quality", "forward_C+m?_locations", "forward_C+m?_probabilities", "forward_C+h?_locations", "forward_C+h?_probabilities")]
colnames(merged_modification_data)[c(4,6:10)] <- c("sequence", "quality", "methylation_locations", "methylation_probabilities", "hydroxymethylation_locations", "hydroxymethylation_probabilities")

## Prove equivalance to example_many_sequences
identical(merged_modification_data, example_many_sequences)

## Look at first 4 rows of the data as a reminder
github_table(head(merged_modification_data, 4))

## Extract locations, probabilities, and lengths
## Remember that example_many_sequences is identical to merged_modification_data
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 8, "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = TRUE
)

methylation_data_for_visualisation

## Extract locations, probabilities, and lengths
hydroxymethylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "hydroxymethylation_locations",
    probabilities_colname = "hydroxymethylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 8, "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = TRUE
)

hydroxymethylation_data_for_visualisation

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_01.png"),
                      return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "modification_01.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Methylation probability")

## Write png from object
ggsave(paste0(output_location, "modification_01_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_01_scalebar.png"))

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("individual" = 3),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_02.png"),
                      return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "modification_02.png"))

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_03.png"),
                      return = FALSE,
                      margin = 4, 
                      low_colour = "#00FF00",
                      high_colour = "blue",
                      modified_bases_outline_colour = "purple",
                      modified_bases_outline_linewidth = 5,
                      other_bases_colour = "white",
                      other_bases_outline_colour = "darkgreen",
                      other_bases_outline_linewidth = 0.5,
                      background_colour = "red")

## View image
knitr::include_graphics(paste0(github_location, "modification_03.png"))

## Create scalebar and save to object
## Text colour doesn't have an argument within the function
## but can be modified by adding to the ggplot object like normal
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Methylation probability",
                                               low_colour = "green",
                                               high_colour = "#0000FF",
                                               background_colour = "#FF0000",
                                               outline_colour = "darkgreen",
                                               outline_linewidth = 1) +
    theme(axis.title = element_text(colour = "white"),
          axis.text  = element_text(colour = "white"))

## Write png from object
ggsave(paste0(output_location, "modification_03_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_03_scalebar.png"))

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_04.png"),
                      return = FALSE,
                      margin = 0.1, 
                      low_colour = "white",
                      high_colour = "black",
                      other_bases_colour = "lightblue1",
                      other_bases_outline_colour = "grey",
                      other_bases_outline_linewidth = 1,
                      background_colour = "white")

## View image
knitr::include_graphics(paste0(github_location, "modification_04.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Methylation probability",
                                               low_colour = "white",
                                               high_colour = "black",
                                               background_colour = "lightblue1")

## Write png from object
ggsave(paste0(output_location, "modification_04_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_04_scalebar.png"))

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_05.png"),
                      return = FALSE,
                      margin = 0.1, 
                      low_colour = "white",
                      low_clamp = 127,
                      high_colour = "black",
                      high_clamp = 128,
                      other_bases_colour = "lightblue1",
                      other_bases_outline_colour = "grey",
                      other_bases_outline_linewidth = 1,
                      background_colour = "white")

## View image
knitr::include_graphics(paste0(github_location, "modification_05.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Methylation probability",
                                               low_colour = "white",
                                               low_clamp = 127,
                                               high_colour = "black",
                                               high_clamp = 128,
                                               background_colour = "lightblue1")

## Write png from object
ggsave(paste0(output_location, "modification_05_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_05_scalebar.png"))

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "methylation_locations",
    probabilities_colname = "methylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_06.png"),
                      return = FALSE,
                      low_clamp = 0.3*255,
                      high_clamp = 0.7*255,
                      outline_linewidth = 0)

## View image
knitr::include_graphics(paste0(github_location, "modification_06.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Methylation probability",
                                               low_clamp = 0.3*255,
                                               high_clamp = 0.7*255)

## Write png from object
ggsave(paste0(output_location, "modification_06_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_06_scalebar.png"))

## Extract information to list of character vectors
hydroxymethylation_data_for_visualisation <- extract_methylation_from_dataframe(
    example_many_sequences,
    locations_colname = "hydroxymethylation_locations",
    probabilities_colname = "hydroxymethylation_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = hydroxymethylation_data_for_visualisation$locations,
                      modification_probabilities = hydroxymethylation_data_for_visualisation$probabilities,
                      sequence_lengths           = hydroxymethylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_07.png"),
                      return = FALSE,
                      low_clamp = 0.1*255,
                      high_clamp = 0.5*255,
                      other_bases_outline_linewidth = 0)

## View image
knitr::include_graphics(paste0(github_location, "modification_07.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(x_axis_title = "Hydroxymethylation probability",
                                               low_clamp = 0.1*255,
                                               high_clamp = 0.5*255)

## Write png from object
ggsave(paste0(output_location, "modification_07_scalebar.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_07_scalebar.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(precision = 10)

## Write png from object
ggsave(paste0(output_location, "modification_scalebar_alone_01.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_scalebar_alone_01.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(precision = 50,
                                               do_x_ticks = FALSE)

## Write png from object
ggsave(paste0(output_location, "modification_scalebar_alone_02.png"), scalebar, dpi = 300, width = 5.25, height = 1.5, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_scalebar_alone_02.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(high_colour = "green",
                                               low_colour = "yellow",
                                               high_clamp = 0.8,
                                               low_clamp = 0.5, 
                                               full_range = c(0,1),
                                               precision = 100,
                                               do_x_ticks = TRUE,
                                               x_axis_title = "some kind of title",
                                               do_side_scale = TRUE,
                                               side_scale_title = "some other title",
                                               outline_colour = "red",
                                               outline_linewidth = 3) +
    scale_x_continuous(breaks = seq(0, 1, 0.1))

## Write png from object
ggsave(paste0(output_location, "modification_scalebar_alone_03.png"), scalebar, dpi = 300, width = 5.25, height = 2, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_scalebar_alone_03.png"))

## Create scalebar and save to object
scalebar <- visualise_methylation_colour_scale(low_clamp = 0.1*255,
                                               high_clamp  = 0.9*255,
                                               x_axis_title = "Methylation probability",
                                               do_side_scale = TRUE,
                                               side_scale_title = "Raw\nprobability\nscore",
                                               outline_linewidth = 0)

## Write png from object
ggsave(paste0(output_location, "modification_scalebar_alone_04.png"), scalebar, dpi = 300, width = 5.25, height = 2, device = ragg::agg_png)

## View image
knitr::include_graphics(paste0(github_location, "modification_scalebar_alone_04.png"))

modified_fastq_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")
metadata            <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## Merge with offset = 0 (map C to G of palindromic CG sites when reversing)
## See the reading from modified FASTQ section for a full discussion
merged_modification_data <- merge_methylation_with_metadata(modified_fastq_data, metadata,
                                                            reversed_location_offset = 0)

## Extract information to list of character vectors
## Note that this time we read from merged_modification_data,
## rather than example_many_sequences
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    merged_modification_data,
    locations_colname = "forward_C+m?_locations",
    probabilities_colname = "forward_C+m?_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_08.png"),
                      return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "modification_08.png"))

modified_fastq_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")
metadata            <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## Merge with offset = -1 (not recommended)
merged_modification_data <- merge_methylation_with_metadata(modified_fastq_data, metadata,
                                                            reversed_location_offset = -1)

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    merged_modification_data,
    locations_colname = "forward_C+m?_locations",
    probabilities_colname = "forward_C+m?_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_09.png"),
                      return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "modification_09.png"))

modified_fastq_data <- read_modified_fastq("inst/extdata/example_many_sequences_raw_modified.fastq")
metadata            <- read.csv("inst/extdata/example_many_sequences_metadata.csv")

## Merge with offset = 0 (but we aren't using the forward-ified information anyway)
merged_modification_data <- merge_methylation_with_metadata(modified_fastq_data, metadata,
                                                            reversed_location_offset = 0)

## Extract information to list of character vectors
methylation_data_for_visualisation <- extract_methylation_from_dataframe(
    merged_modification_data,
    locations_colname = "C+m?_locations",
    probabilities_colname = "C+m?_probabilities",
    lengths_colname = "sequence_length",
    grouping_levels = c("family" = 6, 
                        "individual" = 2),
    sort_by = "sequence_length",
    desc_sort = FALSE
)

## Use saved methylation data for visualisation to make image
visualise_methylation(modification_locations     = methylation_data_for_visualisation$locations,
                      modification_probabilities = methylation_data_for_visualisation$probabilities,
                      sequence_lengths           = methylation_data_for_visualisation$lengths,
                      filename = paste0(output_location, "modification_10.png"),
                      return = FALSE)

## View image
knitr::include_graphics(paste0(github_location, "modification_10.png"))