Introduction to SeqIO · Biopython

Python Tools for Computational Molecular Biology
This page describes Bio.SeqIO, the standard Sequence Input/Output interface for BioPython 1.43 and later. For implementation details, see the SeqIO development page.
Python novices might find Peter’s introductory Biopython Workshop useful which start with working with sequence files using SeqIO.
There is a whole chapter in the Tutorial (PDF) on Bio.SeqIO, and although there is some overlap it is well worth reading in addition to this WIKI page. There is also the API documentation (which you can read online, or from within Python with the help command).
Bio.SeqIO provides a simple uniform interface to input and output assorted sequence file formats (including multiple sequence alignments), but will only deal with sequences as SeqRecord objects. There is a sister interface Bio.AlignIO for working directly with sequence alignment files as Alignment objects.
The design was partly inspired by the simplicity of BioPerl’s SeqIO. In the long term we hope to match BioPerl’s impressive list of supported sequence file formats and multiple alignment formats.
Note that the inclusion of Bio.SeqIO (and Bio.AlignIO) in Biopython does lead to some duplication or choice in how to deal with some file formats. For example, Bio.Nexus will also read sequences from Nexus files - but Bio.Nexus can also do much more, for example reading any phylogenetic trees in a Nexus file.
My vision is that for manipulating sequence data you should try Bio.SeqIO as your first choice. Unless you have some very specific requirements, I hope this should suffice.
The authorative list of supported formats is in the code’s docstrings. The table here may not be fully up to date.
This table lists the file formats that Bio.SeqIO can read, write and index, with the Biopython version where this was first supported (or git to indicate this is supported in our latest in development code). The format name is a simple lowercase string. Where possible we use the same name as BioPerl’s SeqIO and EMBOSS.
With Bio.SeqIO you can treat sequence alignment file formats just like any other sequence file, but the new Bio.AlignIO module is designed to work with such alignment files directly. You can also convert a set of SeqRecord objects from any file format into an alignment - provided they are all the same length. Note that when using Bio.SeqIO to write sequences to an alignment file format, all the (gapped) sequences should be the same length.
The main function is Bio.SeqIO.parse() which takes a file handle (or filename) and format name, and returns a SeqRecord iterator. This lets you do things like:
In the above example, we opened the file using the built-in python function open. The with- statement makes sure that the file is properly closed after reading it. That should all happen automatically if you just use the filename instead.
Note that you must specify the file format explicitly, unlike BioPerl’s SeqIO which can try to guess using the file name extension and/or the file contents. See Explicit is better than implicit (The Zen of Python).
If you had a different type of file, for example a Clustalw alignment file such as opuntia.aln which contains seven sequences, the only difference is you specify "clustal" instead of "fasta":
Iterators are great for when you only need the records one by one, in the order found in the file. For some tasks you may need to have random access to the records in any order. In this situation, use the built in python list() function to turn the iterator into a list:
Another common task is to index your records by some identifier. For small files we have a function Bio.SeqIO.to_dict() to turn a SeqRecord iterator (or list) into a dictionary (in memory):
The function Bio.SeqIO.to_dict() will use the record ID as the dictionary key by default, but you can specify any mapping you like with its optional argument, key_function.
For larger files, it isn’t possible to hold everything in memory, so Bio.SeqIO.to_dict is not suitable. Biopython 1.52 inwards includes the Bio.SeqIO.index function for this situation, but you might also consider BioSQL.
Biopython 1.45 introduced another function, Bio.SeqIO.read(), which like Bio.SeqIO.parse() will expect a handle and format. It is for use when the handle contains one and only one record, which is returned as a single SeqRecord object. If there are no records, or more than one, then an exception is raised:
For the related situation where you just want the first record (and are happy to ignore any subsequent records), you can use the built-in python function next:
For writing records to a file use the function Bio.SeqIO.write(), which takes a SeqRecord iterator (or list), output handle (or filename) and format string:
There are more examples in the following section on converting between file formats.
Note that if you are writing to an alignment file format, all your sequences must be the same length.
If you supply the sequences as a SeqRecord iterator, then for sequential file formats like Fasta or GenBank, the records can be written one by one. Because only one record is created at a time, very little memory is required. See the example below filtering a set of records.
On the other hand, for interlaced or non-sequential file formats like Clustal, the Bio.SeqIO.write() function will be forced to automatically convert an iterator into a list. This will destroy any potential memory saving from using an generator/iterator approach.
Suppose you have a GenBank file which you want to turn into a Fasta file. For example, lets consider the file cor6_6.gb which is included in the Biopython unit tests under the GenBank directory.
You could read the file like this, using the Bio.SeqIO.parse() function:
Notice that this file contains six records. Now instead of printing the records, let’s pass the SeqRecord iterator to the Bio.SeqIO.write() function, to turn this GenBank file into a Fasta file:
Or more concisely using the Bio.SeqIO.convert()