Expose `igraph_degree_correlation_vector()` as `knnk()`

[Copilot]

Exposes the C function igraph_degree_correlation_vector() to compute the k_nn(k) degree correlation function, which gives the mean degree of neighbors for vertices with degree k. This is a primary metric for characterizing degree correlations in networks.

Changes

• New function knnk() in R/structural-properties.R

  • Wraps existing degree_correlation_vector_impl() with user-facing API
  • Parameters: from.mode, to.mode control in/out degree computation in directed graphs
  • Parameter: directed.neighbors controls whether edges are treated as directed or reciprocal
  • Supports weighted graphs via weights parameter
  • Includes parameter validation via match.arg()

• Documentation

  • Comprehensive roxygen2 docs with mathematical notation and scientific references
  • Examples for ring, star, scale-free, and directed graphs
  • Links to Network Science textbook chapter on degree correlations

• Tests covering undirected/directed graphs, weighted graphs, parameter modes, and consistency with existing knn() function

Usage

# Basic usage
g <- make_ring(10)
knnk(g)
# [1] NaN NaN   2

# Directed graph with fine-grained control
g <- sample_pa(100, directed = TRUE)
knnk(g, from.mode = "out", to.mode = "in")

# Weighted graph
g <- make_star(5)
E(g)$weight <- c(1, 2, 3, 4)
knnk(g)

Note: Unlike knn() which returns results starting at degree 1, knnk() includes degree 0 at index 1, matching the C API convention where knnk[d] contains the value for degree d.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Expose igraph_degree_correlation_vector()</issue_title> <issue_description>What is the feature or improvement you would like to see?

Expose igraph_degree_correlation_vector().

This function computes the $k_{nn}(k)$ function, which can already be computed by knn(), even for a subset of vertices.

In comparison to knn(), igraph_degree_correlation_vector() gives more fine grained control over how in/out degrees are used, but it does not allow restricting the computation to a subset of vertices. This is fine, as such a restriction would rarely be needed and would require a special interpretation.

I recommend exposing this as a new function called knnk().

Use cases for the feature

The $k_{nn}(k)$ function is one of the primary way to characterize degree correlations. This is useful both for teaching and practical network analysis.

References

• https://networksciencebook.com/chapter/7#measuring-degree </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes igraph/rigraph#1801

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[krlmlr]

@copilot: Merge main and obey the updated agent instructions.