flexify_cli.R

#!/usr/bin/env Rscript
# =============================================================================
# Flexify — Command-Line Interface
# =============================================================================
#
# A command-line wrapper for the Flexify probe design pipeline. Supports three
# modes: probe design from Arriba input, BLAST off-target filtering, and
# handle/barcode appending to generate final synthesis-ready sequences.
#
# USAGE:
#
#   Mode 1 — Design probes (default):
#     Rscript flexify_cli.R --input fusions.csv --output probes.csv
#     Rscript flexify_cli.R -i fusions.csv -o probes.csv --restraint 5 --mrna
#
#   Mode 2 — BLAST off-target check:
#     Rscript flexify_cli.R --mode blast \
#       --input probes.csv --blast-db /path/to/transcriptome_db \
#       --output probes_filtered.csv
#
#   Mode 3 — Append handles (v1, with barcode):
#     Rscript flexify_cli.R --mode finalise \
#       --input selected_probes.csv --output final_probes.csv
#
#     Input CSV columns required: GENE1, GENE2, probe, Barcode (integer 1-16 or "BC001"-"BC016")
#
#   Mode 3 — Append handles (v2, no barcode):
#     Rscript flexify_cli.R --mode finalise --assay-version v2 \
#       --input selected_probes.csv --output final_probes.csv
#
#     Optionally set --rhs-mode singleplex for the 4-sample kit tail (default: multiplex).
#     Input CSV columns required: GENE1, GENE2, probe (no Barcode column needed)
#
# DEPENDENCIES:
#   optparse, tidyverse, stringr
#   flexify_core.R, flexify_offtarget.R, flexify_handles.R must be in the
#   same directory as this script.
# =============================================================================

suppressPackageStartupMessages({
  library(optparse)
  library(tidyverse)
  library(stringr)
})

# Locate the directory containing this script so helper modules can be sourced
# regardless of where the script is called from.
script_dir <- tryCatch(
  dirname(normalizePath(sys.frame(1)$ofile)),
  error = function(e) getwd()
)

source(file.path(script_dir, "flexify_core.R"))
source(file.path(script_dir, "flexify_nonfusion.R"))
source(file.path(script_dir, "flexify_offtarget.R"))
source(file.path(script_dir, "flexify_handles.R"))


# =============================================================================
# ARGUMENT DEFINITIONS
# =============================================================================

option_list <- list(

  # --- General ---------------------------------------------------------------
  make_option(c("-i", "--input"),
              type    = "character",
              default = NULL,
              help    = "Path to input CSV file [required]",
              metavar = "FILE"),

  make_option(c("-o", "--output"),
              type    = "character",
              default = NULL,
              help    = "Path for output CSV file [required]",
              metavar = "FILE"),

  make_option(c("-m", "--mode"),
              type    = "character",
              default = "design",
              help    = "Pipeline mode: 'design', 'blast', or 'finalise' [default: design]",
              metavar = "MODE"),

  make_option("--nonfusion",
              action  = "store_true",
              default = FALSE,
              help    = "Run non-fusion probe design: input CSV must have 'gene' and 'sequence' columns [default: FALSE]"),

  make_option("--arriba",
              action  = "store_true",
              default = FALSE,
              help    = "Treat --input as an Arriba TSV file (auto-parses gene names and fusion_transcript column) [default: FALSE]"),

  # --- Design mode options ---------------------------------------------------
  make_option("--restraint",
              type    = "integer",
              default = 5L,
              help    = "Minimum bases each gene must contribute to a probe half [default: 5]",
              metavar = "INT"),

  make_option("--mrna",
              action  = "store_true",
              default = FALSE,
              help    = "Include mRNA target sequence column in output [default: FALSE]"),

  make_option("--prioritise-rhs",
              action  = "store_true",
              default = FALSE,
              help    = "Apply 0.7x score penalty to probes with junction in left half [default: FALSE]"),

  make_option("--no-asterix",
              action  = "store_true",
              default = FALSE,
              help    = "Do not mark the fusion breakpoint with '*' in output [default: FALSE]"),

  make_option("--no-halves",
              action  = "store_true",
              default = FALSE,
              help    = "Do not mark probe half boundary with '|' in output [default: FALSE]"),

  # --- BLAST mode options ----------------------------------------------------
  make_option("--blast-db",
              type    = "character",
              default = NULL,
              help    = "Path to BLAST nucleotide database (no extension) [required for blast mode]",
              metavar = "PATH"),

  make_option("--min-mismatches",
              type    = "integer",
              default = 5L,
              help    = "Minimum mismatches to off-target for a probe to pass [default: 5]",
              metavar = "INT"),

  make_option("--threads",
              type    = "integer",
              default = 1L,
              help    = "Number of BLAST threads [default: 1]",
              metavar = "INT"),

  make_option("--keep-fails",
              action  = "store_true",
              default = FALSE,
              help    = "Keep probes that fail off-target check (adds flag columns but does not filter) [default: FALSE]"),

  # --- Finalise mode options -------------------------------------------------
  make_option("--assay-version",
              type    = "character",
              default = "v1",
              help    = "Assay version for finalise mode: 'v1' (Chromium Flex, barcode embedded), 'v2' (GEM-X Flex, no barcode), or 'visium' (Visium FFPE / CytAssist, poly-A tail) [default: v1]",
              metavar = "VERSION"),

  make_option("--rhs-mode",
              type    = "character",
              default = "multiplex",
              help    = "v2 RHS tail configuration: 'multiplex' (CCCATATAAGAAA) or 'singleplex' (CGGTCCTAGCAA) [default: multiplex]",
              metavar = "MODE")
)

# Parse arguments
opt_parser <- OptionParser(
  option_list  = option_list,
  description  = "\nFlexify: automated fusion probe design for 10x Genomics Flex.",
  epilogue     = paste(
    "Examples:",
    "  Rscript flexify_cli.R -i fusions.csv -o probes.csv",
    "  Rscript flexify_cli.R --mode blast -i probes.csv --blast-db /path/db -o filtered.csv",
    "  Rscript flexify_cli.R --mode finalise -i selected.csv -o final.csv",
    sep = "\n"
  )
)
opt <- parse_args(opt_parser)


# =============================================================================
# INPUT VALIDATION
# =============================================================================

if (is.null(opt$input)) {
  stop("--input is required. Run with --help for usage.")
}
if (!file.exists(opt$input)) {
  stop("Input file not found: ", opt$input)
}
if (is.null(opt$output)) {
  stop("--output is required. Run with --help for usage.")
}
if (!opt$mode %in% c("design", "blast", "finalise")) {
  stop("--mode must be one of: design, blast, finalise. Got: ", opt$mode)
}


# =============================================================================
# MODE: DESIGN
# Run probe design pipeline from an Arriba-derived fusion CSV.
# =============================================================================

if (opt$mode == "design") {
  message("Flexify | Mode: design")
  message("  Input:   ", opt$input)
  message("  Output:  ", opt$output)

  if (isTRUE(opt$nonfusion)) {
    # ------------------------------------------------------------------
    # Non-fusion design: tile probes across a wild-type transcript
    # Input CSV: gene, sequence
    # ------------------------------------------------------------------
    message("  Probe type: non-fusion")

    input_df <- read.csv(opt$input, stringsAsFactors = FALSE)
    message("  Genes in input: ", nrow(input_df))

    output_df <- tryCatch(
      create_nonfusion_probes(
        input_df,
        PROBE_HALVES_FLAG = !isTRUE(opt[["no-halves"]]),
        MRNA_FLAG         = isTRUE(opt$mrna)
      ),
      error = function(e) stop("Non-fusion probe design failed: ", conditionMessage(e))
    )

  } else {
    # ------------------------------------------------------------------
    # Fusion design: probes spanning a gene fusion junction
    # Input CSV: gene1, gene2, gene1_transcript, gene2_transcript
    # ------------------------------------------------------------------
    message("  Probe type: fusion")
    message("  Restraint constant: ", opt$restraint)

    if (isTRUE(opt$arriba)) {
      message("  Input format: Arriba TSV")
      cleaned_df <- tryCatch(
        parse_arriba_tsv(opt$input),
        error = function(e) stop("Arriba TSV parsing failed: ", conditionMessage(e))
      )
    } else {
      message("  Input format: generic CSV")
      raw_df <- read.csv(opt$input, stringsAsFactors = FALSE)
      cleaned_df <- tryCatch(
        process_arriba_transcript(raw_df),
        error = function(e) stop("Input validation failed: ", conditionMessage(e))
      )
    }

    message("  Fusions in input: ", nrow(cleaned_df))

    output_df <- tryCatch(
      create_probes_from_arriba(
        cleaned_df,
        RESTRAINT_CONST     = opt$restraint,
        PRIORITISE_RHS_FLAG = isTRUE(opt[["prioritise-rhs"]]),
        ASTERIX_FLAG        = !isTRUE(opt[["no-asterix"]]),
        PROBE_HALVES_FLAG   = !isTRUE(opt[["no-halves"]]),
        MRNA_FLAG           = isTRUE(opt$mrna)
      ),
      error = function(e) stop("Probe design failed: ", conditionMessage(e))
    )
  }

  write.csv(output_df, opt$output, row.names = FALSE)
  message("Done. ", nrow(output_df), " candidate probes written to: ", opt$output)
}


# =============================================================================
# MODE: BLAST
# Run BLAST off-target check on a ranked probe CSV.
# =============================================================================

if (opt$mode == "blast") {
  message("Flexify | Mode: blast off-target check")
  message("  Input:    ", opt$input)
  message("  BLAST db: ", opt[["blast-db"]])
  message("  Output:   ", opt$output)

  if (is.null(opt[["blast-db"]])) {
    stop("--blast-db is required in blast mode. Provide the path to your BLAST database.")
  }

  probe_df <- read.csv(opt$input, stringsAsFactors = FALSE)
  message("  Probes loaded: ", nrow(probe_df))

  if (isTRUE(opt$nonfusion)) {
    message("  Probe type: non-fusion (checking both halves independently)")
    filtered_df <- tryCatch(
      run_offtarget_check_nonfusion(
        probe_df       = probe_df,
        blast_db       = opt[["blast-db"]],
        min_mismatches = opt[["min-mismatches"]],
        n_threads      = opt$threads,
        filter_fails   = !isTRUE(opt[["keep-fails"]])
      ),
      error = function(e) stop("BLAST check failed: ", conditionMessage(e))
    )
  } else {
    message("  Probe type: fusion (checking junction half only)")
    filtered_df <- tryCatch(
      run_offtarget_check(
        probe_df       = probe_df,
        blast_db       = opt[["blast-db"]],
        min_mismatches = opt[["min-mismatches"]],
        n_threads      = opt$threads,
        filter_fails   = !isTRUE(opt[["keep-fails"]])
      ),
      error = function(e) stop("BLAST check failed: ", conditionMessage(e))
    )
  }

  write.csv(filtered_df, opt$output, row.names = FALSE)
  message("Done. ", nrow(filtered_df), " probes written to: ", opt$output)
}


# =============================================================================
# MODE: FINALISE
# Append handle sequences and barcodes to a user-selected probe CSV.
# Input CSV must have columns: GENE1, GENE2, probe, Barcode (1-16 or BC001-BC016).
# If a 'Selected' column is present, only rows with Selected == TRUE are processed.
# =============================================================================

if (opt$mode == "finalise") {

  assay_ver <- opt[["assay-version"]]
  if (!assay_ver %in% c("v1", "v2", "visium")) {
    stop("--assay-version must be 'v1', 'v2', or 'visium'. Got: ", assay_ver)
  }
  is_v2     <- assay_ver == "v2"
  is_visium <- assay_ver == "visium"

  rhs_mode <- opt[["rhs-mode"]]
  if (is_v2 && !rhs_mode %in% c("multiplex", "singleplex")) {
    stop("--rhs-mode must be 'multiplex' or 'singleplex'. Got: ", rhs_mode)
  }

  message("Flexify | Mode: finalise (append handles)")
  message("  Input:         ", opt$input)
  message("  Output:        ", opt$output)
  message("  Assay version: ", assay_ver)
  if (is_v2) message("  RHS mode:      ", rhs_mode)

  input_df <- read.csv(opt$input, stringsAsFactors = FALSE)

  # If a Selected column exists, filter to marked rows only
  if ("Selected" %in% colnames(input_df)) {
    n_before <- nrow(input_df)
    input_df <- input_df[which(input_df$Selected == TRUE | input_df$Selected == "TRUE"), ]
    message("  Filtered to Selected == TRUE: ", nrow(input_df), " of ", n_before, " rows")
  }

  if (nrow(input_df) == 0) {
    stop("No rows to process. If a 'Selected' column is present, ensure some rows are TRUE.")
  }

  if (isTRUE(opt$nonfusion)) {
    # Non-fusion: single GENE column, no GENE1/GENE2
    required <- if (is_v2 || is_visium) c("GENE", "probe") else c("GENE", "probe", "Barcode")
    missing  <- setdiff(required, colnames(input_df))
    if (length(missing) > 0) {
      stop("Input CSV is missing required columns: ", paste(missing, collapse = ", "))
    }

    final_df <- tryCatch(
      if (is_visium) finalise_nonfusion_probes_visium(input_df)
      else if (is_v2) finalise_nonfusion_probes_v2(input_df, rhs_mode = rhs_mode)
      else            finalise_nonfusion_probes(input_df),
      error = function(e) stop("Finalise failed: ", conditionMessage(e))
    )

    message("Done. ", nrow(final_df), " probe sequences written to: ", opt$output)
    message("  Each gene produces one LHS and one RHS oligonucleotide.")

  } else {
    # Fusion: GENE1 + GENE2 columns
    required <- if (is_v2 || is_visium) c("GENE1", "GENE2", "probe") else c("GENE1", "GENE2", "probe", "Barcode")
    missing  <- setdiff(required, colnames(input_df))
    if (length(missing) > 0) {
      stop("Input CSV is missing required columns: ", paste(missing, collapse = ", "))
    }

    final_df <- tryCatch(
      if (is_visium) finalise_probes_visium(input_df)
      else if (is_v2) finalise_probes_v2(input_df, rhs_mode = rhs_mode)
      else            finalise_probes(input_df),
      error = function(e) stop("Finalise failed: ", conditionMessage(e))
    )

    message("Done. ", nrow(final_df), " probe sequences written to: ", opt$output)
    message("  Each fusion produces one LHS and one RHS oligonucleotide.")
  }

  write.csv(final_df, opt$output, row.names = FALSE)
}