{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "bedtools_shuffle",
  "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",
  "type": "object",
  "$defs": {
    "inputs": {
      "title": "Inputs",
      "type": "object",
      "description": "No description",
      "properties": {
        "input": {
          "type": "string",
          "format": "path",
          "exists": true,
          "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",
          "help_text": "Type: `file`, multiple: `False`, required, direction: `input`, example: `\"features.bed\"`. "
        },
        "genome": {
          "type": "string",
          "format": "path",
          "exists": true,
          "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",
          "help_text": "Type: `file`, multiple: `False`, required, direction: `input`, example: `\"hg19.genome\"`. "
        },
        "exclude": {
          "type": "string",
          "format": "path",
          "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",
          "help_text": "Type: `file`, multiple: `False`, direction: `input`, example: `\"gaps.bed\"`. "
        },
        "include": {
          "type": "string",
          "format": "path",
          "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",
          "help_text": "Type: `file`, multiple: `False`, direction: `input`, example: `\"accessible_regions.bed\"`. "
        }
      }
    },
    "outputs": {
      "title": "Outputs",
      "type": "object",
      "description": "No description",
      "properties": {
        "output": {
          "type": "string",
          "format": "path",
          "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",
          "help_text": "Type: `file`, multiple: `False`, required, default: `\"$id.$key.output.bed\"`, direction: `output`, example: `\"shuffled_features.bed\"`. ",
          "default": "$id.$key.output.bed"
        }
      }
    },
    "shuffling options": {
      "title": "Shuffling Options",
      "type": "object",
      "description": "No description",
      "properties": {
        "keep_chromosome": {
          "type": "boolean",
          "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",
          "help_text": "Type: `boolean_true`, multiple: `False`, default: `false`. ",
          "default": false
        },
        "chrom_first": {
          "type": "boolean",
          "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",
          "help_text": "Type: `boolean_true`, multiple: `False`, default: `false`. ",
          "default": false
        },
        "seed": {
          "type": "integer",
          "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",
          "help_text": "Type: `integer`, multiple: `False`, example: `12345`. "
        }
      }
    },
    "overlap control": {
      "title": "Overlap Control",
      "type": "object",
      "description": "No description",
      "properties": {
        "max_overlap": {
          "type": "number",
          "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",
          "help_text": "Type: `double`, multiple: `False`, example: `0.1`. "
        },
        "no_overlapping": {
          "type": "boolean",
          "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",
          "help_text": "Type: `boolean_true`, multiple: `False`, default: `false`. ",
          "default": false
        },
        "max_tries": {
          "type": "integer",
          "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",
          "help_text": "Type: `integer`, multiple: `False`, example: `5000`. "
        }
      }
    },
    "format options": {
      "title": "Format Options",
      "type": "object",
      "description": "No description",
      "properties": {
        "bedpe_format": {
          "type": "boolean",
          "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",
          "help_text": "Type: `boolean_true`, multiple: `False`, default: `false`. ",
          "default": false
        },
        "allow_beyond_chrom_end": {
          "type": "boolean",
          "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",
          "help_text": "Type: `boolean_true`, multiple: `False`, default: `false`. ",
          "default": false
        }
      }
    },
    "nextflow input-output arguments": {
      "title": "Nextflow input-output arguments",
      "type": "object",
      "description": "Input/output parameters for Nextflow itself. Please note that both publishDir and publish_dir are supported but at least one has to be configured.",
      "properties": {
        "publish_dir": {
          "type": "string",
          "description": "Path to an output directory.",
          "help_text": "Type: `string`, multiple: `False`, required, example: `\"output/\"`. "
        }
      }
    }
  },
  "allOf": [
    {
      "$ref": "#/$defs/inputs"
    },
    {
      "$ref": "#/$defs/outputs"
    },
    {
      "$ref": "#/$defs/shuffling options"
    },
    {
      "$ref": "#/$defs/overlap control"
    },
    {
      "$ref": "#/$defs/format options"
    },
    {
      "$ref": "#/$defs/nextflow input-output arguments"
    }
  ]
}
