SeqKit Documentation

SeqKit is a cross-platform, ultrafast toolkit designed for FASTA/Q file manipulation.

Key capabilities include:

• Format Support: Seamlessly parses both FASTA and FASTQ formats.
• Compression & I/O: Supports gzip, xz, zstd, bzip2, and lz4 compressed files. It works with both input/output files and STDIN/STDOUT, making it ideal for shell piping.
• Reproducibility: Commands like sample and shuffle allow for a configurable random seed to ensure reproducible results.
• Customization: Supports custom sequence ID extraction using regular expressions.
• Shell Integration: Supports Bash/Zsh autocompletion.

SeqKit is a cross-platform, ultrafast toolkit designed for manipulating FASTA and FASTQ files. It is a comprehensive tool for nucleotide and protein sequence processing, supporting common tasks such as converting, searching, filtering, deduplication, splitting, shuffling, sampling, and more.

Key advantages include:

• Cross-platform: Provides executable binaries for Windows, Linux, and macOS.
• Zero dependencies: Can be used directly without pre-configured environments or additional packages.
• High performance: Demonstrates competitive execution time and memory usage compared to other bioinformatics tools.
• Versatile I/O: Supports reading from STDIN and handling gzipped files (both reading and writing).

SeqKit provides a wide range of subcommands categorized by their primary function. These include basic operations, format conversions, searching, set operations, editing, ordering, BAM processing, and miscellaneous utilities.

Command Categories

• Basic operation: seq, stats, subseq, sliding, faidx, translate, watch, scat.
• Format conversion: fq2fa, fx2tab, fa2fq, tab2fx, convert.
• Searching: grep, locate, amplicon, fish.
• Set operation: sample, sample2, rmdup, common, duplicate, split, split2, head, head-genome, range, pair.
• Edit: replace, rename, concat, restart, mutate, sana.
• Ordering: sort, shuffle.
• BAM processing: bam.
• Miscellaneous: sum, merge-slides.

SeqKit provides a comprehensive set of features for FASTA/Q manipulation. Compared to other common tools like seqtk, fasta_utilities, or fastx_toolkit, SeqKit supports a wider range of functions including:

• Format Support: Multi-line FASTA, FASTQ, and Multi-line FASTQ.
• Sequence Operations: Searching by motifs, locating motifs, sampling, shuffling, and removing duplicates.
• Sequence Transformation: Transcription, translation, and cleaning bases.
• File Handling: Reading from STDIN, reading/writing gzipped files, and cross-platform compatibility.
• Advanced Filtering: Filtering by size (indirectly) and renaming headers.

SeqKit provides a wide range of subcommands categorized by functionality:

• Basic operations: seq, stats, subseq, sliding, faidx, translate, watch, sana, scat
• Format conversion: fq2fa, fa2fq, fx2tab, tab2fx, convert
• Searching: grep, locate, amplicon, fish
• Set operations: sample, sample2, rmdup, common, duplicate, split, split2, head, head-genome, range, pair
• Editing: concat, replace, restart, mutate, rename
• Ordering: sort, shuffle
• BAM processing: bam
• Others: sum, merge-slides

SeqKit supports high-speed reading and writing of compressed files. It uses the pgzip package for gzip, which is significantly faster than piping to pigz or gzip manually.

Supported Formats and Compression Levels

Use the --compress-level flag to adjust these values.

By default, seqkit seq automatically detects the sequence type (DNA, RNA, or Protein) based on the characters present in the file. You can verify this using seqkit stats.

If you need to force a specific sequence type, use the -t or --seq-type flag. Note that this flag only takes effect on the seq and locate subcommands. When -t is used, the -v (--validate-seq) flag is automatically enabled to ensure the sequence matches the specified alphabet.

Example of forcing DNA type:

echo -e ">seq\nabcdefghijklmnpqrstvwyz" | seqkit seq -t dna

For commands like subseq, split, sort, and shuffle, SeqKit can use a FASTA index to enable rapid access and reduce memory usage. This is particularly useful when using the --two-pass (-2) flag for large files.

Important: The .seqkit.fai index files created by SeqKit are different from samtools .fai files; SeqKit uses the full sequence header as the key instead of just the ID.

When using SeqKit subcommands, you may encounter settings for strand-sensitivity and multi-threading:

Strand-sensitivity

• + only: The command only processes the positive/forward strand.
• + and -: The command searches on both strands.
• + or/and -: The behavior depends on the specific flags, options, or arguments provided by the user.

Multi-threads

SeqKit uses multiple threads to accelerate processing. While the default of 4 threads is sufficient for most commands, certain commands can benefit significantly from additional threads. Look for the ✓ symbol in the subcommand reference table to identify which commands support multi-threading.

The seqkit sample command supports two modes of sampling:

1. Sampling by proportion (-p / --proportion): SeqKit returns a record if a generated random number in the range [0, 1) is less than the specified proportion P.
2. Sampling by amount (-n / --number): SeqKit first calculates the total number of records, computes the equivalent proportion P, and then performs sampling by proportion.

Important Note on Accuracy: Because SeqKit uses pseudorandom numbers, the actual number of sampled records when using the amount (-n) flag may not exactly equal the requested number N. This behavior is influenced by the random seed provided via the -s or --rand-seed flag.

When using the -r/--by-region flag, regions are defined using a 1-based index. You can use positive indices for the start of the sequence or negative indices to count from the end.

Indexing Examples: