README

An R package that turns your BoxDensityplot.R script into a reusable, documented, testable package. It reads wide-format multi-trait data (one row per genotype/sample, one column per trait) from a CSV or Excel file and produces faceted figures combining a mirrored density curve with a boxplot for each trait — with the density drawn on the left, right, or both sides of the box.

Installation

You need R (>= 4.1) installed locally. From the folder containing the BoxDensityPlot directory (or the BoxDensityPlot_0.1.0.tar.gz tarball):

# Install dependencies first, if you don't already have them
install.packages(c("ggplot2", "dplyr", "tidyr", "rlang", "readxl"))

# Option A: install from the source folder
install.packages("BoxDensityPlot", repos = NULL, type = "source")

# Option B: install from the tarball
install.packages("BoxDensityPlot_0.1.0.tar.gz", repos = NULL, type = "source")

# Option C: using devtools, from the folder
# devtools::install("BoxDensityPlot")

Quick start

library(BoxDensityPlot)

# Use the bundled example data (same as the original a.csv)
f <- example_trait_data()

# Build all three figures without writing files
plots <- plot_trait_density_box(f, save = FALSE)

# Save figures only when an output directory is explicitly supplied
out_dir <- file.path(tempdir(), "figures")
plots <- plot_trait_density_box(f, save = TRUE, out_dir = out_dir)

# Or work with your own file without saving
plots <- plot_trait_density_box("path/to/my_data.csv", save = FALSE)
plots$both
plots$left
plots$right

Using an Excel file

plot_trait_density_box("path/to/my_data.xlsx", sheet = 1)

Customizing the look

plot_trait_density_box(
  f,
  density_position = "both",
  both_colour   = "#4DBBD5",
  box_colour    = "#006D6F",
  mean_colour   = "#E31A1C",
  density_width = 0.45,
  density_alpha = 0.30,
  boxplot_width = 0.25,
  save = TRUE,
  out_dir = file.path(tempdir(), "figures"),
  format = "png",
  dpi = 600
)

Building a single custom figure

If you want full control, prepare your own long-format data and call the lower-level plot builder directly:

dat <- read_trait_data(f)
# ... your own reshaping / filtering ...
p <- make_density_boxplot(
  long_data = my_long_data,
  density_data = my_density_data,
  ncol_plot = 3,
  density_position = "right",
  density_colour = "#7FBF7B",
  plot_title = "My Traits"
)
p

Functions

Data format expected

Function	Purpose
`read_trait_data()`	Read a wide-format CSV/XLS/XLSX file into a data frame
`plot_trait_density_box()`	One-call: read data, build figure(s), optionally save them
`make_density_boxplot()`	Low-level `ggplot2` builder for one figure from prepared long data
`example_trait_data()`	Path to the bundled example CSV (the original `a.csv`)

A wide table with one identifier column (default name Genotype) and one column per trait, e.g.:

Genotype	Trait1	Trait2	…
CZR1	77.87	145.27	…
CZR2	93.17	144.61	…

If your identifier column has a different name, pass genotype_col = "YourColumnName".

Running tests

devtools::test("BoxDensityPlot")
# or, after installing:
testthat::test_package("BoxDensityPlot")

Rebuilding documentation (optional)

The man/*.Rd files and NAMESPACE are already included and match the roxygen comments in R/*.R. If you edit those comments, regenerate with:

roxygen2::roxygenise("BoxDensityPlot")