Package {metaweave}

MetaWeave: spatial ecological network inference

Description

Reconstruct local assemblages from distributions, infer ecological networks with pluggable models, simulate observations, summarize network properties, and map the results.

Author(s)

Maintainer: Gabriel Munoz gmunozacevedo@proton.me (Affiliation: Concordia University) [copyright holder]

Authors:

• Gabriel Munoz gmunozacevedo@proton.me (Affiliation: Concordia University) [copyright holder]

See Also

Useful links:

• https://github.com/fgabriel1891/metaweave

• Report bugs at https://github.com/fgabriel1891/metaweave/issues

Add standard metrics to network collection

Description

Add standard metrics to network collection

Usage

add_network_metrics(x, threshold = NULL)

Arguments

Value

A network_collection with summary columns appended to index; see summarize_networks().

Assemble local communities from aligned distribution rasters

Description

Assemble local communities from aligned distribution rasters

Usage

assemble_communities(distributions, min_species = 1L)

Arguments

Value

A list of assemblage objects, one per cell meeting min_species in every group. Nonzero, nonmissing raster values indicate presence; the list is empty if no cell qualifies.

Construct a generic stochastic block model backend

Description

Construct a generic stochastic block model backend

Usage

block_model(
  row_lookup,
  column_lookup,
  theta,
  row_group,
  column_group,
  species_col = "species",
  guild_col = "guild"
)

Arguments

Value

An inference_model with subclass block_model. Prediction returns a probability network using the supplied block assignments and probabilities; no model fitting is performed. Unmatched local species are listed in metadata$excluded_rows and metadata$excluded_columns.

Build a species range stack

Description

Build a species range stack

Usage

build_range_stack(
  source,
  template,
  species_col = NULL,
  species_keep = NULL,
  region = NULL,
  touches = TRUE
)

Arguments

Value

A terra::SpatRaster with named species layers, optionally cropped and filtered to the region.

Create a standard raster grid

Description

Create a standard raster grid

Usage

create_standard_grid(
  extent = c(-180, 180, -90, 90),
  resolution = 1,
  crs = "EPSG:4326"
)

Arguments

Value

A terra::SpatRaster with the requested extent, resolution, and coordinate reference system.

Examples

create_standard_grid(c(0, 2, 0, 2), resolution = 1)

Crop a stack and remove species absent from the region

Description

Crop a stack and remove species absent from the region

Usage

crop_filter_stack(stack, region, return_cropped = TRUE)

Arguments

Value

A terra::SpatRaster containing layers with nonmissing cells in the crop region. Zero values count as nonmissing; this helper expects presence/NA range rasters.

Compatibility wrapper for spatial network downscaling

Description

Compatibility wrapper for spatial network downscaling

Usage

downscale_networks(
  palm_stack,
  mammal_stack,
  palm_lookup,
  mammal_lookup,
  theta,
  species_col = "species",
  guild_col = "guild",
  min_palms = 1L,
  min_mammals = 1L
)

Arguments

Value

A network_collection with local probability networks, cell index, and raster template.

Infer a network for one assemblage

Description

Infer a network for one assemblage

Usage

infer_network(assemblage, model)

Arguments

Value

The ecological_network returned by the model prediction function.

Infer networks for many assemblages

Description

Infer networks for many assemblages

Usage

infer_networks(assemblages, model, template = NULL)

Arguments

Value

A network_collection containing one network per assemblage and an index with cell_id, x, and y columns. An empty input returns a zero-network collection with a zero-row index.

Convert an interaction table to a matrix

Description

Convert an interaction table to a matrix

Usage

interaction_table_to_matrix(data, row_col, column_col, value_col, fill = 0)

Arguments

Value

A numeric matrix with row and column species names. Unspecified pairs receive fill; repeated pairs use the last supplied value.

Examples

records <- data.frame(plant = c("a", "b"), animal = c("x", "x"), p = c(0.8, 0.3))
interaction_table_to_matrix(records, "plant", "animal", "p")

List ESRI shapefiles

Description

List ESRI shapefiles

Usage

list_shapefiles(path, recursive = FALSE)

Arguments

Value

A character vector of shapefile paths, empty if no matches are found.

Build one local generic block-model network directly

Description

Build one local generic block-model network directly

Usage

local_block_network(
  rows,
  columns,
  row_lookup,
  column_lookup,
  theta,
  row_group = "rows",
  column_group = "columns",
  species_col = "species",
  guild_col = "guild",
  cell_id = NA_integer_
)

Arguments

Value

A numeric probability matrix with species row and column names.

Build one local palm-mammal probability network directly

Description

Compatibility wrapper around local_block_network().

Usage

local_probability_network(
  palms,
  mammals,
  palm_lookup,
  mammal_lookup,
  theta,
  species_col = "species",
  guild_col = "guild",
  cell_id = NA_integer_
)

Arguments

Value

A numeric palm-by-mammal probability matrix.

Create a bounding-box polygon

Description

Create a bounding-box polygon

Usage

make_bbox(extent, crs = "EPSG:4326")

Arguments

Value

A polygon terra::SpatVector representing the bounding box.

Map cell metrics back to rasters

Description

Map cell metrics back to rasters

Usage

map_metrics(x, metrics = NULL)

Arguments

Value

A spatial_result with a multilayer terra::SpatRaster in data, one layer per requested metric, and metric names in metrics.

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

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. 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

Compatibility alias returning metric rasters

Description

Compatibility alias returning metric rasters

Usage

network_metrics_raster(x, metrics = NULL)

Arguments

Value

A terra::SpatRaster with one layer per requested metric.

Construct a local assemblage

Description

Construct a local assemblage

Usage

new_assemblage(species, cell_id = NA_integer_, coordinates = NULL)

Arguments

Value

An assemblage list with species, cell_id, and coordinates.

Examples

new_assemblage(list(plants = c("a", "b"), animals = "x"), cell_id = 1)

Construct a distribution collection

Description

Construct a distribution collection

Usage

new_distribution_collection(data, guild = NULL, metadata = NULL)

Arguments

Value

A distribution_collection list with data (the raster), guild, and metadata.

Construct an ecological network

Description

Construct an ecological network

Usage

new_ecological_network(
  matrix,
  type = c("probability", "binary", "weighted", "observed"),
  metadata = list(),
  row_group = "rows",
  column_group = "columns",
  directed = FALSE,
  self_links = NA
)

Arguments

Value

An ecological_network list with matrix, type, metadata, row_group, column_group, directed, and self_links; also inherits from the type-specific network class.

Construct a pluggable inference model

Description

Construct a pluggable inference model

Usage

new_inference_model(
  predict,
  name = "custom",
  parameters = list(),
  subclass = NULL
)

Arguments

Value

An inference_model list containing name, predict, and parameters, with the optional subclass prepended.

Construct a collection of spatial ecological networks

Description

Construct a collection of spatial ecological networks

Usage

new_network_collection(networks, index, template = NULL, settings = list())

Arguments

Value

A network_collection list with networks, index, template, and settings. Each index row corresponds to one network.

Construct a spatial result

Description

Construct a spatial result

Usage

new_spatial_result(data, metrics = names(data))

Arguments

Value

A spatial_result list with the spatial object in data and metric names in metrics.

Prepare palm and mammal range stacks

Description

Prepare palm and mammal range stacks

Usage

prepare_range_stacks(
  palm_source,
  mammal_source,
  mammal_species_col,
  mammal_species_keep = NULL,
  template = create_standard_grid(),
  region = NULL,
  output_dir = NULL,
  touches = TRUE
)

Arguments

Value

A list with palms and mammals, each a terra::SpatRaster. If output_dir is supplied, RDS files are also written there.

Print a MetaWeave object

Description

Prints a compact summary of an assemblage, distribution collection, ecological network, inference model, or network collection. The object is returned invisibly. These methods are normally called through print().

Usage

## S3 method for class 'assemblage'
print(x, ...)
## S3 method for class 'distribution_collection'
print(x, ...)
## S3 method for class 'ecological_network'
print(x, ...)
## S3 method for class 'inference_model'
print(x, ...)
## S3 method for class 'network_collection'
print(x, ...)

Arguments

Value

The input object, returned invisibly after printing a compact summary.

Construct a species-level probability-matrix model

Description

Use this backend when an external model returns probabilities for named species pairs directly, including ensemble-averaged predictions for which no single coherent block partition exists.

Usage

probability_matrix_model(
  probability_matrix,
  row_group,
  column_group,
  name = "species probability matrix"
)

Arguments

Value

An inference_model with subclass probability_matrix_model. Prediction subsets the supplied matrix to locally present, matched species. Unmatched local species are listed in the resulting network's metadata$excluded_rows and metadata$excluded_columns.

Examples

p <- matrix(c(0.8, 0.3), 2, dimnames = list(c("a", "b"), "x"))
model <- probability_matrix_model(p, "plants", "animals")
site <- new_assemblage(list(plants = "a", animals = "x"))
infer_network(site, model)$matrix

Experimental rarefied network metric

Description

Simulates standardized count matrices and evaluates a user-supplied metric function. This helper is experimental in MetaWeave 1.0; its metric and random-number behavior are outside the stable 1.x API.

Usage

rarefied_network_metric(
  prob_mat,
  target_size = 100L,
  metric,
  n_per_level = 10L,
  seed = NULL
)

Arguments

Value

A numeric mean of the supplied metric across simulated count matrices, with missing metric values omitted.

Rasterize one range file

Description

Rasterize one range file

Usage

rasterize_range_file(shp_file, template, touches = TRUE)

Arguments

Value

A one-layer terra::SpatRaster, named from the file stem, with 1 for presence and NA for background.

Rasterize rows grouped by species

Description

Rasterize rows grouped by species

Usage

rasterize_range_rows(
  x,
  template,
  species_col,
  species_keep = NULL,
  touches = TRUE
)

Arguments

Value

A terra::SpatRaster with one named layer per retained species, using 1 for presence and NA for background.

Reconstruct spatial networks from arbitrary distribution groups

Description

Reconstruct spatial networks from arbitrary distribution groups

Usage

reconstruct_networks(distributions, model, min_species = 1L)

Arguments

Value

A network_collection of locally inferred networks with a spatial template and cell index.

Complete compatibility workflow

Description

Complete compatibility workflow

Usage

run_network_downscaling(...)

Arguments

Value

A list with result (a summarized network_collection) and rasters (a terra::SpatRaster of metrics).

Run generic spatial ecological-network inference

Description

Run generic spatial ecological-network inference

Usage

run_spatial_inference(distributions, model, min_species = 1L, threshold = NULL)

Arguments

Value

A list with result (a summarized network_collection) and spatial (a spatial_result containing metric rasters).

Construct the original palm-mammal SBM backend

Description

Compatibility wrapper around block_model().

Usage

sbm_model(
  palm_lookup,
  mammal_lookup,
  theta,
  species_col = "species",
  guild_col = "guild"
)

Arguments

Value

A block-model inference_model using group names palms and mammals.

Simulate an interaction-count matrix

Description

Simulate an interaction-count matrix

Usage

simulate_interaction_counts(network, size = 100L, seed = NULL)

Arguments

Value

An integer matrix with the input dimensions and names. Counts sum to size when positive probability mass exists; otherwise all entries are zero.

Simulate a network

Description

Simulate a network

Usage

simulate_network(network, size = 100L, seed = NULL)

Arguments

Value

A weighted ecological_network containing simulated interaction counts and the source network in its metadata.

Summarize one ecological network

Description

Summarize one ecological network

Usage

summarize_network(network, threshold = NULL)

Arguments

Value

A one-row data frame with row_richness, column_richness, possible_links (number of eligible matrix entries), expected_links (sum of eligible entries, or number at least threshold), and mean_probability (mean of eligible nonmissing entries). For networks with self_links = FALSE, pairs with the same species name are excluded. Unnamed same-group square networks use the diagonal; unnamed networks across different groups require species names. Other inputs use all matrix entries, including missing entries in the possible-link count. Missing values are omitted from sums and means. Without eligible entries the mean is NA; if all are missing it is NaN. For weighted/observed networks these fields summarize weights, not link probabilities; use threshold to count entries at or above a cutoff.

Examples

p <- matrix(c(0.8, 0.3), 2)
summarize_network(p)
summarize_network(p, threshold = 0.5)

Summarize a collection of networks

Description

Summarize a collection of networks

Usage

summarize_networks(x, threshold = NULL)

Arguments

Value

The input network_collection with summary columns appended to its index; see summarize_network() for column definitions. A zero-network collection receives the same five columns with zero rows.