17.1.1.6.1.3. cobra.sampling.hr_sampler

Provide the base class and associated functions for Hit-and-Run samplers.

17.1.1.6.1.3.1. Module Contents

17.1.1.6.1.3.1.1. Classes

HRSampler

The abstract base class for hit-and-run samplers.

17.1.1.6.1.3.1.2. Functions

shared_np_array(shape: Tuple[int, int], data: Optional[np.ndarray] = None, integer: bool = False) → np.ndarray

Create a new numpy array that resides in shared memory.

cobra.sampling.hr_sampler.logger[source]
cobra.sampling.hr_sampler.Problem[source]

Define the matrix representation of a sampling problem.

A named tuple consisting of 6 arrays, 1 matrix and 1 boolean.

cobra.sampling.hr_sampler.equalities

All equality constraints in the model.

Type

numpy.array

cobra.sampling.hr_sampler.b

The right side of the equality constraints.

Type

numpy.array

cobra.sampling.hr_sampler.inequalities

All inequality constraints in the model.

Type

numpy.array

cobra.sampling.hr_sampler.bounds

The lower and upper bounds for the inequality constraints.

Type

numpy.array

cobra.sampling.hr_sampler.variable_fixed

A boolean vector indicating whether the variable at that index is fixed i.e., whether variable.lower_bound == variable.upper_bound.

Type

numpy.array

cobra.sampling.hr_sampler.variable_bounds

The lower and upper bounds for the variables.

Type

numpy.array

cobra.sampling.hr_sampler.nullspace

A matrix containing the nullspace of the equality constraints. Each column is one basis vector.

Type

numpy.matrix

cobra.sampling.hr_sampler.homogeneous

Indicates whether the sampling problem is homogeneous, e.g. whether there exist no non-zero fixed variables or constraints.

Type

bool

cobra.sampling.hr_sampler.shared_np_array(shape: Tuple[int, int], data: Optional[np.ndarray] = None, integer: bool = False) → np.ndarray[source]

Create a new numpy array that resides in shared memory.

Parameters
  • shape (tuple of int) – The shape of the new array.

  • data (numpy.array, optional) – Data to copy to the new array. Has to have the same shape (default None).

  • integer (bool, optional) – Whether to use an integer array. By default, float array is used (default False).

Returns

The newly created shared numpy array.

Return type

numpy.array

Raises

ValueError – If the input data (if provided) size is not equal to the created array.

class cobra.sampling.hr_sampler.HRSampler(model: Model, thinning: int, nproj: Optional[int] = None, seed: Optional[int] = None, **kwargs)[source]

Bases: 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.

Parameters
  • model (cobra.Model) – The cobra model from which to generate samples.

  • thinning (int) – The thinning factor of the generated sampling chain. A thinning of 10 means samples are returned every 10 steps.

  • nproj (int > 0, optional) – 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).

  • seed (int > 0, optional) – Sets the random number seed. Initialized to the current time stamp if None (default None).

feasibility_tol

The tolerance used for checking equalities feasibility.

Type

float

bounds_tol

The tolerance used for checking bounds feasibility.

Type

float

n_samples

The total number of samples that have been generated by this sampler instance.

Type

int

retries

The overall of sampling retries the sampler has observed. Larger values indicate numerical instabilities.

Type

int

problem

A NamedTuple whose attributes define the entire sampling problem in matrix form.

Type

Problem

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

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

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

__build_problem(self) → Problem[source]

Build the matrix representation of the sampling problem.

Returns

The matrix representation in the form of a NamedTuple.

Return type

Problem

generate_fva_warmup(self) → None[source]

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.

_reproject(self, p: np.ndarray) → np.ndarray[source]

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.

Parameters

p (numpy.array) – The current sample point.

Returns

A new feasible point. If p is feasible, it will return p.

Return type

numpy.array

_random_point(self) → np.ndarray[source]

Find an approximately random point in the flux cone.

_is_redundant(self, matrix: np.matrix, cutoff: Optional[float] = None) → bool[source]

Identify redundant rows in a matrix that can be removed.

_bounds_dist(self, p: np.ndarray) → np.ndarray[source]

Get the lower and upper bound distances. Negative is bad.

abstract sample(self, n: int, fluxes: bool = True) → pd.DataFrame[source]

Abstract sampling function.

Should be overwritten by child classes.

Parameters
  • n (int) – The number of samples that are generated at once.

  • fluxes (bool, optional) – 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).

Returns

Returns a pandas DataFrame with n rows, each containing a flux sample.

Return type

pandas.DataFrame

batch(self, batch_size: int, batch_num: int, fluxes: bool = True) → pd.DataFrame[source]

Create a batch generator.

This is useful to generate batch_num batches of batch_size samples each.

Parameters
  • batch_size (int) – The number of samples contained in each batch.

  • batch_num (int) – The number of batches in the generator.

  • fluxes (bool, optional) – 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).

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.

validate(self, samples: np.matrix) → np.ndarray[source]

Validate a set of samples for equality and inequality feasibility.

Can be used to check whether the generated samples and warmup points are feasible.

Parameters

samples (numpy.matrix) – Must be of dimension (samples x n_reactions). Contains the samples to be validated. Samples must be from fluxes.

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 a lower bound validation - ‘e’ means and equality constraint violation

Return type

numpy.array

Raises

ValueError – If wrong number of columns.