biopipen 0.21.0__py3-none-any.whl → 0.34.26__py3-none-any.whl

biopipen/scripts/regulatory/MotifAffinityTest_MotifBreakR.R

@@ -0,0 +1,104 @@
+library(motifbreakR)
+
+bsgenome <- getBSgenome(genome_pkg)
+
+# `chrom`, `start`, `end`, `name`, `score`, `strand`, `ref`, `alt`.
+is_indel <- nchar(snpinfo$ref) != 1 | nchar(snpinfo$alt) != 1
+snpinfo$coordname <- ifelse(
+    is_indel,
+    sprintf("%s:%s-%s:%s:%s", snpinfo$chrom, snpinfo$start + 1, snpinfo$end, snpinfo$ref, snpinfo$alt),
+    sprintf("%s:%s:%s:%s", snpinfo$chrom, snpinfo$end, snpinfo$ref, snpinfo$alt)
+)
+motifbreakr_bed <- file.path(outdir, gsub("\\.vcf(\\.gz)?$|\\.bed$", ".motifbreakr.bed", basename(varfile)))
+write.table(
+    snpinfo[, c("chrom", "start", "end", "coordname", "score", "strand")],
+    file = motifbreakr_bed,
+    sep = "\t", quote = FALSE, row.names = FALSE, col.names = FALSE
+)
+snps <- snps.from.file(motifbreakr_bed, search.genome = bsgenome, format = "bed", indels = any(is_indel))
+snpinfo <- snpinfo[snpinfo$coordname == snps$SNP_id, , drop = FALSE]
+snps@elementMetadata$SNP_id <- ifelse(
+    snpinfo$name == "." | is.na(snpinfo$name) | nchar(snpinfo$name) == 0,
+    snpinfo$coordname,
+    snpinfo$name
+)
+
+# prepare PWMs
+get_bkg <- function(base) {
+    base_col <- paste0("bkg.", base)
+    base_bkg <- mdb@elementMetadata[[base_col]]
+    if (is.null(base_bkg) || length(base_bkg) == 0 || is.na(base_bkg[1])) {
+        base_bkg <- 0.25
+    } else {
+        base_bkg <- as.numeric(base_bkg[1])
+    }
+}
+bkg <- c(A = get_bkg("A"), C = get_bkg("C"), G = get_bkg("G"), T = get_bkg("T"))
+
+# run motifbreakR
+log$info("Running motifbreakR ...")
+results <- motifbreakR(
+    snpList = snps,
+    pwmList = mdb,
+    threshold = cutoff,
+    method = motifbreakr_args$method,
+    bkg = bkg,
+    filterp = TRUE,
+    show.neutral = FALSE,
+    BPPARAM = MulticoreParam(ncores)
+)
+
+log$info("Calculating p values ...")
+results <- calculatePvalue(results)
+results$.id <- 1:length(results)
+results_to_save <- as.data.frame(unname(results))
+results_to_save$motifPos <- lapply(results_to_save$motifPos, function(x) paste(x, collapse = ","))
+results_to_save$altPos <- lapply(results_to_save$altPos, function(x) paste(x, collapse = ","))
+if (!is.null(regulator_col)) {
+    results_to_save$Regulator <- in_motifs[
+        match(results_to_save$providerId, in_motifs[[motif_col]]),
+        regulator_col,
+        drop = TRUE
+    ]
+}
+results_to_save <- as.data.frame(apply(results_to_save, 2, as.character))
+
+if (!is.null(motif_var_pairs)) {
+    log$info("Filtering motif-variant pairs ...")
+    results_to_save$motifs_vars <- paste0(results_to_save$providerId, " // ", results_to_save$SNP_id)
+    results_to_save <- results_to_save[results_to_save$motifs_vars %in% motif_var_pairs, , drop = FALSE]
+    results_to_save$motifs_vars <- NULL
+}
+
+write.table(
+    results_to_save,
+    file = file.path(outdir, "motifbreakr.txt"),
+    sep = "\t", quote = FALSE, row.names = FALSE
+)
+# rm(results_to_save)
+
+log$info("Plotting variants ...")
+if (is.null(plots) || length(plots) == 0) {
+    results_to_save$alleleDiff <- as.numeric(results_to_save$alleleDiff)
+    results_to_save <- results_to_save[order(-abs(results_to_save$alleleDiff)), , drop = FALSE]
+    results_to_save <- results_to_save[1:min(plot_nvars, nrow(results_to_save)), , drop = FALSE]
+    variants <- unique(results_to_save$SNP_id)
+} else {
+    variants <- names(plots)
+}
+for (variant in variants) {
+    log$info("- Variant: {variant}")
+    if (is.null(plots[[variant]])) {
+        plots[[variant]] <- list(devpars = devpars, which = "TRUE")
+    }
+    if (is.null(plots[[variant]]$which)) {
+        plots[[variant]]$which <- "TRUE"
+    }
+    if (is.null(plots[[variant]]$devpars)) {
+        plots[[variant]]$devpars <- devpars
+    }
+    res <- results[results$SNP_id == variant & results$.id %in% results_to_save$.id, , drop = FALSE]
+    res <- subset(res, subset = eval(parse(text = plots[[variant]]$which)))
+
+    plot_variant_motifs(res, variant, plots[[variant]]$devpars, outdir)
+}

biopipen/scripts/regulatory/MotifScan.py

@@ -0,0 +1,159 @@
+"""Script for regulatory.MotifScan"""
+import re
+
+# Paths may be passed in args or to motifdb
+from pathlib import PosixPath  # noqa: F401
+from biopipen.utils.misc import run_command, dict_to_cli_args, logger
+
+motiffile: str = {{in.motiffile | quote}}  # pyright: ignore # noqa: #999
+seqfile: str = {{in.seqfile | quote}}  # pyright: ignore
+outdir: str = {{out.outdir | quote}}  # pyright: ignore
+
+tool = {{envs.tool | repr}}  # pyright: ignore
+fimo = {{envs.fimo | repr}}  # pyright: ignore
+motif_col: str | int = {{envs.motif_col | repr}}  # pyright: ignore
+regulator_col: str | int = {{envs.regulator_col | repr}}  # pyright: ignore
+notfound = {{envs.notfound | repr}}  # pyright: ignore
+motifdb: str | None = {{envs.motifdb | repr}}  # pyright: ignore
+cutoff = {{envs.cutoff | repr}}  # pyright: ignore
+q = {{envs.q | repr}}  # pyright: ignore
+q_cutoff = {{envs.q_cutoff | repr}}  # pyright: ignore
+args: dict = {{envs.args | dict | repr}}  # pyright: ignore
+
+# Check if the tool is supported
+if tool != "fimo":
+    raise ValueError(f"Unsupported tool: {tool}, currently only fimo is supported")
+
+# Check if the motif database is provided
+if motifdb is None:
+    raise ValueError("The motif database is required")
+
+# Check if the motif file exists
+if not motiffile:
+    raise FileNotFoundError(f"Motif file in.motiffile must be provided")
+
+# Check if the sequence file exists
+if not seqfile:
+    raise FileNotFoundError(f"Sequence file in.seqfile must be provided")
+
+# Normalize motif_col and regulator_col into 0-based indexes
+if isinstance(motif_col, str) or isinstance(regulator_col, str):
+    with open(motiffile, "r") as f:
+        header = f.readline().strip().split("\t")
+        if isinstance(motif_col, str):
+            motif_col: int = header.index(motif_col) + 1
+        if isinstance(regulator_col, str):
+            regulator_col = header.index(regulator_col) + 1
+if isinstance(motif_col, int):
+    motif_col -= 1
+if isinstance(regulator_col, int):
+    regulator_col -= 1
+
+# Check if motif names exist in the database
+with open(motiffile, "r") as f:
+    motif_names = set(
+        line.strip().split("\t")[motif_col]
+        for i, line in enumerate(f)
+        if i > 0  # skip header
+    )
+
+with open(motifdb, "r") as f:
+    motif_db_names = set(
+        line[6:].strip()
+        for line in f
+        if line.startswith("MOTIF")
+    )
+
+if notfound == "error":
+    notfound_motifs = motif_names - motif_db_names
+    if notfound_motifs:
+        raise ValueError(f"Motifs not found in the database: {notfound_motifs}")
+
+# Make a new motif database with only the motifs in the motiffile
+motif_names = motif_names & motif_db_names
+motifdb_filtered = f"{outdir}/motif_db.txt"
+with open(motifdb, "r") as f, open(motifdb_filtered, "w") as f_out:
+    should_write = True
+    for line in f:
+        if line.startswith("MOTIF"):
+            motif_name = line[6:].strip()
+            if motif_name in motif_names:
+                should_write = True
+            else:
+                should_write = False
+
+        if should_write:
+            f_out.write(line)
+        else:
+            continue
+
+# Now run fimo
+args[""] = fimo
+args["oc"] = f"{outdir}"
+args["thresh"] = cutoff
+args["qv_thresh"] = q_cutoff
+args["no_qvalue"] = not q
+args["no-pgc"] = True
+args["_"] = [motifdb_filtered, seqfile]
+
+logger.info("Running fimo ...")
+run_command(dict_to_cli_args(args, dashify=True), fg=True)
+
+logger.info("Adding additional information to the output ...")
+# Get the motif to regulator mapping
+motif_regulator_map = {}
+if regulator_col is not None:
+    with open(motiffile, "r") as f:
+        next(f)  # skip header
+        for line in f:
+            line = line.strip().split("\t")
+            motif_name = line[motif_col]
+            regulator = line[regulator_col]
+            motif_regulator_map[motif_name] = regulator
+
+# Get the sequence name information
+seqnames = {}
+seqcoords = {}
+with open(seqfile, "r") as f:
+    for line in f:
+        if not line.startswith(">"):
+            continue
+
+        seqname = line[1:].strip()
+        match = re.match(r"^(.+)::((?:chr)?\d+):(\d+)-(\d+).*$", seqname)
+        if not match:
+            seqnames[seqname] = seqname
+            seqcoords[seqname] = None
+        else:
+            sname, chrom, start, end = match.groups()
+            seqnames[seqname] = sname
+            seqcoords[seqname] = (chrom, int(start), int(end))
+
+# Add additional information to the output
+with open(f"{outdir}/fimo.tsv", "r") as f, open(f"{outdir}/fimo_output.txt", "w") as f_out:
+    header = f.readline().strip().split("\t")
+    f_out.write(
+        "\t".join(header + ["regulator", "seqname", "seqstart", "seqstop"]) + "\n"
+    )
+    for line in f:
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        line = line.split("\t")
+        motif_name = line[0]
+        sequence_name = line[2]
+        start = int(line[3])
+        stop = int(line[4])
+        regulator = motif_regulator_map.get(motif_name, motif_name)
+        seqname = seqnames.get(sequence_name, "NA")
+        seqcoord = seqcoords.get(sequence_name)
+        if not seqcoord:
+            seqstart = "NA"
+            seqstop = "NA"
+        else:
+            seqstart = start + seqcoord[1] - 1
+            seqstop = stop + seqcoord[2] - 1
+
+        f_out.write(
+            "\t".join(line + [regulator, seqname, str(seqstart), str(seqstop)]) + "\n"
+        )

biopipen/scripts/regulatory/VariantMotifPlot.R

@@ -0,0 +1,78 @@
+{% include biopipen_dir + "/scripts/regulatory/motifs-common.R" %}
+
+library(BSgenome)
+library(GenomicRanges)
+library(biopipen.utils)
+
+infile <- {{in.infile | r}}
+outdir <- {{out.outdir | r}}
+genome <- {{envs.genome | r}}
+motifdb <- {{envs.motifdb | r}}
+motif_col <- {{envs.motif_col | r}}
+regulator_col <- {{envs.regulator_col | r}}
+regmotifs <- {{envs.regmotifs | r}}
+notfound <- {{envs.notfound | r}}
+devpars <- {{envs.devpars | r}}
+plot_vars <- {{envs.plot_vars | r}}
+
+if (is.null(motifdb) || !file.exists(motifdb)) {
+    stop("Motif database (envs.motifdb) is required and must exist")
+}
+
+if (is.null(genome)) {
+    stop("Reference genome (envs.ref) is required and must exist")
+}
+
+if (is.null(motif_col) && is.null(regulator_col)) {
+    stop("Either motif (envs.motif_col) or regulator (envs.regulator_col) column must be provided")
+}
+
+log <- get_logger()
+
+log$info("Reading input data ...")
+indata <- read.table(infile, header=TRUE, sep="\t", stringsAsFactors=FALSE, check.names = FALSE)
+
+log$info("Ensuring regulators in the input data ...")
+indata <- ensure_regulator_motifs(indata, outdir, motif_col, regulator_col, "SNP_id", regmotifs, notfound = notfound)
+genome_pkg <- get_genome_pkg(genome)
+
+log$info("Reading motif database ...")
+meme <- read_meme_to_motifdb(motifdb, indata, motif_col, regulator_col, notfound, outdir)
+
+log$info("Composing motifbreakR results from input data ...")
+indata$chr <- indata$chrom %||% indata$chr %||% indata$seqnames
+indata$seqnames <- NULL
+indata$strand <- indata$strand %||% "+"
+indata$varType <- indata$varType %||% "SNV"
+indata$geneSymbol <- indata$geneSymbol %||% indata$Regulator
+indata$providerId <- indata$providerId %||% indata$motif
+indata$providerName <- indata$providerName %||% indata$providerId
+indata$dataSource <- indata$dataSource %||% strsplit(basename(motifdb), "\\.")[[1]][1]
+indata$effect <- indata$effect %||% "strong"
+indata$altPos <- indata$altPos %||% 1
+indata$alleleDiff <- indata$alleleDiff %||% indata$score %||% 0
+
+# check other required columns
+for (col in c("start", "end", "SNP_id", "REF", "ALT", "motifPos")) {
+    if (!(col %in% colnames(indata))) {
+        stop("Column '", col, "' is required in the input data")
+    }
+}
+indata$motifPos <- lapply(indata$motifPos, function(x) as.integer(unlist(strsplit(x, ","))))
+indata <- makeGRangesFromDataFrame(indata, keep.extra.columns = TRUE, starts.in.df.are.0based = TRUE)
+genome(indata) <- genome
+attributes(indata)$genome.package <- genome_pkg
+attributes(indata)$motifs <- meme
+
+log$info("Plotting variants ...")
+if (is.null(plot_vars)) {
+    plot_vars <- unique(indata$SNP_id)
+} else if (length(plot_vars) > 1) {
+    plot_vars <- unique(plot_vars)
+} else {
+    plot_vars <- strsplit(plot_vars, ",")[[1]]
+}
+for (pvar in plot_vars) {
+    log$info("- Variant: {pvar}")
+    plot_variant_motifs(indata, pvar, devpars, outdir)
+}

biopipen/scripts/regulatory/motifs-common.R

@@ -0,0 +1,324 @@
+library(rlang)
+library(universalmotif)
+library(MotifDb)
+library(biopipen.utils)
+
+#' @title Common functions for regulatory analysis
+#' @name regulatory-common
+#' @author Panwen Wang
+
+#' Read a regulator-motif mapping file
+#'
+#' @param rmfile Regulator-motif mapping file
+#' @param motif_cols_allowed Allowed motif columns
+#' @param reg_cols_allowed Allowed regulator columns
+#' @return Data frame with regulators and motifs in the first and second columns, respectively
+.read_regmotifs <- function(
+    rmfile,
+    motif_cols_allowed = c("Motif", "motif", "MOTIF", "Model", "model", "MODEL"),
+    reg_cols_allowed = c("Regulator", "regulator", "REGULATOR", "TF", "tf", "TF")
+) {
+    if (!file.exists(rmfile)) {
+        stop("Regulator-motif mapping file does not exist.")
+    }
+    regmotifs <- read.table(rmfile, header=TRUE, sep="\t", stringsAsFactors=FALSE, check.names = FALSE)
+    rm_motif_col <- intersect(motif_cols_allowed, colnames(regmotifs))
+    rm_reg_col <- intersect(reg_cols_allowed, colnames(regmotifs))
+    if (length(rm_motif_col) == 0) {
+        stop(paste0("No motif column found in the regulator-motif mapping file, provide one of: ", paste(motif_cols_allowed, collapse = ", ")))
+    }
+    if (length(rm_reg_col) == 0) {
+        stop(paste0("No regulator column found in the regulator-motif mapping file, provide one of: ", paste(reg_cols_allowed, collapse = ", ")))
+    }
+    if (length(rm_motif_col) > 1) {
+        stop(paste0("Multiple motif columns found (", paste(rm_motif_col, collapse = ", "), ") in the regulator-motif mapping file, provide only one"))
+    }
+    if (length(rm_reg_col) > 1) {
+        stop(paste0("Multiple regulator columns found (", paste(rm_reg_col, collapse = ", "), ") in the regulator-motif mapping file, provide only one"))
+    }
+    rm_motif_col <- rm_motif_col[1]
+    rm_reg_col <- rm_reg_col[1]
+    regmotifs <- regmotifs[, c(rm_motif_col, rm_reg_col), drop = FALSE]
+
+    return(regmotifs)
+}
+
+#' Handle not found items
+#'
+#' @param notfound_items Items that were not found
+#' @param log_warn Function to log warnings
+#' @param msg Message to display
+#' @param notfound Action to take if items are not found
+#' @param notfound_file File to save the full list of not found items
+#' @param log_indent Indentation for log messages
+.handle_notfound_items <- function (notfound_items, log_warn, msg, notfound, notfound_file, log_indent = "") {
+    if (length(notfound_items) > 0) {
+        first_notfound <- head(notfound_items, 3)
+        if (length(notfound_items) > 3) {
+            first_notfound <- c(first_notfound, "...")
+            writeLines(notfound_items, notfound_file)
+            msg1 <- paste0(log_indent, msg, ": ", paste(first_notfound, collapse = ", "))
+            msg2 <- paste0(log_indent, "Check the full list in ", notfound_file)
+            if (notfound == "error") {
+                stop(msg1, "\n", msg2)
+            } else if (notfound == "ignore") {
+                log_warn(msg1)
+                log_warn(msg2)
+            }
+        } else {
+            msg <- paste0(log_indent, msg, ": ", paste(first_notfound, collapse = ", "))
+            if (notfound == "error") {
+                stop(msg)
+            } else if (notfound == "ignore") {
+                log_warn(msg)
+            }
+        }
+    }
+}
+
+#' Read a MEME file to a MotifDb object
+#' and filter the motifs based on the input data
+#' and return the filtered MotifDb object
+#' with metadata
+#'
+#' @param motifdb MEME file
+#' @param indata Input data frame
+#' @param motif_col Column name for the motif
+#' @param regulator_col Column name for the regulator
+#' @param notfound Action to take if motifs are not found
+#' @param outdir Output directory, used to save un-matched motifs
+#' @return MotifDb object
+#' @export
+read_meme_to_motifdb <- function(motifdb, indata, motif_col, regulator_col, notfound, outdir) {
+    meme <- read_meme(motifdb)
+    motifdb_names <- sapply(meme, function(m) m@name)
+    motifs <- check_motifs(indata[[motif_col]], motifdb_names, notfound, outdir)
+    meme <- filter_motifs(meme, name = motifs)
+    # Get the right order of motif names
+    motifs <- sapply(meme, function(m) m@name)
+    motifdb_matrices <- lapply(meme, function(m) m@motif)
+    names(motifdb_matrices) <- motifs
+    motifdb_meta <- do.call(rbind, lapply(meme, function(m) {
+            ats <- attributes(m)
+            ats$dataSource <- strsplit(basename(motifdb), "\\.")[[1]][1]
+            ats$class <- NULL
+            ats$motif <- NULL
+            ats$gapinfo <- NULL
+            ats$sequenceCount <- ats$nsites
+            ats$providerId <- ats$name
+            ats$providerName <- ats$name
+            ats$organism <- if (is.null(ats$organism) || length(ats$organism) == 0) "Unknown" else ats$organism
+            if (!is.null(regulator_col)) {
+                ats$geneSymbol <- indata[
+                    indata[[motif_col]] == ats$name,
+                    regulator_col,
+                    drop = TRUE
+                ]
+            }
+            unlist(ats)
+        })
+    )
+    rownames(motifdb_meta) <- motifs
+    MotifDb:::MotifList(motifdb_matrices, tbl.metadata = motifdb_meta)
+}
+
+#' Convert a MotifDb object to a motif library
+#' with motif names as keys
+#' and PWMs as values
+#' @param motifdb MotifDb object
+#' @return Motif library
+#' @export
+motifdb_to_motiflib <- function(motifdb) {
+    lapply(motifdb, t)
+}
+
+#' Make sure the regulators and motifs in the input data from a regulator-motif mappings
+#'
+#' @param indata Input data frame
+#' @param outdir Output directory, used to save un-matched regulators
+#' @param motif_col Column name for the motif
+#' @param regulator_col Column name for the regulator
+#' @param var_col Column name for the variant
+#' @param regmotifs Regulator-motif mapping file
+#' @param log_indent Indentation for log messages
+#' @param notfound Action to take if regulators are not found in the mapping file
+#' @return Data frame with regulators and motifs
+#' @export
+ensure_regulator_motifs <- function (indata, outdir, motif_col, regulator_col, var_col, regmotifs, log_indent = "", notfound = "error", log = NULL) {
+    if (is.null(motif_col)) {
+        if (is.null(regmotifs)) {
+            stop("Regulator-motif mapping file (envs.regmotifs) is required when no motif column (envs.motif_col) is provided")
+        }
+        log <- log %||% get_logger()
+        regmotifs <- .read_regmotifs(regmotifs)
+        rm_motif_col <- colnames(regmotifs)[1]
+        rm_reg_col <- colnames(regmotifs)[2]
+        # check regulators
+        rm_regs <- regmotifs[[rm_reg_col]]
+        regulators <- indata[[regulator_col]]
+        notfound_regs <- setdiff(regulators, rm_regs)
+        .handle_notfound_items(
+            notfound_regs,
+            log$warn,
+            "The following regulators were not found in the regulator-motif mapping file",
+            notfound,
+            file.path(outdir, "notfound_regulators.txt"),
+            log_indent
+        )
+        indata <- indata[indata[[regulator_col]] %in% rm_regs, , drop = FALSE]
+        # add motif column
+        indata <- merge(indata, regmotifs, by.x = regulator_col, by.y = rm_reg_col, all.x = TRUE, suffixes = c("", "_db"))
+        # update motif column
+        motif_col <<- rm_motif_col
+    } else if (is.null(regulator_col)) {
+        if (is.null(regmotifs) || (is.character(regmotifs) && nchar(regmotifs) == 0)) {
+            # make motifs unique
+            indata <- indata[!duplicated(indata[[motif_col]]), , drop = FALSE]
+        } else if (!file.exists(regmotifs)) {
+            stop("Regulator-motif mapping file (envs.regmotifs) does not exist.")
+        } else {
+            # map the regulators
+            regmotifs <- .read_regmotifs(regmotifs)
+            rm_motif_col <- colnames(regmotifs)[1]
+            rm_reg_col <- colnames(regmotifs)[2]
+            rm_motifs <- regmotifs[[rm_motif_col]]
+            motifs <- indata[[motif_col]]
+            notfound_motifs <- setdiff(motifs, rm_motifs)
+            .handle_notfound_items(
+                notfound_motifs,
+                log$warn,
+                "The following motifs were not found in the regulator-motif mapping file",
+                notfound,
+                file.path(outdir, "notfound_motifs.txt"),
+                log_indent
+            )
+            indata <- indata[indata[[motif_col]] %in% rm_motifs, , drop = FALSE]
+            # add regulator column
+            indata <- merge(indata, regmotifs, by.x = motif_col, by.y = rm_motif_col, all.x = TRUE, suffixes = c("", "_db"))
+            # update regulator column
+            regulator_col <<- rm_reg_col
+        }
+    } else {
+        indata <- indata[!duplicated(indata[, c(regulator_col, motif_col, var_col), drop = FALSE]), , drop = FALSE]
+    }
+
+    return(indata)
+}
+
+#' Get the genome package name for a given genome
+#'
+#' @param genome Genome name
+#' @return Genome package name
+#' @export
+get_genome_pkg <- function(genome) {
+    if (!grepl(".", genome, fixed = TRUE)) {
+        genome_pkg = sprintf("BSgenome.Hsapiens.UCSC.%s", genome)
+    } else {
+        genome_pkg = genome
+    }
+    if (!requireNamespace(genome_pkg, quietly = TRUE)) {
+        stop(sprintf("Genome package %s is not installed", genome_pkg))
+    }
+
+    library(package = genome_pkg, character.only = TRUE)
+    return(genome_pkg)
+}
+
+#' Check if motifs are in the motif database
+#' and return the motifs that are found
+#'
+#' @param motifs Motifs to check
+#' @param all_motifs All motifs in the motif database
+#' @param notfound Action to take if motifs are not found
+#' @param outdir Output directory, used to save un-matched motifs
+#' @return Motifs that are found
+#' @export
+check_motifs <- function(motifs, all_motifs, notfound, outdir, log = NULL) {
+    log <- log %||% get_logger()
+    notfound_motifs <- setdiff(motifs, all_motifs)
+    if (length(notfound_motifs) > 0) {
+        first_notfound <- head(notfound_motifs, 3)
+        if (length(notfound_motifs) > 3) {
+            first_notfound <- c(first_notfound, "...")
+            notfound_file <- file.path(outdir, "notfound_motifs.txt")
+            writeLines(notfound_motifs, notfound_file)
+            msg1 <- paste0("The following motifs were not found in the motif database: ", paste(first_notfound, collapse = ", "))
+            msg2 <- paste0("Check the full list in ", notfound_file)
+
+            if (notfound == "error") {
+                stop(msg1, "\n", msg2)
+            } else if (notfound == "ignore") {
+                log$warn(msg1)
+                log$warn(msg2)
+            }
+        } else {
+            msg <- paste0("The following motifs were not found in the motif database: ", paste(first_notfound, collapse = ", "))
+            if (notfound == "error") {
+                stop(msg)
+            } else if (notfound == "ignore") {
+                log$warn(msg)
+            }
+        }
+
+        motifs <- setdiff(motifs, notfound_motifs)
+    }
+    return(motifs)
+}
+
+#' Plot a genomic region surrounding a genomic variant, and
+#' potentially disrupted motifs.
+#'
+#' @param results The motifbreakR results.
+#'  A GRanges object with the following columns:
+#'  - seqnames: Chromosome
+#'  - ranges: Start and end positions
+#'  - strand: Strand
+#'  -------------------
+#'  - SNP_id: Variant ID
+#'  - REF: Reference allele
+#'  - ALT: Alternative allele
+#'  - varType: Variant type. By default, "SNV"
+#'  - motifPos: Motif positions
+#'  - geneSymbol: Gene symbol, if not provided, try to get from the Regulator column
+#'  - dataSource: Motif database source
+#'  - providerName: Motif name
+#'  - providerId: Motif ID
+#'  - effect: Effect of the variant. By default, "strong"
+#'  - altPos: Alternative allele position. By default, 1
+#'  - alleleDiff: Allele difference, default 0, does not affect the plot for SNVs
+#'
+#'  Attributes:
+#'  - genome.package: Genome package name
+#'  - motifs: Motif database, in MotifDb::MotifList format
+#' @param variant Variant ID to be plotted
+#' @param devpars List of device parameters
+#'  - res: Resolution, default 100
+#'  - width: Width of the plot, default NULL, calculated based on sequence length
+#'  - height: Height of the plot, default NULL, calculated based on the number of motifs
+#' @param outdir Output directory. Plots will be saved in the sub-directory "<outdir>/plots/"
+#' @export
+plot_variant_motifs <- function(results, variant, devpars, outdir) {
+    plotdir <- file.path(outdir, "plots")
+    dir.create(plotdir, showWarnings = FALSE)
+
+    res <- results[results$SNP_id == variant, , drop = FALSE]
+    devpars <- devpars %||% list(res = 100, width = NULL, height = NULL)
+    if (length(res) == 0) {
+        stop(sprintf("Variant %s not found in results", variant))
+    }
+    devpars$res <- devpars$res %||% 100
+    devpars$height <- devpars$height %||% 2.4 * devpars$res + length(res) * 1.2 * devpars$res
+    if (is.null(devpars$width)) {
+        left <- min(sapply(res$motifPos, `[`, 1))
+        right <- max(sapply(res$motifPos, `[`, 2))
+        devpars$width <- 1.5 * devpars$res + (right - left) * 0.3 * devpars$res
+        devpars$width <- max(devpars$width, 5 * devpars$res)
+    }
+
+    plotfile <- file.path(plotdir, sprintf("%s.png", slugify(variant)))
+    # fix motifBreakR 2.12 using names to filter in plotMB
+    names(res) <- res$SNP_id
+    png(plotfile, width = devpars$width, height = devpars$height, res = devpars$res)
+    motifbreakR::plotMB(res, variant)
+    dev.off()
+}