GenomicBreedingPlots

BarPlots <: PlotsGB

Mutable struct for storing bar plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the bar plot figures

BoxPlots <: PlotsGB

Mutable struct for storing box plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the box plot figures

CorHeatPlots <: PlotsGB

Mutable struct for storing correlation heatmap plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the correlation heatmap figures

DistributionPlots <: PlotsGB

Mutable struct for storing distribution plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the distribution plot figures

PCBiPlots <: PlotsGB

Mutable struct for storing principal component or biplot visualizations.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the PC/biplot figures

abstract type PlotsGB end

Abstract type representing the base type for various plotting structures in GenomicBreedingPlots.

TreePlots <: PlotsGB

Mutable struct for storing tree visualization plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the tree plot figures

ViolinPlots <: PlotsGB

Mutable struct for storing violin plots.

Fields

• labels::Vector{String}: Vector containing labels for the plots
• plots::Vector{CairoMakie.Figure}: Vector containing the violin plot figures

checkdims(x::PlotsGB)::Bool

Check if dimensions of labels and plots match in a PlotsGB object.

Arguments

• x::PlotsGB: A PlotsGB object containing labels and plots

Returns

• Bool: true if the number of labels equals the number of plots, false otherwise

labeltofname(; label::String, prefix::String, suffix::String)::String

Convert a label string into a valid filename by replacing special characters.

This function takes a label string and converts it into a filename-safe string by:

1. Replacing common symbols with underscores
2. Adding a prefix and suffix
3. Cleaning up repeated separators

Arguments

• label::String: The input label to be converted
• prefix::String: String to prepend to the filename
• suffix::String: The file extension (without the dot)

Returns

• String: A cleaned filename string with format "prefix-label.suffix"

plot(type::Type{T}, genomes::Genomes; kwargs...)::T where {T<:CorHeatPlots}

Generate correlation heatmap plots for genome data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of CorHeatPlots)
• genomes::Genomes: The genome data structure to analyze

Keywords

• n_loci_alleles::Int64 = 1_000: Maximum number of loci alleles to include in the plot
• seed::Int64 = 42: Random seed for reproducibility
• plot_size::Tuple{Int64,Int64} = (600, 450): Size of each plot in pixels
• colour_scheme::Symbol = :viridis: Color scheme for the heatmap
• rev_label_colors::Bool = false: If true, reverses the text color threshold for labels
• n_threshold_to_show_text::Int64 = 1_000: Maximum number of cells before text labels are hidden

Returns

• CorHeatPlots: A CorHeatPlots object containing the generated correlation heatmaps

Description

Creates correlation heatmaps showing relationships between:

• Loci alleles across all populations
• Entries across all populations
• Loci alleles within each population
• Entries within each population

Each heatmap includes correlation values and sample sizes for each pair, with automatic text sizing and visibility based on the number of elements being displayed.

Throws

• ArgumentError: If the Genomes struct dimensions are invalid

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> hplots = GenomicBreedingPlots.plot(CorHeatPlots, genomes);

julia> fnames = saveplots(hplots, format="png")

julia> rm.(fnames);

plot(type::Type{T}, genomes::Genomes; n_loci_alleles::Int64 = 1_000, seed::Int64 = 42, plot_size::Tuple{Int64,Int64} = (600, 450))::T where {T<:DistributionPlots}

Generate a density plot of allele frequencies distribution from genomic data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of DistributionPlots)
• genomes::Genomes: A Genomes struct containing the genomic data to plot
• n_loci_alleles::Int64: Number of loci to sample for plotting (default: 1000)
• seed::Int64: Random seed for reproducibility (default: 42)
• plot_size::Tuple{Int64,Int64}: Size of the output plot in pixels (width, height) (default: (600, 450))

Returns

• T<:DistributionPlots: A DistributionPlots object containing the generated plot

Description

This function creates a density plot showing the distribution of allele frequencies across the sampled loci. It randomly samples a specified number of loci from the genomic data and plots their frequency distribution using CairoMakie.

Throws

• ArgumentError: If the Genomes struct dimensions are invalid or corrupted

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> dplots = GenomicBreedingPlots.plot(DistributionPlots, genomes);

julia> fnames = saveplots(dplots)

julia> rm.(fnames);

plot(type::Type{T}, genomes::Genomes; kwargs...)::T where {T<:PCBiPlots}

Generate Principal Component Analysis (PCA) biplots for genomic data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of PCBiPlots)
• genomes::Genomes: A Genomes struct containing the genomic data to plot

Keywords

• n_loci_alleles::Int64=1_000: Maximum number of loci-alleles to include in the analysis
• seed::Int64=42: Random seed for reproducibility
• plot_size::Tuple{Int64,Int64}=(600, 450): Size of the output plots in pixels
• colour_scheme::Symbol=:tol_muted: Color scheme to use for the plots

Returns

• PCBiPlots: A PCBiPlots object containing two plots:
  1. PCA biplot of entries colored by population
  2. PCA biplot of loci colored by chromosome

Details

The function performs the following operations:

1. Validates input dimensions
2. Samples loci-alleles if necessary
3. Processes allele frequencies matrix
4. Removes columns with zero variance
5. Performs PCA and generates two biplots:
   • One showing the relationship between entries/populations
   • One showing the relationship between loci/chromosomes

Throws

• ArgumentError: If the Genomes struct is corrupted
• ErrorException: If the Genomes struct is too sparse

Examples

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> pplots = GenomicBreedingPlots.plot(PCBiPlots, genomes);

julia> fnames = saveplots(pplots)

julia> rm.(fnames);

plot(type::Type{T}, genomes::Genomes; kwargs...)::T where {T<:TreePlots}

Generate hierarchical clustering dendrograms for a Genomes object.

Arguments

• type::Type{T}: The type of plot to generate (must be subtype of TreePlots)
• genomes::Genomes: A Genomes struct containing genetic data

Keyword Arguments

• n_loci_alleles::Int64=1_000: Number of loci-alleles to sample for plotting
• seed::Int64=42: Random seed for reproducibility
• plot_size::Tuple{Int64,Int64}=(600, 450): Size of the output plots in pixels
• colour_scheme::Symbol=:tol_muted: Color scheme to use for the dendrograms
• horizontal::Bool=true: If true, plot dendrograms horizontally; if false, vertically

Returns

• TreePlots: A TreePlots object containing two dendrograms:
  1. Clustering of loci-alleles based on genotypes
  2. Clustering of entries (samples) based on genotypes

Details

Uses Ward's minimum variance method for hierarchical clustering based on Euclidean distances. The dendrograms are colored using the specified color scheme and optimally ordered for visualization.

Throws

• ArgumentError: If the Genomes struct dimensions are invalid

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> tplots = GenomicBreedingPlots.plot(TreePlots, genomes);

julia> fnames = saveplots(tplots)

julia> rm.(fnames);

plot(type::Type{T}, genomes::Genomes; kwargs...)::T where {T<:ViolinPlots}

Generate a violin plot visualizing allele frequencies across different populations in genomic data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of ViolinPlots)
• genomes::Genomes: A Genomes struct containing genomic data and population information

Keywords

• n_loci_alleles::Int64=1_000: Number of loci alleles to sample for plotting
• seed::Int64=42: Random seed for reproducibility
• plot_size::Tuple{Int64,Int64}=(600, 450): Size of the output plot in pixels
• colour_scheme::Symbol=:viridis: Color scheme to use for the violin plots

Returns

• ViolinPlots: A ViolinPlots object containing the generated plot

Description

Creates a horizontal violin plot showing the distribution of allele frequencies for each population in the genomic data. The plot includes population labels with sample sizes and uses different colors for each population.

Throws

• ArgumentError: If the Genomes struct dimensions are invalid or corrupted

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> trials, _ = GenomicBreedingCore.simulatetrials(genomes=genomes, n_years=1, n_seasons=1, n_harvests=1, n_sites=1, n_replications=1, verbose=false);

julia> genomes = extractgenomes(trials); genomes.phenotypes[1,1] = missing;

julia> vplots = GenomicBreedingPlots.plot(ViolinPlots, genomes);

julia> fnames = saveplots(vplots)

julia> rm.(fnames);

plot(type::Type{T}, phenomes::Phenomes; 
     plot_size::Tuple{Int64,Int64}=(600, 450),
     colour_scheme::Symbol=:viridis,
     rev_label_colors::Bool=false,
     n_threshold_to_show_text::Int64=1_000)::T where {T<:CorHeatPlots}

Generate correlation heatmap plots for phenotypic data.

Creates multiple correlation heatmaps showing relationships between traits and entries across all populations and within individual populations.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of CorHeatPlots)
• phenomes::Phenomes: A Phenomes struct containing the phenotypic data to plot

Keywords

• plot_size::Tuple{Int64,Int64}: Size of the plot in pixels (width, height)
• colour_scheme::Symbol: Color scheme for the heatmap (e.g., :viridis)
• rev_label_colors::Bool: If true, reverses the text color threshold for labels
• n_threshold_to_show_text::Int64: Maximum number of cells before text labels are hidden

Returns

• CorHeatPlots: A CorHeatPlots object containing correlation heatmaps for:
  • Traits across all populations
  • Entries across all populations
  • Traits within each population
  • Entries within each population

Notes

• Correlation values range from -1.0 to 1.0
• Text labels show correlation values and sample sizes (when sample sizes vary)
• Text color automatically adjusts for readability against the background
• Labels are hidden when the number of cells exceeds n_threshold_to_show_text

Throws

• ArgumentError: If the Phenomes struct dimensions are corrupted

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> trials, _ = GenomicBreedingCore.simulatetrials(genomes=genomes, n_years=1, n_seasons=1, n_harvests=1, n_sites=1, n_replications=1, verbose=false);

julia> phenomes = extractphenomes(trials); phenomes.phenotypes[1,1] = missing;

julia> hplots = GenomicBreedingPlots.plot(CorHeatPlots, phenomes);

julia> fnames = saveplots(hplots, format="png")

julia> rm.(fnames);

plot(type::Type{T}, phenomes::Phenomes; plot_size::Tuple{Int64,Int64}=(600, 450))::T where {T<:DistributionPlots}

Create density plots for each trait in the provided phenomes data.

Arguments

• type::Type{T}: The type of distribution plot to create (must be a subtype of DistributionPlots).
• phenomes::Phenomes: A Phenomes struct containing the phenotypic data to plot.
• plot_size::Tuple{Int64,Int64}: Optional tuple specifying the width and height of each plot in pixels. Defaults to (600, 450).

Returns

• T<:DistributionPlots: A DistributionPlots object containing the generated density plots and their labels.

Details

The function creates density plots for each trait in the phenomes data, excluding any missing, NaN, or infinite values. Only traits with more than 3 valid observations will be plotted. Each plot includes the trait name and the number of observations in its title.

Throws

• ArgumentError: If the dimensions of the Phenomes struct are invalid or corrupted.

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> trials, _ = GenomicBreedingCore.simulatetrials(genomes=genomes, n_years=1, n_seasons=1, n_harvests=1, n_sites=1, n_replications=1, verbose=false);

julia> phenomes = extractphenomes(trials); phenomes.phenotypes[1,1] = missing;

julia> dplots = GenomicBreedingPlots.plot(DistributionPlots, phenomes);

julia> fnames = saveplots(dplots)

julia> rm.(fnames);

plot(type::Type{T}, phenomes::Phenomes; plot_size::Tuple{Int64,Int64}=(600, 450), colour_scheme::Symbol=:tol_muted)::T where {T<:PCBiPlots}

Generate Principal Component Analysis (PCA) biplots for phenotypic data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of PCBiPlots)
• phenomes::Phenomes: A Phenomes struct containing phenotypic data, populations, and traits
• plot_size::Tuple{Int64,Int64}: Size of the output plots in pixels (width, height)
• colour_scheme::Symbol: Color scheme to use for the plots (default: :tol_muted)

Returns

• PCBiPlots: A PCBiPlots object containing two figures:
  1. PCA biplot of entries colored by population
  2. PCA biplot of traits

Details

The function performs the following operations:

• Handles missing, NaN, and Inf values in the phenotypic data
• Standardizes the data (centers and scales)
• Performs PCA when more than 2 dimensions are present
• Creates direct trait comparison plots when only 2 dimensions are present
• Adds legends when multiple populations or traits are present

Throws

• ArgumentError: If the Phenomes struct dimensions are corrupted
• ErrorException: If the phenotypic data is too sparse

Examples

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> pplots = GenomicBreedingPlots.plot(PCBiPlots, genomes);

julia> fnames = saveplots(pplots)

julia> rm.(fnames);

plot(type::Type{T}, phenomes::Phenomes; plot_size::Tuple{Int64,Int64}=(600, 450), 
     colour_scheme::Symbol=:tol_light, horizontal::Bool=true, 
     standardise_traits::Bool=true)::T where {T<:TreePlots}

Generate hierarchical clustering dendrograms for traits and entries based on phenotypic data.

Arguments

• type::Type{T}: The type of plot to generate (must be a subtype of TreePlots)
• phenomes::Phenomes: A Phenomes struct containing phenotypic data
• plot_size::Tuple{Int64,Int64}: Size of the output plots in pixels (width, height)
• colour_scheme::Symbol: Color scheme to use for the dendrogram branches
• horizontal::Bool: If true, plots dendrograms horizontally; if false, vertically
• standardise_traits::Bool: If true, standardizes trait values before distance calculation

Returns

• A TreePlots object containing two dendrograms:
  1. Traits dendrogram showing relationships between phenotypic traits
  2. Entries dendrogram showing relationships between genetic entries

Details

The function performs the following operations:

• Calculates pairwise Euclidean distances between traits and entries
• Performs hierarchical clustering using Ward's method
• Creates dendrograms with optimal branch ordering
• Adjusts font sizes automatically based on the number of labels
• Uses color schemes from ColorSchemes.jl

Throws

• ArgumentError: If the dimensions in the Phenomes struct are corrupted

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> trials, _ = GenomicBreedingCore.simulatetrials(genomes=genomes, n_years=1, n_seasons=1, n_harvests=1, n_sites=1, n_replications=1, verbose=false);

julia> phenomes = extractphenomes(trials); phenomes.phenotypes[1,1] = missing;

julia> tplots = GenomicBreedingPlots.plot(TreePlots, phenomes);

julia> fnames = saveplots(tplots)

julia> rm.(fnames);

plot(type::Type{T}, phenomes::Phenomes; plot_size::Tuple{Int64,Int64}=(600, 450), colour_scheme::Symbol=:viridis)::T where {T<:ViolinPlots}

Create violin plots for phenotypic data across different populations.

Arguments

• type::Type{T}: The type of plot to create (must be a subtype of ViolinPlots)
• phenomes::Phenomes: A Phenomes struct containing the phenotypic data to visualize
• plot_size::Tuple{Int64,Int64}: Size of the plot in pixels (width, height)
• colour_scheme::Symbol: Color scheme for the violin plots (default: :viridis)

Returns

• T<:ViolinPlots: A ViolinPlots object containing the generated plots and their labels

Details

The function creates violin plots for each trait in the phenomes data, showing the distribution of phenotypic values across different populations. Each plot includes:

• Violin plots showing the distribution density
• Box plots overlaid on the violin plots
• Population counts in the y-axis labels
• Horizontal orientation for better readability

Missing, NaN, and infinite values are automatically filtered out.

Throws

• ArgumentError: If the Phenomes struct dimensions are corrupted

Example

julia> genomes = GenomicBreedingCore.simulategenomes(n=300, verbose=false); genomes.populations = StatsBase.sample(string.("pop_", 1:3), length(genomes.entries), replace=true);

julia> trials, _ = GenomicBreedingCore.simulatetrials(genomes=genomes, n_years=1, n_seasons=1, n_harvests=1, n_sites=1, n_replications=1, verbose=false);

julia> phenomes = extractphenomes(trials); phenomes.phenotypes[1,1] = missing;

julia> vplots = GenomicBreedingPlots.plot(ViolinPlots, phenomes);

julia> fnames = saveplots(vplots)

julia> rm.(fnames);

plot(type::Type{T}, cvs::Vector{CV}; metric::String="cor", plot_size::Tuple{Int64,Int64}=(600,450), colour_scheme::Symbol=:viridis)::T where {T<:BarPlots}

Generate bar plots visualizing cross-validation results from genomic prediction models.

Arguments

• type::Type{T}: The type of plot output, must be a subtype of BarPlots
• cvs::Vector{CV}: Vector of cross-validation results objects
• metric::String="cor": The metric to plot (e.g. "cor" for correlation, "rmse" for root mean square error)
• plot_size::Tuple{Int64,Int64}=(600,450): Size of the output plots in pixels
• colour_scheme::Symbol=:viridis: Color scheme to use for the plots

Returns

• BarPlots: A BarPlots object containing the generated plots and their labels

Details

Creates various bar plots showing model performance across:

• Within-population cross-validation results
• Across-population cross-validation results

For each case, generates plots showing performance by:

• Model
• Trait
• Population

With appropriate grouping and faceting based on the CV structure.

Each bar shows the mean metric value with standard deviation in parentheses.

Throws

• ArgumentError: If any CV object is corrupted or if the requested metric doesn't exist

Examples

julia> cvs::Vector{CV} = [];

julia> for m in 1:3
            for t in 1:5
                for p in 1:4
                    n = 100
                    populations = if rand() < 0.5
                        string.("population_", sample(1:4, n, replace=true))
                    else
                        string.("population_", repeat([p], n))
                    end
                    entries = string.("entry_", sample(1:1_000, n, replace=true))
                    for r in 1:5
                        for f in 1:5
                            fit = Fit(n = 10, l = 1_000); fit.model = string("model_", m); fit.populations .= string("population_", p); fit.trait = string("trait_", t); fit.metrics = Dict("cor" => rand()/maximum([1, 5*rand()]), "rmse" => rand())
                            cv = CV(
                                string("replication_", r), 
                                string("fold_", f), 
                                fit, 
                                populations, 
                                entries, 
                                rand(n), 
                                rand(n), 
                                fit.metrics
                            )
                            push!(cvs, cv)
                        end
                    end
                end
            end
        end;

julia> bplots = GenomicBreedingPlots.plot(BarPlots, cvs);

julia> fnames = saveplots(bplots, overwrite=true)

julia> rm.(fnames);

plot(type::Type{T}, cvs::Vector{CV}; metric::String="cor", plot_size::Tuple{Int64,Int64}=(600,450), colour_scheme::Symbol=:viridis)::T where {T<:BoxPlots}

Generate box plots visualizing cross-validation results from genomic prediction models.

Arguments

• type::Type{T}: The type of BoxPlots to generate
• cvs::Vector{CV}: Vector of cross-validation (CV) results
• metric::String="cor": Metric to plot (e.g. "cor" for correlation, "rmse" for root mean square error)
• plot_size::Tuple{Int64,Int64}=(600,450): Size of the output plots in pixels
• colour_scheme::Symbol=:viridis: Color scheme to use for the plots

Returns

• BoxPlots: A struct containing labels and plots visualizing the cross-validation results

Details

Creates box plots showing genomic prediction accuracy metrics across different:

• Within-population cross-validation scenarios
• Across-population cross-validation scenarios

The plots are organized by combinations of:

• Models
• Traits
• Populations
• Training/validation population combinations

Each plot shows the distribution of the specified accuracy metric, with options for:

• Single or multiple groups per trait/model
• Horizontal orientation
• Custom color schemes
• Automatic sizing and formatting

Throws

• ArgumentError: If CV elements are corrupted or if specified metric doesn't exist

Example

julia> cvs::Vector{CV} = [];

julia> for m in 1:3
            for t in 1:5
                for p in 1:4
                    n = 100
                    populations = if rand() < 0.5
                        string.("population_", sample(1:4, n, replace=true))
                    else
                        string.("population_", repeat([p], n))
                    end
                    entries = string.("entry_", sample(1:1_000, n, replace=true))
                    for r in 1:5
                        for f in 1:5
                            fit = Fit(n = 10, l = 1_000); fit.model = string("model_", m); fit.populations .= string("population_", p); fit.trait = string("trait_", t); fit.metrics = Dict("cor" => rand()/maximum([1, 5*rand()]), "rmse" => rand())
                            cv = CV(
                                string("replication_", r), 
                                string("fold_", f), 
                                fit, 
                                populations, 
                                entries, 
                                rand(n), 
                                rand(n), 
                                fit.metrics
                            )
                            push!(cvs, cv)
                        end
                    end
                end
            end
        end;

julia> bplots = GenomicBreedingPlots.plot(BoxPlots, cvs);

julia> fnames = saveplots(bplots)

julia> rm.(fnames);

saveplots(plots::PlotsGB; idx::Vector{Int64}=[0], format::String="svg", 
          prefix::String="", use_labels::Bool=true, overwrite::Bool=false)::Vector{String}

Save plots from a PlotsGB object to files in the specified format.

Arguments

• plots::PlotsGB: A PlotsGB object containing the plots to be saved
• idx::Vector{Int64}: Indices of plots to save. Default [0] saves all plots
• format::String: Output file format, one of "svg", "png", or "pdf". Default "svg"
• prefix::String: Prefix for output filenames. Default uses type name of plots
• use_labels::Bool: If true, use plot labels in filenames; if false, use numeric indices. Default true
• overwrite::Bool: If true, overwrite existing files; if false, throw error. Default false

Returns

• Vector{String}: Vector of filenames where plots were saved

Throws

• ArgumentError: If plots object is corrupted, indices are invalid, or format is unsupported
• ErrorException: If attempting to overwrite existing files when overwrite=false