Input / output (Python)#

raven-toolbox objects in raven_toolbox.io.

Functions#

Function	Summary
`ec_data_from_yaml_sections`	Build an `EcData` from the ec-* top-level YAML sections.
`ec_data_to_yaml_sections`	Serialise an `EcData` to a dict suitable for YAML emission.
`EcData`	Typed enzyme-constrained ecModel substructure attached as `model.ec`.
`export_for_git`	Write `model` into a Standard-GEM repository layout.
`export_to_excel`	Write `model` to a RAVEN-format `.xlsx` file.
`get_model_metadata`	All metadata of the model as a plain dict (a copy).
`model_from_yaml_data`	Build a `cobra.Model` from an already-parsed RAVEN/cobrapy YAML dict.
`read_matlab_model`	Read a model structure from a MATLAB `.mat` file.
`read_yaml_model`	Read a RAVEN/cobrapy YAML model into a `cobra.Model`.
`set_model_metadata`	Set the version, date and descriptive fields that the YAML export writes, in place.
`write_matlab_model`	Write `model` as a RAVEN model structure in a MATLAB `.mat` file.
`write_yaml_model`	Write a `cobra.Model` to RAVEN/cobrapy (`!!omap`) YAML.

Reference#

ec_data_from_yaml_sections#

ec_data_from_yaml_sections(sections: dict)

Build an EcData from the ec-* top-level YAML sections.

Returns None when ec-rxns and ec-enzymes are both absent; the caller then leaves model.ec = None. Raises ValueError when exactly one of the two is present.

sections is the dict of foreign top-level keys captured by the YAML loader. gecko_light defaults to False when the key is absent.

ec_data_to_yaml_sections#

ec_data_to_yaml_sections(ec: EcData)

Serialise an EcData to a dict suitable for YAML emission.

Returns a fresh dict with three keys: gecko_light (bool), ec-rxns (list of mappings), ec-enzymes (list of mappings). Values are native Python primitives (no numpy or ruamel scalars), so the YAML writer can dump them directly.

Empty optional fields are omitted; the loader restores them.

EcData#

Typed enzyme-constrained ecModel substructure attached as model.ec.

Field semantics match MATLAB GECKO's model.ec struct one-to-one. The fields form two parallel index spaces:

per-reaction arrays (rxns, kcat, source, notes, eccodes) of length n_rxns;
per-enzyme arrays (genes, enzymes, mw, sequence, concs) of length n_enzymes.

The sparse rxn_enz_mat of shape (n_rxns, n_enzymes) connects the two spaces. Its [i, j] entry is the subunit count of enzyme j in reaction i (0 or 1 for single enzymes, above 1 for heteromeric complexes).

Sentinels (as in MATLAB GECKO):

kcat == 0 means "no kcat assigned" (real turnover numbers are positive).
mw == nan means "MW unknown" (the writer omits NaN mw entries).
concs == nan means "not measured" (the writer omits NaN concs).
empty strings in source / notes / eccodes / sequence are omitted on write and restored as "" on load.

gecko_light marks the gecko-light layout: cobra reactions stay singular, ec.rxns carries one entry per isozyme distinguished by a ###_ counter prefix, and the per-enzyme prot_<id> and usage reactions are omitted in favour of the shared protein pool. False (default) is the full layout, where ec.rxns matches cobra reactions one-to-one after isozyme expansion.

export_for_git#

export_for_git(model: cobra.Model, path: str | Path='.', *, prefix: str='model', formats: Iterable[str]=_ALL_FORMATS, main_branch_flag: bool=False, sub_dirs: bool=True, varname: str | None=None, version: str | None=None, date: str | datetime.date | None=None)

Write model into a Standard-GEM repository layout.

Parameters

model : cobra.Model: Model to export. A sorted copy is written; the model passed in is not changed.
path : str or Path: Directory to populate.
prefix : str: Base filename for every format (default "model").
formats : Iterable of str: Which formats to write; any of "yml", "xml", "mat", "xlsx", "txt" (default: all five, as RAVEN's exportForGit).
main_branch_flag : bool: A bool. If True, raise RuntimeError when raven_toolbox runs from a git checkout that is not on main or master (default False), as RAVEN's mainBranchFlag. The check passes when the package is not in a raven_toolbox checkout (for example a pip installation) and when git is missing or refuses the checkout (OSError or a failing git call such as safe.directory). GECKO is not checked.
sub_dirs : bool: A bool. If True (default), write model/<fmt>/<prefix>.<fmt> (standard-GEM layout); otherwise all files go directly in path.
varname : str or None: Variable name for the MATLAB (.mat) struct. None (default) lets cobra use its own default (the model id); set it when a repository pins a specific name (for example Human-GEM's humanGEM).
version : str or None: Version stamped into the exported copy's metadata (see raven_toolbox.io.set_model_metadata); the model passed in is not changed. When not given, the model's own version is written.
date : str or datetime.date or None: Date stamped into the exported copy's metadata in the same way. When not given, the model's own date is written.

Returns

pathlib.Path: The root directory written to.

Raises

TypeError: If main_branch_flag or sub_dirs is not a bool or numpy.bool_.

export_to_excel#

export_to_excel(model: cobra.Model, path: str | Path, *, sort_ids: bool=False)

Write model to a RAVEN-format .xlsx file.

For enzyme-constrained models (a populated raven_toolbox.io.EcData on model.ec), two further export-only sheets are written: ENZYMES (one row per enzyme) and ENZRXNS (one row per ec-reaction).

Parameters

model : cobra.Model: Model to export.
path : str or Path: Output file path; the workbook is saved to it (str or pathlib.Path).
sort_ids : bool: If True, write reactions, metabolites and genes sorted alphabetically by ID (the model itself is not modified); compartments are sorted by abbreviation. The ec sheets keep the order of the ec data.

get_model_metadata#

get_model_metadata(model: cobra.Model)

All metadata of the model as a plain dict (a copy).

The dict holds version, date and the descriptive fields, and any other entry that read_yaml_model put in metaData (for example id, name and the default bounds). version is taken from notes["version"], falling back to notes["metaData"], the same order write_yaml_model uses. Fields the model does not carry are absent.

Parameters

model : cobra.Model: Model whose notes are read. The model is not changed.

model_from_yaml_data#

model_from_yaml_data(raw: dict)

Build a cobra.Model from an already-parsed RAVEN/cobrapy YAML dict.

Performs three jobs in order:

cobra-shaped portion: strips and restores RAVEN-only per-entry side-fields onto each entry's .notes; lifts id / name out of legacy metaData; preserves version and metaData on model.notes for round-trip.
legacy quirks: lifts per-metabolite top-level smiles into annotation['smiles'] and per-reaction top-level eccodes into annotation['ec-code'] (older RAVEN/MATLAB GECKO files emitted these at the top level); flips the older reverse-direction usage_prot_* / prot_pool_exchange convention to the forward convention.
GECKO ec sections: when ec-rxns / ec-enzymes are present, parses them into a typed EcData and attaches it as model.ec. Other unknown top-level keys land opaquely on model.notes['_yaml_sections'] for round-trip.

raw is mutated in place — copy it first if the caller needs the original.

read_matlab_model#

read_matlab_model(path: str | Path, *, varname: str | None=None)

Read a model structure from a MATLAB .mat file.

Reads a RAVEN structure natively. A COBRA Toolbox structure is recognised and handed to cobra's own reader instead, so a file written by save_matlab_model — Human-GEM 2.0.1 and 2.1.0 shipped one — is read rather than silently coming back without its identifier, EC codes, gene names and cross-references. A struct that is neither raises.

The inverse of write_matlab_model: RAVEN-only fields land where read_yaml_model puts the same data, so a model read from either format looks the same to the rest of raven-toolbox — cross-references in annotation, metFrom/rxnFrom/notes/references/deltaG and inchis in notes, and the model's own metadata in notes["metaData"] and notes["version"].

Parameters

path: File to read.
varname: Name of the struct to read. Defaults to the file's only struct variable; required when the file holds more than one.

Returns

cobra.Model :

read_yaml_model#

read_yaml_model(path: str | Path)

Read a RAVEN/cobrapy YAML model into a cobra.Model.

Convenience wrapper around model_from_yaml_data that opens the file (transparently un-gzipping .gz) and parses the YAML. Callers that need to pre-process the document (e.g. lift further non-standard fields that cobra doesn't recognise) can read+normalise themselves and call model_from_yaml_data with the resulting dict.

Accepts both the cobra !!omap shape and a very old RAVEN shape where the document root is a bare - sequence of single-key mappings; the latter is merged into one mapping before parsing.

Parameters

path : str or pathlib.Path: Path of the YAML file. A path ending in .gz is read as gzip-compressed text.

set_model_metadata#

set_model_metadata(model: cobra.Model, *, version: str | None=None, date: str | datetime.date | None=None, **fields: str)

Set the version, date and descriptive fields that the YAML export writes, in place.

Parameters

model : cobra.Model: Model whose notes["version"] and notes["metaData"] are updated in place.
version : str or None: Model version, for example "1.2.0".
date : str or datetime.date or None: Model date, as YYYY-MM-DD or a datetime.date (a datetime is reduced to its date). Any other value raises ValueError. The YAML writer stamps today's date only when the model has none.
**fields : str: Descriptive metaData fields: givenName, familyName, authors, email, organization, taxonomy, note and sourceUrl.

Arguments left out are not touched. :

write_matlab_model#

write_matlab_model(model: cobra.Model, path: str | Path, *, varname: str | None=None)

Write model as a RAVEN model structure in a MATLAB .mat file.

Parameters

model: The model to write.
path: Destination file.
varname: Name of the struct inside the file. Defaults to the model's id; set it when a repository pins a specific name (Human-GEM's humanGEM).

Returns

pathlib.Path: The file written.

write_yaml_model#

write_yaml_model(model: cobra.Model, path: str | Path, *, sort_ids: bool=False)

Write a cobra.Model to RAVEN/cobrapy (!!omap) YAML.

When model.ec is a populated EcData, the gecko_light flag and the ec-rxns / ec-enzymes top-level sections are emitted from it (numpy/ruamel scalars are coerced to plain Python primitives en route, so the dumper never sees them).

With sort_ids=True metabolites/reactions/genes/compartments are written in alphabetical order (diff-friendly), without modifying model.

Parameters

model : cobra.Model: Model to write.
path : str or pathlib.Path: Output file path. A path ending in .gz is written as gzip-compressed text.
sort_ids : bool: Whether to write entries in alphabetical order of their ids. The default is False.