src.utils.ptransf.point_cloud_sampler_decorator

Classes

PointCloudSamplerDecorator(**kwargs)

class src.utils.ptransf.point_cloud_sampler_decorator.PointCloudSamplerDecorator(**kwargs)

Author:: Alberto M. Esmoris Pena

Class representing an abstract sampler that transforms the number of points in a point cloud and can be used to decorate different components of the framework.

Typically, \(m \in \mathbb{Z}_{>0}\) denotes the number of points in the input point cloud and \(R \in \mathbb{Z}_{>0}\) the number of points in the sampled point cloud.

Variables:

num_encoding_neighbors (int) – How many closest neighbors consider when doing reductions. For instance, for three encoding neighbors reducing a value means three points in the original domain will be considered to estimate the value in the representation domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the original domain to the representation domain will be computed.
num_decoding_neighbors (int) – How many closest neighbors consider when doing propagations. For instance, for three decoding neighbors propagating a value means three points in the representation domain will be considered to estimate the value in the original domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the representation domain back to the original domain will be computed.
release_encoding_neighborhoods – A flag to enable releasing the encoding neighborhoods after building the representation. It can be used to save memory when the topological information of the encoding process will not be used after generating the representation.
representation_report_path (str) – Path where a point cloud with the points in the representation space will be exported.
threads (int) – The number of threads to be used for parallel computations. A value of -1 means using all available cores.
N (np.ndarray) – The encoding neighborhoods that define what points in the original space must be considered to obtain each point in the representation space. It is a matrix \(\pmb{N} \in \mathbb{R}^{R \times k_e}\) for \(k_e\) encoding neighbors where each row corresponds to a point in the reduced space and the columns give the indices of their neighbors in the original space.
M (np.ndarray) – The decoding neighborhoods that define what points in the representation space must be considered to propagate back to the original space. It is a matrix \(\pmb{M} \in \mathbb{R}^{m \times k_d}\) for \(k_d\) decoding neighbors where each row corresponds to a point in the original space and the columns give the indices of their neighbors in the reduced space.

__init__(**kwargs)

Initialize/instantiate a point cloud sampler decorator object.

Parameters:

kwargs – The key-word specification to instantiate the PointCloudSamplerDecorator.

Keyword Arguments:

num_encoding_neighbors (int) –
How many closest neighbors consider when doing reductions. For instance, for three encoding neighbors reducing a value means three points in the original domain will be considered to estimate the value in the representation domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the original domain to the representation domain will be computed.
num_decoding_neighbors (int) –
How many closest neighbors consider when doing propagations. For instance, for three decoding neighbors propagating a value means three points in the representation domain will be considered to estimate the value in the original domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the representation domain back to the original domain will be computed.
release_encoding_neighborhoods (bool) –
A flag to enable releasing the encoding neighborhoods after building the representation. It can be used to save memory when the topological information of the encoding process will not be used after generating the representation.
threads (int) –
The number of threads to be used for parallel computations. Giving -1 means using all available cores.
representation_report_path (str) –
Path where a point cloud with the points in the representation space will be exported.

abstractmethod transform(X, F=None, y=None, out_prefix=None)

Transform the given point cloud to its sampled representation.

Note that any concrete point cloud sampler decorator implementation must provide its own logic for this method.

Parameters:

X – The structure space matrix (i.e., the matrix of coordinates).
F – The feature space matrix (i.e., the matrix of features).
y – The reference classes (i.e., the classification).
out_prefix – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The structure space matrix, the feature space matrix, and the classes vector of the sampled representation.

Return type:

tuple (np.ndarray, np.ndarray or None, np.ndarray or None)

transform_pcloud(pcloud, fnames=None, ignore_y=False, out_prefix=None)

Transform the given point cloud to its sampled representation.

Parameters:

pcloud (PointCloud) – The point cloud to be transformed.
fnames (None or list of str) – A list with the names of the features to be considered. If an empty list is given, no features will be considered. If None is given, all features will be considered.
ignore_y (bool) – Whether to ignore the classes (True) or to encode them in the representation (False).
out_prefix (None or str) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

A new point cloud that is a sampled representation of the input one.

Return type:

PointCloud

propagate(rep_x)

Propagate a representation on \(R\) back to the original space of \(m\) points.

Parameters:: rep_x (np.ndarray) – The representation to be propagated back to the original space. When given as a matrix, rows must be points and columns must be point-wise values.
Returns:: The propagated representation.
Return type:: np.ndarray

reduce(x)

Reduce the original space of \(m\) points to a representation space of \(R\) points.

Parameters:: x (np.ndarray) – The original values to be reduced to the representation space. When given as a matrix, rows must be points and columns must be point-wise values.
Returns:: The reduced values.
Return type:: np.ndarray

handle_encoding_neighbors(X, rep_X)

Compute the encoding neighbors, if necessary.

Parameters:

X (np.ndarray) – The input structure space.
rep_X (np.ndarray) – The sampled representation of the structure space.

Returns:

Nothing at all, but self.N is updated.

handle_decoding_neighbors(X, rep_X)

Compute the decoding neighbors, if necessary.

Parameters:

X (np.ndarray) – The input structure space.
rep_X (np.ndarray) – The sampled representation of the structure space.

Returns:

Nothing at all, but self.M is updated.

encode(F, y)

Encode the point-wise features and classes.

Parameters:

F (np.ndarray) – The input feature space matrix.
y (np.ndarray) – The input vector of classes.

Returns:

The encoded feature space matrix and point-wise classes vector. If any of them was given as None input, the returned one will also be None.

Return type:

tuple of np.ndarray

handle_encoding_neighborhoods_release()

Release the encoding neighborhoods if requested, i.e., if self.release_encoding_neighborhoods is True.

Returns:: Nothing, but self.N is set to None.

export_representation(rep_X, rep_F, rep_y, out_prefix=None)

Export the sampled representation of the point cloud.

Parameters:

rep_X (np.ndarray) – The structure space matrix of the sampled representation.
rep_F (np.ndarray) – The feature space matrix of the sampled representation.
rep_y (np.ndarray) – The point-wise classes vector of the sampled representation.
out_prefix (None or str) – The output prefix (OPTIONAL). If given, it will be used to particularize the output path.

Returns:

Nothing, but the sampled point cloud is exported to the representation report path.

encode_decode_release_and_export(X, F, y, rep_X, out_prefix=None)

Handle the encoding, decoding, release, and export stages. These are typical computed as a post-processing step after the computation of the sampled structure space.

Parameters:

X (np.ndarray) – The input structure space.
F (np.ndarray or None) – The input feature space.
y (np.ndarray or None) – The input point-wise classes.
rep_X (np.ndarray) – The sampled structure space.
out_prefix (str or None) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The feature space matrix and vector of points-wise classes obtained after encoding features and classes from the input point cloud into the sampled point cloud.

Return type:

tuple of np.ndarray