maxent_model: Maximum-entropy ecological network model

In metaweave: Spatial Ecological Network Inference

Maximum-entropy ecological network model

Description

Experimental: this backend remains available in MetaWeave 1.0, but its degree-sequence sampler and scientific interpretation are not part of the stable 1.x API. Review the constraints and sampling limits below before using its output for inference.

Constructs a directed network inference backend that generates binary adjacency matrices under hard structural constraints and returns their marginal species-pair probabilities. Rows are consumers, columns are resources, and matrix[i, j] = 1 means consumer i uses resource j.

Usage

maxent_model(
  row_group,
  column_group = row_group,
  constraint = c("connectance", "links", "degree_sequence"),
  connectance = NULL,
  links = NULL,
  out_degree = NULL,
  in_degree = NULL,
  ensemble_size = 100L,
  self_links = FALSE,
  seed = 1L,
  burn_in = 1000L,
  thin = 100L,
  keep_ensemble = FALSE
)

Arguments

row_group	Assemblage group represented by matrix rows (consumers).
column_group	Assemblage group represented by matrix columns (resources). May equal row_group for a directed unipartite food web.
constraint	One of "connectance", "links", or "degree_sequence".
connectance	Desired connectance in ⁠[0, 1]⁠. Converted to an exact local link count with round(connectance * allowed_dyads).
links	Exact number of interactions in every local ensemble member.
out_degree	Row sums (numbers of resources per consumer).
in_degree	Column sums (numbers of consumers per resource). Degree constraints may be named numeric vectors or functions accepting the locally present species names and returning a numeric vector.
ensemble_size	Number of adjacency matrices used for marginal probabilities.
self_links	Whether a species may interact with itself when its name appears in both groups.
seed	Integer seed. A cell identifier is added to this seed so spatial cells receive distinct reproducible ensembles. The previous global random state is restored after inference. Use NULL to use normal R RNG behavior.
burn_in	Number of degree-preserving swap proposals before recording a degree-constrained ensemble.
thin	Number of swap proposals between recorded matrices.
keep_ensemble	Store binary ensemble members in network metadata.

Details

For constraint = "connectance" or "links", networks are sampled uniformly from all allowed adjacency matrices with exactly the requested number of links. This is the maximum-entropy distribution under a hard link count. For constraint = "degree_sequence", a feasible matrix is found by maximum flow and randomized with degree-preserving checkerboard swaps. This is an approximate uniform MCMC ensemble conditional on the supplied margins. The degree-preserving swap chain has no built-in convergence diagnostic; burn_in and thin count proposals, not accepted swaps. Marginal probabilities from this route should be checked for sensitivity to these settings and to the seed.

The implementation follows the constrained, minimally biased ensemble rationale of Banville, Gravel & Poisot (2023), but does not yet implement their SVD-entropy objective or simulated-annealing optimizer.

Value

An inference_model compatible with infer_network() and infer_networks().

References

Banville F, Gravel D, Poisot T (2023). What constrains food webs? A maximum entropy framework for predicting their structure with minimal biases. PLOS Computational Biology 19: e1011458. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1371/journal.pcbi.1011458")}

Examples

assemblage <- new_assemblage(list(food_web = c("a", "b", "c")))
model <- maxent_model(
  row_group = "food_web",
  constraint = "connectance",
  connectance = 0.25,
  ensemble_size = 50,
  self_links = FALSE,
  seed = 42
)
network <- infer_network(assemblage, model)
network$matrix

metaweave documentation built on Nov. 3, 2026, 9:06 a.m.