gbrsR: Genome-Based Reconstruction of Strains Visualization

A comprehensive R package for visualizing genome reconstructions from GBRS (Genome-Based Reconstruction of Strains) data. Supports NPZ files containing genotypic probability matrices and generates publication-ready genome plots with configurable parameters.

---

!!! NPZ LOADING BACKENDS !!!

To load NPZ files, you need one of the following backends installed at runtime:

• reticulate (with Python + NumPy)
• RcppCNPy

The package will prefer reticulate if available; otherwise it will fall back to RcppCNPy. If neither is installed, loading NPZ will error with guidance.

---

Features

• NPZ File Support: Load and process NPZ files containing genotypic probability data
• Founder Strain Analysis: Analyze founder strain contributions across the genome
• Recombination Detection: Count and visualize recombination events per chromosome
• Publication Quality: Generate high-quality plots suitable for publication
• Flexible Configuration: Customize plot appearance, spacing, and styling
• Multiple Formats: Export plots as PDF, PNG, SVG, or TIFF
• Compact Mode: Pre-configured settings for space-constrained layouts

Installation

Prerequisites (R packages)

# Core R dependencies
install.packages(c("ggplot2", "dplyr", "tidyr", "stringr", "readr", "magrittr"))

# Optional NPZ backends (install at least one)
install.packages("RcppCNPy")
install.packages("reticulate")

# Suggested (optional)
install.packages(c("testthat", "knitr", "rmarkdown"))

From GitHub (Recommended)

# Install devtools if you don't have it
if (!require(devtools)) install.packages("devtools")

# Install from GitHub
devtools::install_github("churchill-lab/gbrsR")

Alternative: Using remotes

# Install remotes if you don't have it
if (!require(remotes)) install.packages("remotes")

# Install from GitHub
remotes::install_github("churchill-lab/gbrsR")

If using reticulate backend

When using the reticulate backend, ensure:

• Python 3.6+ installed and accessible from R
• NumPy installed (pip install numpy or conda install numpy)

If Python/NumPy are missing, NPZ loading via reticulate will fail; the package will then try RcppCNPy if installed.

Troubleshooting

Common Error: Backend not installed

If you see an error about missing backends when loading NPZ:

Please install reticulate or RcppCNPy to load NPZ files

Install at least one backend:

install.packages("RcppCNPy")
# or
install.packages("reticulate")

Common Error: "FileNotFoundError" or "No such file or directory"

If you see Python errors about missing files:

FileNotFoundError: [Errno 2] No such file or directory

SOLUTION: Ensure Python and NumPy are installed:

# Check Python version
python3 --version

# Install NumPy
pip3 install numpy
# OR if using conda
conda install numpy

Quick Start

library(gbrsR)

# Load and plot a genome reconstruction
plot <- plot_gbrs_genome("path/to/your/file.npz")

# Save the plot
save_genome_plot(plot, "genome_plot.pdf")

Usage Examples

Basic Genome Plot

# Create a basic genome plot
plot <- plot_gbrs_genome("example.npz", sample_name = "DO140")
save_genome_plot(plot, "DO140_genome.pdf")

Custom Configuration

# Create a compact configuration for publication
config <- configure_plot(
    font_size_recomb = 6,
    chrom_spacing = 0.2,
    bar_height = 0.1,
    founder_gap = 0.02,
    font_size_title = 16,
    compact_mode = TRUE
)

# Generate plot with custom settings
plot <- plot_gbrs_genome("example.npz", config = config)
save_genome_plot(plot, "compact_genome.pdf", width = 14, height = 10)

Pre-configured Compact Layout

# Use built-in compact configuration
config <- create_compact_config()
plot <- plot_gbrs_genome("example.npz", config = config)
save_genome_plot(plot, "publication_ready.pdf")

Return Both Plot and Data

# Get both the plot and processed data
result <- plot_gbrs_genome("example.npz", return_data = TRUE)

# Access components
plot <- result$plot
data <- result$data
recombinations <- result$recombinations

# Save plot
save_genome_plot(plot, "genome_with_data.pdf")

Input Data Format

The package expects NPZ files containing:

• Genotypic probability matrices for each chromosome
• Diplotype probabilities (e.g., AA, AB, AC, etc.)
• Marker positions across the genome

Configuration Options

The package provides extensive customization through the configure_plot() function:

• Layout: bar_height, founder_gap, chrom_spacing
• Fonts: font_size_title, font_size_axis, font_size_tick
• Colors: background_color, panel_border, grid_alpha
• Spacing: y_scale_factor, plot_margin, title_margin

Dependencies

• Required: ggplot2, dplyr, tidyr, stringr, reticulate, readr, magrittr
• Suggested: testthat, knitr, rmarkdown, extrafont, systemfonts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.