Package 'NADIA'

Description

Applies BERT batch effect correction to a normalized assay in a SummarizedExperiment. BERT uses hierarchical tree decomposition to handle missing values, making it suitable for pre-imputation batch correction on protein-level proteomics data.

Usage

batch_correct_proteomics(
  se,
  assay_name,
  batch_column = "Batch",
  corrected_assay_name = "BERT",
  algorithm = "ComBat",
  ComBat_mode = 1,
  covariates = NULL,
  qualitycontrol = FALSE,
  verbose = TRUE
)

Arguments

Value

SummarizedExperiment with the new corrected assay added, and metadata(se)$batch_correction, a list naming the features kept unadjusted (unadjusted, no variance within a batch) and those corrected for the batch only (batch_only). If BERT returns fewer features than the input, the SE is subsetted to match and a warning is issued.

Examples

data(nadia_dia)

# nadia_dia has no batch information, so the example builds a plausible one:
# two digestion batches crossed with the three conditions.
cov <- data.frame(Column = nadia_dia$metadata$Coding,
                  Batch = rep(c("b1", "b2"),
                              length.out = nrow(nadia_dia$metadata)),
                  stringsAsFactors = FALSE)
res <- process_proteomics(nadia_dia, covariate_df = cov, verbose = FALSE)

# BERT removes the batch effect and adds a "BERT" assay, leaving the
# original one untouched
se <- batch_correct_proteomics(res$se_proc, assay_name = "Impseqrob_min",
                               batch_column = "Batch", verbose = FALSE)
SummarizedExperiment::assayNames(se)

# On a real experiment you would normally pass the biological variable of
# interest in `covariates`, so that ComBat preserves it instead of removing
# it along with the batch effect. Before imputation, a protein that lacks
# two values in some batch-by-condition cell is corrected for the batch only.

Description

Orchestrator that imports, ranks, visualizes, and exports results from multiple normalization/imputation method combinations.

Usage

benchmarking_multiple(
  opdea_combined = NULL,
  confusion_combined = NULL,
  classified_combined = NULL,
  bench_metrics_combined = NULL,
  results_dir = NULL,
  pattern = "benchmark_opdea_metrics\\.tsv$",
  method_names = NULL,
  recursive = TRUE,
  strip_prefix = "benchmark_",
  metrics = .BM_METRICS,
  extended_metrics = .BM_EXTENDED_METRICS,
  p_col = "adj.P.Val",
  plots = "all",
  verbose = TRUE,
  output_dir = NULL,
  export_plots = TRUE,
  export_tables = TRUE,
  plot_width = 12,
  plot_height = 8,
  plot_dpi = 150
)

Arguments

Value

Named list with:

opdea_combined

Combined input data.frame

mean_aggregated

Mean of metrics per Assay

median_aggregated

Median of metrics per Assay

mean_ranking

Ranking table (mean-based)

median_ranking

Ranking table (median-based)

gg_ranking_heatmap_mean

Heatmap of ranks (mean)

gg_ranking_heatmap_median

Heatmap of ranks (median)

gg_ranking_bars_mean

Bar chart of final rank (mean)

gg_ranking_bars_median

Bar chart of final rank (median)

gg_metrics_heatmap_mean

Heatmap of metric values (mean)

gg_metrics_heatmap_median

Heatmap of metric values (median)

gg_metrics_comparison

Boxplot distributions

ranking_by_comparison

Named list of ranking data.frames per comparison

ranking_by_comparison_combined

data.frame with all per-comparison rankings

gg_ranking_heatmap_by_comp

Named list of heatmaps per comparison

gg_ranking_bars_by_comp

Named list of bar charts per comparison

confusion_combined

Combined confusion data.frame (if available)

gg_confusion_stacked

Faceted confusion stacked bars (if available)

gg_confusion_stacked_by_comp

Named list of confusion plots per comparison

classified_combined

Combined classified data.frame (if available)

gg_roc_by_comp

Named list of ROC plots per comparison (if available)

gg_roc_zoom_by_comp

Named list of ROC zoom plots per comparison (if available)

extended_combined

Merged classification + OpDEA data (if bench_metrics available)

extended_mean_aggregated

Mean-aggregated extended metrics per Assay

extended_ranking

Extended ranking table (11 metrics, mean-based)

gg_extended_ranking_bars

Bar chart of extended ranking

gg_extended_ranking_heatmap

Heatmap of extended ranking

parameters

List of parameters used

Examples

data(nadia_dia)
sp <- utils::read.delim(system.file("extdata", "nadia_dia_spikein.tsv.gz",
                                    package = "NADIA"))
ev <- data.frame(Comparison = rep(c("B-A", "D-A"), each = 2),
                 Species = c("ECOLI", "YEAST"),
                 expected_logFC = c(1, -0.58, 2, -3.3))
root <- file.path(tempdir(), "nadia_bench")
for (nm in c("cycloess", "quantile")) {
  de <- process_proteomics(nadia_dia, norm_method = nm,
                           verbose = FALSE)$DEPs_results
  de$Species <- sp$PG.OrganismId[match(de$Protein.IDs, sp$PG.ProteinGroups)]
  benchmarking_proteomics(de, ev, output_dir = file.path(root, nm),
                          verbose = FALSE)
}
result <- benchmarking_multiple(results_dir = root, verbose = FALSE)
result$mean_ranking
result$gg_ranking_bars_mean

Description

Evaluates the reliability of DE results by comparing them against known ground truth (multi-species spike-in experiments). Computes classification metrics, dispersion statistics, and generates visualizations.

Usage

benchmarking_proteomics(
  de_res,
  expected_values,
  alpha = 0.05,
  lfc_thr = 0,
  p_col = "adj.P.Val",
  comparisons = NULL,
  assay = NULL,
  output_dir = NULL,
  verbose = TRUE,
  species_colors = NULL,
  species_df = NULL
)

Arguments

Value

List with:

• metrics_table: Classification metrics per comparison

• confusion_by_species: Confusion matrix per Comparison x Species

• confusion_overall: Confusion matrix aggregated per Comparison

• dispersion_metrics: Dispersion stats per Comparison x Species

• classified_df: Full classified data frame

• gg_heatmap: ggplot2 performance heatmap

• gg_confusion_by_species: ggplot2 confusion matrix heatmap (by species)

• gg_confusion_overall: ggplot2 confusion matrix heatmap (aggregated)

• gg_auc_bars: ggplot2 AUC bar chart

• gg_metrics_bars: ggplot2 grouped metrics bar chart

• gg_signif_bars: ggplot2 significant proteins stacked bars (absolute)

• hc_volcano_list: Named list of Highcharter volcano plots (empty if the suggested package highcharter is not installed)

• parameters: List of parameters used

Examples

data(nadia_dia)
de <- process_proteomics(nadia_dia, verbose = FALSE)$DEPs_results
sp <- utils::read.delim(system.file("extdata", "nadia_dia_spikein.tsv.gz",
                                    package = "NADIA"))
species_df <- data.frame(Protein.IDs = sp$PG.ProteinGroups,
                         Species = sp$PG.OrganismId)
ev <- data.frame(Comparison = rep(c("B-A", "D-A"), each = 2),
                 Species = c("ECOLI", "YEAST"),
                 expected_logFC = c(1, -0.58, 2, -3.3))
bench <- benchmarking_proteomics(de, ev, species_df = species_df,
                                 verbose = FALSE)
bench$metrics_table
bench$gg_heatmap

Description

Interactive Highcharts Boxplot for Proteomics

Usage

boxplot_highchart_list(
  data,
  assays = NULL,
  color_by = "Condition",
  group_order = NULL,
  palette = NULL,
  title = NULL,
  subtitle = NULL,
  show_outliers = TRUE,
  outlier_jitter = 0.15,
  outlier_size = 3,
  box_width = 20,
  horizontal = TRUE,
  height = NULL
)

Arguments

Value

List of highchart objects (one per assay)

Examples

if (requireNamespace("highcharter", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)

  # One boxplot per assay; keep only the imputed one
  hc_list <- boxplot_highchart_list(
    res$BoxPlot_Input,
    assays      = "Impseqrob_min",
    group_order = c("A", "B", "D"),
    title       = "Boxplot: {assay}"
  )
  names(hc_list)
}

Description

Build the clustering matrix aggregated by condition

Usage

build_clustering_matrix(
  intensity_matrix,
  sample_metadata,
  selected_features,
  condition_order = NULL,
  aggregate = c("median", "mean"),
  verbose = TRUE
)

Arguments

Value

Matrix of aggregated intensities (features x conditions)

Description

Creates one row per FeatureID-Cluster combination where membership >= min_membership. This lets a protein appear in several clusters (soft clustering).

Usage

build_long_output(cl, eset_std, conditions, min_membership)

Arguments

Value

DataFrame in long format

Description

Build a PCA scores data frame from data in long format

Usage

build_pca_scores(
  pca_input,
  mode = c("all", "any", "specific"),
  alpha = 0.05,
  comparison = NULL,
  subset_label = NULL,
  center = TRUE,
  scale. = TRUE,
  filter_samples_to_comparison = FALSE,
  cond_col = "Condition"
)

Arguments

Value

Data frame with columns: SampleID, PC1, PC2, PC1_Perc, PC2_Perc, Subset, Condition, Replicate

Examples

data(nadia_dia)
res <- process_proteomics(nadia_dia, verbose = FALSE)

# Scores and the variance explained by the first two components
scores <- build_pca_scores(res$PCA_Input, mode = "all")
head(scores)
unique(scores[c("PC1_Perc", "PC2_Perc")])

Description

Builds a comparative plot with the centroids of all the clusters.

Usage

cluster_centroids_highchart(
  data,
  conditions = NULL,
  clusters = NULL,
  min_membership = NULL,
  centroid_summary = c("mean", "median"),
  palette = NULL,
  line_width = 2.5,
  show_markers = TRUE,
  title = NULL,
  height = NULL
)

Arguments

Value

highchart object

Examples

if (requireNamespace("highcharter", quietly = TRUE) &&
    requireNamespace("Mfuzz", quietly = TRUE) &&
    requireNamespace("e1071", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)
  pp <- pattern_profiler_analysis(res$se_proc, res$DEPs_results,
                                  assay_name = "Impseqrob_min",
                                  auto_select_c = FALSE, c = 3,
                                  verbose = FALSE)

  # All the cluster centroids on one chart
  hc <- cluster_centroids_highchart(pp$long_output,
                                    conditions = c("A", "B", "D"),
                                    centroid_summary = "median")
  print(class(hc))
}

Description

Builds an interactive plot showing the expression profiles of the proteins in a given cluster.

Usage

cluster_profile_highchart(
  data,
  cluster,
  conditions = NULL,
  min_membership = NULL,
  show_centroid = TRUE,
  centroid_summary = c("mean", "median"),
  cluster_color = NULL,
  line_width = 1,
  line_opacity = 0.4,
  centroid_width = 3,
  title = NULL,
  height = NULL
)

Arguments

Value

highchart object

Examples

if (requireNamespace("highcharter", quietly = TRUE) &&
    requireNamespace("Mfuzz", quietly = TRUE) &&
    requireNamespace("e1071", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)
  pp <- pattern_profiler_analysis(res$se_proc, res$DEPs_results,
                                  assay_name = "Impseqrob_min",
                                  auto_select_c = FALSE, c = 3,
                                  verbose = FALSE)

  hc <- cluster_profile_highchart(pp$long_output, cluster = 1,
                                  conditions = c("A", "B", "D"))
  print(class(hc))
}

Description

Builds a list of interactive plots for all the clusters.

Usage

cluster_profile_highchart_list(
  data,
  conditions = NULL,
  clusters = NULL,
  min_membership = NULL,
  show_centroid = TRUE,
  centroid_summary = c("mean", "median"),
  palette = NULL,
  line_width = 1,
  line_opacity = 0.4,
  centroid_width = 3,
  height = NULL
)

Arguments

Value

Named list of highchart objects

Examples

if (requireNamespace("highcharter", quietly = TRUE) &&
    requireNamespace("Mfuzz", quietly = TRUE) &&
    requireNamespace("e1071", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)
  pp <- pattern_profiler_analysis(res$se_proc, res$DEPs_results,
                                  assay_name = "Impseqrob_min",
                                  auto_select_c = FALSE, c = 3,
                                  verbose = FALSE)

  hc_profiles <- cluster_profile_highchart_list(pp$long_output,
                                                conditions = c("A", "B", "D"))
  print(names(hc_profiles))
}

Description

Computes the coordinates of a confidence ellipse based on the chi-squared distribution, similar to FactoMineR::coord.ellipse and ggplot2::stat_ellipse.

Usage

compute_confidence_ellipse(
  scores_df,
  group_col = "Condition",
  level = 0.95,
  npoints = 100
)

Arguments

Value

List of data frames, each one with columns: group, x, y

Description

Compute the convex hull (enclosing polygon) per group

Usage

compute_hulls(scores_df, group_col = "Condition")

Arguments

Value

List of data frames, each one with columns: group, x, y

Description

Configure the colour palette for the clusters

Usage

configure_cluster_palette(n_clusters, palette = NULL)

Arguments

Value

Vector of colours named by cluster

Description

Create an ExpressionSet for Mfuzz

Usage

create_expression_set(mat, feature_info = NULL)

Arguments

Value

ExpressionSet object

Description

Coordinates comparison specification, limma analysis, and result extraction.

Usage

de_analysis_proteomics(
  se,
  assay_name = NULL,
  comparisons = NULL,
  control = NULL,
  logFC_threshold = 0,
  alpha = 0.05,
  p_adj = TRUE,
  eBayes_trend = NULL,
  eBayes_robust = NULL,
  de_method = "limma",
  covariate_column = NULL,
  bio_replicate_column = NULL,
  condition_column = "Condition",
  verbose = TRUE
)

Arguments

Value

List with:

• DEPs_results: Data frame with differential expression results

• comparisons: Comparisons performed

• assay_name: Assay name used

Examples

data(nadia_dia)
norm <- normalize_proteomics(nadia_dia, norm_method = "cycloess",
                             verbose = FALSE)
imp  <- impute_proteomics(norm$se, normalized_assay_name = "cycloess",
                          verbose = FALSE)

# All pairwise comparisons
de <- de_analysis_proteomics(imp$se, assay_name = "Impseqrob_min",
                             verbose = FALSE)
head(de$DEPs_results[, c("Protein.IDs", "Comparison", "logFC", "adj.P.Val")])

# Or every condition against a single control
de2 <- de_analysis_proteomics(imp$se, assay_name = "Impseqrob_min",
                              control = "A", verbose = FALSE)
unique(de2$DEPs_results$Comparison)

Description

Joins the differential-abundance results to the soft clustering, giving the table a functional-enrichment or over-representation analysis needs: the statistics that say which proteins moved, and the cluster that says which pattern they follow.

Usage

deps_with_clusters(
  DEPs_results,
  pattern_profiler,
  assignment = c("primary", "all"),
  min_membership = NULL,
  comparison = NULL,
  significant_only = FALSE
)

Arguments

Details

The join is a left join from the results, so every protein that was tested survives it, with or without a cluster. That matters more than it looks: the complete set of tested proteins is the background an enrichment is computed against, and a protein with no cluster – one that was never selected for the clustering, or that the clustering dropped – belongs in that background rather than in the bin.

Clustering is fuzzy, so a protein can belong to several clusters at once. assignment decides what to do about it. "primary" keeps only the dominant pattern of each protein and returns exactly one row per protein and comparison, which is what most enrichment tools expect. "all" keeps every association above the threshold, which is the honest representation of a soft clustering and the one to use when the analysis downstream can weight by membership.

Value

A data frame with the columns of DEPs_results followed by Cluster, Membership and ClusterRank (1 is the protein's dominant cluster).

See Also

nadia_deps_with_clusters() for the same table read from a .nadia file, and pattern_profiler_analysis() for the clustering.

Examples

data(nadia_dia)
res <- process_proteomics(nadia_dia, verbose = FALSE)

# Without a clustering the shape is the same and the clusters are NA.
fi <- deps_with_clusters(res$DEPs_results, NULL)
head(fi)

if (requireNamespace("Mfuzz", quietly = TRUE) &&
    requireNamespace("Biobase", quietly = TRUE) &&
    requireNamespace("e1071", quietly = TRUE)) {
    pp <- pattern_profiler_analysis(res$se_proc, res$DEPs_results,
                                    assay_name = "Impseqrob_min",
                                    verbose = FALSE)

    primary <- deps_with_clusters(res$DEPs_results, pp)
    nrow(primary) == nrow(res$DEPs_results)   # the background is intact

    soft <- deps_with_clusters(res$DEPs_results, pp, assignment = "all")
    table(soft$ClusterRank)
}

Description

Detect the condition columns (z-scores)

Usage

detect_condition_columns(data)

Arguments

Value

Vector with the names of the condition columns

Description

Evaluate a range of cluster numbers

Usage

evaluate_cluster_range(
  eset_std,
  c_range = 2:10,
  m = NULL,
  n_starts = 3L,
  verbose = TRUE
)

Arguments

Value

DataFrame with the metrics per number of clusters

Description

Retrieves the intensity matrix, the feature IDs and the sample metadata from a SummarizedExperiment object.

Usage

extract_se_data(se_proc, assay_name = NULL, verbose = TRUE)

Arguments

Value

List with:

• intensity_matrix: features x samples matrix

• feature_ids: vector of protein IDs

• sample_metadata: DataFrame with SampleID, Condition, etc.

Description

Filter features by significance

Usage

filter_significant_features(
  feature_info,
  filter_mode = c("any", "all", "specific"),
  comparison = NULL,
  alpha = 0.05,
  verbose = TRUE
)

Arguments

Value

Vector of the selected FeatureIDs

Description

Build the Colour Palette for Categorical Annotations

Usage

get_annotation_palette(levels, palette = NULL)

Arguments

Value

Named vector of colours

Description

Build the Colour Palette for the Heatmap Values

Usage

get_heatmap_palette(palette = NULL, n = 11, reverse = FALSE)

Arguments

Value

Vector of colours, or a colorRamp2 function

Description

Convenience function that creates a SE from a proteomics_data object and applies the winning normalization method (from normalization benchmarking). The result is ready for imputation_metrics().

Usage

im_prepare_se(
  preprocessing,
  norm_method = NULL,
  pc1_rank = NULL,
  min_reps = NULL,
  min_groups = 1,
  covariate_df = NULL,
  norm_method_args = list(),
  include_log2 = TRUE,
  verbose = TRUE
)

Arguments

Details

Internally calls nm_prepare_se() to build the baseline SE with assay "log2", then applies the chosen normalization via .norm_dispatch().

Value

SummarizedExperiment with assays "log2" (optional) + winner method; only "log2" when that is the method.

Examples

data(nadia_dia)

# Option A: name the normalization to benchmark imputation on
se <- im_prepare_se(nadia_dia, norm_method = "cycloess", verbose = FALSE)
SummarizedExperiment::assayNames(se)

# Option B: let the winner of normalization_metrics() decide. That function
# takes a SummarizedExperiment, so the baseline is built first.
se_base <- nm_prepare_se(nadia_dia, verbose = FALSE)
nm <- normalization_metrics(se_base,
                            methods = c("cycloess", "quantile", "MAD"),
                            plots = "pc1_ranking", verbose = FALSE)
nm$pc1_rank
se2 <- im_prepare_se(nadia_dia, pc1_rank = nm$pc1_rank, verbose = FALSE)
SummarizedExperiment::assayNames(se2)

Description

Reads all TSV files matching a pattern from a directory, one assay per file. Each TSV must have column 1 as protein identifier and remaining columns as sample names matching the sample_col in the metadata file.

Usage

import_imp_matrices(
  tsv_dir,
  metadata_path,
  pattern = "matrix_log2_.*\\.tsv$",
  method_names = NULL,
  condition_col = "Condition",
  sample_col = "Column"
)

Arguments

Value

A SummarizedExperiment with one assay per TSV, colData from metadata, and rowData containing Protein.IDs.

Examples

# Round trip: write the imputed matrices out, then read them back in
data(nadia_dia)
res <- process_proteomics(nadia_dia, export_dir = tempdir(),
                          export_format = "tsv", verbose = FALSE)

meta <- file.path(tempdir(), "metadata.tsv")
utils::write.table(
  data.frame(Column = res$se_proc$Column, Condition = res$se_proc$Condition,
             Replicate = res$se_proc$Replicate),
  meta, sep = "\t", row.names = FALSE, quote = FALSE)

se <- import_imp_matrices(tsv_dir = tempdir(), metadata_path = meta)
SummarizedExperiment::assayNames(se)

Description

Reads all TSV files matching a pattern from a directory, one assay per file. Each TSV must have column 1 named ProteinGroups and remaining columns as sample names matching the sample_col in the metadata file.

Usage

import_norm_matrices(
  tsv_dir,
  metadata_path,
  pattern = "matrix_log2_.*\\.tsv$",
  method_names = NULL,
  condition_col = "Condition",
  sample_col = "Column"
)

Arguments

Value

A SummarizedExperiment with one assay per TSV, colData from metadata, and rowData containing Protein.IDs.

Examples

data(nadia_dia)
se <- nm_prepare_se(nadia_dia, verbose = FALSE)
se <- nm_run_normalizations(se, methods = c("cycloess", "MAD"), verbose = FALSE)

# Write the normalized assays as TSVs, then read them back into a new SE
tsv_dir <- file.path(tempdir(), "nm_matrices")
dir.create(tsv_dir, showWarnings = FALSE)
for (a in c("cycloess", "MAD")) {
  m <- SummarizedExperiment::assay(se, a)
  utils::write.table(
    data.frame(ProteinGroups = rownames(m), m, check.names = FALSE),
    file.path(tsv_dir, paste0("matrix_log2_", a, ".tsv")),
    sep = "\t", row.names = FALSE, quote = FALSE)
}
meta_path <- file.path(tsv_dir, "metadata.tsv")
utils::write.table(as.data.frame(SummarizedExperiment::colData(se)), meta_path,
                   sep = "\t", row.names = FALSE, quote = FALSE)

se_nm <- import_norm_matrices(tsv_dir, meta_path)
SummarizedExperiment::assayNames(se_nm)

Description

Computes NRMSE, SOR, PSS, ACC_OI via ground-truth simulation, then generates up to 6 diagnostic plots. Each plot is wrapped in tryCatch() so that a failure in one does not abort all.

Usage

imputation_metrics(
  se,
  assay_name = NULL,
  methods = .IM_BENCH_METHODS,
  combo_methods = list(),
  condition_col = "Condition",
  na_prop = 0.2,
  pattern = "random",
  method_args = list(),
  with_value = NA_real_,
  plots = "all",
  verbose = TRUE,
  output_dir = NULL,
  export_plots = TRUE,
  export_tables = TRUE,
  plot_width = 12,
  plot_height = 8,
  plot_dpi = 150
)

Arguments

Value

Named list of ggplot objects (or NULL for failed plots), plus metrics_table: a data.frame with one row per method and the columns NRMSE, SOR, PSS, ACC_OI and Rank_Mean.

Reproducibility

The cells masked to build the ground truth are drawn from the caller's RNG, and so are the imputations of the stochastic methods (MinProb, QRILC, PI, mice, missForest, MLE). Call set.seed() beforehand to reproduce a run.

Examples

data(nadia_dia)
se <- im_prepare_se(nadia_dia, norm_method = "cycloess", verbose = FALSE)

# The default sweeps 15 methods; a handful is enough to illustrate it
set.seed(42)
res <- imputation_metrics(se, methods = c("min", "zero", "knn"),
                          plots = "ranking", verbose = FALSE)
res$metrics_table

# Two-stage combos can be compared alongside the individual methods
res2 <- imputation_metrics(se, methods = c("min", "knn"),
  combo_methods = list(
    "Impseq+min" = list(mar_method = "Impseq", mnar_method = "min")),
  plots = "ranking", verbose = FALSE)
res2$metrics_table$Method

Description

Complete imputation pipeline with 19 methods. Four pathways:

Usage

impute_proteomics(
  se,
  normalized_assay_name = "cycloess",
  imputed_assay_name = NULL,
  imp_method = "combo",
  mar_method = "Impseqrob",
  mnar_method = "min",
  prop_na_mnar = 0.51,
  prop_present_mar = 0.5,
  min_present_mar = 1,
  require_n_conditions = 1,
  max_na_prop = NULL,
  method_args = list(),
  with_value = NA_real_,
  verbose = TRUE
)

Arguments

Details

• imp_method = "none": no imputation

• imp_method = "combo": two-stage MAR+MNAR with binary classification

• imp_method = "softHybrid": sigmoid-weighted MAR+MNAR blend (continuous)

• Any other method: apply to all NAs (no MAR/MNAR distinction)

Value

List with:

• se: SummarizedExperiment with imputed assay added

• x_imputed: Raw imputed matrix (for direct export)

• prefilter_summary: Pre-filtering summary

• imputation_summary: Imputation statistics

• mnar_mask: MNAR mask matrix (combo only, NULL otherwise)

• mar_mask: MAR mask matrix (combo only, NULL otherwise)

Examples

data(nadia_dia)
norm <- normalize_proteomics(nadia_dia, norm_method = "cycloess",
                             verbose = FALSE)

# Default: two-stage combo, Impseqrob for MAR and min for MNAR
imp <- impute_proteomics(norm$se, normalized_assay_name = "cycloess",
                         verbose = FALSE)
SummarizedExperiment::assayNames(imp$se)
sum(is.na(SummarizedExperiment::assay(imp$se, "Impseqrob_min")))

# Any single method works too, and per-method options go in method_args
imp2 <- impute_proteomics(norm$se, normalized_assay_name = "cycloess",
                          imp_method = "knn",
                          method_args = list(knn = list(k = 15)),
                          verbose = FALSE)
SummarizedExperiment::assayNames(imp2$se)

Description

Converts DEPs_results (long format) into wide format with one adjP_* column per comparison, and computes sig_any.

Usage

merge_significance_info(
  feature_ids,
  DEPs_results,
  assay_name,
  alpha = 0.05,
  verbose = TRUE
)

Arguments

Value

DataFrame with FeatureID, adjP_*, sig_any

Description

The clustering is an optional extra step, so it is written separately: this adds it to a file that already holds the analysis, and refuses to create one from scratch.

Usage

nadia_add_pattern_profiler(
  file,
  pattern_profiler,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

The path, invisibly.

See Also

write_nadia()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    res <- process_proteomics(nadia_dia, verbose = FALSE)
    f <- file.path(tempdir(), "pp.nadia")
    write_nadia(f, nadia_dia, res, verbose = FALSE)

    # pp <- pattern_profiler_analysis(res$se_proc, res$DEPs_results)
    # nadia_add_pattern_profiler(f, pp)

    unlink(f)
}

Description

For querying the file directly with SQL or dplyr. Most users want read_nadia() instead; this is the way in when the file is larger than memory or when a specific query beats loading everything.

Usage

nadia_connect(file, read_only = TRUE)

Arguments

Details

The caller owns the connection and must close it with DBI::dbDisconnect(con, shutdown = TRUE).

Value

A DBI connection.

See Also

read_nadia(), nadia_tables()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    f <- file.path(tempdir(), "query.nadia")
    write_nadia(f, nadia_dia,
                process_proteomics(nadia_dia, verbose = FALSE),
                verbose = FALSE)

    con <- nadia_connect(f)
    DBI::dbGetQuery(con, "SELECT COUNT(*) AS n FROM proteins")
    DBI::dbDisconnect(con, shutdown = TRUE)

    unlink(f)
}

Description

The file's own answer to deps_with_clusters(). The join lives in the file as the view v_deps_pattern_profiler, so this reads a table rather than building one, and a client that is not R gets the same table from the same SQL. The filters are the ones deps_with_clusters() applies, and the two functions return identical results for the same arguments.

Usage

nadia_deps_with_clusters(
  db,
  assignment = c("primary", "all"),
  min_membership = NULL,
  comparison = NULL,
  significant_only = FALSE
)

Arguments

Details

The table is read on demand rather than by read_nadia(), because it is as long as the number of proteins times comparisons times clusters and there is no reason to carry it around unasked.

Value

A data frame with the columns of DEPs_results followed by Cluster, Membership and ClusterRank, or NULL if the file holds no differential-abundance results. A file with results but no clustering returns the same shape with the three cluster columns NA.

See Also

deps_with_clusters(), nadia_add_pattern_profiler()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    res <- process_proteomics(nadia_dia, verbose = FALSE)

    f <- file.path(tempdir(), "functional.nadia")
    write_nadia(f, nadia_dia, res, verbose = FALSE)

    head(nadia_deps_with_clusters(f))

    unlink(f)
}

Description

Output of preprocess_spectronaut() on a trimmed Spectronaut report, ready to feed process_proteomics() and the rest of the pipeline without having to read the source file again.

Usage

data(nadia_dia)

Format

An S3 object of class c("spectronaut_data", "proteomics_data", "list") with three elements:

metadata

Data frame of 12 rows and 7 columns, one row per injection: R.FileName, R.Condition, R.Replicate, Coding and the three identification counts reported by Spectronaut (R.PrecursorsIdentified, R.StrippedSequencesIdentified, R.ProteinGroupsIdentified).

protein_id

Data frame of 2,000 rows by 52 columns holding the identification information of every protein group.

protein_quant

Data frame of 2,000 rows by 44 columns: eight annotation columns plus, for each of the 12 samples, the number of precursors and of stripped sequences used for quantification and the intensity (⁠PG.Quantity_<condition>_<replicate>⁠).

Details

The data come from a quantitative proteomics experiment acquired on an Orbitrap Exploris at the Proteomics Facility of the Centro Nacional de Biotecnologia (CNB-CSIC) and processed with Spectronaut v20. The original experiment has 16 injections of the same digest split across four conditions (A-D) of four replicates each, and 10,437 protein groups.

So that the package examples run quickly, three conditions (A, B and D) and a random sample of 2,000 protein groups are kept. Three and not two conditions are retained because the soft-clustering in pattern_profiler_analysis() groups profiles across conditions, and with only two points per profile there is no pattern left to cluster.

The sample is drawn at random, with a fixed seed, rather than picking the best-covered proteins. That matters: 8.1 % of the intensities are missing and 72.2 % of the proteins are complete, closely matching the 7.9 % and 72.1 % of the full experiment. Selecting the most-quantified proteins instead would yield a dataset with no missing values at all, in which every imputation method returns the input unchanged, and in which 87 % of the proteins come out differentially expressed instead of the 31 % of the full data.

The full recipe is in system.file("scripts", "make_extdata.R", package = "NADIA"). The trimmed report this object is derived from is also distributed as a file, in system.file("extdata", "nadia_dia_report.tsv.gz", package = "NADIA"), so that preprocess_spectronaut() can be run end to end.

Source

Proteomics Facility, Centro Nacional de Biotecnologia (CNB-CSIC).

Examples

data(nadia_dia)
nadia_dia

# The three conditions and their four replicates
table(nadia_dia$metadata$R.Condition)

# Proteins and intensity columns
dim(nadia_dia$protein_quant)
grep("^PG.Quantity_", colnames(nadia_dia$protein_quant), value = TRUE)

# Missing values, which is what the package is about. A Spectronaut report is
# long, one row per run and protein group, and where a protein was not
# quantified the row is simply absent; the pivot to wide format is what turns
# those absences into NA.
quant <- as.matrix(nadia_dia$protein_quant[
  grep("^PG.Quantity_", colnames(nadia_dia$protein_quant))])
round(100 * mean(is.na(quant)), 1)

Description

A way out to an open, stable format. DuckDB reads its own files back a long way, but Parquet is the safer bet for something that has to be readable in ten years by software nobody has written yet, and it is what a repository will expect alongside a publication.

Usage

nadia_export_parquet(db, dir, views = TRUE, verbose = TRUE)

Arguments

Value

The paths written, invisibly.

See Also

read_nadia(), write_nadia()

Examples

if (requireNamespace("duckdb", quietly = TRUE) &&
    requireNamespace("arrow", quietly = TRUE)) {
    data(nadia_dia)
    f <- file.path(tempdir(), "export.nadia")
    write_nadia(f, nadia_dia, verbose = FALSE)

    out <- file.path(tempdir(), "nadia_parquet_export")
    nadia_export_parquet(f, out, verbose = FALSE)
    list.files(out)

    unlink(c(f, out), recursive = TRUE)
}

Description

Rebuild the Pattern Profiler table from a .nadia file

Usage

nadia_pattern_profiler(db)

Arguments

Value

The long_output data frame, ready for cluster_profile_highchart_list(), or NULL if the file holds no clustering.

See Also

read_nadia(), nadia_add_pattern_profiler()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    f <- file.path(tempdir(), "nopp.nadia")
    write_nadia(f, nadia_dia, verbose = FALSE)

    is.null(nadia_pattern_profiler(read_nadia(f)))

    unlink(f)
}

Description

Returns an object indistinguishable from what the ⁠preprocess_*()⁠ function that wrote the file produced – Spectronaut, DIA-NN, TMT or label-free – so it can be fed straight to process_proteomics() or to the table functions.

Usage

nadia_preprocessing(db)

Arguments

Value

A proteomics_data object with metadata, protein_id and protein_quant.

See Also

read_nadia(), nadia_result()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    f <- file.path(tempdir(), "pre.nadia")
    write_nadia(f, nadia_dia, verbose = FALSE)

    pre <- nadia_preprocessing(read_nadia(f))
    identical(pre$protein_id, nadia_dia$protein_id)

    unlink(f)
}

Description

Returns a proteomics_result with everything process_proteomics() returns, the SummarizedExperiment included, so that every plotting function in the package works from the file directly:

Usage

nadia_result(db)

Arguments

Details

db  <- read_nadia("experiment.nadia")
res <- nadia_result(db)
volcano_highchart_list(res$DEPs_results)
pca_highchart_list(res$PCA_Input)

Value

A proteomics_result object, or an error if the file holds only the preprocessing step.

See Also

read_nadia(), nadia_preprocessing()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    res <- process_proteomics(nadia_dia, verbose = FALSE)
    f <- file.path(tempdir(), "result.nadia")
    write_nadia(f, nadia_dia, res, verbose = FALSE)

    back <- nadia_result(read_nadia(f))
    identical(back$DEPs_results, res$DEPs_results)
    class(volcano_highchart_list(back$DEPs_results)[[1]])

    unlink(f)
}

Description

Returns the directory holding the agent skill that ships with NADIA. The skill documents the analysis pipeline for a coding assistant: which function to call at each stage, how to choose between the normalisation and imputation methods, what to verify afterwards, and the mistakes the package's defaults invite. It is plain Markdown, so any assistant can read it, and it follows the layout Claude expects for a skill: a SKILL.md entry point that points at the files under ⁠reference/⁠ and ⁠scripts/⁠.

Usage

nadia_skill_path(...)

Arguments

Details

To use it with Claude Code, copy the directory into the skills folder of a project (⁠.claude/skills/nadia/⁠) or of the user (⁠~/.claude/skills/nadia/⁠). The examples below print the command that does it.

Value

A single character string: the absolute path, or "" when the skill cannot be found, which is what system.file() returns for a missing file.

See Also

vignette("NADIA") for the same pipeline written for a person.

Examples

# Where the skill lives
nadia_skill_path()

# Its entry point, and the files it refers to
nadia_skill_path("SKILL.md")
list.files(nadia_skill_path(), recursive = TRUE)

# Install it for Claude Code, for the current user
cat(sprintf(
    "cp -R '%s' ~/.claude/skills/nadia",
    nadia_skill_path()
))

Description

List the contents of a .nadia file without loading it

Usage

nadia_tables(file)

Arguments

Value

A data frame with name, type (table or view) and rows.

See Also

read_nadia()

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
    data(nadia_dia)
    f <- file.path(tempdir(), "tables.nadia")
    write_nadia(f, nadia_dia, verbose = FALSE)

    nadia_tables(f)

    unlink(f)
}

Description

Convenience wrapper that extracts metadata and protein data from a proteomics_data object (from any of the preprocess_*() functions), performs zero-to-NA conversion, protein filtering, and returns a SE with assays "raw" and "log2" – ready for nm_run_normalizations() or normalization_metrics(..., methods = "all").

Usage

nm_prepare_se(
  preprocessing,
  min_reps = NULL,
  min_groups = 1,
  covariate_df = NULL,
  verbose = TRUE
)

Arguments

Details

Internally calls normalize_proteomics() with norm_method = "log2" (no additional normalization).

Value

SummarizedExperiment with assays "raw" and "log2".

Examples

data(nadia_dia)
se <- nm_prepare_se(nadia_dia, verbose = FALSE)
dim(se)
SummarizedExperiment::assayNames(se)

Description

Takes a SummarizedExperiment with a log2-scale assay and applies each requested normalization method, returning a new SE with one assay per method.

Usage

nm_run_normalizations(
  se,
  assay_name = "log2",
  methods = "all",
  method_args = list(),
  include_baseline = TRUE,
  verbose = TRUE
)

Arguments

Value

SummarizedExperiment with one assay per successfully normalized method (plus baseline if include_baseline = TRUE).

Examples

data(nadia_dia)
se <- nm_prepare_se(nadia_dia, verbose = FALSE)
se_bench <- nm_run_normalizations(se, methods = c("cycloess", "quantile", "MAD"),
                                  verbose = FALSE)
SummarizedExperiment::assayNames(se_bench)

Description

Calls all (or selected) ⁠nm_plot_*()⁠ functions on a SummarizedExperiment produced by import_norm_matrices(). Each plot is wrapped in tryCatch() so that a failure in one plot does not abort the entire run.

Usage

normalization_metrics(
  se,
  assay_names = NULL,
  condition_col = "Condition",
  plots = "all",
  cor_method = "pearson",
  pca_scales = c("free", "fixed", "both"),
  mds_scales = c("free", "fixed", "both"),
  methods = NULL,
  method_args = list(),
  base_assay = "log2",
  verbose = TRUE,
  output_dir = NULL,
  export_plots = TRUE,
  export_tables = TRUE,
  plot_width = 12,
  plot_height = 8,
  plot_dpi = 150
)

Arguments

Details

When methods is provided, the function first runs nm_run_normalizations() to automatically apply the requested normalization methods from the base_assay, then computes metrics and generates plots on the resulting multi-assay SE.

Value

Named list of ggplot objects (or NULL for failed plots), plus data.frames always computed regardless of plots selection: metrics_table (one row per method and metric), pc1_rank, mds1_rank, pcv_rank, pmad_rank, pev_rank, cor_rank, and final_rank (combined ranking as the mean of the five ranks Rank_PCV, Rank_PMAD, Rank_PEV, Rank_Cor and Rank_Sep; pc1_rank and mds1_rank are standalone diagnostics and do not enter it).

Reproducibility

Two columns use random numbers: Hopkins, which samples random reference points, and PERMANOVA_pval, which permutes the group labels. Both draw from the caller's RNG, so call set.seed() beforehand to reproduce them. Every other column is deterministic.

Examples

data(nadia_dia)
se <- nm_prepare_se(nadia_dia, verbose = FALSE)

# Auto-benchmark: normalize from the "log2" baseline, then score the methods
res <- normalization_metrics(se, methods = c("cycloess", "quantile", "MAD"),
                             plots = c("pcv", "final_ranking"), verbose = FALSE)
res$final_rank
res$pcv

Description

Complete normalization pipeline: zero-to-NA conversion, protein filtering by group presence, SummarizedExperiment creation, and normalization with the selected method. Output is always in log2 scale.

Usage

normalize_proteomics(
  data,
  metadata = NULL,
  min_reps = NULL,
  min_groups = 1,
  norm_method = "cycloess",
  cyclic_loess_method = c("fast", "pairs"),
  cyclic_loess_iterations = 3,
  cyclic_loess_span = 0.7,
  verbose = TRUE
)

Arguments

Value

List with:

• se: SummarizedExperiment with assays raw, log2, and <norm_method> (assays raw + log2 only when norm_method = "log2")

• filter_summary: Filtering summary

• na_overview: NA statistics

Examples

data(nadia_dia)

# The object returned by preprocess_*() is accepted directly
norm <- normalize_proteomics(nadia_dia, norm_method = "cycloess",
                             verbose = FALSE)
SummarizedExperiment::assayNames(norm$se)

# Zeros become NA and low-coverage proteins are filtered out
norm$filter_summary

# Any of the 13 methods can be used
norm2 <- normalize_proteomics(nadia_dia, norm_method = "quantile",
                              verbose = FALSE)
SummarizedExperiment::assayNames(norm2$se)

Description

Complete clustering pipeline starting from a SummarizedExperiment. Writes a parquet file in LONG format for visualisation.

Usage

pattern_profiler_analysis(
  se_proc,
  DEPs_results,
  assay_name = NULL,
  filter_mode = c("any", "all", "specific"),
  alpha = 0.05,
  comparison = NULL,
  condition_order = NULL,
  aggregate = c("median", "mean"),
  c_range = 2:10,
  auto_select_c = TRUE,
  c = NULL,
  selection_method = c("xb", "consensus", "elbow"),
  min_membership = 0.25,
  n_starts = 3L,
  output_file = NULL,
  verbose = TRUE
)

Arguments

Value

List (invisible) with the clustering results: optimal_c, m, conditions, feature counts, selection_metrics, cluster_counts, the Mfuzz cl object, the standardised eset_std and long_output, the long-format data.frame that is written when output_file is given.

Reproducibility

Fuzzy c-means starts from a random partition, so the cluster labels, the memberships and, with auto_select_c = TRUE, the chosen number of clusters depend on the caller's RNG. Call set.seed() immediately before the function to make a run reproducible on its own, whatever ran before it.

Examples

if (requireNamespace("Mfuzz", quietly = TRUE) &&
    requireNamespace("e1071", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)

  # auto_select_c = TRUE would cluster once per value of c_range
  set.seed(42)
  pp <- pattern_profiler_analysis(
    res$se_proc,
    DEPs_results    = res$DEPs_results,
    assay_name      = "Impseqrob_min",
    filter_mode     = "any",
    condition_order = c("A", "B", "D"),
    auto_select_c   = FALSE,
    c               = 3,
    verbose         = FALSE
  )
  print(pp$cluster_counts)
  print(head(pp$long_output))
}

Description

Generates PCA scatter plots (PC1 vs PC2) from a SummarizedExperiment assay, coloring points by different covariates. Useful for visually identifying batch effects or confounding.

Usage

pca_covariates_plot(
  se,
  assay_name = NULL,
  covariates,
  na_action = "complete",
  fill_value = -1,
  center = TRUE,
  scale. = TRUE,
  de_results = NULL,
  comparison = "any",
  alpha = 0.05,
  filter_samples = FALSE,
  condition_column = "Condition",
  point_size = 3,
  verbose = TRUE
)

Arguments

Details

Categorical covariates use a discrete color scale; numeric covariates use a continuous viridis gradient.

Value

Named list:

grid

ggplot2 facet_wrap with one panel per covariate

plots

Named list of individual ggplot2 objects per covariate

pca_summary

data.frame with PC1/PC2 variance explained

assay_name

Assay used

n_proteins

Number of proteins used

Examples

data(nadia_dia)

# nadia_dia has no batch information, so the example builds a plausible one:
# two digestion batches crossed with the three conditions.
cov <- data.frame(Column = nadia_dia$metadata$Coding,
                  Batch = rep(c("b1", "b2"),
                              length.out = nrow(nadia_dia$metadata)),
                  stringsAsFactors = FALSE)
res <- process_proteomics(nadia_dia, covariate_df = cov, verbose = FALSE)

# How the samples lay out in PCA space against each covariate
p <- pca_covariates_plot(res$se_proc, assay_name = "Impseqrob_min",
                         covariates = c("Condition", "Batch"))
names(p)

Description

Automatically builds PCA plots for "all", "any" and/or specific comparisons. Similar to factoextra::fviz_pca_ind with ellipse options.

Usage

pca_highchart_list(
  pca_input,
  modes = c("all", "any"),
  alpha = 0.05,
  color_by = "Condition",
  group_order = NULL,
  palette = NULL,
  addEllipses = TRUE,
  ellipse_type = c("convex", "confidence"),
  ellipse_level = 0.95,
  ellipse_fill_opacity = 0.12,
  ellipse_line_width = 1,
  ellipse_npoints = 100,
  point_size = 5,
  show_labels = FALSE,
  label_size = 10,
  center = TRUE,
  scale. = TRUE,
  filter_samples_to_comparison = FALSE
)

Arguments

Value

Named list of highchart objects

Examples

if (requireNamespace("highcharter", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)

  # One PCA over all proteins and one over the significant ones
  hc_pcas <- pca_highchart_list(
    res$PCA_Input,
    modes         = c("all", "any"),
    group_order   = c("A", "B", "D"),
    ellipse_type  = "confidence",
    ellipse_level = 0.95
  )
  names(hc_pcas)
}

Description

Prepare Long-Format Data for tidyHeatmap

Usage

prepare_heatmap_data(
  data,
  mode = c("all", "any", "target"),
  alpha = 0.05,
  comparison = NULL,
  feature_ids = NULL,
  scale_data = c("row", "none", "column"),
  sample_order = c("clustering", "condition", "custom"),
  condition_order = NULL
)

Arguments

Value

Data frame in long format, ready for tidyHeatmap

Description

Converts a DIA-NN protein-group matrix (report.pg_matrix.tsv, wide TSV format) into the same output structure as preprocess_spectronaut(): three data.frames (metadata, protein_id, protein_quant) ready for the downstream pipeline (process_proteomics() and the associated modules).

DIA-NN names its intensity columns after the raw file, which says nothing about the experimental design, so the design has to be declared. There are two ways: rename the columns to ⁠Abundance: <Condition>_<Replicate>⁠ as Proteome Discoverer writes them, or pass a sample sheet through annot_path. The design is never inferred from the raw-file name – a guess that happened to be right for one export would be wrong and silent for the next.

A protein-group matrix carries only intensities. The identification metrics the wide contract expects are filled from what DIA-NN does report (N.Sequences, N.Proteotypic.Sequences), left as NA where it reports nothing (the precursor counts), or omitted where nothing downstream needs them (coverage and the Spectronaut C-score).

Usage

preprocess_diann(
  file_path,
  condition_order,
  annot_path = NULL,
  export_dir = NULL,
  timestamp_suffix = TRUE,
  verbose = TRUE
)

Arguments

Value

A list with class c("diann_data", "proteomics_data", "list") containing:

metadata

Data frame with one record per run, including the number of protein groups quantified in each

protein_id

Data frame with the identification metrics per protein (wide format, the global metrics replicated per run)

protein_quant

Data frame with the quantification metrics per protein (includes ⁠PG.Quantity_<Coding>⁠)

The call that produced the object and a fingerprint of the file it was read from (path, size, modification time and MD5) travel with it as the attributes nadia_call and nadia_source. They are attributes rather than list elements so that the three-element structure above is unchanged; write_nadia() records them as the provenance of an analysis.

Examples

# A trimmed DIA-NN protein-group matrix ships with the package. Its run
# columns have been renamed to the "Abundance: <Condition>_<Replicate>"
# convention, so no further argument is needed.
report <- system.file("extdata", "nadia_diann_report.tsv.gz",
                      package = "NADIA")

diann <- preprocess_diann(report, condition_order = c("A", "B", "D"),
                          verbose = FALSE)
diann
table(diann$metadata$R.Condition)

# Straight from DIA-NN, where the columns are still raw-file paths, the
# design is given instead by a sheet whose 'Column' holds those paths:
# preprocess_diann("report.pg_matrix.tsv",
#                  condition_order = c("A", "B", "D"),
#                  annot_path = "design.tsv")

Description

Converts a Proteome Discoverer LFQ protein export (wide TSV format) into the same output structure as preprocess_spectronaut() / preprocess_tmt(): three data.frames (metadata, protein_id, protein_quant) ready for the downstream pipeline (process_proteomics()).

The experimental design comes from the ⁠Abundance: <Condition>_<Replicate>⁠ column suffixes, exactly as in preprocess_tmt() and preprocess_diann(). For a report whose columns are not named that way, annot_path takes a sample sheet instead.

The intensities (⁠Abundance: <sample>⁠) and the three per-sample metric families (⁠Score Mascot⁠, ⁠# PSMs (by Search Engine)⁠, ⁠# Peptides (by Search Engine)⁠) are mapped BY SAMPLE NAME, never by position: Proteome Discoverer writes the four families in different orders.

Usage

preprocess_lfq(
  file_path,
  annot_path = NULL,
  condition_order = NULL,
  export_dir = NULL,
  timestamp_suffix = TRUE,
  verbose = TRUE
)

Arguments

Value

A list with class c("lfq_data", "proteomics_data", "list") containing metadata, protein_id and protein_quant.

The call that produced the object and a fingerprint of the files it was read from – the report, and the sample sheet when there is one – (path, size, modification time and MD5) travel with it as the attributes nadia_call and nadia_source. They are attributes rather than list elements so that the three-element structure above is unchanged; write_nadia() records them as the provenance of an analysis.

Examples

# A trimmed Proteome Discoverer LFQ report ships with the package. Its columns
# follow the "Abundance: <Condition>_<Replicate>" convention, so the design
# needs no further argument.
report <- system.file("extdata", "nadia_lfq_report.tsv.gz", package = "NADIA")

lfq <- preprocess_lfq(report, verbose = FALSE)
lfq
lfq$metadata[, c("Coding", "R.Condition", "R.Replicate")]

# The same design, declared in a sheet instead. Use this route when the
# columns are not named by the convention; here it is the same experiment, so
# it produces the same sample table.
annot <- system.file("extdata", "nadia_lfq_annotation.tsv", package = "NADIA")
from_sheet <- preprocess_lfq(report, annot_path = annot, verbose = FALSE)
identical(from_sheet$metadata, lfq$metadata)

Description

Converts a SummarizedExperiment of protein intensities into the proteomics_data object that every NADIA reader returns. It is the way in for data imported with other Bioconductor tools, for instance one of the assays of a QFeatures object. process_proteomics() also accepts the SummarizedExperiment directly and calls this function; call it yourself to keep the object, for example to store it with write_nadia().

Usage

preprocess_se(
  se,
  condition_order = NULL,
  assay_name = NULL,
  log2_input = FALSE,
  condition_column = "Condition",
  replicate_column = "Replicate",
  verbose = TRUE
)

Arguments

Details

What is read from the object:

• Intensities: the assay assay_name, proteins in rows and samples in columns. With log2_input = TRUE the values are taken back to the linear scale, because NADIA applies the log2 transformation when it normalises. Zeros are treated as missing values, as for the other readers.

• Proteins: the row names, which must be present and unique. The gene names come from rowData()$Genes and the descriptions from rowData()$Description, when those columns exist.

• Design: the condition from colData()[[condition_column]] and the replicate from colData()[[replicate_column]]; without a replicate column the samples are numbered within each condition, in column order.

The samples are renamed ⁠<condition>_<replicate>⁠, the convention the rest of NADIA relies on, and the original column names are kept in metadata$R.FileName. Identification metrics (precursor or peptide counts, scores) are not read from rowData(), so those columns of the tables are left empty.

Value

An object of class c("se_data", "proteomics_data", "list") with the elements metadata, protein_id and protein_quant, like the other readers.

See Also

process_proteomics(), which accepts the SummarizedExperiment directly.

Examples

data(nadia_dia)
# A SummarizedExperiment built from the example data
quant <- as.matrix(nadia_dia$protein_quant[, grep("^PG\\.Quantity_",
                                                  names(nadia_dia$protein_quant))])
rownames(quant) <- nadia_dia$protein_quant$PG.ProteinGroups
se <- SummarizedExperiment::SummarizedExperiment(
  assays  = list(intensity = quant),
  colData = data.frame(Condition = nadia_dia$metadata$R.Condition,
                       Replicate = nadia_dia$metadata$R.Replicate),
  rowData = data.frame(Genes = nadia_dia$protein_quant$PG.Genes))

pre <- preprocess_se(se, verbose = FALSE)
pre

# The same values on the log2 scale
SummarizedExperiment::assay(se, "intensity") <- log2(quant)
pre_log2 <- preprocess_se(se, log2_input = TRUE, verbose = FALSE)

Description

Converts a Spectronaut report (long TSV format) into three structured tables: run metadata, protein identification and protein quantification.

The report has to carry the right columns, and rather than leave that to be reconstructed by hand the package ships the Spectronaut export schema that produces them:

system.file("extdata", "NADIA_Report.rs", package = "NADIA")

Import that file into Spectronaut as a report schema and export with it. The result has the shape of nadia_dia_report.tsv.gz, the example that ships alongside it.

Usage

preprocess_spectronaut(
  file_path,
  condition_order,
  export_dir = NULL,
  agg_coverage_run = c("max", "mean", "median", "min"),
  agg_coverage_global = c("max", "mean", "median", "min"),
  agg_mw = c("max", "mean", "median", "min"),
  agg_cscore_runwise = c("mean", "max", "median", "min"),
  timestamp_suffix = TRUE,
  verbose = TRUE
)

Arguments

Value

A list with class spectronaut_data containing:

metadata

Data frame with the run information (1 row per sample)

protein_id

Data frame with the identification metrics per protein

protein_quant

Data frame with the quantification metrics per protein

The call that produced the object and a fingerprint of the file it was read from (path, size, modification time and MD5) travel with it as the attributes nadia_call and nadia_source. They are attributes rather than list elements so that the three-element structure above is unchanged; write_nadia() records them as the provenance of an analysis.

Examples

# A trimmed Spectronaut report ships with the package
report <- system.file("extdata", "nadia_dia_report.tsv.gz", package = "NADIA")

prep <- preprocess_spectronaut(report,
                               condition_order = c("A", "B", "D"),
                               verbose = FALSE)
prep
dim(prep$protein_quant)

# Nothing is written to disk unless export_dir is given
prep <- preprocess_spectronaut(report,
                               condition_order = c("A", "B", "D"),
                               export_dir = tempdir(),
                               verbose = FALSE)

Description

Converts a Proteome Discoverer protein export (wide TSV format, with ⁠Abundance: <Condition>_<Replicate>⁠ columns) into the same output structure as preprocess_spectronaut(): three data.frames (metadata, protein_id, protein_quant) ready for the downstream pipeline (process_proteomics() and the associated modules).

The global PD identification metrics (⁠# PSMs⁠, ⁠# Peptides⁠, ⁠# Unique Peptides⁠, ⁠Coverage [%]⁠) are replicated into per-channel columns to fit the wide Spectronaut contract.

Usage

preprocess_tmt(
  file_path,
  condition_order,
  annot_path = NULL,
  export_dir = NULL,
  timestamp_suffix = TRUE,
  verbose = TRUE
)

Arguments

Value

A list with class c("tmt_data", "proteomics_data", "list") containing:

metadata

Data frame with one record per channel/sample

protein_id

Data frame with the identification metrics per protein (wide format, global metrics replicated per channel)

protein_quant

Data frame with the quantification metrics per protein (includes ⁠PG.Quantity_<Coding>⁠)

The call that produced the object and a fingerprint of the file it was read from (path, size, modification time and MD5) travel with it as the attributes nadia_call and nadia_source. They are attributes rather than list elements so that the three-element structure above is unchanged; write_nadia() records them as the provenance of an analysis.

Examples

# A trimmed Proteome Discoverer TMTpro report ships with the package: three
# conditions of eight replicates, split across two TMT mixes (replicates 1-4
# are the first mix, 5-8 the second) and bridged by four "IS" channels.
report <- system.file("extdata", "nadia_tmt_report.tsv.gz", package = "NADIA")

# condition_order is required, and doubles as a filter: the report also holds
# an "IS" channel (internal standards) that is left out by not listing it
tmt <- preprocess_tmt(report,
                      condition_order = c("A", "B", "D"),
                      verbose = FALSE)
tmt
table(tmt$metadata$R.Condition)

Description

Reports the number of runs, protein groups and conditions, so that the shape of the experiment can be checked at a glance before processing it.

Usage

## S3 method for class 'diann_data'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints.

Examples

diann <- preprocess_diann(
  system.file("extdata", "nadia_diann_report.tsv.gz", package = "NADIA"),
  condition_order = c("A", "B", "D"),
  verbose = FALSE)
print(diann)

Description

Reports the number of samples, protein groups and conditions, so that the shape of the experiment can be checked at a glance before processing it.

Usage

## S3 method for class 'lfq_data'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints.

Examples

lfq <- preprocess_lfq(
  system.file("extdata", "nadia_lfq_report.tsv.gz", package = "NADIA"),
  annot_path = system.file("extdata", "nadia_lfq_annotation.tsv",
                           package = "NADIA"),
  verbose = FALSE)
print(lfq)

Description

Print a summary of a .nadia file

Usage

## S3 method for class 'nadia_db'
print(x, ...)

Arguments

Value

x, invisibly.

Description

Renders the object built by proteomics_heatmap() on the current graphics device, adding the title stored in the object. Printing is what actually draws the heatmap: building it does not.

Usage

## S3 method for class 'proteomics_heatmap'
print(x, ...)

Arguments

Value

The drawn HeatmapList, invisibly. Called for its side effect.

Examples

if (requireNamespace("ComplexHeatmap", quietly = TRUE) &&
    requireNamespace("tidyHeatmap", quietly = TRUE) &&
    requireNamespace("circlize", quietly = TRUE)) {
  data(nadia_dia)
  res <- process_proteomics(nadia_dia, verbose = FALSE)
  hm <- proteomics_heatmap(res$PCA_Input, mode = "any")

  # Drawing needs a graphics device; send it to a temporary file
  f <- tempfile(fileext = ".png")
  grDevices::png(f)
  print(hm)
  grDevices::dev.off()
  file.remove(f)
}

Description

Print method for proteomics_result

Usage

## S3 method for class 'proteomics_result'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints: the assays of the SummarizedExperiment, the comparisons performed, the number of differential proteins and the parameters used.

Examples

data(nadia_dia)
res <- process_proteomics(nadia_dia, verbose = FALSE)
print(res)

Description

Print a Summary of Data Imported from a SummarizedExperiment

Usage

## S3 method for class 'se_data'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints.

Examples

data(nadia_dia)
quant <- as.matrix(nadia_dia$protein_quant[, grep("^PG\\.Quantity_",
                                                  names(nadia_dia$protein_quant))])
rownames(quant) <- nadia_dia$protein_quant$PG.ProteinGroups
se <- SummarizedExperiment::SummarizedExperiment(
  assays  = list(intensity = quant),
  colData = data.frame(Condition = nadia_dia$metadata$R.Condition))
print(preprocess_se(se, verbose = FALSE))

Description

Reports the number of runs, protein groups and conditions, so that the shape of the experiment can be checked at a glance before processing it.

Usage

## S3 method for class 'spectronaut_data'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints.

Examples

data(nadia_dia)
print(nadia_dia)

Description

Reports the number of channels, protein groups and conditions, so that the shape of the experiment can be checked at a glance before processing it.

Usage

## S3 method for class 'tmt_data'
print(x, ...)

Arguments

Value

x, invisibly. Called for the summary it prints.

Examples

tmt <- preprocess_tmt(
  system.file("extdata", "nadia_tmt_report.tsv.gz", package = "NADIA"),
  condition_order = c("A", "B", "D"),
  verbose = FALSE)
print(tmt)

Description

Complete processing pipeline: filtering, normalization, imputation and differential expression analysis. Coordinates sub-modules Normalization.R, Imputation.R, and DEAnalysis.R.

Usage

process_proteomics(
  preprocessing,
  export_dir = NULL,
  min_reps_filter = NULL,
  min_groups_filter = 1,
  norm_method = "cycloess",
  cyclic_loess_method = "fast",
  cyclic_loess_iterations = 3,
  cyclic_loess_span = 0.7,
  batch_correct = FALSE,
  batch_column = "Batch",
  batch_algorithm = "ComBat",
  batch_ComBat_mode = 1,
  batch_covariates = NULL,
  batch_qualitycontrol = FALSE,
  imp_method = "combo",
  mar_method = "Impseqrob",
  mnar_method = "min",
  prop_na_mnar = 0.51,
  prop_present_mar = 0.5,
  min_present_mar = 1,
  require_n_conditions = 1,
  max_na_prop = NULL,
  method_args = list(),
  with_value = NA_real_,
  comparisons = NULL,
  control = NULL,
  logFC_threshold = 0,
  alpha = 0.05,
  eBayes_trend = NULL,
  eBayes_robust = NULL,
  de_method = "limma",
  covariate_df = NULL,
  covariate_column = NULL,
  bio_replicate_column = NULL,
  export_normalized = TRUE,
  export_imputed = TRUE,
  export_format = "tsv",
  export_volcano = TRUE,
  export_boxplot = TRUE,
  export_pca = TRUE,
  assay_name = NULL,
  log2_input = FALSE,
  verbose = TRUE
)

Arguments

Details

The input is a proteomics_data object, which every preprocessing function returns with the same three elements, so the pipeline is indifferent to the acquisition and the search engine the data came from. A SummarizedExperiment is also accepted, for data imported with other tools: it is converted by preprocess_se(), with assay_name and log2_input.

Value

List of class proteomics_result with:

• se_proc: Processed SummarizedExperiment with all assays

• DEPs_results: Data frame with differential expression results

• BoxPlot_Input: Long-format data frame with one row per protein, sample and assay (columns Column, Assay, Intensity, Condition, Replicate, Protein.IDs). Feed it to boxplot_highchart_list().

• PCA_Input: Long-format data frame with the imputed intensities plus one adjP_* column per comparison and a sig_any flag. Feed it to pca_highchart_list(), proteomics_heatmap() or proteomics_heatmap_list().

• comparisons: Comparisons performed

• parameters: Parameters used

BoxPlot_Input and PCA_Input are always returned, whether or not export_dir is given: the plotting layer needs them, and requiring a round trip through disk to obtain them would be gratuitous.

Examples

data(nadia_dia)

# Normalization, imputation and differential expression in one call
res <- process_proteomics(nadia_dia, verbose = FALSE)
res

SummarizedExperiment::assayNames(res$se_proc)
table(res$DEPs_results$Comparison, res$DEPs_results$Change)

# The plotting layer is fed straight from the result, no files involved
names(res$BoxPlot_Input)
names(res$PCA_Input)

# Another combination: quantile normalization and a single imputation method
res2 <- process_proteomics(nadia_dia, norm_method = "quantile",
                           imp_method = "QRILC", verbose = FALSE)
SummarizedExperiment::assayNames(res2$se_proc)

Description

Builds a reactable table with 2-level grouped headers, static columns pinned (sticky) to the left and data bars coloured by condition inside each numeric cell. It reproduces the usual Excel layout and improves on it.

Usage

protein_list_reactable(
  data,
  metadata = NULL,
  page_size = 15,
  height = 720,
  element_id = NULL,
  selection = NULL,
  searchable = TRUE
)

Arguments

Value

A reactable object.

Examples

if (requireNamespace("reactable", quietly = TRUE)) {
  data(nadia_dia)

  # metadata$Coding fixes the order of the sample columns
  tbl <- protein_list_reactable(nadia_dia$protein_id,
                                metadata = nadia_dia$metadata)
  class(tbl)
}