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, reversible: List[bool], 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, reversible: List[bool], meta_names: List[str], reac_names: List[str], suppressed: Optional[Set[str]] = None) -> CompressionRecord Compress network, return transformation matrices. Uses Java efmtool's two-phase approach: 1. Phase 1: Remove zero-flux and contradicting reactions (iteratively) 2. Phase 2: Combine coupled reactions (iteratively) This separation prevents cascading effects where combining reactions could create new coupling patterns that weren't present in the original. .. 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') 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. :returns: Compression maps for reversing each compression step :rtype: list of dict .. py:function:: compress_model_coupled(model, compression_backend='sparse_rref') 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) :returns: Mapping {compressed_id: {orig_id: factor, ...}} :rtype: dict .. py:function:: compress_model_parallel(model, protected_rxns=set()) Compress by lumping parallel reactions. :param model: COBRA model to compress in-place :param protected_rxns: Reactions exempt from parallel compression :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.