cobra.sampling.hr_sampler ========================= .. py:module:: cobra.sampling.hr_sampler .. autoapi-nested-parse:: Provide the base class and associated functions for Hit-and-Run samplers. Attributes ---------- .. autoapisummary:: cobra.sampling.hr_sampler.logger Classes ------- .. autoapisummary:: cobra.sampling.hr_sampler.Problem cobra.sampling.hr_sampler.HRSampler Functions --------- .. autoapisummary:: cobra.sampling.hr_sampler.shared_np_array Module Contents --------------- .. py:data:: logger .. py:class:: Problem Bases: :py:obj:`tuple` .. py:attribute:: equalities .. py:attribute:: b .. py:attribute:: inequalities .. py:attribute:: bounds .. py:attribute:: variable_fixed .. py:attribute:: variable_bounds .. py:attribute:: nullspace .. py:attribute:: homogeneous .. py:function:: shared_np_array(shape: Tuple[int, int], data: Optional[numpy.ndarray] = None, integer: bool = False) -> numpy.ndarray Create a new numpy array that resides in shared memory. :param shape: The shape of the new array. :type shape: tuple of int :param data: Data to copy to the new array. Has to have the same shape (default None). :type data: numpy.array, optional :param integer: Whether to use an integer array. By default, float array is used (default False). :type integer: bool, optional :returns: The newly created shared numpy array. :rtype: numpy.array :raises ValueError: If the input `data` (if provided) size is not equal to the created array. .. py:class:: HRSampler(model: cobra.Model, thinning: int, nproj: Optional[int] = None, seed: Optional[int] = None, **kwargs) Bases: :py:obj:`abc.ABC` The abstract base class for hit-and-run samplers. New samplers should derive from this class where possible to provide a uniform interface. :param model: The cobra model from which to generate samples. :type model: cobra.Model :param thinning: The thinning factor of the generated sampling chain. A thinning of 10 means samples are returned every 10 steps. :type thinning: int :param nproj: How often to reproject the sampling point into the feasibility space. Avoids numerical issues at the cost of lower sampling. If you observe many equality constraint violations with `sampler.validate` you should lower this number (default None). :type nproj: int > 0, optional :param seed: Sets the random number seed. Initialized to the current time stamp if None (default None). :type seed: int > 0, optional .. attribute:: feasibility_tol The tolerance used for checking equalities feasibility. :type: float .. attribute:: bounds_tol The tolerance used for checking bounds feasibility. :type: float .. attribute:: n_samples The total number of samples that have been generated by this sampler instance. :type: int .. attribute:: retries The overall of sampling retries the sampler has observed. Larger values indicate numerical instabilities. :type: int .. attribute:: problem A NamedTuple whose attributes define the entire sampling problem in matrix form. :type: Problem .. attribute:: warmup A numpy matrix with as many columns as reactions in the model and more than 3 rows containing a warmup sample in each row. None if no warmup points have been generated yet. :type: numpy.matrix .. attribute:: fwd_idx A numpy array having one entry for each reaction in the model, containing the index of the respective forward variable. :type: numpy.array .. attribute:: rev_idx A numpy array having one entry for each reaction in the model, containing the index of the respective reverse variable. :type: numpy.array .. py:attribute:: model .. py:attribute:: feasibility_tol .. py:attribute:: bounds_tol .. py:attribute:: thinning .. py:attribute:: n_samples :value: 0 .. py:attribute:: retries :value: 0 .. py:attribute:: problem .. py:attribute:: fwd_idx .. py:attribute:: rev_idx .. py:attribute:: warmup :value: None .. py:attribute:: _seed .. py:method:: __build_problem() -> Problem Build the matrix representation of the sampling problem. :returns: The matrix representation in the form of a NamedTuple. :rtype: Problem .. py:method:: generate_fva_warmup() -> None Generate the warmup points for the sampler. Generates warmup points by setting each flux as the sole objective and minimizing/maximizing it. Also caches the projection of the warmup points into the nullspace for non-homogeneous problems (only if necessary). :raises ValueError: If flux cone contains a single point or the problem is inhomogeneous. .. py:method:: _reproject(p: numpy.ndarray) -> numpy.ndarray Reproject a point into the feasibility region. This function is guaranteed to return a new feasible point. However, no guarantee can be made in terms of proximity to the original point. :param p: The current sample point. :type p: numpy.array :returns: A new feasible point. If `p` is feasible, it will return `p`. :rtype: numpy.array .. py:method:: _random_point() -> numpy.ndarray Find an approximately random point in the flux cone. .. py:method:: _is_redundant(matrix: numpy.matrix, cutoff: Optional[float] = None) -> bool Identify redundant rows in a matrix that can be removed. .. py:method:: _bounds_dist(p: numpy.ndarray) -> numpy.ndarray Get the lower and upper bound distances. Negative is bad. .. py:method:: sample(n: int, fluxes: bool = True) -> pandas.DataFrame :abstractmethod: Abstract sampling function. Should be overwritten by child classes. :param n: The number of samples that are generated at once. :type n: int :param fluxes: Whether to return fluxes or the internal solver variables. If set to False, will return a variable for each forward and backward flux as well as all additional variables you might have defined in the model (default True). :type fluxes: bool, optional :returns: Returns a pandas DataFrame with `n` rows, each containing a flux sample. :rtype: pandas.DataFrame .. py:method:: batch(batch_size: int, batch_num: int, fluxes: bool = True) -> pandas.DataFrame Create a batch generator. This is useful to generate `batch_num` batches of `batch_size` samples each. :param batch_size: The number of samples contained in each batch. :type batch_size: int :param batch_num: The number of batches in the generator. :type batch_num: int :param fluxes: Whether to return fluxes or the internal solver variables. If set to False, will return a variable for each forward and backward flux as well as all additional variables you might have defined in the model (default True). :type fluxes: bool, optional :Yields: *pandas.DataFrame* -- A DataFrame with dimensions (batch_size x n_r) containing a valid flux sample for a total of n_r reactions (or variables if fluxes=False) in each row. .. py:method:: validate(samples: numpy.matrix) -> numpy.ndarray Validate a set of samples for equality and inequality feasibility. Can be used to check whether the generated samples and warmup points are feasible. :param samples: Must be of dimension (samples x n_reactions). Contains the samples to be validated. Samples must be from fluxes. :type samples: numpy.matrix :returns: A one-dimensional numpy array containing a code of 1 to 3 letters denoting the validation result: - 'v' means feasible in bounds and equality constraints - 'l' means a lower bound violation - 'u' means an upper bound validation - 'e' means and equality constraint violation :rtype: numpy.array :raises ValueError: If wrong number of columns.