name: "bedtools_shuffle"
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"
    alternatives:
    - "-i"
    description: "Input file containing genomic intervals to shuffle.\n\n**Format:**\
      \ BED, GFF, VCF, or BEDPE file\n**Content:** Genomic intervals that will be\
      \ randomly relocated\n**Preservation:** Interval sizes and attributes are maintained\n\
      **Usage:** Each interval will be moved to a random genomic position\n"
    info: null
    example:
    - "features.bed"
    must_exist: true
    create_parent: true
    required: true
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--genome"
    alternatives:
    - "-g"
    description: "Genome file defining chromosome sizes for shuffling boundaries.\n\
      \n**Format:** Tab-delimited text file with chromosome names and sizes\n**Content:**\
      \ Each line contains: <chromName><TAB><chromSize>\n**Usage:** Defines valid\
      \ coordinate space for random placement\n**Creation:** Can be generated with\
      \ 'samtools faidx' or UCSC Table Browser\n**Example format:**\n  chr1    249250621\n\
      \  chr2    243199373\n"
    info: null
    example:
    - "hg19.genome"
    must_exist: true
    create_parent: true
    required: true
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--exclude"
    alternatives:
    - "-excl"
    description: "BED/GFF/VCF file defining regions where shuffled intervals should\
      \ NOT be placed.\n\n**Format:** BED, GFF, or VCF file with forbidden regions\n\
      **Content:** Genomic intervals to avoid during shuffling (e.g., gaps, repeats)\n\
      **Usage:** Shuffled intervals will avoid overlapping these regions\n**Applications:**\
      \ Exclude centromeres, gaps, repetitive elements\n**Interaction:** Cannot be\
      \ used together with --include\n"
    info: null
    example:
    - "gaps.bed"
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--include"
    alternatives:
    - "-incl"
    description: "BED/GFF/VCF file defining regions where shuffled intervals should\
      \ be placed.\n\n**Format:** BED, GFF, or VCF file with allowed regions\n**Content:**\
      \ Genomic intervals where shuffling is permitted (e.g., genes, accessible chromatin)\n\
      **Usage:** Shuffled intervals will only be placed within these regions\n**Effect:**\
      \ Disables --chrom_first option\n**Interaction:** Cannot be used together with\
      \ --exclude\n"
    info: null
    example:
    - "accessible_regions.bed"
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
- name: "Outputs"
  arguments:
  - type: "file"
    name: "--output"
    description: "Output file containing shuffled genomic intervals.\n\n**Format:**\
      \ Same format as input file\n**Content:** Original intervals with randomized\
      \ genomic coordinates\n**Preservation:** Interval sizes and non-coordinate attributes\
      \ maintained\n"
    info: null
    example:
    - "shuffled_features.bed"
    must_exist: true
    create_parent: true
    required: true
    direction: "output"
    multiple: false
    multiple_sep: ";"
- name: "Shuffling Options"
  arguments:
  - type: "boolean_true"
    name: "--keep_chromosome"
    alternatives:
    - "-chrom"
    description: "Keep shuffled intervals on their original chromosomes.\n\n**Effect:**\
      \ Intervals are randomly repositioned only within their source chromosome\n\
      **Default:** false (intervals can move to any chromosome)\n**Usage:** Preserves\
      \ chromosome-specific distributions\n**Note:** Automatically enables --chrom_first\
      \ option\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--chrom_first"
    alternatives:
    - "-chromFirst"
    description: "Select chromosome first, then random position within that chromosome.\n\
      \n**Effect:** Results in uniform distribution across chromosomes regardless\
      \ of size\n**Default:** false (positions chosen from entire genome space)\n\
      **Usage:** Prevents bias toward larger chromosomes\n**Disabled by:** --include\
      \ option\n"
    info: null
    direction: "input"
  - type: "integer"
    name: "--seed"
    description: "Integer seed for random number generation.\n\n**Usage:** Ensures\
      \ reproducible shuffling results\n**Range:** Any integer value\n**Default:**\
      \ Automatically chosen seed (non-reproducible)\n**Applications:** Reproducible\
      \ research, testing, validation\n"
    info: null
    example:
    - 12345
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
- name: "Overlap Control"
  arguments:
  - type: "double"
    name: "--max_overlap"
    alternatives:
    - "-f"
    description: "Maximum allowed overlap with excluded regions as fraction of interval\
      \ length.\n\n**Range:** 0.0 to 1.0\n**Default:** 1E-9 (essentially no overlap\
      \ allowed)\n**Usage:** Tolerance for overlap with --exclude regions\n**Example:**\
      \ 0.10 allows up to 10% overlap with excluded regions\n**Interaction:** Cannot\
      \ be used with --include\n"
    info: null
    example:
    - 0.1
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--no_overlapping"
    alternatives:
    - "-noOverlapping"
    description: "Prevent shuffled intervals from overlapping with each other.\n\n\
      **Effect:** Ensures no two shuffled intervals overlap\n**Applications:** Creating\
      \ non-redundant control datasets\n**Performance:** May require more placement\
      \ attempts\n**Default:** false (overlaps allowed)\n"
    info: null
    direction: "input"
  - type: "integer"
    name: "--max_tries"
    alternatives:
    - "-maxTries"
    description: "Maximum attempts to find valid placement for each interval.\n\n\
      **Default:** 1000\n**Usage:** Limits computation time when valid placements\
      \ are scarce\n**Applications:** Highly constrained shuffling with many restrictions\n\
      **Failure:** Intervals that cannot be placed after max tries are dropped\n"
    info: null
    example:
    - 5000
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
- name: "Format Options"
  arguments:
  - type: "boolean_true"
    name: "--bedpe_format"
    alternatives:
    - "-bedpe"
    description: "Treat input file as BEDPE format (paired-end intervals).\n\n**Usage:**\
      \ For paired-end sequencing data or interaction data\n**Effect:** Shuffles paired\
      \ intervals as units\n**Format:** BEDPE format with paired genomic coordinates\n\
      **Default:** false (standard BED/GFF/VCF format)\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--allow_beyond_chrom_end"
    alternatives:
    - "-allowBeyondChromEnd"
    description: "Allow shuffled intervals to extend beyond chromosome boundaries.\n\
      \n**Effect:** If interval cannot fit entirely, end coordinate set to chromosome\
      \ length\n**Default:** false (intervals must fit entirely within chromosomes)\n\
      **Applications:** When preserving interval start positions is more important\n\
      **Trade-off:** May alter interval sizes for intervals near chromosome ends\n"
    info: null
    direction: "input"
resources:
- type: "bash_script"
  path: "script.sh"
  is_executable: true
description: "Randomly shuffle the genomic locations of intervals while preserving\
  \ their size and structure.\n\nbedtools shuffle randomly relocates genomic intervals\
  \ to new positions within the genome\nwhile maintaining their original size and\
  \ other attributes. This tool is essential for \ncreating randomized control datasets\
  \ that preserve interval characteristics but eliminate\npositional bias.\n\nThis\
  \ tool is commonly used for:\n- Generating null distributions for statistical testing\n\
  - Creating randomized control datasets for enrichment analysis\n- Testing positional\
  \ significance of genomic features\n- Removing spatial clustering bias from interval\
  \ datasets\n- Permutation testing in comparative genomics\n- Background generation\
  \ for motif discovery and regulatory analysis\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"
- "shuffle"
- "random"
- "permutation"
- "controls"
- "statistics"
license: "MIT"
references:
  doi:
  - "10.1093/bioinformatics/btq033"
links:
  repository: "https://github.com/arq5x/bedtools2"
  homepage: "https://bedtools.readthedocs.io/en/latest/content/tools/shuffle.html"
  documentation: "https://bedtools.readthedocs.io/en/latest/content/tools/shuffle.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_shuffle/config.vsh.yaml"
  runner: "nextflow"
  engine: "docker|native"
  output: "target/nextflow/bedtools/bedtools_shuffle"
  executable: "target/nextflow/bedtools/bedtools_shuffle/main.nf"
  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"
