Input / output¶

MATLAB functions in RAVEN/io of the RAVEN toolbox. Help text is collected from the source of the tracked branch.

Functions¶

Function	Summary
`checkFileExistence`	Check whether files exist.
`cleanSheet`
`exportForGit`	Export a model for a Git-maintained model repository.
`exportModel`	Export a constraint-based model to an SBML file (L3V1 FBCv2).
`exportToExcelFormat`	Export a model to the Microsoft Excel model format.
`exportToTabDelimited`	Export a model to tab-delimited text files.
`importModel`	Import a constraint-based model from an SBML file.
`parseYAML`	Read an arbitrary YAML file into a MATLAB struct/cell tree.
`readFasta`	Read sequences from a FASTA file.
`readYAMLmodel`	Read a model structure from a YAML file.
`writeExcel`	Write one or more sheets to an .xlsx (Office Open XML) file.
`writeFasta`	Write sequences to a FASTA file.
`writeYAMLmodel`	Write a model to a yaml file matching cobrapy's structure.

Reference¶

checkFileExistence¶

Check whether files exist.

If no full path is given a file should be located in the current folder, which by default is appended to the filename.

Input arguments:

Name	Type	Description	Default
`files`	`char or cell`	string or cell array of strings with path to file(s) or path or filename(s).	required

Name-value arguments:

Name	Type	Description
`fullOrTemp`	`double`	controls path handling (default 0): 0 : do not change path to file(s) 1 : return full path to file(s) 2 : copy file(s) to system default temporary folder and return full path
`allowSpace`	`logical`	whether the 'space' character is allowed in the path (default true).
`checkExist`	`logical`	whether file existence should really be checked, as this function can also be used to return the full path to a new file (default true). Can only be set to false if fullOrTemp is set to 1.

Output arguments:

Name	Type	Description
`files`	`char or cell`	string or cell array of strings with updated paths if fullOrTemp was set as 1 or 2, otherwise original paths are returned.

Examples:

files = checkFileExistence(files, fullOrTemp, allowSpace, checkExist);

cleanSheet¶

Clean up an Excel sheet.

Removes empty rows/columns (and performs some other checks).

Input arguments:

Name	Type	Description	Default
`raw`	`cell`	cell array with the data in the sheet.	required

Name-value arguments:

Name	Type	Description
`removeComments`	`logical`	true if commented lines (non-empty first cell in each row) should be removed (default true).
`removeOnlyCap`	`logical`	remove columns with captions but no other values (default false).
`removeNoCap`	`logical`	remove columns without captions (default true).
`removeEmptyRows`	`logical`	remove rows with no non-empty cells (default true).

Output arguments:

Name	Type	Description
`raw`	`cell`	cleaned version.
`keptRows`	`double`	indices of the kept rows in the original structure.
`keptCols`	`double`	indices of the kept columns in the original structure.

Examples:

[raw, keptRows, keptCols] = cleanSheet(raw, removeComments, ...
    removeOnlyCap, removeNoCap, removeEmptyRows);

exportForGit¶

Export a model for a Git-maintained model repository.

Generates a directory structure and populates it with model files, ready to be committed to a Git(Hub) maintained model repository. Writes the model as SBML L3V1 FBCv2 (both XML and YAML), COBRA text, Matlab MAT-file and Microsoft Excel formats.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	model structure in RAVEN format that should be exported.	required

Name-value arguments:

Name	Type	Description
`prefix`	`char`	prefix for all filenames (default 'model').
`path`	`char`	path where the directory structure should be generated and populated with all files (default current working directory).
`formats`	`cell`	cell array of strings specifying in what file formats the model should be exported (default all formats as {'mat', 'txt', 'xlsx', 'xml', 'yml'}).
`mainBranchFlag`	`logical`	if true, function will error if RAVEN (and GECKO for enzyme- constrained models) is/are not on the main branch (default false).
`subDirs`	`logical`	whether model files for each file format should be written in their own subdirectory, with 'model' as parent directory, in accordance to the standard-GEM repository format. If false, all files are stored in the same folder (default true).
`COBRAtext`	`logical`	whether the txt file should be in COBRA Toolbox format using metabolite IDs, instead of metabolite names and compartments (default false).
`neverPrefixIDs`	`logical`	true if prefixes are never added to identifiers, even if they start with e.g. digits. This might result in invalid SBML files (default false).

Examples:

exportForGit(model, prefix, path, formats, mainBranchFlag, subDirs, ...
    COBRAtext, neverPrefixIDs);

exportModel¶

Export a constraint-based model to an SBML file (L3V1 FBCv2).

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`fileName`	`char`	filename to export the model to. A dialog window will open if no file name is specified.
`neverPrefix`	`logical`	true if prefixes are never added to identifiers, even if they start with e.g. digits. This might result in invalid SBML files (default false).
`supressWarnings`	`logical`	true if warnings should be suppressed. This might result in invalid SBML files, as no checks are performed (default false).
`sortIds`	`logical`	whether metabolites, reactions and genes should be sorted alphabetically by their identifiers (default false).

Examples:

exportModel(model, fileName, neverPrefix, supressWarnings, sortIds);

exportToExcelFormat¶

Export a model to the Microsoft Excel model format.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`fileName`	`char`	file name of the Excel file. Only xlsx format is supported. This can also be only a path, in which case the model is exported to a set of tab-delimited text files via exportToTabDelimited. A dialog window will open if fileName is empty.
`sortIds`	`logical`	whether metabolites, reactions and genes should be sorted alphabetically by their identifiers (default false).

Examples:

exportToExcelFormat(model, fileName, sortIds);

exportToTabDelimited¶

Export a model to tab-delimited text files.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`path`	`char`	the path to export to. The resulting text files will be saved under the names excelRxns.txt, excelMets.txt, excelGenes.txt, excelModel.txt, and excelComps.txt (default './').
`sortIds`	`logical`	whether metabolites, reactions and genes should be sorted alphabetically by their identifiers (default false).

Examples:

exportToTabDelimited(model, path, sortIds);

Notes

No checks are made regarding the correctness of the model. Use checkModelStruct to identify problems in the model structure.

importModel¶

Import a constraint-based model from an SBML file.

Name-value arguments:

Name	Type	Description
`fileName`	`char`	a SBML file to import. A dialog window will open if no file name is specified.
`removeExcMets`	`logical`	if true, exchange metabolites are removed from the imported model (default true).
`removePrefix`	`logical`	true if identifier prefixes should be removed when loading the model: G_ for genes, R_ for reactions, M_ for metabolites, and C_ for compartments. These are only removed if all identifiers of a certain type contain the prefix (default true).
`supressWarnings`	`logical`	true if warnings regarding the model structure should be supressed (default false).

Output arguments:

Name	Type	Description
`model`	`struct`	imported model structure with fields: id : model ID name : name of model contents annotation : additional information about model rxns : reaction ids mets : metabolite ids S : stoichiometric matrix lb : lower bounds ub : upper bounds rev : reversibility vector c : objective coefficients b : equality constraints for the metabolite equations comps : compartment ids compNames : compartment names compOutside : the id (as in comps) for the compartment surrounding each of the compartments compMiriams : structure with MIRIAM information about the compartments rxnNames : reaction description rxnComps : compartments for reactions grRules : reaction to gene rules in text form rxnGeneMat : reaction-to-gene mapping in sparse matrix form subSystems : subsystem name for each reaction eccodes : EC-codes for the reactions rxnMiriams : structure with MIRIAM information about the reactions rxnNotes : reaction notes rxnReferences : reaction references rxnConfidenceScores : reaction confidence scores genes : list of all genes geneComps : compartments for genes geneMiriams : structure with MIRIAM information about the genes geneShortNames : gene alternative names (e.g. ERG10) proteins : protein associated to each gene metNames : metabolite description metComps : compartments for metabolites inchis : InChI-codes for metabolites metFormulas : metabolite chemical formula metMiriams : structure with MIRIAM information about the metabolites metCharges : metabolite charge unconstrained : true if the metabolite is an exchange metabolite

Examples:

model = importModel(fileName, removeExcMets, removePrefix, supressWarnings);

Notes

A number of consistency checks are performed in order to ensure that the model is valid. Take these warnings seriously and modify the model structure to solve them.

parseYAML¶

Read an arbitrary YAML file into a MATLAB struct/cell tree.

Use this for parsing arbitrary YAML configuration / data files (e.g. yeast-GEM's data/conditions/*.yml). For loading a cobra-format model YAML, use readYAMLmodel instead — that function knows the model schema and returns a populated RAVEN model struct.

Implementation: delegates to Python's yaml.safe_load, then recursively converts the py.dict / py.list tree to native MATLAB struct / cell. Requires a working MATLAB-Python bridge and the pyyaml package in the linked Python environment:

pip install pyyaml         % from the MATLAB-linked Python env

Input arguments:

Name	Type	Description	Default
`filename`	`char`	Path to the YAML file.	required

Output arguments:

Name	Type	Description
`out`	`struct or cell or char or double or logical`	MATLAB representation of the document: py.dict -> struct py.list -> cell column vector py.str -> char py.int -> double py.float -> double py.bool -> logical py.None -> []

Examples:

cfg = parseYAML('data/conditions/anaerobic.yml');

See also

readYAMLmodel

readFasta¶

Read sequences from a FASTA file.

Reads a FASTA file into a structure array, providing the same Header and Sequence fields as the Bioinformatics Toolbox fastaread, but using only base MATLAB so that no toolbox is required.

Input arguments:

Name	Type	Description	Default
`fileName`	`char`	path to the FASTA file to read.	required

Output arguments:

Name	Type	Description
`fastaStruct`	`struct`	structure array with one element per sequence, with the fields: Header : the header line, without the leading ">" Sequence : the sequence with all line breaks removed

Examples:

fastaStruct = readFasta('proteins.fa');

See also

writeFasta

readYAMLmodel¶

Read a model structure from a YAML file.

Reads a yaml file matching (roughly) the cobrapy yaml structure.

Name-value arguments:

Name	Type	Description	Default
`fileName`	`char`	a model file in yaml file format. A dialog window will open if no file name is specified.
`verbose`	`logical`	set as true to monitor progress (default false).

Output arguments:

Name	Type	Description
`model`	`struct`	a model structure.

Examples:

model = readYAMLmodel(fileName, verbose);

writeExcel¶

Write one or more sheets to an .xlsx (Office Open XML) file.

Writes data to one or more worksheets of an .xlsx file. Each sheet can have a bold header row (frozen at the top), column widths and per-column number formats. Numeric, text and logical cell values are supported; empty values are written as blank cells.

Input arguments:

Name	Type	Description	Default
`fileName`	`char`	path of the .xlsx file to write. An existing file is overwritten.	required
`sheets`	`struct`	struct array, one element per worksheet, with fields: name : char the worksheet name (truncated to 31 characters; the characters []*?/: are removed). data : cell cell matrix with the cell values. Supported value types are char (text), numeric scalar, logical, and empty (written as a blank cell). header : cell, optional column captions written as a bold, frozen first row above the data (default none). widths : double, optional vector of column widths in character units (default: column widths are left to the spreadsheet application). isIntegers : logical, optional if true numeric cells use the '0' number format, otherwise '##0.00' (default true). colFormats : cell, optional per-column number-format codes that override the sheet default for individual columns (default none).	required

Examples:

s.name='SHEET1'; s.header={'ID','VALUE'}; s.data={'a',1;'b',2};
writeExcel('out.xlsx',s);

See also

exportToExcelFormat

writeFasta¶

Write sequences to a FASTA file.

Writes a structure array of sequences to a FASTA file, replacing the Bioinformatics Toolbox fastawrite with base MATLAB so that no toolbox is required. An existing file is overwritten.

Input arguments:

Name	Type	Description	Default
`fileName`	`char`	path to the FASTA file to write.	required
`fastaStruct`	`struct`	structure array with one element per sequence, with the fields: Header : the header line (written after a leading ">") Sequence : the sequence	required
`lineWidth`	`double`	number of residues per sequence line (default 80).	required

Examples:

writeFasta('proteins.fa', fastaStruct);

See also

readFasta

writeYAMLmodel¶

Write a model to a yaml file matching cobrapy's structure.

The format is cobrapy's native !!omap layout, extended with RAVEN-only top-level per-entry keys (inchis, deltaG, metFrom, rxnFrom, references, confidence_score, protein) and the GECKO ec-rxns / ec-enzymes sections. Reaction EC numbers are written inside the annotation block as ec-code (the cobrapy/geckopy convention), not as a top-level reaction key. Output is byte-stable with raven_python's io.yaml.write_yaml_model when called with the same model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`fileName`	`char`	name that the file will have. A dialog window will open if no file name is specified.
`preserveQuotes`	`logical`	if all string values should be wrapped in double quotes. cobrapy emits quotes only where YAML requires them, so the default is false (matches cobrapy / raven-python) (default false).
`sortIds`	`logical`	if metabolites, reactions, genes and compartments should be sorted alphabetically by their identifier, otherwise they are kept in their original order (default false).

Examples:

writeYAMLmodel(model,fileName,preserveQuotes,sortIds);