# Harmonizr

> HarmonizR

- Skill: `biomate-ai/harmonizr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/harmonizr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/harmonizr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/harmonizr

---


# HarmonizR

## Workflows

### Standard Workflow

Perform batch effect correction on a data frame containing missing values using ComBat or limma.

```r
library(HarmonizR)

# 1. Prepare the input data frame and sample description data frame
df <- data.frame(matrix(rnorm(n = 3*6), ncol = 6))
colnames(df) <- c("A", "B", "C", "D", "E", "F")
rownames(df) <- c("F1", "F2", "F3")

batch <- rep(1:3, each = 2)
des <- data.frame(ID = colnames(df), sample = 1:6, batch = batch)

# 2. Run harmonizR and write results
result <- harmonizR(df, des, output_file = FALSE, cores = 1)
```
*Input: A data frame of features with potential missing values and a sample description data frame; Output: A batch-corrected data frame.*

## When to Use
- To perform batch effect correction on high-throughput biological datasets (especially proteomics) containing missing values using `harmonizR()`.
- To run ComBat or limma batch correction algorithms on dissected matrices to maximize feature rescue.
- To correct batch effects in a `SummarizedExperiment` object containing batch metadata in `colData`.

## When NOT to Use
- For datasets with absolutely no missing values, you can use `sva::ComBat` or `limma::removeBatchEffect` directly because `HarmonizR`'s matrix dissection overhead is unnecessary.
- For non-log-transformed data where a log transformation is not appropriate, because `HarmonizR` assumes log-transformed input for plotting and standard processing.

## Data Requirements
- **Input Format**: A `data.frame`, `matrix`, or `SummarizedExperiment` object.
- **Structure**: Features (e.g., proteins, genes) as rows and samples as columns. A separate description data frame mapping sample IDs to batch numbers is required unless using a `SummarizedExperiment` with batch info in `colData`.
- **Normalization State**: Log-transformed continuous values (e.g., log2 intensity) are assumed and recommended.

## Key Parameters
- **data_as_input** (NULL): Path to raw data or a data frame/matrix of features.
- **description_as_input** (NULL): Path to description file or a data frame mapping samples to batches.
- **algorithm`** ("ComBat"): Batch correction algorithm to use, either `"ComBat"` or `"limma"`.
- **ComBat_mode** (1): Integer (1 to 4) specifying ComBat prior settings (e.g., parametric vs. non-parametric, mean-only).
- **plot** (NULL): Type of diagnostic plot to generate, e.g., `"samplemeans"`, `"featuremeans"`, or `"CV"`.
- **output_file** ("cured_data"): Name or path of the output `.tsv` file.
- **cores** (all available): Number of CPU cores to use for parallel execution.
- **ur** (TRUE): Logical indicating whether to apply unique removal of combinations for increased feature rescue.

## Best Practices
- Keep the unique removal parameter `ur = TRUE` enabled to maximize the rescue of features across batches.
- Log-transform your data before running `harmonizR()` to ensure correct behavior of the underlying ComBat/limma algorithms and plotting functions.
- Use the `block` parameter to group batches together during matrix dissection to reduce runtime on large datasets.

## Common Pitfalls
- **Plotting un-logged data**: Fix by log-transforming the input matrix prior to running `harmonizR()` with plotting enabled.
- **Extremely long runtimes on datasets with many batches**: Fix by setting the `block` parameter to an integer greater than 1 to pack batches together during dissection.
- **Missing batch metadata**: Fix by ensuring the description data frame contains `ID`, `sample`, and `batch` columns matching the input matrix column names.

## Alternatives
- `sva` (specifically `ComBat`) for batch correction when there are no missing values.
- `limma` (specifically `removeBatchEffect`) for linear model-based batch correction without missing values.

## Citations
- Schlumbohm et al. 2022, Nature Communications (for the HarmonizR framework).

## References
- Homepage: bioconductor.org/packages/HarmonizR
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/HarmonizR/inst/doc/HarmonizR_Vignette.html