BioMap

R2026b

Contain sequence, quality, alignment, and mapping data

Description

A BioMap object contains data from short-read sequences, including sequence headers, read sequences, quality scores, and data about how each sequence aligns to a given reference.

Create 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 functions to explore, access, filter, and manipulate all or a subset of the data, before analyzing or viewing the data.

Creation

Syntax

BioMapobj = BioMap

BioMapobj = BioMap(File)

BioMapobj = BioMap(Struct)

BioMapobj = BioMap(___,Name=Value)

Description

BioMapobj = BioMap creates an empty BioMap object.

BioMapobj = BioMap(File) creates 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.

BioMapobj = BioMap(Struct) creates 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) uses additional options specified as one or more name-value arguments for any of previous input arguments. For example, InMemory=true specifies to place data in memory.

Input Arguments

File — SAM- or BAM-formatted file

character vector | string scalar

SAM- or BAM-formatted file, specified as a character vector or string scalar. The file must contain reads 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 function creates the index files in that folder.

When you pass in an unordered BAM-formatted file, the function automatically orders the file and writes the data to an ordered file using the same base name and extension with an added text .ordered before the extension. The new file is indexed and used to create 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.

Data Types: char | string

Struct — Sequence and alignment information

structure

Sequence and alignment information, specified as a MATLAB structure. For instance, such a structure is returned by the samread or bamread function. The structure must have a one-based start position.

Data Types: struct

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: BioMapobj = BioMap('ex1.bam',InMemory=true) specifies to load the data in memory instead of leaving it in the source file.

SelectReference — Reference sequences to select

character vector | string scalar | string vector | cell array of character vectors

Reference sequences to select, specified as a character vector, string scalar, string vector, or cell array of character vectors. Use this option to select one or more references when the source data contains sequences mapped to more than one reference. By default, the function includes all of the references in the header dictionary of the source file. When the header dictionary is not available, the function defaults to including all reference names found in the source data.

By using this option, you can prevent the BioMap function 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.

Data Types: char | string | cell

InMemory — Indicator to place data in memory

false or 0 (default) | true or 1

Indicator to place data in memory, specified as a numeric or logical 1 (true) or 0 (false). 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 argument is ignored, and the data is automatically placed in memory.

Tip

Set InMemory to true if you want to modify the properties of BioMapobj.

Data Types: logical

IndexDir — Path to folder where index files exist

character vector | string scalar

Path to the folder where the index files (*.idx, *.bai, or *.linearindex) either exist or will be created, specified as a character vector or string scalar. By default, the index file folder is the folder where File is located.

Tip

Use IndexDir if you do not have write access to the folder where the source file is located.

Data Types: char | string

Sequence — Nucleotide sequences

string vector | cell array of character vectors

Nucleotide sequences, specified as a string vector or cell array of character vectors containing the letter representations of nucleotide sequences. This name-value argument works only if the data is read into memory.

This argument sets the object Sequence property. The samread and bamread functions return this information in the Sequence field of the output structure.

Data Types: string | cell

Header — Header text for nucleotide sequences

string vector | cell array of character vectors

Header text for nucleotide sequences, specified as a string vector or cell array of character vectors. This name-value argument works only if the data is read into memory.

This argument sets the object Header property. The samread and bamread functions return this information in the QueryName field of the returned structure.

Data Types: string | cell

Name — Object name or description

'' (default) | character vector | string scalar

Object name or description, specified as a character vector or string scalar.

This argument sets the object Name property.

Data Types: char | string

Quality — Per-base quality scores

string vector | cell array of character vectors

Per-base quality scores, specified as a string vector or cell array of character vectors containing the ASCII representation of per-base quality scores for nucleotide sequences. This name-value argument works only if the data is read into memory.

This argument sets the object Quality property. The samread and bamread functions return this information in the Quality field of the output structure.

Data Types: string | cell

Reference — Names of reference sequences

string vector | cell array of character vectors

Names of reference sequences, specified as a string vector or cell array of character vectors. This name-value argument works only if the data is read into memory.

This argument sets the object 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.

Data Types: string | cell

Signature — Alignment information for read sequences

string vector | cell array of character vectors

Alignment information for read sequences, specified as a string vector or cell array of character vectors containing information describing the alignment of each read sequence with the reference sequence. This name-value argument works only if the data is read into memory.

This argument sets the object Signature property. The samread and bamread functions return this information in the CigarString field of the return structure.

Data Types: string | cell

Start — Start positions of aligned read sequences

vector of positive integers

Start positions of aligned read sequences, specified as a vector of positive integers specifying the position in the reference sequence where the alignment of each read sequence starts. This name-value argument works only if the data is read into memory.

This argument sets the object Start property. The samread and bamread functions return this information in the Position field of the output structure.

Data Types: double

Flag — SAM format flags for read sequences

vector of positive integers

SAM format flags for read sequences, specified as 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 argument works only if the data is read into memory.

This argument sets the object Flag property. The samread and bamread functions return this information in the Flag field of the output structure.

Data Types: double

MappingQuality — Mapping quality for read sequences

vector of positive integers

Mapping quality for read sequences, specified as a vector of positive integers specifying the mapping quality for each read sequence. This name-value argument works only if the data is read into memory.

This argument sets the object MappingQuality property. The samread and bamread functions return this information in the MappingQuality field of the output structure.

Data Types: double

MatePosition — Mate positions for read sequences

vector of nonnegative integers

Mate positions for read sequences, specified as a vector of nonnegative integers specifying the mate position for each read sequence. This name-value argument works only if the data is read into memory.

This argument sets the object MatePosition property. The samread and bamread functions return this information in the MatePosition field of the output structure.

Data Types: double

Output Arguments

BioMapobj — BioMap object

BioMap object

BioMap object, returned as a BioMap object containing sequence, quality, alignment, and mapping data.

Properties

Flag — Flags associated with all read sequences

vector of positive integers

Flags associated with all read sequences, specified as a 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.

Data Types: double

Header — Headers associated with all read sequences

cell array of character vectors

Headers associated with all read sequences, specified as a 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.

Data Types: cell

MappingQuality — Mapping quality scores associated with all read sequences

vector of integers

Mapping quality scores associated with all read sequences, specified as a 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.

Data Types: double

MatePosition — Positions of the mates for all read sequences

vector of nonnegative integers

Positions of the mates for all read sequences, specified as a 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 function with the 'pairedInMap' flag.

Data Types: double

Name — Object name or description

'' (default) | character vector | string scalar

Object name or description, specified as a character vector or string scalar.

Data Types: char | string

NSeqs — Number of sequences

Read-only: positive integer

This property is read-only.

Number of sequences in the BioMap object, represented as a positive integer.

Data Types: double

Quality — Per-base quality scores associated with all read sequences

cell array of character vectors

Per-base quality scores associated with all read sequences, specified as a 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.

Data Types: cell

Reference — Reference sequences

cell array of character vectors

Reference sequences, specified as a cell array of character vectors containing the names of the reference sequences. The reference sequences are the sequences against which the read sequences are aligned.

The cell array has the size of N-by-1, where N is BioMapobj.NSeqs.

Data Types: cell

Sequence — Read sequences

cell array of character vectors

Read sequences, specified as a cell array of character vectors containing the letter representations of the read sequences.

Data Types: cell

SequenceDictionary — Names of available references

Read-only: cell array of character vectors

This property is read-only.

Names of available references, represented as a cell array of character vectors that catalogs the names of the references available in the BioMap object.

Data Types: cell

Signature — Alignment information associated with all read sequences

cell array of character vectors

Alignment information associated with all read sequences, specified as a 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.

Data Types: cell

Start — Start positions of all aligned read sequences

vector of integers

Start positions of all aligned read sequences, specified as a 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.

Data Types: double

Object Functions

Filtering, Subsetting, and Combining

filterByFlag	Filter sequence reads by SAM flag
getSubset	Retrieve subset of elements from object
setSubset	Update elements of object
combine	Combine two objects

Alignment, Mapping, and Reference Management

getAlignment	Construct alignment represented in BioMap object
getCompactAlignment	Construct compact alignment represented in BioMap object
getBaseCoverage	Return base-by-base alignment coverage of reference sequence in BioMap object
getCounts	Return count of read sequences aligned to reference sequence in BioMap object
getIndex	Return indices of read sequences aligned to reference sequence in BioMap object
getStart	Retrieve start positions of aligned read sequences from BioMap object
getStop	Compute stop positions of aligned read sequences from BioMap object
setStart	Set start positions of aligned read sequences in BioMap object
getSignature	Retrieve signature (alignment information) from BioMap object
setSignature	Set signature (alignment information) for BioMap object
getReference	Retrieve reference sequence from BioMap object
setReference	Set name of reference sequence for BioMap object

Flags, Sequence, Quality, and Header Data

getFlag	Retrieve read sequence flags from BioMap object
setFlag	Set read sequence flags for BioMap object
getMappingQuality	Retrieve sequence mapping quality scores from BioMap object
setMappingQuality	Set sequence mapping quality scores for BioMap object
getSequence	Retrieve sequences from object
setSequence	Update read sequences
getSubsequence	Retrieve partial sequences from object
setSubsequence	Update partial sequences
getHeader	Retrieve sequence headers from object
getQuality	Retrieve sequence quality information from object
setHeader	Update header information of reads
setQuality	Update quality information

Object Summary, Properties, and Export

getInfo	Retrieve information for single element of BioMap object
getSummary	Print summary of BioMap object
get	Retrieve property of object
set	Set property of object
write	Write contents of BioRead or BioMap object to file

Examples

Construct a BioMap object

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: {1501×1 cell}
             Signature: {1501×1 cell}
                 Start: [1501×1 uint32]
        MappingQuality: [1501×1 uint8]
                  Flag: [1501×1 uint16]
          MatePosition: [1501×1 uint32]
               Quality: {1501×1 cell}
              Sequence: {1501×1 cell}
                Header: {1501×1 cell}
                 NSeqs: 1501
                  Name: ''

Version History

Introduced in R2010a