diff --git a/CHANGELOG.md b/CHANGELOG.md index 56ea62c..36d7225 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ * `zero_unmeasured_isozymes` lowers the usage upper bound of the unmeasured isozymes of a reaction that has a measured isozyme, to 0 or to a detection limit (`method="detection_limit"`), as GECKO's `zeroUnmeasuredIsozymes`; it lowers the bounds in place and returns a DataFrame, and a lower bound above the new upper bound is lowered with it. * `level_complex_concs` and `level_complex_abundances` keep a subunit with a concentration of 0 at 0 instead of filling it with the level of its complex. * `flexibilize_enz_concs` warns about enzymes with a concentration of 0, which it cannot raise, and does not report them as flexibilized; with `per_complex=True` the count of a complex is recorded on its first subunit with a concentration above 0. +* `format_kcat_source` and `parse_kcat_source` write and read the provenance strings of `model.ec.source`, `[ ()][ | tuned=[+...] (prior=)]`, and `KcatSource` holds the parts of one. `format_kcat_source(origin, detail=None, tuned=(), prior=None)` replaces `format_kcat_source(source, wildcard_level, origin)` and writes the same string for the same non-empty source, wildcard level and origin; an empty source with a detail is written as `unknown`. GECKO's `formatKcatSource` and `parseKcatSource` do the same. +* `sensitivity_tuning` and `cmaes_kcat_tuning` keep the origin and detail of the source of a kcat they change and add the method (`sensitivity`, `cmaes`) to its tuning status, with the kcat before the first tuning as `prior`. `sensitivity_tuning` no longer writes `sensitivityTuning` to `ec.source` or the kcat before tuning to `ec.notes`. `tune_prior_penalty_weight` restores `ec.source` with `ec.kcat`. +* `set_kcat_for_reactions` writes the source `manual`, which was `setKcatForReactions`, and drops any tuning status. +* `assign_standard_kcat`, `remove_standard_kcat`, `review_assignment`, `convert_custom_kcats` and the evotune trust tiers read the origin of `ec.source`, so a source with a detail or a tuning status is recognised. A standard kcat with a tuning status was changed on purpose and `remove_standard_kcat` keeps it. ## 4.0.0b2 — 2026-11-02 diff --git a/src/geckopy/__init__.py b/src/geckopy/__init__.py index 14ccf82..7c47589 100644 --- a/src/geckopy/__init__.py +++ b/src/geckopy/__init__.py @@ -81,12 +81,14 @@ # Gather-kcats from geckopy.gather_kcats import ( EcStats, + KcatSource, apply_kcat_list, assign_kcats, assign_standard_kcat, collect_kcats, ec_stats_from_brenda, fetch_open_kinetics_predictor, + format_kcat_source, fuzzy_kcat_matching, get_standard_kcat, # deprecated; alias of assign_standard_kcat kcats_from_brenda, @@ -97,6 +99,7 @@ load_kcat_source, merge_dlkcat_and_fuzzy_kcats, # deprecated; alias of merge_kcats merge_kcats, + parse_kcat_source, read_dlkcat_output, read_kcat_source, remove_standard_kcat, @@ -218,12 +221,14 @@ "set_kcat_for_reactions", "set_prot_pool_size", # Gather-kcats + "KcatSource", "apply_kcat_list", "assign_kcats", "assign_standard_kcat", "collect_kcats", "ec_stats_from_brenda", "fetch_open_kinetics_predictor", + "format_kcat_source", "fuzzy_kcat_matching", "kcats_from_brenda", "kcats_from_dlkcat", @@ -233,6 +238,7 @@ "load_kcat_source", "merge_dlkcat_and_fuzzy_kcats", # deprecated; alias of merge_kcats "merge_kcats", + "parse_kcat_source", "read_dlkcat_output", "read_kcat_source", "remove_standard_kcat", diff --git a/src/geckopy/ec_model/pipeline/apply_custom_kcats.py b/src/geckopy/ec_model/pipeline/apply_custom_kcats.py index 736472a..d048643 100644 --- a/src/geckopy/ec_model/pipeline/apply_custom_kcats.py +++ b/src/geckopy/ec_model/pipeline/apply_custom_kcats.py @@ -19,7 +19,6 @@ logger = logging.getLogger(__name__) _EXP_SUFFIX_REGEX = re.compile(r"_EXP_\d+$") -_SOURCE_TAG = "custom" _NOTES_SEPARATOR = ", " @@ -309,9 +308,12 @@ def _apply_to_indices( updated_indices: set[int], ) -> None: """Write kcat, source, and notes to ec.* for the given indices.""" + # Imported here because gather_kcats imports this module. + from ...gather_kcats.kcat_source_format import format_kcat_source + source = format_kcat_source("custom") for idx in indices: model.ec.kcat[idx] = kcat - model.ec.source[idx] = _SOURCE_TAG + model.ec.source[idx] = source if notes: existing = model.ec.notes[idx] if existing: diff --git a/src/geckopy/ec_model/pipeline/fill_kcats.py b/src/geckopy/ec_model/pipeline/fill_kcats.py index 8af9f1a..24b2ee8 100644 --- a/src/geckopy/ec_model/pipeline/fill_kcats.py +++ b/src/geckopy/ec_model/pipeline/fill_kcats.py @@ -20,7 +20,6 @@ logger = logging.getLogger(__name__) _EXP_SUFFIX_REGEX = re.compile(r"_EXP_\d+$") -_SOURCE_TAG = "isozymes" _AGGREGATORS = { "mean": np.mean, @@ -116,6 +115,9 @@ def fill_kcats_from_isozymes( if known: known_by_base.setdefault(bid, []).append(float(k)) + # Imported here because gather_kcats imports this module. + from ...gather_kcats.kcat_source_format import format_kcat_source + source = format_kcat_source("isozymes") # For each missing entry, look up its base group and average if available. filled_indices: list[int] = [] for i, (bid, missing) in enumerate(zip(base_ids, missing_mask)): @@ -125,7 +127,7 @@ def fill_kcats_from_isozymes( if not siblings: continue model.ec.kcat[i] = float(combine(siblings)) - model.ec.source[i] = _SOURCE_TAG + model.ec.source[i] = source filled_indices.append(i) if not filled_indices: diff --git a/src/geckopy/ec_model/pipeline/set_kcat.py b/src/geckopy/ec_model/pipeline/set_kcat.py index 7f3a4f5..63f2e75 100644 --- a/src/geckopy/ec_model/pipeline/set_kcat.py +++ b/src/geckopy/ec_model/pipeline/set_kcat.py @@ -15,7 +15,6 @@ _EXP_SUFFIX_PATTERN = re.compile(r"_EXP_\d+$") -_SOURCE_TAG = "setKcatForReactions" def set_kcat_for_reactions( @@ -57,10 +56,8 @@ def set_kcat_for_reactions( passing the suffixed reaction IDs explicitly when the mapping matters, so intent doesn't depend on ``ec.rxns``'s row order. - ``ec.source`` is set to ``"setKcatForReactions"`` for every - reaction changed by this call, matching MATLAB's ``ec.source`` - label (its own docstring says ``'from setKcatForReactions'``, but - the actual assignment writes the bare function name). + ``ec.source`` is set to ``"manual"`` for every reaction changed by + this call, which drops any tuning status the source had. Parameters ---------- @@ -142,9 +139,12 @@ def set_kcat_for_reactions( for indices in matches_per_input: flat_indices.extend(indices) + # Imported here because gather_kcats imports this module. + from ...gather_kcats.kcat_source_format import format_kcat_source + source = format_kcat_source("manual") for idx, value in zip(flat_indices, kcat_per_index): model.ec.kcat[idx] = value - model.ec.source[idx] = _SOURCE_TAG + model.ec.source[idx] = source updated_ids = [ec_rxns[i] for i in flat_indices] diff --git a/src/geckopy/gather_kcats/__init__.py b/src/geckopy/gather_kcats/__init__.py index f5688ab..921e48d 100644 --- a/src/geckopy/gather_kcats/__init__.py +++ b/src/geckopy/gather_kcats/__init__.py @@ -6,6 +6,7 @@ from .kcat_assignment import assign_kcats, collect_kcats, update_kcat_sources from .homologs import kcats_from_homologs from .kcat_sources import ec_rxn_keys, load_kcat_source, read_kcat_source, save_kcat_source +from .kcat_source_format import KcatSource, format_kcat_source, parse_kcat_source from .kcats_from import kcats_from_brenda, kcats_from_dlkcat, kcats_from_ec_tree, kcats_from_okp from .get_standard_kcat import assign_standard_kcat, get_standard_kcat from .merge_dlkcat_and_fuzzy_kcats import merge_dlkcat_and_fuzzy_kcats @@ -20,15 +21,12 @@ from .remove_standard_kcat import remove_standard_kcat from .review import EcStats, ec_stats_from_brenda, review_assignment from .run_dlkcat import run_dlkcat -from .select_kcat_value import ( - apply_kcat_list, - format_kcat_source, - select_kcat_value, -) +from .select_kcat_value import apply_kcat_list, select_kcat_value from .write_dlkcat_input import extract_enzyme_substrate_pairs, write_dlkcat_input __all__ = [ "EcStats", + "KcatSource", "OKPClient", "OKPError", "apply_kcat_list", @@ -51,6 +49,7 @@ "merge_dlkcat_and_fuzzy_kcats", # deprecated; use merge_kcats "merge_kcats", "normalize_source", + "parse_kcat_source", "read_kcat_source", "read_dlkcat_output", "remove_standard_kcat", diff --git a/src/geckopy/gather_kcats/get_standard_kcat.py b/src/geckopy/gather_kcats/get_standard_kcat.py index c9f9ddf..05ae0bb 100644 --- a/src/geckopy/gather_kcats/get_standard_kcat.py +++ b/src/geckopy/gather_kcats/get_standard_kcat.py @@ -17,6 +17,7 @@ from ..ec_model.constants import POOL_ID from ..ec_model.pipeline.protein_pool import _resolve_enzyme_compartment_id +from .kcat_source_format import format_kcat_source, is_standard_source if TYPE_CHECKING: from ..databases import UniprotDB @@ -54,7 +55,8 @@ def assign_standard_kcat( A reaction with an empty subsystem has none. The function is idempotent: previous "standard" entries - (identified by ``model.ec.source == "standard"``) are stripped + (rows whose ``model.ec.source`` has the origin ``standard`` and no + tuning status) are stripped before re-applying. Filtering: exchange (a reaction without a substrate or without a @@ -300,7 +302,7 @@ def _load_custom_pseudo_rxns(adapter) -> set[str]: def _remove_previous_standard(model: "EcModel") -> None: - """Strip out entries marked source='standard' from a prior run.""" + """Strip out the entries of a prior run whose source marks the standard kcat.""" n = model.ec.n_rxns if n == 0: return @@ -317,7 +319,7 @@ def _remove_previous_standard(model: "EcModel") -> None: rows_to_remove: list[int] = [] rows_to_reset: list[int] = [] for i in range(n): - if model.ec.source[i] != "standard": + if not is_standard_source(model.ec.source[i]): continue if std_col is not None and rxn_enz_dense[i, std_col] > 0: rows_to_remove.append(i) @@ -417,7 +419,7 @@ def _assign_standard_kcat_to_missing( model.ec.kcat = np.concatenate( [model.ec.kcat, np.array(kcats_to_add, dtype=float)] ) - model.ec.source = list(model.ec.source) + ["standard"] * n_new + model.ec.source = list(model.ec.source) + [format_kcat_source(_STANDARD_NAME)] * n_new model.ec.notes = list(model.ec.notes) + [""] * n_new model.ec.eccodes = list(model.ec.eccodes) + [""] * n_new @@ -444,7 +446,7 @@ def _fill_zero_kcats(model: "EcModel", standard_kcat: float) -> list[str]: model.ec.kcat[unset_mask] = standard_kcat indices = np.where(unset_mask)[0] for i in indices: - model.ec.source[int(i)] = "standard" + model.ec.source[int(i)] = format_kcat_source(_STANDARD_NAME) return [model.ec.rxns[int(i)] for i in indices] diff --git a/src/geckopy/gather_kcats/kcat_assignment.py b/src/geckopy/gather_kcats/kcat_assignment.py index 5d4189c..f041ac5 100644 --- a/src/geckopy/gather_kcats/kcat_assignment.py +++ b/src/geckopy/gather_kcats/kcat_assignment.py @@ -23,6 +23,7 @@ from ..ec_model.pipeline.apply_kcat import apply_kcat_constraints from ..ec_model.pipeline.fill_kcats import fill_kcats_from_isozymes from .get_standard_kcat import assign_standard_kcat +from .kcat_source_format import format_kcat_source, is_standard_source from .kcat_sources import load_kcat_source, read_kcat_source from .kcats_from import _brenda_release, _measurements, kcats_from_brenda, kcats_from_dlkcat, kcats_from_ec_tree, kcats_from_okp from .merge_kcats import _strip_okp_prefix, merge_kcats, normalize_source @@ -204,7 +205,7 @@ def load(name: str) -> Optional[pd.DataFrame]: combined["n"], combined["spread_log10"]): i = index[rxn] ec.kcat[i] = kcat - ec.source[i] = f"combined (sd={sdv:.2f}, n={nsrc})" + ec.source[i] = format_kcat_source("combined", {"sd": f"{sdv:.2f}", "n": int(nsrc)}) stage[i], candidates[i], spread[i], sd[i] = str(s), nsrc, spr, sdv continue lists: list[pd.DataFrame] = [] @@ -266,7 +267,7 @@ def load(name: str) -> Optional[pd.DataFrame]: spread = np.concatenate([spread, np.full(extra, np.nan)]) sd = np.concatenate([sd, np.full(extra, np.nan)]) for i, src in enumerate(ec.source): - if src == "standard" and ec.kcat[i] > 0: + if is_standard_source(src) and ec.kcat[i] > 0: stage[i] = "standard" decisions = pd.DataFrame({ diff --git a/src/geckopy/gather_kcats/kcat_source_format.py b/src/geckopy/gather_kcats/kcat_source_format.py new file mode 100644 index 0000000..5c7df1c --- /dev/null +++ b/src/geckopy/gather_kcats/kcat_source_format.py @@ -0,0 +1,206 @@ +"""Write and read the provenance strings of ``model.ec.source``. + +A string is ``[ ()][ | tuned=[+...] (prior=)]``, +for example ``"brenda (wc=0, origin=1)"`` or +``"okp_catapro (similarity=42) | tuned=sensitivity+cmaes (prior=5.48)"``. +The origin names where the kcat came from, the detail holds ``key=value`` +pairs of that origin, and the tuning status lists the tuning methods applied +to the kcat in order together with the kcat before the first of them. + +Mirrors GECKO MATLAB's ``formatKcatSource`` and ``parseKcatSource``. +""" +from __future__ import annotations + +import math +import re +from dataclasses import dataclass, field +from numbers import Real +from typing import Iterable, Mapping, Optional + +from .merge_kcats import normalize_source + +_TUNED_MARK = " | tuned=" +_NUMBER = re.compile(r"[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?") +_PARSE_KEY = re.compile(r"[A-Za-z][A-Za-z0-9_]*") +_FORMAT_KEY = re.compile(r"[a-z][a-z0-9_]*") + + +@dataclass(frozen=True) +class KcatSource: + """The parts of one ``ec.source`` string. + + Attributes + ---------- + origin + The origin as written (case is not changed); ``""`` for a missing + string. + detail + The ``key=value`` pairs of the detail: a float when the value + parses as a number, a str otherwise. + tuned + The tuning methods in order of application. + prior + The kcat before the first tuning, or None. + """ + + origin: str + detail: dict[str, float | str] = field(default_factory=dict) + tuned: tuple[str, ...] = () + prior: Optional[float] = None + + +def _is_missing(value: object) -> bool: + if value is None: + return True + return isinstance(value, Real) and math.isnan(float(value)) + + +def _number_text(value: float) -> str: + return f"{float(value):.6g}" + + +def _is_number(value: object) -> bool: + return isinstance(value, Real) and math.isfinite(float(value)) + + +def format_kcat_source( + origin: object, + detail: Optional[Mapping[str, object]] = None, + tuned: Iterable[str] = (), + prior: Optional[float] = None, +) -> str: + """Build the provenance string written to ``model.ec.source``. + + Mirrors GECKO MATLAB's ``formatKcatSource``. + + Parameters + ---------- + origin + Where the kcat came from (``"brenda"``, ``"custom"``, + ``"okp_catapro"``, ...). Lower-cased, with every run of characters + outside ``[0-9a-z]`` folded to one ``_`` (``"OKP-CataPro"`` gives + ``"okp_catapro"``). + detail + ``key=value`` pairs written in the order of the mapping, keys + normalised as the origin. A number is written with ``%.6g``, text + verbatim. A pair whose value is None, NaN or infinite is left out, + so is a pair whose key does not start with a letter after the + normalisation, and the brackets are left out when no pair is left. + tuned + Tuning methods applied to the kcat, in order of application. The + tuning status is written when this is not empty. + prior + The kcat before the first tuning, written as ``(prior=)`` + after the methods; None or NaN means none. + + Returns + ------- + str + The provenance string. An empty ``origin`` gives ``""`` when there + is no detail and no tuning status, and the origin ``unknown`` + otherwise. + + Examples + -------- + >>> format_kcat_source("brenda", {"wc": 0, "origin": 1}) + 'brenda (wc=0, origin=1)' + >>> format_kcat_source("OKP-CataPro", {"similarity": 42}, ["cmaes"], 5.48) + 'okp_catapro (similarity=42) | tuned=cmaes (prior=5.48)' + """ + token = normalize_source(origin) + pairs = [] + for key, value in (detail or {}).items(): + name = normalize_source(key) + if not _FORMAT_KEY.fullmatch(name) or _is_missing(value): + continue + if isinstance(value, Real): + if not math.isfinite(float(value)): + continue + text = _number_text(value) + else: + text = str(value) + pairs.append(f"{name}={text}") + if tuned is None: + tuned = () + methods = [str(m) for m in ([tuned] if isinstance(tuned, str) else tuned)] + if not token and not pairs and not methods: + return "" + text = token or "unknown" + if pairs: + text += f" ({', '.join(pairs)})" + if methods: + text += _TUNED_MARK + "+".join(methods) + if _is_number(prior): + text += f" (prior={_number_text(prior)})" + return text + + +def _parse_value(text: str) -> float | str: + return float(text) if _NUMBER.fullmatch(text) else text + + +def parse_kcat_source(text: object) -> KcatSource: + """Split a provenance string of ``model.ec.source`` into its parts. + + Mirrors GECKO MATLAB's ``parseKcatSource``. A string that does not + follow the format is read as an origin with no detail and no tuning + status, so a string written by an earlier version stays readable. + + Parameters + ---------- + text + One ``ec.source`` entry. None, NaN and anything that is not a str + give the origin ``""``. + + Returns + ------- + KcatSource + ``origin`` as written, ``detail`` (numbers as float), ``tuned`` + (methods in order) and ``prior`` (None when absent). + + Examples + -------- + >>> info = parse_kcat_source("brenda (wc=0, origin=2) | tuned=cmaes (prior=6.55)") + >>> info.origin, info.detail, info.tuned, info.prior + ('brenda', {'wc': 0.0, 'origin': 2.0}, ('cmaes',), 6.55) + """ + if not isinstance(text, str): + return KcatSource("") + head, mark, tail = text.strip().partition(_TUNED_MARK) + head = head.strip() + origin, bracket, rest = head.partition(" (") + detail: dict[str, float | str] = {} + if bracket and rest.endswith(")"): + for part in rest[:-1].split(","): + key, equals, value = part.partition("=") + if equals and _PARSE_KEY.fullmatch(key.strip()): + detail[key.strip()] = _parse_value(value.strip()) + elif bracket: + origin = head + methods: tuple[str, ...] = () + prior: Optional[float] = None + if mark: + tail = tail.strip() + names, bracket, rest = tail.partition(" (prior=") + if ( + bracket + and rest.endswith(")") + and ")" not in rest[:-1] + and not names[-1:].isspace() + ): + value = _parse_value(rest[:-1].strip()) + prior = value if isinstance(value, float) else None + else: + names = tail + methods = tuple(m.strip() for m in names.split("+") if m.strip()) + return KcatSource(origin.strip(), detail, methods, prior) + + +def is_standard_source(source: object) -> bool: + """Whether an ``ec.source`` entry marks the standard kcat. + + True when the origin is ``standard`` (compared exactly) and the string has + no tuning status, so a tuned standard kcat counts as set on purpose. + """ + info = parse_kcat_source(source) + return info.origin == "standard" and not info.tuned diff --git a/src/geckopy/gather_kcats/remove_standard_kcat.py b/src/geckopy/gather_kcats/remove_standard_kcat.py index ca6bfaa..e5854e6 100644 --- a/src/geckopy/gather_kcats/remove_standard_kcat.py +++ b/src/geckopy/gather_kcats/remove_standard_kcat.py @@ -11,6 +11,7 @@ import numpy as np from ..ec_model.pipeline.apply_kcat import apply_kcat_constraints +from .kcat_source_format import is_standard_source if TYPE_CHECKING: from ..ec_model.ec_model import EcModel @@ -35,7 +36,8 @@ def remove_standard_kcat(model: "EcModel") -> None: ec fields. 2. The "standard" entry is dropped from all per-enzyme ec fields, and its column is removed from ``rxn_enz_mat``. - 3. Remaining ec.rxns rows where ``source == "standard"`` (these + 3. Remaining ec.rxns rows whose ``source`` has the origin ``standard`` + and no tuning status (these are rxns whose existing kcat was filled by ``fill_zero_kcat=True``, but linked to a real enzyme) have their ``kcat`` reset to 0 and ``source`` cleared. @@ -109,14 +111,17 @@ def _remove_standard_pseudoenzyme(model: "EcModel") -> None: def _reset_standard_source_rxns(model: "EcModel") -> list[str]: - """Reset rows where source='standard' to kcat=0 and source=''. + """Reset the rows of the standard kcat to kcat=0 and source=''. + + A row counts when its source has the origin ``standard`` and no tuning + status. Returns the affected reaction IDs so the caller can re-apply kcat constraints to clean up the S matrix. """ affected: list[str] = [] for i, src in enumerate(model.ec.source): - if src == "standard": + if is_standard_source(src): model.ec.kcat[i] = 0.0 model.ec.source[i] = "" affected.append(model.ec.rxns[i]) diff --git a/src/geckopy/gather_kcats/review.py b/src/geckopy/gather_kcats/review.py index 1ebbf24..d6910aa 100644 --- a/src/geckopy/gather_kcats/review.py +++ b/src/geckopy/gather_kcats/review.py @@ -34,6 +34,7 @@ from ..kcat_tuning.evotune.tying import ( base_reaction, isozyme_tie_map, ) +from .kcat_source_format import parse_kcat_source #: Checks reported unless asked for explicitly. ``standard`` values are a #: deliberate fallback and ``tied`` groups are unresolvable by design, so @@ -179,7 +180,7 @@ def review_assignment( if kcats[i] < slow or kcats[i] > fast: checks.append("magnitude") detail.append(f"{kcats[i]:g} 1/s is outside {slow:g}-{fast:g}") - if (str(sources[i]).lower() == "custom" and st is not None + if (parse_kcat_source(str(sources[i])).origin.lower() == "custom" and st is not None and round(float(kcats[i]), 6) in st.values): checks.append("custom-duplicate") detail.append("custom value equals a database value for its own EC") @@ -187,7 +188,7 @@ def review_assignment( if "tied-isozymes" in include: checks.append("tied-isozymes") detail.append(f"{len(idx)} isozyme copies share this value") - if str(sources[i]).lower() == "standard": + if parse_kcat_source(str(sources[i])).origin.lower() == "standard": if "standard-fallback" not in include: continue checks.append("standard-fallback") diff --git a/src/geckopy/gather_kcats/select_kcat_value.py b/src/geckopy/gather_kcats/select_kcat_value.py index 1e54234..7d20286 100644 --- a/src/geckopy/gather_kcats/select_kcat_value.py +++ b/src/geckopy/gather_kcats/select_kcat_value.py @@ -10,7 +10,7 @@ import numpy as np import pandas as pd -from .merge_kcats import normalize_source +from .kcat_source_format import format_kcat_source if TYPE_CHECKING: from ..ec_model.ec_model import EcModel @@ -20,31 +20,18 @@ _OverwriteMode = Union[bool, Literal["if_higher"]] -def format_kcat_source( - source: object, - wildcard_level: object = None, - origin: object = None, -) -> str: - """Build the provenance string written to ``model.ec.source``. - - The result is lowercase ``snake_case``: the first token is the - source (``brenda``, ``sabio_rk``, ``catapro``, ``dlkcat``, ...), and - for a *fuzzy* BRENDA match the bracketed detail records how the - value was obtained -- its wildcard level and origin, e.g. - ``"brenda (wc=0, origin=1)"``. Rows without fuzzy metadata (an exact - OKP database hit or a prediction) render as the bare token, so the - bracket's presence and the wildcard/origin numbers give downstream - consumers (notably evotune kcat tuning) a quick read on how - uncertain the kcat is. +def _fuzzy_source(source: object, wildcard_level: object, origin: object) -> str: + """Provenance string of one kcat-list row. + + The string holds the source and, for a fuzzy BRENDA match, the wildcard + level and origin of the match as the detail pairs ``wc`` and ``origin``. """ - token = normalize_source(source) - wc_ok = wildcard_level is not None and pd.notna(wildcard_level) - origin_ok = origin is not None and pd.notna(origin) - if wc_ok and origin_ok: - return f"{token} (wc={int(wildcard_level)}, origin={int(origin)})" - if wc_ok: - return f"{token} (wc={int(wildcard_level)})" - return token + detail = {} + if wildcard_level is not None and pd.notna(wildcard_level): + detail["wc"] = int(wildcard_level) + if origin is not None and pd.notna(origin): + detail["origin"] = int(origin) + return format_kcat_source(source, detail) def apply_kcat_list( @@ -179,7 +166,7 @@ def apply_kcat_list( kcat_val, j = float(np.mean(kcats)), 0 if criteria in ("max", "min"): kcat_val = float(kcats[j]) - source_val = format_kcat_source(sources[j], wcs[j], origins[j]) + source_val = _fuzzy_source(sources[j], wcs[j], origins[j]) selected[str(rxn_id)] = (kcat_val, source_val) updated: list[str] = [] diff --git a/src/geckopy/kcat_tuning/evotune/priors.py b/src/geckopy/kcat_tuning/evotune/priors.py index 3d965b9..6ae356e 100644 --- a/src/geckopy/kcat_tuning/evotune/priors.py +++ b/src/geckopy/kcat_tuning/evotune/priors.py @@ -7,6 +7,7 @@ import numpy as np from ...adapter.params import EvotuneParams +from ...gather_kcats.kcat_source_format import parse_kcat_source #: Sentinel group name for an ``ec.source`` value matched by no #: ``source_groups`` entry -- MATLAB's ``noKcatSource``. @@ -22,13 +23,10 @@ def classify_kcat_source( """Map one ``ec.source`` string to a trust-tier group name. Matching is case-insensitive, mirroring MATLAB's - ``strcmpi(ecModel.ec.source, kcatSources{i})``, and ignores the - bracketed fuzzy-match detail geckopy appends to a database source. - ``ec.source`` reads ``"brenda (wc=0, origin=1)"`` where MATLAB's - reads ``"brenda"``, so matching the whole string would leave every - fuzzy-matched kcat unlabelled and silently on the default prior - width -- which is most of a model's kcats. A ``source_groups`` entry - listing the full string still matches it. + ``strcmpi(ecModel.ec.source, kcatSources{i})``. A ``source_groups`` entry + matches the origin of the source (``"brenda"`` for + ``"brenda (wc=0, origin=1) | tuned=cmaes (prior=2)"``, so the detail and + the tuning status are ignored) and also the whole source string. Parameters ---------- @@ -50,7 +48,7 @@ def classify_kcat_source( ``force_prior_thr_default``. """ source_lower = source.lower() - token = source_lower.split(" (")[0].strip() + token = parse_kcat_source(source).origin.lower() forms = {source_lower, token} for name, rule in params.source_groups.items(): if any(s.lower() in forms for s in rule.sources): diff --git a/src/geckopy/kcat_tuning/evotune/tuning.py b/src/geckopy/kcat_tuning/evotune/tuning.py index 978b3fc..1550559 100644 --- a/src/geckopy/kcat_tuning/evotune/tuning.py +++ b/src/geckopy/kcat_tuning/evotune/tuning.py @@ -69,6 +69,7 @@ from cobra.util import ProcessPool from ...ec_model.pipeline.apply_kcat import apply_kcat_constraints +from ...gather_kcats.kcat_source_format import format_kcat_source, parse_kcat_source from ..corrections import Correction, corrections as build_corrections from .data import EvotuneData, load_evotune_data from .distance import evotune_distance, compute_excarbon @@ -431,7 +432,9 @@ def cmaes_kcat_tuning( model EcModel with a populated ``ec.kcat``. Mutated in place: on return, tunable rows hold the best kcat vector CMA-ES found, - with kcat constraints already applied. + with kcat constraints already applied. The ``ec.source`` of + every row whose kcat changed gets the tuning method ``cmaes``, + with the kcat before the first tuning as ``prior``. tunable_mask, screen, target_impact_share Control which kcats are searched over, in order of precedence. Pass ``tunable_mask`` to fix the set yourself. Otherwise, a @@ -599,6 +602,14 @@ def _score_batch(kcat_matrix, pool): break model.ec.kcat[tunable_idx] = best_vec + for i, before, after in zip(tunable_idx, kcat0, best_vec): + if after != before: + previous = parse_kcat_source(model.ec.source[i]) + model.ec.source[i] = format_kcat_source( + previous.origin, previous.detail, + dict.fromkeys((*previous.tuned, "cmaes")), + previous.prior if previous.prior is not None else float(before), + ) if ec_rxn_ids_tunable: apply_kcat_constraints(model, update_rxns=ec_rxn_ids_tunable) @@ -703,9 +714,11 @@ def tune_prior_penalty_weight( model, screen, target_impact_share=target_impact_share) prior_kcat = model.ec.kcat.copy() + prior_source = list(model.ec.source) def _reset(): model.ec.kcat[:] = prior_kcat + model.ec.source[:] = prior_source apply_kcat_constraints(model, update_rxns=model.ec.rxns) try: diff --git a/src/geckopy/kcat_tuning/sensitivity_tuning.py b/src/geckopy/kcat_tuning/sensitivity_tuning.py index aba983e..4141a05 100644 --- a/src/geckopy/kcat_tuning/sensitivity_tuning.py +++ b/src/geckopy/kcat_tuning/sensitivity_tuning.py @@ -25,7 +25,6 @@ from __future__ import annotations import logging -import math from dataclasses import dataclass, field from typing import TYPE_CHECKING, Optional, Sequence @@ -39,6 +38,7 @@ ) from ..ec_model.pipeline.apply_kcat import apply_kcat_constraints from ..ec_model.pipeline.populate_ec import split_light_rxn_id +from ..gather_kcats.kcat_source_format import format_kcat_source, parse_kcat_source from .corrections import Correction, corrections as build_corrections if TYPE_CHECKING: @@ -48,27 +48,13 @@ logger = logging.getLogger(__name__) -_TUNING_SOURCE = "sensitivityTuning" +_TUNING_METHOD = "sensitivity" # Growth is considered stalled when an iteration improves it by no more # than this (absolute, 1/h). Using a tolerance instead of exact equality # avoids spinning on sub-numerical-noise increases. _GROWTH_STALL_TOL = 1e-9 -def _num2str(value: float) -> str: - """A scalar as MATLAB's ``num2str`` prints it: integers as such, other - values with ``max(floor(log10(abs(x))) + 5, 5)`` significant digits.""" - value = float(value) - if math.isnan(value): - return "NaN" - if math.isinf(value): - return "Inf" if value > 0 else "-Inf" - if value == int(value): - return str(int(value)) - digits = max(math.floor(math.log10(abs(value))) + 5, 5) - return f"{value:.{digits}g}" - - @dataclass class TunedKcatsResult: """Outcome of a sensitivity-tuning run. @@ -153,15 +139,16 @@ def sensitivity_tuning( 5. Finds the catalysed reaction consuming the most of that enzyme's pseudometabolite and multiplies that reaction's ``ec.kcat`` by ``fold_change``. A tuned kcat has no upper limit. - 6. Annotates ``ec.notes`` with the original kcat (printed as MATLAB's - ``num2str`` does) and source, unless the source is already - ``"sensitivityTuning"``. + 6. Extends the tuning status of ``ec.source`` with ``sensitivity`` + (the origin and detail are kept; the kcat before the first tuning + is recorded as ``prior`` unless the source already has one). 7. Re-applies kcat constraints for that single reaction. On a gecko-light model each iteration instead selects the reaction with the most flux through the protein pool, multiplies the kcat of all its isozyme rows by ``fold_change`` and re-applies the constraint of that - reaction; ``ec.notes`` and ``ec.source`` are left as they are. + reaction; the tuning status of ``ec.source`` is extended for each of those + rows as above. Ported from GECKO MATLAB: src/geckomat/kcat_sensitivity_analysis/sensitivityTuning.m. @@ -297,6 +284,7 @@ def sensitivity_tuning( break ec_rows = step for i in ec_rows: + _mark_tuned(model, i) model.ec.kcat[i] = float(model.ec.kcat[i]) * fold_change apply_kcat_constraints(model, update_rxns=[model.ec.rxns[ec_rows[0]]]) if ec_rows[0] not in tuned_ec_indices: @@ -366,20 +354,9 @@ def sensitivity_tuning( break ec_idx = model.ec.rxns.index(target_rxn.id) - # Record the pre-tune kcat/source the first time this reaction is - # tuned, and annotate notes (idempotently). - if model.ec.source[ec_idx] != _TUNING_SOURCE: - old_note = model.ec.notes[ec_idx] - new_note = ( - f"preTuneKcat={_num2str(model.ec.kcat[ec_idx])} | " - f"source:{model.ec.source[ec_idx]}" - ) - model.ec.notes[ec_idx] = ( - f"{old_note}; {new_note}" if old_note else new_note - ) - - model.ec.kcat[ec_idx] = float(model.ec.kcat[ec_idx]) * fold_change - model.ec.source[ec_idx] = _TUNING_SOURCE + kcat_before = float(model.ec.kcat[ec_idx]) + _mark_tuned(model, ec_idx) + model.ec.kcat[ec_idx] = kcat_before * fold_change apply_kcat_constraints(model, update_rxns=[target_rxn.id]) if ec_idx not in tuned_ec_indices: @@ -394,6 +371,20 @@ def sensitivity_tuning( return _build_result(model, tuned_ec_indices, input_kcat, input_source) +def _mark_tuned(model: "EcModel", ec_idx: int) -> None: + """Add the tuning method to the source of one ec row. + + The kcat before the first tuning is the prior. Called before the kcat + changes. + """ + previous = parse_kcat_source(model.ec.source[ec_idx]) + model.ec.source[ec_idx] = format_kcat_source( + previous.origin, previous.detail, + dict.fromkeys((*previous.tuned, _TUNING_METHOD)), + previous.prior if previous.prior is not None else float(model.ec.kcat[ec_idx]), + ) + + def _usage_ids_to_ignore( usage_rxn_ids: list[str], prot_to_ignore: list[str], ) -> set[str]: diff --git a/src/geckopy/upgrade.py b/src/geckopy/upgrade.py index 70cb12b..bf29d14 100644 --- a/src/geckopy/upgrade.py +++ b/src/geckopy/upgrade.py @@ -23,6 +23,7 @@ import pandas as pd from .ec_model.constants import POOL_EXCHANGE_ID, POOL_ID +from .gather_kcats.kcat_source_format import parse_kcat_source if TYPE_CHECKING: from .adapter import ModelAdapter @@ -99,7 +100,7 @@ def convert_custom_kcats( base, enzymes = ec_rxn_keys(applied) rows: dict[tuple[str, str], list[str]] = {} for i in range(n): - if applied.ec.source[i] != "custom": + if parse_kcat_source(applied.ec.source[i]).origin != "custom": continue note = re.sub(r"[\t\r\n]", " ", applied.ec.notes[i] or "") rows.setdefault((base[i], enzymes[i]), [base[i], enzymes[i], "", format_number(float(applied.ec.kcat[i])), diff --git a/tests/test_evotune.py b/tests/test_evotune.py index fc73710..0b0b845 100644 --- a/tests/test_evotune.py +++ b/tests/test_evotune.py @@ -292,6 +292,33 @@ def test_cmaes_tuning_moves_kcats_toward_truth(tmp_path): assert abs(result.new_kcat[i] - _TRUE_KCAT) < abs(before[i] - _TRUE_KCAT) +def test_cmaes_tuning_extends_the_source_of_changed_kcats(tmp_path): + adapter = _adapter(tmp_path) + model = _build_toy(adapter) + params = EvotuneParams(max_generations=15, rmse_threshold=1e-6) + before = model.ec.kcat.copy() + origins = ["brenda", "dlkcat"] + + result = cmaes_kcat_tuning( + model, adapter=adapter, params=params, evotune_data=_evotune_data(), + n_proc=1, seed=0, verbose=False, + ) + + assert (result.new_kcat != before).all() + for i, origin in enumerate(origins): + assert model.ec.source[i] == f"{origin} | tuned=cmaes (prior={before[i]:.6g})" + + # A second run keeps the first prior and does not repeat the method. + first = list(model.ec.source) + kcat_first = model.ec.kcat.copy() + cmaes_kcat_tuning( + model, adapter=adapter, params=params, evotune_data=_evotune_data(), + n_proc=1, seed=1, verbose=False, + ) + assert (model.ec.kcat != kcat_first).any() + assert list(model.ec.source) == first + + def test_cmaes_tuning_n_proc_matches_serial(tmp_path): params = EvotuneParams(max_generations=5, rmse_threshold=-1.0) @@ -399,6 +426,7 @@ def test_tune_prior_penalty_weight_restores_model(tmp_path): model = _build_toy(adapter) evotune_data = _evotune_data() before = model.ec.kcat.copy() + source_before = list(model.ec.source) params = EvotuneParams(max_generations=4, rmse_threshold=-1.0) tune_prior_penalty_weight( @@ -409,6 +437,7 @@ def test_tune_prior_penalty_weight_restores_model(tmp_path): # Unlike cmaes_kcat_tuning, this only reports -- it leaves the model # exactly as it found it. assert np.array_equal(model.ec.kcat, before) + assert list(model.ec.source) == source_before def test_tune_prior_penalty_weight_single_seed_gives_nan_reproducibility(tmp_path): diff --git a/tests/test_evotune_priors.py b/tests/test_evotune_priors.py index 607a9c8..562cecc 100644 --- a/tests/test_evotune_priors.py +++ b/tests/test_evotune_priors.py @@ -69,6 +69,18 @@ def test_build_sigma0_log_uses_group_values_and_default_fallback(): assert sigma0_log.tolist() == pytest.approx([0.4, 0.2, 0.5, 0.3]) +def test_a_tuning_status_does_not_hide_the_source(): + params = EvotuneParams( + source_groups={"brenda": SourceGroupRule(sources=["brenda"])}, + sigma0_log_source={"brenda": 0.2}, + sigma0_log_default=0.3, + ) + for source in ("brenda | tuned=cmaes (prior=6.55)", + "BRENDA (wc=0, origin=2) | tuned=sensitivity+cmaes (prior=5.48)"): + assert classify_kcat_source(source, params) == "brenda" + assert classify_kcat_source("brendax | tuned=cmaes (prior=1)", params) == UNLABELLED_GROUP + + def test_a_fuzzy_match_detail_does_not_hide_the_source(): """``ec.source`` carries the wildcard/origin detail; the tier is the source token in front of it.""" diff --git a/tests/test_fill_kcats.py b/tests/test_fill_kcats.py index 870bdcf..ce51399 100644 --- a/tests/test_fill_kcats.py +++ b/tests/test_fill_kcats.py @@ -268,7 +268,7 @@ def test_filled_kcats_have_isozymes_source(): assert _source(ec_model, "R2_EXP_2") == "isozymes" # The source of the originally-set reaction should be untouched. - assert _source(ec_model, "R2_EXP_1") == "setKcatForReactions" + assert _source(ec_model, "R2_EXP_1") == "manual" def test_deprecated_alias_still_works(): diff --git a/tests/test_get_standard_kcat.py b/tests/test_get_standard_kcat.py index 8b10c63..b346abf 100644 --- a/tests/test_get_standard_kcat.py +++ b/tests/test_get_standard_kcat.py @@ -386,6 +386,7 @@ def test_reaction_without_gpr_gets_standard(tmp_path): assign_standard_kcat(model, _uniprot([100.0])) assert "r1" in model.ec.rxns assert "r2" in model.ec.rxns + assert model.ec.source[list(model.ec.rxns).index("r1")] == "standard" def test_reaction_with_gpr_but_no_ec_entry_gets_standard(tmp_path): diff --git a/tests/test_kcat_source_format.py b/tests/test_kcat_source_format.py new file mode 100644 index 0000000..247185a --- /dev/null +++ b/tests/test_kcat_source_format.py @@ -0,0 +1,278 @@ +"""format_kcat_source and parse_kcat_source, and the writers and readers of ec.source that use them.""" +import math + +import numpy as np +import pandas as pd +import pytest +from scipy import sparse + +from geckopy.ec_model import EcModel +from geckopy.ec_model.ec_data import EcData +from geckopy.gather_kcats import ( + KcatSource, + apply_kcat_list, + format_kcat_source, + parse_kcat_source, +) +from geckopy.gather_kcats.kcat_source_format import is_standard_source + +EXAMPLES = [ + "brenda (wc=0, origin=1)", + "custom", + "okp_catapro (similarity=42)", + "combined (sd=0.61, n=6)", + "brenda (wc=0, origin=2) | tuned=cmaes (prior=6.55)", + "okp_catapro (similarity=42) | tuned=sensitivity+cmaes (prior=5.48)", + "standard", + "manual", + "isozymes", +] + + +def _ec_model(rxns, source=None, kcat=None): + n = len(rxns) + model = EcModel("test") + model.ec = EcData( + rxns=list(rxns), + kcat=np.array(kcat if kcat is not None else [0.0] * n, dtype=float), + source=list(source if source is not None else [""] * n), + notes=[""] * n, + eccodes=[""] * n, + rxn_enz_mat=sparse.csr_matrix((n, 0), dtype=float), + ) + return model + + +# --------------------------------------------------------------------------- # +# format_kcat_source +# --------------------------------------------------------------------------- # + +def test_format_each_example(): + assert format_kcat_source("brenda", {"wc": 0, "origin": 1}) == EXAMPLES[0] + assert format_kcat_source("custom") == "custom" + assert format_kcat_source("okp_catapro", {"similarity": 42}) == EXAMPLES[2] + assert format_kcat_source("combined", {"sd": "0.61", "n": 6}) == EXAMPLES[3] + assert format_kcat_source( + "brenda", {"wc": 0, "origin": 2}, ["cmaes"], 6.55) == EXAMPLES[4] + assert format_kcat_source( + "okp_catapro", {"similarity": 42}, ["sensitivity", "cmaes"], 5.48) == EXAMPLES[5] + assert format_kcat_source("standard") == "standard" + assert format_kcat_source("manual") == "manual" + assert format_kcat_source("isozymes") == "isozymes" + + +def test_format_normalises_origin_and_detail_keys(): + assert format_kcat_source("OKP-CataPro") == "okp_catapro" + assert format_kcat_source(" Sabio--RK ") == "sabio_rk" + assert format_kcat_source("brenda", {"WC-level": 1}) == "brenda (wc_level=1)" + + +def test_format_detail_values(): + assert format_kcat_source("a", {"x": 0.1234567}) == "a (x=0.123457)" + assert format_kcat_source("a", {"x": 1234567.0}) == "a (x=1.23457e+06)" + assert format_kcat_source("a", {"x": np.int64(3)}) == "a (x=3)" + assert format_kcat_source("a", {"x": "0.60"}) == "a (x=0.60)" + + +def test_format_leaves_out_missing_detail_and_empty_brackets(): + assert format_kcat_source("brenda", {"wc": 0, "origin": None}) == "brenda (wc=0)" + assert format_kcat_source("brenda", {"wc": math.nan, "origin": float("nan")}) == "brenda" + assert format_kcat_source("brenda", {}) == "brenda" + + +def test_format_tuning_status_needs_methods(): + assert format_kcat_source("brenda", None, [], 5.0) == "brenda" + assert format_kcat_source("brenda", None, ["cmaes"]) == "brenda | tuned=cmaes" + assert format_kcat_source("brenda", None, ["cmaes"], math.nan) == "brenda | tuned=cmaes" + assert format_kcat_source("brenda", None, iter(["sensitivity"]), 0.5) == ( + "brenda | tuned=sensitivity (prior=0.5)") + + +def test_format_empty_origin(): + assert format_kcat_source("") == "" + assert format_kcat_source("", {}) == "" + assert format_kcat_source("", {"wc": 1}) == "unknown (wc=1)" + assert format_kcat_source("", None, ["cmaes"], 2.0) == "unknown | tuned=cmaes (prior=2)" + + +# --------------------------------------------------------------------------- # +# parse_kcat_source +# --------------------------------------------------------------------------- # + +def test_parse_each_example(): + assert parse_kcat_source(EXAMPLES[0]) == KcatSource("brenda", {"wc": 0.0, "origin": 1.0}) + assert parse_kcat_source("custom") == KcatSource("custom", {}, (), None) + assert parse_kcat_source(EXAMPLES[2]) == KcatSource("okp_catapro", {"similarity": 42.0}) + assert parse_kcat_source(EXAMPLES[3]) == KcatSource("combined", {"sd": 0.61, "n": 6.0}) + assert parse_kcat_source(EXAMPLES[4]) == KcatSource( + "brenda", {"wc": 0.0, "origin": 2.0}, ("cmaes",), 6.55) + assert parse_kcat_source(EXAMPLES[5]) == KcatSource( + "okp_catapro", {"similarity": 42.0}, ("sensitivity", "cmaes"), 5.48) + + +def test_parse_detail_text_and_odd_parts(): + info = parse_kcat_source("x (note=abc, junk, wc = 2 ,=3)") + assert info.origin == "x" + assert info.detail == {"note": "abc", "wc": 2.0} + + +def test_parse_status_without_prior(): + info = parse_kcat_source("brenda | tuned=sensitivity+cmaes") + assert info.tuned == ("sensitivity", "cmaes") + assert info.prior is None + + +@pytest.mark.parametrize("text, origin", [ + ("brenda", "brenda"), + ("OKP-CataPro", "OKP-CataPro"), + ("sensitivityTuning", "sensitivityTuning"), + (" Custom ", "Custom"), + ("setKcatForReactions", "setKcatForReactions"), +]) +def test_parse_legacy_strings_are_origins_as_written(text, origin): + assert parse_kcat_source(text) == KcatSource(origin, {}, (), None) + + +@pytest.mark.parametrize("value", ["", None, math.nan, np.nan, 3, 2.5, ["brenda"]]) +def test_parse_missing_or_non_text_gives_empty_origin(value): + assert parse_kcat_source(value) == KcatSource("", {}, (), None) + + +def test_parse_result_is_frozen(): + with pytest.raises(AttributeError): + parse_kcat_source("brenda").origin = "x" + + +# --------------------------------------------------------------------------- # +# Round trip +# --------------------------------------------------------------------------- # + +@pytest.mark.parametrize("text", EXAMPLES) +def test_format_of_parse_returns_the_string(text): + info = parse_kcat_source(text) + assert format_kcat_source(info.origin, info.detail, info.tuned, info.prior) == text + + +def test_round_trip_changes_only_the_number_format(): + info = parse_kcat_source("combined (sd=0.60, n=6)") + assert format_kcat_source(info.origin, info.detail) == "combined (sd=0.6, n=6)" + + +# --------------------------------------------------------------------------- # +# Writers +# --------------------------------------------------------------------------- # + +def test_apply_kcat_list_writes_the_strings_it_always_wrote(): + model = _ec_model(["r1", "r2", "r3", "r4"]) + kcat_list = pd.DataFrame({ + "rxn_id": ["r1", "r2", "r3", "r4"], + "kcat": [1.0, 2.0, 3.0, 4.0], + "source": ["BRENDA", "DLKcat", "OKP-CataPro", "Sabio-RK"], + "wildcard_level": [0, 2, np.nan, 1], + "origin": [1, np.nan, np.nan, 3], + }) + apply_kcat_list(model, kcat_list) + assert model.ec.source == [ + "brenda (wc=0, origin=1)", + "dlkcat (wc=2)", + "okp_catapro", + "sabio_rk (wc=1, origin=3)", + ] + + +def test_apply_kcat_list_without_fuzzy_columns_writes_the_bare_token(): + model = _ec_model(["r1"]) + apply_kcat_list(model, pd.DataFrame({"rxn_id": ["r1"], "kcat": [1.0], "source": ["DLKcat"]})) + assert model.ec.source == ["dlkcat"] + + +# --------------------------------------------------------------------------- # +# Readers +# --------------------------------------------------------------------------- # + +@pytest.mark.parametrize("source, expected", [ + ("standard", True), + ("standard | tuned=sensitivity (prior=0.5)", False), + ("standard | tuned=cmaes (prior=0.5)", False), + ("Standard", False), + ("standardised", False), + ("brenda", False), + ("", False), +]) +def test_standard_source_needs_the_origin_and_no_tuning_status(source, expected): + assert is_standard_source(source) is expected + + +def test_parse_reads_an_unclosed_bracket_as_one_origin(): + info = parse_kcat_source("brenda (wc=1") + assert info.origin == "brenda (wc=1" + assert info.detail == {} + assert info.tuned == () + assert info.prior is None + + +def test_parse_reads_a_number_only_in_plain_decimal_form(): + info = parse_kcat_source("x (a=1_0, b=inf, c=1e3, d=.5, e=-2., f=0x10)") + assert info.detail == { + "a": "1_0", "b": "inf", "c": 1000.0, "d": 0.5, "e": -2.0, "f": "0x10", + } + + +def test_parse_ignores_a_pair_whose_key_does_not_start_with_a_letter(): + info = parse_kcat_source("x (1a=1, a b=2, ok=3, _c=4)") + assert info.detail == {"ok": 3.0} + + +def test_parse_needs_one_space_before_the_prior(): + info = parse_kcat_source("x | tuned=cmaes(prior=3)") + assert info.tuned == ("cmaes(prior=3)",) + assert info.prior is None + + +def test_format_leaves_out_pairs_without_a_usable_key_or_value(): + assert format_kcat_source("x", {"": 1, "1a": 2, "ok": 3}) == "x (ok=3)" + assert format_kcat_source("x", {"a": float("inf"), "b": 1}) == "x (b=1)" + assert format_kcat_source("x", {"a": float("-inf")}) == "x" + + +def test_format_leaves_out_a_prior_that_is_not_finite(): + assert format_kcat_source("x", None, ["cmaes"], float("inf")) == "x | tuned=cmaes" + + +def test_format_takes_a_single_method_as_text(): + assert format_kcat_source("x", None, "cmaes", 2) == "x | tuned=cmaes (prior=2)" + + +def test_parse_needs_exactly_one_space_before_the_prior(): + info = parse_kcat_source("x | tuned=cmaes (prior=3)") + assert info.tuned == ("cmaes (prior=3)",) + assert info.prior is None + + +def test_parse_reads_a_closing_bracket_inside_the_prior_as_a_method(): + info = parse_kcat_source("x | tuned=cmaes (prior=1))") + assert info.tuned == ("cmaes (prior=1))",) + assert info.prior is None + + +def test_parse_reads_a_number_of_ascii_digits_only(): + info = parse_kcat_source("x (a=\u0663, b=3)") + assert info.detail == {"a": "\u0663", "b": 3.0} + + +def test_format_takes_no_methods_as_none(): + assert format_kcat_source("x", None, None, 2) == "x" + + +def test_parse_trims_the_head_before_the_tuning_status(): + info = parse_kcat_source("x (a=1) | tuned=cmaes") + assert info.origin == "x" + assert info.detail == {"a": 1.0} + assert info.tuned == ("cmaes",) + + +def test_parse_takes_the_first_prior_marker(): + info = parse_kcat_source("x | tuned=cmaes (prior=3) (prior=4)") + assert info.tuned == ("cmaes (prior=3) (prior=4)",) + assert info.prior is None + diff --git a/tests/test_parity_fixes_g1b.py b/tests/test_parity_fixes_g1b.py index 355b64e..12d21e5 100644 --- a/tests/test_parity_fixes_g1b.py +++ b/tests/test_parity_fixes_g1b.py @@ -6,7 +6,14 @@ import pytest from scipy import sparse -from geckopy import EcModel, ModelAdapter, fit_sigma, make_ec_model, sensitivity_tuning +from geckopy import ( + EcModel, + ModelAdapter, + fit_sigma, + make_ec_model, + parse_kcat_source, + sensitivity_tuning, +) from geckopy.ec_model.ec_data import EcData from geckopy.ec_model.pipeline import apply_kcat_constraints, set_prot_pool_size @@ -143,35 +150,17 @@ def test_tuned_reactions_are_listed_in_model_order(tmp_path): def test_rerun_reports_the_kcat_and_source_of_the_input_model(tmp_path): model = _chain(_toy_adapter(tmp_path), kcats=[1.0, 0.5]) + kcat_before = dict(zip(model.ec.rxns, (float(k) for k in model.ec.kcat))) sensitivity_tuning(model, desired_growth_rate=1.0, verbose=False) result = sensitivity_tuning(model, desired_growth_rate=30.0, verbose=False) assert result.rxns assert not np.isnan(result.old_kcat).any() - assert all(src == "sensitivityTuning" for src in result.source) + for rxn, source in zip(result.rxns, result.source): + assert source == f"initial | tuned=sensitivity (prior={kcat_before[rxn]:.6g})" # The values the second run started from are the tuned ones of the first. assert set(result.old_kcat) <= {10.0, 5.0} -@pytest.mark.parametrize("value, text", [ - (10.0, "10"), - (float(np.pi), "3.1416"), - (0.5, "0.5"), - (123456.789, "123456.789"), - (1e7, "10000000"), - (float("nan"), "NaN"), -]) -def test_num2str_prints_a_scalar_as_matlab_does(value, text): - from geckopy.kcat_tuning.sensitivity_tuning import _num2str - assert _num2str(value) == text - - -def test_notes_hold_the_pre_tune_kcat_as_num2str_prints_it(tmp_path): - model = _chain(_toy_adapter(tmp_path), kcats=[10.0, float(np.pi)]) - sensitivity_tuning(model, desired_growth_rate=30.0, verbose=False) - assert "preTuneKcat=10 |" in model.ec.notes[0] - assert "preTuneKcat=3.1416 |" in model.ec.notes[1] - - def test_a_tuned_kcat_has_no_upper_limit(tmp_path): """kcat 2e6 and mw 7.2e9 give growth 1; a target of 100 needs 2e8, past the old 1e7 cap.""" model = _chain(_toy_adapter(tmp_path), kcats=[2e6, 1e12], mws=(7.2e9, 3600.0)) @@ -228,8 +217,7 @@ def test_gecko_light_model_is_tuned(): ) assert result.rxns assert float(model.optimize().objective_value) > before - # ec.source is left as it was on a light model, as in sensitivityTuning.m. - assert list(model.ec.source) == source_before + tuned_rows = set() # Every isozyme row of a tuned reaction was multiplied by the same power of 10. for rxn_id in result.rxns: rows = [i for i, ec_id in enumerate(model.ec.rxns) @@ -237,3 +225,14 @@ def test_gecko_light_model_is_tuned(): ratios = [model.ec.kcat[i] / kcat_before[i] for i in rows] assert ratios and np.allclose(ratios, ratios[0]) assert ratios[0] >= 10.0 - 1e-9 + tuned_rows.update(rows) + # Every changed row has the tuning status with the kcat before tuning as prior; + # every other row keeps its source. + for i, source in enumerate(model.ec.source): + if i in tuned_rows: + parsed = parse_kcat_source(source) + assert parsed.tuned == ("sensitivity",) + assert parsed.prior == pytest.approx(kcat_before[i], rel=1e-5) + assert parsed.origin == (parse_kcat_source(source_before[i]).origin or "unknown") + else: + assert source == source_before[i] diff --git a/tests/test_remove_standard_kcat.py b/tests/test_remove_standard_kcat.py index a20f03b..f7bb132 100644 --- a/tests/test_remove_standard_kcat.py +++ b/tests/test_remove_standard_kcat.py @@ -261,6 +261,38 @@ def test_filled_zero_kcat_reset_to_zero(tmp_path): assert model.ec.source[r2_idx] == "" +def test_tuned_standard_kcat_is_kept(tmp_path): + """A standard kcat with a tuning status was changed on purpose: it is + not reset, while one with the bare origin is.""" + adapter = _adapter(tmp_path) + model = _build_model_with_pool( + adapter, + [("r1", [("A", -1.0, "alpha", "c"), ("B", 1.0, "beta", "c")], "g1"), + ("r2", [("B", -1.0, "beta", "c"), ("C", 1.0, "gamma", "c")], "g2"), + ("r3", [("C", -1.0, "gamma", "c"), ("D", 1.0, "delta", "c")], "g3")], + ec_rxns=["r1", "r2", "r3"], + ec_kcats=[10.0, 0.0, 0.0], + ec_genes=["g1", "g2", "g3"], ec_enzymes=["g1", "g2", "g3"], + ec_mws=[100.0, 100.0, 100.0], + rxn_to_ec_genes=[[0], [1], [2]], + ) + assign_standard_kcat(model, _uniprot([100.0]), fill_zero_kcat=True) + r2_idx = model.ec.rxns.index("r2") + r3_idx = model.ec.rxns.index("r3") + tuned = "standard | tuned=cmaes (prior=7.5)" + model.ec.source[r2_idx] = tuned + kcat_r2 = float(model.ec.kcat[r2_idx]) + + remove_standard_kcat(model) + + r2_idx = model.ec.rxns.index("r2") + r3_idx = model.ec.rxns.index("r3") + assert model.ec.source[r2_idx] == tuned + assert model.ec.kcat[r2_idx] == kcat_r2 + assert model.ec.source[r3_idx] == "" + assert model.ec.kcat[r3_idx] == 0.0 + + # --------------------------------------------------------------------------- # # Round-trip # --------------------------------------------------------------------------- # diff --git a/tests/test_review_public_api.py b/tests/test_review_public_api.py index 90cab47..990be24 100644 --- a/tests/test_review_public_api.py +++ b/tests/test_review_public_api.py @@ -51,3 +51,16 @@ def test_review_recognises_custom_and_standard_without_regard_to_case(): by_rxn = {f.rxn_id: f.checks for f in found} assert "custom-duplicate" in by_rxn["R1"] assert "standard-fallback" in by_rxn["R2"] + + +def test_review_reads_the_origin_of_a_source_with_detail_and_tuning_status(): + stats = {"1.1.1.1": geckopy.EcStats(n_kcat=1, kcat_max=2.0, kcat_median=2.0, values=frozenset({2.0}))} + found = geckopy.review_assignment( + ["R1", "R2", "R3"], [2.0, 20000.0, 2.0], + ["custom | tuned=cmaes (prior=1)", "standard | tuned=sensitivity (prior=1)", "customary"], + ["1.1.1.1", "", "1.1.1.1"], ec_stats=stats, include=("standard-fallback",), + ) + by_rxn = {f.rxn_id: f.checks for f in found} + assert "custom-duplicate" in by_rxn["R1"] + assert "standard-fallback" in by_rxn["R2"] + assert "R3" not in by_rxn diff --git a/tests/test_sensitivity_tuning.py b/tests/test_sensitivity_tuning.py index 6dcabf3..a5388af 100644 --- a/tests/test_sensitivity_tuning.py +++ b/tests/test_sensitivity_tuning.py @@ -151,42 +151,37 @@ def test_explicit_growth_rate_overrides_adapter(tmp_path): # --------------------------------------------------------------------------- # -# Notes annotation +# Source annotation # --------------------------------------------------------------------------- # -def test_notes_annotated_with_pre_tune_kcat(tmp_path): +def test_source_gets_tuning_status_with_prior(tmp_path): adapter = _adapter(tmp_path, gr_exp=300.0) model = _build_toy(adapter, initial_kcat=1.0) sensitivity_tuning(model, fold_change=10.0) - note = model.ec.notes[0] - assert "preTuneKcat=" in note - assert "source:initial" in note + assert model.ec.source[0] == "initial | tuned=sensitivity (prior=1)" -def test_source_set_to_sensitivity_tuning(tmp_path): +def test_notes_are_left_alone(tmp_path): adapter = _adapter(tmp_path, gr_exp=300.0) - model = _build_toy(adapter) + model = _build_toy(adapter, initial_kcat=1.0) + notes = list(model.ec.notes) sensitivity_tuning(model, fold_change=10.0) - assert model.ec.source[0] == "sensitivityTuning" + assert list(model.ec.notes) == notes -def test_re_tuning_does_not_double_annotate(tmp_path): - """A second tuning pass on an already-tuned kcat should not - re-annotate (source is 'sensitivityTuning').""" +def test_re_tuning_keeps_one_method_and_the_first_prior(tmp_path): + """A second tuning pass on a tuned kcat does not repeat the method and + keeps the kcat before the first tuning as prior.""" adapter = _adapter(tmp_path, gr_exp=300.0) model = _build_toy(adapter, initial_kcat=1.0) sensitivity_tuning(model, fold_change=10.0) - note_after_first = model.ec.notes[0] + assert model.ec.source[0] == "initial | tuned=sensitivity (prior=1)" - # Bump target to force more tuning. sensitivity_tuning( model, desired_growth_rate=3000.0, fold_change=10.0, ) - note_after_second = model.ec.notes[0] - - # Note should be unchanged (no second "preTuneKcat=" appended). - assert note_after_first == note_after_second - assert note_after_second.count("preTuneKcat=") == 1 + assert model.ec.kcat[0] > 10.0 + assert model.ec.source[0] == "initial | tuned=sensitivity (prior=1)" # --------------------------------------------------------------------------- # diff --git a/tests/test_set_kcat.py b/tests/test_set_kcat.py index 7187af6..1df3945 100644 --- a/tests/test_set_kcat.py +++ b/tests/test_set_kcat.py @@ -55,7 +55,7 @@ def test_set_single_suffixed_rxn(): updated = set_kcat_for_reactions(ec_model, ["R3"], 10.0, apply=False) assert updated == ["R3"] assert _kcat_at(ec_model, "R3") == 10.0 - assert _source_at(ec_model, "R3") == "setKcatForReactions" + assert _source_at(ec_model, "R3") == "manual" def test_set_single_kcat_scalar_only_form(): @@ -265,13 +265,11 @@ def test_apply_only_updates_passed_reactions(): # Source string # --------------------------------------------------------------------------- # -def test_source_string_matches_matlab(): - """raven-gecko-parity#77: ec.source reads 'setKcatForReactions', - matching MATLAB's actual assignment (its docstring says 'from - setKcatForReactions', but the real code writes the bare name).""" +def test_source_string_is_manual(): + """ec.source reads 'manual' for every reaction set by the call.""" ec_model = _ectestgem_ec_model() set_kcat_for_reactions(ec_model, ["R3"], 10.0, apply=False) - assert _source_at(ec_model, "R3") == "setKcatForReactions" + assert _source_at(ec_model, "R3") == "manual" # --------------------------------------------------------------------------- # @@ -300,7 +298,7 @@ def test_light_set_single_explicit_prefixed_id(): updated = set_kcat_for_reactions(ec, ["001_R3"], 10.0, apply=False) assert updated == ["001_R3"] assert _kcat_at(ec, "001_R3") == 10.0 - assert _source_at(ec, "001_R3") == "setKcatForReactions" + assert _source_at(ec, "001_R3") == "manual" def test_light_base_id_matches_nothing(): @@ -371,3 +369,11 @@ def test_light_apply_picks_lowest_cost_isozyme(): def test_light_unknown_rxn_id_is_ignored(): ec = _ectestgem_light_ec_model() assert set_kcat_for_reactions(ec, ["nonsense"], 1.0) == [] + + +def test_source_drops_the_tuning_status(): + ec_model = _ectestgem_ec_model() + i = ec_model.ec.rxns.index("R3") + ec_model.ec.source[i] = "brenda (wc=0, origin=1) | tuned=cmaes (prior=2)" + set_kcat_for_reactions(ec_model, ["R3"], 10.0, apply=False) + assert _source_at(ec_model, "R3") == "manual"