foundrHarmony Function Index & Loader Breakdown

Function Index & Loader Breakdown

This article provides an exhaustive architectural overview of all 17 functions and specialized dataset loaders in foundrHarmony, organized across 5 functional categories.

Category Breakdown Overview

flowchart LR
    cat1["1. Master Orchestration (harmonize)"]
    cat2["2. Multi-Dataset Binding (bind_traits)"]
    cat3["3. Specialized Loaders (userHarmony)"]
    cat4["4. Quantile Normalization (nqrank, normalscores)"]
    cat5["5. Metadata & Comparisons (linkpath, comp_datasets)"]

    cat1 --> cat2
    cat3 --> cat1
    cat4 --> cat1
    cat5 --> cat3
    cat5 --> cat2

    classDef c1 fill:#1f77b4,stroke:#333,stroke-width:2px,color:#fff
    classDef c2 fill:#ff7f0e,stroke:#333,stroke-width:2px,color:#fff
    classDef c3 fill:#2ca02c,stroke:#333,stroke-width:2px,color:#fff
    classDef c4 fill:#d62728,stroke:#333,stroke-width:2px,color:#fff
    classDef c5 fill:#9467bd,stroke:#333,stroke-width:2px,color:#fff

    class cat1 c1
    class cat2 c2
    class cat3 c3
    class cat4 c4
    class cat5 c5

1. Master Pipeline & Orchestration

The top-level runner standardizes, normalizes, evaluates strain statistics, partitions variance, and serializes dataset products.

Function	File	Description	Signature / Parameters
`harmonize()`	`R/harmonize.R`	Master runner function that executes a `userHarmony` loader, normalizes traits, fits linear models via `foundr::strainstats()`, filters bad/incomplete traits, partitions variance via `foundr::partition()`, and saves `Stats`, `Data`, and `Signal` RDS files	`(dataset, links, userHarmony, ..., normalize = TRUE, condition_name = "condition", minstrains = nstrains - 2, drop_na_pvalue = TRUE)`

2. Multi-Dataset Binding & Consolidation

Tools to bind individual processed dataset RDS outputs into unified multi-study datasets.

Function	File	Description	Signature / Parameters
`bind_traits()`	`R/bind_traits.R`	Combines individual dataset `Stats`, `Data`, and `Signal` RDS files into unified multi-study RDS files (and optional CSVs), creating a single `traitObject` list structure	`(datasets, dirname = ".", traitRoot = "trait", CSV = FALSE)`
`bind_traits_object()`	`R/bind_traits.R`	Internal helper that iterates across dataset names, reads specified RDS file types, and binds rows with a `dataset` ID column	`(datasets, filetype, dirname = ".")`

3. Specialized `userHarmony` Data Loaders

Domain-specific spreadsheet and matrix parsers designed to match the userHarmony loader interface standard:

flowchart TD
    subgraph harmonyLoaders ["userHarmony Loader Family"]
        physio["PhysioHarmony (Physiology & AUC)"]
        enrich["EnrichHarmony (Plasma Enrichment)"]
        enrich3["Enrich3Harmony (Multi-Sheet Excel & M-Values)"]
        livenrich["LivEnrichHarmony (Liver Enrichment)"]
        livrna["LivRnaHarmony (Liver mRNA & Ensembl)"]
        met["MetHarmony (Plasma Metabolites)"]
        lipid["LipidHarmony (Lipidomics & Annot Check)"]
        protein["ProteinHarmony (Proteomics & log10)"]
        calcium["CalciumHarmony (Basal & Oscillatory Signals)"]
        module["moduleHarmony (WGCNA Modules)"]
    end

    physio --> tidyDF["Standard Tidy Long Data Frame (dataset, strain, sex, animal, condition, trait, value)"]
    enrich --> tidyDF
    enrich3 --> tidyDF
    livenrich --> tidyDF
    livrna --> tidyDF
    met --> tidyDF
    lipid --> tidyDF
    protein --> tidyDF
    calcium --> tidyDF
    module --> tidyDF

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

    class physio,enrich,enrich3,livenrich,livrna,met,lipid,protein,calcium,module loader
    class tidyDF output

Loader Details

Function	File	Input Data Type	Special Processing / Features
`PhysioHarmony()`	`R/Physio.R`	Physiological measurements (body weight, GTT, ketones)	Computes Area Under the Curve (AUC) across minutes and weeks
`EnrichHarmony()`	`R/Enrich.R`	Plasma enrichment CSV / Excel spreadsheets	Assigns time-point traits and reshapes matrix wide-to-long
`Enrich3Harmony()`	`R/Enrich3.R`	Multi-sheet plasma enrichment Excel workbooks	Computes fractional M-values (relative enrichment) and time-series AUC summaries
`LivEnrichHarmony()`	`R/LivEnrich.R`	Liver enrichment Excel workbooks	Maps experimental sample IDs to animal identifiers
`LivRnaHarmony()`	`R/LivRna.R`	Liver mRNA expression matrices	Resolves gene symbols to Ensembl IDs and matches animal metadata against annotation tables
`MetHarmony()`	`R/Met.R`	Plasma metabolomics CSV files	Supports customizable header skips (`skiprows`) and animal ID clean-up
`LipidHarmony()`	`R/Lipid.R`	Lipidomics data matrices	Performs validation checks matching animal IDs against experimental annotation maps
`ProteinHarmony()`	`R/Protein.R`	Proteomics quantitative matrices	Applies $\log_{10}$ transformation and enforces unique gene/protein labels
`CalciumHarmony()`	`R/Calcium.R`	Islet basal & oscillatory calcium trace data	Extracts spectral density parameters, oscillation frequency, and peak amplitudes
`moduleHarmony()`	`R/moduleHarmony.R`	WGCNA co-expression `traitModule` objects	Reshapes module ejecta into standardized long-format trait datasets

4. Normalization & Score Transformation

Functions providing normal quantile rank transformation to convert arbitrary trait distributions into standard normal scores $\mathcal{N}(0,1)$ .

Function	File	Description	Signature / Parameters
`nqrank()`	`R/nqrank.R`	Normal quantile rank transformation (adapted from `broman::nqrank`) mapping numeric vectors to normal scores	`(x, jitter = FALSE)`
`normalscores()`	`R/normalscores.R`	Group-wise application of `nqrank()` across all traits in a long data frame	`(object, ...)`

5. Metadata, Lookup & Cross-Dataset Module Comparison

Utilities for dynamic file resolution, documentation manifest generation, and cross-dataset module analysis.

Function	File	Description	Signature / Parameters
`linkpath()`	`R/linkpath.R`	Looks up local file path or address based on dataset `shortname` from links mapping	`(target, links)`
`link_datasets()`	`R/linkpath.R`	Consolidates dataset names, generates `datasets.rds`, and renders `help.md` deployment documentation	`(datasets, rawdir = "../RawData", outdir = "HarmonizedData")`
`comp_datasets()`	`R/comp_datasets.R`	Compares module eigengene kMEs across datasets (e.g., `LivMet` vs `PlaMet0`) and builds `module_kMEs` object	`(object1, object2)`
`ggplot_comp_datasets()`	`R/comp_datasets.R`	Visualizes cross-dataset module kME comparisons as scatter plots with correlation metrics	`(object)`
`join_dataset_modules()`	`R/join_dataset_modules.R`	Merges module objects from different datasets based on overlapping genes/traits and animal IDs	`(object1, object2)`