name: "bedtools_subtract"
namespace: "bedtools"
version: "main"
authors:
- name: "Robrecht Cannoodt"
  roles:
  - "author"
  - "maintainer"
  info:
    links:
      email: "robrecht@data-intuitive.com"
      github: "rcannood"
      orcid: "0000-0003-3641-729X"
      linkedin: "robrechtcannoodt"
    organizations:
    - name: "Data Intuitive"
      href: "https://www.data-intuitive.com"
      role: "Data Science Engineer"
    - name: "Open Problems"
      href: "https://openproblems.bio"
      role: "Core Member"
argument_groups:
- name: "Inputs"
  arguments:
  - type: "file"
    name: "--input_a"
    alternatives:
    - "-a"
    description: "Input file A containing genomic intervals to subtract from.\n\n\
      **Format:** BED, GFF, or VCF file with genomic coordinates\n**Content:** Intervals\
      \ from which overlapping portions will be removed\n**Usage:** This is the primary\
      \ input file that will be modified\n**Requirements:** Standard genomic interval\
      \ format\n**Output:** Modified intervals with overlapping regions removed\n"
    info: null
    example:
    - "target_regions.bed"
    must_exist: true
    create_parent: true
    required: true
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--input_b"
    alternatives:
    - "-b"
    description: "Input file B containing genomic intervals to subtract.\n\n**Format:**\
      \ BED, GFF, or VCF file with genomic coordinates  \n**Content:** Intervals that\
      \ will be removed from file A\n**Usage:** Regions in this file will be subtracted\
      \ from input_a intervals\n**Requirements:** Standard genomic interval format\n\
      **Effect:** Any overlap with these intervals will be removed from A\n"
    info: null
    example:
    - "repetitive_elements.bed"
    must_exist: true
    create_parent: true
    required: true
    direction: "input"
    multiple: false
    multiple_sep: ";"
- name: "Outputs"
  arguments:
  - type: "file"
    name: "--output"
    description: "Output file with subtracted intervals.\n\n**Format:** Same format\
      \ as input file A\n**Content:** Modified intervals from A with B regions removed\n\
      **Behavior:** Only non-overlapping portions of A intervals are retained\n**Special\
      \ cases:** Intervals completely overlapped by B are omitted entirely\n"
    info: null
    example:
    - "filtered_regions.bed"
    must_exist: true
    create_parent: true
    required: true
    direction: "output"
    multiple: false
    multiple_sep: ";"
- name: "Overlap Options"
  arguments:
  - type: "double"
    name: "--min_overlap_a"
    alternatives:
    - "-f"
    description: "Minimum overlap required as a fraction of A interval.\n\n**Default:**\
      \ 1E-9 (essentially 1 base pair)\n**Range:** 0.0 to 1.0\n**Usage:** B must overlap\
      \ at least this fraction of A for subtraction\n**Example:** 0.5 requires B to\
      \ overlap at least 50% of A interval\n"
    info: null
    example:
    - 0.1
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "double"
    name: "--min_overlap_b"
    alternatives:
    - "-F"
    description: "Minimum overlap required as a fraction of B interval.\n\n**Default:**\
      \ 1E-9 (essentially 1 base pair)\n**Range:** 0.0 to 1.0\n**Usage:** A must overlap\
      \ at least this fraction of B for subtraction\n**Example:** 0.3 requires A to\
      \ overlap at least 30% of B interval\n"
    info: null
    example:
    - 0.1
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--reciprocal"
    alternatives:
    - "-r"
    description: "Require that the fraction overlap be reciprocal for A AND B.\n\n\
      **Usage:** Both A and B must overlap each other by the specified fractions\n\
      **Example:** With -f 0.9, B must overlap 90% of A AND A must overlap 90% of\
      \ B\n**Effect:** More stringent overlap requirement than -f or -F alone\n**Default:**\
      \ false (only one-way overlap required)\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--either_overlap"
    alternatives:
    - "-e"
    description: "Require that the minimum fraction be satisfied for A OR B.\n\n**Usage:**\
      \ Either the -f fraction OR the -F fraction must be satisfied\n**Example:**\
      \ With -f 0.9 and -F 0.1, either 90% of A OR 10% of B must be covered\n**Default:**\
      \ false (both fractions must be satisfied if both specified)\n"
    info: null
    direction: "input"
- name: "Strand Options"
  arguments:
  - type: "boolean_true"
    name: "--same_strand"
    alternatives:
    - "-s"
    description: "Require same strandedness for overlap detection.\n\n**Usage:** Only\
      \ subtract B intervals that overlap A on the same strand\n**Applications:**\
      \ Strand-specific analysis, gene annotation filtering\n**Default:** false (overlaps\
      \ reported without respect to strand)\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--opposite_strand"
    alternatives:
    - "-S"
    description: "Require different strandedness for overlap detection.\n\n**Usage:**\
      \ Only subtract B intervals that overlap A on the opposite strand\n**Applications:**\
      \ Antisense filtering, strand-specific exclusions\n**Default:** false (overlaps\
      \ reported without respect to strand)\n"
    info: null
    direction: "input"
- name: "Subtraction Behavior"
  arguments:
  - type: "boolean_true"
    name: "--remove_entire"
    alternatives:
    - "-A"
    description: "Remove entire feature if any overlap is found.\n\n**Behavior:**\
      \ Instead of partial subtraction, remove entire A interval if any overlap with\
      \ B\n**Usage:** Binary filtering - intervals are either kept completely or removed\
      \ completely\n**Applications:** Quality filtering, blacklist exclusion\n**Default:**\
      \ false (only overlapping portions are subtracted)\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--remove_if_all_overlap"
    alternatives:
    - "-N"
    description: "Remove entire feature based on sum of all B feature overlaps.\n\n\
      **Usage:** Same as -A but considers cumulative overlap from multiple B features\n\
      **Behavior:** Remove A if total overlap from all B features meets threshold\n\
      **Applications:** Complex filtering based on multiple overlapping annotations\n\
      **Requires:** Used with -f option for fraction threshold\n"
    info: null
    direction: "input"
- name: "Output Format Options"
  arguments:
  - type: "boolean_true"
    name: "--write_original_b"
    alternatives:
    - "-wb"
    description: "Write the original entry in B for each overlap.\n\n**Output:** Each\
      \ A interval followed by overlapping B intervals\n**Usage:** Track which B features\
      \ caused the subtraction\n**Restrictions:** Overlap filtering by -f and -r still\
      \ applies\n**Applications:** Detailed overlap reporting, annotation tracking\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--write_overlap_counts"
    alternatives:
    - "-wo"
    description: "Write original A and B entries plus the number of base pairs of\
      \ overlap.\n\n**Output:** A interval, B interval, and overlap count in base\
      \ pairs\n**Usage:** Quantify the extent of overlap between features\n**Filtering:**\
      \ Only A features with overlap are reported\n**Applications:** Overlap statistics,\
      \ coverage analysis\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--output_bed"
    alternatives:
    - "-bed"
    description: "Convert BAM input to BED format output.\n\n**Usage:** Only applicable\
      \ when input is BAM format\n**Effect:** Output genomic coordinates in BED format\n\
      **Applications:** Converting alignment data to interval format\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--include_header"
    alternatives:
    - "-header"
    description: "Print the header from the A file prior to results.\n\n**Usage:**\
      \ Preserves metadata and format information from input\n**Applications:** Maintaining\
      \ file structure and annotations\n**Formats:** Particularly relevant for VCF\
      \ and GFF files\n"
    info: null
    direction: "input"
- name: "Performance Options"
  arguments:
  - type: "boolean_true"
    name: "--use_split"
    alternatives:
    - "-split"
    description: "Treat \"split\" BAM or BED12 entries as distinct BED intervals.\n\
      \n**Usage:** Split complex entries into individual intervals\n**Applications:**\
      \ Detailed analysis of spliced alignments or multi-part features\n**Formats:**\
      \ Applies to BAM alignments and BED12 format\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--sorted_input"
    alternatives:
    - "-sorted"
    description: "Use the \"chromsweep\" algorithm for sorted input.\n\n**Requirements:**\
      \ Input must be sorted by chromosome then start coordinate\n**Performance:**\
      \ Much faster for large sorted files\n**Usage:** Optimize processing for pre-sorted\
      \ genomic data\n**Sort command:** sort -k1,1 -k2,2n input.bed\n"
    info: null
    direction: "input"
  - type: "file"
    name: "--genome_file"
    alternatives:
    - "-g"
    description: "Genome file to enforce consistent chromosome sort order.\n\n**Format:**\
      \ Tab-delimited file with chromosome names and lengths\n**Usage:** Only applies\
      \ when used with -sorted option\n**Purpose:** Ensure consistent chromosome ordering\
      \ across input files\n**Example:** chr1\\t249250621\n"
    info: null
    example:
    - "genome.txt"
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--no_name_check"
    alternatives:
    - "-nonamecheck"
    description: "Don't throw error for different chromosome naming conventions.\n\
      \n**Usage:** For sorted data with mixed naming (e.g., \"chr1\" vs \"chr01\"\
      )\n**Applications:** Working with data from different sources\n**Safety:** Allows\
      \ processing despite naming inconsistencies\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--no_buffer"
    alternatives:
    - "-nobuf"
    description: "Disable output buffering for real-time processing.\n\n**Effect:**\
      \ Each line printed immediately instead of buffered\n**Trade-off:** Slower output\
      \ but enables real-time processing\n**Applications:** Pipeline integration,\
      \ streaming analysis\n"
    info: null
    direction: "input"
  - type: "string"
    name: "--input_buffer"
    alternatives:
    - "-iobuf"
    description: "Amount of memory to allocate for input buffer.\n\n**Format:** Integer\
      \ with optional K/M/G suffix\n**Examples:** \"1G\", \"512M\", \"2048K\"\n**Usage:**\
      \ Larger buffers can improve I/O performance for large files\n**Note:** Currently\
      \ has no effect with compressed files\n"
    info: null
    example:
    - "1G"
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
resources:
- type: "bash_script"
  path: "script.sh"
  is_executable: true
description: "Remove the portion(s) of genomic intervals that are overlapped by other\
  \ features.\n\nbedtools subtract removes portions of intervals in file A that overlap\
  \ with intervals \nin file B. By default, only the overlapping portions are removed,\
  \ leaving the \nnon-overlapping parts of A intervals. This is essential for genomic\
  \ analysis tasks \nlike removing repetitive elements, excluding known variants,\
  \ or filtering out \nunwanted regions from interval datasets.\n\nThis tool is commonly\
  \ used for:\n- Removing repetitive elements or low-complexity regions from analysis\n\
  - Excluding known polymorphic sites from variant calling regions\n- Filtering out\
  \ blacklisted genomic regions from ChIP-seq peaks\n- Creating clean interval sets\
  \ by removing overlapping annotations\n- Generating non-overlapping genomic windows\
  \ for analysis\n- Quality control by removing problematic genomic regions\n"
test_resources:
- type: "bash_script"
  path: "test.sh"
  is_executable: true
- type: "file"
  path: "test_helpers.sh"
info: null
status: "enabled"
scope:
  image: "public"
  target: "public"
requirements:
  commands:
  - "bedtools"
  - "ps"
keywords:
- "genomics"
- "intervals"
- "subtract"
- "remove"
- "overlap"
- "filter"
- "exclusion"
license: "MIT"
references:
  doi:
  - "10.1093/bioinformatics/btq033"
links:
  repository: "https://github.com/arq5x/bedtools2"
  homepage: "https://bedtools.readthedocs.io/en/latest/content/tools/subtract.html"
  documentation: "https://bedtools.readthedocs.io/en/latest/content/tools/subtract.html"
runners:
- type: "executable"
  id: "executable"
  docker_setup_strategy: "ifneedbepullelsecachedbuild"
- type: "nextflow"
  id: "nextflow"
  directives:
    tag: "$id"
  auto:
    simplifyInput: true
    simplifyOutput: false
    transcript: false
    publish: false
  config:
    labels:
      mem1gb: "memory = 1000000000.B"
      mem2gb: "memory = 2000000000.B"
      mem5gb: "memory = 5000000000.B"
      mem10gb: "memory = 10000000000.B"
      mem20gb: "memory = 20000000000.B"
      mem50gb: "memory = 50000000000.B"
      mem100gb: "memory = 100000000000.B"
      mem200gb: "memory = 200000000000.B"
      mem500gb: "memory = 500000000000.B"
      mem1tb: "memory = 1000000000000.B"
      mem2tb: "memory = 2000000000000.B"
      mem5tb: "memory = 5000000000000.B"
      mem10tb: "memory = 10000000000000.B"
      mem20tb: "memory = 20000000000000.B"
      mem50tb: "memory = 50000000000000.B"
      mem100tb: "memory = 100000000000000.B"
      mem200tb: "memory = 200000000000000.B"
      mem500tb: "memory = 500000000000000.B"
      mem1gib: "memory = 1073741824.B"
      mem2gib: "memory = 2147483648.B"
      mem4gib: "memory = 4294967296.B"
      mem8gib: "memory = 8589934592.B"
      mem16gib: "memory = 17179869184.B"
      mem32gib: "memory = 34359738368.B"
      mem64gib: "memory = 68719476736.B"
      mem128gib: "memory = 137438953472.B"
      mem256gib: "memory = 274877906944.B"
      mem512gib: "memory = 549755813888.B"
      mem1tib: "memory = 1099511627776.B"
      mem2tib: "memory = 2199023255552.B"
      mem4tib: "memory = 4398046511104.B"
      mem8tib: "memory = 8796093022208.B"
      mem16tib: "memory = 17592186044416.B"
      mem32tib: "memory = 35184372088832.B"
      mem64tib: "memory = 70368744177664.B"
      mem128tib: "memory = 140737488355328.B"
      mem256tib: "memory = 281474976710656.B"
      mem512tib: "memory = 562949953421312.B"
      cpu1: "cpus = 1"
      cpu2: "cpus = 2"
      cpu5: "cpus = 5"
      cpu10: "cpus = 10"
      cpu20: "cpus = 20"
      cpu50: "cpus = 50"
      cpu100: "cpus = 100"
      cpu200: "cpus = 200"
      cpu500: "cpus = 500"
      cpu1000: "cpus = 1000"
  debug: false
  container: "docker"
engines:
- type: "docker"
  id: "docker"
  image: "quay.io/biocontainers/bedtools:2.31.1--h13024bc_3"
  target_registry: "images.viash-hub.com"
  target_tag: "main"
  namespace_separator: "/"
  setup:
  - type: "docker"
    run:
    - "bedtools --version 2>&1 | head -1 | sed 's/.*bedtools v/bedtools: /' > /var/software_versions.txt\n"
  entrypoint: []
  cmd: null
- type: "native"
  id: "native"
build_info:
  config: "src/bedtools/bedtools_subtract/config.vsh.yaml"
  runner: "executable"
  engine: "docker|native"
  output: "target/executable/bedtools/bedtools_subtract"
  executable: "target/executable/bedtools/bedtools_subtract/bedtools_subtract"
  viash_version: "0.9.4"
  git_commit: "9991e9a4f5ddd5085a4e2becf962950b1daf594b"
  git_remote: "https://github.com/viash-hub/biobox"
package_config:
  name: "biobox"
  version: "main"
  summary: "A curated collection of high-quality, standalone bioinformatics components\
    \ built with [Viash](https://viash.io).\n"
  description: "`biobox` offers a suite of reliable bioinformatics components, similar\
    \ to [nf-core/modules](https://github.com/nf-core/modules) and [snakemake-wrappers/bio](https://github.com/snakemake/snakemake-wrappers/tree/master/bio),\
    \ but built using the [Viash](https://viash.io) framework.\n\nThis approach emphasizes\
    \ **reusability**, **reproducibility**, and adherence to **best practices**. Key\
    \ features of `biobox` components include:\n\n* **Standalone & Nextflow Ready:**\
    \ Run components directly via the command line or seamlessly integrate them into\
    \ Nextflow workflows.\n* **High Quality Standards:**\n    * Comprehensive documentation\
    \ for components and parameters.\n    * Full exposure of underlying tool arguments.\n\
    \    * Containerized (Docker) for dependency management and reproducibility.\n\
    \    * Unit tested for verified functionality.\n"
  info: null
  viash_version: "0.9.4"
  source: "src"
  target: "target"
  config_mods:
  - ".requirements.commands += ['ps']\n"
  - ".engines += { type: \"native\" }"
  - ".engines[.type == 'docker'].target_registry := 'images.viash-hub.com'"
  - ".engines[.type == 'docker'].target_tag := 'main'"
  keywords:
  - "bioinformatics"
  - "modules"
  - "sequencing"
  license: "MIT"
  organization: "vsh"
  links:
    repository: "https://github.com/viash-hub/biobox"
    issue_tracker: "https://github.com/viash-hub/biobox/issues"
