Package 'proBatch'

Description

Ensures the [ method returns a ProBatchFeatures instance so the subclass-specific slots remain available after subsetting.

Usage

## S4 method for signature 'ProBatchFeatures,ANY,ANY,ANY'
x[i, j, k, ..., drop = TRUE]

Arguments

Value

A ProBatchFeatures object containing the requested subset.

Description

Wraps an existing QFeatures instance into the ProBatchFeatures subclass, initializing the operation log and optional assay renaming when a single assay is present.

Usage

as_ProBatchFeatures(
  object,
  level = "feature",
  pipeline = "raw",
  sample_id_name = NULL
)

Arguments

Value

A ProBatchFeatures object containing the same assays as object.

Examples

if (requireNamespace("QFeatures", quietly = TRUE)) {
    data(example_proteome_matrix, package = "proBatch")
    data(example_sample_annotation, package = "proBatch")
    sample_order <- match(
        colnames(example_proteome_matrix),
        example_sample_annotation$FullRunName
    )
    cd <- S4Vectors::DataFrame(
        example_sample_annotation[sample_order, , drop = FALSE]
    )
    rownames(cd) <- colnames(example_proteome_matrix)
    se <- SummarizedExperiment::SummarizedExperiment(
        assays = list(intensity = example_proteome_matrix),
        colData = cd
    )
    qf <- QFeatures::QFeatures(
        experiments = list(peptideRaw = se),
        colData = cd
    )
    as_ProBatchFeatures(qf, level = "peptide")
}

Description

Calculate CV distribution for each feature

Usage

calculate_feature_CV(
  df_long,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  batch_col = NULL,
  biospecimen_id_col = NULL,
  unlog = TRUE,
  log_base = 2,
  offset = 0,
  pbf_name = NULL
)

Arguments

Value

data frame with replicate-level CV values:

• CV_total: per feature_id_col and biospecimen_id_col (and per Step, if present),

• CV_perBatch: additionally stratified by batch_col when provided.

Examples

data(
    list = c("example_sample_annotation", "example_proteome"),
    package = "proBatch"
)
CV_df <- calculate_feature_CV(example_proteome,
    sample_annotation = example_sample_annotation,
    measure_col = "Intensity",
    batch_col = "MS_batch",
    biospecimen_id_col = "EarTag"
)

Description

Calculate peptide correlation between and within peptides of one protein

Usage

calculate_peptide_corr_distr(
  data_matrix,
  peptide_annotation,
  protein_col = "ProteinName",
  feature_id_col = "peptide_group_label",
  pbf_name = NULL
)

Arguments

Value

dataframe with peptide correlation coefficients that are suggested to use for plotting in plot_peptide_corr_distribution as plot_param:

Examples

data(
    list = c("example_peptide_annotation", "example_proteome_matrix"),
    package = "proBatch"
)
selected_genes <- c("BOVINE_A1ag", "BOVINE_FetuinB", "Cyfip1")
gene_filter <- example_peptide_annotation$Gene %in% selected_genes
peptides_ann <- example_peptide_annotation$peptide_group_label
selected_peptides <- peptides_ann[gene_filter]
matrix_test <- example_proteome_matrix[selected_peptides, ]
pep_annotation_sel <- example_peptide_annotation[gene_filter, ]
corr_distribution <- calculate_peptide_corr_distr(matrix_test,
    pep_annotation_sel,
    protein_col = "Gene"
)

Description

Calculate variance distribution by variable

Usage

## Default S3 method:
calculate_PVCA(
  data_matrix,
  sample_annotation,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  factors_for_PVCA = c("MS_batch", "digestion_batch", "Diet", "Sex", "Strain"),
  pca_threshold = 0.6,
  variance_threshold = 0.01,
  fill_the_missing = -1,
  ...
)

## S3 method for class 'ProBatchFeatures'
calculate_PVCA(
  data_matrix,
  pbf_name = NULL,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  ...
)

Arguments

Value

For matrix input, a data frame of Principal Variance Component weights. For ProBatchFeatures input, one selected assay returns that data frame and multiple assays return a named list of data frames.

Examples

data(
    list = c("example_proteome_matrix", "example_sample_annotation"),
    package = "proBatch"
)
matrix_test <- na.omit(example_proteome_matrix)[1:50, ]
pvca_df <- calculate_PVCA(matrix_test, example_sample_annotation,
    factors_for_PVCA = c(
        "MS_batch", "digestion_batch", "Diet", "Sex", "Strain"
    ),
    pca_threshold = .6, variance_threshold = .01, fill_the_missing = -1
)

Description

Calculates correlation for all pairs of the samples in data matrix, labels as replicated/same_batch/unrelated in output columns (see "Value").

Usage

calculate_sample_corr_distr(
  data_matrix,
  sample_annotation,
  repeated_samples = NULL,
  biospecimen_id_col = "EarTag",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  pbf_name = NULL
)

Arguments

Value

dataframe with the following columns, that are suggested to use for plotting in plot_sample_corr_distribution as plot_param:

1. replicate

2. batch_the_same

3. batch_replicate

4. batches

other columns are:

1. sample_id_1 & sample_id_2, both generated from sample_id_col variable

2. correlation - correlation of two corresponding samples

3. batch_1 & batch_2 or analogous, created the same as sample_id_1

Examples

data(
    list = c("example_sample_annotation", "example_proteome_matrix"),
    package = "proBatch"
)
corr_distribution <- calculate_sample_corr_distr(
    data_matrix = example_proteome_matrix,
    sample_annotation = example_sample_annotation,
    batch_col = "MS_batch", biospecimen_id_col = "EarTag"
)

Description

Centers each feature within each batch to the global location (median/mean) of that feature. Works for long-data frames and wide matrices.

Usage

center_feature_batch(
  x,
  sample_annotation = NULL,
  format = c("long", "wide"),
  stat = c("medians", "means"),
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL
)

Arguments

Details

For "wide", conversion uses matrix_to_long() / long_to_matrix(). For "long", the function adds "preBatchCorr_[measure_col]" and the diagnostic columns:

• for medians: median_batch, median_global, diff_medians

• for means: mean_batch, mean_global, diff_means

Value

If format = "long", a data.frame; if format = "wide", a matrix.

Examples

# LONG
# Load necessary datasets
data(
    list = c("example_sample_annotation", "example_proteome"),
    package = "proBatch"
)
out_long <- center_feature_batch(
    x = example_proteome, sample_annotation = example_sample_annotation,
    format = "long", stat = "medians",
    sample_id_col = "FullRunName", batch_col = "MS_batch",
    feature_id_col = "peptide_group_label", measure_col = "Intensity",
    no_fit_imputed = FALSE
)

# WIDE
data(example_proteome_matrix, package = "proBatch")
out_wide <- center_feature_batch(
    x = example_proteome_matrix,
    sample_annotation = example_sample_annotation,
    format = "wide", stat = "means",
    sample_id_col = "FullRunName", batch_col = "MS_batch",
    feature_id_col = "peptide_group_label", measure_col = "Intensity",
    no_fit_imputed = FALSE
)

Description

Use center_feature_batch() with ⁠format="long", stat="means"⁠.

Usage

center_feature_batch_means_df(
  df_long,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL
)

Arguments

Value

A data.frame in long format with batch-corrected values in measure_col and original values preserved in preBatchCorr_[measure_col].

Examples

# Use the unified replacement with `format = "long"` and `stat = "means"`.
args(center_feature_batch)

Description

Use center_feature_batch() with ⁠format="wide", stat="means"⁠.

Usage

center_feature_batch_means_dm(
  data_matrix,
  sample_annotation,
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity"
)

Arguments

Value

A numeric matrix of batch-corrected values (features $\times$ samples).

Examples

# Use the unified replacement with `format = "wide"` and `stat = "means"`.
args(center_feature_batch)

Description

Use center_feature_batch() with ⁠format="long", stat="medians"⁠.

Usage

center_feature_batch_medians_df(
  df_long,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL
)

Arguments

Value

A data.frame in long format with batch-corrected values in measure_col and original values preserved in preBatchCorr_[measure_col].

Examples

# Use the unified replacement with `format = "long"` and `stat = "medians"`.
args(center_feature_batch)

Description

Use center_feature_batch() with ⁠format="wide", stat="medians"⁠.

Usage

center_feature_batch_medians_dm(
  data_matrix,
  sample_annotation,
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity"
)

Arguments

Value

A numeric matrix of batch-corrected values (features $\times$ samples).

Examples

# Use the unified replacement with `format = "wide"` and `stat = "medians"`.
args(center_feature_batch)

Description

Check if sample annotation is consistent with data matrix and join the two

Usage

check_sample_consistency(
  sample_annotation,
  sample_id_col,
  df_long,
  batch_col = NULL,
  order_col = NULL,
  facet_col = NULL,
  merge = TRUE
)

Arguments

Value

'df_long'. When 'sample_annotation' is supplied and 'merge = TRUE', it is inner-joined to 'df_long' by the applicable annotation columns, so only intersecting sample identifiers remain. When 'merge = FALSE' or 'sample_annotation = NULL', 'df_long' is returned without merging.

Examples

# Load necessary datasets
data(
    list = c("example_proteome", "example_sample_annotation"),
    package = "proBatch"
)

df_test <- check_sample_consistency(
    sample_annotation = example_sample_annotation,
    df_long = example_proteome, sample_id_col = "FullRunName",
    batch_col = NULL, order_col = NULL, facet_col = NULL
)

Description

Convert specified factor columns to factor type and numeric columns to numeric.

Usage

convert_annotation_classes(df, factor_columns, numeric_columns)

Arguments

Value

data frame with converted columns.

Examples

annotation <- data.frame(
    batch = c("A", "B"),
    injection_order = c("1", "2")
)
converted <- convert_annotation_classes(
    annotation,
    factor_columns = "batch",
    numeric_columns = "injection_order"
)
vapply(converted, class, character(1))

Description

Batch correction of normalized data to bring each feature within each batch to a comparable scale. The following methods are available:

1. Per-feature centering by median/mean: center_feature_batch() — unified API for long ("long") and wide ("wide") data via format, and for medians/means via stat. Deprecated wrappers: center_feature_batch_medians_df(), center_feature_batch_means_df(), center_feature_batch_medians_dm(), center_feature_batch_means_dm() now forward to center_feature_batch() and emit deprecation warnings.

2. Discrete batch correction with ComBat: correct_with_ComBat() adjusts for discrete batch effects using parametric or non-parametric empirical Bayes (Johnson et al., 2007). Missing data: ComBat requires an NA-free matrix. If your data contain missing values, use fill_the_missing = "drop_features" to drop NA-containing features or fill_the_missing = "fill" with an explicit fill_value to impute before calling ComBat.

3. Linear batch correction with limma: correct_with_removeBatchEffect() removes linear batch effects via limma::removeBatchEffect. Missing data: NA values in the expression/intensity matrix are allowed; the design matrix (batch/covariates) must be free of missing values.

4. Continuous drift correction: adjust_batch_trend_df() fits and removes within-batch trends (e.g., LOESS) and is typically followed by a discrete adjustment such as center_feature_batch(), correct_with_ComBat(), or correct_with_removeBatchEffect().

Alternatively, use the wrapper correct_batch_effects() to combine continuous and/or discrete corrections in one call.

Adjust batch signal trend with the custom (continuous) fit. Should be followed by discrete corrections, e.g. center_feature_batch() or correct_with_ComBat(). Available for both long format data frame (adjust_batch_trend_df()) and data matrix (adjust_batch_trend_dm()).

Optional continuous drift removal + discrete adjustment via "MedianCentering", "MeanCentering", "ComBat", or "removeBatchEffect". Works for long or wide via format.

Usage

adjust_batch_trend_dm(
  data_matrix,
  sample_annotation,
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  order_col = "order",
  fit_func = "loess_regression",
  return_fit_df = TRUE,
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  min_measurements = 8,
  ...
)

adjust_batch_trend_df(
  df_long,
  sample_annotation = NULL,
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  order_col = "order",
  keep_all = "default",
  fit_func = "loess_regression",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  min_measurements = 8,
  ...
)

correct_batch_effects(
  x,
  sample_annotation,
  format = c("long", "wide"),
  continuous_func = NULL,
  discrete_func = c("MedianCentering", "MeanCentering", "ComBat", "removeBatchEffect"),
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  order_col = "order",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  fill_the_missing = "error",
  par.prior = TRUE,
  covariates_cols = NULL,
  min_measurements = 8,
  ...,
  fill_value = NULL
)

Arguments

Value

Returns data in the same format as input (data_matrix or df_long). For long-format discrete correction, original values from measure_col are preserved in "preBatchCorr_[measure_col]"; trend adjustment instead uses "preTrendFit_[measure_col]". Corrected values are written to measure_col.

The function adjust_batch_trend_dm(), if return_fit_df = TRUE, returns a list with:

1. corrected_dm — corrected data matrix

2. fit_df — data frame to inspect fitted curves

References

Johnson WE, Li C, Rabinovic A (2007). Adjusting batch effects in microarray expression data using empirical Bayes methods. Biostatistics 8(1):118–127. Smyth GK (2025). limma User's Guide, Bioconductor (see removeBatchEffect / lmFit). Leek JT et al. (2024). sva vignette, Bioconductor.

See Also

center_feature_batch, adjust_batch_trend_df, adjust_batch_trend_dm, correct_with_ComBat, correct_with_removeBatchEffect, correct_batch_effects

fit_nonlinear, plot_with_fitting_curve

Examples

data(
    list = c("example_sample_annotation", "example_proteome"),
    package = "proBatch"
)
test_peptides <- unique(example_proteome$peptide_group_label)[1:3]
test_df <- subset(example_proteome, peptide_group_label %in% test_peptides)

# 1) Per-feature median centering
median_centered_df <- center_feature_batch(
    x = test_df,
    sample_annotation = example_sample_annotation,
    format = "long",
    stat = "medians",
    no_fit_imputed = FALSE
)

# 2) ComBat (discrete) — drop NA features first if needed
combat_corrected_df <- correct_with_ComBat(
    x = test_df,
    sample_annotation = example_sample_annotation,
    format = "long",
    fill_the_missing = "drop_features",
    no_fit_imputed = FALSE
)

# 3) Continuous drift correction (LOESS), then discrete centering if desired
adjusted_df <- adjust_batch_trend_df(
    df_long = test_df,
    sample_annotation = example_sample_annotation,
    span = 0.7, min_measurements = 8,
    no_fit_imputed = FALSE
)
plot_fit <- plot_with_fitting_curve(
    unique(adjusted_df$peptide_group_label),
    df_long = adjusted_df,
    measure_col = "preTrendFit_Intensity",
    fit_df = adjusted_df,
    sample_annotation = example_sample_annotation
)

# 4) One-call wrapper (continuous + discrete)
batch_corrected_df <- correct_batch_effects(
    x = test_df, sample_annotation = example_sample_annotation,
    format = "long",
    continuous_func = "loess_regression",
    discrete_func = "MedianCentering",
    batch_col = "MS_batch",
    fill_the_missing = "keep",
    no_fit_imputed = FALSE,
    span = 0.7, min_measurements = 8
)

Description

Use correct_batch_effects() with format="long".

Usage

correct_batch_effects_df(
  df_long,
  sample_annotation,
  continuous_func = NULL,
  discrete_func = c("MedianCentering", "MeanCentering", "ComBat", "removeBatchEffect"),
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  order_col = "order",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  fill_the_missing = "error",
  par.prior = TRUE,
  covariates_cols = NULL,
  min_measurements = 8,
  ...,
  fill_value = NULL
)

Arguments

Value

A data.frame in long format with batch-corrected values in measure_col.

Examples

# Use the unified replacement with `format = "long"`.
args(correct_batch_effects)

Description

Use correct_batch_effects() with format="wide".

Usage

correct_batch_effects_dm(
  data_matrix,
  sample_annotation,
  continuous_func = NULL,
  discrete_func = c("MedianCentering", "MeanCentering", "ComBat", "removeBatchEffect"),
  batch_col = "MS_batch",
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  order_col = "order",
  min_measurements = 8,
  no_fit_imputed = TRUE,
  fill_the_missing = "error",
  par.prior = TRUE,
  covariates_cols = NULL,
  ...,
  fill_value = NULL
)

Arguments

Value

A numeric matrix of batch-corrected values (features $\times$ samples).

Examples

# Use the unified replacement with `format = "wide"`.
args(correct_batch_effects)

Description

Adjusts for discrete batch effects using ComBat. Works for long-format data frames and wide matrices via format. Optionally accepts covariates through covariates_cols (passed as mod).

Usage

correct_with_ComBat(
  x,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  format = c("long", "wide"),
  par.prior = TRUE,
  covariates_cols = NULL,
  fill_the_missing = "error",
  keep_all = "default",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  ...,
  fill_value = NULL
)

Arguments

Value

Matrix if format="wide", data.frame if format="long".

References

Johnson WE et al. (2007) Biostatistics 8(1):118–127; sva vignette.

Examples

data(
    list = c("example_sample_annotation", "example_proteome"),
    package = "proBatch"
)
feature_ids <- c(
    "10062_NVGVSFYADKPEVTQEQK_3",
    "10063_NVGVSFYADKPEVTQEQKK_3"
)
example_subset <- example_proteome[
    example_proteome$peptide_group_label %in% feature_ids,
]
combat_corrected <- correct_with_ComBat(
    x = example_subset,
    sample_annotation = example_sample_annotation,
    format = "long",
    fill_the_missing = "error"
)

Description

Use correct_with_ComBat() with format="long".

Usage

correct_with_ComBat_df(
  df_long,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  par.prior = TRUE,
  fill_the_missing = "error",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = NULL,
  keep_all = "default",
  covariates_cols = NULL,
  ...,
  fill_value = NULL
)

Arguments

Value

A data.frame in long format with ComBat-corrected values in measure_col and original values preserved in preBatchCorr_[measure_col].

Examples

# Use the unified replacement with `format = "long"`.
args(correct_with_ComBat)

Description

Use correct_with_ComBat() with format="wide".

Usage

correct_with_ComBat_dm(
  data_matrix,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  par.prior = TRUE,
  fill_the_missing = "error",
  covariates_cols = NULL,
  ...,
  fill_value = NULL
)

Arguments

Value

A numeric matrix of ComBat-corrected values (features $\times$ samples).

Examples

# Use the unified replacement with `format = "wide"`.
args(correct_with_ComBat)

Description

Removes batch-associated linear effects with removeBatchEffect from limma. Works for long or wide via format. Use covariates_cols to keep biological effects in the design (not removed).

Usage

correct_with_removeBatchEffect(
  x,
  sample_annotation,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  format = c("long", "wide"),
  covariates_cols = NULL,
  fill_the_missing = "error",
  keep_all = "default",
  ...,
  fill_value = NULL
)

Arguments

Value

Matrix if format="wide", data.frame if format="long" with batch effects removed

See Also

removeBatchEffect

Examples

data(
    list = c("example_sample_annotation", "example_proteome_matrix"),
    package = "proBatch"
)
batch_corrected_matrix <- correct_with_removeBatchEffect(
    example_proteome_matrix,
    example_sample_annotation,
    format = "wide",
    batch_col = "MS_batch",
    covariates_cols = c("Diet", "Sex"),
    fill_the_missing = "drop_features"
)

Description

Use correct_with_removeBatchEffect() with format="long".

Usage

correct_with_removeBatchEffect_df(
  df_long,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  covariates_cols = NULL,
  fill_the_missing = "error",
  keep_all = "default",
  ...,
  fill_value = NULL
)

Arguments

Value

A data.frame in long format with batch effects removed in measure_col.

Examples

# Use the unified replacement with `format = "long"`.
args(correct_with_removeBatchEffect)

Description

Use correct_with_removeBatchEffect() with format="wide".

Usage

correct_with_removeBatchEffect_dm(
  data_matrix,
  sample_annotation,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  batch_col = "MS_batch",
  covariates_cols = NULL,
  fill_the_missing = "error",
  ...,
  fill_value = NULL
)

Arguments

Value

A numeric matrix with batch effects removed (features $\times$ samples).

See Also

removeBatchEffect

Examples

data(
    list = c("example_sample_annotation", "example_proteome_matrix"),
    package = "proBatch"
)
example_proteome_small <- example_proteome_matrix[1:100, ]
batch_corrected_matrix <- correct_with_removeBatchEffect(
    example_proteome_small,
    example_sample_annotation,
    format = "wide",
    batch_col = "MS_batch",
    covariates_cols = c("Diet", "Sex"),
    fill_the_missing = "drop_features"
)

Description

Create light-weight peptide annotation data frame for selection of illustrative proteins

Usage

create_peptide_annotation(
  df_long,
  feature_id_col = "peptide_group_label",
  protein_col = c("ProteinName", "Gene")
)

Arguments

Value

data frame containing peptide annotations

See Also

plot_peptides_of_one_protein, plot_protein_corrplot

Examples

data("example_proteome", package = "proBatch")
generated_peptide_annotation <- create_peptide_annotation(
    example_proteome,
    feature_id_col = "peptide_group_label",
    protein_col = c("Protein")
)

Description

Converts date/time columns for sample_annotation to POSIXct format and calculates sample run rank in order column

Usage

date_to_sample_order(
  sample_annotation,
  time_column = c("RunDate", "RunTime"),
  new_time_column = "DateTime",
  dateTimeFormat = c("%b_%d", "%H:%M:%S"),
  new_order_col = "order",
  instrument_col = "instrument"
)

Arguments

Value

sample annotation file with a new column new_time_column with POSIX-formatted date & new_order_col used in some diagnostic plots (e.g. plot_iRT, plot_sample_mean)

Examples

data("example_sample_annotation", package = "proBatch")
sample_annotation_wOrder <- date_to_sample_order(
    example_sample_annotation,
    time_column = c("RunDate", "RunTime"),
    new_time_column = "new_DateTime",
    dateTimeFormat = c("%b_%d", "%H:%M:%S"),
    new_order_col = "new_order",
    instrument_col = NULL
)

Description

convert date/time column of sample_annotation to POSIX format required to keep number-like behavior

Usage

dates_to_posix(
  sample_annotation,
  time_column = c("RunDate", "RunTime"),
  new_time_column = "DateTime",
  dateTimeFormat = c("%b_%d", "%H:%M:%S"),
  tz = "GMT",
  locale = "en_US.UTF-8"
)

Arguments

Value

sample annotation file with a new column new_time_column with POSIX-formatted date

Examples

data("example_sample_annotation", package = "proBatch")
date_to_posix <- dates_to_posix(example_sample_annotation,
    time_column = c("RunDate", "RunTime"),
    new_time_column = "DateTime_new",
    dateTimeFormat = c("%b_%d", "%H:%M:%S")
)

Description

Defining sample order internally

Usage

define_sample_order(
  order_col,
  sample_annotation,
  facet_col,
  batch_col,
  df_long,
  sample_id_col,
  color_by_batch
)

Arguments

Value

list of two items: order_col new name and new df_long

See Also

plot_sample_mean_or_boxplot, feature_level_diagnostics

Examples

data(
    list = c("example_proteome", "example_sample_annotation"),
    package = "proBatch"
)
sample_order <- define_sample_order(
    order_col = "order",
    sample_annotation = example_sample_annotation,
    facet_col = NULL, batch_col = "MS_batch", df_long = example_proteome,
    sample_id_col = "FullRunName", color_by_batch = TRUE
)
new_order_col <- sample_order$order_col
df_long <- sample_order$df_long

Description

Detect nested batch variables

Usage

detect_nested_batches(sample_annotation, batch_cols)

Arguments

Value

A list with adjacency matrix of nesting relations (parent -> child), edge list, equivalent (bijective) partitions, topological ordering (if acyclic), and suggestions. The object has class "pb_nested_batches".

Examples

data("example_ecoli_data", package = "proBatch")
meta <- example_ecoli_data$all_metadata
detect_nested_batches(meta, batch_cols = c("Lab", "Condition"))

Description

Detect outlier samples in PCA space

Usage

detect_outlier_samples(
  data_matrix,
  sample_annotation = NULL,
  batch_col = NULL,
  n_pcs = 10,
  center = TRUE,
  scale. = TRUE,
  robust = TRUE,
  cutoff = 0.99,
  pbf_name = NULL
)

Arguments

Value

A data frame with sample_id, batch (if provided), mdist, and is_outlier. Attributes include cutoff, df, mdist_cutoff, and outlier_mode. The object has class "pb_outliers". When batch_col is supplied, the batch_summary attribute contains per-batch outlier counts and percentages.

Examples

data("example_ecoli_data", package = "proBatch")
meta <- example_ecoli_data$all_metadata
dm <- as.matrix(example_ecoli_data$all_protein_groups)[1:100, ]
outliers <- detect_outlier_samples(
    dm,
    sample_annotation = meta,
    batch_col = "Lab",
    n_pcs = 5
)

Description

An example dataset illustrating a typical multi-center DIA (data-independent acquisition) proteomics study processed with DIA-NN. Subset of 400 protein groups and 1463 precursors from the PRIDE ID PXD053812. Study design summary: - Five independent centers. - Per center: 23 or 24 samples of E. coli grown in different media (Pyruvate vs Glucose) The distributed object is a named list that contains the combined study-level tables derived from all centers (per-center sub-lists were removed to keep the package size below 5 MB).

Format

A named list with four elements:

'all_metadata'

'data.frame' (118 rows × 3 columns) with per-sample annotation. Columns: 'Run', 'Lab', and 'Condition'.

'all_precursors'

'data.frame' (1463 rows × 118 columns) containing the combined precursor-level Precursor.Normalised intensities (rows = precursors, columns = samples).

'all_protein_groups'

'data.frame' (400 rows × 118 columns) containing the combined protein group-level PG.MaxLFQ intensities.

'all_precursor_pg_match'

'data.frame' (1463 rows × 2 columns) linking 'Precursor.Id' to 'Protein.Ids'.

Value

A named list containing the combined metadata, quantification matrices, and precursor-to-protein mapping.

Source

PRIDE ID PXD053812

Examples

data("example_ecoli_data", package = "proBatch")
names(example_ecoli_data)

Description

This is data from Aging study annotated with gene names

Format

A data frame with 366 rows and 3 variables:

peptide_group_label

peptide group label ID, identical to peptide_group_label in example_proteome

Gene

HUGO gene ID

ProteinName

protein group name as specified in example_proteome

Value

A data frame with 366 rows and 3 variables.

Examples

data("example_peptide_annotation", package = "proBatch")
head(example_peptide_annotation)

Description

This is OpenSWATH-output data from Aging study with all iRT, spike-in peptides, few representative peptides and proteins for signal improvement demonstration. Using long_to_matrix can be converted to example_proteome_matrix

Format

A data frame with 85278 rows and 5 variables:

peptide_group_label

peptide ID, which is regular feature level. This column is mostly used as feature_id_col

used for merging with "example_peptide_annotation"

Intensity

peptide group intensity in given sample. Used in function as measure_col

Protein

Protein group ID, specified as N/UniProtID1|UniProtID2|..., where N is number of protein peptide group maps to. If 1/UniProtID, then this is proteotypic peptide, in functions used as protein_col

FullRunName

name of the file, in most functions used for sample_id_col

m_score

logical column marking peptide-identification quality, usable as qual_col

...

Value

A data frame with 85278 rows and 5 variables.

Source

PRIDE ID will be added upon the publication of the dataset

Examples

data("example_proteome", package = "proBatch")
head(example_proteome)

Description

This is measurement data from Aging study with columns representing samples and rows representing peptides. Generated by long_to_matrix

Format

A matrix with 366 rows and 233 columns:

Value

A matrix with 366 rows and 233 columns.

Source

PRIDE ID will be added upon the publication of the dataset

Examples

data("example_proteome_matrix", package = "proBatch")
dim(example_proteome_matrix)

Description

This is data from BXD mouse population aging study with mock instruments to show how instrument-specific functionality works

Format

A data frame with 233 rows and 11 variables:

FullRunName

name of the file with the measurement for each sample, referred to as sample_id_col

MS_batch

mass-spectrometry batch: character vector with four manually annotated batch labels

EarTag

mouse ID, i.e. ID of the biological object. Only 14 mice have been replicated, one mouse was profiled 7 times.

Strain

mouse strain ID from BXD population set - biological covariate #1, 51 Strain represented

Diet

diet, biological covariate #2 - either HF = 'High Fat Diet' or CD = 'Chow Diet'

Sex

mice sex - biological covariate #3

RunDate

mass-spectrometry running date. In combination with RunTime used for running order determination. Character vector

RunTime

mass-spectrometry running time. In combination with RunDate used for running order determination. Character vector

DateTime

date and time of class "POSIXct"/"POSIXt" generated by date_to_sample_order

order

order of samples generated by sorting DateTime in date_to_sample_order

digestion_batch

numeric peptide digestion batch with four manually annotated values

...

Value

A data frame with 233 rows and 11 variables.

Examples

data("example_sample_annotation", package = "proBatch")
head(example_sample_annotation)

Description

Creates a peptide faceted ggplot2 plot of the value in measure_col vs order_col (if 'NULL', x-axis is simply a sample name order). Additionally, the resulting plot can also be colored either by batch factor, by quality factor (e.g. imputed/non-imputed) and, if needed, faceted by another batch factor, e.g. an instrument. If the non-linear curve was fit, this can also be added to the plot, see functions specific to each case below

Usage

plot_single_feature(
  feature_name,
  df_long,
  sample_annotation = NULL,
  pbf_name = NULL,
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  feature_id_col = "peptide_group_label",
  geom = c("point", "line"),
  qual_col = NULL,
  qual_value = NULL,
  batch_col = "MS_batch",
  color_by_batch = FALSE,
  color_scheme = "brewer",
  order_col = "order",
  vline_color = "red",
  facet_col = NULL,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("cm", "in", "mm"),
  plot_title = NULL,
  theme = "classic",
  ylimits = NULL,
  base_size = 20
)

plot_peptides_of_one_protein(
  protein_name,
  peptide_annotation = NULL,
  protein_col = "ProteinName",
  df_long,
  sample_annotation = NULL,
  pbf_name = NULL,
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  feature_id_col = "peptide_group_label",
  geom = c("point", "line"),
  qual_col = NULL,
  qual_value = NULL,
  batch_col = "MS_batch",
  color_by_batch = FALSE,
  color_scheme = "brewer",
  order_col = "order",
  vline_color = "red",
  facet_col = NULL,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("cm", "in", "mm"),
  plot_title = sprintf("Peptides of %s protein", protein_name),
  theme = "classic",
  base_size = 20
)

plot_spike_in(
  spike_ins = "BOVIN",
  peptide_annotation = NULL,
  protein_col = "ProteinName",
  df_long,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  feature_id_col = "peptide_group_label",
  geom = c("point", "line"),
  qual_col = NULL,
  qual_value = NULL,
  batch_col = "MS_batch",
  color_by_batch = FALSE,
  color_scheme = "brewer",
  order_col = "order",
  vline_color = "red",
  facet_col = NULL,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("cm", "in", "mm"),
  plot_title = sprintf("Spike-in %s plots", spike_ins),
  theme = "classic",
  base_size = 20
)

plot_iRT(
  irt_pattern = "iRT",
  peptide_annotation = NULL,
  protein_col = "ProteinName",
  df_long,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  feature_id_col = "peptide_group_label",
  geom = c("point", "line"),
  qual_col = NULL,
  qual_value = NULL,
  batch_col = "MS_batch",
  color_by_batch = FALSE,
  color_scheme = "brewer",
  order_col = "order",
  vline_color = "red",
  facet_col = NULL,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("cm", "in", "mm"),
  plot_title = "iRT peptide profile",
  theme = "classic",
  base_size = 20
)

plot_with_fitting_curve(
  feature_name,
  fit_df,
  fit_value_col = "fit",
  df_long,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  feature_id_col = "peptide_group_label",
  geom = c("point", "line"),
  qual_col = NULL,
  qual_value = NULL,
  batch_col = "MS_batch",
  color_by_batch = FALSE,
  color_scheme = "brewer",
  order_col = "order",
  vline_color = "grey",
  facet_col = NULL,
  filename = NULL,
  width = NA,
  height = NA,
  units = c("cm", "in", "mm"),
  plot_title = sprintf("Fitting curve of %s peptide", paste(feature_name, collapse =
    " ")),
  theme = "classic",
  base_size = 20
)

Arguments

Value

ggplot2 type plot of measure_col vs order_col, faceted by feature_name and (optionally) by facet_col

Examples

data(list = c(
    "example_sample_annotation", "example_proteome",
    "example_peptide_annotation"
), package = "proBatch")

sample_annotation <- example_sample_annotation

feature_ids <- c(
    "10231_QDVDVWLWQQEGSSK_2", "10768_RLESELDGLR_2",
    "10062_NVGVSFYADKPEVTQEQK_3", "10063_NVGVSFYADKPEVTQEQKK_3",
    "1146_ADVTPADFSEWSK_3", "12476_TPVISGGPYEYR_2"
)
peptide_annotation <- subset(
    example_peptide_annotation, peptide_group_label %in% feature_ids)
proteome <- subset(
    example_proteome, peptide_group_label %in% feature_ids)
feature_id <- feature_ids[1]

feature_plot <- plot_single_feature(
    feature_name = feature_id,
    df_long = proteome,
    sample_annotation = sample_annotation,
    color_by_batch = TRUE,
    batch_col = "MS_batch"
)

protein_plot <- plot_peptides_of_one_protein(
    protein_name = "Haao",
    peptide_annotation = peptide_annotation,
    df_long = proteome,
    sample_annotation = sample_annotation,
    protein_col = "Gene"
)

spike_in_plot <- plot_spike_in(
    spike_ins = "BOVINE_A1ag",
    peptide_annotation = peptide_annotation,
    df_long = proteome,
    sample_annotation = sample_annotation,
    protein_col = "Gene"
)

irt_plot <- plot_iRT(
    irt_pattern = "iRT",
    peptide_annotation = peptide_annotation,
    df_long = proteome,
    sample_annotation = sample_annotation,
    protein_col = "Gene"
)

fit_input <- adjust_batch_trend_df(
    proteome[proteome$peptide_group_label == feature_id, ],
    sample_annotation,
    span = 0.7
)

curve_plot <- plot_with_fitting_curve(
    feature_name = feature_id,
    df_long = proteome,
    sample_annotation = sample_annotation,
    fit_df = fit_input
)

Description

Automate common metadata cleaning steps by dropping duplicated columns while retaining the preferred representative and optionally removing columns with excessive missingness. Works on plain data frames as well as ['ProBatchFeatures'] objects.

Usage

filter_metadata_columns(x, ...)

## Default S3 method:
filter_metadata_columns(
  x,
  duplicate_keep = c("first", "last", "pattern"),
  duplicate_pattern = NULL,
  pattern_ignore_case = TRUE,
  pattern_fixed = FALSE,
  min_non_na = NULL,
  max_pct_na = NULL,
  sort = FALSE,
  ...
)

## S3 method for class 'ProBatchFeatures'
filter_metadata_columns(
  x,
  component = c("colData", "rowData"),
  assay = NULL,
  df = NULL,
  inplace = FALSE,
  ...
)

Arguments

Value

For data frames, a filtered data frame with attributes '"dropped_columns"', '"dropped_duplicates"', and '"dropped_missing"' describing the removal decisions. For 'ProBatchFeatures' objects, either a filtered data frame (default) or the modified object when 'inplace = TRUE'. Supplying 'df' always returns the filtered data frame and ignores 'component', 'assay', and 'inplace'.

Examples

metadata <- data.frame(
    `factor value intensity` = c(1, 2, 3),
    intensity = c(1, 2, 3),
    batch = c("A", NA, "B"),
    stringsAsFactors = FALSE,
    check.names = FALSE
)
filtered <- filter_metadata_columns(
    metadata,
    duplicate_keep = "pattern",
    duplicate_pattern = "^factor value",
    min_non_na = 2
)
names(filtered)

Description

Compare columns after stripping attributes and normalising integer storage to double, then report pairs with matching values and 'NA' placements. The method works on plain data frames as well as on ['ProBatchFeatures'] objects by extracting the relevant annotation tables.

Usage

find_duplicated_columns(x, ...)

## Default S3 method:
find_duplicated_columns(x, ...)

## S3 method for class 'ProBatchFeatures'
find_duplicated_columns(
  x,
  component = c("colData", "rowData"),
  assay = NULL,
  df = NULL,
  ...
)

Arguments

Value

A list of character vectors (each of length two) naming duplicated column pairs. An empty list is returned when no duplicates are detected.

Examples

metadata <- data.frame(
    sample = LETTERS[1:4],
    batch = c("A", "B", "A", "B"),
    batch_copy = c("A", "B", "A", "B"),
    check.names = FALSE
)
find_duplicated_columns(metadata)

Description

Fit a non-linear trend (currently optimized for LOESS)

Usage

fit_nonlinear(
  df_feature_batch,
  measure_col = "Intensity",
  order_col = "order",
  feature_id = NULL,
  batch_id = NULL,
  fit_func = "loess_regression",
  optimize_span = FALSE,
  no_fit_imputed = TRUE,
  qual_col = "m_score",
  qual_value = 2,
  min_measurements = 8,
  ...
)

Arguments

Value

vector of fitted response values

Examples

# Load necessary datasets
data(
    list = c("example_proteome", "example_sample_annotation"),
    package = "proBatch"
)

test_peptide <- example_proteome$peptide_group_label[1]
selected_peptide <- example_proteome$peptide_group_label == test_peptide
df_selected <- example_proteome[selected_peptide, ]
selected_batch <- example_sample_annotation$MS_batch == "Batch_1"
batch_selected_df <- example_sample_annotation[selected_batch, ]
df_for_test <- merge(df_selected, batch_selected_df, by = "FullRunName")
fit_values <- fit_nonlinear(df_for_test)

# for the case where are two many missing values, no curve is fit
selected_batch <- example_sample_annotation$MS_batch == "Batch_2"
batch_selected_df <- example_sample_annotation[selected_batch, ]
df_for_test <- merge(df_selected, batch_selected_df, by = "FullRunName")
fit_values <- fit_nonlinear(df_for_test)
missing_values <- df_for_test[["m_score"]] == 2
all(fit_values[!is.na(fit_values)] ==
    df_for_test[["Intensity"]][!missing_values])

Description

Retrieve operation chain as vector or single string "combat_on_mediannorm_on_log"

Usage

get_chain(object, as_string = FALSE, assay = NULL)

Arguments

Details

Logged lineage is validated before a chain is returned. Ambiguous or cyclic lineage causes an error, including when assay = NULL.

Value

Character vector or string describing the processing chain.

Examples

# Shared setup for ProBatchFeatures documentation examples -----------------
data("example_ecoli_data", package = "proBatch")

# Extract data
all_metadata <- example_ecoli_data$all_metadata
all_precursors <- example_ecoli_data$all_precursors
all_protein_groups <- example_ecoli_data$all_protein_groups
all_precursor_pg_match <- example_ecoli_data$all_precursor_pg_match

# Keep only essential
rm(example_ecoli_data)

# Construct a ProBatchFeatures object --------------------------------------
pbf <- ProBatchFeatures(
    data_matrix = all_precursors,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    level = "peptide"
)

# Register a custom step and evaluate it -----------------------------------
example_step <- "example_add_one"
if (!pb_has_step(example_step)) {
    pb_register_step(example_step, function(x) x + 1)
}
head(pb_eval(pbf, from = "peptide::raw", steps = example_step))

# Derived objects for downstream helpers -----------------------------------
pbf_logged <- pb_transform(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm"),
    store_fast_steps = TRUE
)

# Get information about the object ---------------------------------------
get_operation_log(pbf_logged)
get_chain(pbf_logged)
get_chain(pbf_logged, as_string = TRUE)
pb_pipeline_name(pbf_logged) # the latest pipeline
pb_pipeline_name(pbf_logged, assay = "peptide::raw")

# Access assays and matrices ------------------------------------------------
head(pb_current_assay(pbf_logged)) # the latest assay
head(pb_assay_matrix(pbf_logged)) # the latest matrix
head(pb_assay_matrix(pbf_logged, assay = "peptide::raw")) # the latest matrix
head(pb_as_wide(pbf_logged)) # the latest assay in wide format
head(pb_as_long(pbf_logged, sample_id_col = "Run")) # the latest assay in long format

# Pipeline evaluation without storing --------------------------------------
head(pb_eval(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm")
))

# Long-format constructor ---------------------------------------------------
long_pbf <- pb_as_long(pbf_logged, sample_id_col = "Run") # the latest assay in long format

ProBatchFeatures_from_long(
    df_long = long_pbf,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    feature_id_col = "feature_label",
    level = "peptide"
)


# Add proteins as a new level and link via mapping
#    all_precursor_pg_match has columns: "Precursor.Id", "Protein.Ids"
pbf <- pb_add_level(
    object = pbf,
    from = "peptide::raw",
    new_matrix = all_protein_groups,
    to_level = "protein", # will name "protein::raw" by default
    mapping_df = all_precursor_pg_match,
    from_id = "Precursor.Id",
    to_id = "Protein.Ids",
    map_strategy = "as_is"
)

# Aggregate and add levels --------------------------------------------------
pb_aggregate_level(
    pbf,
    from = "peptide::raw",
    feature_var = "ProteinID",
    new_level = "protein_new"
)

Description

Access the operation log (structured)

Usage

get_operation_log(object)

Arguments

Value

S4Vectors::DataFrame

Examples

# Shared setup for ProBatchFeatures documentation examples -----------------
data("example_ecoli_data", package = "proBatch")

# Extract data
all_metadata <- example_ecoli_data$all_metadata
all_precursors <- example_ecoli_data$all_precursors
all_protein_groups <- example_ecoli_data$all_protein_groups
all_precursor_pg_match <- example_ecoli_data$all_precursor_pg_match

# Keep only essential
rm(example_ecoli_data)

# Construct a ProBatchFeatures object --------------------------------------
pbf <- ProBatchFeatures(
    data_matrix = all_precursors,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    level = "peptide"
)

# Register a custom step and evaluate it -----------------------------------
example_step <- "example_add_one"
if (!pb_has_step(example_step)) {
    pb_register_step(example_step, function(x) x + 1)
}
head(pb_eval(pbf, from = "peptide::raw", steps = example_step))

# Derived objects for downstream helpers -----------------------------------
pbf_logged <- pb_transform(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm"),
    store_fast_steps = TRUE
)

# Get information about the object ---------------------------------------
get_operation_log(pbf_logged)
get_chain(pbf_logged)
get_chain(pbf_logged, as_string = TRUE)
pb_pipeline_name(pbf_logged) # the latest pipeline
pb_pipeline_name(pbf_logged, assay = "peptide::raw")

# Access assays and matrices ------------------------------------------------
head(pb_current_assay(pbf_logged)) # the latest assay
head(pb_assay_matrix(pbf_logged)) # the latest matrix
head(pb_assay_matrix(pbf_logged, assay = "peptide::raw")) # the latest matrix
head(pb_as_wide(pbf_logged)) # the latest assay in wide format
head(pb_as_long(pbf_logged, sample_id_col = "Run")) # the latest assay in long format

# Pipeline evaluation without storing --------------------------------------
head(pb_eval(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm")
))

# Long-format constructor ---------------------------------------------------
long_pbf <- pb_as_long(pbf_logged, sample_id_col = "Run") # the latest assay in long format

ProBatchFeatures_from_long(
    df_long = long_pbf,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    feature_id_col = "feature_label",
    level = "peptide"
)


# Add proteins as a new level and link via mapping
#    all_precursor_pg_match has columns: "Precursor.Id", "Protein.Ids"
pbf <- pb_add_level(
    object = pbf,
    from = "peptide::raw",
    new_matrix = all_protein_groups,
    to_level = "protein", # will name "protein::raw" by default
    mapping_df = all_precursor_pg_match,
    from_id = "Precursor.Id",
    to_id = "Protein.Ids",
    map_strategy = "as_is"
)

# Aggregate and add levels --------------------------------------------------
pb_aggregate_level(
    pbf,
    from = "peptide::raw",
    feature_var = "ProteinID",
    new_level = "protein_new"
)

Description

Derive numeric columns from factor columns if guess_factors is TRUE and numeric columns are NULL.

Usage

guess_factor_columns_if_needed(
  factor_columns,
  sample_annotation,
  guess_factors
)

Arguments

Value

Named list containing updated factor_columns and numeric_columns.

Examples

annotation <- data.frame(
    batch = rep(c("A", "B"), 6),
    injection_order = seq_len(12)
)
guessed <- guess_factor_columns_if_needed(
    names(annotation),
    annotation,
    guess_factors = TRUE
)
guessed

Description

Remove numeric columns from factor columns if overlap is detected.

Usage

handle_factor_numeric_overlap(factor_columns, numeric_columns)

Arguments

Value

A character vector containing factor_columns after any columns in numeric_columns have been removed.

Examples

factor_columns <- c("batch", "injection_order")
overlap_result <- handle_factor_numeric_overlap(
    factor_columns,
    numeric_columns = "injection_order"
)
overlap_result

Description

Applies the package-wide missing-value policy used before matrix-oriented batch correction. Feature dropping never removes sample columns, including when the input happens to be square and symmetric.

Usage

handle_missing_values(
  data_matrix,
  warning_message,
  fill_the_missing = "error",
  fill_value = NULL
)

Arguments

Value

A numeric matrix with the requested missing-value policy applied.

Examples

mat <- matrix(c(1, NA, 3, 4), nrow = 2)
handle_missing_values(
    mat,
    warning_message = "demo",
    fill_the_missing = "fill",
    fill_value = 0
)

Description

Convert from a long data frame representation to a wide matrix representation

Usage

long_to_matrix(
  df_long,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  qual_col = NULL,
  qual_value = 2
)

Arguments

Value

data_matrix (proBatch) like matrix (features in rows, samples in columns)

See Also

Other matrix manipulation functions: matrix_to_long()

Examples

data("example_proteome", package = "proBatch")
proteome_matrix <- long_to_matrix(example_proteome)

Description

Convert from wide matrix to a long data frame representation

Usage

matrix_to_long(
  data_matrix,
  sample_annotation = NULL,
  feature_id_col = "peptide_group_label",
  measure_col = "Intensity",
  sample_id_col = "FullRunName",
  step = NULL
)

Arguments

Value

df_long (proBatch) like data frame

See Also

Other matrix manipulation functions: long_to_matrix()

Examples

# Load necessary datasets
data(
    list = c("example_sample_annotation", "example_proteome_matrix"),
    package = "proBatch"
)
# Convert matrix to long format
proteome_long <- matrix_to_long(
    example_proteome_matrix,
    example_sample_annotation
)

Description

Produce a per-column overview reporting how many distinct non-missing values appear in each column together with the number and percentage of 'NA' entries. The summary is available for plain data frames and ['ProBatchFeatures'] objects.

Usage

metadata_column_summary(x, ...)

## Default S3 method:
metadata_column_summary(x, sort = TRUE, ...)

## S3 method for class 'ProBatchFeatures'
metadata_column_summary(
  x,
  component = c("colData", "rowData"),
  assay = NULL,
  df = NULL,
  sort = TRUE,
  ...
)

Arguments

Value

A data frame with columns 'colname', 'n_unique', 'n_NA', and 'pct_NA'. Percentages are expressed on a 0–100 scale. When 'sort = TRUE' the rows are ordered by decreasing missingness.

Examples

metadata <- data.frame(
    sample = LETTERS[1:4],
    batch = c("A", "B", "A", "B"),
    batch_copy = c("A", "B", "A", "B"),
    check.names = FALSE
)
metadata_column_summary(metadata)

Description

Normalization of raw (usually log-transformed) data. Normalization brings the samples to the same scale. Currently the following normalization functions are implemented:

1. Quantile normalization: 'quantile_normalize_dm()'. Quantile normalization of the data.

2. Median normalization: 'normalize_sample_medians_dm()'. Normalization by centering sample medians to global median of the data

Alternatively, one can call normalization function with 'normalize_data_dm()' wrapper.

Usage

quantile_normalize_dm(data_matrix)

quantile_normalize_df(
  df_long,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = 2,
  keep_all = "default"
)

normalize_sample_medians_dm(
  data_matrix,
  sample_annotation = NULL,
  sample_id_col = "FullRunName",
  group_col = NULL,
  inside_batch = FALSE
)

normalize_sample_medians_df(
  df_long,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  no_fit_imputed = FALSE,
  qual_col = NULL,
  qual_value = 2,
  keep_all = "default",
  sample_annotation = NULL,
  group_col = NULL,
  inside_batch = FALSE
)

normalize_data_dm(
  data_matrix,
  normalize_func = c("quantile", "medianCentering"),
  log_base = NULL,
  offset = 1
)

normalize_data_df(
  df_long,
  normalize_func = c("quantile", "medianCentering"),
  log_base = NULL,
  offset = 1,
  feature_id_col = "peptide_group_label",
  sample_id_col = "FullRunName",
  measure_col = "Intensity",
  no_fit_imputed = TRUE,
  qual_col = NULL,
  qual_value = 2,
  keep_all = "default"
)

Arguments

Value

The data in the same format as input (data_matrix or df_long). For long input, the pre-normalization values used by the method are stored in preNorm_<measure_col> (for example, preNorm_Intensity) and normalized values are stored in measure_col. When median normalization excludes flagged imputed values, the saved pre-normalization column contains the masked values used for fitting.

Examples

data(
    list = c("example_proteome", "example_proteome_matrix"),
    package = "proBatch"
)

# Quantile normalization:
quantile_normalized_matrix <- quantile_normalize_dm(example_proteome_matrix)

# Median centering:
median_normalized_df <- normalize_sample_medians_df(example_proteome)

# Transform the data in one go:
quantile_normalized_matrix <- normalize_data_dm(example_proteome_matrix,
    normalize_func = "quantile", log_base = 2, offset = 1
)

Description

Add a new level from an external matrix and link to an existing assay

Usage

pb_add_level(
  object,
  from,
  new_matrix,
  to_level,
  to_pipeline = NULL,
  name = NULL,
  mapping_df = NULL,
  from_id = NULL,
  to_id = NULL,
  map_strategy = c("as_is", "first", "longest"),
  link_var = "ProteinID",
  backend = c("auto", "memory", "hdf5"),
  hdf5_path = NULL
)

Arguments

Value

ProBatchFeatures with new assay and link added

Examples

# Shared setup for ProBatchFeatures documentation examples -----------------
data("example_ecoli_data", package = "proBatch")

# Extract data
all_metadata <- example_ecoli_data$all_metadata
all_precursors <- example_ecoli_data$all_precursors
all_protein_groups <- example_ecoli_data$all_protein_groups
all_precursor_pg_match <- example_ecoli_data$all_precursor_pg_match

# Keep only essential
rm(example_ecoli_data)

# Construct a ProBatchFeatures object --------------------------------------
pbf <- ProBatchFeatures(
    data_matrix = all_precursors,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    level = "peptide"
)

# Register a custom step and evaluate it -----------------------------------
example_step <- "example_add_one"
if (!pb_has_step(example_step)) {
    pb_register_step(example_step, function(x) x + 1)
}
head(pb_eval(pbf, from = "peptide::raw", steps = example_step))

# Derived objects for downstream helpers -----------------------------------
pbf_logged <- pb_transform(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm"),
    store_fast_steps = TRUE
)

# Get information about the object ---------------------------------------
get_operation_log(pbf_logged)
get_chain(pbf_logged)
get_chain(pbf_logged, as_string = TRUE)
pb_pipeline_name(pbf_logged) # the latest pipeline
pb_pipeline_name(pbf_logged, assay = "peptide::raw")

# Access assays and matrices ------------------------------------------------
head(pb_current_assay(pbf_logged)) # the latest assay
head(pb_assay_matrix(pbf_logged)) # the latest matrix
head(pb_assay_matrix(pbf_logged, assay = "peptide::raw")) # the latest matrix
head(pb_as_wide(pbf_logged)) # the latest assay in wide format
head(pb_as_long(pbf_logged, sample_id_col = "Run")) # the latest assay in long format

# Pipeline evaluation without storing --------------------------------------
head(pb_eval(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm")
))

# Long-format constructor ---------------------------------------------------
long_pbf <- pb_as_long(pbf_logged, sample_id_col = "Run") # the latest assay in long format

ProBatchFeatures_from_long(
    df_long = long_pbf,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    feature_id_col = "feature_label",
    level = "peptide"
)


# Add proteins as a new level and link via mapping
#    all_precursor_pg_match has columns: "Precursor.Id", "Protein.Ids"
pbf <- pb_add_level(
    object = pbf,
    from = "peptide::raw",
    new_matrix = all_protein_groups,
    to_level = "protein", # will name "protein::raw" by default
    mapping_df = all_precursor_pg_match,
    from_id = "Precursor.Id",
    to_id = "Protein.Ids",
    map_strategy = "as_is"
)

# Aggregate and add levels --------------------------------------------------
pb_aggregate_level(
    pbf,
    from = "peptide::raw",
    feature_var = "ProteinID",
    new_level = "protein_new"
)

Description

Aggregate features (e.g., peptide -> protein) and store as new level

Usage

pb_aggregate_level(
  object,
  from,
  feature_var,
  fun = colMedians,
  new_level = "protein",
  new_pipeline = NULL
)

Arguments

Value

ProBatchFeatures with an additional aggregated assay appended

Examples

# Shared setup for ProBatchFeatures documentation examples -----------------
data("example_ecoli_data", package = "proBatch")

# Extract data
all_metadata <- example_ecoli_data$all_metadata
all_precursors <- example_ecoli_data$all_precursors
all_protein_groups <- example_ecoli_data$all_protein_groups
all_precursor_pg_match <- example_ecoli_data$all_precursor_pg_match

# Keep only essential
rm(example_ecoli_data)

# Construct a ProBatchFeatures object --------------------------------------
pbf <- ProBatchFeatures(
    data_matrix = all_precursors,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    level = "peptide"
)

# Register a custom step and evaluate it -----------------------------------
example_step <- "example_add_one"
if (!pb_has_step(example_step)) {
    pb_register_step(example_step, function(x) x + 1)
}
head(pb_eval(pbf, from = "peptide::raw", steps = example_step))

# Derived objects for downstream helpers -----------------------------------
pbf_logged <- pb_transform(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm"),
    store_fast_steps = TRUE
)

# Get information about the object ---------------------------------------
get_operation_log(pbf_logged)
get_chain(pbf_logged)
get_chain(pbf_logged, as_string = TRUE)
pb_pipeline_name(pbf_logged) # the latest pipeline
pb_pipeline_name(pbf_logged, assay = "peptide::raw")

# Access assays and matrices ------------------------------------------------
head(pb_current_assay(pbf_logged)) # the latest assay
head(pb_assay_matrix(pbf_logged)) # the latest matrix
head(pb_assay_matrix(pbf_logged, assay = "peptide::raw")) # the latest matrix
head(pb_as_wide(pbf_logged)) # the latest assay in wide format
head(pb_as_long(pbf_logged, sample_id_col = "Run")) # the latest assay in long format

# Pipeline evaluation without storing --------------------------------------
head(pb_eval(
    pbf,
    from = "peptide::raw",
    steps = c("log2", "medianNorm")
))

# Long-format constructor ---------------------------------------------------
long_pbf <- pb_as_long(pbf_logged, sample_id_col = "Run") # the latest assay in long format

ProBatchFeatures_from_long(
    df_long = long_pbf,
    sample_annotation = all_metadata,
    sample_id_col = "Run",
    feature_id_col = "feature_label",
    level = "peptide"
)


# Add proteins as a new level and link via mapping
#    all_precursor_pg_match has columns: "Precursor.Id", "Protein.Ids"
pbf <- pb_add_level(
    object = pbf,
    from = "peptide::raw",
    new_matrix = all_protein_groups,
    to_level = "protein", # will name "protein::raw" by default
    mapping_df = all_precursor_pg_match,
    from_id = "Precursor.Id",
    to_id = "Protein.Ids",
    map_strategy = "as_is"
)

# Aggregate and add levels --------------------------------------------------
pb_aggregate_level(
    pbf,
    from = "peptide::raw",
    feature_var = "ProteinID",
    new_level = "protein_new"
)