foundrHarmony Developer Guide Overview & Architecture

Package Purpose & Ecosystem

foundrHarmony (v0.6.0) is an R package within the foundr ecosystem that provides data-harmonizing tools for multiparent genetic crosses (specifically Collaborative Cross mouse studies). It serves as the data ingestion layer, transforming raw, diverse, domain-specific experimental spreadsheets and matrices (physiology, metabolomics, proteomics, transcriptomics, calcium signals, and WGCNA modules) into standard long-format structures required for core variance partitioning (foundr) and interactive visualization (foundrShiny).

Author: Brian S. Yandell (brian.yandell@wisc.edu)
License: GPL-3
Minimum R Version: ≥ 4.2.0

Related packages in the ecosystem:

foundrHarmony: Data ingestion, normalization (nqrank()), domain-specific spreadsheet parsers (userHarmony), and multi-dataset binding (bind_traits()).
foundr: Core statistical analysis, linear model estimation, orthogonal variance partitioning (partition()), summary stats (strainstats()), S3 trait classes, and ggplot2 visualizations.
foundrShiny: Interactive Shiny web application providing modular UI components and reactive visual analysis panels.
modulr: Standardization and harmonization of WGCNA co-expression module objects.

High-Level Package Architecture & Data Flow

The foundrHarmony package structures multi-study data conversion into a clean end-to-end processing pipeline:

flowchart TD
    rawFiles["Raw Data Files (Excel / CSV sheets defined in source.csv)"]
    linkpath["linkpath() Lookup & Annotation Mapping"]

    subgraph harmonyLoaders ["Specialized Loaders (userHarmony)"]
        physio["PhysioHarmony (AUC Calculation)"]
        enrich["Enrich3Harmony / EnrichHarmony"]
        livrna["LivRnaHarmony (Ensembl Gene Mapping)"]
        metlip["MetHarmony / LipidHarmony"]
        prot["ProteinHarmony (log10 Transformation)"]
        calc["CalciumHarmony (Spectral Density)"]
        mod["moduleHarmony (WGCNA Formatting)"]
    end

    harmonize["harmonize() Master Runner"]
    nqrank["normalscores() / nqrank() Normal Quantile Rank"]
    foundrStats["foundr::strainstats() Linear Models & F-Stats"]
    foundrPart["foundr::partition() Variance Partitioning"]

    rdsOut["Local Dataset RDS Files (Data, Signal, Stats)"]
    bindTraits["bind_traits() Multi-Dataset Consolidation"]
    traitObj["Unified traitObject S3 List (Data, Signal, Stats)"]

    rawFiles --> linkpath
    linkpath --> harmonyLoaders
    harmonyLoaders --> harmonize
    harmonize --> nqrank
    nqrank --> foundrStats
    foundrStats --> rdsOut
    rdsOut --> foundrPart
    foundrPart --> rdsOut
    rdsOut --> bindTraits
    bindTraits --> traitObj

    classDef input fill:#1f77b4,stroke:#333,stroke-width:2px,color:#fff
    classDef loader fill:#ff7f0e,stroke:#333,stroke-width:2px,color:#fff
    classDef core fill:#2ca02c,stroke:#333,stroke-width:2px,color:#fff
    classDef output fill:#d62728,stroke:#333,stroke-width:2px,color:#fff

    class rawFiles,linkpath input
    class physio,enrich,livrna,metlip,prot,calc,mod loader
    class harmonize,nqrank,foundrStats,foundrPart core
    class rdsOut,bindTraits,traitObj output

Developer Quick Start

Local Development Workflow

To inspect, modify, or test foundrHarmony locally:

# 1. Load local package sources dynamically
devtools::load_all()

# 2. Re-generate documentation & NAMESPACE
devtools::document()

# 3. Build pkgdown documentation site locally
pkgdown::build_site(install = FALSE)

# 4. Run package check
devtools::check(cran = FALSE, vignettes = FALSE)

This Developer Guide is organized into the following detailed sub-articles:

Developer Guide Overview & Architecture: High-level package introduction, ecosystem role, quick start commands, and top-level architecture flowchart.
Function Index & Loader Breakdown: Exhaustive breakdown of all 17 package functions and specialized userHarmony loaders across 5 core categories with visual sub-flowcharts.
Data Pipeline & Normalization Methodology: Technical specification of the standard long-format schema, normal quantile rank transformation math, trait filtering criteria, and multi-study traitObject consolidation.

foundrHarmony Developer Guide Overview & Architecture