'\" t .TH samtools-view 1 "22 September 2020" "samtools-1.11" "Bioinformatics tools" .SH NAME samtools view \- views and converts SAM/BAM/CRAM files .\" .\" Copyright (C) 2008-2011, 2013-2020 Genome Research Ltd. .\" Portions copyright (C) 2010, 2011 Broad Institute. .\" .\" Author: Heng Li .\" Author: Joshua C. Randall .\" .\" 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 .B view samtools view .RI [ options ] .IR in.sam | in.bam | in.cram .RI [ region ...] .SH DESCRIPTION .PP With no options or regions specified, prints all alignments in the specified input alignment file (in SAM, BAM, or CRAM format) to standard output in SAM format (with no header). You may specify one or more space-separated region specifications after the input filename to restrict output to only those alignments which overlap the specified region(s). Use of region specifications requires a coordinate-sorted and indexed input file (in BAM or CRAM format). The .BR -b , .BR -C , .BR -1 , .BR -u , .BR -h , .BR -H , and .B -c options change the output format from the default of headerless SAM, and the .B -o and .B -U options set the output file name(s). The .B -t and .B -T options provide additional reference data. One of these two options is required when SAM input does not contain @SQ headers, and the .B -T option is required whenever writing CRAM output. The .BR -L , .BR -M , .BR -r , .BR -R , .BR -d , .BR -D , .BR -s , .BR -q , .BR -l , .BR -m , .BR -f , .BR -F , and .B -G options filter the alignments that will be included in the output to only those alignments that match certain criteria. The .B -x and .B -B options modify the data which is contained in each alignment. The .B -X option can be used to allow user to specify customized index file location(s) if the data folder does not contain any index file. See .B EXAMPLES section for sample of usage. Finally, the .B -@ option can be used to allocate additional threads to be used for compression, and the .B -? option requests a long help message. .TP .B REGIONS: .RS Regions can be specified as: RNAME[:STARTPOS[-ENDPOS]] and all position coordinates are 1-based. Important note: when multiple regions are given, some alignments may be output multiple times if they overlap more than one of the specified regions. Examples of region specifications: .TP 10 .B chr1 Output all alignments mapped to the reference sequence named `chr1' (i.e. @SQ SN:chr1). .TP .B chr2:1000000 The region on chr2 beginning at base position 1,000,000 and ending at the end of the chromosome. .TP .B chr3:1000-2000 The 1001bp region on chr3 beginning at base position 1,000 and ending at base position 2,000 (including both end positions). .TP .B '*' Output the unmapped reads at the end of the file. (This does not include any unmapped reads placed on a reference sequence alongside their mapped mates.) .TP .B . Output all alignments. (Mostly unnecessary as not specifying a region at all has the same effect.) .RE .SH OPTIONS .TP 10 .B -b Output in the BAM format. .TP .B -C Output in the CRAM format (requires -T). .TP .B -1 Enable fast BAM compression (implies -b). .TP .B -u Output uncompressed BAM. This option saves time spent on compression/decompression and is thus preferred when the output is piped to another samtools command. .TP .B -h Include the header in the output. .TP .B -H Output the header only. .TP .B -c Instead of printing the alignments, only count them and print the total number. All filter options, such as .BR -f , .BR -F , and .BR -q , are taken into account. .TP .B -? Output long help and exit immediately. .TP .BI "-o " FILE Output to .I FILE [stdout]. .TP .BI "-U " FILE Write alignments that are .I not selected by the various filter options to .IR FILE . When this option is used, all alignments (or all alignments intersecting the .I regions specified) are written to either the output file or this file, but never both. .TP .BI "-t " FILE A tab-delimited .IR FILE . Each line must contain the reference name in the first column and the length of the reference in the second column, with one line for each distinct reference. Any additional fields beyond the second column are ignored. This file also defines the order of the reference sequences in sorting. If you run: `samtools faidx ', the resulting index file .I .fai can be used as this .IR FILE . .TP .BI "-T " FILE A FASTA format reference .IR FILE , optionally compressed by .B bgzip and ideally indexed by .B samtools .BR faidx . If an index is not present one will be generated for you, if the reference file is local. If the reference file is not local, but is accessed instead via an https://, s3:// or other URL, the index file will need to be supplied by the server alongside the reference. It is possible to have the reference and index files in different locations by supplying both to this option separated by the string "##idx##", for example: .B -T ftp://x.com/ref.fa##idx##ftp://y.com/index.fa.fai However, note that only the location of the reference will be stored in the output file header. If this method is used to make CRAM files, the cram reader may not be able to find the index, and may not be able to decode the file unless it can get the references it needs using a different method. .TP .BI "-L " FILE Only output alignments overlapping the input BED .I FILE [null]. .TP .B "-M " Use the multi-region iterator on the union of a BED file and command-line region arguments. This avoids re-reading the same regions of files so can sometimes be much faster. Note this also removes duplicate sequences. Without this a sequence that overlaps multiple regions specified on the command line will be reported multiple times. The usage of a BED file is optional and its path has to be preceded by .BR -L option. .TP .BI "-r " STR Output alignments in read group .I STR [null]. Note that records with no .B RG tag will also be output when using this option. This behaviour may change in a future release. .TP .BI "-R " FILE Output alignments in read groups listed in .I FILE [null]. Note that records with no .B RG tag will also be output when using this option. This behaviour may change in a future release. .TP .BI "-d " STR:STR Only output alignments with tag .I STR and associated value .I STR [null]. .TP .BI "-D " STR:FILE Only output alignments with tag .I STR and associated values listed in .I FILE [null]. .TP .BI "-q " INT Skip alignments with MAPQ smaller than .I INT [0]. .TP .BI "-l " STR Only output alignments in library .I STR [null]. .TP .BI "-m " INT Only output alignments with number of CIGAR bases consuming query sequence \(>= .I INT [0] .TP .BI "-f " INT Only output alignments with all bits set in .I INT present in the FLAG field. .I INT can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal by beginning with `0' (i.e. /^0[0-7]+/) [0]. .TP .BI "-F " INT Do not output alignments with any bits set in .I INT present in the FLAG field. .I INT can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal by beginning with `0' (i.e. /^0[0-7]+/) [0]. .TP .BI "-G " INT Do not output alignments with all bits set in .I INT present in the FLAG field. This is the opposite of \fI-f\fR such that \fI-f12 -G12\fR is the same as no filtering at all. .I INT can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal by beginning with `0' (i.e. /^0[0-7]+/) [0]. .TP .BI "-x " STR Read tag to exclude from output (repeatable) [null] .TP .B -B Collapse the backward CIGAR operation. .TP .BI "-s " FLOAT Output only a proportion of the input alignments. This subsampling acts in the same way on all of the alignment records in the same template or read pair, so it never keeps a read but not its mate. .IP The integer and fractional parts of the .BI "-s " INT . FRAC option are used separately: the part after the decimal point sets the fraction of templates/pairs to be kept, while the integer part is used as a seed that influences .I which subset of reads is kept. .IP .\" Reads are retained based on a score computed by hashing their QNAME .\" field and the seed value. When subsampling data that has previously been subsampled, be sure to use a different seed value from those used previously; otherwise more reads will be retained than expected. .TP .BI "-@ " INT Number of BAM compression threads to use in addition to main thread [0]. .TP .B -S Ignored for compatibility with previous samtools versions. Previously this option was required if input was in SAM format, but now the correct format is automatically detected by examining the first few characters of input. .TP .B -X Include customized index file as a part of arguments. See .B EXAMPLES section for sample of usage. .TP .B --no-PG Do not add a @PG line to the header of the output file. .SH EXAMPLES .IP o 2 Import SAM to BAM when .B @SQ lines are present in the header: .EX 2 samtools view -bS aln.sam > aln.bam .EE If .B @SQ lines are absent: .EX 2 samtools faidx ref.fa samtools view -bt ref.fa.fai aln.sam > aln.bam .EE where .I ref.fa.fai is generated automatically by the .B faidx command. .IP o 2 Convert a BAM file to a CRAM file using a local reference sequence. .EX 2 samtools view -C -T ref.fa aln.bam > aln.cram .EE .IP o 2 Convert a BAM file to a CRAM with NM and MD tags stored verbatim rather than calculating on the fly during CRAM decode, so that mixed data sets with MD/NM only on some records, or NM calculated using different definitions of mismatch, can be decoded without change. The second command demonstrates how to decode such a file. The request to not decode MD here is turning off auto-generation of both MD and NM; it will still emit the MD/NM tags on records that had these stored verbatim. .EX 2 samtools view -C --output-fmt-option store_md=1 --output-fmt-option store_nm=1 -o aln.cram aln.bam samtools view --input-fmt-option decode_md=0 -o aln.new.bam aln.cram .EE .IP o 2 An alternative way of achieving the above is listing multiple options after the \fB--output-fmt\fR or \fB-O\fR option. The commands below are equivalent to the two above. .EX 2 samtools view -O cram,store_md=1,store_nm=1 -o aln.cram aln.bam samtools view --input-fmt cram,decode_md=0 -o aln.new.bam aln.cram .EE .IP o 2 Include customized index file as a part of arguments. .EX 2 samtools view [options] -X /data_folder/data.bam /index_folder/data.bai chrM:1-10 .EE .IP o 2 Output alignments in read group \fBgrp2\fR (records with no \fBRG\fR tag will also be in the output). .EX 2 samtools view -r grp2 -o /data_folder/data.rg2.bam /data_folder/data.bam .EE .IP o 2 Only keep reads with tag \fBBC\fR and were the barcode matches the barcodes listed in the barcode file. .EX 2 samtools view -D BC:barcodes.txt -o /data_folder/data.barcodes.bam /data_folder/data.bam .EE .IP o 2 Only keep reads with tag \fBRG\fR and read group \fBgrp2\fR. This does almost the same than \fB-r grp2\fR but will not keep records without the \fBRG\fR tag. .EX 2 samtools view -d RG:grp2 -o /data_folder/data.rg2_only.bam /data_folder/data.bam .EE .SH AUTHOR .PP Written by Heng Li from the Sanger Institute. .SH SEE ALSO .IR samtools (1), .IR samtools-tview (1), .IR sam (5) .PP Samtools website: