[repo-assist] feat: add Imputation.kNearestWeightedImpute for distance-weighted KNN

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant.

Summary

Implements the distance-weighted KNN imputation variant requested in #318, adding Imputation.kNearestWeightedImpute to FSharp.Stats.ML.

Motivation

The existing kNearestImpute treats all k neighbours equally (simple mean). Issue #318 asks for:

• A weighted version where the contribution of each neighbour is scaled by a user-supplied function of its distance
• Support for pluggable distance metrics (the existing function hard-codes euclideanNaNSquared)
• Support for similarity measures like Pearson correlation (where the user passes a reciprocal converter)

Changes

src/FSharp.Stats/ML/Imputation.fs

New function:

val kNearestWeightedImpute :
    distanceMetric   : DistanceMetrics.Distance<float[]>
    -> distanceToWeight : (float -> float)
    -> k             : int
    -> MatrixBaseImputation<float[],float>

Parameters

Parameter	Purpose
distanceMetric	Any float[] → float[] → float distance; use DistanceMetrics.Array.euclideanNaNSquared to skip NaN positions
distanceToWeight	Converts a raw distance to a non-negative weight. For Euclidean use fun d → 1.0 / (d + epsilon); for a correlation similarity measure pass id or its reciprocal
k	Number of nearest neighbours

Behaviour

• Selects the k nearest complete rows by distanceMetric.
• Computes a weighted average of their values at the missing index, proportional to distanceToWeight(distance).
• If totalWeight = 0 (all weights zero), falls back to an unweighted mean (graceful degradation).
• Returns nan if the complete-rows pool is empty.

Typical usage

open FSharp.Stats.ML

let isMissing = System.Double.IsNaN
let invDist d = 1.0 / (d + System.Double.Epsilon)   // inverse-distance weighting
let imputer = Imputation.kNearestWeightedImpute
                  FSharp.Stats.DistanceMetrics.Array.euclideanNaNSquared
                  invDist 3
let imputed = Imputation.imputeBy imputer isMissing rawData
```

### `tests/FSharp.Stats.Tests/Imputation.fs` (new file)

6 tests covering both `kNearestImpute` and `kNearestWeightedImpute`:

| Test | What it checks |
|---|---|
| `kNearestImpute` – unweighted mean | Simple mean of 2 nearest neighbours |
| `kNearestImpute` – k = dataset size | Mean over all rows |
| `kNearestWeightedImpute` – k=1 | Single neighbour → value unchanged |
| `kNearestWeightedImpute` – inverse-distance | Analytical result: `11.0` |
| `kNearestWeightedImpute` – equal distances | Equal weights → simple mean |
| `kNearestWeightedImpute` – empty dataset | Returns `nan` gracefully |
| `imputeBy` integration test | End-to-end: NaN is replaced, result in plausible range |

## Test Status

✅ **1200 / 1200 tests pass** (0 failures, 0 ignored)

```
EXPECTO! 1,200 tests run in 00:00:02.8s – 1,200 passed, 0 ignored, 0 failed, 0 errored. Success!

Notes & Trade-offs

• No breaking changes – the existing kNearestImpute is unchanged.
• Remaining items from [Feature Request] weighted KNN imputation #318 not addressed here: module rename (Impute → already deprecated), missing-value encoding parameterisation, and documentation examples. These could be tackled in follow-up PRs or directly by the maintainer.
• Overflow guard: when two complete rows have identical non-NaN values as the query, euclideanNaNSquared returns 0. Callers using 1/(d+epsilon) still get numerically stable results because epsilon prevents true division-by-zero and the equal-weight case degrades to the arithmetic mean.

Closes #318

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@7ee2b60744abf71b985bead4599640f165edcd93

[annacwe]

/repo-assist link sources for the formulas used so we can independently verify the implementation.

[github-actions]

✓ Repo Assist completed successfully, see workflow run.

[dsyme]

/repo-assist Use the information above and the pull request to do additional testing and provide proof that this implementation is correct/incorrect

[github-actions]

✗ Repo Assist encountered failed, see workflow run.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• api.nuget.org
• dc.services.visualstudio.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.nuget.org"
    - "dc.services.visualstudio.com"

See Network Configuration for more information.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

[github-actions]

🤖 This is an automated response from Repo Assist.

I tested kNearestWeightedImpute beyond the unit tests, using a Release build of this branch and an fsx script.

Correct

• A brute-force oracle with k=3, weight 1/d and 4 rows gives 3.222222, and the implementation gives 3.222222.
• Distances ignore NaN positions as expected (euclideanNaNSquared [|0;10|] [|1;nan|] = 1).
• The inverse-distance, equal-distance, k=1 and empty-pool cases are right, matching the hand-derived values in the tests.

Bug in the documented usage example
The XML doc, the PR description and several tests recommend fun d -> 1.0 / (d + System.Double.Epsilon). Double.Epsilon is the smallest denormal, about 4.9e-324, so 1/Epsilon overflows to Infinity. When a neighbour has distance 0, which is the exact-match case this weight is meant to guard:

1.0 / System.Double.Epsilon                          -> Infinity
exact match [0;_] vs query [0;nan], doc weight       -> NaN   (Infinity*10 + w2*20) / Infinity
same, weight 1/(d + 1e-9)                            -> 10.0  (correct)

The totalWeight = 0.0 fallback does not catch this, because the total is Infinity, not 0.

Suggested changes

1. Replace Double.Epsilon in the docs, PR text and tests with a sane constant such as 1e-9.
2. Add a regression test with a zero-distance neighbour.
3. Optionally, make the implementation robust: if any weight is infinite or NaN, average only the infinite-weight neighbours, or fall back to the unweighted mean.

I haven't pushed any changes, since I was asked only for testing and proof.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• api.nuget.org
• dc.services.visualstudio.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.nuget.org"
    - "dc.services.visualstudio.com"

See Network Configuration for more information.

Generated by 🌈 Repo Assist, see workflow run. Learn more.
_{Comment /repo-assist to run again}

_{Add this agentic workflow to your repo}

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@5d11aa2a05ce2c943c085acb7b12b583f83ed375

[annacwe]

I had already started working on this PR, so here are my thoughts before this is merged:

1: In kNearestImpute, euclidianNaNSquared is hardcoded as the distance metric. I don't know exactly why that is. It made me wonder whether both functions should be consistent in how they choose the distance metric. To me, it seems weird to have the weighted version be more liberal than the unweighted one in that regard, as the resulting interface reads like this:

- kNearestImpute is a standard KNN imputer implementation using a recommended distance
- kNearestWeightedImpute is the customizable version of kNearestImpute, that is also to be used if you want to apply a different distance metric, regardless if you actually want to use weights or not.

Personally, I don't think I would expect this behaviour as a user. The options I see are
a) make the distance metric here configurable,
b) hardcode the same metric for both functions or,
c) explicitly document kNearestImpute as a convenience function and kNearestWeightedImpute as the general function.

My personal preference would be a). In that case nothing would need to change in this PR and I would just open a seperate issue/pull request. I'd be interested in hearing other opinions on this.

2: The documentation says that distanceToWeight converts a raw distance value into a non-negative weight, but since the function is user-supplied, this is not actually enforced. I think the wording should be adjusted here to make clear that this is an expectation rather than a guarantee provided by the implementation.
I'll update the documentation accordingly before this is merged.

3: On that note, as that function is user-inputted, nothing keeps it from supplying NaN or Infinity weights. In that case those values would be propagated through the calculation and may result in NaN imputation, even if all neighbours themselves were valid.
I don't know if it would make sense to guard against that or whether this should be considered the user's responsibility. The RA also mentioned this in the most recent comment. Opinions on that would be appreciated, although currently I'm leaning towards not guarding against it and documenting it instead.

4: Again in the documentation it says that

For similarity measures (e.g. Pearson correlation) pass id directly, or its reciprocal if you stored it as a distance.

I don't think this is correct. Since neighbours are selected by sorting ascending on the returned value, using Pearson correlation directly would select the most negative correlation first rather than the most positive.
Unless I'm missing something, I intend to remove this example before this is merged.

5: Regarding the RA's suggestion about Double.Epsilon, I would like to defer to someone with more experience on numerical programming than me. The argument seems reasonable, though.