dgraphs
Data-Derived Graph Construction Utilities
Constructs data-derived graphs from numerical observations using
mutual, shared-neighbor, intersection, geodesic, radius, adaptive-radius,
minimum-spanning-tree completion, Fermat-distance, and optional iterated
adaptive neighborhood methods. Provides graph conversion, pruning,
diagnostics, spectral embedding, endpoint detection, and path utilities,
including intrinsic Euclidean distances on the max-normalized compositional
simplex. Includes reproducible synthetic geometries, point sampling, and an
optional interactive graph explorer. The graph constructions include methods
described by Jarvis and Patrick (1973)
dgraphs
dgraphs constructs and analyzes graphs derived from numerical observations.
It includes mutual and shared-neighbor graphs, intersection and geodesic
nearest-neighbor graphs, radius and adaptive-radius graphs, minimum-spanning-tree
completion, and Fermat-distance graphs. It also provides graph conversion,
pruning, diagnostics, spectral embedding, endpoint and path utilities, intrinsic
simplex distances, and reproducible synthetic geometries and point sampling.
Optional tools include iterated adaptive neighborhood (IAN) graphs and an
interactive graph explorer.
Installation
This README describes dgraphs 0.4.1, a planned patch update to CRAN release 0.4.0. The patch fixes native handling of empty vectors and matrices without changing the API. See NEWS for release notes and migration guidance from 0.2.0.
Install the published release from CRAN and check its version:
install.packages("dgraphs")
library(dgraphs)
packageVersion("dgraphs")
Until 0.4.1 is published, this installs CRAN release 0.4.0. For local testing of
the patch, build its source archive with make build from this checkout, then
install it in a fresh R session:
install.packages("build/dgraphs_0.4.1.tar.gz", repos = NULL, type = "source")
library(dgraphs)
packageVersion("dgraphs") # 0.4.1
Source installation requires a C++17 toolchain (Rtools on Windows or Xcode command-line tools on macOS). Building the source archive with its offline guides also requires knitr, rmarkdown and Pandoc. The geometry galleries have static fallbacks. To include interactive 3D views, install these optional packages from CRAN before building the archive:
install.packages(c("ivue", "htmlwidgets", "rgl"))
IAN graphs
create.ian.graph() builds a Gabriel graph and adapts its neighborhoods, preserving
connectivity by default. It returns the initial and final graphs, local scales,
affinities and diagnostics. IAN uses an optional backend; setup currently supports
macOS arm64 and needs Python 3, native Cargo/Rust and Apple's C++ tools.
backend <- build.ian.backend("ian-build") # New directory; explicit one-time setup.
X <- rbind(c(0, 0), c(1, 0), c(2, 0))
fit <- create.ian.graph(X, backend = backend)
if (!fit$complete) stop(fit$error$message)
graph.edges(fit$initial_graph)
graph.edges(fit$final_graph)
fit$diagnostics$connectivity$protected.edges
Keep the returned backend path for later calls. Ordinary package installation does
not compile the optional Rust backend. See vignette("ian-graphs") and
help("build.ian.backend") for setup, reference options, duplicate handling and
resource limits. Successful graph construction does not establish biological or
predictive usefulness.
Example
library(dgraphs)
set.seed(1)
x <- matrix(rnorm(80), ncol = 2)
graph <- create.mknn.graph(x, k = 4)
nrow(graph.edges(graph))
For standard graph examples, choose a type with create.graph():
chain <- create.graph("chain", n = 10, span = 2, labels = 101:110)
circle <- create.graph("circle", n = 20, sampling = "uniform",
edge.length = "chord")
graph.edges(chain)
circle$metadata$coordinates
Other types are "empty", "complete", "cycle", "complete_bipartite",
"star" and "random". Type-specific arguments are documented together in
help("create.graph") and the function guide.
Distances, stored routes, and plotting share the graph representation:
D <- graph.geodesic.distances(chain, vertices = c(1, 10))
paths <- create.path.graph(chain, h.values = c(2, 5))
get.shortest.path(paths[["h_5"]], from = 10, to = 1)
xy <- plot(chain, vertex.values = seq_len(graph.order(chain)))
plot(chain, coordinates = xy, vertex.colors = "navy")
For an end-to-end introduction to graph construction, connectivity repair, parameter sequences, conversion, and diagnostics, run:
vignette("data-derived-graph-workflow", package = "dgraphs")
Guides
- Finding your way around dgraphs: choose an entry point by task and browse the complete public-function catalog.
- Synthetic geometry and point sampling: create reproducible curves, surfaces and compositions, then build graphs.
- Constructing and Diagnosing Data-Derived Graphs: compare graph families, connectivity repair and geodesic diagnostics.
The installed guides also cover IAN graphs, Fermat distances, surface examples, and the effects of sampling density and curvature. List all available guides or open individual ones with:
vignette(package = "dgraphs")
vignette("function-guide", package = "dgraphs")
vignette("synthetic-geometry", package = "dgraphs")
vignette("fermat-density-curvature", package = "dgraphs")
Synthetic geometry
Version 0.4.0 adds reusable surfaces, curves and point samplers. For example, construct a graph on a quadratic saddle:
surface <- synthetic.quadform(2, 3, list(diag(c(1, -1))))
points <- sample.synthetic.geometry(surface,
synthetic.sampling.uniform.disk(1), n = 100, seed = 4101)
graph <- create.sknn.graph(points$predictors, k = 6, connect.components = FALSE)
The figure uses the exact seed and sample above. Edges carry Euclidean chord
lengths, not surface geodesic lengths. Color represents height, from blue
(low) through cream to red (high). In the source checkout,
dev/build-readme-figure.R generates the figure and defines the labeled
perspective view. The full geometry gallery
compares forms, sampling densities, coordinate frames and dimensions.
Geometry-only samples contain coordinates, geometric metadata and reproducible
random-state information. Statistical truth, responses, named recipe registries
and dataset identities remain in geosmooth. The development Geometry Lab app
is documented in dev/apps/embedding-explorer/README.md; it is not installed
with the R package.
Graph Reconstruction Explorer
Open saved graph reconstruction benchmarks with dgraphs::explore.graphs().
The optional app dependencies are shiny, bslib, plotly, and digest.
Use explore.graphs(project = run_directory) to open an existing benchmark,
or remember it with register.graph.project(run_directory, name = "My study").
The no-argument launcher presents your saved projects. Scientific data stay
outside the package; opening them does not rerun analysis. grip is needed only
when you explicitly generate a missing weighted layout.
Start with the bundled twelve-point circle comparison:
install.packages(c("shiny", "bslib", "plotly", "digest"))
demo <- system.file("extdata", "graph-explorer-demo", package = "dgraphs")
benchmark <- read.graph.benchmark(demo)
explore.graphs(demo)
Compare k = 2 and k = 4: extra chords increase error relative to exact circle
arcs. Both graph layouts and metric tables are saved, so this demonstration
needs no fitting or project registration. The default display preserves
coordinate proportions, with labeled x/y/z axes. See ?explore.graphs for
project paths and cache controls.