SortByName
Sorts reads by name or other keys such as length, quality, mapping position, flowcell coordinates, or taxonomy. Writes temp files if memory is exceeded.
Basic Usage
sortbyname.sh in=<file> out=<file>Input may be FASTA, FASTQ, or SAM, compressed or uncompressed. Temp files use the same format as the output. Pairs are kept together if reads are paired, and in2/out2 may be used for that.
Parameters
Parameters control input/output files, which key to sort by, sort direction, and memory/temp-file behavior for external sorting.
File Parameters
- in=<file>
- Input file. Required parameter.
- out=<file>
- Output file. Required parameter.
- list=<file>
- Sort reads according to this list of names, instead of one of the built-in sort keys below.
Sort Key Parameters
- name=t
- Sort reads by name.
- length=f
- Sort reads by length.
- quality=f
- Sort reads by quality. Note: name, length, and quality are mutually exclusive. Sorting by quality actually sorts by average expected error rate, so ascending places the highest-quality reads first.
- position=f
- Sort reads by position, for mapped reads.
- taxa=f
- Sort reads by taxonomy, for NCBI naming convention. See the Taxonomy-Sorting Parameters below.
- sequence=f
- Sort reads by sequence, alphabetically.
- clump=f
- Sort reads by shared kmers, like Clumpify.
- flowcell=f
- Sort reads by flowcell coordinates.
- shuffle=f
- Shuffle reads randomly (untested).
- crispr=f
- Sort reads by CRISPR repeat quality score. Requires a neural network model.
Order Parameters
- ascending=t
- Sort ascending. This defaults to true except for length.
- descending=f
- Sort descending instead of ascending. Overrides the ascending flag.
Processing Parameters
- maxfiles=12
- Maximum number of temp files to use during external sort.
- genkmer=t
- Generate 5-bit kmers for topological/lexicographic sorting modes.
- deleteearly=f
- Delete temp files as soon as they are merged, to save disk space.
Memory Parameters
You might reduce these if you experience a crash.
- memmult=0.30
- Write a temp file when used memory exceeds this fraction of available memory.
- memlimit=0.65
- Wait for temp files to finish writing until used memory drops below this fraction of available memory.
- delete=t
- Delete temporary files.
- allowtemp=t
- Allow writing temporary files.
Taxonomy-Sorting Parameters
For taxa mode only.
- tree=t
- Use a TaxTree for taxa sorting. Default (and required in taxa mode).
- usetree=t
- Alias for tree=t/f.
- treefile=auto
- Select the TaxTree source without changing the local gate.
- tree=<path>
- Legacy form that selects the path and enables loading.
- gi=
- Specify a gitable file. On Genepool, use 'auto'.
- accession=
- Specify one or more comma-delimited NCBI accession-to-taxid files. On Dori/NERSC, use 'auto'.
Java Parameters
- -Xmx
- Set Java's memory usage, overriding autodetection. For example -Xmx20g specifies 20 gigs of RAM and -Xmx200m specifies 200 megs. The max is typically 85% of physical memory.
- -eoom
- Cause the process to exit if an out-of-memory exception occurs. Requires Java 8u92+.
- -da
- Disable assertions.
Examples
Sort by Name
sortbyname.sh in=raw.fq out=sorted.fqSorts reads alphabetically by name, the default sort key.
Sort by Sequence
sortbyname.sh in=raw.fq out=sorted.fq sequenceSorts reads alphabetically by sequence content.
Sort Mapped Reads by Position
sortbyname.sh in=mapped.sam out=sorted.sam positionSorts a SAM file's reads by their mapping position.
Sort by Taxonomy
sortbyname.sh in=reads.fa out=sorted.fa taxa tree=tSorts reads using NCBI taxonomic ID naming convention, loading the bundled TaxTree.
Support
For questions and support:
- Email: bbushnell@lbl.gov
- Documentation: bbmap.org