PenguinoidRTools

R

A collection of useful R functions for statistical analysis and colour science.

Installation

# Install from GitHub
# install.packages("devtools")
devtools::install_github("GavinDuley/PenguinoidRTools")

Functions

ANOVA Summary Functions

aovSummaryTable(aov_data, group_var, output_file, return_raw, output_name)

Generates a comprehensive summary table of ANOVA results for a whole dataframe without interaction terms.

Parameters:

Output: A summary table containing:

Example:

library(agricolae)
library(PenguinoidRTools)

# Load example data
data(greenhouse, package = "agricolae")
aov_data <- greenhouse$greenhouse1

# Run analysis
result <- aovSummaryTable(
  aov_data = aov_data,
  group_var = "variety",
  output_file = "results.xlsx",
  return_raw = TRUE
)
print(result)

aovInteractSummaryTable(aov_data, group_vars, output_file, return_raw, output_name)

Generates a summary table of ANOVA results including interaction terms for two, three, or four-way factorial designs.

Parameters:

Output: A summary table containing:

Example:

library(agricolae)
library(PenguinoidRTools)

# Load example data
data(greenhouse, package = "agricolae")
greenhouse1_data <- greenhouse$greenhouse1

# Two-way ANOVA with interaction
result <- aovInteractSummaryTable(
  aov_data = greenhouse1_data,
  group_vars = c("variety", "method"),
  output_file = "interaction_results.xlsx"
)
print(result)

CIELab Colour Functions

R functions for calculating CIELab colour coordinates from spectrophotometry data using the OIV-MA-AS2-11 (R2006) method with D65 illuminant and 10 degree standard observer.

cielab_spectroscopy_percentage_to_fraction(transmission_pct)

Converts spectrophotometry transmission data from percentage (0-100) to fraction (0-1) format.

Example:

# Convert 50% transmission to fraction
cielab_spectroscopy_percentage_to_fraction(50)
# Returns: 0.5

# Convert a vector of percentages
cielab_spectroscopy_percentage_to_fraction(c(10, 50, 90))
# Returns: c(0.1, 0.5, 0.9)

cielab_from_spectrum(data, sample_col, path_mm)

Converts spectrophotometry transmission data to CIELab colour values using the OIV method. Automatically detects data format - just pass your dataframe and get CIELab values back.

Input: A data.frame in either format:

  1. Wide format (typical from spectrophotometers):
    • Sample identifier column (e.g., WineName, Sample)
    • Wavelength columns named X780, X779, … X380
    • Values as transmission fraction (0-1)
  2. Long format:
    • Sample identifier column (e.g., WineName)
    • lambda - Wavelength in nm
    • T - Transmission as fraction (0-1)

Parameters:

Output: A data.frame with one row per unique value of sample_col:

Note: Transmission values slightly > 1 (e.g., 1.003) are normal instrument noise and ignored. Only values > 1.1 trigger a warning.

Example:

# Wide format - just pass your data directly
result <- cielab_from_spectrum(spectroscopy_data)
# Returns one row per WineName, replicates averaged

# Get individual results per replicate (no averaging)
result <- cielab_from_spectrum(spectroscopy_data, sample_col = "Replicate")

# Long format works too
result <- cielab_from_spectrum(spectroscopy_long)

# Use different path length
result <- cielab_from_spectrum(my_data, path_mm = 5)

lab_to_C(a, b)

Calculate chroma (C) from CIELab a and b* values.

Example:

lab_to_C(30, 40)  # Returns 50

hue_deg(a, b)

Calculate hue angle in degrees from CIELab a* and b* values.

Example:

hue_deg(1, 1)   # Returns 45
hue_deg(-1, 1)  # Returns 135

delta_h_signed(h2, h1)

Calculate signed hue difference, correctly handling wraparound at 360 degrees.

Example:

delta_h_signed(10, 350)   # Returns 20 (crossing 0)
delta_h_signed(350, 10)   # Returns -20

deltaE76(L1, a1, b1, L2, a2, b2)

Calculate CIE76 colour difference (Delta E) between two colours.

Delta E interpretation:

Example:

deltaE76(50, 10, 20, 55, 15, 25)

calc_colour_diff(data, compare_by, reference_level, group_by)

Calculate centroid-to-centroid colour differences between groups. Computes the mean L, a, b* for each group and returns differences (dL, dC, dh, dE76, dE00) relative to a reference level.

Parameters:

Output: A data.frame with columns:

Example:

# Compare ethanol treatments to control
results <- calc_colour_diff(
  data = wine_colours,
  compare_by = "EtOH",
  reference_level = "CTRL"
)

# Compare within each wine variety
results <- calc_colour_diff(
  data = wine_colours,
  compare_by = "Treatment",
  reference_level = "Control",
  group_by = "WineType"
)

calc_pairwise_dE(data, compare_by, reference_level, target_levels, group_by, method)

Calculate mean pairwise colour differences between all observations in different groups. This gives a distribution of Delta E values rather than a single centroid-based value.

Parameters:

Output: A data.frame with columns:

Example:

# Compare all treatments to control using CIE76
results <- calc_pairwise_dE(
  data = wine_colours,
  compare_by = "EtOH",
  reference_level = "CTRL"
)

# Use CIE2000 for more perceptually uniform differences
results <- calc_pairwise_dE(
  data = wine_colours,
  compare_by = "Treatment",
  reference_level = "Control",
  method = "CIE2000"
)

# Compare specific treatments only
results <- calc_pairwise_dE(
  data = wine_colours,
  compare_by = "Treatment",
  reference_level = "Control",
  target_levels = c("Low", "High")
)

cielab_swatch(CIELab, file, ...)

Create and save colour swatch visualisations to various formats (PNG, PDF, SVG, etc.).

Input: A data.frame with columns:

Optional parameters:

Example:

df <- data.frame(
  WineName = c("Red", "White", "Rose"),
  CIELab_L = c(30, 90, 70),
  CIELab_a = c(50, -5, 20),
  CIELab_b = c(30, 10, 15)
)
cielab_swatch(df, "swatches.png")
cielab_swatch(df, "swatches.pdf")
cielab_swatch(df, "swatches.svg")

process_spectrum(folder_path, ...)

Process a folder of spectrophotometer CSV files into a combined data frame.

Parameters:

Output: A data.frame with columns:

Example:

# Process all CSV files in a folder
spectra <- process_spectrum("path/to/spectrophotometer/data")

# Then calculate CIELab - just pass the result directly!
result <- cielab_from_spectrum(spectra)

Agilent MassHunter UV-DAD Peak Table Functions

read_agilent_dad_peaks(file_path, sep, col_peak, col_rt, col_height, col_area)

Parses a multi-sample UV-DAD peak table exported from Agilent MassHunter Quantitative Analysis. Returns a long-format data frame with one row per detected peak per sample, ready to pass to align_peaks_by_rt().

Parameters:

Output: A long-format data frame:

Notes:

align_peaks_by_rt(peaks_long, max_drift)

Aligns peaks across samples by matching each sample’s peaks to the nearest RT in the reference sample (the first sample). Uses greedy one-to-one nearest-neighbour matching, flags ambiguous and unmatched peaks, and clusters peaks absent from the reference into new groups.

Parameters:

Output: A named list with three elements:

$aligned — Long-format table, one row per peak per sample:

$summary — One row per peak group (reference peaks + any new groups found only in non-reference samples):

$drift_stats — One row per sample:

Flags:

Example:

library(PenguinoidRTools)
library(tidyr)

peaks_long <- read_agilent_dad_peaks("polyphenols_peaktable.csv")
result     <- align_peaks_by_rt(peaks_long, max_drift = 0.25)

result$summary      # mean RT, SD, CV% per peak — equivalent to manual Excel workflow
result$drift_stats  # per-sample drift vs reference — use to tune max_drift
result$aligned      # full table with flags for review

# Pivot to wide format
area_wide <- pivot_wider(
  result$aligned[!is.na(result$aligned$ref_rt), ],
  id_cols     = ref_rt,
  names_from  = sample,
  values_from = area
)

Dependencies

For ANOVA functions

For CIELab colour difference functions (calc_colour_diff, calc_pairwise_dE)

For CIELab visualisation (cielab_swatch)

For data processing (process_spectrum)

For Agilent MassHunter peak table functions (read_agilent_dad_peaks, align_peaks_by_rt)

OIV Method Reference

The CIELab functions implement the colour calculation method specified in:

OIV-MA-AS2-11 (R2006): Determination of chromatic characteristics according to CIELab

The method uses:

License

GPL-3.0