Support build of "adaptive" kernel graphs

[darribas]

Under the weights framework, one can build a kernel W with adaptive bandwidth (example from the book:

# Build weights with adaptive bandwidth
w_adaptive = weights.distance.Kernel.from_dataframe(
    sub_30, fixed=False, k=15
)

The fixed=False flag is not supported under Graph and it'd be useful to have it available (e.g., for gwlearn, cc' @martinfleis). A proposed analogue API could be:

# Build weights with adaptive bandwidth
w_adaptive = graph.Graph.build_kernel(
    sub_30.centroid, fixed=False, k=15
)

[FirePheonix]

hey @darribas I'd be very happy to work upon this..

what we can do is add a fixed=True (default): current behaviour, global bandwidth h=max(d_knn)
and
fixed=False: per observation bandwidth, h i = distance to i's k-th neighbour

this will lead to a:

Graph.build_kernel(
    data,
    kernel="gaussian",
    k=None,
    fixed=True, # <- new parameter
    bandwidth=None,
    ...
)

The kernel functions already work element-wise so no changes needed there.
The error case fixed=False, k=None would raise a clear ValueError since adaptive bandwidth has no meaning without a k-NN structure.

this would make the proposed API work exactly as suggested:

w_adaptive = graph.Graph.build_kernel(
    sub_30.centroid, fixed=False, k=15
)

will need a test case too (maybe)

@martinfleis would this direction work ?
or can there be a better API for this?

[martinfleis]

If we add a new keyword, then you are specifying the same parameter (bandwidth) using two arguments as both bandwidth and fixed would control it with no clear priority. I would implement this by allowing bandwidth="adaptive". That way we don't need to add a keyword and have a clear API with no confusion.

[FirePheonix]

yep, you're right..
i saw we already have a bandwidth="auto"
bandwidth="adaptive" would slot right in alongside it.

Implementation could be straightforward then :
when bandwidth="adaptive" and k is set, compute per-observation bandwidths as h i = distance to i's k-th neighbour, otherwise raise a ValueError. No new keyword needed.

may i raise a PR for this? alongside a test case?

[FirePheonix]

Fixed bandwidth (default)
Graph.build_kernel(sub_30.centroid, k=15)

Adaptive bandwidth (Martin's suggestion)
Graph.build_kernel(sub_30.centroid, k=15, bandwidth="adaptive")

[martinfleis]

Go ahead if you have time. There is code for adaptive bandwidth in gwlearn though there might be easier, lower-level, solutions.