robustnet.model =============== .. py:module:: robustnet.model .. autoapi-nested-parse:: Define Model class. Classes ------- .. autoapisummary:: robustnet.model.Reaction robustnet.model.Ratelaw robustnet.model.Model Module Contents --------------- .. py:class:: Reaction Bases: :py:obj:`tuple` .. py:attribute:: enzyme .. py:attribute:: substrates .. py:attribute:: products .. py:attribute:: ratelaw .. py:class:: Ratelaw Bases: :py:obj:`tuple` .. py:attribute:: enz .. py:attribute:: metabs .. py:attribute:: kparams .. py:attribute:: expr .. py:class:: Model(name=None) .. py:attribute:: name :value: None .. py:attribute:: reaction_list :value: [] .. py:attribute:: enzyme_list :value: [] .. py:attribute:: metabolite_list :value: [] .. py:attribute:: reaction_info .. py:attribute:: reaction_list_temp .. py:attribute:: enzyme_list_temp .. py:attribute:: metabolite_list_temp .. py:attribute:: reaction_info_temp .. py:method:: _parse_reactants(expr) :param expr: Expression describing substrates or products. Spaces between coefficients and metabolite names are allowed. Metabolite names cannot start with a number. :type expr: str :returns: **metab_coe** -- Dictionary mapping metabolite IDs to their stoichiometric coefficients. :rtype: dict .. py:method:: _parse_expression(rxn, expr_str, enzymes, metabolites) Parse a reaction rate expression. :param expr_str: Mathematical expression defining the reaction rate. :type expr_str: str :param rxn: Reaction ID. :type rxn: str :param enzymes: List of enzyme IDs. :type enzymes: list of str :param metabolites: List of metabolite IDs. :type metabolites: list of str :returns: **ratelaw** -- Parsed reaction rate information with the following fields: - ``enz`` (str or None): Enzyme variable. - ``metabs`` (list of str): Sorted metabolite variables. - ``kparams`` (list of str): Sorted kinetic parameter variables. - ``expr``: Symbolic expression of the reaction rate. :rtype: namedtuple .. py:method:: _update_model() Update reaction information in the model. Variables appearing in the rate expression that are not identified as enzymes, substrates, or products are treated as kinetic parameters. .. py:method:: read_from_file(filename) Read reaction information from a file. Previously imported reactions with the same reaction ID will be overwritten. :param filename: Path to the input file containing reaction information. Supported file formats are ``.xlsx``, ``.tsv``, and ``.csv``. The input file must contain the following columns: - ``Reaction``: Reaction ID. - ``Enzyme``: Catalytic enzyme associated with the reaction. Leave empty if the reaction is non-enzymatic. - ``Substrates``: Reaction substrates separated by ``+``. Spaces between metabolite names are allowed. Metabolite names cannot start with a number, but may contain ``-`` and ``_``. Metabolite names must not overlap with enzyme names. - ``Products``: Reaction products separated by ``+``. Spaces between metabolite names are allowed. Metabolite names cannot start with a number, but may contain ``-`` and ``_``. Metabolite names must not overlap with enzyme names. - ``Rate expression``: Mathematical expression defining the reaction rate. Enzyme and metabolite names must be consistent with those provided in the ``Enzyme``, ``Substrates``, and ``Products`` columns. Any additional variables appearing in the expression are treated as kinetic parameters. Both reversible and irreversible reactions are supported. Spaces in the expression are allowed. :type filename: str .. py:method:: add_reaction(name=None, enzyme=None, substrates=None, products=None, rate_expression=None) Add reaction information into the model. Previously imported reactions with the same reaction ID will be overwritten. :param name: reaction ID. :type name: str, optional :param enzyme: Catalytic enzyme associated with the reaction. Use ``None`` for non-enzymatic reactions. :type enzyme: str or None, optional :param substrates: Dictionary mapping substrate metabolite IDs to stoichiometric coefficients. Metabolite names cannot start with a number, but may contain ``-`` and ``_``. Metabolite names must not overlap with enzyme names. Use ``None`` if the reaction has no substrates. :type substrates: dict or None, optional :param products: Dictionary mapping product metabolite IDs to stoichiometric coefficients. Metabolite names cannot start with a number, but may contain ``-`` and ``_``. Metabolite names must not overlap with enzyme names. Use ``None`` if the reaction has no products. :type products: dict or None, optional :param rate_expression: Mathematical expression defining the reaction rate. Enzyme and metabolite names must be consistent with those used in the ``enzyme``, ``substrates``, and ``products`` arguments. Any additional variables in the expression are treated as kinetic parameters. Spaces in the expression are allowed. :type rate_expression: str or None, optional .. py:method:: remove_reaction(reactions) Remove reaction(s) from the model. :param reactions: Reaction ID or list of reaction IDs to remove. :type reactions: str or list of str .. py:method:: parsed_kinetic_parameters(reactions='all') Show parsed kinetic parameters in reactions. :param reactions: Reactions for which parsed kinetic parameters are returned. Use ``"all"`` to return kinetic parameters for all reactions in the model. :type reactions: str or list of str, optional .. py:method:: __repr__() .. py:method:: _make_stoichiometric_matrix(reaction_info, metabolites, reactions, exclude=None) :staticmethod: Build the stoichiometric matrix from reaction information. :param reaction_info: Dictionary of reactions in the format ``{reaction_id: Reaction_namedtuple}``. :type reaction_info: dict :param metabolites: Metabolite IDs defining the matrix rows. :type metabolites: tuple or list :param reactions: Reaction IDs defining the matrix columns. :type reactions: tuple or list :param exclude: Metabolites to exclude from the stoichiometric matrix. :type exclude: tuple, list or None, optional .. py:method:: stoichiometric_matrix(exclude=None) Compute the stoichiometric matrix, where rows correspond to metabolites and columns correspond to reactions. :param exclude: Metabolites to exclude from the stoichiometric matrix. :type exclude: list, optional .. py:method:: _get_live_metabolites(stoy_mat) :staticmethod: .. py:method:: initial_substrates(exclude=None) Get the initial substrates of the model. Initial substrates are metabolites that participate in only one consuming reaction and are not produced by any reaction. :param exclude: Metabolites to exclude from the stoichiometric matrix and, consequently, from the returned initial substrate list. :type exclude: list, optional .. py:method:: final_products(exclude=None) Get the final products of the model. Final products are metabolites that participate in only one producing reaction and are not consumed by any reaction. :param exclude: Metabolites to exclude from the stoichiometric matrix and, consequently, from the returned final product list. :type exclude: list, optional .. py:method:: _check_data_consistency(data, data_type, kind, std) .. py:method:: load_priors(kind, data, std=None) Metabolomics and proteomics data are expected in units of mM, while fluxomics data are expected in units of mmol/L/s. For kinetic parameters, catalytic constants have units of 1/s, Michaelis, activation, and inhibition constants have units of mM, and equilibrium constants are dimensionless. All concentration and flux units are assumed to be cell-volume based. Missing values are allowed and may be indicated by ``"nan"``, ``"na"``, or blank entries in the input file. :param kind: "kparameters"} Type of prior measurement data. :type kind: {"metabolomics", "proteomics", "fluxomics", "reference_fluxes", :param data: Prior measurements. File names must end with ``.xlsx``, ``.tsv``, or ``.csv``. The input file with headers must contain species name and its measurement in each row. Alternatively, a ``pandas.Series`` can be provided. :type data: file or pandas.Series :param std: Standard deviations of prior measurements. File names must end with ``.xlsx``, ``.tsv``, or ``.csv``. The input file with headers must contain species name and its measurement in each row. Alternatively, a ``pandas.Series`` can be provided. The shape of ``std`` must match that of ``data``. Use ``None`` if uncertainty information is unavailable. :type std: file or pandas.Series, optional .. py:method:: estimate_reference_fluxes(bounds, exclude_metabolites=None, optimizer='scipy', method='COBYQA', tol=0.0001) Estimate the reference flux distribution by fitting measured fluxes (e.g., from 13C fluxomics) using least-squares regression. Fluxes are expected in units of mmol/L/s with cell-based volumes. Note that it is recommended to run the optimization multiple times to improve the chance of obtaining a solution with minimal SSR. :param bounds: Lower and upper bounds used during fitting. If a tuple is provided, the same bounds are applied to all fluxes. If a dict is provided, bounds can be specified for individual fluxes, which is useful for defining flux reversibility. For example, Setting ``lower_bound >= 0`` or ``upper_bound <= 0`` enforces irreversibility in the forward or reverse direction, respectively. Fluxes without explicit bounds use the minimum lower bound and maximum upper bound from the provided bounds. :type bounds: 2-tuple or dict of 2-tuples :param exclude_metabolites: Metabolites excluded from steady-state mass balance constraints, such as initial substrates and final products. If ``None``, these metabolites are inferred automatically from the stoichiometric matrix. Because inferred initial substrates and final products depend on reaction direction definitions, explicitly specifying this argument is recommended. :type exclude_metabolites: list of str or None, optional :param optimizer: Optimizer used to solve the fitting problem. The NLopt package must be installed if ``optimizer="nlopt"`` is selected. :type optimizer: {"scipy", "nlopt"}, optional :param method: optimization method. ``COBYQA`` is gradient-free and generally more robust for non-smooth problems, but may be slower. ``SLSQP`` is gradient-based and typically faster, but may struggle with highly nonlinear problems. Currently, ``COBYQA`` is only available when ``optimizer="scipy"``. :type method: {"COBYQA", "SLSQP"}, optional :param tol: Tolerance criterion for optimization convergence. :type tol: float, optional :returns: **res** -- Object containing the estimated reference flux distribution. Important attributes and methods include: - ``estimated_fluxes``: Estimated reference flux distribution. - ``estimated_flux_errors``: Estimated errors in the reference flux distribution. - ``plot_simulated_vs_measured_fluxes``: Visualize simulated versus measured fluxes. :rtype: FluxFitResults .. py:method:: generate_parameter_sets(ref_flux_mu=None, kparam_prior_mu=None, mconc_prior_mu=None, econc_prior_mu=None, ref_flux_sigma=None, kparam_prior_sigma=None, mconc_prior_sigma=None, econc_prior_sigma=None, ref_flux_initvalues=None, kparam_initvalues=None, mconc_initvalues=None, econc_initvalues=None, exclude_metabolites=None, alpha=None, n_tunes=5000, n_samples=2000, n_chains=10, n_jobs=1) Sample model parameters based on prior knowledge of reference fluxes, metabolite concentrations, enzyme concentrations and enzyme kinetic parameters, which can be collected from omics data and enzyme database. Missing values are allowed. Prior measurements can be provided directly through the corresponding arguments or loaded beforehand using ``load_priors``. Directly supplied arguments take precedence over loaded priors. :param ref_flux_mu: Reference-state flux distribution in units of mmol/L/s (cell-based). Typically obtained from ``estimate_reference_fluxes``. If ``None``, reference fluxes loaded by ``load_priors`` are used. :type ref_flux_mu: dict, pandas.Series or None :param kparam_prior_mu: Mean values of the prior distributions for kinetic parameters. Catalytic constants have units of 1/s, Michaelis, activation, and inhibition constants have units of mM, and equilibrium constants are dimensionless. Missing kinetic parameters are allowed. If ``None``, kinetic parameters loaded by ``load_priors`` are used. :type kparam_prior_mu: dict, pandas.Series or None :param mconc_prior_mu: Mean values of prior metabolite concentrations in mM (cell-based). Missing metabolites are allowed. If ``None``, metabolomics data loaded by ``load_priors`` are used. :type mconc_prior_mu: dict, pandas.Series, or None :param econc_prior_mu: Mean values of prior enzyme concentrations in mM (cell-based). Missing enzymes are allowed. If ``None``, proteomics data loaded by ``load_priors`` are used. :type econc_prior_mu: dict, pandas.Series, or None :param ref_flux_sigma: Standard deviations of reference-state fluxes. If a scalar is provided, the same value is used for all fluxes. Missing flux values are allowed when using a dict or ``pandas.Series``. Typically obtained from ``estimate_reference_fluxes``. If ``None``, standard deviations from reference fluxes loaded by ``load_priors`` are used. Defaults to ``0.01``. :type ref_flux_sigma: scalar, dict, pandas.Series, or None, optional :param kparam_prior_sigma: Standard deviations of kinetic parameters. If a scalar is provided, the same value is used for all parameters. Missing parameter values are allowed. If ``None``, standard deviations from kinetic parameters loaded by ``load_priors`` are used. Default to ``0.1``. :type kparam_prior_sigma: scalar, dict, pandas.Series, or None, optional :param mconc_prior_sigma: Standard deviations of metabolite concentrations. If a scalar is provided, the same value is used for all metabolites. Missing metabolite values are allowed. If ``None``, standard deviations from metabolomics data loaded by ``load_priors`` are used. Default to ``0.1``. :type mconc_prior_sigma: scalar, dict, pandas.Series, or None, optional :param econc_prior_sigma: Standard deviations of enzyme concentrations. If a scalar is provided, the same value is used for all enzymes. Missing enzyme values are allowed. If ``None``, standard deviations from proteomics data loaded by ``load_priors`` are used. Default to ``0.001``. :type econc_prior_sigma: scalar, dict, pandas.Series, or None, optional :param ref_flux_initvalues: Initial values for reference flux sampling. Missing fluxes are allowed. If ``None``, ``ref_flux_mu`` is used. :type ref_flux_initvalues: dict, pandas.Series, or None, optional :param kparam_initvalues: Initial values for kinetic parameter sampling. Missing parameter values are allowed. If ``None``, ``kparam_prior_mu`` is used. :type kparam_initvalues: dict, pandas.Series, or None, optional :param mconc_initvalues: Initial values for metabolite concentration sampling. Missing metabolite values are allowed. If ``None``, ``mconc_prior_mu`` is used. :type mconc_initvalues: dict, pandas.Series, or None, optional :param econc_initvalues: Initial values for enzyme concentration sampling. Missing enzyme values are allowed. If ``None``, ``econc_prior_mu`` is used. :type econc_initvalues: dict, pandas.Series, or None, optional :param exclude_metabolites: Reserved argument. Currently unused. :type exclude_metabolites: list of str or None, optional :param alpha: Gaussian penalty strength used in parameter balancing. Larger values impose stronger penalties in log-posterior space. A reasonable choice is often on the same order of magnitude as ``1 / ref_flux_sigma**2``. If ``None``, ``geomean(1 / ref_flux_sigma**2)`` is used. Excessively large values of ``alpha`` may produce sparse or discontinuous samples and significantly reduce the number of effective models in robustness analysis. :type alpha: float or None, optional :param n_tunes: Number of tuning iterations performed before sampling in each chain. :type n_tunes: int, optional :param n_samples: Number of samples drawn in each chain. :type n_samples: int, optional :param n_chains: Number of sampling chains. :type n_chains: int, optional :param n_jobs: Number of parallel jobs to run in parallel. For Windows platforms, ``n_jobs`` is forced to ``1`` for compatibility reasons. :type n_jobs: int, optional :returns: **res** -- Object containing the sampled parameter sets. Important attributes and methods include: - ``sampled_reference_fluxes``: Sampled reference flux distributions. - ``sampled_kinetic_parameters``: Sampled kinetic parameters. - ``sampled_metabolite_concentrations``: Sampled metabolite concentrations. - ``sampled_enzyme_concentrations``: Sampled enzyme concentrations. - ``trace``: ``arviz.InferenceData`` object containing the sampling trace. - ``plot_sampled_vs_prior_fluxes``: Visualize sampled versus prior reference fluxes. - ``plot_sampled_vs_prior_kinetic_parameters``: Visualize sampled versus prior kinetic parameters. - ``plot_sampled_vs_prior_metabolites``: Visualize sampled versus prior metabolite concentrations. - ``plot_sampled_vs_prior_enzymes``: Visualize sampled versus prior enzyme concentrations. :rtype: NonTCSampleResults .. py:method:: load_parameter_sets(mconc_set, econc_set, kparam_set) Load sampled parameter sets for robustness analysis. Sampled parameter sets must be mutually compatible by index. For example, the ``i``-th sampled metabolite concentration set must correspond to the ``i``-th sampled kinetic parameter set and enzyme concentration set. :param mconc_set: Sampled metabolite concentration sets. File names must end with ``.xlsx``, ``.tsv``, or ``.csv``. Columns correspond to metabolites. Alternatively, a ``pandas.DataFrame`` can be provided. :type mconc_set: file or pandas.DataFrame :param econc_set: Sampled enzyme concentration sets. File names must end with ``.xlsx``, ``.tsv``, or ``.csv``. Columns correspond to enzymes. Alternatively, a ``pandas.DataFrame`` can be provided. :type econc_set: file or pandas.DataFrame :param kparam_set: Sampled kinetic parameter sets. File names must end with ``.xlsx``, ``.tsv``, or ``.csv``. Columns correspond to kinetic parameters. Alternatively, a ``pandas.DataFrame`` can be provided. Note that some metabolites may be treated as kinetic parameters if they only appear in reaction rate expressions. These metabolites must therefore also be included in the kinetic parameter sets. :type kparam_set: file or pandas.DataFrame .. py:method:: evaluate_robustness(perturb_enzymes='all', fold_change=(0.2, 5), exclude_metabolites=None, n_steps=200, log_spacing=False, n_models=1000, n_jobs=1, flux_sensitivity=True, check_jacobian=True, check_metabolite=True) Simulate perturbation responses and evaluate the robustness of the metabolic system with respect to enzyme expression perturbations. :param perturb_enzymes: Enzymes to perturb simultaneously over their specified expression ranges. If ``"all"``, all enzymes in the model are perturbed. :type perturb_enzymes: list of str or "all", optional :param fold_change: Relative perturbation bounds for enzyme concentrations, defined as fold changes with respect to the reference state. The fold-change interval must always include ``1`` (the reference state). Perturbations are simulated from the reference state toward both left and right bounds. For example, ``(0.1, 10)`` and ``(10, 0.1)`` both indicate simulations from ``1 → 0.1`` and ``1 → 10``. If one bound equals ``1``, perturbation is only performed in one direction. For example, ``(1, 50)`` and ``(50, 1)`` both indicate perturbation from ``1 → 50``. If a dict is provided, fold-change ranges can be assigned individually to enzymes. This allows coordinated or opposed regulation patterns. For example, ``{"A": (0.1, 10), "B": (50, 0.5)}`` indicates that in the left direction enzyme A is perturbed from ``1 -> 0.1`` while enzyme B is perturbed simultaneously from ``1 -> 50``, whereas in the right direction enzyme A is perturbed from ``1 -> 10`` while enzyme B is perturbed simultaneously from ``1 -> 0.5``. ``{"A": (1, 10), "B": (1, 50)}`` represents co-overexpression of enzyme A and B, whereas ``{"A": (1, 10), "B": (0.5, 1)}`` represents simultaneous overexperssion of enzyme A and downregulation of enzyme B. Enzymes without explicitly assigned ranges use the default fold-change range ``(0.2, 5)``. Enzymes specified in ``fold_change`` but not explicitly listed in ``perturb_enzymes`` are still perturbed if their names are valid. This argument can also be used when ``perturb_enzymes="all"``. In this case, specified fold-change ranges override the default values. :type fold_change: 2-tuple or dict, optional :param exclude_metabolites: Metabolites excluded from the analysis. Excluded metabolites are not included in the ODE system. :type exclude_metabolites: list of str or None, optional :param n_steps: Number of perturbation steps in each direction. If perturbation is performed in both directions, ``2 * n_steps`` total steps are applied. Large fold changes may cause model failure at early perturbation steps, resulting in no effective models. Increasing ``n_steps`` may improve stability in such cases. :type n_steps: int, optional :param log_spacing: If ``True``, perturbation points are logarithmically spaced. Otherwise, they are evenly spaced. :type log_spacing: bool, optional :param n_models: Number of sampled models used in the simulation. Increasing this value may improve consensus robustness estimates. The maximum number of models is limited by the number of loaded parameter sets. :type n_models: int, optional :param n_jobs: Number of parallel jobs. :type n_jobs: int, optional :param flux_sensitivity: If ``True``, derivatives of steady-state fluxes with respect to enzyme concentrations are also computed. :type flux_sensitivity: bool, optional :param check_jacobian: If ``True``, verify that all eigenvalues of the Jacobian matrix have negative real parts. :type check_jacobian: bool, optional :param check_metabolite: If ``True``, enforce positive metabolite concentrations during analysis. :type check_metabolite: bool, optional :returns: **res** -- Object containing robustness analysis results. Important attributes and methods include: - ``robust_index``: Robustness index under the specified perturbation condition. - ``robust_model_probability``: Plot the probability of models remaining robust across perturbations. - ``metabolite_sensitivity``: Plot metabolite concentration responses across perturbations. - ``bifurcation_diagram``: Alias for ``metabolite_sensitivity``. - ``metabolite_distribution``: Plot distributions of metabolite concentrations during perturbations. - ``flux_sensitivity``: Plot steady-state flux responses across perturbations. Available only when ``flux_sensitivity=True``. - ``flux_distribution``: Plot distributions of steady-state fluxes during perturbations. Available only when ``flux_sensitivity=True``. - ``eigreal_sensitivity``: Plot responses of the maximum real part of Jacobian eigenvalues across perturbations. - ``eigreal_distribution``: Plot distributions of the maximum real part of Jacobian eigenvalues during perturbations. :rtype: EnsembleResults