PressPurt: network sensitivity to press perturbations under interaction uncertainty [version 1; peer review: awaiting peer review]

While the use of networks to understand how complex systems respond to perturbations is pervasive across scientific disciplines, the uncertainty associated with estimates of pairwise interaction strengths (edge weights) remains rarely considered. Mischaracterizations of interaction strength can lead to qualitatively incorrect predictions regarding system responses as perturbations propagate through often counteracting direct and indirect effects. Here, we introduce PressPurt, a computational package for identifying the interactions whose strengths must be estimated most accurately in order to produce robust predictions of a network's response to press perturbations. The package provides methods for calculating and visualizing these edge-specific sensitivities (tolerances) when uncertainty is associated to one or more edges according to a variety of different error distributions. The software requires the network to be represented as a numerical (quantitative or qualitative) Jacobian matrix evaluated at stable equilibrium. PressPurt is open source under the MIT license and is available as both a Python package and an R package hosted at https://github.com/dkoslicki/PressPurt and on the CRAN repository https://CRAN.R-project.org/package=PressPurt.


Introduction
Networks have become a routine tool for representing the complex systems that pervade biology, technology and society. While the development of methods for inferring network topology remains a dominant focus, 18,19,[21][22][23][24] numerous methods are now also being advanced for quantifying the weights (fluxes and interaction strengths) of the edges between pairs of nodes (genes, metabolites, species) in different network types. 1,5,7,9,10 Motivating advances is the desire to predict how systems respond to perturbations wherein the concentration or process rates of a subset of nodes is chronically altered by external forces. 2,28 Examples of such perturbations include gene knock-downs, fisheries harvest, and the administering of antibiotics. 17,20,25,27 Predictive insight into perturbation effects nevertheless remains hard to obtain. This is true even when a network's topology is fixed and precisely specified because edge weights are always subject to estimation error and empirical variation. Because of the many, often counteracting pathways through which perturbations travel, these uncertainties rapidly compound. 16,26 In many cases, therefore, predicting even just the qualitative sign pattern by which nodes respond to perturbations (i.e. whether concentrations increase, decrease, or remain unchanged) is of desirable interest. 6,14,17 Here we introduce PressPurta collection of computational tools designed to shed light on the qualitative and quantitative response of a network to press perturbations when there is uncertainty in the magnitude of edge weights. The PressPurt package is written to implement in a usable form the theoretical results established in Ref. 11. PressPurt is designed to identify the most sensitive interactions within the network which must be estimated most accurately to produce robust predictions of press perturbation responses.

Scope
PressPurt is designed to analyze networks whose dynamics may be described by a system of differential equations of is a function describing the interactions between node i and a vector of other nodes, N i is node i's concentration, and u i is a scalar representing a constant rate of external input to (or removal from) node i (a so-called press perturbation, sensu Ref. 2). Other forms of press perturbation may be represented in a similar manner. 17 For input, PressPurt requires only a single CSV file representing the so-called Community Matrix 12 : the Jacobian of the system evaluated at a stable equilibrium point, . PressPurt begins by determining how a press perturbation on each node j is predicted to alter the equilibrium concentration of each node i by calculating the Net Effects matrix without interaction strength uncertainty, ∂Ni ∂u j ¼ ÀA À1 ij .
6,17,26 Uncertainties in the elements of A that alter the sign structure of ÀA À1 are the cause of qualitative mispredictions. 26 Network sensitivity with single edge uncertainty PressPurt can quantify the effects of interaction strength uncertainty in a single edge, independent of uncertainty in all other edges. To do so, the user specifies the kind of distribution and parameterization that describes interaction strength uncertainties. Currently, options include the uniform, truncated normal, truncated log normal, and beta distributions. Within the specified distribution, PressPurt finds the range of uncertainty values that permits the system to remain asymptotically stable, then returns a matrix in CSV format whose k,l ð Þ th entry gives the expected (average) fraction of qualitative/sign changes in the net effects matrix resulting from the interaction uncertainty associated with edge k,l ð Þ. PressPurt can produce a visualization of the exact number of sign switches that are incurred as a function of uncertainty magnitude for a given edge (Figure 1b), as well as a heat map visualization of all edges depicting the fraction of possible sign switches that are incurred by uncertainty in each edge (Figure 1c). The overall sensitivity of the network when interaction uncertainty is considered one edge at a time is also returned as a percent of all n 2 possible mispredictions.
Similar computation and visualization functions are provided to measure the quantitative response of the network when interaction strength uncertainties are at their stability-limited values. In this context the actual magnitude change in the net effects matrix is computed, as opposed to just quantifying sign-changes in the net effects matrix.
Network sensitivity with multiple edge uncertainty PressPurt can also quantify the effects of interaction strength uncertainty when it is associated with multiple edges simultaneously. This is achieved via Monte Carlo sampling where uncertainties are presumed to follow a uniform distribution of a user-specified length. The fraction of samples that contain a qualitative misprediction in the net effects matrix is then reported.

Implementation
PressPurt is available as both a Python package and an R package hosted at https://github.com/dkoslicki/ PressPurt and on the CRAN repository https://CRAN.R-project.org/package=PressPurt. These provide complete documentation of all functions, as well as detailed installation instructions, quick start and use tutorials with example data (i.e. Jacobian matrices).

Operation
The PressPurt Python package is dependent on the Python packages numpy, scipy, matplotlib, sympy, pathos and pandas. The PressPurt R package is dependent on Python for its symbolic toolbox and uses the R package reticulate to communicate with Python. Thus Python, as well as its dependent packages, must be installed. It also depends on the R packages data.table, ggplot2, grid, gridExtra and utils, primarily for the convenience of their efficient data manipulation and visualization functions.

Use case
For input, PressPurt requires only a single CSV file representing either a quantitative or qualitatively-specified Jacobian matrix and the specification of a desired error distribution for the edge weight uncertainties. The three steps of an analysis entail: (1) preprocessing the Jacobian matrix, (2) computing the entry-wise or multi-entry perturbation expectations for either qualitative or quantitative sensitivities, and (3) visualizing the results. In R, for example, determining and visualizing the qualitative entry-wise sensitivities of a four-species intraguild predation module (whose Jacobian matrix 11  is provided in PressPurt as IGP.csv) involves three commands. First, infile <-system.file("extdata", "Modules", "IGP.csv", package = "PressPurt") PreProsMatrix <-PreprocessMatrix (input_file = infile max_bound = 10, zero_perturb = FALSE, threads = 2) which returns information that includes, for each non-zero edge, their asymptotic stability intervals and values that would lead to a sign switch in the net effects matrix. Second, Entrywise <-ComputeEntryWisePerturbationExpectation ( PreProsMatrix = PreProsMatrix, distribution_type = "truncnorm", input_a = 0, input_b = -2, threads = 1) which specifies a truncated normal distribution of edge weight uncertainties with mean 0 and variance 2 (a negative value indicates that the standard deviation is to be the scaled to each edge weight) and whose output includes a matrix containing the consequent which produces Figure 2 that overlays visualizations of the assumed uncertainty distribution associated with each edge weight and the consequent number of qualitative mispredictions (sign switches) that a given magnitude of edge weight uncertainty will incur in the net effects matrix as a whole.

Summary
The measures of sensitivity that PressPurt implements are exact and may be computed with relative ease and computational efficiency. PressPurt thereby obviates the need for what are typically computationally expensive simulations whose results can be difficult to interpret when assessing the sources of mispredictions in complex networks. Underlying these advances is the separation of uncertainty magnitudes from their frequency distributions (Figure 1b) License: MIT Figure 2. Visualization produced by the R package function GenerateEntryWiseFigures depicting the assumed uncertainty distribution associated with each non-zero Jacobian element in a four-species intraguild predation network (grey distributions) and the consequent number of qualitative mispredictions (sign switches) that a given magnitude of uncertainty in each element will incur in the net effects matrix of the network as a whole (black lines).