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`	Everything the model stores as metadata, 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 treats that as "this YAML is not an ec-model" and leaves model.ec = None. If exactly one of the two is present, the YAML is malformed: raise ValueError.

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/ruamel scalars — so the YAML writer can dump them directly without further coercion.

Empty optional fields are omitted to keep the file compact; the loader fills them back in.

EcData#

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

Field semantics match MATLAB GECKO's model.ec struct one-to-one. 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.

Connected by the sparse rxn_enz_mat of shape (n_rxns, n_enzymes) whose [i, j] entry is the subunit count of enzyme j in reaction i (typically 0 or 1; >1 for heteromeric complexes).

Sentinels (mirror MATLAB GECKO):

kcat == 0 means "no kcat assigned" (zero is the unset state; real turnover numbers are always 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 per-enzyme prot_<id> / usage reactions are skipped in favour of the shared protein pool. False is the default (full layout, where ec.rxns matches cobra reactions one-to-one after isozyme expansion).

export_for_git#

Write model into a Standard-GEM repository layout.

Parameters

path: Directory to populate.
prefix: Base filename for every format (default "model").
formats: Which formats to write; any of "yml", "xml", "mat", "xlsx", "txt" (default yml/xml/mat/xlsx).
sub_dirs: If True (default), write model/<fmt>/<prefix>.<fmt> (standard-GEM layout); otherwise all files go directly in path.
varname: 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 (e.g. Human-GEM's humanGEM).
version, date: Stamped into the exported copy's metadata (see raven_toolbox.io.set_model_metadata); the model passed in is not changed. Left out, the model's own version and date are written.

Returns

pathlib.Path: The root directory written to.

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

sort_ids: If True, write reactions/metabolites/genes sorted alphabetically by ID (the model itself is not modified). The ec sheets are not reordered.

get_model_metadata#

get_model_metadata(model: cobra.Model)

Everything the model stores as metadata, as a plain dict (a copy).

That is version, date and the descriptive fields, plus whatever else a file read with 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.

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.

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

version: Model version, e.g. "1.2.0".
date: Model date, as YYYY-MM-DD or a datetime.date (a datetime is reduced to its date). Anything else raises. The YAML writer stamps today's date only when the model has none, so pass one when the date should change.
**fields: 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.