bedtools/bedtools_closest
Closest
Nearest
Distance
BED
GFF
VCF
Association
Description
Find the closest feature in file B for each feature in file A.
For each interval in file A, this tool identifies the nearest feature in
file B, regardless of whether they overlap. Useful for associating genomic
features with their nearest neighbors, such as finding the closest gene
to each SNP or the nearest regulatory element to each promoter.
Default behavior: Reports closest feature regardless of strand or overlap
Distance reporting: Optional distance calculation with various orientations
Multiple hits: Configurable handling of ties and k-nearest neighbors
Inputs
Name | Type & Properties | Description |
|---|---|---|
--input_a -a | file required | Query file in BED, GFF, or VCF format. For each feature in this file, the closest feature in file B will be identified and reported. |
--input_b -b | file required multiple | Database file(s) in BED, GFF, or VCF format. **Single file:** Find closest features in one database **Multiple files:** Find closest features across multiple databases **Format:** Same or different format as input A |
Outputs
Name | Type & Properties | Description |
|---|---|---|
--output | file required output | Output file with closest feature results. Contains input A features with additional columns showing the closest features from file(s) B, and optionally distance and other metadata. |
Distance Options
Name | Type & Properties | Description |
|---|---|---|
--distance -d | boolean_true | Report distance to closest feature as extra column. **Distance calculation:** Always positive, 0 for overlapping features **Use case:** When you need quantitative proximity measurements |
--distance_mode -D | string | Report signed distance with orientation awareness. **"ref":** Distance relative to reference genome coordinates **"a":** Distance relative to strand of feature A **"b":** Distance relative to strand of feature B **Negative values:** Upstream features **Positive values:** Downstream features |
Filtering Options
Name | Type & Properties | Description |
|---|---|---|
--ignore_overlaps -io | boolean_true | Ignore overlapping features in B. Only consider features in B that do not overlap with A. Useful for finding nearby but non-overlapping features. |
--ignore_upstream -iu | boolean_true | Ignore upstream features in B. **Requires:** --distance_mode parameter **Effect:** Only consider downstream features **Orientation:** Follows --distance_mode orientation rules |
--ignore_downstream -id | boolean_true | Ignore downstream features in B. **Requires:** --distance_mode parameter **Effect:** Only consider upstream features **Orientation:** Follows --distance_mode orientation rules |
--force_upstream -fu | boolean_true | Choose first upstream feature when ties exist. **Requires:** --distance_mode parameter **Tie handling:** Among equally close features, prefer upstream **Orientation:** Follows --distance_mode orientation rules |
--force_downstream -fd | boolean_true | Choose first downstream feature when ties exist. **Requires:** --distance_mode parameter **Tie handling:** Among equally close features, prefer downstream **Orientation:** Follows --distance_mode orientation rules |
--strand -s | boolean_true | Require same strandedness. Only consider features in B that are on the same strand as the corresponding feature in A. |
--different_strand -S | boolean_true | Require different strandedness. Only consider features in B that are on the opposite strand from the corresponding feature in A. |
Advanced Options
Name | Type & Properties | Description |
|---|---|---|
--k_closest -k | integer | Report k closest hits for each query. **Default:** 1 (single closest feature) **Multiple hits:** Reports multiple closest features per query **Tie handling:** All ties still reported based on --tie_mode |
--tie_mode -t | string | How to handle ties for closest features. **"all":** Report all equally close features (default) **"first":** Report first tie found in file B **"last":** Report last tie found in file B |
--different_names -N | boolean_true | Require different names between query and hit. For BED files, compares the 4th column (name field). Useful to avoid self-hits in self-comparisons. |
Run this component
Run the following command to execute this component with Nextflow:
cat > params.yaml <<'EOM'
output: "$id.$key.output.bed"
k_closest: [ 1 ]
tie_mode: [ "all" ]
id: "run"
publish_dir: "output/"
EOM
nextflow run https://packages.viash-hub.com/vsh/biobox.git \
-revision v0.4.0 \
-main-script target/nextflow/bedtools/bedtools_closest/main.nf \
-params-file params.yaml Relationships
Used by
0 relationships
No components use this component.
Current component
bedtools/bedtools_closestbiobox v0.4.0
Uses
0 relationships
No component dependencies found.