bio-0.5.2: A bioinformatics library

Safe Haskell | Safe-Infered

Bio.Sequence.SFF

Description

Read and write the SFF file format used by Roche/454 sequencing to store flowgram data.

A flowgram is a series of values (intensities) representing homopolymer runs of A,G,C, and T in a fixed cycle, and usually displayed as a histogram.

This file is based on information in the Roche FLX manual. Among other sources for information about the format, are The Staden Package, which contains an io_lib with a C routine for parsing this format. According to comments in the sources, the io_lib implementation is based on a file called getsff.c, which I've been unable to track down. Other software parsing SFFs are QIIME, sff_extract, and Celera's sffToCa.

It is believed that all values are stored big endian.

Synopsis

- data SFF = SFF !CommonHeader [ReadBlock]
- data CommonHeader = CommonHeader {
  - index_offset :: Int64
  - index_length :: Int32
  - num_reads :: Int32
  - key_length :: Int16
  - flow_length :: Int16
  - flowgram_fmt :: Word8
  - flow :: ByteString
  - key :: ByteString
  }
- data ReadHeader = ReadHeader {
  - name_length :: Int16
  - num_bases :: Int32
  - clip_qual_left :: Int16
  - clip_qual_right :: Int16
  - clip_adapter_left :: Int16
  - clip_adapter_right :: Int16
  - read_name :: ByteString
  }
- data ReadBlock = ReadBlock {
  - read_header :: !ReadHeader
  - flow_data :: !ByteString
  - flow_index :: !ByteString
  - bases :: !SeqData
  - quality :: !QualData
  }
- readSFF :: FilePath -> IO SFF
- writeSFF :: FilePath -> SFF -> IO ()
- writeSFF' :: FilePath -> SFF -> IO Int
- recoverSFF :: FilePath -> IO SFF
- sffToSequence :: SFF -> [Sequence Nuc]
- rbToSequence :: ReadBlock -> Sequence Nuc
- trim :: ReadBlock -> ReadBlock
- trimFromTo :: Integral i => i -> i -> ReadBlock -> ReadBlock
- trimKey :: CommonHeader -> Sequence Nuc -> Maybe (Sequence Nuc)
- baseToFlowPos :: Integral i => ReadBlock -> i -> Int
- flowToBasePos :: Integral i => ReadBlock -> i -> Int
- trimFlows :: Integral i => i -> ReadBlock -> ReadBlock
- test :: FilePath -> IO ()
- convert :: FilePath -> IO ()
- flowgram :: ReadBlock -> [Flow]
- masked_bases :: ReadBlock -> SeqData
- cumulative_index :: ReadBlock -> [Int]
- packFlows :: [Flow] -> ByteString
- unpackFlows :: ByteString -> [Flow]
- type Flow = Int16
- type Qual = Word8
- type Index = Word8
- type SeqData = ByteString
- type QualData = ByteString
- data ReadName = ReadName {
  - date :: (Int, Int, Int)
  - time :: (Int, Int, Int)
  - region :: Int
  - x_loc :: Int
  - y_loc :: Int
  }
- decodeReadName :: ByteString -> Maybe ReadName
- encodeReadName :: ReadName -> ByteString

# Documentation

data SFF

The data structure storing the contents of an SFF file (modulo the index)

Constructors

SFF !CommonHeader [ReadBlock] |

Instances

Show SFF |
Binary SFF |

data CommonHeader

SFF has a 31-byte common header

The format is open to having the index anywhere between reads, we should really keep count and check for each read. In practice, it seems to be places after the reads.

The following two fields are considered part of the header, but as they are static, they are not part of the data structure

         magic   :: Word32   -- 0x2e736666, i.e. the string ".sff"
         version :: Word32   -- 0x00000001

Constructors

CommonHeader |

Fields

index_offset :: Int64

  Points to a text(?) section

index_length :: Int32
num_reads :: Int32
key_length :: Int16
flow_length :: Int16
flowgram_fmt :: Word8
flow :: ByteString
key :: ByteString

Instances

Show CommonHeader |
Binary CommonHeader |

data ReadHeader

Each Read has a fixed read header, containing various information.

Constructors

ReadHeader |

Fields

name_length :: Int16
num_bases :: Int32
clip_qual_left :: Int16
clip_qual_right :: Int16
clip_adapter_left :: Int16
clip_adapter_right :: Int16
read_name :: ByteString

Instances

Show ReadHeader |
Binary ReadHeader |

data ReadBlock

This contains the actual flowgram for a single read.

Constructors

ReadBlock |

Fields

read_header :: !ReadHeader
flow_data :: !ByteString
flow_index :: !ByteString
bases :: !SeqData
quality :: !QualData

Instances

Show ReadBlock |

readSFF :: FilePath -> IO SFF

Read an SFF file.

writeSFF :: FilePath -> SFF -> IO ()

Write an `SFF` to the specified file name

writeSFF' :: FilePath -> SFF -> IO Int

Write an `SFF` to the specified file name, but go back and update the read count. Useful if you want to output a lazy stream of `ReadBlock`s. Returns the number of reads written.

recoverSFF :: FilePath -> IO SFF

Read an SFF file, but be resilient against errors.

sffToSequence :: SFF -> [Sequence Nuc]

Extract the sequences from an `SFF` data structure.

rbToSequence :: ReadBlock -> Sequence Nuc

Extract the sequence information from a `ReadBlock`.

trim :: ReadBlock -> ReadBlock

Trim a read according to clipping information

trimFromTo :: Integral i => i -> i -> ReadBlock -> ReadBlock

Trim a read to specific sequence position, inclusive bounds.

trimKey :: CommonHeader -> Sequence Nuc -> Maybe (Sequence Nuc)

Extract the read without the initial (TCAG) key.

baseToFlowPos :: Integral i => ReadBlock -> i -> Int

Convert a sequence position to the corresponding flow position

flowToBasePos :: Integral i => ReadBlock -> i -> Int

Convert a flow position to the corresponding sequence position

trimFlows :: Integral i => i -> ReadBlock -> ReadBlock

Trim a `ReadBlock` limiting the number of flows. If writing to an SFF file, make sure you update the `CommonHeader` accordingly. See `examples/Flx.hs` for how to use this.

test :: FilePath -> IO ()

test serialization by output'ing the header and first two reads in an SFF, and the same after a decode + encode cycle.

convert :: FilePath -> IO ()

Convert a file by decoding it and re-encoding it This will lose the index (which isn't really necessary)

flowgram :: ReadBlock -> [Flow]

Helper function to access the flowgram

masked_bases :: ReadBlock -> SeqData

Extract the sequence with masked bases in lower case

cumulative_index :: ReadBlock -> [Int]

Extract the index as absolute coordinates, not relative.

packFlows :: [Flow] -> ByteString

Pack a list of flows into the corresponding binary structure (the flow_data field)

unpackFlows :: ByteString -> [Flow]

Unpack the flow_data field into a list of flow values

type Flow = Int16

The type of flowgram value

type Qual = Word8

Basic type for quality data. Range 0..255. Typical Phred output is in the range 6..50, with 20 as the line in the sand separating good from bad.

type Index = Word8

type SeqData = ByteString

The basic data type used in `Sequence`s

type QualData = ByteString

Quality data is a `Qual` vector, currently implemented as a `ByteString`.

data ReadName

Read names encode various information, as per this struct.

Constructors

ReadName |

Fields

date :: (Int, Int, Int)
time :: (Int, Int, Int)
region :: Int
x_loc :: Int
y_loc :: Int

Instances

Show ReadName |

decodeReadName :: ByteString -> Maybe ReadName

encodeReadName :: ReadName -> ByteString