utils.preds package

Submodules

utils.preds.argmax_pred_select_strategy module

class utils.preds.argmax_pred_select_strategy.ArgMaxPredSelectStrategy(**kwargs)

Bases: PredSelectStrategy

Author:

Alberto M. Esmoris Pena

Select the index of the max prediction from reduced predictions.

The selected prediction for the \(i-th\) points assuming \(K\) predicted values (e.g., likelihoods for classifications) will be:

\[y_{i} = \operatorname*{argmax}_{0 \leq k < K} \quad z_{ik}\]

Note that when a single value is given the selection will consider the value round to the closest integer such that:

\[y_{i} = \lfloor{z_i}\rceil\]

See PredSelectStrategy.

__init__(**kwargs)

Initialize/instantiate an argmax prediction selection strategy.

Parameters:

kwargs – The attributes for the ArgmaxPredSelectStrategy.

select(reducer, Z)

See PredSelectStrategy and PredSelectStrategy.select().

static is_single_value(Z)

Check whether the reduced predictions consist of a single scalar per point (True) or not (False).

Parameters:

Z – The reduced predictions to be checked.

Returns:

True if the reduced predictions consist of a single scalar, False otherwise.

Return type:

bool

static round_to_closest_int(Z)

Round each reduced prediction to its closest integer.

Parameters:

Z – The reduced predictions to be checked.

Returns:

Each prediction rounded to its closest integer.

utils.preds.entropic_pred_reduce_strategy module

class utils.preds.entropic_pred_reduce_strategy.EntropicPredReduceStrategy(**kwargs)

Bases: PredReduceStrategy

Author:

Alberto M. Esmoris Pena

Reduce many predictions per point to a single one by considering the point-wise entropies.

The reduced likelihoods for the \(n_c\) classes of the \(i\)-th point will be as shown below, assuming \(K_i\) values for the reduction.

\[\pmb{\hat{z}}_{i} = \dfrac{ \displaystyle \sum_{k=1}^{K_i}{(1-\hat{e}_{i_k}) \pmb{z}_{i_k}} }{ \displaystyle \sum_{k=1}^{K_i}{(1-\hat{e}_{i_k})} } \in (0, 1)^{n_c}\]

In the above equation, \(\pmb{z}_{i_k} \in (0, 1)^{n_c}\) represents the \(k\) vector of likelihoods for the \(i\)-th point where \(k=1,\ldots,K_i\) (\(K_i\) is the number of neighborhoods where the \(i\)-th point appears).

To understand \(\hat{e}_{i_k}\) it is necessary to define the entropy for a classification task of \(n_c\) classes first such that:

\[\mathcal{E}(\pmb{z}_{i_k}) = - \sum_{c=1}^{n_c}{z_{i_kc} \log_2(z_{i_kc})} = \sum_{c=1}^{n_c}{f(z_{i_kc})}\]

Now, consider the derivatives of \(f(z) = -z \log_2(z)\):

\[\dfrac{df}{dz} = - \dfrac{1+\ln(z)}{\ln(2)} \;,\quad \dfrac{d^2f}{dz^2} = - \dfrac{1}{z\ln(2)}\]

Note that \(\dfrac{df}{dz} = 0 \iff z = e^{-1}\) and \(\dfrac{d^2f}{dz^2} < 0\). For then, \(f(e^{-1})\) will be a maximum, leading to an upper bound \(e^* = -n_ce^{-1}\log_2(e^{-1})\) such that \(\mathcal{E}(\pmb{z}_{i_k}) \leq e^*\). Consequently, it is possible to obtain normalized entropies such that:

\[\hat{e}_{i_k} = \dfrac{\mathcal{E}(\pmb{z}_{i_k})}{e^*} \in (0, 1)\]

NOTE that a min clip value \(\epsilon_*\) will be considered to replace all values below it to avoid logarithm of zero or division by zero cases.

See PredReduceStrategy.

Variables:

min_clip_value (float) – The minimum value that will be allowed. Values below it will be replaced to be the min clip value itself. This is useful to avoid division by zero and logarithm of zero cases. By default it is \(10^{-6}\).

__init__(**kwargs)

Initialize/instantiate a mean prediction reduction strategy.

Parameters:

kwargs – The attributes for the EntropicPredReduceStrategy.

reduce(reducer, npoints, nvals, Z, I)

See PredReduceStrategy and PredReduceStrategy.reduce().

reduce_single(reducer, npoints, nvals, Z, I)

Handle the reduce operations when nvals=1. See EntropicPredReduceStrategy.reduce().

reduce_many(reducer, npoints, nvals, Z, I)

Handle the reduce operation when nvals>1. See EntropicPredReduceStrategy.reduce().

utils.preds.max_pred_reduce_strategy module

class utils.preds.max_pred_reduce_strategy.MaxPredReduceStrategy(**kwargs)

Bases: PredReduceStrategy

Author:

Alberto M. Esmoris Pena

Reduce many predictions per point to a single one by taking the max value.

The reduced prediction for the \(j\)-th class of the \(i\)-th point will be as shown below, assuming \(K\) values for the reduction.

\[z_{ij} = \max*_{1 \leq k < K} z_{ijk}\]

See PredReduceStrategy.

__init__(**kwargs)

Initialize/instantiate a mean prediction reduction strategy.

Parameters:

kwargs – The attributes for the MaxPredReduceStrategy.

reduce(reducer, npoints, nvals, Z, I)

See PredReduceStrategy and PredReduceStrategy.reduce().

utils.preds.mean_pred_reduce_strategy module

class utils.preds.mean_pred_reduce_strategy.MeanPredReduceStrategy(**kwargs)

Bases: PredReduceStrategy

Author:

Alberto M. Esmoris Pena

Reduce many predictions per point to a single one by taking the mean value.

The reduced prediction for the \(j-th\) class of the \(i\)-th point will be as shown below, assuming \(K\) values for the reduction.

\[z_{ij} = \dfrac{1}{K} \sum_{k=1}^{K}{z_{ijk}}\]

See PredReduceStrategy.

__init__(**kwargs)

Initialize/instantiate a mean prediction reduction strategy.

Parameters:

kwargs – The attributes for the MeanPredReduceStrategy.

reduce(reducer, npoints, nvals, Z, I)

See PredReduceStrategy and PredReduceStrategy.reduce().

utils.preds.pred_reduce_strategy module

class utils.preds.pred_reduce_strategy.PredReduceStrategy(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Interface for reduce operations on predictions.

See PredictionReducer.

__init__(**kwargs)

Initialize/instantiate a prediction reduction strategy.

Parameters:

kwargs – The attributes for the PredReduceStrategy.

abstractmethod reduce(reducer, npoints, nvals, Z, I)

The method that provides the logic to reduce potentially more predictions than points such that there is at most one prediction per point. It must be overridden by any concrete implementation of a prediction reduction strategy.

Parameters:

  • reducer (PredictionReducer) – The prediction reducer that is doing the reduction.

  • Z (list of np.ndarray) – List of arrays. There is one array per input neighborhood, each array is a matrix where the rows represent the points and the columns the class-wise likelihoods.

  • I (list of list of int) – The indices representing the neighborhoods. There are as many lists as input neighborhoods. Each list contains the indices representing the points in the original point cloud. For example, the j-th element of the i-th list I[i][j] is the index of the j-th point in the i-th input neighborhood in the original point cloud.

Variables:

  • npoints (int) – The number of points to which the predictions must be reduced to.

  • nvals (int) – How many point-wise values must be considered for each point (classes for classification tasks, reference values for regression tasks).

Returns:

The reduced predictions as a matrix \(\pmb{Z} \in \mathbb{R}^{m \times n_v}\) where the \(m\) rows represent the points (I[i][j] will point to a row) and the \(n_v\) columns represent the likelihood for each of the predicted classes (classification) or the reference point-wise values (regression).

Return type:

np.ndarray

utils.preds.pred_select_strategy module

class utils.preds.pred_select_strategy.PredSelectStrategy(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Interface for select operations on predictions.

See PredictionReducer.

__init__(**kwargs)

Initialize/instantiate a prediction selection strategy.

Parameters:

kwargs – The attributes for the PredSelectStrategy.

abstractmethod select(reducer, Z)

The method that provides the logit to select the values of interest from the reduced predictions. It must be overridenn by any concrete implementation of a prediction selection strategy.

Parameters:

  • reducer (PredictionReducer) – The prediction reducer that is doing the reduction.

  • Z – Matrix-like array. There are as many rows as points and as many columns as reduced predictions.

Returns:

The selected predictions derived from the reduced predictions as a matrix. Either a matrix with the \(n_y\) point-wise output values \(\pmb{\hat{Y}} \in \mathbb{R}^{m \times n_y}\) or a vector for the case of a single point-wise scalar output \(\pmb{\hat{y}} \in \mathbb{R}^{m}\).

Return type:

np.ndarray

utils.preds.prediction_reducer module

exception utils.preds.prediction_reducer.PredictionReducerException(message='')

Bases: VL3DException

Author:

Alberto M. Esmoris Pena

Class for exceptions related to the reduction of many predictions for the same point. See VL3DException.

__init__(message='')
class utils.preds.prediction_reducer.PredictionReducer(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Class for reduce and select-after-reduce operations on predictions.

See PredReduceStrategy and PredSelectStrategy.

Variables:
__init__(**kwargs)

Initialize/instantiate a PredictionReducer.

Parameters:

kwargs – The attributes for the PredictionReducer.

reduce(npoints, nvals, Z, I)

See PredReduceStrategy and PredReduceStrategy.reduce().

select(Z)

See PredSelectStrategy and PredSelectStrategy.select().

utils.preds.prediction_reducer_factory module

class utils.preds.prediction_reducer_factory.PredictionReducerFactory

Bases: object

Author:

Alberto M. Esmoris Pena

Factory to build instances of PredictionReducer.

static make_from_dict(spec)

Make a PredictionReducer from the given dict-like specification.

Parameters:

spec – The specification on how to build the prediction reducer.

Returns:

The built prediction reducer.

Return type:

PredictionReducer.

static make_reduce_strategy(spec)

Make a PredReduceStrategy from the given dict-like specification.

Parameters:

spec (dict) – The specification on how to build the prediction reduce strategy.

Returns:

The built prediction reduce strategy

Return type:

PredReduceStrategy

static make_select_strategy(spec)

Make a PredSelectStrategy from the given dict-like specification.

Parameters:

spec (dict) – The specification on how to build the prediction select strategy.

Returns:

The built prediction select strategy.

Return type:

PredSelectStrategy

utils.preds.sum_pred_reduce_strategy module

class utils.preds.sum_pred_reduce_strategy.SumPredReduceStrategy(**kwargs)

Bases: PredReduceStrategy

Author:

Alberto M. Esmoris Pena

Reduce many predictions per point to a single one by summation.

The reduced prediction for the \(j-th\) class of the \(i\)-th point will be as shown below, assuming \(K\) values for the reduction.

\[z_{ij} = \sum_{k=1}^{K}{z_{ijk}}\]

See PredReduceStrategy.

__init__(**kwargs)

Initialize/instantiate a mean prediction reduction strategy.

Parameters:

kwargs – The attributes for the MeanPredReduceStrategy.

reduce(reducer, npoints, nvals, Z, I)

See PredReduceStrategy and PredReduceStrategy.reduce().

Module contents

author:

Alberto M. Esmoris Pena

The preds package contains the logic to handle predictions, generally for reduction and selection strategies on deep learning models (but not only).