read

Read one or more entries from source file associated with BioIndexedFile object

Syntax

Output = read(BioIFobj, Indices) Output = read(BioIFobj, Key)

Description

Output = read(BioIFobj, Indices) reads the entries specified by Indices from the source file associated with BioIFobj, a BioIndexedFile object. Indices is a vector of positive integers specifying indices to entries in the source file. The read method reads and parses the entries using the function specified by the Interpreter property of the BioIndexedFile object. A one-to-one relationship exists between the number and order of elements in Indices and Output, even if Indices has repeated entries. Output is a structure or an array of structures containing the parsed data returned by the interpreter function.

Output = read(BioIFobj, Key) reads the entries specified by Key from the source file associated with BioIFobj, a BioIndexedFile object. Key is a character vector or cell array of character vectors specifying one or more keys to entries in the source file. The read method reads and parses the entries using the function specified by the Interpreter property of the BioIndexedFile object. If the keys in the source file are not unique, the read method reads all entries that match a specified key, all at the position of the key in the Key cell array. If the keys in the source file are unique, there is a one-to-one relationship between the number and order of elements in Key and Output.

Input Arguments

`BioIFobj`	Object of the `BioIndexedFile` class.
`Indices`	Vector of positive integers specifying indices to entries in the source file associated with `BioIFobj`, the BioIndexedFile object. The number of elements in `Indices` must be less than or equal to the number of entries in the source file. There is a one-to-one relationship between the number and order of elements in `Indices` and `Output`, even if `Indices` has repeated entries.
`Key`	Character vector or cell array of character vectors specifying one or more keys in the source file.

Output Arguments

Output

Structure or an array of structures containing the parsed data returned by the interpreter function.

Examples

Construct a BioIndexedFile object to access a table containing cross-references between gene names and gene ontology (GO) terms:

% Create variable containing full absolute path of source file
sourcefile = which('yeastgenes.sgd');
% Create a BioIndexedFile object from the source file. Indicate
% the source file is a tab-delimited file where contiguous rows
% with the same key are considered a single entry. Store the
% index file in the Current Folder. Indicate that keys are
% located in column 3 and that header lines are prefaced with !
gene2goObj = BioIndexedFile('mrtab', sourcefile, '.', ...
                            'KeyColumn', 3, 'HeaderPrefix','!')

Read the GO term from all entries that are associated with the gene YAT2:

% Access entries that have the string YAT2 in their keys
YAT2_entries = getEntryByKey(gene2goObj, 'YAT2');
% Adjust the object interpreter to return only the column
% containing the GO term
gene2goObj.Interpreter = @(x) regexp(x,'GO:\d+','match')
% Parse the entries with a key of YAT2 and return all GO terms
% from those entries
GO_YAT2_entries = read(gene2goObj, 'YAT2')

GO_YAT2_entries = 

'GO:0004092'  'GO:0005737'  'GO:0006066'  'GO:0006066'  'GO:0009437'

Tips

Before using the read method, make sure the Interpreter property of the BioIndexedFile object is set appropriately. The Interpreter property is a handle to a function that parses the entries in the source file. The interpreter function must accept a character vector of one or more concatenated entries and return a structure or an array of structures containing the interpreted data.

If the BioIndexedFile object was created from a source file with an application-specific format such as 'SAM', 'FASTQ', or 'FASTA', the default Interpreter property is a handle to a function appropriate for that file type and typically does not require you to change it. If the BioIndexedFile object was created from a source file with a 'TABLE', 'MRTAB', or 'FLAT' format, then the default Interpreter property is [], which means the interpreter is an anonymous function in which the output is equivalent to the input.

For information on setting the Interpreter property, see BioIndexedFile class.