Package {OmicsBraid}

OmicsBraid: cross-omics effect concordance and heterogeneity

Description

OmicsBraid is a research-oriented framework for cross-layer inference from matched bulk multi-omics studies. Its core estimand is the vector of standardized group effects for the same biological entity/pathway across ordered omics layers. It is intentionally not a raw-data preprocessing or latent-factor integration package. Robust empirical calibration is available for the omnibus and heterogeneity tests when asymptotic chi-square reference distributions are questionable.

Author(s)

Maintainer: Adeel Farooq jhwanj9@gmail.com

Authors:

• Adeel Farooq jhwanj9@gmail.com

See Also

Useful links:

• https://github.com/microbes-potential/OmicsBraid

• https://microbes-potential.github.io/OmicsBraid/

• Report bugs at https://github.com/microbes-potential/OmicsBraid/issues

Coerce supported objects to OmicsBraid data

Description

Converts supported input objects into the standardized data structure used by OmicsBraid for downstream cross-omic analyses.

Usage

as_omics_braid_data(x, ...)

Arguments

Value

An object of class omics_braid_data containing the harmonized omics assays, sample metadata, and optional feature annotation, ready for downstream OmicsBraid analyses.

Bootstrap confidence intervals for GLS consensus effects

Description

Uses matched subject-bootstrap layer-effect draws from 'bootstrap_effect_covariance()' and the fitted covariance structure to form a bootstrap distribution of the GLS consensus effect. The hypothesis tests and analytic standard errors remain unchanged; these intervals are intended for robust uncertainty reporting and coverage validation.

Usage

bootstrap_consensus_intervals(
  effects,
  bootstrap,
  integrated = NULL,
  method = c("percentile", "basic"),
  conf_level = 0.95,
  min_boot = 100L,
  min_omics = 2L
)

Arguments

Value

One row per entity with bootstrap consensus interval diagnostics.

Estimate cross-omic effect covariance by matched-subject bootstrap

Description

Biological subjects are resampled as whole units, preserving their matched measurements across omics. Bootstrap correlations are estimated for each entity and combined with analytic marginal standard errors from 'estimate_effects()': V = diag(SE) R_boot diag(SE). This stabilizes marginal uncertainty while retaining empirically estimated cross-layer dependence.

Usage

bootstrap_effect_covariance(
  data,
  group,
  reference,
  comparison,
  effects = NULL,
  entities = NULL,
  B = 500L,
  seed = 1L,
  min_n = 3L,
  shrinkage = 0.05,
  min_complete = 50L,
  stratified = TRUE
)

Arguments

Value

Object of class 'omics_braid_covariance' containing a covariance matrix per entity.

Bootstrap confidence intervals for layer-specific standardized effects

Description

Constructs nonparametric confidence intervals for Hedges' g using the matched, group-stratified subject bootstrap draws generated by 'bootstrap_effect_covariance()'. Percentile and basic intervals reuse those bootstrap draws. BCa intervals additionally estimate the acceleration term from leave-one-subject-out jackknife effects within each omic.

Usage

bootstrap_effect_intervals(
  effects,
  bootstrap,
  method = c("percentile", "basic", "bca"),
  conf_level = 0.95,
  min_boot = 100L,
  data = NULL,
  group = NULL,
  reference = NULL,
  comparison = NULL,
  min_n = 3L
)

Arguments

Details

These intervals are an uncertainty-reporting option. They do not replace the analytic standard errors or p-values used by the current OmicsBraid hypothesis tests unless a future method version explicitly validates such a change.

Value

A data frame with one row per usable entity-by-omic effect and bootstrap interval diagnostics.

Quantify uncertainty in effect-braid geometry

Description

Draws from a multivariate normal approximation to the estimated cross-omic effects and reports how often each practical geometric pattern occurs. These frequencies propagate estimation uncertainty; they are not Bayesian posterior probabilities and they do not replace the confirmatory inferential braid label.

Usage

braid_pattern_probabilities(
  effects,
  covariance = NULL,
  omic_order,
  margin = 0.3,
  n_draws = 2000L,
  trajectory_margin = 0.15,
  seed = 1L,
  min_slope = NULL
)

Arguments

Value

Long data frame of geometric pattern frequencies per entity.

Create a one-row-per-entity master result table

Description

Create a one-row-per-entity master result table

Usage

braid_results_table(result)

Arguments

Value

Data frame merging integrated inference, braid classification, and compact layer summaries.

Classify cross-omic braid patterns using inferential evidence

Description

Braid labels are deliberately conservative. Opposite statistically supported layer directions confirm inversion. Buffering and emergence require practical equivalence in the appropriate downstream/upstream layers. Concordance, attenuation, and amplification require all observed layers to support one direction and use a covariance-aware GLS trajectory test. If the joint-null omnibus test is not rejected and practical equivalence is not established, the result is labelled 'no_detectable_effect' rather than incorrectly claiming equivalence.

Usage

classify_braids(
  equivalence,
  omic_order,
  covariance = NULL,
  integrated = NULL,
  trend = NULL,
  trajectory_margin = 0.15,
  alpha = 0.05,
  min_slope = NULL
)

Arguments

Details

A separate 'suggestive_pattern' is derived from effect geometry only. It can be useful when the inferential pattern is unresolved because the data are too imprecise, but it is not a confirmatory conclusion.

Value

One row per entity containing confirmatory and suggestive labels plus trajectory diagnostics.

Empirically calibrate OmicsBraid omnibus and heterogeneity tests

Description

Provides resampling-based p-values for the two cross-omic quadratic tests. The omnibus test can be calibrated by matched-subject label permutation or by a centered matched-subject bootstrap. The heterogeneity test can be calibrated by a raw-data null-shift matched bootstrap (recommended) or by an effect-level centered bootstrap under the fitted common-effect null.

Usage

empirical_omics_tests(
  data,
  group,
  reference,
  comparison,
  effects = NULL,
  entities = NULL,
  B = 499L,
  seed = 1L,
  min_n = 3L,
  min_omics = 2L,
  min_complete = 100L,
  omnibus_method = c("permutation", "centered_bootstrap"),
  heterogeneity_method = c("null_shift_bootstrap", "centered_bootstrap"),
  orientation = NULL,
  p_adjust = "BH"
)

Arguments

Details

The resampling is performed at the biological-subject level: all available omic measurements belonging to a subject remain linked. This preserves the cross-omic dependence that would be destroyed by shuffling individual assay matrices independently.

Empirical calibration is intended as a robust alternative when the chi-square reference distributions used by 'integrate_effects()' may be inaccurate, for example under heavy-tailed sampling distributions. The asymptotic statistics remain available and are not overwritten by this function.

Value

A data frame containing asymptotic-independent empirical omnibus and heterogeneity p-values, empirical critical values, and resampling diagnostics.

Estimate layer-specific standardized effects

Description

Estimates Hedges' g for a two-group contrast in each feature/pathway and omic. Inputs should already be quality-controlled and normalized appropriately for their assay technology. Hedges' g is scale-free but does not repair poor raw preprocessing, severe censoring, or inappropriate transformations.

Usage

estimate_effects(
  data,
  group,
  reference,
  comparison,
  entities = NULL,
  min_n = 3L,
  conf_level = 0.95,
  p_adjust = "BH"
)

Arguments

Value

Data frame of effect estimates and uncertainty.

Harmonize assay-specific feature identifiers to common entities

Description

Maps feature IDs within each omic to a shared entity identifier for entity-level cross-omic analysis (for example Ensembl RNA identifiers and UniProt proteins to a common gene symbol). Many-to-one mappings are rejected by default because collapsing isoforms/probes changes the scientific estimand.

Usage

harmonize_entities(
  data,
  mapping,
  collapse = c("error", "mean", "median"),
  min_mapped = 1L
)

Arguments

Value

An 'omics_braid_data' object with harmonized entity row names and a mapping report stored in 'attr(x, "entity_harmonization")'.

Integrate effects across omic layers and quantify heterogeneity

Description

Uses generalized least squares (GLS) to estimate a common cross-omic effect. A generalized Cochran Q statistic tests whether the layer-specific effects are compatible with a common effect after accounting for their sampling covariance. A separate multivariate Wald-type omnibus statistic tests the joint null that all layer effects are zero; unlike the consensus effect, this test does not cancel equally strong effects occurring in opposite directions. The reported I2-like statistic is descriptive and should not be interpreted as literal between-study heterogeneity because omics layers are not studies.

Usage

integrate_effects(
  effects,
  covariance = NULL,
  min_omics = 2L,
  p_adjust = "BH",
  conf_level = 0.95
)

Arguments

Value

Data frame of integrated effects and heterogeneity diagnostics.

Construct an OmicsBraid data object

Description

Construct an OmicsBraid data object

Usage

omics_braid_data(assays, metadata, sample_id = "sample_id", annotation = NULL)

Arguments

Value

An object of class 'omics_braid_data'.

Harmonize the sign orientation of omic-layer effects

Description

Some omic measurements have an interpretation whose natural direction is opposite to an activity/abundance scale used in other layers. This helper multiplies selected omic effects by +1 or -1 and applies the corresponding sign transformation to covariance matrices. Use it only when the orientation is scientifically justified; it must not be used to force apparent agreement.

Usage

orient_omics(effects, covariance = NULL, orientation)

Arguments

Value

A list with oriented 'effects' and 'covariance'.

Plot a braid heatmap across entities and omics

Description

Plot a braid heatmap across entities and omics

Usage

plot_braid_heatmap(
  result,
  entities = NULL,
  omic_order = result$settings$omic_order
)

Arguments

Value

A ggplot object.

Plot concordance versus integrated significance

Description

Plot concordance versus integrated significance

Usage

plot_concordance_map(
  result,
  label_top = 0L,
  metric = c("evidence_direction_agreement", "direction_agreement", "i2_consistency"),
  significance = c("omnibus", "consensus")
)

Arguments

Value

A ggplot object.

Plot an Effect Braid

Description

Plot an Effect Braid

Usage

plot_effect_braid(
  result,
  entity,
  omic_order = result$settings$omic_order,
  show_ci = TRUE,
  show_equivalence_region = TRUE
)

Arguments

Value

A ggplot object.

Plot an Omics Evidence Forest

Description

Plot an Omics Evidence Forest

Usage

plot_evidence_forest(result, entity, omic_order = result$settings$omic_order)

Arguments

Value

A ggplot object.

Read OmicsBraid input files

Description

Read OmicsBraid input files

Usage

read_omics_braid(
  metadata_file,
  assay_files,
  sample_id = "sample_id",
  sep = NULL,
  annotation_file = NULL
)

Arguments

Value

An 'omics_braid_data' object.

Run the complete OmicsBraid workflow on sample-level data

Description

Run the complete OmicsBraid workflow on sample-level data

Usage

run_omics_braid(
  data,
  group,
  reference,
  comparison,
  omic_order = names(data$assays),
  entities = NULL,
  pathway_mapping = NULL,
  pathway_method = "mean_z",
  min_pathway_features = 3L,
  bootstrap_B = 500L,
  bootstrap_shrinkage = 0.05,
  empirical_tests = FALSE,
  empirical_B = 499L,
  empirical_omnibus_method = c("permutation", "centered_bootstrap"),
  empirical_heterogeneity_method = c("null_shift_bootstrap", "centered_bootstrap"),
  empirical_use_as_primary = FALSE,
  ci_method = c("analytic", "percentile", "basic", "bca"),
  integrated_ci_method = c("analytic", "percentile", "basic"),
  ci_conf_level = 0.95,
  ci_min_boot = 100L,
  orientation = NULL,
  equivalence_margin = 0.3,
  alpha = 0.05,
  state_basis = c("local", "adjusted"),
  equivalence_p_adjust = "BH",
  trajectory_margin = 0.15,
  trend_p_adjust = "BH",
  min_slope = NULL,
  pattern_draws = 2000L,
  seed = 1L
)

Arguments

Value

An object of class 'omics_braid_result'.

Run OmicsBraid from externally estimated summary statistics

Description

Run OmicsBraid from externally estimated summary statistics

Usage

run_omics_braid_summary(
  effects,
  covariance = NULL,
  omic_order,
  orientation = NULL,
  equivalence_margin = 0.3,
  alpha = 0.05,
  state_basis = c("local", "adjusted"),
  equivalence_p_adjust = "BH",
  trajectory_margin = 0.15,
  trend_p_adjust = "BH",
  min_slope = NULL,
  pattern_draws = 2000L,
  seed = 1L
)

Arguments

Value

'omics_braid_result' without sample-level data.

Score pathways within each omic layer

Description

This convenience function z-standardizes each feature across samples within an omic and then aggregates features assigned to the same pathway. OmicsBraid's inferential core can also accept externally computed pathway/activity scores, which is recommended when a domain-specific scoring method is preferred.

Usage

score_pathways(
  data,
  mapping,
  method = c("mean_z", "median_z"),
  min_features = 3L,
  center = TRUE,
  scale = TRUE
)

Arguments

Value

An 'omics_braid_data' object whose assay rows are pathways.

Simulate multi-omics data with known braid patterns

Description

Generates matched sample-level data for method development and validation. Residuals are correlated across omic layers for each entity, allowing the covariance, heterogeneity, equivalence, and classification procedures to be tested against known cross-layer effects.

Usage

simulate_braid_data(
  n_per_group = 60L,
  n_reference = NULL,
  n_comparison = NULL,
  omics = c("RNA", "Protein", "Metabolite"),
  patterns = NULL,
  rho = 0.4,
  missing_rate = 0,
  modality_missing_rate = 0,
  residual_distribution = c("normal", "t"),
  t_df = 5,
  seed = 1L
)

Arguments

Value

List with 'data' ('omics_braid_data') and 'truth' table.

Test ordered cross-omic effect trajectories with generalized least squares

Description

Fits a covariance-aware linear trajectory to standardized effects across an explicitly ordered set of omic layers. Effects are aligned to the dominant observed direction before fitting, so a positive slope represents increasing absolute effect magnitude (amplification) and a negative slope represents decreasing magnitude (attenuation). Three practical hypotheses are evaluated: a meaningfully positive slope, a meaningfully negative slope, and practical equivalence of the slope to a flat trajectory within '[-trajectory_margin, +trajectory_margin]'.

Usage

test_braid_trend(
  effects,
  covariance = NULL,
  omic_order,
  trajectory_margin = 0.15,
  alpha = 0.05,
  min_omics = 2L,
  p_adjust = "BH"
)

Arguments

Details

The trend test is intended for ordered layers when attenuation/amplification is scientifically meaningful. It does not establish causality or temporal direction.

Value

One row per entity containing the aligned GLS slope, uncertainty, practical trend tests, and local/adjusted trajectory states.

Test practical equivalence to a negligible effect region

Description

Performs two one-sided tests (TOST) for whether each standardized effect lies within '[-margin, +margin]'. It reports both local (entity-specific) and multiplicity-adjusted inferential states. Local states are recommended for describing the geometry of an individual braid because they do not change merely when unrelated entities are added to the analysis; adjusted states are retained for confirmatory screening across many entities.

Usage

test_equivalence(
  effects,
  margin = 0.3,
  alpha = 0.05,
  p_adjust = "BH",
  state_basis = c("local", "adjusted")
)

Arguments

Value

Effect table with TOST p-values, local/adjusted difference p-values, and both local and multiplicity-adjusted practical states.

Validate an OmicsBraid data object

Description

Validate an OmicsBraid data object

Usage

validate_omics_braid_data(x)

Arguments

Value

Invisibly returns 'TRUE' or throws an informative error.

Export OmicsBraid results

Description

Export OmicsBraid results

Usage

write_omics_braid(result, dir, save_plots = TRUE, top_n = 20L)

Arguments

Value

Invisibly returns the output directory.