k-Nearest Neighbors APIs#

k-Nearest Neighbors for Classification#

class aoclda.nearest_neighbors.knn_classifier(n_neighbors=5, weights='uniform', algorithm='brute', metric='euclidean', precision='double')#

A k-Nearest Neighbors (k-NN) classifier.

Parameters
  • n_neighbors (int, optional) – The number of nearest neighbors. Default = 5.

  • weights (str, optional) – The weight function used for prediction. Available options are ‘uniform’ and ‘distance’. Default = ‘uniform’.

  • algorithm (str, optional) – The underlying algorithm used to compute the k-nearest neighbors. Only option is ‘brute’. This argument is included as a placeholder for more algorithms.

  • metric (str, optional) – The metric used for the distance computation. Available metrics are ‘euclidean’ and ‘sqeuclidean’ (squared euclidean distances). Default = ‘euclidean’.

  • precision (str, optional) – Whether to initialize the k-NN object in double or single precision. It can take the values ‘single’ or ‘double’. Default = ‘double’.

fit(X, y)#

Fit the k-NN classifier from the training data set provided.

Parameters
  • X (numpy.ndarray) – The feature matrix on which to fit the model. Its shape is (n_samples, n_features).

  • y (numpy.ndarray) – The vector with the corresponding labels. Its shape is (n_samples).

Returns

Returns the instance itself.

Return type

self (object)

kneighbors(X, n_neighbors=0, return_distance=True)#

Compute the indices of the nearest neighbors for each test data point, and optionally the corresponding distances.

Parameters
  • X (numpy.ndarray) – The test data for which the nearest neighbors are required. Its shape is (n_queries, n_features).

  • n_neighbors (int, optional) – The number of neighbors. If this is less or equal to zero, the number of neighbors set while fitting the model will be used instead.

  • return_distance (bool, optional) – Denotes whether to return the distances or not. Default=True.

Returns

The matrix with the corresponding

distances to each neighbor. Only returned if return_distance=True.

numpy.ndarray of shape (n_queries, n_neighbors): The matrix with the indices to

each neighbor.

Return type

numpy.ndarray of shape (n_queries, n_neighbors)

predict(X)#

Compute the predicted labels for the test data.

Parameters

X (numpy.ndarray) – The test data for which the nearest neighbors are required. Its shape is (n_queries, n_features).

Returns

The predicted labels of the test data.

Return type

numpy.ndarray of shape (n_queries)

predict_proba(X)#

Compute the probability estimates for each of the available classes.

Parameters

X (numpy.ndarray) – The test data for which the nearest neighbors are required. Its shape is (n_queries, n_features).

Returns

The class probabilities of the test data. Classes are sorted in ascending order.

Return type

numpy.ndarray of shape (n_queries, n_classes)

da_status da_knn_set_training_data_s(da_handle handle, da_int n_samples, da_int n_features, const float *X_train, da_int ldx_train, const da_int *y_train)#
da_status da_knn_set_training_data_d(da_handle handle, da_int n_samples, da_int n_features, const double *X_train, da_int ldx_train, const da_int *y_train)#

Pass a data matrix and a label array to the da_handle object in preparation for computing a k-NN.

The data itself is not copied; a pointer to the data matrix is stored instead.

After calling this function you may use the option setting APIs to set options.

Parameters
  • handle – [inout] a da_handle object, initialized with type da_handle_knn.

  • n_samples – [in] number of observations in X_train.

  • n_features – [in] number of features in X_train.

  • X_train – [in] array containing n_samples \(\times\) n_features data matrix, in column-major format.

  • ldx_train – [in] leading dimension of X_train. Constraint: ldx_train \(\ge\) n_samples.

  • y_train – [in] array containing the n_samples labels.

Returns

da_status. The function returns:

da_status da_knn_kneighbors_s(da_handle handle, da_int n_queries, da_int n_features, const float *X_test, da_int ldx_test, da_int *n_ind, float *n_dist, da_int k, da_int return_distance)#
da_status da_knn_kneighbors_d(da_handle handle, da_int n_queries, da_int n_features, const double *X_test, da_int ldx_test, da_int *n_ind, double *n_dist, da_int k, da_int return_distance)#

Compute k-Nearest Neighbors (k-NN)

Compute the k-NN of a test data \(X_{test}\) with respect to the data matrix previously passed into the handle using da_knn_set_training_data_?.

Parameters
  • handle – [inout] a da_handle object, initialized with type da_handle_knn.

  • n_queries – [in] number of observations in X_test.

  • n_features – [in] number of features in X_test. Constraint: n_features \(=\) the number of features in the data matrix originally supplied to da_knn_set_training_data_?.

  • X_test – [in] array containing n_queries \(\times\) n_features data matrix, in column-major format.

  • ldx_test – [in] leading dimension of X_test. Constraint: ldx_test \(\ge\) n_queries.

  • n_ind – [out] array containing the n_queries \(\times\) k matrix, with the indices of the k - nearest neighbors of the test data X_test. If k \(\le\) 0, the number of neighbors passed during the option setting will be used instead.

  • n_dist – [out] array containing the corresponding distances to the neighbors whose indices are stored in n_ind, if return_distance is 1.

  • k – [in] number of nearest neighbors requested. If k \(\le\) 0, the number of neighbors passed during the option setting will be used instead. Constraint: If k \(\le\) n_features.

  • return_distance – [in] denotes if the distances to the k-NN need be computed. If return_distance is 1, the distances are returned.

Returns

da_status. The function returns:

da_status da_knn_classes_s(da_handle handle, da_int *n_classes, da_int *classes)#
da_status da_knn_classes_d(da_handle handle, da_int *n_classes, da_int *classes)#

Get number of the distinct class labels.

Request the number of different class labels provided in the training data so that memory is allocated correctly for computing the class probabilities of a test data set.

Parameters
  • handle – [inout] a da_handle object, initialized with type da_handle_knn.

  • n_classes – [inout] the number of different classes. If n_classes \(\le\) 0, the number of different classes will be returned and classes will not be referenced.

  • classes – [out] ordered array that holds the different classes.

Returns

da_status. The function returns:

da_status da_knn_predict_proba_s(da_handle handle, da_int n_queries, da_int n_features, const float *X_test, da_int ldx_test, float *proba)#
da_status da_knn_predict_proba_d(da_handle handle, da_int n_queries, da_int n_features, const double *X_test, da_int ldx_test, double *proba)#

Compute probability estimates using k-Nearest Neighbors.

Compute the probability estimates for the different classes based on the k-NN of a test data \(X_{test}\) with respect to the data matrix data matrix previously passed into the handle using da_knn_set_training_data_?.

Parameters
  • handle – [inout] a da_handle object, initialized with type da_handle_knn.

  • n_queries – [in] number of observations in X_test.

  • n_features – [in] number of features in X_test. Constraint: n_features \(=\) the number of features in the data matrix originally supplied to da_knn_set_training_data_?.

  • X_test – [in] array containing n_queries \(\times\) n_features data matrix, in column-major format.

  • ldx_test – [in] leading dimension of X_test. Constraint: ldx_test \(\ge\) n_queries.

  • proba – [out] array of size n_queries \(\times\) n_classes containing the probability estimates for each of the available classes.

Returns

da_status. The function returns:

da_status da_knn_predict_s(da_handle handle, da_int n_queries, da_int n_features, const float *X_test, da_int ldx_test, da_int *y_test)#
da_status da_knn_predict_d(da_handle handle, da_int n_queries, da_int n_features, const double *X_test, da_int ldx_test, da_int *y_test)#

Compute estimated labels of a data set using k-Nearest Neighbors.

Compute the estimated labels based on the k-NN of a test data \(X_{test}\) with respect to the data matrix data matrix previously passed into the handle using da_knn_set_training_data_?.

Parameters
  • handle – [inout] a da_handle object, initialized with type da_handle_knn.

  • n_queries – [in] number of observations in X_test.

  • n_features – [in] number of features in X_test. Constraint: n_features \(=\) the number of features in the data matrix originally supplied to da_knn_set_training_data_?.

  • X_test – [in] array containing n_queries \(\times\) n_features data matrix, in column-major format.

  • ldx_test – [in] leading dimension of X_test. Constraint: ldx_test \(\ge\) n_queries.

  • y_test – [out] array of size n_queries containing the estimated label for each query.

Returns

da_status. The function returns: