gflow

Explore how scalar fields rise, form basins, and change together on a graph. gflow helps you follow peaks, overlapping supports, and trajectories in structured data, and compare local changes between fields.

Two peaks, one hierarchy. The plateau peak is born at height 3 and joins the higher peak at height 1. The tree records this relationship; its branch lifetimes are in field units, not significance scores. Reproduce the figure · Start an analysis · Explore the example graphs

Install with help and guides

This is the unreleased 0.2.0 development package. Build from a source checkout with R, a C++17 compiler, GNU make, and Pandoc (also supplied with RStudio). R >= 4.1.0 and dgraphs >= 0.2.0 are required. The graph boundary supports both the published 0.2.0 list API and the tested 0.3.0.9000 object API.

git clone https://github.com/pgajer/gflow.git
cd gflow
make install-user

This installs missing core/build R dependencies, generates function help, builds all four vignettes, installs the source archive, and checks the installed introduction. It uses your current R library configuration. For a library you control, create a directory and set R_LIBS_USER before running the command. Optional viewers and archived modeling packages are not needed for this route.

Then, in R:

help("gflow-package", package = "gflow")
vignette("function-guide", package = "gflow")

A plain Git/local installation that skips the Makefile's documentation step can omit generated help and rendered guides. Use the route above, or install a source archive produced by make build. See installation details for manual steps, library selection, and optional OpenMP toolchains.

A first result

This small example reproduces the structure in the opening figure. Each adjacency entry has an aligned list of edge lengths; the field has one value per vertex in the same order.

library(gflow)
adjacency <- list(2L, c(1L, 3L), c(2L, 4L), c(3L, 5L),
                  c(4L, 6L), c(5L, 7L), 6L)
edge_lengths <- lapply(adjacency, function(v) rep(1, length(v)))
field <- c(0, 3, 3, 1, 2, 4, 0)
bc <- create.basin.complex(
  adjacency, edge_lengths, field,
  method = "superlevel_merge_tree", direction = "max"
)
get.basin.table(bc)[, c("extremum.vertex", "persistence", "raw.support.size")]

Peak vertex	Persistence (field units)	Raw support (vertices)
2 (plateau at 2–3)	2	2
6	4	7

The root support includes the younger branch, so these supports overlap. Change the field and reconstruct bc to see how the hierarchy changes.

summary(bc)                         # Rankings, coverage, and diagnostics
get.basin.membership(bc)             # Raw overlapping membership
get.basin.assignment(bc)             # Current single labels, when available
plot(bc, view = "merge_tree", type = "tree",
     label = "extremum.vertex", show.mass = FALSE, show.support = FALSE)

For graph maps, supply drawing coordinates to plot(bc, view = "assignment", coordinates = xy) or view = "overlap". plot(bc) shows the input field against vertex index. A drawing does not change the analysis.

Choose the next task

Task	Start with	Guide
Choose a basin definition	create.basin.complex()	Canonical workflow
Understand overlap, cuts, and refinement	get.basin.*(), cut(), summary()	Paths, grids, and disconnected graphs
Follow trajectories or extend coordinates	construct.madag(), compute.harmonic.extension()	Task map
Compare local changes between fields	lcor(), lslope(), lslope.neighborhood()	Noisy-circle workflow

Function reference · Full task and API catalog · Guide sources · Release notes

All four guides are installed locally. Use browseVignettes("gflow") for the index and help("gflow-migration", package = "gflow") for migration advice. Loading the package stays quiet.

Package boundaries

Build graphs with dgraphs, then supply adjacency and aligned edge lengths. gflow owns basin/flow analysis and local association. Layout and interactive viewers are optional and separate. Retired response-smoothing estimators are archived in gflowx.

gfcor() and gfassoc.membership() currently require compatible archived basin objects and reject canonical basin_complex inputs. They are not a continuation of the new-analysis example above. See REFERENCE.md and the migration guide.

Development and documentation

make document
make audit-api-guide
make check
make audit-final-acceptance

To rebuild the website from a matching installed archive, install pkgdown and run make website with the same R_ENV library selection used to install that archive. Generated pages live in build/site/; maintained installation notes in docs/ are preserved. See the documentation build guide.

The developer map locates implementations, scientific regression tests, ownership records, and resource limits.