saminfo

R2026b

Return information about SAM file

Syntax

InfoStruct = saminfo(File)

InfoStruct = saminfo(File,Name=Value)

Description

InfoStruct = saminfo(File) returns information about a SAM-formatted file.

InfoStruct = saminfo(File,Name=Value) uses additional options specified by one or more name-value arguments. For example, you can specify to include the read count in the output.

Examples

Get SAM File Information

Return information from the ex1.sam file included with the toolbox.

info = saminfo("ex1.sam")

info =

                  Filename: 'ex1.sam'
                  FilePath: [1x89 char]
                  FileSize: 254270
               FileModDate: '12-May-2011 14:23:25'
                    Header: [1x1 struct]
        SequenceDictionary: [1x1 struct]
                 ReadGroup: [1x2 struct]
                  NumReads: []
         ScannedDictionary: {0x1 cell}
    ScannedDictionaryCount: [0x1 uint64]

Include the number of sequence reads.

info = saminfo("ex1.sam",NumOfReads=true)

info =

                  Filename: 'ex1.sam'
                  FilePath: [1x89 char]
                  FileSize: 254270
               FileModDate: '12-May-2011 14:23:25'
                    Header: [1x1 struct]
        SequenceDictionary: [1x1 struct]
                 ReadGroup: [1x2 struct]
                  NumReads: 1501
         ScannedDictionary: {0x1 cell}
    ScannedDictionaryCount: [0x1 uint64]

Input Arguments

File — SAM file

character vector | string scalar

SAM file, specified as a character vector or string scalar. Specify a filename or path and filename of a SAM-formatted file. If you specify only a filename, that file must be on the MATLAB^® search path or in the current folder.

Tip

Use saminfo to investigate the size and content of a SAM file before using the samread function to read the file contents into a structure.

Data Types: char | string

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: InfoStruct = saminfo(File,NumOfReads=true) specifies to include the number of sequence reads in the output structure.

NumOfReads — Flag to include read count

false or 0 (default) | true or 1

Flag to include read counts in the output, specified as a numeric or logical 1 (true) or 0 (false). If true, the output structure includes a NumReads field containing the number of sequence reads in the file.

Note

Setting NumOfReads to true can significantly increase the time to create the output structure.

Data Types: logical

ScanDictionary — Reference scanning flag

false or 0 (default) | true or 1

Reference scanning flag, specified as a numeric or logical 1 (true) or 0 (false). If true, the output structure includes ScannedDictionary and ScannedDictionaryCount fields containing the reference names and the number of reads aligned to each reference.

Data Types: logical

Output Arguments

InfoStruct — SAM file summary information

structure

SAM file summary information, returned as a structure. The structure contains these fields.

Field	Description
Filename	Name of the SAM-formatted file.
FilePath	Path to the file.
FileSize	Size of the file in bytes.
FileModDate	Modification date of the file.
NumReads*	Number of sequence reads in the file.
ScannedDictionary*	Cell array of character vectors specifying the names of the reference sequences in the SAM-formatted file.
ScannedDictionaryCount*	Cell array specifying the number of reads aligned to each reference sequence.
Header**	Structure containing the file format version, sort order, and group order.
SequenceDictionary**	Structure containing the: Sequence name Sequence length Genome assembly identifier MD5 checksum of sequence URI of sequence Species
ReadGroup**	Structure containing the: Read group identifier Sample Library Description Platform unit Predicted median insert size Sequencing center Date Platform
Program**	Structure containing the: Program name Version Command line

* — The NumReads field is empty if you do not set the NumOfReads name-value argument to true. The ScannedDictionary and ScannedDictionaryCount fields are empty if you do not set the ScanDictionary name-value argument to true.

** — These structures and their fields appear in the output structure only if they are in the SAM file. The information in these structures depends on the information in the SAM file.

Version History

Introduced in R2010a