1samtools-import(1) Bioinformatics tools samtools-import(1)
2
6 samtools import - converts FASTQ files to unmapped SAM/BAM/CRAM
7
9 samtools import [options] [ fastq_file ... ]
10
14 Reads one or more FASTQ files and converts them to unmapped SAM, BAM or
15 CRAM. The input files may be automatically decompressed if they have a
16 .gz extension.
17 The simplest usage in the absence of any other command line options is
19 to provide one or two input files.
20 If a single file is given, it will be interpreted as a single-ended se‐
22 quencing format unless the read names end with /1 and /2 in which case
23 they will be labelled as PAIRED with READ1 or READ2 BAM flags set. If
24 a pair of filenames are given they will be read from alternately to
25 produce an interleaved output file, also setting PAIRED and READ1 /
26 READ2 flags.
27 The filenames may be explicitly labelled using -1 and -2 for READ1 and
29 READ2 data files, -s for an interleaved paired file (or one half of a
30 paired-end run), -0 for unpaired data and explicit index files speci‐
31 fied with --i1 and --i2. These correspond to typical output produced
32 by Illumina bcl2fastq and match the output from samtools fastq. The
33 index files will set both the BC barcode code and it's associated QT
34 quality tag.
35 The Illumina CASAVA identifiers may also be processed when the -i op‐
37 tion is given. This tag will be processed for READ1 / READ2, whether
38 or not the read failed processing (QCFAIL flag), and the barcode se‐
39 quence which will be added to the BC tag. This can be an alternative
40 to explicitly specifying the index files, although note that doing so
41 will not fill out the barcode quality tag.
42
46 -s FILE Import paired interleaved data from FILE.
47 -0 FILE Import single-ended (unpaired) data from FILE.
50 Operationally there is no difference between the -s and -0 op‐
52 tions as given an interleaved file with /1 and /2 read name
53 endings both will correctly set the PAIRED, READ1 and READ2
54 flags, and given data with no suffixes and no CASAVA identi‐
55 fiers being processed both will leave the data as unpaired.
56 However their inclusion here is for more descriptive command
57 lines and to improve the header comment describing the samtools
58 fastq decode command.
59 -1 FILE, -2 FILE
62 Import paired data from a pair of FILEs. The BAM flag PAIRED
63 will be set, but not PROPER_PAIR as it has not been aligned.
64 READ1 and READ2 will be stored in their original, unmapped,
65 orientation.
66 --i1 FILE, --i2 FILE
69 Specifies index barcodes associated with the -1 and -2 files.
70 These will be appended to READ1 and READ2 records in the bar‐
71 code (BC) and quality (QT) tags.
72 -i Specifies that the Illumina CASAVA identifiers should be pro‐
75 cessed. This may set the READ1, READ2 and QCFAIL flags and add
76 a barcode tag.
77 --barcode-tag TAG
80 Changes the auxiliary tag used for barcode sequence. Defaults
81 to BC.
82 --quality-tag TAG
85 Changes the auxiliary tag used for barcode quality. Defaults
86 to QT.
87 -oFILE Output to FILE. By default output will be written to stdout.
90 --order TAG
93 When outputting a SAM record, also output an integer tag con‐
94 taining the Nth record number. This may be useful if the data
95 is to be sorted or collated in some manner and we wish this to
96 be reversible. In this case the tag may be used with samtools
97 sort -t TAG to regenerate the original input order.
98 -r RG_line, --rg-line RG_line
101 A complete @RG header line may be specified, with or without
102 the initial "@RG" component. If specified this will also use
103 the ID field from RG_line in each SAM records RG auxiliary tag.
104 If specified multiple times this appends to the RG line, auto‐
106 matically adding tabs between invocations.
107 -R RG_ID, --rg RG_ID
110 This is a shorter form of the option above, equivalent to --rg-
111 line ID:RG_ID. If both are specified then this option is ig‐
112 nored.
113 -u Output BAM or CRAM as uncompressed data.
116 -T TAGLIST
119 This looks for any SAM-format auxiliary tags in the comment
120 field of a fastq read name. These must match the <alpha-
121 num><alpha-num>:<type>:<data> pattern as specified in the SAM
122 specification. TAGLIST can be blank or * to indicate all tags
123 should be copied to the output, otherwise it is a comma-sepa‐
124 rated list of tag types to include with all others being dis‐
125 carded.
126
130 Convert a single-ended fastq file to an unmapped CRAM. Both of these
131 commands perform the same action.
132 samtools import -0 in.fastq -o out.cram
135 samtools import in.fastq > out.cram
136 Convert a pair of Illumina fastqs containing CASAVA identifiers to BAM,
139 adding the barcode information to the BC auxiliary tag.
140 samtools import -i -1 in_1.fastq -2 in_2.fastq -o out.bam
143 samtools import -i in_[12].fastq > out.bam
144 Specify the read group. These commands are equivalent
147 samtools import -r "$(echo -e 'ID:xyz\tPL:ILLUMINA')" in.fq
150 samtools import -r "$(echo -e '@RG\tID:xyz\tPL:ILLUMINA')" in.fq
151 samtools import -r ID:xyz -r PL:ILLUMINA in.fq
152 Create an unmapped BAM file from a set of 4 Illumina fastqs from
155 bcf2fastq, consisting of two read and two index tags. The CASAVA iden‐
156 tifier is used only for setting QC pass / failure status.
157 samtools import -i -1 R1.fq -2 R2.fq --i1 I1.fq --i2 I2.fq -o out.bam
160 Convert a pair of CASAVA barcoded fastq files to unmapped CRAM with an
163 incremental record counter, then sort this by minimiser in order to re‐
164 duce file space. The reversal process is also shown using samtools
165 sort and samtools fastq.
166 samtools import -i in_1.fq in_2.fq --order ro -O bam,level=0 | \
169 samtools sort -@4 -M -o out.srt.cram -
170 samtools sort -@4 -O bam -u -t ro out.srt.cram | \
172 samtools fastq -1 out_1.fq -2 out_2.fq -i --index-format "i*i*"
173
177 Written by James Bonfield of the Wellcome Sanger Institute.
178
181 samtools(1), samtools-fastq(1)
182 Samtools website: <http://www.htslib.org/>
184samtools-1.13 7 July 2021 samtools-import(1)