Native R Implementation of Connectome Influence Calculator

Create an InfluenceCalculator object using native R implementations. This provides a fast, pure R alternative to the Python implementation.

Usage

influence_calculator_r(
  edgelist_simple = NULL,
  meta = NULL,
  filename = NULL,
  sqlite = FALSE,
  signed = FALSE,
  count_thresh = 3,
  const = 24,
  inhibitory_nts = NULL,
  excluded_nts = NULL,
  lambda_max = 0.99,
  syn_weight_measure = c("norm", "count"),
  neg_neurotransmitters = NULL
)

Arguments

edgelist_simple

Data frame with edge list containing columns 'pre', 'post', 'count', and optional 'norm'. If 'norm' is absent it is computed from 'count' as count / sum(count) per post. Required when sqlite = FALSE.

meta

Data frame with metadata containing at least 'root_id' column. Must also contain 'top_nt' when signed = TRUE or excluded_nts is given. Required when sqlite = FALSE.

filename

Character. Path to SQLite database file. Used when sqlite = TRUE.

sqlite

Logical. Whether to load data from SQLite database (default: FALSE).

signed

Logical. Whether to use signed connectivity matrix (default: FALSE). When TRUE, inhibitory_nts must be supplied.

count_thresh

Numeric. Minimum threshold count for postsynaptic connections (default: 3).

const

Constant value added to log(influence) to ensure non-negative adjusted influence scores. Should be set to -log(minimum_accepted_influence) where minimum_accepted_influence is the smallest influence value considered meaningful. Default 24 corresponds to minimum_accepted_influence = exp(-24) ~ 3.78e-11.

inhibitory_nts

Character vector of top_nt values whose pre-neurons should receive negative weights when signed = TRUE. The library has no per-organism default; you must supply this set explicitly when signed = TRUE. Common conventions: c("glutamate", "gaba", "serotonin", "octopamine") for Drosophila, "gaba" for C. elegans (only ACh and GABA have unambiguous signs there).

excluded_nts

Character vector of top_nt values whose pre-neurons should contribute nothing to W: their outgoing edges are dropped entirely. Independent of signed. Use this for transmitter classes whose sign at a given target depends on the receptor mix (e.g. dopamine, serotonin in C. elegans) and so cannot be assigned a single sign safely.

lambda_max

Numeric in (0, 1). Target spectral radius of the rescaled connectivity matrix W~; controls how much the leading recurrent mode of (I - W~)^-1 is amplified (gain = 1/(1 - lambda_max)). The default 0.99 gives a 100x gain – appropriate for whole-CNS Drosophila (BANC-scale) graphs where you want sensitivity to weak distal influence. Lower values (e.g. 0.5, 2x gain) damp the leading mode and expose per-target seed specificity at the cost of attenuating long polysynaptic effects – more appropriate for smaller graphs like C. elegans. Treat it as a "reverb knob": near 1 a signal echoes through long indirect paths; near 0.5 it mostly traverses short paths.

syn_weight_measure

Character, one of "norm" (default) or "count". Which edge column populates the connectivity matrix W: "count" is the raw synapse count, "norm" is the per-postsynaptic input fraction (count / sum(count) per post; recomputed from count if absent). The default "norm" matches the Python backend as exposed through influence_calculator_py(). For signed = TRUE, "count" is the more natural choice: negating "norm" weights breaks the column-sum-to-1 property and loses the input-normalisation interpretation.

neg_neurotransmitters

Deprecated (renamed to inhibitory_nts). Still accepted for backwards compatibility but emits a warning.

Value

InfluenceCalculatorR object (R6 class)

Examples

if (FALSE) { # \dontrun{
# C. elegans convention (small graph; lower lambda_max)
ic <- influence_calculator_r(
  edgelist_simple = my_edges,
  meta = my_meta,
  signed = TRUE,
  inhibitory_nts = "gaba",
  excluded_nts = c("glutamate", "dopamine", "serotonin", "octopamine"),
  lambda_max = 0.5
)

# Drosophila / BANC convention (whole-CNS; default lambda_max)
ic <- influence_calculator_r(
  edgelist_simple = banc_edges,
  meta = banc_meta,
  signed = TRUE,
  inhibitory_nts = c("glutamate", "gaba", "serotonin", "octopamine")
)

# Calculate influence for specific seed neurons
results <- ic$calculate_influence(seed_ids = c(123, 456))
} # }