pypesto.ensemble

Ensemble

class pypesto.ensemble.Ensemble[source]

Bases: object

An ensemble is a wrapper around a numpy array.

It comes with some convenience functionality: It allows to map parameter values via identifiers to the correct parameters, it allows to compute summaries of the parameter vectors (mean, standard deviation, median, percentiles) more easily, and it can store predictions made by pyPESTO, such that the parameter ensemble and the predictions are linked to each other.

__init__(x_vectors, x_names=None, vector_tags=None, ensemble_type=None, predictions=None, lower_bound=None, upper_bound=None)[source]

Initialize.

Parameters:
  • x_vectors (ndarray) – parameter vectors of the ensemble, in the format n_parameter x n_vectors

  • x_names (Sequence[str]) – Names or identifiers of the parameters

  • vector_tags (Sequence[tuple[int, int]]) – Additional tag, which adds information about the parameter vectors. For example, (optimization_run, optimization_step) if the ensemble is created from an optimization result or history (see from_optimization_endpoints(), from_optimization_history()).

  • ensemble_type (EnsembleType) – Type of ensemble: EnsembleType.ensemble (default), EnsembleType.sample, or EnsembleType.unprocessed_chain. Samples are meant to be representative, ensembles can be any ensemble of parameters, and unprocessed chains still have burn-ins.

  • predictions (Sequence[EnsemblePrediction]) – List of EnsemblePrediction objects.

  • lower_bound (ndarray) – Array of potential lower bounds for the parameters.

  • upper_bound (ndarray) – Array of potential upper bounds for the parameters.

check_identifiability()[source]

Check identifiability of ensemble.

Use ensemble mean and standard deviation to assess (in a rudimentary way) whether parameters are identifiable. Returns a dataframe with tuples, which specify whether the lower and the upper bounds are violated.

Return type:

DataFrame

Returns:

parameter_identifiability – DataFrame indicating parameter identifiability based on mean plus/minus standard deviations and parameter bounds

compute_summary(percentiles_list=(5, 20, 80, 95))[source]

Compute summary for the parameters of the ensemble.

Summary includes the mean, the median, the standard deviation and possibly percentiles. Those summary results are added as a data member to the EnsemblePrediction object.

Parameters:

percentiles_list (Sequence[int]) – List or tuple of percent numbers for the percentiles

Return type:

dict[str, array]

Returns:

Dict with mean, std, median, and percentiles of parameter vectors

static from_optimization_endpoints(result, rel_cutoff=None, max_size=inf, percentile=None, **kwargs)[source]

Construct an ensemble from an optimization result.

Parameters:
  • result (Result) – A pyPESTO result that contains an optimization result.

  • rel_cutoff (float) – Relative cutoff. Exclude parameter vectors, for which the objective value difference to the best vector is greater than cutoff, i.e. include all vectors such that fval(vector) <= fval(opt_vector) + rel_cutoff.

  • max_size (int) – The maximum size the ensemble should be.

  • percentile (float) – Percentile of a chi^2 distribution. Used to determine the cutoff value.

Return type:

Ensemble

Returns:

The ensemble.

static from_optimization_history(result, rel_cutoff=None, max_size=inf, max_per_start=inf, distribute=True, percentile=None, **kwargs)[source]

Construct an ensemble from the history of an optimization.

Parameters:
  • result (Result) – A pyPESTO result that contains an optimization result with history recorded.

  • rel_cutoff (float) – Relative cutoff. Exclude parameter vectors, for which the objective value difference to the best vector is greater than cutoff, i.e. include all vectors such that fval(vector) <= fval(opt_vector) + rel_cutoff.

  • max_size (int) – The maximum size the ensemble should be.

  • max_per_start (int) – The maximum number of vectors to be included from a single optimization start.

  • distribute (bool) – Boolean flag, whether the best (False) values from the start should be taken or whether the indices should be more evenly distributed.

  • percentile (float) – Percentile of a chi^2 distribution. Used to determine the cutoff value.

Return type:

Ensemble

Returns:

The ensemble.

static from_sample(result, remove_burn_in=True, chain_slice=None, x_names=None, lower_bound=None, upper_bound=None, **kwargs)[source]

Construct an ensemble from a sample.

Parameters:
  • result (Result) – A pyPESTO result that contains a sample result.

  • remove_burn_in (bool) – Exclude parameter vectors from the ensemble if they are in the “burn-in”.

  • chain_slice (slice) – Subset the chain with a slice. Any “burn-in” removal occurs first.

  • x_names (Sequence[str]) – Names or identifiers of the parameters

  • lower_bound (ndarray) – array of potential lower bounds for the parameters

  • upper_bound (ndarray) – array of potential upper bounds for the parameters

Return type:

Ensemble

Returns:

The ensemble.

predict(predictor, prediction_id=None, sensi_orders=(0,), default_value=None, mode='mode_fun', include_llh_weights=False, include_sigmay=False, engine=None, progress_bar=None)[source]

Run predictions for a full ensemble.

User needs to hand over a predictor function and settings, then all results are grouped as EnsemblePrediction for the whole ensemble.

Parameters:
  • predictor (Callable) – Prediction function, e.g., an AmiciPredictor

  • prediction_id (str) – Identifier for the predictions

  • sensi_orders (tuple) – Specifies which sensitivities to compute, e.g. (0,1) -> fval, grad

  • default_value (float) – If parameters are needed in the mapping, which are not found in the parameter source, it can make sense to fill them up with this default value (e.g. np.nan) in some cases (to be used with caution though).

  • mode (Literal['mode_fun', 'mode_res']) – Whether to compute function values or residuals.

  • include_llh_weights (bool) – Whether to include weights in the output of the predictor.

  • include_sigmay (bool) – Whether to include standard deviations in the output of the predictor.

  • engine (Engine) – Parallelization engine. Defaults to sequential execution on a SingleCoreEngine.

  • progress_bar (bool) – Whether to display a progress bar.

Return type:

EnsemblePrediction

Returns:

The prediction of the ensemble.

class pypesto.ensemble.EnsemblePrediction[source]

Bases: object

Class of ensemble prediction.

An ensemble prediction consists of an ensemble, i.e., a set of parameter vectors and their identifiers such as a sample, and a prediction function. It can be attached to an ensemble-type object.

__init__(predictor=None, prediction_id=None, prediction_results=None, lower_bound=None, upper_bound=None)[source]

Initialize.

Parameters:
  • predictor (Optional[Callable[[Sequence], PredictionResult]]) – Prediction function, e.g., an AmiciPredictor, which takes a parameter vector as input and outputs a PredictionResult object

  • prediction_id (str) – Identifier for the predictions

  • prediction_results (Sequence[PredictionResult]) – List of Prediction results

  • lower_bound (Sequence[ndarray]) – Array of potential lower bounds for the predictions, should have the same shape as the output of the predictions, i.e., a list of numpy array (one list entry per condition), with the arrays having the shape of n_timepoints x n_outputs for each condition.

  • upper_bound (Sequence[ndarray]) – array of potential upper bounds for the parameters

compute_chi2(amici_objective)[source]

Compute the chi^2 error of the weighted mean trajectory.

Parameters:

amici_objective (AmiciObjective) – The objective function of the model, the parameter ensemble was created from.

Return type:

float

Returns:

The chi^2 error.

compute_summary(percentiles_list=(5, 20, 80, 95), weighting=False, compute_weighted_sigma=False)[source]

Compute summary from the ensemble prediction results.

Summary includes the mean, the median, the standard deviation and possibly percentiles. Those summary results are added as a data member to the EnsemblePrediction object.

Parameters:
  • percentiles_list (Sequence[int]) – List or tuple of percent numbers for the percentiles

  • weighting (bool) – Whether weights should be used for trajectory.

  • compute_weighted_sigma (bool) – Whether weighted standard deviation of the ensemble mean trajectory should be computed. Defaults to False.

Return type:

dict

Returns:

  • dictionary of predictions results with the keys mean, std, median,

  • percentiles, …

condense_to_arrays()[source]

Add prediction result to EnsemblePrediction object.

Reshape the prediction results to an array and add them as a member to the EnsemblePrediction objects. It’s meant to be used only if all conditions of a prediction have the same observables, as this is often the case for large-scale data sets taken from online databases or similar.

pypesto.ensemble.get_covariance_matrix_parameters(ens)[source]

Compute the covariance of ensemble parameters.

Parameters:

ens (Ensemble) – Ensemble object containing a set of parameter vectors

Return type:

ndarray

Returns:

covariance_matrix – covariance matrix of ensemble parameters

pypesto.ensemble.get_covariance_matrix_predictions(ens, prediction_index=0)[source]

Compute the covariance of ensemble predictions.

Parameters:
  • ens (Union[Ensemble, EnsemblePrediction]) – Ensemble object containing a set of parameter vectors and a set of predictions or EnsemblePrediction object containing only predictions

  • prediction_index (int) – index telling which prediction from the list should be analyzed

Return type:

ndarray

Returns:

covariance_matrix – covariance matrix of ensemble predictions

pypesto.ensemble.get_pca_representation_parameters(ens, n_components=2, rescale_data=True, rescaler=None)[source]

PCA of parameter ensemble.

Compute the representation with reduced dimensionality via principal component analysis (with a given number of principal components) of the parameter ensemble.

Parameters:
  • ens (Ensemble) – Ensemble objects containing a set of parameter vectors

  • n_components (int) – number of components for the dimension reduction

  • rescale_data (bool) – flag indicating whether the principal components should be rescaled using a rescaler function (e.g., an arcsinh function)

  • rescaler (Optional[Callable]) – callable function to rescale the output of the PCA (defaults to numpy.arcsinh)

Return type:

Tuple

Returns:

  • principal_components – principal components of the parameter vector ensemble

  • pca_object – returned fitted pca object from sklearn.decomposition.PCA()

pypesto.ensemble.get_pca_representation_predictions(ens, prediction_index=0, n_components=2, rescale_data=True, rescaler=None)[source]

PCA of ensemble prediction.

Compute the representation with reduced dimensionality via principal component analysis (with a given number of principal components) of the ensemble prediction.

Parameters:
  • ens (Union[Ensemble, EnsemblePrediction]) – Ensemble objects containing a set of parameter vectors and a set of predictions or EnsemblePrediction object containing only predictions

  • prediction_index (int) – index telling which prediction from the list should be analyzed

  • n_components (int) – number of components for the dimension reduction

  • rescale_data (bool) – flag indicating whether the principal components should be rescaled using a rescaler function (e.g., an arcsinh function)

  • rescaler (Optional[Callable]) – callable function to rescale the output of the PCA (defaults to numpy.arcsinh)

Return type:

Tuple

Returns:

  • principal_components – principal components of the parameter vector ensemble

  • pca_object – returned fitted pca object from sklearn.decomposition.PCA()

pypesto.ensemble.get_percentile_label(percentile)[source]

Convert a percentile to a label.

Labels for percentiles are used at different locations (e.g. ensemble prediction code, and visualization code). This method ensures that the same percentile is labeled identically everywhere.

The percentile is rounded to two decimal places in the label representation if it is specified to more decimal places. This is for readability in plotting routines, and to avoid float to string conversion issues related to float precision.

Parameters:

percentile (Union[float, int, str]) – The percentile value that will be used to generate a label.

Return type:

str

Returns:

The label of the (possibly rounded) percentile.

pypesto.ensemble.get_spectral_decomposition_lowlevel(matrix, normalize=False, only_separable_directions=False, cutoff_absolute_separable=1e-16, cutoff_relative_separable=1e-16, only_identifiable_directions=False, cutoff_absolute_identifiable=1e-16, cutoff_relative_identifiable=1e-16)[source]

Compute the spectral decomposition of ensemble parameters or predictions.

Parameters:
  • matrix (ndarray) – symmetric matrix (typically a covariance matrix) of parameters or predictions

  • normalize (bool) – flag indicating whether the returned Eigenvalues should be normalized with respect to the largest Eigenvalue

  • only_separable_directions (bool) – return only separable directions according to cutoff_[absolute/relative]_separable

  • cutoff_absolute_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff (only applied when only_separable_directions is True)

  • cutoff_relative_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff, when rescaled with the largest eigenvalue (only applied when only_separable_directions is True)

  • only_identifiable_directions (bool) – return only identifiable directions according to cutoff_[absolute/relative]_identifiable

  • cutoff_absolute_identifiable (float) – Consider only low eigenvalues of the covariance matrix with inverses above of this cutoff (only applied when only_identifiable_directions is True)

  • cutoff_relative_identifiable (float) – Consider only low eigenvalues of the covariance matrix when rescaled with the largest eigenvalue with inverses above of this cutoff (only applied when only_identifiable_directions is True)

Return type:

Tuple[ndarray, ndarray]

Returns:

  • eigenvalues – Eigenvalues of the covariance matrix

  • eigenvectors – Eigenvectors of the covariance matrix

pypesto.ensemble.get_spectral_decomposition_parameters(ens, normalize=False, only_separable_directions=False, cutoff_absolute_separable=1e-16, cutoff_relative_separable=1e-16, only_identifiable_directions=False, cutoff_absolute_identifiable=1e-16, cutoff_relative_identifiable=1e-16)[source]

Compute the spectral decomposition of ensemble parameters.

Parameters:
  • ens (Ensemble) – Ensemble object containing a set of parameter vectors

  • normalize (bool) – flag indicating whether the returned Eigenvalues should be normalized with respect to the largest Eigenvalue

  • only_separable_directions (bool) – return only separable directions according to cutoff_[absolute/relative]_separable

  • cutoff_absolute_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff (only applied when only_separable_directions is True)

  • cutoff_relative_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff, when rescaled with the largest eigenvalue (only applied when only_separable_directions is True)

  • only_identifiable_directions (bool) – return only identifiable directions according to cutoff_[absolute/relative]_identifiable

  • cutoff_absolute_identifiable (float) – Consider only low eigenvalues of the covariance matrix with inverses above of this cutoff (only applied when only_identifiable_directions is True)

  • cutoff_relative_identifiable (float) – Consider only low eigenvalues of the covariance matrix when rescaled with the largest eigenvalue with inverses above of this cutoff (only applied when only_identifiable_directions is True)

Return type:

Tuple[ndarray, ndarray]

Returns:

  • eigenvalues – Eigenvalues of the covariance matrix

  • eigenvectors – Eigenvectors of the covariance matrix

pypesto.ensemble.get_spectral_decomposition_predictions(ens, normalize=False, only_separable_directions=False, cutoff_absolute_separable=1e-16, cutoff_relative_separable=1e-16, only_identifiable_directions=False, cutoff_absolute_identifiable=1e-16, cutoff_relative_identifiable=1e-16)[source]

Compute the spectral decomposition of ensemble predictions.

Parameters:
  • ens (Ensemble) – Ensemble object containing a set of parameter vectors and a set of predictions or EnsemblePrediction object containing only predictions

  • normalize (bool) – flag indicating whether the returned Eigenvalues should be normalized with respect to the largest Eigenvalue

  • only_separable_directions (bool) – return only separable directions according to cutoff_[absolute/relative]_separable

  • cutoff_absolute_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff (only applied when only_separable_directions is True)

  • cutoff_relative_separable (float) – Consider only eigenvalues of the covariance matrix above this cutoff, when rescaled with the largest eigenvalue (only applied when only_separable_directions is True)

  • only_identifiable_directions (bool) – return only identifiable directions according to cutoff_[absolute/relative]_identifiable

  • cutoff_absolute_identifiable (float) – Consider only low eigenvalues of the covariance matrix with inverses above of this cutoff (only applied when only_identifiable_directions is True)

  • cutoff_relative_identifiable (float) – Consider only low eigenvalues of the covariance matrix when rescaled with the largest eigenvalue with inverses above of this cutoff (only applied when only_identifiable_directions is True)

Return type:

Tuple[ndarray, ndarray]

Returns:

  • eigenvalues – Eigenvalues of the covariance matrix

  • eigenvectors – Eigenvectors of the covariance matrix

pypesto.ensemble.get_umap_representation_parameters(ens, n_components=2, normalize_data=False, **kwargs)[source]

UMAP of parameter ensemble.

Compute the representation with reduced dimensionality via umap (with a given number of umap components) of the parameter ensemble. Allows to pass on additional keyword arguments to the umap routine.

Parameters:
  • ens (Ensemble) – Ensemble objects containing a set of parameter vectors

  • n_components (int) – number of components for the dimension reduction

  • normalize_data (bool) – flag indicating whether the parameter ensemble should be rescaled with mean and standard deviation

Return type:

Tuple

Returns:

  • umap_components – first components of the umap embedding

  • umap_object – returned fitted umap object from umap.UMAP()

pypesto.ensemble.get_umap_representation_predictions(ens, prediction_index=0, n_components=2, normalize_data=False, **kwargs)[source]

UMAP of ensemble prediction.

Compute the representation with reduced dimensionality via umap (with a given number of umap components) of the ensemble predictions. Allows to pass on additional keyword arguments to the umap routine.

Parameters:
  • ens (Union[Ensemble, EnsemblePrediction]) – Ensemble objects containing a set of parameter vectors and a set of predictions or EnsemblePrediction object containing only predictions

  • prediction_index (int) – index telling which prediction from the list should be analyzed

  • n_components (int) – number of components for the dimension reduction

  • normalize_data (bool) – flag indicating whether the parameter ensemble should be rescaled with mean and standard deviation

Return type:

Tuple

Returns:

  • umap_components – first components of the umap embedding

  • umap_object – returned fitted umap object from umap.UMAP()

pypesto.ensemble.read_ensemble_prediction_from_h5(predictor, input_file)[source]

Read an ensemble prediction from an HDF5 File.

Parameters:
pypesto.ensemble.read_from_csv(path, sep='\\t', index_col=0, headline_parser=None, ensemble_type=None, lower_bound=None, upper_bound=None)[source]

Create an ensemble from a csv file.

Parameters:
  • path (str) – path to csv file to read in parameter ensemble

  • sep (str) – separator in csv file

  • index_col (int) – index column in csv file

  • headline_parser (Callable) – A function which reads in the headline of the csv file and converts it into vector_tags (see constructor of Ensemble for more details)

  • ensemble_type (EnsembleType) – Ensemble type: representative sample or random ensemble

  • lower_bound (ndarray) – array of potential lower bounds for the parameters

  • upper_bound (ndarray) – array of potential upper bounds for the parameters

Returns:

result – Ensemble object of parameter vectors

pypesto.ensemble.read_from_df(dataframe, headline_parser=None, ensemble_type=None, lower_bound=None, upper_bound=None)[source]

Create an ensemble from a csv file.

Parameters:
  • dataframe (DataFrame) – pandas.DataFrame to read in parameter ensemble

  • headline_parser (Callable) – A function which reads in the headline of the csv file and converts it into vector_tags (see constructor of Ensemble for more details)

  • ensemble_type (EnsembleType) – Ensemble type: representative sample or random ensemble

  • lower_bound (ndarray) – array of potential lower bounds for the parameters

  • upper_bound (ndarray) – array of potential upper bounds for the parameters

Returns:

result – Ensemble object of parameter vectors

pypesto.ensemble.write_ensemble_prediction_to_h5(ensemble_prediction, output_file, base_path=None)[source]

Write an EnsemblePrediction to hdf5.

Parameters:
  • ensemble_prediction (EnsemblePrediction) – The prediciton to be saved.

  • output_file (str) – The filename of the hdf5 file.

  • base_path (str) – An optional filepath where the file should be saved to.