map_reads
Read-only
Map sequencing reads (FASTQ or FASTA) or assembled contigs onto a reference and return the alignment as SAM, the file a pileup viewer, a variant caller or samtools reads next. This is minimap2 (minimizer seeds, chaining, banded dual-affine extension with inversion detection, MAPQ), ported and checked record for record against the minimap2 2.31 CLI under every preset it offers: Illumina short reads (sr, the default), RNA-seq across introns (splice:sr for short reads, splice and splice:hq for long RNA or cDNA, which also report every splice junction with its read support), Nanopore, PacBio HiFi and CLR, accurate long reads, Illumina Complete Long Reads, assemblies at three divergence levels, and all-vs-all read overlaps (ava-pb, ava-ont, where the reads are their own reference and the output is PAF). Give mates to map read pairs (sr and splice:sr): the two inputs pair record for record, mate 2 facing mate 1 (FR), and pairing lifts a mate placed in a repeat by its uniquely placed partner. Leave reference unset to map against the record this step runs on; a multi-record FASTA maps against every record.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | k-mer size of the minimizer seeds (`-k`). Advanced. | |
| w | No | minimizer window (`-w`): one seed kept per this many consecutive k-mers. Advanced. | |
| depth | No | per-base read depth of the SAM written (`samtools depth`): off; every position inside some read's span (an intron or deletion inside a read prints 0); or every position of each reference a read landed on (`-a`). Reads that are unmapped, secondary, QC-failed or duplicate are not counted. Values: none (Off), covered (Covered positions), all (Every position (-a)). | none |
| mates | No | mate-2 reads, pairing record for record with `reads`. Empty maps the reads single-end. | |
| reads | Yes | the reads: FASTQ (quality kept in the SAM) or FASTA (QUAL written as `*`). | |
| zdrop | No | Z-drop (`-z`): stop extending when the score falls this far below its best, which clips a read at a junction instead of forcing it through. Advanced. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| md_tag | No | write MD tags (`--MD`); the consensus uses them to trust reads with edits nearby less. | |
| preset | No | what is being mapped (`-x`): it sets every option below to minimap2's values for that data. The defaults shown are the short-read preset's; an option left unset takes the chosen preset's own value. Values: sr (Short reads), splice:sr (Short RNA-seq reads), splice (Long RNA reads, cDNA), splice:hq (Accurate long RNA reads), map-ont (Nanopore), lr:hq (Accurate long reads), map-hifi (PacBio HiFi), map-pb (PacBio CLR), map-iclr (Illumina Complete Long Reads), lr:hqae (Assembly evaluation), asm5 (Assembly, ~0.1% divergent), asm10 (Assembly, ~1% divergent), ava-pb (PacBio all-vs-all overlaps), ava-ont (Nanopore all-vs-all overlaps), asm20 (Assembly, several % divergent). | sr |
| max_gap | No | a chain stops at a gap longer than this between seeds (`-g`). In bp. Advanced. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| gap_open | No | gap-open penalty of the short-gap cost (`-O`, first value). Advanced. | |
| variants | No | call SNVs and indels from the SAM written (`bcftools mpileup | bcftools call -mv`): genotype, quality, allelic depths and strand counts per site, as VCF. | |
| bandwidth | No | band of the chaining and alignment dynamic programming (`-r`, first value): the most the two sequences may drift against each other inside one chain. In bp. Advanced. | |
| consensus | No | the sample's sequence called from the reads over the reference (`samtools consensus`); N where no call is confident. Values: off (Off), fasta (FASTA), fastq (FASTQ (with quality)), pileup (Pileup (every column)). | off |
| end_bonus | No | bonus for reaching the read's end (`--end-bonus`); higher prefers end-to-end alignment over soft-clipping. Advanced. | |
| reference | No | what to map against: bases, or a FASTA with one or more records. Unset, it is the record this step runs on. | |
| gap_extend | No | per-base extension of the short-gap cost (`-E`, first value). Advanced. | |
| max_intron | No | longest intron an alignment may span (`-G`); it also sets the reference gap and both chaining bands, as minimap2 does. In bp. Only applies when preset is splice or splice:hq or splice:sr. Advanced. | |
| markdup_tag | No | tag each duplicate with the name of the read it copies (`do:Z`, `-t`). Only applies when mark_duplicates is true. | |
| match_score | No | score per matching base (`-A`). Advanced. | |
| markdup_mode | No | what makes two reads duplicates (`-m`): the template's two outer ends (samtools' default, as Picard), or each read's start by strand. Values: t (Template ends), s (Read starts). Only applies when mark_duplicates is true. | t |
| min_dp_score | No | lowest peak alignment score kept (`-s`). | |
| variants_baq | No | recalibrate base qualities by their alignment uncertainty near indels (BAQ, bcftools' default; off is `-B`). Only applies when variants is true. | |
| gap_open_long | No | gap-open penalty of the long-gap cost (`-O`, second value); a gap costs the cheaper of the two. Advanced. | |
| max_secondary | No | most secondary placements kept per read (`-N`). | |
| output_format | No | SAM (`-a`, every read with its alignment) or PAF (minimap2's default: one line per hit, no read sequence). Unset: PAF for the all-vs-all presets, SAM otherwise. Values: sam (SAM), paf (PAF). | |
| variants_args | No | further `bcftools mpileup` options (`--max-BQ`, `--delta-BQ`, `--ff`, `-M`, `-E`). Only applies when variants is true. | |
| bandwidth_long | No | wider band for the long join (`-r`, second value): when the best chain leaves much of a long read unexplained, its seeds are re-chained in this band. No effect under the short-read preset. In bp. Advanced. | |
| base_alignment | No | in PAF, align base by base (`-c`): exact ends, CIGAR as `cg:Z`, NM. Off, a hit's coordinates are its chain's ends, which is much faster. SAM always aligns. Only applies when output_format is paf. | |
| consensus_args | No | further `samtools consensus` options, applied last (e.g. `--min-MQ 20 -t :hiseq`); all but files and threads. Only applies when consensus is fasta or fastq or pileup. | |
| consensus_mode | No | how a column is called (`-m`). Values: bayesian (Bayesian), bayesian_p (Bayesian, precise), bayesian_m (Bayesian, blended), bayesian_116 (Bayesian (samtools 1.16)), simple (Simple counting). Only applies when consensus is fasta or fastq or pileup. | bayesian |
| markdup_remove | No | remove the duplicates from the SAM instead of flagging them (`-r`). Only applies when mark_duplicates is true. | |
| min_minimizers | No | fewest seeds a chain may have (`-n`). Advanced. | |
| variants_prior | No | the mutation-rate prior (`call -P`): higher calls more sites. Only applies when variants is true. | |
| gap_extend_long | No | per-base extension of the long-gap cost (`-E`, second value). Advanced. | |
| mark_duplicates | No | mark PCR and optical duplicates (`samtools fixmate -m`, `sort`, `markdup`): reads whose 5′ ends, strands and mate position match are copies of one fragment; the best by base quality is kept and the rest flagged 0x400. The SAM comes back sorted by coordinate, and flagstat, coverage and depth then count the flags. | |
| min_chain_score | No | lowest chaining score kept (`-m`), roughly the number of matching bases the seeds cover. | |
| secondary_ratio | No | a secondary placement is kept when its score is at least this fraction of the primary's (`-p`). | |
| variants_indels | No | call indels too, with bcftools' default indel model (off is `-I`, SNVs only). Only applies when variants is true. | |
| write_secondary | No | also write secondary records to the SAM (`--secondary=yes`); off, they are counted but not written, as minimap2 does for short reads. | |
| zdrop_inversion | No | Z-drop at which a stalled long alignment is tested for an inversion (`-z`, second value); an inverted segment found there is written as its own record. Advanced. | |
| consensus_region | No | one region (`-r`): name or name:start-end, 1-based. Only applies when consensus is fasta or fastq or pileup. | |
| mismatch_penalty | No | penalty per mismatch (`-B`). Advanced. | |
| consensus_profile | No | a platform's quality calibration and tuned parameters (`-X`). Values: none (None), hiseq (Illumina HiSeq), hifi (PacBio HiFi), r10.4_sup (Nanopore R10.4 simplex (sup)), r10.4_dup (Nanopore R10.4 duplex), ultima (Ultima Genomics). Only applies when consensus is fasta or fastq or pileup. | none |
| variants_full_baq | No | run BAQ on every read at a column with an indel, not only the reads it is likely to change (`-D`; nothing with BAQ off). Only applies when variants is true. | |
| variants_gap_open | No | phred-scaled probability that sequencing opens a gap (`-o`); lower calls more indels. Only applies when variants is true. | |
| transition_penalty | No | penalty for a transition (A↔G, C↔T) mismatch (`-b`); 0 scores it as any mismatch. Illumina Complete Long Reads use 4. Advanced. | |
| variants_adjust_mq | No | cap the mapping quality of reads with many high-quality mismatches (`-C`; 50 for BWA reads, 0 is off, values up to 10 do nothing). Only applies when variants is true. | |
| variants_max_depth | No | most reads piled up per position (`-d`); at most 255, where bcftools starts downsampling at random. Only applies when variants is true. | |
| consensus_ambiguity | No | a heterozygous call as its IUPAC code (`-A`). Only applies when consensus is fasta or fastq or pileup. | |
| consensus_min_depth | No | fewer usable reads than this is N (`-d`). Only applies when consensus is fasta or fastq or pileup. | |
| consensus_positions | No | which positions are written. Values: covered (Covered span), reference (Whole reference (-a)), all (Every reference (-aa)). Only applies when consensus is fasta or fastq or pileup. | covered |
| max_fragment_length | No | longest fragment (insert) two mates may span and still pair (`--frag`/`-I`). In bp. Only applies when mates is set. | |
| max_seed_occurrence | No | seeds occurring more often than this in the reference are skipped (`-f`); the query length they cover is what `rep_len` reports, and it lowers MAPQ. Advanced. | |
| variants_gap_extend | No | phred-scaled probability that sequencing extends a gap (`-e`). Only applies when variants is true. | |
| variants_indel_bias | No | raise to favour indel recall over precision (`--indel-bias`). Only applies when variants is true. | |
| variants_indel_size | No | approximate largest indel considered, in bases (`--indel-size`, at least 20). Only applies when variants is true. | |
| noncanonical_penalty | No | cost of a splice site that is not GT..AG, GC..AG or AT..AC (`-C`). Only the splice presets align across introns. Only applies when preset is splice or splice:hq or splice:sr. Advanced. | |
| variants_homopolymer | No | how strongly a homopolymer run lowers an indel's quality (`-h`); lower trusts indels in runs less. Only applies when variants is true. | |
| depth_count_deletions | No | count a read's deletions toward the depth under them (`-J`); off, a deleted base is not covered by that read. Only applies when depth is covered or all. | |
| depth_min_read_length | No | a read with fewer aligned bases than this (soft clips excluded) does not count (`-l`). In bp. Only applies when depth is covered or all. | |
| depth_remove_overlaps | No | count the overlap of a read pair once (`-s`): the second mate starts counting where the first ended. Only applies when depth is covered or all. | |
| markdup_supplementary | No | also flag the supplementary, secondary and unmapped records of a duplicate (`-S`). Only applies when mark_duplicates is true. | |
| depth_min_base_quality | No | a base below this quality does not count (`-q`). Only applies when depth is covered or all. | |
| homopolymer_compressed | No | seed on homopolymer-compressed sequence (`-H`), so runs of one base count once: the PacBio CLR preset's answer to its length errors in homopolymers. Advanced. | |
| variants_count_orphans | No | keep reads paired but not properly paired (`-A`). Only applies when variants is true. | |
| variants_keep_reference | No | also write the positions where the reads agree with the reference (`call -m` without `-v`): one record per covered position, variant or not. Only applies when variants is true. | |
| consensus_fill_reference | No | the reference's base where no read gives one (`-T`), instead of N. Only applies when consensus is fasta or fastq or pileup. | |
| consensus_show_deletions | No | write a deletion as `*` (`--show-del`). Only applies when consensus is fasta or fastq or pileup. | |
| markdup_optical_distance | No | also call a duplicate optical when its Illumina tile x/y lies within this many pixels of the original's (`-d`); 0 is off. Illumina suggests 100 for unpatterned flow cells and 2,500 for patterned ones. In px. Only applies when mark_duplicates is true. | |
| variants_max_indel_depth | No | positions this deep or deeper get no indel call (`-L`). Only applies when variants is true. | |
| variants_min_indel_reads | No | fewest reads carrying an indel for it to be considered (`-m`). Only applies when variants is true. | |
| consensus_show_insertions | No | write inserted bases (`--show-ins`). Only applies when consensus is fasta or fastq or pileup. | |
| depth_min_mapping_quality | No | a read below this mapping quality does not count (`-Q`). Only applies when depth is covered or all. | |
| variants_min_base_quality | No | skip bases below this quality (`-Q`). Only applies when variants is true. | |
| variants_min_indel_fraction | No | smallest fraction of reads carrying an indel for it to be considered (`-F`). Only applies when variants is true. | |
| variants_overlap_adjustment | No | where two mates overlap, count the shared bases once by zeroing one mate's qualities (off is `-x`). Only applies when variants is true. | |
| variants_min_mapping_quality | No | skip reads below this mapping quality (`-q`). Only applies when variants is true. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| paf | Yes | the hits as PAF, as minimap2 writes it by default (empty when the output is SAM); for the all-vs-all presets, every overlap between two reads | |
| sam | Yes | the alignment as SAM text (header + records), as `minimap2 -ax <preset>` writes it. Open it in the pileup, or hand it to a variant caller | |
| vcf | Yes | SNVs called from the SAM written, as `bcftools call -mv` writes the VCF (GT, PL, AD; DP, DP4, MQ and the bias tests per site). Empty unless `variants` is on. Open it in the variant viewer | |
| calls | Yes | each call: contig, position, reference and alternate alleles, QUAL, genotype, depth, DP4, allelic depths, PL and mean mapping quality. Empty unless `variants` is on | |
| depth | Yes | `samtools depth` of the SAM written, as samtools prints it (reference, 1-based position, depth; one line per position). Empty unless `depth` asks for it | |
| mapq0 | Yes | mapped reads with MAPQ 0: placed, but with an equally good placement elsewhere | |
| stats | Yes | every count: reads, fragments, mapped, unmapped, MAPQ bins, proper pairs, supplementary and secondary placements, reads spanning an intron, and per reference its reads and covered bases | |
| mapped | Yes | reads with a primary placement | |
| markdup | Yes | `samtools markdup`'s statistics when duplicates were marked: reads examined, pairs and singles, duplicate pairs and singles, optical duplicates, and the estimated library size. Empty otherwise | |
| options | Yes | every minimap2 option the run used, with its flag, the preset value, and whether it was changed | |
| reading | Yes | what the run found, generated from its counts: the conclusion, then each qualifier the run earned | |
| coverage | Yes | `samtools coverage` of the SAM written: per reference its reads, covered bases, percent covered, mean depth, mean base quality and mean mapping quality (reads that are unmapped, secondary, QC-failed or duplicate excluded, as samtools does). Null for PAF output, which writes no SAM to summarize | |
| flagstat | Yes | `samtools flagstat` of the SAM written, as samtools prints it (QC-passed + QC-failed: total, primary, secondary, supplementary, duplicates, mapped, paired, properly paired, singletons, mates on another reference). Empty for PAF. Null for PAF output, which writes no SAM to summarize | |
| unmapped | Yes | reads with none | |
| consensus | Yes | `samtools consensus` of the SAM written, as samtools prints it (FASTA, FASTQ or pileup). Empty unless `consensus` asks for it | |
| junctions | Yes | splice junctions as `minimap2 --write-junc` writes them (BED-like: reference, start, end, read, motif score, strand; one line per intron per read, primary alignments of MAPQ 10 or more). Empty outside the splice presets | |
| meanIdentity | Yes | mean identity of primary alignments, matching bases over aligned columns (0–1). Null when no read aligned, so there is nothing to measure: a 0 would read as every base mismatched | |
| junctionTable | Yes | each distinct junction once: reference, start, end, strand, motif score (6 = GT..AG) and the number of reads that support it | |
| properlyPaired | Yes | reads in a proper pair (0 when mapped single-end) | |
| variantSummary | Yes | the calls counted: SNVs, indels, homozygous and heterozygous, transitions and transversions among the SNVs, covered positions, and the bcftools command used | |
| consensusSummary | Yes | the consensus counted: sequences, bases, N (no call), IUPAC ambiguity codes, lower-case and deletion calls, mean quality, and the samtools arguments used |