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.

example

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

expand all

`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

expand all

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

expand all

`BioMapobj` — `BioMap` object
`BioMap` object

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

Properties

expand all

`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

expand all

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

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: {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

BioMap

Description

Creation

Syntax

Description

Input Arguments

File — SAM- or BAM-formatted file character vector | string scalar

Struct — Sequence and alignment information structure

Name-Value Arguments

SelectReference — Reference sequences to select character vector | string scalar | string vector | cell array of character vectors

InMemory — Indicator to place data in memory false or 0 (default) | true or 1

IndexDir — Path to folder where index files exist character vector | string scalar

Sequence — Nucleotide sequences string vector | cell array of character vectors

Header — Header text for nucleotide sequences string vector | cell array of character vectors

Name — Object name or description '' (default) | character vector | string scalar

Quality — Per-base quality scores string vector | cell array of character vectors

Reference — Names of reference sequences string vector | cell array of character vectors

Signature — Alignment information for read sequences string vector | cell array of character vectors

Start — Start positions of aligned read sequences vector of positive integers

Flag — SAM format flags for read sequences vector of positive integers

MappingQuality — Mapping quality for read sequences vector of positive integers

MatePosition — Mate positions for read sequences vector of nonnegative integers

Output Arguments

BioMapobj — BioMap object BioMap object

Properties

Flag — Flags associated with all read sequences vector of positive integers

Header — Headers associated with all read sequences cell array of character vectors

MappingQuality — Mapping quality scores associated with all read sequences vector of integers

MatePosition — Positions of the mates for all read sequences vector of nonnegative integers

Name — Object name or description '' (default) | character vector | string scalar

NSeqs — Number of sequences Read-only: positive integer

Quality — Per-base quality scores associated with all read sequences cell array of character vectors

Reference — Reference sequences cell array of character vectors

Sequence — Read sequences cell array of character vectors

SequenceDictionary — Names of available references Read-only: cell array of character vectors

Signature — Alignment information associated with all read sequences cell array of character vectors

Start — Start positions of all aligned read sequences vector of integers

Object Functions

Filtering, Subsetting, and Combining

Alignment, Mapping, and Reference Management

Flags, Sequence, Quality, and Header Data

Object Summary, Properties, and Export

Examples

Construct a BioMap object

Version History

See Also

Topics

`File` — SAM- or BAM-formatted file
character vector | string scalar

`Struct` — Sequence and alignment information
structure

`SelectReference` — Reference sequences to select
character vector | string scalar | string vector | cell array of character vectors

`InMemory` — Indicator to place data in memory
`false` or 0 (default) | `true` or 1

`IndexDir` — Path to folder where index files exist
character vector | string scalar

`Sequence` — Nucleotide sequences
string vector | cell array of character vectors

`Header` — Header text for nucleotide sequences
string vector | cell array of character vectors

`Name` — Object name or description
`''` (default) | character vector | string scalar

`Quality` — Per-base quality scores
string vector | cell array of character vectors

`Reference` — Names of reference sequences
string vector | cell array of character vectors

`Signature` — Alignment information for read sequences
string vector | cell array of character vectors

`Start` — Start positions of aligned read sequences
vector of positive integers

`Flag` — SAM format flags for read sequences
vector of positive integers

`MappingQuality` — Mapping quality for read sequences
vector of positive integers

`MatePosition` — Mate positions for read sequences
vector of nonnegative integers

`BioMapobj` — `BioMap` object
`BioMap` object

`Flag` — Flags associated with all read sequences
vector of positive integers

`Header` — Headers associated with all read sequences
cell array of character vectors

`MappingQuality` — Mapping quality scores associated with all read sequences
vector of integers

`MatePosition` — Positions of the mates for all read sequences
vector of nonnegative integers

`Name` — Object name or description
`''` (default) | character vector | string scalar

`NSeqs` — Number of sequences
Read-only: positive integer

`Quality` — Per-base quality scores associated with all read sequences
cell array of character vectors

`Reference` — Reference sequences
cell array of character vectors

`Sequence` — Read sequences
cell array of character vectors

`SequenceDictionary` — Names of available references
Read-only: cell array of character vectors

`Signature` — Alignment information associated with all read sequences
cell array of character vectors

`Start` — Start positions of all aligned read sequences
vector of integers