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

Type

bash_script

License

MIT

Keywords

genomics

intervals

shuffle

random

permutation

controls

statistics

Links

Repository

Documentation

Contributors

Launch

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

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

Name

Type & Properties

--input

-i

file

required

--genome

-g

file

required

--exclude

-excl

file

--include

-incl

file

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

Name

Type & Properties

--output

file

required

output

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

Name

Type & Properties

--keep_chromosome

-chrom

boolean_true

--chrom_first

-chromFirst

boolean_true

--seed

integer

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

Name

Type & Properties

--max_overlap

-f

double

--no_overlapping

-noOverlapping

boolean_true

--max_tries

-maxTries

integer

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

Name

Type & Properties

--bedpe_format

-bedpe

boolean_true

--allow_beyond_chrom_end

-allowBeyondChromEnd

boolean_true