src.model.model

Classes

Model(**kwargs)

Exceptions

ModelException([message])

exception src.model.model.ModelException(message='')
Author:

Alberto M. Esmoris Pena

Class for exceptions related to model components. See VL3DException.

__init__(message='')
class src.model.model.Model(**kwargs)
Author:

Alberto M. Esmoris Pena

Abstract class providing the interface governing any model.

Variables:

  • training_type (str) – The type of training. Either “base”, “autoval”, or “stratified_kfold”.

  • autoval_size (int or float) – The size of the auto validation set (used by model.Model.train_autoval()). It can be given as a ratio in [0, 1] or as the set cardinality in [0, m].

  • autoval_metrics_names (list of str) – A list with the names of the evaluation metrics governing the autovalidation.

  • shuffle_points (bool) – Flag governing whether to shuffle the points (True) or not (False). It is used by src.model.Model.train_autoval() and src.model.Model.train_stratified_kfold().

  • num_folds (int) – The number of folds, i.e. K for K-Folding.

  • imputer (Imputer) – The imputer to deal with missing values (can be None).

  • fnames (list) – The list of feature names (fnames) attribute. These features must correspond to the features in the input point cloud for training and predictions.

  • random_seed (int) – Optional attribute to specify a fixed random seed for the random computations of the model.

  • stratkfold_report_path (str) – The path where the report representing the evaluation of the k-folding procedure must be written.

  • stratkfold_plot_path (str) – The path where the plot representing the evaluation of the k-folding procedure must be written.

  • training_data_pipeline (list of dict) – List of dictionaries such that each dictionary provides a key-word specification of a component to be used to transform or select the training data. Note that the components will be sequentially applied to the data in the same order they are given in the list.

static extract_model_args(spec)

Extract the arguments to initialize/instantiate a Model from a key-word specification.

Parameters:

spec – The key-word specification containing the arguments.

Returns:

The arguments to initialize/instantiate a Model.

__init__(**kwargs)

Root initialization for any instance of type Model.

Parameters:

kwargs – The attributes for the Model.

train(pcloud)

Train the model from a given input point cloud.

Parameters:

pcloud – The input point cloud to train the model with.

Returns:

The trained model.

Return type:

src.model.model.Model

predict(pcloud, X=None)

Use the model to compute predictions on the input point cloud.

Parameters:

  • pcloud (src.pcloud.point_cloud.PointCloud) – The input point cloud to compute the predictions.

  • X – The input matrix of features where each row represents a point from the point cloud (OPTIONAL). If given, X will be used as point-wise features instead of pcloud. It is often named F in the context of point clouds where the point cloud is a block matrix P = [X|F].

Returns:

The point-wise predictions.

Return type:

np.ndarray

abstractmethod prepare_model()

Prepare the model so its model attribute (i.e., model.model) can be used, for instance by a hyperparameter tuner.

Returns:

The prepared model itself. However, the prepared model must be automatically assigned as an attribute of the object/instance too.

overwrite_pretrained_model(spec)

This method must be called when preparing a pretrained model to overwrite any attribute that must be overriding depending on the model and the given training specification.

Parameters:

spec (dict) – The key-word training specification to continue the training of the pretrained model.

Returns:

Nothing, but the model object internal state is updated.

get_input_from_pcloud(pcloud)

Obtain the model-ready input from the given point cloud.

Parameters:

pcloud – The point cloud containing the data to fit the model.

Returns:

Model-ready input data.

is_deep_learning_model()

Check whether a model is a deep learning model or not.

By default, models are not deep learning models. Those models which are a deep learning model should explicitly overwrite this method to return True. It is necessary for correct pipelines.

Returns:

True if the model is a deep learning model, False otherwise.

abstractmethod training(X, y, info=True)

The fundamental training logic defining the model.

It must be overridden by non-abstract subclasses.

Parameters:

  • X – The input matrix representing the point cloud, e.g., the geometric features matrix.

  • y – The class for each point.

  • info – True to enable info log messages, False otherwise.

Returns:

Nothing, but the model itself is updated.

autoval(y, yhat, info=True)

Auto validation during training.

Any non-abstract subclass must provide an implementation for autoval or avoid calling model.Model.train_autoval() and src.model.model.Model.train_stratified_kfold to prevent exceptions/errors.

Parameters:

  • y – The expected values.

  • yhat – The predicted values.

  • info – True to log an info message with the auto validation, False otherwise.

Returns:

The results of the auto validation.

train_base(pcloud)

Straightforward model training.

Parameters:

pcloud – The input point cloud to train the model.

Returns:

The trained model.

Return type:

Model

train_autoval(pcloud)

Auto validation training strategy.

Some part of the data is ignored during training to be used for later validation of the trained model (auto validation).

The subsets are extracted in a stratified way. See src.model.model.Model.train_stratified_kfold() for a description of stratification.

Parameters:

pcloud – The input point cloud to train the model.

Returns:

The trained model.

Return type:

src.model.model.Model

train_stratified_kfold(pcloud)

Stratified k-fold training strategy.

Stratification consists of dividing the data into subsets (strata). Test points are taken from each subset, i.e., each stratum of the strata, so they follow a class distribution approximately proportional to the original set. This strategy guarantees that the test points constitute a reliable representation of the original points.

K-folding consists of dividing the data into K different subsets (folds). Then, K iterations are computed such that at each one a different fold is considered as the test set and the other (K-1) folds are used for training.

Stratified K-folding is K-folding with stratified folds, i.e., each fold is also a stratum.

Parameters:

pcloud – The input point cloud to train the model.

Returns:

The trained model.

Return type:

Model

on_training_finished(X, y)

Callback method that must be invoked by any training strategy after finishing the training but before returning the trained model.

Parameters:

  • X – The point-wise features matrix with points as rows and features as columns.

  • y – The point-wise expected classes.

Returns:

Nothing.

optimize_data_types(X=None, y=None)

Optimize the data types, depending on the current configuration of the framework.

Parameters:

  • X – The input data.

  • y – The reference data.

Returns:

The updated data types.

Return type:

tuple of np.ndarray