straindesign.compression ======================== .. py:module:: straindesign.compression .. autoapi-nested-parse:: Metabolic network compression using nullspace-based coupling detection. This module provides network compression for COBRA models. The main function is compress_cobra_model() which compresses a model and returns transformation matrices for converting between original and compressed flux spaces. API: >>> from straindesign.compression import compress_cobra_model >>> result = compress_cobra_model(model) >>> compressed_model = result.compressed_model Note: The model should be preprocessed first (rational coefficients, conservation relations removed). Use networktools.compress_model() for automatic preprocessing. Module Contents --------------- .. py:class:: CompressionConverter(reaction_map: Dict[str, Dict[str, Union[float, fractions.Fraction]]], metabolite_map: Dict[str, Dict[str, Union[float, fractions.Fraction]]], flipped_reactions: List[str]) Bidirectional transformer for expressions between original and compressed spaces. .. py:method:: expand_expression(expression: Dict[str, float], remove_missing: bool = False) -> Dict[str, float] Transform expression from compressed back to original space. .. py:class:: CompressionMethod Bases: :py:obj:`enum.Enum` Compression methods for metabolic network compression. .. py:method:: standard() -> List[CompressionMethod] :classmethod: Standard compression methods (recommended). .. py:class:: CompressionRecord(pre: RationalMatrix, cmp: RationalMatrix, post: RationalMatrix, meta_names: List[str], stats: Optional[CompressionStatistics] = None) Compression result with transformation matrices. Contains: pre @ stoich @ post == cmp For EFM expansion: efm_original = post @ efm_compressed .. py:class:: CompressionResult(compressed_model, compression_converter, pre_matrix, post_matrix, reaction_map, metabolite_map, statistics, methods_used, original_reaction_names, original_metabolite_names, flipped_reactions) Result of COBRA model compression. .. py:class:: CompressionStatistics Tracks compression statistics for logging. .. py:class:: RationalMatrix(rows: int, cols: int) Sparse rational matrix using dual int sparse storage (numerators + denominators). .. py:method:: add_scaled_column(dst_col: int, src_col: int, scalar_num: int, scalar_den: int) -> None Add scalar * column[src] to column[dst]. dst[i] += (num/den) * src[i] .. py:method:: begin_batch_edit() Enter batch edit mode - delays cache invalidation. .. py:method:: clone() -> RationalMatrix Create a deep copy. .. py:method:: end_batch_edit() Exit batch edit mode - converts back to CSR and invalidates cache. .. py:method:: from_cobra_model(model, max_precision: int = 6, max_denom: int = 100) -> RationalMatrix :classmethod: Create RationalMatrix from COBRA model stoichiometry. .. py:method:: from_numpy(arr: numpy.ndarray, max_precision: int = 6, max_denom: int = 100) -> RationalMatrix :classmethod: Create RationalMatrix from numpy array. .. py:method:: get_signum(row: int, col: int) -> int Return sign of element: -1, 0, or 1. .. py:method:: identity(size: int) -> RationalMatrix :classmethod: Create identity matrix. .. py:method:: iter_column_fractions(col: int) -> Iterator[Tuple[int, fractions.Fraction]] Iterate over non-zero entries in column as (row, Fraction) pairs. .. py:method:: remove_columns(keep_indices: List[int]) -> None Keep only the specified columns. .. py:method:: remove_rows(keep_indices: List[int]) -> None Keep only the specified rows. .. py:method:: submatrix(rows: int, cols: int) -> RationalMatrix Extract top-left submatrix of given dimensions. .. py:method:: to_numpy() -> numpy.ndarray Convert to numpy float array. .. py:method:: to_sparse_csr() -> Tuple[scipy.sparse.csr_matrix, int] Return sparse representation and common denominator. Returns numerator matrix scaled by LCM of denominators, plus the LCM. .. py:method:: to_sparse_pattern() -> Tuple[scipy.sparse.csr_matrix, Dict[int, Dict[int, fractions.Fraction]]] Return sparsity pattern as CSR and row-wise Fraction data. For pattern analysis (coupled reaction detection) without integer overflow. :returns: CSR matrix with 1s at non-zero positions (for indptr/indices) row_data: {row: {col: Fraction}} for actual values :rtype: pattern .. py:class:: StoichMatrixCompressor(*methods: CompressionMethod) Nullspace-based metabolic network compression. .. py:method:: compress(stoich: RationalMatrix, meta_names: List[str], reac_names: List[str], suppressed: Optional[Set[str]] = None, bounds: Optional[List[Tuple[float, float]]] = None) -> CompressionRecord Compress network, return transformation matrices. Single-pass approach: each iteration computes the nullspace once, then removes zero-flux reactions AND merges coupled groups from the same kernel. Re-iterates only when contradicting groups were removed (which may expose new couplings). .. py:function:: basic_columns(matrix: RationalMatrix) -> List[int] Find indices of basic (pivot) columns using integer RREF. .. py:function:: basic_columns_from_numpy(mx: numpy.ndarray) -> List[int] Find basic columns from a numpy array. .. py:function:: compress_cobra_model(model, methods: Optional[List[Union[str, CompressionMethod]]] = None, in_place: bool = True, suppressed_reactions: Optional[Set[str]] = None) -> CompressionResult Compress a COBRA model using nullspace-based coupling detection. Note: Model should be preprocessed first (rational coefficients, conservation relations removed). Use networktools.compress_model() for automatic preprocessing. :param model: COBRA model to compress (should be preprocessed) :param methods: Compression methods. Default: CompressionMethod.standard() :param in_place: Modify original model (True) or work on copy (False) :param suppressed_reactions: Reaction names to exclude from compression :returns: CompressionResult with compressed model and transformation data .. py:function:: compress_model(model, no_par_compress_reacs=set(), compression_backend='sparse_rref', propagate_gpr=False) Compress a metabolic model using multiple techniques. Performs blocked reaction removal, conservation relation removal, and alternating dependent/parallel reaction lumping until no further compression is possible. :param model: COBRA model to compress in-place :param no_par_compress_reacs: Reactions exempt from parallel compression :param compression_backend: Compression backend to use: - 'sparse_rref' (default): Pure Python sparse integer RREF. No external dependencies beyond NumPy/SciPy. - 'efmtool_rref' (legacy): Java-based EFMTool via JPype. Requires a JVM and the jpype1 package. :param propagate_gpr: If True, propagate and simplify GPR rules through compression (AND for coupled, OR for parallel merges). Empty GPR rules are correctly handled: skipped in AND (always active), and absorb in OR (result is always active). Uses sympy for boolean simplification. Default False. :returns: Compression maps for reversing each compression step :rtype: list of dict .. py:function:: compress_model_coupled(model, compression_backend='sparse_rref', propagate_gpr=False, suppressed_reactions=None) Compress by lumping stoichiometrically coupled (dependent) reactions. Identifies groups of reactions whose flux vectors are proportional in every steady state (i.e. they share a common nullspace direction) and merges each group into a single lumped reaction. Both the pure-Python and legacy Java backends perform this operation; the compression_backend controls the nullspace algorithm. :param model: COBRA model to compress in-place :param compression_backend: 'sparse_rref' (default, Python) or 'efmtool_rref' (Java legacy) :param propagate_gpr: If True, AND-combine GPR rules of merged reactions (with sympy simplification). Empty GPRs are skipped. Default False. :param suppressed_reactions: Set of reaction IDs to exclude from compression (Java backend only). Used to protect reactions referenced in strain design constraints from being deleted by the Java compressor's CoupledContradicting logic. Ignored for the Python backend (which handles contradicting groups correctly via bounds intersection). :returns: Mapping {compressed_id: {orig_id: factor, ...}} :rtype: dict .. py:function:: compress_model_parallel(model, protected_rxns=set(), propagate_gpr=False) Compress by lumping parallel reactions. :param model: COBRA model to compress in-place :param protected_rxns: Reactions exempt from parallel compression :param propagate_gpr: If True, OR-combine GPR rules of lumped reactions (with sympy simplification). Default False. :returns: Mapping {compressed_id: {orig_id: factor, ...}} :rtype: dict .. py:function:: detect_max_precision(model) -> int Detect maximum decimal precision needed for model coefficients. .. py:function:: float_to_rational(val, max_precision: int = 6, max_denom: int = 100) -> fractions.Fraction Convert float to Fraction with bounded denominators. .. py:function:: nullspace(matrix: RationalMatrix) -> RationalMatrix Compute right nullspace (kernel). Returns K where matrix @ K = 0. Uses integer RREF with column/row pre-sorting and GCD reduction. All arithmetic is Python arbitrary-precision integers — no overflow possible. :param matrix: Input RationalMatrix :returns: Kernel matrix K where matrix @ K = 0 .. py:function:: remove_blocked_reactions(model) -> List Remove blocked reactions (bounds == (0, 0)) from a network. .. py:function:: remove_conservation_relations(model) -> None Remove conservation relations (dependent metabolites) from a model. This reduces the number of metabolites while maintaining the original flux space. Uses exact rational arithmetic to find linearly independent rows. :param model: COBRA model to modify in-place .. py:function:: remove_dummy_bounds(model) -> None Replace COBRA standard bounds with +/-inf. .. py:function:: remove_ext_mets(model) -> None Remove external metabolites from 'External_Species' compartment. .. py:function:: stoichmat_coeff2float(model) -> None Convert stoichiometric coefficients to floats. .. py:function:: stoichmat_coeff2rational(model) -> None Convert stoichiometric coefficients to rational numbers.