This package provides I/O functionality for skbio.
For details on what objects are supported by each format, see the associated documentation.
|clustal||Clustal format (skbio.io.format.clustal)|
|fasta||FASTA/QUAL format (skbio.io.format.fasta)|
|fastq||FASTQ format (skbio.io.format.fastq)|
|lsmat||Labeled square matrix format (skbio.io.format.lsmat)|
|newick||Newick format (skbio.io.format.newick)|
|ordination||Ordination results format (skbio.io.format.ordination)|
|phylip||PHYLIP multiple sequence alignment format (skbio.io.format.phylip)|
|qseq||QSeq format (skbio.io.format.qseq)|
|write(obj, format, into, **kwargs)||Write obj as format into a file.|
|read(file[, format, into, verify])||Read file as format into an object.|
|sniff(file, **kwargs)||Detect the format of a given file and suggest kwargs for reading.|
|FormatIdentificationWarning||Warn when the sniffer of a format cannot confirm the format.|
|ArgumentOverrideWarning||Warn when a user provided kwarg differs from a guessed kwarg.|
|UnrecognizedFormatError||Raised when a file’s format is unknown, ambiguous, or unidentifiable.|
|IOSourceError||Raised when a file source cannot be resolved.|
|FileFormatError||Raised when a file cannot be parsed.|
|ClustalFormatError||Raised when a clustal formatted file cannot be parsed.|
|FASTAFormatError||Raised when a fasta formatted file cannot be parsed.|
|FASTQFormatError||Raised when a fastq formatted file cannot be parsed.|
|LSMatFormatError||Raised when a lsmat formatted file cannot be parsed.|
|NewickFormatError||Raised when a newick formatted file cannot be parsed.|
|OrdinationFormatError||Raised when an ordination formatted file cannot be parsed.|
|PhylipFormatError||Raised when a phylip formatted file cannot be parsed.|
|QSeqFormatError||Raised when a qseq formatted file cannot be parsed.|
|QUALFormatError||Raised when a qual formatted file cannot be parsed.|
|registry||I/O Registry (skbio.io.registry)|
|util||I/O utils (skbio.io.util)|
For developer documentation on extending I/O, see skbio.io.registry.
Reading and writing files (I/O) can be a complicated task:
To address these issues (and others), scikit-bio provides a simple, powerful interface for dealing with I/O. We accomplish this by using a single I/O registry.
To see a complete list of file-like inputs that can be used for reading, writing, and sniffing, see the documentation for skbio.io.util.open().
There are two ways to read files. The first way is to use the procedural interface:
my_obj = skbio.io.read(file, format='someformat', into=SomeSkbioClass)
The second is to use the object-oriented (OO) interface which is automatically constructed from the procedural interface:
my_obj = SomeSkbioClass.read(file, format='someformat')
For example, to read a newick file using both interfaces you would type:
>>> from skbio import read >>> from skbio import TreeNode >>> from io import StringIO >>> open_filehandle = StringIO(u'(a, b);') >>> tree = read(open_filehandle, format='newick', into=TreeNode) >>> tree <TreeNode, name: unnamed, internal node count: 0, tips count: 2>
For the OO interface:
>>> open_filehandle = StringIO(u'(a, b);') >>> tree = TreeNode.read(open_filehandle, format='newick') >>> tree <TreeNode, name: unnamed, internal node count: 0, tips count: 2>
In the case of skbio.io.registry.read() if into is not provided, then a generator will be returned. What the generator yields will depend on what format is being read.
When into is provided, format may be omitted and the registry will use its knowledge of the available formats for the requested class to infer the correct format. This format inference is also available in the OO interface, meaning that format may be omitted there as well.
As an example:
>>> open_filehandle = StringIO(u'(a, b);') >>> tree = TreeNode.read(open_filehandle) >>> tree <TreeNode, name: unnamed, internal node count: 0, tips count: 2>
We call format inference sniffing, much like the csv.Sniffer class of Python’s standard library. The goal of a sniffer is twofold: to identify if a file is a specific format, and if it is, to provide **kwargs which can be used to better parse the file.
There is a built-in sniffer which results in a useful error message if an empty file is provided as input and the format was omitted.
Just as when reading files, there are two ways to write files.
skbio.io.write(my_obj, format='someformat', into=file)
In the procedural interface, format is required. Without it, scikit-bio does not know how you want to serialize an object. OO interfaces define a default format, so it may not be necessary to include it.