subtract.rst 5.06 KB
Newer Older
Aaron's avatar
Aaron committed
1
###############
Aaron's avatar
Aaron committed
2
*subtract*
Aaron's avatar
Aaron committed
3
4
###############

5
|
Aaron's avatar
Aaron committed
6

7
8
9
10
11
12
13
14
15
16
17
18
.. image:: ../images/tool-glyphs/subtract-glyph.png 
    :width: 600pt 

|

``bedtools subtract`` searches for features in B that overlap A. If an 
overlapping feature is found in B, the overlapping portion is removed from A 
and the remaining portion of A is reported. If a feature in B overlaps all of a 
feature in A, the A feature will not be reported.


===============================
19
Usage and option summary
20
21
===============================
**Usage**:
Aaron's avatar
Aaron committed
22
::
23
24
25
26
27
28

  bedtools subtract [OPTIONS] -a <BED/GFF/VCF> -b <BED/GFF/VCF>

**(or)**:
::
  
Aaron's avatar
Aaron committed
29
  subtractBed [OPTIONS] -a <BED/GFF/VCF> -b <BED/GFF/VCF>
30
31


Aaron's avatar
Aaron committed
32
33
34
35
  
===========================      ===============================================================================================================================================================================================================
Option                           Description
===========================      ===============================================================================================================================================================================================================
arq5x's avatar
arq5x committed
36
37
**-f**				                   Minimum overlap required as a fraction of A. Default is 1E-9 (i.e. 1bp).
**-s**		                       Force "strandedness". That is, only report hits in B that overlap A on the same strand. By default, overlaps are reported without respect to strand.
38
39
**-S**	                         Require different strandedness.  That is, only report hits in B that overlap A on the _opposite_ strand. By default, overlaps are reported without respect to strand.
**-A**	                         Remove entire feature if any overlap.  That is, by default, only subtract the portion of A that overlaps B. Here, if any overlap is found (or ``-f`` amount), the entire feature is removed.
arq5x's avatar
arq5x committed
40
**-N**                           Same as -A except when used with -f, the amount is the sum of all features (not any single feature).
Aaron's avatar
Aaron committed
41
42
43
44
45
===========================      ===============================================================================================================================================================================================================



==========================================================================
46
Default behavior
Aaron's avatar
Aaron committed
47
========================================================================== 
48
49
50
51
52
53
54
By default, ``bedtools subtracts`` removes each overlapping interval in B
from A.  If a feature in B *completely* overlaps a feature in A, the A feature
is removed.

.. code-block:: bash

  $ cat A.bed
Aaron's avatar
Aaron committed
55
  chr1  10   20
56
  chr1  100  200
Aaron's avatar
Aaron committed
57

58
  $ cat B.bed
Aaron's avatar
Aaron committed
59
60
61
  chr1  0    30
  chr1  180  300

62
  $ bedtools subtract -a A.bed -b B.bed
Aaron's avatar
Aaron committed
63
64
65
66
67
68
69
70
  chr1  100  180
  
  
  
  
  

==========================================================================
71
``-f`` Requiring a minimal overlap fraction before subtracting
Aaron's avatar
Aaron committed
72
==========================================================================
73
74
75
76
77
This option behaves the same as the ``-f`` option for ``bedtools intersect``. 
In this case, ``subtract`` will only subtract an overlap with B if it covers at 
least the fraction of A defined by ``-f``. If an overlap is found,
but it does not meet the overlap fraction, the original A feature is 
reported without subtraction.
Aaron's avatar
Aaron committed
78

79
80
81
.. code-block:: bash

  $ cat A.bed
Aaron's avatar
Aaron committed
82
83
  chr1  100  200

84
  $ cat B.bed
Aaron's avatar
Aaron committed
85
86
  chr1  180  300

87
  $ bedtools subtract -a A.bed -b B.bed -f 0.10
Aaron's avatar
Aaron committed
88
89
  chr1  100  180

90
  $ bedtools subtract -a A.bed -b B.bed -f 0.80
Aaron's avatar
Aaron committed
91
92
93
94
95
96
  chr1  100  200




==========================================================================
97
``-s`` Enforcing same "strandedness" 
Aaron's avatar
Aaron committed
98
==========================================================================
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
This option behaves the same as the ``-s`` option for ``bedtools intersect`` 
while scanning for features in B that should be subtracted from A. 

.. code-block:: bash

  $ cat A.bed
  chr1  100  200    a1  1   +

  $ cat B.bed
  chr1  80   120    b1  1   +  
  chr1  180  300    b2  1   -

  $ bedtools subtract -a A.bed -b B.bed -s
  chr1  120  120    a1  1   +
  

==========================================================================
``-S`` Enforcing opposite "strandedness" 
==========================================================================
This option behaves the same as the ``-s`` option for ``bedtools intersect`` 
while scanning for features in B that should be subtracted from A. 

.. code-block:: bash

  $ cat A.bed
  chr1  100  200    a1  1   +

  $ cat B.bed
  chr1  80   120    b1  1   +  
  chr1  180  300    b2  1   -

  $ bedtools subtract -a A.bed -b B.bed -S
  chr1  100  180    a1  1   +
  

==========================================================================
``-A`` Remove features with any overlap
==========================================================================
Unlike the default behavior, the ``-A`` option will completely remove
a feature from A if it has even 1bp of overlap with a feature in B. 

.. code-block:: bash

  $ cat A.bed
  chr1  100  200

  $ cat B.bed
  chr1  180  300

  $ bedtools subtract -a A.bed -b B.bed
  chr1  100  180

  $ bedtools subtract -a A.bed -b B.bed -A
Aaron's avatar
Aaron committed
152
153
154
155