cvi package

cvi.CviBase module

This module contains basic classes and functions.

class cvi.CviBase.Manager(*args, **kwargs)

Bases: BaseManager

Class to connect to the CVA C++ core and manage models. The optional parameters are:

with_flask: If you want to use user models with self implemented modeling algorithms, the package needs to start a flask service. Alternatively, you can start the service later with start_model_service().
flask_port: This is the port used with the flask service for user models. Default is 5000.

available_model_types(): Get the list of available model types.

compare_models(models)

Compare matching models.

For each group of matching models (same input variables and same output variable) a comparison is performed. The results for one group contains the winner (best model), a list of how many times a model won against another and a matrix for pairwise comparison. A -1 means row lost against column, 0 no significant difference, 1 row won against column.

Parameters:: models – List of models to compare.
Returns:: A list of comparison results (see cvi.Structures.CvaModelCompare).

create_design_of_experiments()

Create a new design of experiments object.

Returns:: New design of experiments object.

create_ensemble_model(models, predict_mode='mean_predict')

Create an ensemble model grouping a set of models.

All models must have been fitted before and must be valid. Also, all models must have the same input variable set and the same output variable.

Parameters:

models – A list of trained and valid models.
predict_mode – The mode of prediction. Possible values: mean_predict, mean_weighted_predict, mean_exp_weighted_predict, best_predict. Default value is mean_predict.

Returns:

The ensemble model.

create_model(model_type)

Create an empty model of the given type.

Parameters:: model_type – One of the available model types (get list with available_model_types()).
Returns:: Model with default model and task parameters.

create_optimization()

Create a new optimization object.

Returns:: New optimization object.

create_parallel_tasks(model_types=None, input_variable_names=[], output_variable_names=None, df=None, check_path=None, check_type='pickle', models_dict=None)

Create wrapper structures for fit tasks used for parallelization.

There are two ways creating the tasks:

A list of model types and a list of output_variable_names is given. In this case the function creates tasks for all combinations of model type / output variable name. This does not work for user models because a wrapper object is needed.
A dictionary of output variable names -> list of models is given. In this case the models have been created by the user before. This can be used with any model type.

Use cvi.CviBase.Manager.available_model_types() to get the names of model types available in the CVI core library.

Parameters:

model_types (List[str]) – List of model types (one of cvi.CviBase.Manager.available_model_types()).
input_variable_names (List[str]) – List of input variable names, always needed.
output_variable_names (List[str]) – List of output variable names.
df (DataFrame) – Data frame with the learn data, always needed.
check_path (str) – If a path is given, the models for each task a stored there as a check point. This implies, that the path is reachable from all clients. The name of the files is composed if the output variable name and the model type.
check_type (str) – The check type can be pickle or xml. It is used when a check path is given and determines the type of file stored after completing a task.
models_dict (Dict[str, List[cvi.Models.Model]]) – A dictionary with output variable names as keys and lists of model objects as values.

Raises:

CvaException – if unable to create the tasks.

Returns:

A list of task wrappers.

Return type:

List[cvi.Structures.CvaParallelTask]

create_user_model(user_model)

Create a user model.

Parameters:: user_model – Wrapper object for the user implementation of a modeling algorithm.
Returns:: Model with a user implementation of a modeling algorithm.
Raises:: CvaException – if the pickle does not contain a single model.

exit(): Disconnect from core and release license

import_model(model_file)

Import a model from disk using the CVI xml format.

Parameters:: model_file – The name of the model file.
Returns:: Model created from the CVI xml export file.

init(): Reconnect to core and block license

load_design_of_experiments(pickle_file)

Load a design of experiments from a pickle file.

Parameters:: pickle_file – The name of the pickle file
Returns:: The unpickled design of experiments.
Raises:: CvaException – if the pickle could not be loaded.

load_model(pickle_file)

Load a model from a pickle file.

Parameters:: pickle_file – The name of the pickle file.
Returns:: The unpickled model.
Raises:: CvaException – if the pickle does not contain a single model.

load_optimization(pickle_file)

Load an optimization from a pickle file.

Parameters:: pickle_file – The name of the pickle file.
Returns:: The unpickled optimization.
Raises:: CvaException – if the pickle could not be loaded.

start_model_service(flask_port=5000)

Start a flask service enabling the usage of user models.

Parameters:: flask_port – The port for the flask service. The default is 5000.

class cvi.CviBase.PredictManager(*args, **kwargs)

Bases: InternalPredictManager

Class to connect to the CVI C++ core and use the predict capability of models.

Hint

Models connected to a predict manager can only use the predict function, but do not require a connection a license manager.

import_model(model_file)

Import a model from disk using the CVI xml format.

Parameters:: model_file – The name of the model file.
Returns:: Model created from the CVI xml export file.

load_model(pickle_file)

Load a model from a pickle file.

Parameters:: pickle_file – The name of the pickle file
Returns:: The unpickled model.
Raises:: CvaException – if the pickle does not contain a single model.

cvi.CviBase.html_help(): Open the html help in the default browser

cvi.CviBase.parallel_fit(parallel_task)

Callback function for parallel fitting models.

This callback function can be used to fit models in parallel. The code shows how to use this for example with joblib. First initialize with the Rosenbrock example.

from cvi import CviBase, Examples
from joblib import Parallel, delayed

manager = CviBase.Manager()
model_types = manager.available_model_types()

example = Examples.example_rosenbrock()
input_variable_names = example['input_variable_names']
output_variable_name = example['output_variable_names'][0]

Next, you create the modeling tasks.

model_tasks = manager.create_parallel_tasks(model_types, input_variable_names, [output_variable_name], example['df'])

You need to adjust a parameter for the Rosenbrock example.

model = [t.model for t in model_tasks if t.model.get_model_type()=='random_forest'][0]
model.get_fit_task().get_model_parameters()['mtry'].set_value(2)

Now use this the joblib parallel. You need to use multi-processing not multi-threading.

models = Parallel(n_jobs=4)(delayed(CviBase.parallel_fit)(t) for t in model_tasks)
[m.connect(manager) for m in models]

Note, that you need to connect the models after fitting to a manager to use them.

Parameters:: parallel_task – Information needed to fit a model. Must be of type cvi.Structures.CvaParallelTask and is best created with create_parallel_tasks().

cvi.CviBase.parallel_predict(models, df)

Callback function for parallel model predictions.

This callback function can be used to predict in parallel. The code shows how to use this for example with joblib.

Parameters:

models – List of successfully fitted models.
df – pandas.DataFrame with samples to predict.

Returns:

pandas.DataFrame with predictions.

cvi.DOE module

class cvi.DOE.DesignOfExperiments

Bases: object

The design of experiments class contains all functions to create a design of experiments.

To define a design of experiments input variables must be set and the algorithm needs to be parameterized. Optionally, restrictions can be added.

add_restriction(name, cmp, crit)

Adds a restriction function to the design of experiments.

Parameters:

name (str) – The name of the restriction. The name is also used as an identifier (column name) with evaluation function.
cmp (str) – The comparator, one of: ‘<’, ‘<=’, ‘>’, ‘>=’
crit (float) – Constant value for comparison with the return value of the function.

Raises:

CvaException – if the name is not unique or the comparator is unknown.

add_variable(name, lower_bound=0.0, upper_bound=0.0, vartype='real', class_names=[])

Adds a variable to the search space of this design of experiments.

Parameters:

name (str) – The name of the variable.
lower_bound (float) – The lower bound for a real valued variables.
upper_bound (float) – The upper bound for a real valued variables.
vartype (str) – The type of the variable, can be ‘real’ or ‘class’. ‘real’ needs bounds, ‘class’ needs a list of class names.
class_names (List[str]) – The names of the classes used as values for this variable.

Raises:

CvaException – if name is not a unique identifier.

connect(manager=None)

Connect the design of experiments to an existing CVA manager. If manager is None, an already initialized manager is looked up.

Parameters:: manager (cva.Base.Manager) – The CVA manager.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

create_design_of_experiments()

Create the samples and return the design of experiments as a pandas.DataFrame.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.
Returns:: pandas.DataFrame containing the design of experiments.
Return type:: DataFrame

create_multiple_design_of_experiments(cnt)

Create multiple sample sets running the algorithm multiple times and return the designs of experiments as a concatenated pandas.DataFrame. For deterministic algorithms, like Sobol or factorial designs, only one design of experiment is returned.

Parameters:: cnt (int) – Number of repetitions.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.
Returns:: pandas.DataFrame containing the design of experiments with an additional column with the iteration index.
Return type:: DataFrame

evaluate(input_df)

Evaluates all restrictions and return results in a single data frame.

Parameters:: input_df (DataFrame) – pandas.DataFrame containing values for all input variables.
Returns:: pandas.DataFrame containing values for all restrictions.
Return type:: DataFrame

get_doe()

Returns the created design of experiments as a pandas.DataFrame.

Raises:: CvaException – if no design has been created yet.
Returns:: pandas.DataFrame containing the design of experiments.
Return type:: DataFrame

get_model()

Return the model used for adaptive modeling design of experiments.

Returns:: A CVA model.
Return type:: cva.Models.Model

get_models()

Return the model list used for adaptive modeling design of experiments.

Returns:: The CVA model list.
Return type:: List[‘cva.Models.Model’]

get_parameters()

Returns all parameters of the design of experiments.

Returns:: Dictionary {parameter name, parameter} used by this design of experiments.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

get_restriction_names()

Get the names of the restrictions defined for this design of experiments.

Returns:: The names of the restrictions as list of strings.
Return type:: List[str]

get_restrictions()

Returns all restrictions defined for this design of experiments.

Returns:: The list of restrictions.
Return type:: List[‘cva.Structures.CvaRestriction’]

get_variable_names()

Returns the names all search space variables.

Returns:: The names of variables as list of string.
Return type:: List[str]

get_variables()

Returns all variable objects.

Returns:: The list of variables used in this design of experiments.
Return type:: List[‘cva.Structures.CvaVariable’]

remove_restriction(name)

Removes a restriction from this design of experiments.

Parameters:: name (str) – Name of the restriction to remove.

remove_variable(name)

Removes a variable from the design of experiments.

Parameters:: name (str) – Name of the variable to remove.

set_evaluation_function(evaluation_function)

The evaluation function must accept a pandas.DataFrame as input parameter and return another DateFrame. The returned pandas.DataFrame must contain all restrictions as columns and the same number of rows as the input pandas.DataFrame. The most simple example for this would be to use the apply-function of a data frame and return its result:

return input_df.apply(row_function, axis=1).

Parameters:: evaluation_function (Callable[[DataFrame], DataFrame]) – A function with pandas.DataFrame as input and output. (evaluation_function: pandas.DataFrame -> pandas.DataFrame)

set_existing_samples(df)

Set an initial sample. This is only useful for space-filling designs.

Parameters:: df (DataFrame) – pandas.DataFrame containing samples.

set_model(model)

Set a model for adaptive modeling design of experiments.

Parameters:: model (cva.Models.Model) – A CVA model.

set_models(models)

Set a list of models used for adaptive modeling design of experiments.

Parameters:: models (List['cva.Models.Model']) – A CVA model list.

set_parameter(name, value)

Sets a design of experiments parameter. Parameter values will be stored and transferred to CVA as strings.

Parameters:

name (str) – The name of the parameter.
value (str) – The value of the parameter.

cvi.Examples module

cvi.Examples.data_artificial()

Creates an example data frame with information on inputs and outputs.

The example data has 14 input variables X01-X13 and XC. X01-X13 are real-valued variables all in the range from 0.0 to 1.0. XC is a class variable with to attributes ON and OFF. There are two output variables. Y is real-valued and YC is a class variable with five attributes A-E. There are also some missing values present.

Returns:: A dictionary containing the pandas.DataFrame (df), the input variable names (input_variable_names) and the output variable names (output_variable_names).
Return type:: DataFrame

cvi.Examples.data_rosenbrock(size=100)

Creates an example data frame with values for inputs and outputs.

The example data is generated by using the two dimensional Rosenbrock function

\[y = f(x_1 \cdots x_n) = \sum_{i=1}^{n-1} (100(x_i^2 - x_{i+1})^2 + (1-x_i)^2) \text{ with } n = 2\]

Parameters:: size (int) – Number of sample points.
Returns:: A dictionary containing the pandas.DataFrame (df), the input variable names (input_variable_names) and the output variable names (output_variable_names).
Return type:: Dict[str, object]

cvi.Examples.function_restriction(vector)

Very simple function to calculate a restriction value. Used in optimization example with

optimization.add_restriction('example_restriction', '>', 5.0)

meaning that the result of this function has to be > 5.0. Otherwise vector will not be a valid solution for the optimization.

Parameters:: vector (List[float]) – n-dimensional vector with n >= 2.
Returns:: Sum of first two entries.
Return type:: float

cvi.Examples.function_rosenbrock(vector)

Calculates the Rosenbrock function for an n-dimensional input vector.

Parameters:

vector (List[float]) – Vector of input values.

Returns:

\[y = f(x_1 \cdots x_n) = \sum_{i=1}^{n-1} (100(x_i^2 - x_{i+1})^2 + (1-x_i)^2)\]

Return type:

float

cvi.Examples.function_sphere(vector)

Calculates the sum of squares.

The n-dimensional sphere function:

\[y = f(x_1 \cdots x_n) = \sum_{i=1}^{n} x_i^2\]

Parameters:: vector (List[float]) – Vector of input values.
Returns:: Result of the n-dimensional sphere function (sum of squares).
Return type:: float

cvi.Examples.optimization_multi_objective_evaluation(dataFrame)

Applies the function function_sphere() and function_restriction() to a data frame.

A column with all output values will be added to the data frame. Returning a data frame which contains the output values only, would also work, provided that the order of rows is maintained.

The functions implementation is shown next:

def example_evaluation_function(dataFrame):
    f1 = []
    f2 = []
    for i in range(len(dataFrame)):
        row = dataFrame.iloc[i]
        v = [row.iloc[j] for j in range(len(row))]
        f1 = function_sphere(v)
        f2 = function_rosenbrocks(v)
    return pandas.DataFrame(data={'function_sphere': f1, 'function_restriction': f2})

Parameters:: dataFrame (DataFrame) – pandas.DataFrame with input values.
Returns:: pandas.DataFrame containing inputs, function_sphere() and function_restriction() results in new columns.
Return type:: DataFrame

cvi.Examples.optimization_single_objective_evaluation(dataFrame)

Applies the function function_sphere() and function_restriction() to a data frame.

A column with all output values will be added to the data frame. Returning a data frame which contains the output values only, would also work, provided that the order of rows is maintained.

The functions implementation is shown next:

def example_evaluation_function(dataFrame):
    f1 = []
    f2 = []
    for i in range(len(dataFrame)):
        row = dataFrame.iloc[i]
        v = [row.iloc[j] for j in range(len(row))]
        f1.append(function_sphere(v))
        f2.append(function_restriction(v))
    return pandas.DataFrame(data={'function_sphere': f1, 'function_restriction': f2})

Parameters:: dataFrame (DataFrame) – pandas.DataFrame with input values.
Returns:: pandas.DataFrame containing inputs, function_sphere() and function_restriction() results in new columns.
Return type:: DataFrame

cvi.Models module

class cvi.Models.EnsembleModel

Bases: object

Ensemble model class.

Hint

Model must be created using the function cva.Base.Manager.create_ensemble_model().

An ensemble model contains a list of pre-fitted models which are used to get better predictions. The models can be of different types or of the same type. There are currently four methods available to combine the predictions of the \(n\) models:

mean_predict (default): The mean of all predict values is calculated and returned.

\[y=\frac{\sum_{i=1}^{n} y_i}{n}\]

mean_weighted_predict: The predictions are weighted by their confidence and the mean weighted prediction is returned.

\[y=\frac{\sum_{i=1}^{n} y_i\cdot c_i}{\sum_{i=1}^{n} c_i}\]

mean_exp_weighted_predict: Before weighting the predictions, the predictions are sorted by the confidence and get a number by their position (first \(n\), second \(n-1\) … last \(1\)). The factors can be further altered by an exponential factor \(f\) (default: \(f=1\) see set_exp_weight_factor()).

\[y=\frac{\sum_{i=1}^{n} y_i\cdot c_i\cdot i^{f}}{\sum_{i=1}^{n} c_i} \text{ with } \forall c_i, c_j\in {c_1,...,c_n}:i<j\implies c_i<c_j\]

best_predict: Return the prediction with the highest confidence.

The predict mode can be set with set_predict_mode(). The ensemble model is a new model with all the dependent models integrated and thus the ensemble model can be saved and loaded independently.

connect(manager=None)

Connect the model to an existing CVA manager.

Parameters:: manager (cva.Base.Manager) – The CVA manager.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

create_data_frame(rows=None)

Create a data frame matching the names of the inputs and the output.

Parameters:: rows (int) – If rows is None an empty data frame is created. If rows is an integer, the data frame contains the corresponding number of rows pre-filled with NaNs.
Returns:: A data frame matching the model variables or None, if the model is not valid.
Return type:: DataFrame

delete()

Remove model from C++ core to free memory. Python object becomes invalid.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

export(model_file_name)

Save model to disk. The model is saved as a xml files suited to be used with any CVA tool.

Parameters:: model_file_name (str) – Name of the model file.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

fig_morris(df, figsize=(10, 10), markertextsize=10, titlesize=20, markersize=10, labelsize=15, ticksize=10, legendsize=10)

Create a standard deviation vs. mean scatter plot with colored areas for the results of Morris sensitivity analysis.

Hint

In order to create the plots, you need matplotlib.

Parameters:

df (pandas.DataFrame) – Data frame with the sensitivity values either generated with cva.Models.EnsembleModel.sensitivity()
figsize (Tuple[float, float]) – Size of the figure as used in matplotlib.subplots.
markertextsize (int) – Font size of the marker text.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

Returns:

Handle to a matplotlib figure.

Return type:

matplotlib.Figure

fig_scatter(df, figsize=(10, 10), titlesize=20, markersize=30, labelsize=15, ticksize=15, legendsize=15)

Create a prediction vs. original values scatter plot for the final model and the cross-validation.

Hint

In order to create the plots, you need matplotlib.

Parameters:

df (pandas.DataFrame) – Data frame with a original_values and predicted_values data frame.
figsize (Tuple[float, float]) – Size of the figure as used in matplotlib.subplots.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

Returns:

Handle to a matplotlib figure.

Return type:

matplotlib.Figure

get_confusion_matrix(df=None)

Create a list of the confusion matrices of each model.

Parameters:: df (DataFrame) – A data frame with a column “original_values” and a column “predicted_values”. If no data frame is given, the validation data frame is used.
Raises:: CvaException – if the model is not a classifier or one of the needed columns is missing or if the model has not been fitted.
Returns:: A list of data frames containing the confusion matrix of each model.
Return type:: List[DataFrame]

get_exp_weight_factor()

Get the factor for the exponential weighted predict mode of the ensemble model.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.
Returns:: The exponential weight factor.
Return type:: float

get_fit_info()

Get the qualities and the parameters used to fit the internal models.

Returns:: A list of objects with information on qualities, variable importance, variable sensitivity and more.
Return type:: List[‘cva.Structures.CvaFitTask’]

get_input_variable_class_names()

Get the names of the classes of the input variables.

Returns:: A dictionary with each class input variable name as key and a list of attached class names. None is returned, if the model has not been fitted.
Return type:: Dict[str, List[str]]

get_input_variable_names()

Get the names of the input variables.

Returns:: The list of input variable names or None, if the model has not been fitted.
Return type:: List[str]

get_invalid_reason()

Get the reason for a failed fit.

Returns:: List of reasons, if the model is not valid return the reason or ‘’ if the model is valid.
Return type:: List[str]

get_model_type()

Get the model type.

Returns:: Always ‘ensemble_model’.
Return type:: str

get_output_variable_class_names()

Get the names of the classes of the output variable.

Returns:: If the output is a class variable, a list of the class names is returned, else an empty list is returned. None is returned, if the model has not been fitted.
Return type:: List[str]

get_output_variable_name()

Get the name of the output variable.

Returns:: The name of the output variable or None, if the model has not been fitted.
Return type:: str

get_predict_mode()

Get the predict mode of the ensemble model.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.
Returns:: The predict mode. One of ‘mean_predict’, ‘mean_weighted_predict’, ‘mean_exp_weighted_predict’, ‘best_predict’.
Return type:: str

get_qualities()

Get the quality data frames (see cva.Structures.CvaModelInfo) of the internal models.

Raises:: CvaException – if the model has not been fitted.
Returns:: List of quality data frames.
Return type:: List[DataFrame]

get_validation_data_frame()

Get a list of data frames with comparison between original and predicted values for the internal validation for each model (see cva.Structures.CvaModelInfo).

Raises:: CvaException – if the model has not been fitted.
Returns:: Data frames with the comparison.
Return type:: List[DataFrame]

get_variable_importance()

Get the variable importance data frames (see cva.Structures.CvaModelInfo) of the internal models.

Returns:: A list of data frames with the input variable importance for each model.
Raises:: CvaException – if the model has not been fitted.
Return type:: List[DataFrame]

get_variable_sensitivity(sensitivity_types=['Sobol', 'Morris'])

Get the sensitivity in form of Sobol and/or Morris indices (see cva.Structures.CvaModelInfo) of the internal models.

Parameters:: sensitivity_types – The sensitivity types to include. The default is Sobol and Morris.
Raises:: CvaException – if the model has not been fitted.
Returns:: A list of data frames with the sensitivity for the input variables (Sobol index and total Sobol index and/or Morris values).
Return type:: List[DataFrame]

is_valid()

Check, if the model is valid.

Returns:: True, if all contained models are valid, otherwise False.
Return type:: bool

plot_morris(ax, df, markertextsize, titlesize, markersize, labelsize, ticksize, legendsize)

Add a standard deviation vs. mean scatter plot with colored areas for the results of Morris sensitivity analysis to an existing figure.

Hint

In order to create the plots, you need matplotlib.

Parameters:

ax (matplotlib.Axes) – Axis handle of a matplotlib figure.
df (pandas.DataFrame) – Data frame with the sensitivity values either generated with cva.Models.EnsembleModel.sensitivity()
markertextsize (int) – Font size of the marker text.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

plot_scatter(ax, df, titlesize, markersize, labelsize, ticksize, legendsize)

Add a prediction vs. original values scatter plot for the final model and the cross-validation to an existing figure.

Hint

In order to create the plots, you need matplotlib.

Parameters:

ax (matplotlib.Axes) – Axis handle of a matplotlib figure.
df (pandas.DataFrame) – Data frame with a original_values and predicted_values data frame.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

predict(df, confidence=True)

Predict values using new data.

The data frame needs to contain at least columns with names of the input variables. For more information on confidence see using models.

Parameters:

df – Data frame to predict.
confidence (bool) – If true, calculate the confidence values, else return a list with NaNs for the confidence

Returns:

A tuple of a List with the predicted values and a list of the confidence values or a tuple of (None, None), if the model is not valid. The confidence value is between one and zero, with one being the highest confidence.

Return type:

Tuple[List[float], List[float]]

sensitivity(box, sensitivity_types=['Sobol', 'Morris'])

Calculate variable sensitivity for a given sub-space.

Parameters:

box (Dict[str, object]) – A dictionary of the form variable -> [min, max] / variable -> labels defining the box.
sensitivity_type – The methods to be applied.

Returns:

A pandas.DataFrame with a row for each input variable containing the selected sensitivity values.

Return type:

DataFrame

set_exp_weight_factor(factor)

Set the factor for the exponential weighted predict mode of the ensemble model.

Parameters:: factor (float) – The exponential weight factor.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

set_predict_mode(predict_mode)

Set the predict mode of the ensemble model.

Parameters:: predict_mode (str) – The name of the predict mode. Possible values are mean_predict, mean_weighted_predict, mean_exp_weighted_predict, best_predict
Raises:: CvaException – if the predict mode is unknown.

class cvi.Models.Model

Bases: object

Model class.

Hint

Model is created using the function cva.Base.Manager.create_model().

connect(manager=None)

Connect the model to an existing CVA manager.

Parameters:: manager (cva.Base.Manager) – The CVA manager.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

create_data_frame(rows=None)

Create a data frame matching the names of the inputs and the output.

Parameters:: rows (int) – If rows is None an empty data frame is created. If rows is an integer, the data frame contains the corresponding number of rows pre-filled with NaNs.
Returns:: A data frame matching the model variables or None, if the model is not valid.
Return type:: DataFrame

delete()

Remove model from C++ core to free memory. Python object becomes invalid.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

export(model_file_name)

Save model to disk. The model is saved as a xml files suited to be used with any CVA tool.

Parameters:: model_file_name (str) – Name of the model file.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason or if the model has not been fitted.

fig_morris(df, figsize=(10, 10), markertextsize=10, titlesize=20, markersize=10, labelsize=15, ticksize=10, legendsize=10)

Create a standard deviation vs. mean scatter plot with colored areas for the results of Morris sensitivity analysis.

Hint

In order to create the plots, you need matplotlib.

Parameters:

df (pandas.DataFrame) – Data frame with the sensitivity values either generated with cva.Models.Model.get_variable_sensitivity() or cva.Models.Model.sensitivity()
figsize (Tuple[float, float]) – Size of the figure as used in matplotlib.subplots.
markertextsize (int) – Font size of the marker text.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

Returns:

Handle to a matplotlib figure.

Return type:

matplotlib.Figure

fig_scatter(df, figsize=(10, 10), titlesize=20, markersize=30, labelsize=15, ticksize=15, legendsize=15)

Create a prediction vs. original values scatter plot for the final model and the cross-validation.

Hint

In order to create the plots, you need matplotlib.

Parameters:

df (pandas.DataFrame) – Data frame with a original_values and predicted_values data frame.
figsize (Tuple[float, float]) – Size of the figure as used in matplotlib.subplots.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

Returns:

Handle to a matplotlib figure.

Return type:

matplotlib.Figure

fit(df, input_variable_names, output_variable_name)

Train the model using the model and task parameter set.

Parameters:

df (DataFrame) – Learn data as data frame.
input_variable_names (List[str]) – List of input variable names.
output_variable_name (str) – Name of the output variable.

Raises:

CvaException – if the core operation did not succeed. The exceptions contains the reason.

Returns:

True, if the model fit has been successful, else False.

Return type:

bool

get_confusion_matrix(df=None)

Get the confusion matrix for classification models.

Parameters:: df (DataFrame) – A data frame with a column “original_values” and a column “predicted_values”. If no data frame is given, the validation data frame is used.
Raises:: CvaException – if the model is not a classifier or one of the needed columns is missing or if the model has not been fitted.
Returns:: A data frame containing the confusion matrix.
Return type:: DataFrame

get_fit_info()

Get the qualities and the parameters used to fit the model. The parameters are the result of the hyperparameter optimization.

Returns:: Object with information on qualities, variable importance, variable sensitivity and more.
Return type:: cva.Structures.CvaModelInfo

get_fit_info_fit_task()

Get the task and model parameter used for fitting.

Raises:: CvaException – if the model has not been fitted.
Returns:: Object with the parameters used for fitting.
Return type:: cva.Structures.CvaFitTask

get_fit_info_model_parameter(name)

Get a model parameter used to fit the model by name.

Parameters:: name (str) – The name of the model parameter.
Raises:: CvaException – if the model has not been fitted.
Returns:: The model parameter object.
Return type:: cva.Structures.CvaModelParameter

get_fit_info_model_parameters()

Get the model parameters used to fit the model.

Raises:: CvaException – if the model has not been fitted.
Returns:: The model parameters.
Return type:: Dict[str, ‘cva.Structures.CvaModelParameter’]

get_fit_info_task_parameter(name)

Get a fit task parameter used to fit the model by name.

Parameters:: name (str) – The name of the task parameter.
Raises:: CvaException – if the model has not been fitted.
Returns:: The task parameter object.
Return type:: cva.Structures.CvaTaskParameter

get_fit_info_task_parameters()

Get the fit task parameters used to fit the model.

Raises:: CvaException – if the model has not been fitted.
Returns:: Dictionary {name, parameter}.
Return type:: Dict[str, ‘cva.Structures.CvaTaskParameter’]

get_fit_task()

Get the task and model parameter for fitting.

Returns:: The task and model parameters for fitting..
Return type:: cva.Structures.CvaFitTask

get_fit_task_model_parameter(name)

Get a model parameter by name from the fit info object.

Parameters:: name (str) – The name of the model parameter.
Returns:: The model parameter object.
Return type:: cva.Structures.CvaModelParameter

get_fit_task_model_parameter_value(name)

Get the value of a model parameter.

Parameters:: name (str) – The name of the model parameter.
Returns:: The model parameter object.
Return type:: object

get_fit_task_model_parameters()

Get the fit model parameters. :returns: The model parameters.

get_fit_task_parameter(name)

Get a task parameter by name from the fit info object.

Parameters:: name (str) – The name of the task parameter.
Returns:: The task parameter object.
Return type:: cva.Structures.CvaTaskParameter

get_fit_task_parameter_value(name)

Get the value of a task parameter.

Parameters:: name (str) – The name of the task parameter.
Returns:: The task parameter object.
Return type:: object

get_fit_task_parameters()

Get the fit task parameters. :returns: The task parameters.

get_input_variable_class_names()

Get the names of the classes of the input variables.

Returns:: A dictionary with each class input variable name as key and a list of attached class names. None is returned, if the model has not been fitted.
Return type:: Dict[str, List[str]]

get_input_variable_names()

Get the names of the input variables.

Returns:: The list of input variable names or None, if the model has not been fitted.
Return type:: List[str]

get_invalid_reason()

Get the reasons for a failed fit.

Returns:: List of reasons, if a model is not valid return the reason or ‘’ if the model is valid.
Return type:: List[str]

get_model_type()

Get the model type.

Returns:: The model type.
Return type:: str

get_output_variable_class_names()

Get the names of the classes of the output variable.

Returns:: If the output is a class variable, a list of the class names is returned, else an empty list is returned. None is returned, if the model has not been fitted.
Return type:: List[str]

get_output_variable_name()

Get the name of the output variable.

Returns:: The name of the output variable or None, if the model has not been fitted.
Return type:: str

get_qualities()

Get the quality data frame (see cva.Structures.CvaModelInfo).

Raises:: CvaException – if the model has not been fitted.
Returns:: The quality data frame.
Return type:: DataFrame

get_validation_data_frame()

Get the data frame with comparison between original and predicted values for the internal validation (see cva.Structures.CvaModelInfo).

Raises:: CvaException – if the model has not been fitted.
Returns:: Data frame with the comparison.
Return type:: DataFrame

get_variable_importance()

Get the variable importance data frame (see cva.Base.Structure.CvaModelInfo).

Raises:: CvaException – if the model has not been fitted.
Returns:: A data frame with the input variable importance.
Return type:: DataFrame

get_variable_sensitivity(sensitivity_types=['Sobol', 'Morris'])

Get the sensitivity in form of Sobol and/or Morris indices (see cva.Structures.CvaModelInfo).

Parameters:: sensitivity_types (List[str]) – The sensitivity types to include. The default is Sobol and Morris.
Raises:: CvaException – if the model has not been fitted.
Returns:: A data frame with the sensitivity for the input variables (Sobol index and total Sobol index and/or Morris values).
Return type:: DataFrame

is_valid()

Check, if the model is valid.

Returns:: True, if models has been fitted and is valid, otherwise False.
Return type:: bool

plot_morris(ax, df, markertextsize, titlesize, markersize, labelsize, ticksize, legendsize)

Add a standard deviation vs. mean scatter plot with colored areas for the results of Morris sensitivity analysis to an existing figure.

Hint

In order to create the plots, you need matplotlib.

Parameters:

ax (matplotlib.Axes) – Axis handle of a matplotlib figure.
df (pandas.DataFrame) – Data frame with the sensitivity values either generated with cva.Models.Model.get_variable_sensitivity() or cva.Models.Model.sensitivity()
markertextsize (int) – Font size of the marker text.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

plot_scatter(ax, df, titlesize, markersize, labelsize, ticksize, legendsize)

Add a prediction vs. original values scatter plot for the final model and the cross-validation to an existing figure.

Hint

In order to create the plots, you need matplotlib.

Parameters:

ax (matplotlib.Axes) – Axis handle of a matplotlib figure.
df (pandas.DataFrame) – Data frame with a original_values and predicted_values data frame.
titlesize (int) – Font size of the title.
markersize (int) – Size of the marker.
labelsize (int) – Font size of the x and y label.
ticksize (int) – Size of the x and y ticks.
legendsize (int) – Font size of text of the legend.

Raises:

CvaException – if the matplotlib package is not found.

predict(df, confidence=True)

Predict values using new data.

The data frame needs to contain at least columns with names of the input variables. For more information on confidence see using models.

Parameters:

df – Data frame to predict.
confidence (bool) – If true, calculate the confidence values, else return a list with NaNs for the confidence

Returns:

A tuple of a List with the predicted values and a list of the confidence values or a tuple of (None, None), if the model is not valid. The confidence value is between one and zero, with one being the highest confidence.

Return type:

Tuple[List[float], List[float]]

sensitivity(box, sensitivity_types=['Sobol', 'Morris'])

Calculate variable sensitivity for a given sub-space.

Parameters:

box (Dict[str, object]) – A dictionary of the form variable -> [min, max] / variable -> labels defining the box.
sensitivity_type – The methods to be applied.

Returns:

A pandas.DataFrame with a row for each input variable containing the selected sensitivity values.

Return type:

DataFrame

set_fit_task_model_parameter(parameter)

Add/replace a fit model parameter.

Parameters:

name – The name of the model parameter.
value – The new value for the parameter.

set_fit_task_model_parameter_value(name, value)

Set the value of a fit model parameter.

Parameters:

name (str) – The name of the model parameter.
value (object) – The new value for the parameter.

set_fit_task_model_parameters(parameters)

Set the fit model parameters.

Parameters:: parameters (List['cva.Structures.CvaModelParameter']) – The new parameters.

set_fit_task_parameter(parameter)

Add/replace a fit task parameter.

Parameters:

name – The name of the task parameter.
value – The new value for the parameter.

set_fit_task_parameter_value(name, value)

Set the value of a fit task parameter.

Parameters:

name (str) – The name of the task parameter.
value (object) – The new value for the parameter.

set_fit_task_parameters(parameters)

Set the fit task parameters.

Parameters:: parameters (List['cva.Structures.CvaTaskParameter']) – The new parameters.

set_model_parameter(name, value)

Set a model parameter of a fitted model by name.

Parameters:

name (str) – The name of the model parameter.
value (object) – New value of teh model parameter.

Raises:

CvaException – if the model has not been fitted or value is not accepted.

class cvi.Models.UserModelInterface(model)

Bases: object

Template class for building a user model. The user model class can be derived from this class. The actual implementation of the user algorithm must be given as a reference to the constructor and must work with pickle for storing/loading.

Hint

A user model is created using the function cva.Base.Manager.create_user_model() with an object implementing the function of this interface.

class UserModelInterface:
    '''
    Template class for building a user model. The user model class can be derived from this class. The actual implementation
    of the user algorithm must be given as a reference to the constructor and must work with pickle for storing/loading.

    .. hint:: A user model is created using the function :py:meth:`cva.Base.Manager.create_user_model` with an object implementing the function of this interface.

    .. code-block:: python
        :linenos:

        y, c = model.predict(df, confidence = False)
    '''

    def __init__(self, model) -> None:
        self.model = model

    def get_parameter_list(self, input_cnt) -> list:
        ''' This function should return the list of parameters / hyper-parameters which can be configured or optimized.

        Args:
            input_cnt: In order to properly initialize the parameters, the number of input variables is provided.

        Returns:
            A list of parameters of type :py:class:`cva.Base.Structures.CvaModelParameter`.
        '''
        return []

    def set_parameter_values(self, parameter_values) -> None:
        ''' This function changes the current parameter values.

        Args:
            parameter_values: A dictionary of name value pairs for the parameters to be changed.
        '''
        pass

    def fit(self, df, input_variable_names, output_variable_name) -> None:
        ''' The fit function should provide the actual training algorithm for the user model. The resulting model should be stored in self.model.

        Args:
            df: Learn data as data frame.
            input_variable_names: List of input variable names.
            output_variable_name: Name of the output variable.
        '''
        pass

    def predict(self, df, input_variable_names, output_variable_name):
        ''' Predict values using new data.

        Args:
            df: Data frame to predict.

        Returns:
            A pandas.DataFrame containing one column "output_variable_name" with predictions.
        '''
        pass

fit(df, input_variable_names, output_variable_name)

The fit function should provide the actual training algorithm for the user model. The resulting model should be stored in self.model.

Parameters:

df (DataFrame) – Learn data as data frame.
input_variable_names (List[str]) – List of input variable names.
output_variable_name (str) – Name of the output variable.

get_parameter_list(input_cnt)

This function should return the list of parameters / hyper-parameters which can be configured or optimized.

Parameters:: input_cnt (int) – In order to properly initialize the parameters, the number of input variables is provided.
Returns:: A list of parameters of type cva.Base.Structures.CvaModelParameter.
Return type:: List[‘cva.Structures.CvaModelParameter’]

predict(df, input_variable_names, output_variable_name)

Predict values using new data.

Parameters:: df (DataFrame) – Data frame to predict.
Returns:: A pandas.DataFrame containing one column “output_variable_name” with predictions.

set_parameter_values(parameter_values)

This function changes the current parameter values.

Parameters:: parameter_values (Dict[str, object]) – A dictionary of name value pairs for the parameters to be changed.

cvi.Optimizations module

class cvi.Optimizations.Optimization

Bases: object

The Optimization class contains all necessary methods to setup and start an optimization run.

Input variables, objective functions, and restriction functions can be added. Optimization parameters can be set, ‘start’ and ‘continue_run’ can be used to control to perform a single, or an extended optimization. get_results() returns the best solutions found. get_history() returns all created candidate solutions, including objective and restriction values and generation.

add_objective(name, obj_type='Minimize', obj_value=0.0)

Adds an objective to the optimization.

Parameters:

name (str) – The name of the objective, also the name for the data column.
obj_type (str) – The type of the objective, may be ‘Minimize’, ‘Maximize’, or ‘Value.
obj_value (float) – The target value to use, when obj_type is set to ‘Value’.

add_restriction(name, cmp, crit)

Add a restriction to the optimization.

Parameters:

name (str) – The (column) name.
cmp (str) – The comparator, one of: ‘<’, ‘<=’, ‘>’, ‘>=’
crit (float) – Constant value for comparison with the return value of the function.

Raises:

CvaException – if the name is not unique or the comparator is unknown.

add_variable(name, lower_bound=0.0, upper_bound=1.0, vartype='real', class_names=[], metric_values=[])

Add a design variable.

Parameters:

name (str) – The name of the variable.
lower_bound (float) – The lower bound for a real valued variables.
upper_bound (float) – The upper bound for a real valued variables.
vartype (str) – The type of the variable, can be ‘real’ or ‘class’. ‘real’ needs bounds, ‘class’ needs a list of class names.
class_names (List[str]) – The names of the classes if vartype is ‘class’.
metric_values (List[object]) – The ordered values if vartype is ‘metric’.

connect(manager=None)

Connect the optimization to an existing CVA manager.

Parameters:: manager (cva.Base.Manager) – The CVA manager.
Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.

continue_run(generations)

Continue the optimization process for the given number of generations.

Parameters:: generations (int) – number of generations to continue.
Returns:: pandas.DataFrame containing the optimization results.
Return type:: DataFrame

delete(): Clear the used memory and delete the results of the optimization.

evaluate(input_df)

Evaluates all fitness and restriction functions and return results in a single data frame.

Parameters:: input_df (DataFrame) – pandas.DataFrame containing values for all input variables.
Returns:: pandas.DataFrame containing values for all objectives and restrictions.
Return type:: DataFrame

get_history()

Returns the complete optimization history which contains all individuals that have been created in the process.

Returns:: Complete optimization history.
Return type:: DataFrame

get_initial_parents()

Get the data frame with initial parents.

Returns:: pandas.DataFrame with the initial parents if set, else None
Return type:: DataFrame

get_objective_names()

Get the names of the objectives of the optimization.

The names of the optimizations have to match the names of the columns in the data frame returned by evaluation function.

Returns:: The names of all objectives as list of strings.
Return type:: List[str]

get_objectives()

Get the objective of the optimization.

The names of the optimizations have to match the names of the columns in the data frame returned by evaluation function.

Returns:: The list of objectives.
Return type:: List[‘cva.Structures.CvaObjective’]

get_parameter(name)

Get an optimization parameter.

Returns:: Parameter object.
Return type:: cva.Structures.CvaParameter

get_parameter_value(name)

Get an optimization parameter value.

Returns:: Value of an optimization parameter.
Return type:: object

get_parameters()

Get the optimization parameters.

Returns:: Dictionary of parameters used by this optimization.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

get_progress_by_generation(generation)

Get the progress up to a certain generation. Only usefull for optimizations with more than one objective.

Parameters:: generation – Get the progress up to the generation.
Returns:: A tuple of a data frame with the Pareto front and the hypervolume of that Pareto front.
Return type:: Tuple[DataFrame, float]

get_refrence_point()

Get the reference point.

Returns:: The reference point.
Return type:: List[float]

get_restriction_names()

Get the names of the restrictions of the optimization.

The names of the restrictions have to match the names of the columns in the data frame returned by evaluation function.

Returns:: The names of the restrictions as list of strings.
Return type:: List[str]

get_restrictions()

Get the restrictions of the optimization.

The names of the restrictions have to match the names of the columns in the data frame returned by evaluation function.

Returns:: The list of restrictions.
Return type:: List[‘cva.Structures.CvaRestriction’]

get_result()

Returns the best individuals found in this optimization run.

This is the same result which is returned by the start method. Use get_result when you want to get the results of an optimization object that has finished. E.g. optimizations passed to other functions, loaded from hard disk, …

Returns:: The best solutions found by this optimization.
Return type:: DataFrame

get_status()

Get the status of the optimization.

get_variable_names()

Get the design variable names.

Returns:: The names of the design variables as list of strings.
Return type:: List[str]

get_variables()

Get the design variables.

Returns:: The list of design variables used in this optimization.
Return type:: List[‘cva.Structures.CvaVariable’]

hypervolume(reference_point=None, pareto_front=None)

Calculate the hypervolume of a Pareto front.

Parameters:

reference_point (List[float]) – The referencce point. If not set, the original reference point of the optimzation is used.
pareto_front (List[List[float]]) – The Pareto front. If not set, the result of the optimization is used.

Returns:

The hypervolume.

Return type:

float

remove_initial_parents(): Remove the initial parents and uses random initial parents instead.

remove_objective(name)

Removes an objective from the optimization.

Parameters:: name (str) – Name of the objective to remove.

remove_restriction(name)

Removes a restriction from the optimization.

Parameters:: name (str) – Name of the restriction to remove.

remove_variable(name)

Removes a variable from the optimization.

Parameters:: name (str) – Name of the variable to remove.

set_evaluation_function(func)

The evaluation function must accept a pandas.DataFrame as input parameter and return a DateFrame.

The returned pandas.DataFrame must contain all restrictions and objectives as columns and the same number of rows as the input pandas.DataFrame. It may also contain the input values, so modifying the input data frame is possible. The most simple example for this would be to use the apply-function of a data frame and return its result:

return input_df.apply(row_function, axis=1).

For every objective or restriction in this optimization object, the returned data frame has to contain a column with the name of that objective or restriction.

Parameters:: evaluation_function – A function with pandas.DataFrame as input and output. (evaluation_function: pandas.DataFrame -> pandas.DataFrame)

set_initial_parents(df_parents)

Set initial parents in form of a data frame.

Parameters:: df_parents (DataFrame) – A pandas.DataFrame containing the initial parents. The data frame must contain columns named as the input variables. IF the objective / restrictions values are also known, they can also be added. This prevents unnecessary evaluations.

set_parameter(name, value)

Sets an optimization parameter. Parameter values will be stored and transferred to CVA as strings.

Parameters:

name (str) – The name of the parameter.
value (object) – The value of the parameter.

set_reference_point(reference_point)

Set a reference point.

A reference point can be used to evaluate the quality of a Pareto front.

Parameters:: reference_point (List[float]) – The reference point.

start()

Runs the optimization loop. The evaluation stops aft MaxGeneration.

Raises:: CvaException – if the core operation did not succeed. The exceptions contains the reason.
Returns:: Optimization result (Pareto front) after MaxGeneration iterations.
Return type:: DataFrame

step_check_stalled_optimization()

Checks stall conditions as configured.

Returns:: True if stall conditions are active and are met.
Return type:: bool

step_finish_optimization()

Finalizes an optimization run. Creates the optimization history.

Returns:: A tuple of the a data frame with the best solutions and a data frame with the history of the optimization run.
Return type:: Tuple[DataFrame, DataFrame]

step_init_optimization()

Starts an optimization run by creating initial individuals: and updating the optimization object.

Returns:: The initial individuals in a data frame.
Return type:: DataFrame

step_next_optimization(df_evaluations)

Continues an optimization run by creating next individuals: from previous evaluations and updates the optimization object.

Parameters:: df_evaluations (DataFrame) – Data frame of evaluated individuals from a previous call.
Returns:: The next individuals in a data frame.
Return type:: DataFrame

cvi.Structures module

class cvi.Structures.CvaDesignOfExperimentsInfo

Bases: object

Objects of this class contain all necessary information to describe a design of experiments task. This includes input variables, restriction functions, and design of experiments parameters.

get_doe()

Get the created design of experiments as a pandas.DataFrame.

Returns: The design of experiments or None.

get_existing_samples()

Get the already existing design of experiments set for a space-filling design.

Returns:: The existing design of experiment as pandas.DataFrame.
Return type:: DataFrame

get_model()

Get the model to be used with an adaptive modeling design.

Returns:: The CVA model.
Return type:: cva.Models.Model

get_models()

Get the models to be used with an adaptive modeling design.

Returns:: A list of VA models.
Return type:: List[‘cva.Models.Model’]

get_parameters()

Get the design of experiment parameters.

Returns:: The design of experiment parameters.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

get_restrictions()

Get the list of restrictions.

Returns:: The list restrictions.
Return type:: List[‘cva.Structures.CvaRestriction’]

get_variables()

Get the input variables.

Returns:: The list input variables.
Return type:: List[‘cva.Structures.CvaVariable’]

init_from(info)

Copy from another design of experiments info.

Parameters:: info (cva.Structures.CvaDesignOfExperimentsInfo) – The info to copy from.
Returns:: self.
Return type:: cva.Structures.CvaDesignOfExperimentsInfo

set_doe(doe)

Set the created design of experiments.

Parameters:: doe (DataFrame) – A pandas.DataFrame containing the design of experiments.

set_existing_samples(df)

Set an already existing design of experiments when doing a space-filling design.

Parameters:: df (DataFrame) – A pandas.DataFrame containing the existing samples.

set_model(model)

Set a model used for an adaptive modeling design.

Parameters:: model (cva.Models.Model) – A CVA model.

set_models(models)

Set models to used for an adaptive modeling design.

Parameters:: models – A list of CVA models.

class cvi.Structures.CvaFitTask(c_model_template_paramer=None)

Bases: object

Container for CVA task and model parameters.

Task parameters control how the model is fitted including things like cross-validation and hyper-parameter optimization. They are model type independent. The model parameters contain specific information for the chosen model type. This can be the type of a kernel function or the number of neurons of a neural network. Some of these parameters can be optimized, if the optimization is enabled in the task parameters.

Hint

Objects are provided from internal classes and should not be created by the user.

get_model_parameter_value(name)

Get the value of a model parameter.

Returns:: The value of the model parameter.
Return type:: object

get_model_parameters()

Get model parameter.

Returns:: Dictionary of model parameters (cva.Structures.CvaModelParameter).

get_model_type()

Get the model type.

Returns:: The model type.
Return type:: str

get_task_parameter_value(name)

Get the value of a task parameter.

Returns:: The value of the task parameter.
Return type:: object

get_task_parameters()

Get task parameters. :returns: Dictionary {name, parameter}.

set_model_parameter_value(name, value)

Set value of a model parameter.

Parameters:

name (str) – Name of the model parameter.
value (object) – The new value.

set_model_parameters(model_parameters)

Set model parameters.

Parameters:: model_parameters (Dict[str, 'cva.Structures.CvaModelParameter']) – Dictionary {name, model parameter}.

set_task_parameter_value(name, value)

Set value of a task parameter.

Parameters:

name (str) – Name of the task parameter.
value (object) – The new value.

set_task_parameters(task_parameters)

Set task parameters.

Parameters:: task_parameters (Dict[str, 'cva.Structures.CvaTaskParameter']) – Dictionary {name, model parameter}.

property model_type: str

The model type.

Getter:: Return the model type.

class cvi.Structures.CvaFunction(name)

Bases: object

Base class for objective and restriction functions.

Parameters:: name – Name of the restriction.

get_name()

Names of functions, restrictions, and variables have to be unique identifiers.

Returns:: The name of the function object.
Return type:: str

property name: str

Names of functions, restrictions, and variables have to be unique identifiers.

Getter:: Returns the name of the function object.

class cvi.Structures.CvaModelCompare(c_model_compare, models)

Bases: object

Comparison class for models with the same input variables and the same output variable.

Hint

Objects are provided from internal classes and should not be created by the user.

get_matrix()

Get the comparison matrix.

Returns:: A matrix for pairwise comparison. A -1 means row lost against column, 0 no significant difference, 1 row won against column.
Return type:: DataFrame

get_winner()

Get the winner model.

Returns:: The best model of the comparison.
Return type:: cva.Models.Model

get_wins()

Get how many times a model won against other models.

Returns:: A list of how many times a model won against others.
Return type:: List[Tuple[‘cva.Models.Model’, int]]

class cvi.Structures.CvaModelInfo(c_model_info, fit_task, input_names, output_name, output_class_names, original_output_values, model_type)

Bases: object

CVA model information containing learn parameters (cva.Structures.CvaFitTask()) and if successfully fitted, qualities, variable importance and sensitivity values.

Hint

Objects are provided from internal classes and should not be created by the user.

Qualities

The model qualities can be accessed with the function get_qualities(). The qualities are returned in form of a pandas.DataFrame with the following structure:

Index	output	model_type	mean_squared_error	…	…
Final	y	neural_network	9.12	…	…
Validation	y	neural_network	12.34	…	…

The final values are the quality values of the model fitted on all data using the optimized hyper-parameters. The validation values are the mean qualities on the validation parts.

Variable importance

The importance of the variables can be accessed with the function get_variable_importance(). The importance values are returned in form of a data frame with the following structure:

Input	output	model_type	quality	ranking
x1	y	neural_network	15.67	1.0
x2	y	neural_network	14.56	0.2
…	y	neural_network	…	…

One row exists for each input variable. The quality columns shows the mean squared error of the model after removing the variable. The ranking value shows the importance in comparison with the other variables. A one means, that after removing this variable, the quality drops most. Thus, this variable is most important. The other ranking values relate to their quality value to the quality value of the most important variable. Sometimes the ranking can be negative. This indicates, that removing the variable actually improves the model. Thus, the quality value is lower than the final quality value. The ranking works like before, only the least important variable is the base line for the negative ranking.

Variable sensitivity

The sensitivity of the variables can be accessed with the function get_variable_sensitivity(). The sensitivity values are returned in form of a data frame with the following structure:

Input	output	model_type	sobol_index	total_sobol_index
x1	y	neural_network	0.89	0.84
x2	y	neural_network	0.11	0.16
…	y	neural_network	…	…

One row exists for each input variable. The sensitivity is measured using the Sobol indices.

Validation values

The validation values can be accessed with the function get_validation_data_frame(). The validation values are returned in form of a data frame with the following structure depending on the output variable type:

Real-valued output variable

Index	output	model_type	original_value	predicted_value
0	y	neural_network	626.468	557.014
1	y	neural_network	126.126	122.262
…	y	neural_network	…	…

The index is the index of the learn data points. The predictions are from the validation parts. Thus, you can plot for example the original values against the predicted values to visualize the validation model quality.

Class output variable

Index	output	model_type	original_value	predicted_value
0	y	neural_network	A	B
1	y	neural_network	C	C
…	y	neural_network	…	…

The index is the index of the learn data points. The predictions are from the validation parts. Thus, you can use this to create a confusion matrix (get_confusion_matrix()) for the validation part.

Confusion matrix

For classification models a confusion matrix (get_confusion_matrix()) can be generated.

Index	orig_A	orig_B	…
pred_A	25	1	…
pred_B	2	37	…
…	…	…	…

get_confusion_matrix(df=None, class_names=None)

Create a confusion matrix.

Parameters:: df (DataFrame) – A data frame with a column “original_values” and a column “predicted_values”. If no data frame is given, the validation data frame is used.
Raises:: CvaException – if the model is not a classifier or one of the needed columns is missing.
Returns:: A data frame containing the confusion matrix.

get_fit_task()

Get the fit task used to fit the model.

Returns:: The fit task containing the parameters used to fit the model.
Return type:: cva.Structures.CvaFitTask

get_invalid_reason()

If the model is not valid, get the reason or ‘’ if the model is valid.

Returns:: The reason for failure.
Return type:: str

get_is_valid()

Check, if the model is valid.

Returns:: True, if the model has been successfully fitted, else False.
Return type:: bool

get_model_type()

Get the model type.

Returns:: The model type.
Return type:: str

get_morris()

Get the sensitivity in form of the Morris indices (see CvaModelInfo). :returns: A data frame with the sensitivity for the input variables (Mean and standard deviation of the morris function).

get_qualities()

Get the quality data frame (see CvaModelInfo).

Returns:: The quality data frame.
Return type:: DataFrame

get_validation_data_frame()

Get the data frame with comparison between original and predicted values for the internal validation (see CvaModelInfo).

Returns:: Data frame with the comparison.
Return type:: DataFrame

get_variable_importance()

Get the variable importance data frame (see CvaModelInfo).

Returns:: A pandas.DataFrame with the input variable importance.
Return type:: DataFrame

get_variable_sensitivity()

Get the sensitivity in form of the Sobol indices (see CvaModelInfo).

Returns:: A data frame with the sensitivity for the input variables (Sobol index and total Sobol index).
Return type:: DataFrame

class cvi.Structures.CvaModelParameter(name, value, value_type, enums=[], description='', is_optimizable=False, opt_min=nan, opt_max=nan, is_core=True)

Bases: CvaParameter

CVA modeling parameter extending the normal parameters by is optimizable and optimization limits.

Parameters:

name (str) – Name of the parameter.
value (object) – Default value of the parameter.
value_type (str) – Value type of the parameter (“integer”, “float”, “boolean”, “enum”, “string”).
enums (List[str]) – List of names, if the value type is “enum”.
description (str) – Short description of the parameter.
is_optimizable (bool) – If true, this is a hyperparameter which is optimized, else it is a configurable parameter.
opt_min (float) – If this is a hyperparameter, this is the lower limit (only needed for value_type float and integer).
opt_max (float) – If this is a hyperparameter, this is the upper limit (only needed for value_type float and integer).

get_is_optimizable()

Check, if the parameter is optimizable.

Returns:: True, if the parameter is optimizable, else False.
Return type:: bool

get_opt_max()

Get the upper bound of the optimization range.

Raises:: CvaException – if the parameter is not optimizable.
Returns:: The upper bound.
Return type:: float

get_opt_min()

Get the lower bound of the optimization range.

Raises:: CvaException – if the parameter is not optimizable.
Returns:: The lower bound.
Return type:: float

init_from(parameter)

Copy from a parameter.

Parameters:: parameter (cva.Structures.CvaModelParameter) – The parameter to copy from.
Returns:: self.
Return type:: CvaModelParameter

to_dict()

Convert the parameter to a dictionary.

Returns:: Dictionary {name, value}
Return type:: Dict[str, object]

property opt_max: float

The upper bound of the optimization range.

Getter:: Returns the upper bound of the optimization range.

property opt_min: float

The lower bound of the optimization range.

Getter:: Returns the lower bound of the optimization range.

class cvi.Structures.CvaObjective(name, obj_type='Minimize', obj_value=0.0)

Bases: CvaFunction

Wrapper class for objective functions.

Parameters:

name – Name of the function, also used as column name for data frames. Has to be unique.
obj_type – Type of the objective function, ‘Minimize’ (default), ‘Maximize’, ‘Value’
obj_value – A target value for this objective.

get_type()

The type defines the direction of the optimization. It can be ‘Minimize’, ‘Maximize’, or ‘Value’. In case of ‘Value’ a target value has to be set. These types are just for convenience, since every type can be changed into a minimization task. Default is ‘Minimize’. ‘Maximize’ and ‘Value’ can also implemented within the evaluation function of the optimization, e.g. using \(1/fitness\) or \((fitness-x)^2\) as fitness values and minimizing these transformed values.

Returns:: The type (‘direction’) of this objective.
Return type:: str

get_value()

This will be used, if type is set to ‘Value’. Solutions for this objective are considered to be better when closer to the target value.

Returns:: The target value of this objective.
Return type:: float

init_from(objective)

Copy from objective.

Parameters:: objective (cva.Structures.CvaObjective) – The objective to copy from.
Returns:: self.
Return type:: cva.Structures.CvaObjective

property type: str

The type defines the direction of the optimization. It can be ‘Minimize’, ‘Maximize’, or ‘Value’. In case of ‘Value’ a target value has to be set. These types are just for convenience, since every type can be changed into a minimization task. Default is ‘Minimize’. ‘Maximize’ and ‘Value’ can also implemented within the evaluation function of the optimization, e.g. using \(1/fitness\) or \((fitness-x)^2\) as fitness values and minimizing these transformed values.

Getter:: Returns the type (‘direction’) of this objective.

property value: float

This will be used, if type is set to ‘Value’. Solutions for this objective are considered to be better when closer to the target value.

Getter:: Returns the target value of this objective.

class cvi.Structures.CvaOptimizationInfo

Bases: object

Objects of this class contain all necessary information to describe an optimization task. This includes input variables, objective functions, restriction functions, and optimization parameters.

get_generations()

Returns the maximum number of generations.

Returns:: Number of optimization loop iterations.
Return type:: int

get_objectives()

The list of objective function objects.

Returns:: List of objectives.
Return type:: List[‘cva.Structures.CvaObjective’]

get_parameters()

Get the parameters.

Returns:: Dictionary {name, parameter}`.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

get_restrictions()

The list of restriction function objects.

Returns:: List of restrictions.
Return type:: List[‘cva.Structures.CvaRestriction’]

get_variables()

The list of input variable objects.

Returns:: List variables.
Return type:: List[‘cva.Structures.CvaVariable’]

init_from(info)

Copy from another optimization info.

Parameters:: info (cva.Structures.CvaOptimizationInfo) – The info to copy from.
Returns:: self.
Return type:: cva.Structures.CvaOptimizationInfo

set_generations(generations)

Sets the maximum number of generations to be performed by an optimization task.

Parameters:: generations (int) – Maximum number of optimization loop iterations.

set_parameters(parameters)

Set the optimization parameters.

Parameters:: parameters (Dict[str, 'cva.Structures.CvaParameter']) – Dictionary {name, parameter}.

class cvi.Structures.CvaParallelTask(model, input_variable_names, output_variable_name, df, check_path, check_type)

Bases: object

Structure containing information for a modeling task. This structure is intended to be used with the parallel interface.

Parameters:

model (cva.Models.Model) – The model (cva.Models.Model) created by the manager.
input_variable_names (List[str]) – The input variable names.
output_variable_name (str) – The output variable name.
df (pandas.DataFrame) – A pandas data frame with learn data.
check_path (str) – If a path is given, the models for each task a stored there as a check point. This implies, that the path is reachable from all clients. The name of the files is composed if the output variable name and the model type.
check_type (str) – The check type can be pickle or xml. It is used when a check path is given and determines the type of file stored after completing a task.

check_path: If a path is given, the models for each task a stored there as a check point. This implies, that the path is reachable from all clients. The name of the files is composed if the output variable name and the model type.

check_type: The check type can be pickle or xml. It is used when a check path is given and determines the type of file stored after completing a task.

df: A pandas data frame with learn data.

input_variable_names: The input variable names.

model: The model (cva.Models.Model) created by the manager.

output_variable_name: The output variable name.

class cvi.Structures.CvaParameter(name, value, value_type, enums=[], description='', core=True)

Bases: object

CVA parameter including name, description, value and value type.

Parameters:

name (str) – Name of the parameter.
value (object) – Default value of the parameter.
value_type (str) – Value type of the parameter (“integer”, “float”, “boolean”, “enum”, “string”).
enums (List[str]) – List of names, if the value type is “enum”.
description (str) – Short description of the parameter.

get_description()

Get additional description on the parameter.

Returns:: Additional description, if available.
Return type:: str

get_enums()

Get the names of an enum parameter.

Returns:: A list of possible name of the enum parameter.
Raises:: CvaException – if the parameter is not an enum parameter.
Return type:: List[str]

get_name()

Get the name of the parameter.

Returns:: The name of the parameter.
Return type:: str

get_value()

Get the current value of the parameter.

Returns:: The value.
Return type:: object

get_value_type()

Get the value type.

Returns:: The value type.
Return type:: str

init_from(parameter)

Copy from a parameter.

Parameters:: parameter (cva.Structures.CvaParameter) – The parameter to copy from.
Returns:: self.
Return type:: CvaParameter

is_core_parameter()

Check the internal flag.

Returns:: True if this parameter should be set in CVA-core.
Return type:: bool

set_value(value)

Set a new value for the parameter.

Parameters:: value (object) – The value must be of the same type as stated in value_type.
Raises:: CvaException – if the type does not fit or an unknown name for an enum is given.

to_string()

Convert value to string.

Returns:: The value as a string.
Return type:: str

property description: str

Additional description on the parameter.

Getter:: Returns additional description on the parameter.

property enums: List[str]

The names of an enum parameter.

Getter:: Returns the names of an enum parameter.

property name: str

The name of the parameter.

Getter:: Returns the name of the parameter.

property value: object

The current value of the parameter.

Getter:: Returns current value of the parameter.
Setter:: Sets current value of the parameter.
Type:: object

property value_type: str

The value type.

Getter:: Returns the value type.

class cvi.Structures.CvaRestriction(name, cmp, crit)

Bases: CvaFunction

Wrapper class for restriction functions.

Adding a restriction to an optimization with

add_restriction('res', '<', 5.0)

has the following consequences: First of all, the evaluation function has to provide a column called ‘res’ within the resulting data frame. The restriction function and the evaluation function have to be implemented by the user. Only the individuals with an column entry ‘< 5.0’ are considered as valid solutions.

Parameters:

name – The name of this restriction function. Has to be unique.
cmp – The comparator, has to be one of ‘<’,’<=’,’>=’,’>’
crit – The critical value - depending on selected comparator this is either a lower bound or an upper bound.

check(values)

Check values if they fulfill the restriction.

Parameters:: values (List[float]) – Values to be checked.
Returns:: A list of booleans. True if the check is passed else False.
Return type:: List[bool]

distance(values)

Calculate the distances to the critical value.

Parameters:: values (List[float]) – Values to be checked.
Returns:: A list of booleans. True if the check is passed else False.
Return type:: List[float]

get_comparator()

Get the comparator.

Returns:: The comparator as string.
Return type:: str

get_value()

Get the critical value.

Returns:: The critical value.
Return type:: float

init_from(restriction)

Copy from restriction.

Parameters:: restriction (cva.Structures.CvaRestriction) – The restriction to copy from.
Returns:: self.
Return type:: cva.Structures.CvaRestriction

property comparator: str

the comparator.

Getter:: Returns the comparator as string.

property value: float

The critical value.

Getter:: Returns the critical value.

class cvi.Structures.CvaSolutionSpaceOptimizationInfo

Bases: object

Objects of this class contain all necessary information to describe a solution space optimization task. This includes input variables, output variables, start boxes, and optimization parameters.

get_parameters()

Get the optimization parameter.

Returns:: Dictionary {name, parameter}
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

init_from(info)

Copy from another optimization info.

Parameters:: info (cva.Structures.CvaSolutionSpaceOptimizationInfo) – The info to copy from.
Returns:: self.
Return type:: cva.Structures.CvaSolutionSpaceOptimizationInfo

initial_boxes

start value(s). Depending on the type it could be a tuple of (min, max) or a list of class names.

Type:: List of start boxes. A box is a dictionary of variable name

initial_qualities: List of qualities corresponding with the start boxes.

input_variables: List of CvssInputVariable describing the input variables

output_variables: List of CvssOutputVariable describing the output variables

parameters: Dictionary of optimization parameters.

class cvi.Structures.CvaTaskParameter(name, value, value_type, enums=[], description='', core=True)

Bases: CvaParameter

CVA task parameter extending normal parameters.

Hint

Objects are provided from internal classes and should not be created by the user.

init_from(parameter)

Copy from a parameter.

Parameters:: parameter (cva.Structures.CvaTaskParameter) – The parameter to copy from.
Returns:: self.
Return type:: CvaTaskParameter

class cvi.Structures.CvaVariable(c_variable=None)

Bases: object

Wrapper for variables.

Hint

Objects are provided from internal classes and should not be created by the user.

Parameters:: c_variable – Only used internally.

get_class_names()

Get the attribute names of a class variable.

Returns:: The attribute names of a class variable. If the list is empty, the variable is a real-valued variable.
Return type:: List[str]

get_lower_bound()

Get the valid minimum value of a variable.

Returns:: Minimum value.
Return type:: float

get_metric_values()

Get the values of a metric variable.

Returns:: The values of a metric variable.
Return type:: List[str]

get_name()

Get the name of the variable.

Returns:: Name of the variable.
Return type:: str

get_type()

Get the type of a variable (class, metric or real).

Returns:: The type of the variable.
Return type:: str

get_upper_bound()

Get the valid maximum value of a variable.

Returns:: Maximum value.
Return type:: float

init_from(variable)

Copy from a variable.

Parameters:: variable (cva.Structures.CvaVariable) – The parameter to copy from.
Returns:: self.
Return type:: CvaVariable

set_properties(name, lower_bound=0.0, upper_bound=0.0, vartype='real', class_names=[], metric_values=[])

Set the properties of a variable.

Parameters:

name (str) – Name of the variable.
minimum – Minimum value
maximum – Maximum value
vartype (str) – Type can be real, metric or class
class_names (List[str]) – List of names (set of valid values) for a nominal variable.
metric_values (List[str]) – List of values (set of valid values) for a nominal variable.

property class_names: List[str]

The attribute names of a class variable.

Getter:: Returns the attribute names of a class variable.

property lower_bound: float

The valid minimum value of a variable.

Getter:: Returns the valid minimum value of a variable.

property metric_values: List[str]

The values of a metric variable.

Getter:: Returns the values of a metric variable.

property name: str

The name of the variable.

Getter:: Returns the name of the variable.

property type: str

The type of a variable (class, metric or real).

Getter:: Returns the type of a variable (class, metric or real).

property upper_bound: float

The valid maximum value of a variable.

Getter:: Returns the valid maximum value of a variable.

class cvi.Structures.CvssInputVariable

Bases: object

Wrapper for solution space input variables.

An input variable describes one edge of the design space. It can be either real-valued or a list of class names. A typical task is to find either the largest interval (real-valued) or the biggest subset of the class names while all samples within the box are good samples. An input variable can constrained.

real-valued: The lower or upper bound or the width of the interval can be fixed. Instead of optimizing an interval, the variable can be set to only find one good value. If both bounds are fixed or the single value is fixed, the variable is not considered in the optimization.
class: Instead of finding a subset the task can be changed to find one good class. If the set of classes or a single class is fixed, the variable is not considered in the optimization

check()

Check, if the values set are valid.

Returns:: Tuple of (True, if everything is okay, else False / Fail message).
Return type:: Tuple[bool, str]

get_class_names()

Get the attribute names of a class variable.

Returns:: The attribute names of a class variable. If the list is empty, the variable is a real-valued variable.
Return type:: List[str]

get_is_class_names_fixed()

Get if the class labels are fixed.

Returns:: True, if the class labels are fixed, else False.
Return type:: bool

get_is_interval()

Get if the result should be an interval/subset or a single value/class.

Returns:: True, if upper and lower bound / set of class names is used, else for the usage of single value/class names False.
Return type:: bool

get_is_lower_fixed()

Get if the lower bound is fixed.

Returns:: True, if the bound is fixed, else False.
Return type:: bool

get_is_upper_fixed()

Get if the upper bound is fixed.

Returns:: True, if the bound is fixed, else False.
Return type:: bool

get_is_value_fixed()

Get if the single value is fixed (Only used if is_interval = False).

Returns:: True, if the value is fixed, else False.
Return type:: bool

get_is_width_fixed()

Get if the width is fixed (Only used if is_interval = True).

Returns:: True, if the width is fixed, else False.
Return type:: bool

get_lower_bound()

Get the lower bound of a real-valued variable.

Returns:: lower bound of the variable.
Return type:: float

get_lower_upper_bound()

Get the upper limit for the lower bound (Only used if is_interval = True and is_lower_fixed = False and is_width = False).

The default case moves the lower bound of edge in the design interval. Setting a different bound than the upper design interval bound restricts the lower bound of the edge.

Returns:: The upper bound of the lower bound of the edge or None if not used.
Return type:: float

get_name()

Get the name of the variable.

Returns:: Name of the variable.
Return type:: str

get_type()

Get the type of a variable (class or real).

Returns:: Variable type as string
Return type:: str

get_upper_bound()

Get the upper bound of a real-valued variable.

Returns:: Upper bound of the variable.
Return type:: float

get_upper_lower_bound()

Get the lower limit for the upper bound (Only used if is_interval = True and is_lower_fixed = False and is_width = False).

The default case moves the upper bound of edge in the design interval. Setting a different bound than the lower design interval bound restricts the upper bound of the edge.

Returns:: The lower bound of the upper bound of the edge or None if not used.
Return type:: float

get_value()

Get the fixed value (Only used if is_interval = False and is_fixed = True).

Returns:: Either a real value or a class depending on the variable type..
Return type:: object

get_width()

Gets a fixed width of a real-valued input (only used if is_width = True).

Returns:: The fixed width of the interval.
Return type:: float

init_from(variable)

Copy from another input.

Parameters:: variable (cva.Structures.CvssInputVariable) – The variable to copy from.
Returns:: self.
Return type:: cva.Structures.CvssInputVariable

set_class_names(class_names)

Set the attribute names of a class variable.

Parameters:: class_names (List[str]) – The attribute names of a class variable. If the list is empty, the variable is a real-valued variable.

set_is_class_names_fixed(is_fixed)

Set if the class labels are fixed.

Parameters:: is_fixed (bool) – True, if the class labels are fixed, else False.

set_is_interval(is_interval)

Set if the result should be an interval/subset or a single value/class.

Parameters:: is_interval (bool) – True, if upper and lower bound / set of class names is used, else for the usage of single value/class names False.

set_is_lower_fixed(is_fixed)

Set if the lower bound is fixed.

Parameters:: is_fixed (bool) – True, if the bound is fixed, else False.

set_is_upper_fixed(is_fixed)

Set if the upper bound is fixed.

Parameters:: is_fixed (bool) – True, if the bound is fixed, else False.

set_is_value_fixed(is_fixed)

Set if the single value is fixed (Only used if is_interval = False).

Parameters:: is_fixed (bool) – True, if the value is fixed, else False.

set_is_width_fixed(is_fixed)

Set if the width is fixed (Only used if is_interval = True).

Parameters:: is_fixed (bool) – True, if the width is fixed, else False.

set_lower_bound(lower_bound)

Set the lower bound of a real-valued variable.

Parameters:: lower_bound (float) – lower bound of the variable.

set_lower_upper_bound(value)

Set an upper limit for the lower bound (Only used if is_interval = True and is_lower_fixed = False and is_width = False).

The default case moves the lower bound of edge in the design interval. Setting a different bound than the upper design interval bound restricts the lower bound of the edge.

Parameters:: value (float) – The upper bound of the lower bound of the edge or None to clear the restriction.

set_properties(name, lower_bound=0.0, upper_bound=0.0, value=0.5, vartype='real', class_names=[])

Set the essential properties of an input variable.

Parameters:

name (str) – Name of the variable.
lower_bound (float) – Lower design space bound.
upper_bound (float) – Upper design space bound.
value (float) – The value is needed if the input variable should be fixed at a certain value or class name.
vartype (str) – Type can be real, metric (same as real), or class
class_names (List[str]) – List of names (set of valid values) for a nominal variable.

set_upper_bound(upper_bound)

Set the upper bound of a real-valued variable.

Parameters:: upper_bound (float) – Upper bound of the variable.

set_upper_lower_bound(value)

Set a lower limit for the upper bound (Only used if is_interval = True and is_lower_fixed = False and is_width = False).

The default case moves the upper bound of edge in the design interval. Setting a different bound than the lower design interval bound restricts the upper bound of the edge.

Parameters:: value (float) – The lower bound of the upper bound of the edge or None to clear the restriction.

set_value(value)

Set the fixed value (Only used if is_interval = False and is_fixed = True).

Parameters:: value (object) – Either a real value or a class depending on the variable type.

set_width(width)

Sets a fixed width of a real-valued input (only used if is_width = True).

Parameters:: width (float) – The fixed width of the interval.

property name: str

The name of the parameter.

Getter:: Returns the name of the parameter.

property type: str

The type of a variable (class, metric or real).

Getter:: Returns the type of a variable (class, metric or real).

class cvi.Structures.CvssOutputVariable

Bases: object

Wrapper for solution space output variables. The output variables decide if a sample (design) is good or bad. Each output variable has either critical values (real-valued) or bad labels (class names of a classifier).

check()

Check, if the values set are valid.

Returns:: Tuple of (True, if everything is okay, else False / Fail message).
Return type:: Tuple[bool, str]

get_bad_labels()

Get the bad labels of a class output variable.

Returns:: The list of bad labels. If the list is empty, the variable is a real-valued variable.
Return type:: List[str]

get_crit_low()

Get the critical lower bound of an output variable.

Returns:: Critical minimum value as double. Can be NaN.
Return type:: float

get_crit_up()

Get the critical upper bound of an output variable.

Returns:: Critical maximal value as double. Can be NaN.
Return type:: float

get_low_crit_norm()

Get the critical lower norm value of an output variable.

Returns:: Norm value.
Return type:: crit_norm

get_name()

Get the name of the variable.

Returns:: Name of the variable.
Return type:: str

get_type()

Get the type of a variable (class or real).

Returns:: Variable type as string.
Return type:: str

get_up_crit_norm()

Get the critical upper norm value of an output variable.

Returns:: Norm value.
Return type:: crit_norm

init_from(variable)

Copy from another output.

Parameters:: variable (cva.Structures.CvssOutputVariable) – The variable to copy from.
Returns:: self.
Return type:: cva.Structures.CvssOutputVariable

set_bad_labels(bad_labels)

Set the bad labels of a class output variable.

Parameters:: bad_labels (List[str]) – The list of bad labels. If the list is empty, the variable is a real-valued variable.

set_crit_low(crit_low)

Set the critical lower bound of an output variable.

Parameters:: crit_low (float) – Critical minimum value as double. Can be NaN.

set_crit_up(crit_up)

Set the critical upper bound of an output variable.

Parameters:: crit_up (float) – Critical maximal value as double. Can be NaN.

set_low_crit_norm(crit_norm)

Set the critical lower norm value of an output variable.

Parameters:: crit_norm (float) – Norm value. Must be set and not 0. if crit_low is not NaN.

set_properties(name, crit_low=nan, crit_up=nan, vartype='real', bad_labels=[])

Set the essential properties of an output variable.

Parameters:

name (str) – Name of the variable.
crit_low (float) – Minimum value
crit_up (float) – Maximum value
vartype (str) – Type can be real, metric (same as real), or class
bad_labels (List[str]) – List of names (set of valid values) for a nominal variable.

set_up_crit_norm(crit_norm)

Set the critical upper norm value of an output variable.

Parameters:: crit_norm (float) – Norm value. Must be set and not 0. if crit_up is not NaN.

property name: str

The name of the parameter.

Getter:: Returns the name of the parameter.

property type: str

The type of a variable (class, metric or real).

Getter:: Returns the type of a variable (class, metric or real).

cvi.Structures.create_default_doe_parameter()

Create common design of experiments parameter with default values.

Returns:: Dictionary {name, default parameter}.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

cvi.Structures.create_default_optimization_parameter()

Create common optimization parameter with default values.

Returns:: Dictionary of default parameter.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

cvi.Structures.create_default_solution_space_optimization_parameter()

Create common optimization parameter with default values.

Returns:: Dictionary of default parameter.
Return type:: Dict[str, ‘cva.Structures.CvaParameter’]

cvi.Structures.create_default_task_parameters()

Create common task parameters with default values.

Returns:: Dictionary {name, parameter} of default parameter.
Return type:: Dict[str, ‘cva.Structures.CvaTaskParameter’]

cvi.Structures.create_task(manager, model_type)

Create task and model parameters with default values for a specific model type.

Parameters:

manager – The CVA manager object.
model_type – The model type (one of cva.Base.Manager.available_model_types()).

Raises:

CvaException – if the model type is not recognized.