Utilities

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

Functions

Function	Summary
convertCharArray	Ensure input is a cell array of character vectors.
emptyOrLogicalScalar	Validate that a value is empty or a logical scalar.
emptyOrTextOrCellOfText	mustBeEmptyOrTextOrCellOfText Validate empty, text scalar or cell of text.
emptyOrTextScalar	Validate that a value is empty or a string/char scalar.
parallelWorkersRAVEN	Return the parfor worker count for a given setting.
parseRAVENargs	Resolve optional arguments passed positionally or by name.
printOrange	Print an orange-coloured string to the MATLAB Command Window.
ravenList	Format a header and item list for warning() or error().
ravenModelFields	Declarative registry of all RAVEN model struct fields.
runRAVENtests	Run all RAVEN function tests.
setRavenProgress	Set the RAVEN progress-reporting backend.

Reference

convertCharArray

Ensure input is a cell array of character vectors.

Converts input to make sure it is a cell array of character vectors. String arrays are transformed into character vectors. Output is always a cell array, also if only one character vector is given as input.

Input arguments:

Name	Type	Description	Default
funcInput	char or cell or string	function input that should be checked.	required

Output arguments:

Name	Type	Description
inputConverted	cell	cell array of character vectors.

Examples:

inputConverted = convertCharArray(funcInput);

emptyOrLogicalScalar

Validate that a value is empty or a logical scalar.

Argument-validation helper used in arguments blocks. Passes silently if x is empty or a logical scalar, and otherwise raises a validation error.

Input arguments:

Name	Type	Description	Default
x	logical	the value to validate; may be empty.	required

emptyOrTextOrCellOfText

Validate empty, text scalar or cell of text.

Validate [] OR a text scalar (char row or string scalar) OR a cell array of such text. Throws an error if the input is none of these.

Input arguments:

Name	Type	Description	Default
x	double or char or string or cell	value to validate; allowed forms are empty ([]), a character row vector, a string scalar, or a cell array whose elements are each a character row vector or string scalar.	required

emptyOrTextScalar

Validate that a value is empty or a string/char scalar.

Argument-validation helper used in arguments blocks. Passes silently if x is empty, a string scalar, or a char row vector, and otherwise raises a validation error.

Input arguments:

Name	Type	Description	Default
x	char or string	the value to validate; may be empty.	required

parallelWorkersRAVEN

Return the parfor worker count for a given setting.

Returns a value for use with the parfor worker-count syntax:

nW = parallelWorkersRAVEN(runParallel);
parfor (i = 1:N, nW)
    ...
end

This avoids mutating global parallel-pool state: nW == 0 forces parfor to run as a plain for loop; nW == Inf lets the Parallel Computing Toolbox manage the pool size and auto-creation.

Input arguments:

Name	Type	Description	Default
runParallel	logical	whether the caller should use parallel workers.	required

Output arguments:

Name	Type	Description
nW	double	0 to force sequential execution (parfor behaves as a for loop, no pool required or created). Inf to use available pool workers (PCT manages pool size and auto-creation).

parseRAVENargs

Resolve optional arguments passed positionally or by name.

Helper that lets a RAVEN function accept its optional arguments either in the traditional positional order, as name-value pairs, or as a mix of leading positional values followed by name-value pairs. The required leading arguments stay explicit in the function signature; the optional tail is collected into varargin and passed here together with a specification of the optional parameters.

Input arguments:

Name	Type	Description	Default
rawArgs	cell	the varargin of the function, i.e. whatever was supplied after the required positional arguments.	required
spec	cell	an N-by-2 or N-by-3 cell array describing the optional parameters, one per row: column 1 : parameter name (char). column 2 : default value, used when the parameter is not supplied. column 3 : optional validator, a function handle that is called with the resolved value and should error on an invalid value (e.g. one of the utils/emptyOr* helpers). Use [] for no validation.	required

Output arguments:

Name	Type	Description
args	struct	a struct with one field per parameter name, holding the resolved value.

Notes

Calling convention is resolved as follows:

1. If rawArgs is empty, all parameters take their defaults.
2. The first element in rawArgs that is a string matching a known parameter name marks position k. Everything before k is treated as positional (assigned left-to-right by the order in spec). Everything from k onward must form valid name-value pairs: an even count where every name-position element is a known parameter name.
3. If no such position exists (no element is a matching string), or the trailing section from k does not form valid name-value pairs, the entire rawArgs is treated as positional.

This means three styles are accepted interchangeably:

f(model, v1, v2)                   % purely positional
f(model, "p1", v1, "p2", v2)       % purely named
f(model, v1, "p2", v2, "p3", v3)   % hybrid: v1 positional, rest named

When a positional value could itself be a string that equals a parameter name, use the explicit name-value form for that argument to avoid ambiguity.

Examples:

% inside exportToExcelFormat(model, varargin):
p = parseRAVENargs(varargin, { ...
    "fileName", []; ...
    "sortIds",  false});
fileName = p.fileName;
sortIds  = p.sortIds;

% the caller may use any of these:
exportToExcelFormat(model, "model.xlsx", true)              % positional
exportToExcelFormat(model, "sortIds", true)                 % named
exportToExcelFormat(model, "model.xlsx", "sortIds", true)   % hybrid

printOrange

Print an orange-coloured string to the MATLAB Command Window.

Prints stringToPrint in orange colour to the MATLAB Command Window. Only works if MATLAB is open with a GUI; it does not work with command-line MATLAB.

Input arguments:

Name	Type	Description	Default
stringToPrint	char	string that should be printed in orange colour.	required

Output arguments:

Name	Type	Description
orangeString	char	the input string wrapped with the formatting codes for orange colour.

Examples:

printOrange(stringToPrint);

ravenList

Format a header and item list for warning() or error().

Input arguments:

Name	Type	Description	Default
header	char	message header string.	required
items	cell	cell array of items to list below the header.	required
trim	logical	cap the list at 10 items (default true).	required

Output arguments:

Name	Type	Description
msg	char	header + newline + tab-indented items, ready to pass to warning() or error() as the format string.

Examples:

warning("RAVEN:warning", "%s", ravenList("Missing metabolites:", badMets));
error("RAVEN:badInput", "%s", ravenList("Invalid reactions:", badRxns, false));

ravenModelFields

Declarative registry of all RAVEN model struct fields.

Returns a struct array. Each element describes one field: .name - field name (char) .type - entity type: 'rxn', 'met', 'gene', or 'comp' (char) .default - default value when padding new entries

Only 1-D (vector-per-entity) fields are listed here. Fields that require custom 2-D indexing or value-remapping are excluded and must be handled explicitly by callers:

S - sparse (mets x rxns); use S(:,perm) for rxns, S(perm,:) for mets rxnGeneMat - sparse (rxns x genes); use rxnGeneMat(perm,:) or rxnGeneMat(:,perm) b - double (mets x N), may be 2-D; use b(perm,:) metComps, rxnComps, geneComps - when permuting comps, their VALUES must be remapped (not the arrays themselves permuted)

runRAVENtests

Run all RAVEN function tests.

Runs all unit tests found at RAVEN/test/function_tests, and prints output in the command window.

Output arguments:

Name	Type	Description
testResults	matlab.unittest.TestResult	array of test results returned by runtests.

Examples:

testResults = runRAVENtests;

setRavenProgress

Set the RAVEN progress-reporting backend.

Sets the preference that progressReport uses to decide how progress is shown. The setting is persistent across MATLAB sessions.

Input arguments:

Name	Type	Description	Default
mode	char	one of: 'auto' : choose automatically (default). GUI on an interactive desktop, an animated bar in an interactive terminal, plain log lines on a headless / -batch server, and no output during unit tests. 'gui' : always use a MATLAB waitbar. 'cli' : always use the animated command-line bar. 'log' : always print plain milestone lines (safe in redirected logs and on headless servers). 'none' / 'off' : never show progress.	required

Examples:

setRavenProgress('log');   % e.g. on a compute cluster
setRavenProgress('off');   % silence all progress reporting
setRavenProgress('auto');  % restore the default behaviour

See also

progressReport