CONCERTDR is an R package for drug repurposing against the CMap L1000 database. It covers CMap condition filtering, signature matching (KS, XCos, XSum, GSEA, Zhang), result annotation, z-score extraction, and heatmap visualization.
The recommended pattern is to set all CMap file paths as global options once at
the top of your script. extract_signature_zscores() and
plot_signature_direction_tile_barcode() read these automatically; for other
functions that need explicit paths, pass getOption(...).
install.packages("remotes")
remotes::install_github("DavidsonGroup/CONCERTDR")Visualization dependencies:
if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("ComplexHeatmap")
install.packages("circlize")Download the Expanded CMap LINCS2020 source files from the public Broad
Institute S3 release. The exact source URLs are recorded in
inst/scripts/make_example_data.R, and inst/scripts/download_databases.R
can download the compound Level 5 matrix and metadata files:
level5_beta_all_n1201944x12328.gctxsiginfo_beta.txtgeneinfo_beta.txtcompoundinfo_beta.txt
Also, the repurposing_drugs.txt is available at [https://s3.amazonaws.com/data.clue.io/repurposing/downloads/repurposing_drugs_20200324.txt] on Broad Institute website for drug compound reference.
Set these once at the top of any script before calling other functions. Use plain
paths or file.path() — do not use system.file() here; that function only
looks inside installed R packages and will return "" for external files.
library(CONCERTDR)
data_dir <- "/path/to/cmap_data"
options(
CONCERTDR.data_dir = data_dir,
CONCERTDR.gctx_file = file.path(data_dir, "level5_beta_all_n1201944x12328.gctx"),
CONCERTDR.siginfo_file = file.path(data_dir, "siginfo_beta.txt"),
CONCERTDR.geneinfo_file = file.path(data_dir, "geneinfo_beta.txt"),
CONCERTDR.compoundinfo_file = file.path(data_dir, "compoundinfo_beta.txt")
)You can sanity-check the paths before running:
stopifnot(file.exists(getOption("CONCERTDR.gctx_file")))
stopifnot(file.exists(getOption("CONCERTDR.geneinfo_file")))The package ships a compact example dataset in inst/extdata/ (163 genes ×
496 signatures),
so you can run the full pipeline without the multi-GB GCTX.
system.file() is used here because the files live inside the package — do not
use it for your own data files on disk.
library(CONCERTDR)
sig_file <- system.file("extdata", "example_signature.txt", package = "CONCERTDR")
ref_csv <- system.file("extdata", "example_reference_df.csv", package = "CONCERTDR")
reference_df <- read.csv(ref_csv, row.names = 1, check.names = FALSE)
reference_df$gene_symbol <- rownames(reference_df)
res <- process_signature_with_df(
reference_df = reference_df,
signature_file = sig_file,
methods = c("ks","xsum"),
topN = 4,
permutations = 10,
save_files = FALSE
)
summary(res)
head(res$results$ks)direction controls only the order in which hits are ranked and picked:
"reversal" (the default) puts the lowest scores first, "mimic" the highest
first. It never removes a result because of its sign. The same argument is
available in process_signature_with_df(), annotate_drug_results(),
extract_signature_zscores(), and plot_signature_direction_tile_barcode().
Pass your chosen direction to each stage; plot(res) uses the direction saved
in the result object.
direction <- "mimic" # use "reversal" for disease-signature reversal
res <- process_signature_with_df(
sig_file, reference_df, methods = "ks", permutations = 10,
direction = direction
)
z <- extract_signature_zscores(
res$results$ks, sig_file, reference_df = reference_df,
direction = direction
)
plot_signature_direction_tile_barcode(precomputed = z)Per-method results, tech_view_all, the wetlab views and the context summary
all keep every finite score. direction does not change p-values; CamSum's
one-sided hypothesis is controlled separately by camsum_alternative.
Cross-method summaries use each hit's rank percentile among all profiles of its
method (rank_percentile) to compute global_rank, so differently scaled
scores are not compared directly. These ranks are relative hit orderings, not
combined significance estimates. Wetlab drug views report the best context's
actual cell, time and optional dose.
The bundled example data also support z-score extraction and plotting directly
from example_reference_df.csv:
z <- extract_signature_zscores(
results_df = res$results$ks,
signature_file = sig_file,
reference_df = reference_df,
max_genes = 20,
max_perts = 10
)
plot_signature_direction_tile_barcode(
precomputed = z,
cluster_rows = FALSE,
cluster_cols = FALSE
)If you have the original CMap files, you can still pass gctx_file,
geneinfo_file, and siginfo_file to extract the heatmap matrix from GCTX
instead of using the precomputed reference matrix.
By default, the core analysis and plotting functions do not write files. Files
are only created when you explicitly request them, for example with
save_files = TRUE, write_outputs = TRUE, output_zscores = ..., or
save_png = TRUE.
Narrow down to the cell lines and perturbation types relevant to your analysis. The result is an in-memory data frame that gets passed directly to later steps.
filtered_siginfo <- subset_siginfo_beta(
getOption("CONCERTDR.siginfo_file"),
interactive = FALSE,
filters = list(
pert_type = c("trt_xpr", "trt_cp", "trt_oe"),
pert_itime = c("6 h", "24 h"),
cell_iname = c("HL60", "THP1", "K562", "HAP1", "JURKAT", "U937")
)
)Use interactive = TRUE to select parameters interactively from the console.
Filterable columns: pert_type, pert_itime, pert_idose, cell_iname.
The pert_type values are defined by LINCS2020 as follows:
The signature needs a Gene (HGNC symbol) and log2FC column. You can provide
it as a file path or as an in-memory data frame.
Option A — from a file:
Gene log2FC
STAT3 2.5
TP53 -1.8
MYC 3.2
BRCA1 -2.1
Option B — from a data frame already in R:
# If 'signature' is already a data.frame with Gene + log2FC columns,
# pass it directly — no need to write to disk first.
signature <- data.frame(
Gene = c("STAT3", "TP53", "MYC", "BRCA1"),
log2FC = c(2.5, -1.8, 3.2, -2.1)
)Option C — from gene lists (no fold-changes):
signature <- create_signature_from_gene_lists(
up_genes = c("STAT3", "MYC"),
down_genes = c("TP53", "BRCA1")
)
# Up genes get log2FC = 1, down genes get log2FC = -1Note: This step reads the large GCTX file and can take a long time (minutes to tens of minutes). The package will print a progress message — please do not interrupt the process.
reference_df <- extract_cmap_data_from_siginfo(
geneinfo_file = getOption("CONCERTDR.geneinfo_file"),
siginfo_file = filtered_siginfo, # data frame from Step 1, not re-read from disk
gctx_file = getOption("CONCERTDR.gctx_file"),
filter_quality = FALSE, # TRUE restricts to is_hiq == 1
landmark = TRUE # TRUE restricts to 978 landmark genes
)To include inferred genes in Step 3, set landmark = FALSE. Duplicate symbols
are resolved using landmark > best inferred > inferred > other; ties keep
the first input row. A warning identifies dropped and retained gene IDs.
For LINCS2020, this retains MIA2 gene ID 4253 instead of 117153 and returns
12,327 unique symbols when all features are available. Direct heatmap extraction
and CamSum library calculations use the same feature preference.
When multiple compoundinfo rows describe the same drug, annotation combines
distinct nonblank targets and MOAs with ; , without multiplying signature
rows or context counts. The two annotation columns are independent lists,
not positional target-MOA pairs.
signature_file accepts a file path or a data frame:
results <- process_signature_with_df(
reference_df = reference_df,
signature_file = signature, # data.frame or file path
output_dir = "results",
methods = c("xsum", "xcos", "zhang", "gsea0", "gsea1", "gsea2", "ks"),
topN = 400, # genes used by XCos/XSum
permutations = 1, # increase for p-values
save_files = FALSE # set TRUE only if you want CSV outputs written
)
print(results) # brief overview
summary(results) # top hits across methods (lowest scores first by default)
head(results$results$ks)Available methods:
| ID | Description |
|---|---|
ks |
Kolmogorov–Smirnov |
xcos |
Extreme cosine similarity |
xsum |
Extreme sum |
gsea0 / gsea1 / gsea2 |
GSEA (weight 0 / 1 / 2) |
zhang |
Zhang et al. |
camsum |
CamSum: correlation-adjusted sum with analytic p-value (opt-in; not in the default set) |
Joins siginfo and compoundinfo to add drug names, MoA, dose, cell line, etc.
filtered_siginfo is already in memory from Step 1 — no file re-read.
views <- annotate_drug_results(
results_df = results$results$ks,
sig_info_file = filtered_siginfo,
comp_info_file = getOption("CONCERTDR.compoundinfo_file"),
output_dir = "results",
write_outputs = TRUE
)
head(views$tech_view_all) # per-signature scores
head(views$wetlab_drug_view) # drug-level summary
head(views$drug_context_summary) # drug × cell line breakdownReads the GCTX once. Save the result and reuse it rather than repeating this call.
# Default: top max_genes rows from the combined signature
z <- extract_signature_zscores(
results_df = views$tech_view_all,
signature_file = signature, # data.frame or file path
max_genes = 100,
max_perts = 60,
output_zscores = NULL # set a path if you want to save TSV
)
# Split mode: top max_genes up-regulated AND top max_genes down-regulated genes
# (up to 2 * max_genes columns total)
z <- extract_signature_zscores(
results_df = views$tech_view_all,
signature_file = signature,
max_genes = 50, # 50 up + 50 down = up to 100 columns
split_direction = TRUE,
output_zscores = NULL
)The returned list contains:
z_plot— matrix (perturbations × genes), rows labelleddrug | dose | time | cellordered_genes— gene order (down-regulated → up-regulated)logfc_map— named vector of log2FC valuessig_ids/sig_labels— CMap identifiers and readable labels
Pass precomputed = z to skip any file I/O on repeat calls.
# Default: all genes in one panel (down-regulated → up-regulated left to right)
plot_signature_direction_tile_barcode(
precomputed = z,
cluster_rows = TRUE,
cluster_cols = FALSE, # keeps down → up gene order from signature
show_row_dendrogram = TRUE,
save_png = TRUE, # default is FALSE
output_png = "results/barcode_heatmap.png"
)
# Split mode: up-regulated panel (left) | down-regulated panel (right)
plot_signature_direction_tile_barcode(
precomputed = z,
split_direction = TRUE, # split into up / down panels
gap_width = 5, # mm gap between panels (default 5)
cluster_rows = TRUE,
save_png = TRUE,
output_png = "results/barcode_heatmap_split.png"
)In split mode, row clustering is performed on the full combined matrix so that both panels share the same perturbation order, enabling direct comparison of up- and down-regulation patterns side by side.
Colour scheme: coolwarm (#3B4CC0 → white → #B40426) for z-scores; BrBG
(#01665E → white → #8C510A) for the log2FC annotation bar. Figure dimensions
are computed automatically from data size (~0.22 in/gene, ~0.28 in/perturbation),
or set explicitly with width, height, dpi.
| Function | Description |
|---|---|
subset_siginfo_beta() |
Filter siginfo_beta.txt to a cell-line/pert-type subset |
| Function | Description |
|---|---|
extract_cmap_data_from_siginfo() |
Build reference matrix from filtered siginfo |
| Function | Description |
|---|---|
process_signature_with_df() |
Score a signature against an in-memory reference |
create_signature_from_gene_lists() |
Build a signature data frame from up/down gene lists |
| Function | Description |
|---|---|
annotate_drug_results() |
Join CMap metadata; produce wetlab/tech view tables |
fuzzy_drug_match() |
Fuzzy-match drug names across databases |
extract_compound_id() |
Resolve compound identifiers |
| Function | Description |
|---|---|
extract_signature_zscores() |
Extract GCTX z-score matrix as an R object |
plot_signature_direction_tile_barcode() |
ComplexHeatmap barcode plot (z-score × perturbation) |
All documentation is written as #' roxygen2 blocks in the .R source files.
Do not edit NAMESPACE or man/*.Rd directly.
devtools::document() # regenerate man/ and NAMESPACE
devtools::check() # R CMD check
devtools::install() # install locally for testingMIT — see the LICENSE file for details.

