Add a knn module

[elisno]

Summary

This PR prioritizes a refactoring of the two modules

• cleanlab/outlier.py
• cleanlab/datalab/internal/issue_manager/duplicate.py

that rely heavily on a knn object (NearestNeighbors) for scoring and flagging different kinds of issues.

MERGE THIS AFTER #1115 !

Included docs

More information

The logic for constructing a NearestNeighbor object has been duplicated in several places like so:

# Make sure features exist to fit a knn object
if features is None:
    raise ValueError(
        "Both knn and features arguments cannot be None at the same time. Not enough information to compute outlier scores."
    )

# Select a good value for the number of neighbors
if k is None:
    k = DEFAULT_K  # use default when knn and k are both None
N, M = features.shape
if k > N:  # Ensure number of neighbors less than number of examples
    raise ValueError(
        f"Number of nearest neighbors k={k} cannot exceed the number of examples N={len(features)} passed into the estimator (knn)."
    )

# Select a decent distance metric
if M > 3:  # use euclidean distance for lower dimensional spaces
    metric = "cosine"
elif N > 100:  # Use efficient implementation (numerically unstable in edge cases)
    metric = "euclidean"
else:  # Use scipy implementation for precise results
    metric = euclidean

# Construct the knn object
knn = NearestNeighbors(n_neighbors=k, metric=metric).fit(features)

This PR reduces this headache to a single function call, as this is usually some boilerplate code for creating a knn-object from scratch.

knn: NearestNeighbors = features_to_knn(features, n_neighbors=k)  # Optionally, specify a metric

---

Additionally, there are some dev docs for module added in the new directory cleanlab/internal/neighbor. Those are not a priority and can be omitted in this PR.

[codecov]

Codecov Report

Attention: Patch coverage is 96.03960% with 4 lines in your changes are missing coverage. Please review.

Project coverage is 96.05%. Comparing base (81af417) to head (402d3fe).
Report is 3 commits behind head on master.

❗ Current head 402d3fe differs from pull request most recent head bda30f2. Consider uploading reports for the commit bda30f2 to get more accurate results

Files	Patch %	Lines
cleanlab/internal/neighbor/knn_graph.py	93.33%	1 Missing and 1 partial ⚠️
cleanlab/internal/neighbor/search.py	75.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1117      +/-   ##
==========================================
- Coverage   96.13%   96.05%   -0.09%     
==========================================
  Files          76       80       +4     
  Lines        6088     6102      +14     
  Branches     1081     1075       -6     
==========================================
+ Hits         5853     5861       +8     
- Misses        140      143       +3     
- Partials       95       98       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[elisno]

This condition won't evaluate to True, because even if the metric changed, then the knn object must have been given the same metric in this part of the code.

Removing it is safe.

[jwmueller]

Looks good to me overall, except the remaining comments I've left.
Leaving final merge to @huiwengoh (I don't want to review this again)

@elisno Before you ping Hui Wen for the final review, please address all of my remaining comments, comment on them how they are addressed, and only then mark them as Resolved.

[elisno]

I've addressed the comments made by @jwmueller. @huiwen could you review + merge this?

[huiwengoh]

lgtm! nice work