bedtools/bedtools_shuffle
genomics
intervals
shuffle
random
permutation
controls
statistics
Description
Randomly shuffle the genomic locations of intervals while preserving their size and structure.
bedtools shuffle randomly relocates genomic intervals to new positions within the genome
while maintaining their original size and other attributes. This tool is essential for
creating randomized control datasets that preserve interval characteristics but eliminate
positional bias.
This tool is commonly used for:
Generating null distributions for statistical testing
Creating randomized control datasets for enrichment analysis
Testing positional significance of genomic features
Removing spatial clustering bias from interval datasets
Permutation testing in comparative genomics
Background generation for motif discovery and regulatory analysis
Inputs
Name | Type & Properties | Description |
|---|---|---|
--input -i | file required | Input file containing genomic intervals to shuffle. **Format:** BED, GFF, VCF, or BEDPE file **Content:** Genomic intervals that will be randomly relocated **Preservation:** Interval sizes and attributes are maintained **Usage:** Each interval will be moved to a random genomic position |
--genome -g | file required | Genome file defining chromosome sizes for shuffling boundaries. **Format:** Tab-delimited text file with chromosome names and sizes **Content:** Each line contains: <chromName><TAB><chromSize> **Usage:** Defines valid coordinate space for random placement **Creation:** Can be generated with 'samtools faidx' or UCSC Table Browser **Example format:** chr1 249250621 chr2 243199373 |
--exclude -excl | file | BED/GFF/VCF file defining regions where shuffled intervals should NOT be placed. **Format:** BED, GFF, or VCF file with forbidden regions **Content:** Genomic intervals to avoid during shuffling (e.g., gaps, repeats) **Usage:** Shuffled intervals will avoid overlapping these regions **Applications:** Exclude centromeres, gaps, repetitive elements **Interaction:** Cannot be used together with --include |
--include -incl | file | BED/GFF/VCF file defining regions where shuffled intervals should be placed. **Format:** BED, GFF, or VCF file with allowed regions **Content:** Genomic intervals where shuffling is permitted (e.g., genes, accessible chromatin) **Usage:** Shuffled intervals will only be placed within these regions **Effect:** Disables --chrom_first option **Interaction:** Cannot be used together with --exclude |
Outputs
Name | Type & Properties | Description |
|---|---|---|
--output | file required output | Output file containing shuffled genomic intervals. **Format:** Same format as input file **Content:** Original intervals with randomized genomic coordinates **Preservation:** Interval sizes and non-coordinate attributes maintained |
Shuffling Options
Name | Type & Properties | Description |
|---|---|---|
--keep_chromosome -chrom | boolean_true | Keep shuffled intervals on their original chromosomes. **Effect:** Intervals are randomly repositioned only within their source chromosome **Default:** false (intervals can move to any chromosome) **Usage:** Preserves chromosome-specific distributions **Note:** Automatically enables --chrom_first option |
--chrom_first -chromFirst | boolean_true | Select chromosome first, then random position within that chromosome. **Effect:** Results in uniform distribution across chromosomes regardless of size **Default:** false (positions chosen from entire genome space) **Usage:** Prevents bias toward larger chromosomes **Disabled by:** --include option |
--seed | integer | Integer seed for random number generation. **Usage:** Ensures reproducible shuffling results **Range:** Any integer value **Default:** Automatically chosen seed (non-reproducible) **Applications:** Reproducible research, testing, validation |
Overlap Control
Name | Type & Properties | Description |
|---|---|---|
--max_overlap -f | double | Maximum allowed overlap with excluded regions as fraction of interval length. **Range:** 0.0 to 1.0 **Default:** 1E-9 (essentially no overlap allowed) **Usage:** Tolerance for overlap with --exclude regions **Example:** 0.10 allows up to 10% overlap with excluded regions **Interaction:** Cannot be used with --include |
--no_overlapping -noOverlapping | boolean_true | Prevent shuffled intervals from overlapping with each other. **Effect:** Ensures no two shuffled intervals overlap **Applications:** Creating non-redundant control datasets **Performance:** May require more placement attempts **Default:** false (overlaps allowed) |
--max_tries -maxTries | integer | Maximum attempts to find valid placement for each interval. **Default:** 1000 **Usage:** Limits computation time when valid placements are scarce **Applications:** Highly constrained shuffling with many restrictions **Failure:** Intervals that cannot be placed after max tries are dropped |
Format Options
Name | Type & Properties | Description |
|---|---|---|
--bedpe_format -bedpe | boolean_true | Treat input file as BEDPE format (paired-end intervals). **Usage:** For paired-end sequencing data or interaction data **Effect:** Shuffles paired intervals as units **Format:** BEDPE format with paired genomic coordinates **Default:** false (standard BED/GFF/VCF format) |
--allow_beyond_chrom_end -allowBeyondChromEnd | boolean_true | Allow shuffled intervals to extend beyond chromosome boundaries. **Effect:** If interval cannot fit entirely, end coordinate set to chromosome length **Default:** false (intervals must fit entirely within chromosomes) **Applications:** When preserving interval start positions is more important **Trade-off:** May alter interval sizes for intervals near chromosome ends |
Run this component
Run the following command to execute this component with Nextflow:
cat > params.yaml <<'EOM'
output: "$id.$key.output.bed"
id: "run"
publish_dir: "output/"
EOM
nextflow run https://packages.viash-hub.com/vsh/biobox.git \
-revision v0.4.1 \
-main-script target/nextflow/bedtools/bedtools_shuffle/main.nf \
-params-file params.yaml Relationships
Used by
0 relationships
No components use this component.
Current component
bedtools/bedtools_shufflebiobox v0.4.1
Uses
0 relationships
No component dependencies found.