1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
'\" t
.TH samtools-cat 1 "12 September 2024" "samtools-1.21" "Bioinformatics tools"
.SH NAME
samtools cat \- concatenate files together
.\"
.\" Copyright (C) 2008-2011, 2013-2018, 2024 Genome Research Ltd.
.\" Portions copyright (C) 2010, 2011 Broad Institute.
.\"
.\" Author: Heng Li <lh3@sanger.ac.uk>
.\" Author: Joshua C. Randall <jcrandall@alum.mit.edu>
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
.\" to deal in the Software without restriction, including without limitation
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
.\" and/or sell copies of the Software, and to permit persons to whom the
.\" Software is furnished to do so, subject to the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be included in
.\" all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.\" DEALINGS IN THE SOFTWARE.
.
.\" For code blocks and examples (cf groff's Ultrix-specific man macros)
.de EX
. in +\\$1
. nf
. ft CR
..
.de EE
. ft
. fi
. in
..
.
.SH SYNOPSIS
.PP
samtools cat
.RB [ -b
.IR list ]
.RB [ -h
.IR header.sam ]
.RB [ -o
.IR out.bam "] " in1.bam " " in2.bam " [ ... ]"
.SH DESCRIPTION
.PP
Concatenate BAMs or CRAMs. Although this works on either BAM or CRAM,
all input files must be the same format as each other. The sequence
dictionary of each input file must be identical, although this command
does not check this. This command uses a similar trick to
.B reheader
which enables fast BAM concatenation.
.SH OPTIONS
.TP 8
.BI "-b " FOFN
Read the list of input BAM or CRAM files from \fIFOFN\fR. These are
concatenated prior to any files specified on the command line.
Multiple \fB-b\fR \fIFOFN\fR options may be specified to concatenate
multiple lists of BAM/CRAM files.
.TP 8
.BI "-h " FILE
Uses the SAM header from \fIFILE\fR. By default the header is taken
from the first file to be concatenated.
.TP 8
.BI "-o " FILE
Write the concatenated output to \fIFILE\fR. By default this is sent
to stdout.
.TP 8
.B -q
[CRAM only] Query the number of containers in the CRAM file. The
output is the filename, the number of containers, and the first and
last container number as an inclusive range, with one file per line.
Note this works in conjunction with the \fB-r \fIRANGE\fR option, in
which case the 3rd and 4th columns become useful for identifying which
containers span the requested range.
.TP
.BI "-r " RANGE
[CRAM only] Filter the CRAM file to a specific \fIRANGE\fR. This can
be the usual chromosome:start-end syntax, or "*" for unmapped records
at the end of alignments.
If the range is of the form "#:start-end" then the start and end
coordinates are interpreted as inclusive CRAM container numbers,
starting at 0 and ending 1 less than the number of containers reported
by \fB-q\fR. For example \fB-r "#:0-9"\fR is the first 10 CRAM
containers of data.
All range types filter data in as fast a manner as possible, using
operating system read/write loops where appropriate.
.TP
.BI "-p " A/B
[CRAM only] Filter the CRAM file using a specific fraction. The file
is split into B approximately equal parts and returns element A where A
is between 1 and B inclusive. If there are more parts specified than
CRAM containers then some of the output will be empty CRAMs.
This can also be combined with the range option above to operate of
parts of that range. For example \fB-r chr2 -p 1/10\fR returns the
first 1/10th of data aligned against chromosome 2.
.TP
.B -f
[CRAM only] Enable fast mode. When filtering by chromosome range with
\fB-r\fR we normally do careful recoding of any containers that
overlap the start and end of the range so the record count precisely
matches that returned by a \fBsamtools view\fR equivalent. Fast mode
does no filtering, so may return additional alignments in the same
container but outside of the requested region.
.TP
.BI --no-PG
Do not add a @PG line to the header of the output file.
.TP
.BI "-@, --threads " INT
Number of input/output compression threads to use in addition to main thread [0].
.SH EXAMPLES
.IP o 2
Extract a specific chromosome from a CRAM file, outputting to a new
CRAM.
.EX 2
samtools cat -o chr10.cram -r chr10 in.cram
.EE
.IP o 2
Split a CRAM file up into separate files, each containing at most 123
containers.
.EX 2
set -- $(samtools cat -q in.cram); nc=$2; s=0
while [ $s -lt $nc ]
do
e=`expr $s + 123`
if [ $e -ge $nc ]
then
e=$nc
fi
r="$s-`expr $e - 1`"; echo $r
fn=/tmp/_part-`printf "%08d" $s`.cram
samtools cat -o $fn in.cram -r "#:$r"
s=$e
done
.EE
.IP o 2
Split any unaligned data from a (potentially aligned) CRAM file into
10 approximately equal sized pieces.
.EX 2
for i in `seq 1 10`
do
samtools cat in.cram -r "*" -p $i/10 -o part-`printf "%02d" $i`.cram
done
.SH AUTHOR
.PP
Written by Heng Li from the Sanger Institute.
Updated for CRAM by James Bonfield (also Sanger Institute).
.SH SEE ALSO
.IR samtools (1)
.PP
Samtools website: <http://www.htslib.org/>
|
