BioMap Class

Superclasses: BioRead

Contain sequence, quality, alignment, and mapping data

Description

The BioMap class contains data from short-read sequences, including sequence headers, read sequences, quality scores for the sequences, and data about how each sequence aligns to a given reference. This data is typically obtained from a high-throughput sequencing instrument.

Construct a BioMap object from short-read sequence data. Each element in the object has a sequence, header, quality score, and alignment/mapping information associated with it. Use the object properties and methods to explore, access, filter, and manipulate all or a subset of the data, before analyzing or viewing the data.

Construction

BioMapobj = BioMap constructs BioMapobj, which is an empty BioMap object.

BioMapobj = BioMap(File) constructs BioMapobj, a BioMap object, from File, a SAM- or BAM-formatted file whose reads are ordered by start position in the reference sequence. The data remains in the source file, and the BioMap object accesses it using one or two auxiliary index files. For a SAM-formatted file, MATLAB^® uses or creates one index file that must have the same name as the source file, but with an .idx extension. For a BAM-formatted file, MATLAB uses or creates two index files that must have the same name as the source file, but with *.bai and *.linearindex extensions. If the index files are not found in the same folder as the source file, the BioMap constructor function creates the index files in that folder.

When you pass in an unordered BAM-formatted file, the constructor automatically orders the file and writes the data to an ordered file using the same base name and extension with an added character vector “.ordered” before the extension. The new file is indexed and used to instantiate the new BioMap object.

Note

Because the data remains in the source file and is accessed using the index files:

Do not delete the source file (SAM or BAM).
Do not delete the index files (*.idx,*.bai, or *.linearindex).
You cannot modify BioMapobj properties.

Tip

To determine the number of reference sequences included in your source file, use the saminfo or baminfo function. Use SAMtools to check if the reads in your source file are ordered by position in the reference sequence, and also to reorder them, if needed.

BioMapobj = BioMap(Struct) constructs BioMapobj, a BioMap object, from Struct, a MATLAB structure containing sequence and alignment information, such as returned by the samread or bamread function. The data from Struct remains in memory, which lets you modify the BioMapobj properties.

BioMapobj = BioMap(___,'Name',Value) constructs the BioMap object using any of previous input arguments and additional options, specified as name-value pair arguments as follows.

BioMapobj = BioMap(___,'SelectReference',SelectRefValue) selects one or more references when the source data contains sequences mapped to more than one reference. By default, the constructor includes all of the references in the header dictionary of the source file. When the header dictionary is not available, the constructor defaults to including all reference names found in the source data. SelectRefValue is a character vector, string, string vector, or cell array of character vectors. By using this option, you can prevent the BioMap constructor from creating auxiliary index files for references that you will not use in your analysis. If any reads mapped to selected references are paired and BioMapobj is written to a file, the reference sequences of the mates are also included in the file header.

BioMapobj = BioMap(File,'InMemory',InMemoryValue) specifies whether to place the data in memory or leave the data in the source file. Leaving the data in the source file and accessing via an index file is more memory efficient, but does not let you modify properties of BioMapobj. Choices are true or false (default). If the first input argument is not a file name, then this name-value pair argument is ignored, and the data is automatically placed in memory.

Tip

Set the 'InMemory' name-value pair argument to true if you want to modify the properties of BioMapobj.

BioMapobj = BioMap(___,'IndexDir',IndexDirValue) specifies the path to the folder where the index files (*.idx,*.bai, or *.linearindex) either exist or will be created.

Tip

Use the 'IndexDir' name-value pair argument if you do not have write access to the folder where the source file is located.

BioMapobj = BioMap(___,'Sequence',SequenceValue) constructs BioMapobj, a BioMap object, from SequenceValue that contains he letter representations of nucleotide sequences. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Header',HeaderValue) constructs BioMapobj, a BioMap object, from HeaderValue that contains header text for nucleotide sequences. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Quality',QualityValue) constructs BioMapobj, a BioMap object, from QualityValue that contains the ASCII representation of per-base quality scores for nucleotide sequences. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Reference',ReferenceValue) constructs BioMapobj, a BioMap object, and sets the Reference property to ReferenceValue that contains the names of the reference sequences. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Signature',SignatureValue) constructs BioMapobj, a BioMap object, from SignatureValue that contains information describing the alignment of each read sequence with the reference sequence. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Start',StartValue) constructs BioMapobj, a BioMap object, from StartValue, a vector of positive integers specifying the position in the reference sequence where the alignment of each read sequence starts. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'Flag',FlagValue) constructs BioMapobj, a BioMap object, from FlagValue, a vector of positive integers indicating the bit-wise information for the status of the 11 flags specified by the SAM format specification. These flags describe different sequencing and alignment aspects of the read sequences. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'MappingQuality',MappingQualityValue) constructs BioMapobj, a BioMap object, from MappingQualityValue, a vector of positive integers specifying the mapping quality for each read sequence. This name-value pair works only if the data is read into memory.

BioMapobj = BioMap(___,'MatePosition',MatePositionValue) constructs BioMapobj, a BioMap object, from MatePositionValue, a vector of nonnegative integers specifying the mate position for each read sequence. This name-value pair works only if the data is read into memory.

Input Arguments

`File`	Character vector or string specifying a SAM- or BAM-formatted file that contains only one reference sequence and whose reads are ordered by start position in the reference sequence.
`Struct`	MATLAB structure containing sequence and alignment information, such as returned by the `samread` or `bamread` function. The structure must have a one-based start position.
`SelectRefValue`	Character vector, string, string vector, or cell array of character vectors specifying the name of the reference sequences in `File` or `Struct`. Use `saminfo` or `baminfo` to see a complete list of reference sequences in `File`.
`InMemoryValue`	Logical specifying whether to place the data in memory or leave the data in the source file. Leaving the data in the source file and accessing it via an index file is more memory efficient, but does not let you modify properties of the `BioMap` object. If the first input argument is not a file name, then this name-value pair argument is ignored, and the data is automatically placed in memory. Default: `false`
`IndexDirValue`	Character vector or string specifying the path to the folder where the index file either exists or will be created. Default: Folder where `File` is located
`SequenceValue`	String vector or cell array of character vectors containing the letter representations of nucleotide sequences. This information populates the `BioMap` object's `Sequence` property. The `samread` and `bamread` functions return this information in the `Sequence` field of the output structure.
`QualityValue`	String vector or cell array of character vectors containing the ASCII representation of per-base quality scores for nucleotide sequences. This information populates the `BioMap` object's `Quality` property. The `samread` and `bamread` functions return this information in the `Quality` field of the output structure.
`HeaderValue`	String vector or cell array of character vectors containing header text for nucleotide sequences. This information populates the `BioMap` object's `Header` property. The `samread` and `bamread` functions return this information in the `QueryName` field of the return structure.
`NameValue`	Character vector or string describing the `BioMap` object. This information populates the object's `Name` property. Default: `' '`, an empty character vector
`ReferenceValue`	String vector or cell array of character vectors containing the names of the reference sequences. This information populates the object's `Reference` property. The `samread` function returns this information in the `ReferenceName` field of the `SAMStruct` output argument. The `bamread` function returns this information in the `Reference` field of the `HeaderStruct` output structure.
`SignatureValue`	String vector or cell array of character vectors containing information describing the alignment of each read sequence with the reference sequence. The `samread` and `bamread` functions return this information in the `CigarString` field of the return structure. This information populates the object's `Signature` property.
`StartValue`	Vector of positive integers specifying the position in the reference sequence where the alignment of each read sequence starts. This information populates the object's `Start` property. The `samread` and `bamread` functions return this information in the `Position` field of the output structure.
`FlagValue`	Vector of positive integers indicating the bit-wise information for the status of the 11 flags specified by the SAM format specification. These flags describe different sequencing and alignment aspects of the read sequences. This information populates the object's `Flag` property. The `samread` and `bamread` functions return this information in the `Flag` field of the output structure.
`MappingQualityValue`	Vector of positive integers specifying the mapping quality for each read sequence. This information populates the object's `MappingQuality` property. The `samread` and `bamread` functions return this information in the `MappingQuality` field of the output structure.
`MatePositionValue`	Vector of nonnegative integers specifying the mate position for each read sequence. This information populates the object's `MatePosition` property. The `samread` and `bamread` functions return this information in the `MatePosition` field of the output structure.

Properties

`Flag`	Flags associated with all read sequences represented in the `BioMap` object. Vector of positive integers such that there is an integer for each read sequence in the object. Each integer indicates the bit-wise information that specifies the status of the 11 flags described by the SAM format specification. These flags describe different sequencing and alignment aspects of a read sequence. A one-to-one relationship exists between the number and order of elements in `Flag` and `Sequence`, unless `Flag` is an empty vector.
`Header`	Headers associated with all read sequences represented in the `BioMap` object. Cell array of character vectors, such that there is a header for each read sequence in the object. Headers can be empty. A one-to-one relationship exists between the number and order of elements in `Header` and `Sequence`, unless `Header` is an empty cell array.
`MatePosition`	Positions of the mates for all read sequences represented in the `BioMap` object. Vector of nonnegative integers such that there is an integer for each read sequence in the object. Each integer indicates the position of the corresponding mate sequence, relative to the reference sequence. A one-to-one relationship exists between the number and order of elements in `MatePosition` and `Sequence`, unless `MatePosition` is an empty vector. Not all values in the `MatePosition` vector represent valid mate positions, for example, mates that map to a different reference sequence or mates that do not map. To determine if a mate position is valid, use the `filterByFlag` method with the `'pairedInMap'` flag.
`MappingQuality`	Mapping quality scores associated with all read sequences represented in the `BioMap` object. Vector of integers, such that there is a mapping quality score for each read sequence in the object. A one-to-one relationship exists between the number and order of elements in `MappingQuality` and `Sequence`, unless `MappingQuality` is an empty vector.
`Name`	Description of the `BioMap` object. Character vector describing the `BioMap` object. Default: `' '`, an empty character vector
`NSeqs`	Number of sequences in the `BioMap` object. This information is read-only.
`Quality`	Per-base quality scores associated with all read sequences represented in the `BioMap` object. Cell array of character vectors, such that there is a quality for each read sequence in the object. Each quality is an ASCII representation of per-base quality scores for a read sequence. Quality can be an empty character vector. A one-to-one relationship exists between the number and order of elements in `Quality` and `Sequence`, unless `Quality` is an empty cell array.
`Reference`	Reference sequences in the `BioMap` object. `BioMapobj.NSeqs`-by-1 cell array of character vectors specifying the names of the reference sequences. The reference sequences are the sequences against which the read sequences are aligned.
`Sequence`	Read sequences in the `BioMap` object. Cell array of character vectors containing the letter representations of the read sequences.
`SequenceDictionary`	Cell array of character vectors that catalogs the names of the references available in the `BioMap` object. This information is read-only.
`Signature`	Alignment information associated with all read sequences represented in the `BioMap` object. Cell array of CIGAR–formatted character vectors, such that there is alignment information for each read sequence in the object. Each character vector represents how a read sequence aligns to the reference sequence. Signatures can be empty character vectors. A one-to-one relationship exists between the number and order of elements in `Signature` and `Sequence`, unless `Signature` is an empty cell array.
`Start`	Start positions of all aligned read sequences represented in the `BioMap` object. Vector of integers, such that there is a start position for each read sequence in the object. Each integer specifies the start position of the aligned read sequence with respect to the position numbers in the reference sequence. A one-to-one relationship exists between the number and order of elements in `Start` and `Sequence`, unless `Start` is an empty vector.

Methods

filterByFlag	Filter sequence reads by SAM flag
getAlignment	Construct alignment represented in `BioMap` object
getBaseCoverage	Return base-by-base alignment coverage of reference sequence in `BioMap` object
getCompactAlignment	Construct compact alignment represented in `BioMap` object
getCounts	Return count of read sequences aligned to reference sequence in `BioMap` object
getFlag	Retrieve read sequence flags from `BioMap` object
getIndex	Return indices of read sequences aligned to reference sequence in `BioMap` object
getInfo	Retrieve information for single element of `BioMap` object
getMappingQuality	Retrieve sequence mapping quality scores from `BioMap` object
getReference	Retrieve reference sequence from `BioMap` object
getSignature	Retrieve signature (alignment information) from `BioMap` object
getStart	Retrieve start positions of aligned read sequences from `BioMap` object
getStop	Compute stop positions of aligned read sequences from `BioMap` object
getSummary	Print summary of `BioMap` object
setFlag	Set read sequence flags for `BioMap` object
setMappingQuality	Set sequence mapping quality scores for `BioMap` object
setReference	Set name of reference sequence for `BioMap` object
setSignature	Set signature (alignment information) for `BioMap` object
setStart	Set start positions of aligned read sequences in `BioMap` object

Inherited Methods

combine	Combine two objects
get	Retrieve property of object
getHeader	Retrieve sequence headers from object
getQuality	Retrieve sequence quality information from object
getSequence	Retrieve sequences from object
getSubsequence	Retrieve partial sequences from object
getSubset	Retrieve subset of elements from object
set	Set property of object
setHeader	Update header information of reads
setQuality	Update quality information
setSequence	Update read sequences
setSubsequence	Update partial sequences
setSubset	Update elements of object
write	Write contents of BioRead or BioMap object to file

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation.

Indexing

BioMap objects support dot . indexing to extract, assign, and delete data.

Examples

collapse all

Construct a BioMap object

Open Live Script

This example shows how to construct a BioMap object from a SAM file and from a structure.

Construct a BioMap object from a SAM-formatted file that is provided with Bioinformatics Toolbox™ and set the Name property.

BMObj1 = BioMap('ex1.sam', 'Name', 'MyObject')

BMObj1 = 
  BioMap with properties:

    SequenceDictionary: 'seq1'
             Reference: [1501x1 File indexed property]
             Signature: [1501x1 File indexed property]
                 Start: [1501x1 File indexed property]
        MappingQuality: [1501x1 File indexed property]
                  Flag: [1501x1 File indexed property]
          MatePosition: [1501x1 File indexed property]
               Quality: [1501x1 File indexed property]
              Sequence: [1501x1 File indexed property]
                Header: [1501x1 File indexed property]
                 NSeqs: 1501
                  Name: 'MyObject'

Construct a structure containing information from a SAM file.

SAMStruct = samread('ex1.sam');

Construct a BioMap object from this structure.

BMObj2 = BioMap(SAMStruct)

BMObj2 = 
  BioMap with properties:

    SequenceDictionary: {'seq1'}
             Reference: {1501x1 cell}
             Signature: {1501x1 cell}
                 Start: [1501x1 uint32]
        MappingQuality: [1501x1 uint8]
                  Flag: [1501x1 uint16]
          MatePosition: [1501x1 uint32]
               Quality: {1501x1 cell}
              Sequence: {1501x1 cell}
                Header: {1501x1 cell}
                 NSeqs: 1501
                  Name: ''

BioMap Class

Description

Construction

Input Arguments

Properties

Methods

Inherited Methods

Copy Semantics

Indexing

Examples

Construct a BioMap object

See Also

Topics

External Websites