Package 'PathwaySpace' reference manual

Title:	Spatial Projection of Network Signals along Geodesic Paths
Description:	For a given graph containing vertices, edges, and a signal associated with the vertices, the 'PathwaySpace' package performs a convolution operation, which involves a weighted combination of neighboring vertices and their associated signals. The package uses a decay function to project these signals, creating geodesic paths on a 2D-image space. 'PathwaySpace' has various applications, such as visualizing network data in a graphical format that highlights the relationships and signal strengths between vertices. By combining graph theory, signal processing, and visualization, 'PathwaySpace' provides a way of representing graph data on a continuous projection space. Based on methods introduced in Tercan et al. (2025) <doi:10.1016/j.xpro.2025.103681> and Ellrott et al. (2025) <doi:10.1016/j.ccell.2024.12.002>.
Authors:	Sysbiolab Team [aut], Victor Apolonio [ctb], Jonathan Back [ctb], Lana Querne [ctb], Vinicius Chagas [ctb], Bahar Tercan [ctb], Mauro Castro [cre] (ORCID: <https://orcid.org/0000-0003-4942-8131>)
Maintainer:	Mauro Castro <[email protected]>
License:	Artistic-2.0
Version:	1.3.0
Built:	2026-05-24 16:06:49 UTC
Source:	https://github.com/sysbiolab/pathwayspace

Constructor of PathwaySpace-class Objects

Description

buildPathwaySpace is a constructor of PathwaySpace-class objects.

Usage

buildPathwaySpace(gs, nrc = 500, verbose = TRUE, g = deprecated())
buildPathwaySpace(gs, nrc = 500, verbose = TRUE, g = deprecated())

Arguments

gs

A GraphSpace object. Alternatively, an igraph object with node coordinates assigned to x and y vertex attributes, and node labels assigned to name vertex attribute.

nrc

A single positive integer indicating the number of rows and columns (in pixels) for a square image matrix. This argument will affect the resulting image size and resolution.

verbose

A logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

g

Deprecated from PathwaySpace 1.0.1; use 'gs' instead.

Value

A pre-processed PathwaySpace class object.

Author(s)

Sysbiolab Team

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Check graph validity
gs <- GraphSpace(gtoy1)

gs <- normalizeGraphSpace(gs)

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gs, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Check graph validity
gs <- GraphSpace(gtoy1)

gs <- normalizeGraphSpace(gs)

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gs, nrc = 100)
# note: adjust 'nrc' to increase image resolution

COSMIC-CGC genes mapped to PathwaySpace images

Description

A data frame listing 'GeneSymbol' and 'Entrez' IDs from the COSMIC-CGC database (Sondka et al., 2020). These genes are used to demonstrate the PathwaySpace's summit mapping pipeline, which assigns summits to an image space.

Usage

data(CGC_20211118)
data(CGC_20211118)

Format

data.frame

Value

A data.frame object.

Source

COSMIC-CGC database (release v95, tier 1 collection).

References

Sondka et al. The COSMIC Cancer Gene Census: describing genetic dysfunction across all human cancers. Nat Rev Cancer 18, 696-705, 2018. Doi: 10.1038/s41568-018-0060-1.

Examples

data(CGC_20211118)
data(CGC_20211118)

Circular Projection of Graph-Associated Signals

Description

circularProjection implements a convolution algorithm to project signals onto a 2D-coordinate system.

Usage

## S4 method for signature 'PathwaySpace'
circularProjection(
  ps,
  k = 8,
  decay.fun = weibullDecay(),
  aggregate.fun = signalAggregation(),
  rescale = TRUE,
  verbose = TRUE,
  pdist = deprecated()
)
## S4 method for signature 'PathwaySpace'
circularProjection(
  ps,
  k = 8,
  decay.fun = weibullDecay(),
  aggregate.fun = signalAggregation(),
  rescale = TRUE,
  verbose = TRUE,
  pdist = deprecated()
)

Arguments

ps

A PathwaySpace class object.

k

A single positive integer determining the k-top signals for the convolution operation.

decay.fun

A signal decay function. Available options include 'Weibull', 'exponential', and 'linear' (see weibullDecay). Users may also define a custom decay model with at least two arguments, e.g., function(x, signal) { ... }, which should returns a vector of projected signals of the same length as x. Additional arguments may include any variable available as a graph vertex attribute.

aggregate.fun

A function used to aggregate the projected signals. It must be provided as a unary function, e.g., function(x) { ... }, which should aggregate a vector of signals to a scalar value. Available options include 'mean', 'wmean', 'log.wmean', and 'exp.wmean' (See signalAggregation).

rescale

A logical value indicating whether to rescale the signal. If the signal >=0, then it will be rescaled to [0, 1]; if the signal <=0, then it will be rescaled to [-1, 0]; and if the signal in (-Inf, +Inf), then it will be rescaled to [-1, 1].

verbose

A logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

pdist

Deprecated as of PathwaySpace 1.0.2; this parameter is now passed internally through decay.fun.

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Create a 2D-landscape image
ps <- circularProjection(ps)

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Create a 2D-landscape image
ps <- circularProjection(ps)

Constructor of exponential decay functions

Description

The expDecay() constructor either creates a decay function or returns a ggplot object for visualizing the decay model. It is a utility function used internally by circularProjection and polarProjection.

Usage

expDecay(decay = 0.001, pdist = 0.15, plot = FALSE, demo.signal = 1)
expDecay(decay = 0.001, pdist = 0.15, plot = FALSE, demo.signal = 1)

Arguments

decay

A decay factor (in ⁠[0,1]⁠). This term indicates how much a signal decreases as a function of distance in pathway space. For example, at a specific distance defined by the pdist parameter, the signal intensity will be the initial signal multiplied by decay.

pdist

A distance normalization term (in (0, 1]) at which the signal reaches signal * decay. This parameter is used to anchor the decay to a meaningful distance (see details). Also, when pdist = 1, it will represent the diameter of the inscribed circle within the coordinate space of a PathwaySpace object.

plot

A logical value indicating whether to return a ggplot object.

demo.signal

A numeric value in ⁠[-Inf, Inf]⁠, only passed when plot = TRUE to visualize the decay curve with a specific signal intensity. The value is ignored by the function constructor, as the decay function itself is returned without using an initial signal.

Details

The expDecay() constructor creates an exponential decay model. It describes how a signal decreases as a function of distance, controlled by a decay rate parameter.

The decay function is defined as:

$y = signal \times decay^{\left(\frac{x}{pdist}\right)}$

where $signal$ represents the initial intensity, $decay$ controls the rate of attenuation, and $x$ is a vector of normalized distances. The $pdist$ parameter anchors the model such that:

$y = signal$ when $x = 0$
$y = signal \times decay$ when $x = pdist$

Value

Returns either a function of the form function(x, signal) { ... } or, if plot = TRUE, a ggplot object illustrating the decay model.

Author(s)

Sysbiolab Team

Examples

# Return a decay function
decay_fun <- expDecay(decay = 0.25, pdist = 0.5)

# Plot decay model parameters
# expDecay(decay = 0.25, pdist = 0.5, plot = TRUE)

# Return a decay function
decay_fun <- expDecay(decay = 0.25, pdist = 0.5)

# Plot decay model parameters
# expDecay(decay = 0.25, pdist = 0.5, plot = TRUE)

getNearestNode

Description

Retrieves the nearest neighbor for each node from a PathwaySpace object using Euclidean distance.

Usage

getNearestNode(ps)
getNearestNode(ps)

Arguments

ps

Either a PathwaySpace or GraphSpace object.

Examples

# See examples in the PathwaySpace's tutorials:
# https://sysbiolab.github.io/PathwaySpace/

# See examples in the PathwaySpace's tutorials:
# https://sysbiolab.github.io/PathwaySpace/

Accessors for Fetching Slots from a PathwaySpace Object

Description

getPathwaySpace retrives information from individual slots available in a PathwaySpace object.

Usage

## S4 method for signature 'PathwaySpace'
getPathwaySpace(ps, what = "status")
## S4 method for signature 'PathwaySpace'
getPathwaySpace(ps, what = "status")

Arguments

ps

A preprocessed PathwaySpace class object

what

A character value specifying which information should be retrieved from the slots. Options: "nodes", "edges", "graph", "image", "pars", "misc", "signal","projections", "status", "silhouette", "summits", "summit_mask", "summit_contour"

Value

Content from slots in the PathwaySpace object.

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Get the 'status' slot in ps
status <- getPathwaySpace(ps, what = 'status')

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Get the 'status' slot in ps
status <- getPathwaySpace(ps, what = 'status')

An image matrix

Description

An image matrix used for workflow demonstrations.

Usage

data(gimage)
data(gimage)

Format

matrix

Value

An image matrix.

Source

This package.

Examples

data(gimage)
data(gimage)

Accessor Functions for PathwaySpace Objects

Description

Get or set edge and vertex attributes in PathwaySpace class object.

Usage

## S4 replacement method for signature 'PathwaySpace'
gs_vertex_attr(x, name, ...) <- value

## S4 replacement method for signature 'PathwaySpace'
gs_edge_attr(x, name, ...) <- value
## S4 replacement method for signature 'PathwaySpace'
gs_vertex_attr(x, name, ...) <- value

## S4 replacement method for signature 'PathwaySpace'
gs_edge_attr(x, name, ...) <- value

Arguments

x

A PathwaySpace class object.

name

Name of the attribute.

...

Additional arguments passed to igraph methods.

value

The new value of the attribute.

Value

Updated PathwaySpace object.

Examples

data('gtoy1', package = 'RGraphSpace')
ps <- buildPathwaySpace(gtoy1, nrc = 100)

# Get vertex count
gs_vcount(ps)

# Get edge count
gs_ecount(ps)

# Access a specific vertex attribute
gs_vertex_attr(ps, "signal")

# Replace an entire vertex attribute
gs_vertex_attr(ps, "signal") <- 1

# Modify a single value within a vertex attribute
gs_vertex_attr(ps, "signal")["n1"] <- 1

# Access a specific edge attribute
gs_edge_attr(ps, "weight")

# Replace an entire edge attribute
gs_edge_attr(ps, "weight") <- 1

data('gtoy1', package = 'RGraphSpace')
ps <- buildPathwaySpace(gtoy1, nrc = 100)

# Get vertex count
gs_vcount(ps)

# Get edge count
gs_ecount(ps)

# Access a specific vertex attribute
gs_vertex_attr(ps, "signal")

# Replace an entire vertex attribute
gs_vertex_attr(ps, "signal") <- 1

# Modify a single value within a vertex attribute
gs_vertex_attr(ps, "signal")["n1"] <- 1

# Access a specific edge attribute
gs_edge_attr(ps, "weight")

# Replace an entire edge attribute
gs_edge_attr(ps, "weight") <- 1

A list with Hallmark gene sets (v2023.1)

Description

A list with Human gene symbols from the MSigDB's Hallmark gene set collection (Liberzon et al., 2015). These gene sets are used to demonstrate the PathwaySpace's summit mapping pipeline, which assigns summits to an image space.

Usage

data(Hallmarks_v2023_1_Hs_symbols)
data(Hallmarks_v2023_1_Hs_symbols)

Format

list

Value

A list object.

Source

MSigDB database (v2023.1).

References

Liberzon et al. The Molecular Signatures Database (MSigDB) hallmark gene set collection. Cell Systems 1(5):417-425, 2015 Doi: 10.1016/j.cels.2015.12.004

Examples

data(Hallmarks_v2023_1_Hs_symbols)
data(Hallmarks_v2023_1_Hs_symbols)

Constructor of linear decay functions

Description

The linearDecay() constructor either creates a decay function or returns a ggplot object for visualizing the decay model. It is a utility function used internally by circularProjection and polarProjection.

Usage

linearDecay(decay = 0.001, pdist = 0.15, plot = FALSE, demo.signal = 1)
linearDecay(decay = 0.001, pdist = 0.15, plot = FALSE, demo.signal = 1)

Arguments

decay

pdist

plot

A logical value indicating whether to return a ggplot object.

demo.signal

Details

The linearDecay() constructor creates a simple linear decay model. It describes how a signal decreases proportionally with distance.

The decay function is defined as:

$y = signal \times \left(1 - (1 - decay) \times \frac{x}{pdist}\right)$

where $signal$ represents the initial intensity, $decay$ defines the relative signal level at $pdist$ , and $x$ is a vector of normalized distances. The signal decreases uniformly from its initial value to $pdist$ , which is a reference distance that anchors the model such that:

$y = signal$ when $x = 0$
$y = signal \times decay$ when $x = pdist$

This makes the linear form consistent with the exponential and Weibull decay functions, both of which also reach $signal \times decay$ at the reference distance.

Value

Returns either a function of the form function(x, signal) { ... } or, if plot = TRUE, a ggplot object illustrating the decay model.

Author(s)

Sysbiolab Team

Examples

# Return a decay function
decay_fun <- linearDecay(decay = 0.5, pdist = 0.25)

# Plot decay model parameters
# linearDecay(decay = 0.5, pdist = 0.25, plot = TRUE)

# Return a decay function
decay_fun <- linearDecay(decay = 0.5, pdist = 0.25)

# Plot decay model parameters
# linearDecay(decay = 0.5, pdist = 0.25, plot = TRUE)

Calculate a pathway space distance between two vectors

Description

Calculate a pathway space distance between two vectors

Usage

pathDistances(gdist, from, to, nperm = 1000, verbose = TRUE)
pathDistances(gdist, from, to, nperm = 1000, verbose = TRUE)

Arguments

gdist

A distance matrix computed by the igraph's distances function. Rows and columns must be named with vertex labels as listed in the 'igraph' object.

from

A vector with valid vertex names.

to

A vector with valid vertex names.

nperm

Number of permutations.

verbose

A single logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

Value

A list with pathway space distances and a 'ggplot' object.

Examples


# Load a vertex-wise distance matrix (distance between nodes in a graph)
data("gdist.toy", package = "PathwaySpace")

# Get two vertex lists
from <- sample(colnames(gdist.toy), 50)
to <- sample(colnames(gdist.toy), 50)

# Calculate distances between lists, and between random lists
res <- pathDistances(gdist.toy, from, to)
names(res)
# "p_dist"  "z_score"

# Load a vertex-wise distance matrix (distance between nodes in a graph)
data("gdist.toy", package = "PathwaySpace")

# Get two vertex lists
from <- sample(colnames(gdist.toy), 50)
to <- sample(colnames(gdist.toy), 50)

# Calculate distances between lists, and between random lists
res <- pathDistances(gdist.toy, from, to)
names(res)
# "p_dist"  "z_score"

PathwaySpace: An S4 class for signal propagation on image spaces

Description

PathwaySpace: An S4 class for signal propagation on image spaces

Value

An S4 class object.

Slots

nodes: A data frame with xy-vertex coordinates.
edges: A data frame with edges.
graph: An igraph object.
image: A raster background image matrix.
pars: A list with parameters.
misc: A list with intermediate objects for downstream methods.
projections: A list with processed objects for downstream methods.
status: A vector containing the processing status of the PathwaySpace object.

Constructor

see buildPathwaySpace constructor.

Author(s)

Sysbiolab Team, Mauro Castro ([email protected])

A pruned and laid out igraph object from Pathway Commons V12

Description

This igraph object was created from a 'sif' file available from the Pathway Commons V12 (Rodchenkov et al., 2020), which was filtered to keep interactions from the following sources: CTD, Recon, HumanCyc, DrugBank, MSigDB, DIP, BioGRID, IntAct, BIND, and PhosphoSite. The igraph was additionally pruned and laid out by a force-directed algorithm aiming signal projection on PathwaySpace's images. Edges with the smallest betweenness centrality were pruned using 'backward elimination' and 'forward selection' strategies. The resulting graph represents the main connected component with the minimum number of edges.

Usage

data(PCv12_pruned_igraph)
data(PCv12_pruned_igraph)

Format

igraph

Value

An igraph object.

Author(s)

Chris Wong, Mauro Castro, and TCGA Network.

Source

Pathway Commons V12.

References

Rodchenkov et al. Pathway Commons 2019 Update: integration, analysis and exploration of pathway data. Nucleic Acids Research 48(D1):D489–D497, 2020. doi:10.1093/nar/gkz946

Examples

data(PCv12_pruned_igraph)
## Suggestion to vizualize this igraph in R:
library(RGraphSpace)
plotGraphSpace(PCv12_pruned_igraph)
data(PCv12_pruned_igraph)
## Suggestion to vizualize this igraph in R:
library(RGraphSpace)
plotGraphSpace(PCv12_pruned_igraph)

Accessory function to plot pathway space distances

Description

Accessory function to plot pathway space distances

Usage

plotPathDistances(pdist, z.transform = FALSE)
plotPathDistances(pdist, z.transform = FALSE)

Arguments

pdist

A list generated by the pathDistances function.

z.transform

A single logical value specifying to convert pathway distances into z-score values.

Value

A 'ggplot' object.

Examples


# Load a vertex-wise distance matrix (distance between nodes in a graph)
data("gdist.toy", package = "PathwaySpace")

# Get two gene lists
from <- sample(colnames(gdist.toy), 50)
to <- sample(colnames(gdist.toy), 50)

# Calculate distances between lists, and between random lists
res <- pathDistances(gdist.toy, from, to)

# Plot observed and null distances
plotPathDistances(res)

# Load a vertex-wise distance matrix (distance between nodes in a graph)
data("gdist.toy", package = "PathwaySpace")

# Get two gene lists
from <- sample(colnames(gdist.toy), 50)
to <- sample(colnames(gdist.toy), 50)

# Calculate distances between lists, and between random lists
res <- pathDistances(gdist.toy, from, to)

# Plot observed and null distances
plotPathDistances(res)

Plotting 2D-landscape images for the PathwaySpace package

Description

plotPathwaySpace is a wrapper function to create dedicated ggplot graphics for PathwaySpace-class objects.

Usage

## S4 method for signature 'PathwaySpace'
plotPathwaySpace(
  ps,
  colors = pspace.cols(),
  bg.color = "grey95",
  si.color = "grey85",
  si.alpha = 1,
  theme = c("th0", "th1", "th2", "th3"),
  title = "PathwaySpace",
  xlab = "Pathway coordinates 1",
  ylab = "Pathway coordinates 2",
  zlab = "Density",
  font.size = 1,
  font.color = "white",
  zlim = NULL,
  slices = 25,
  add.grid = TRUE,
  grid.color = "white",
  add.summits = TRUE,
  label.summits = TRUE,
  summit.color = "white",
  add.marks = FALSE,
  marks = NULL,
  mark.size = 3,
  mark.color = "white",
  mark.padding = 0.5,
  mark.line.width = 0.5,
  use.dotmark = FALSE,
  add.image = FALSE
)
## S4 method for signature 'PathwaySpace'
plotPathwaySpace(
  ps,
  colors = pspace.cols(),
  bg.color = "grey95",
  si.color = "grey85",
  si.alpha = 1,
  theme = c("th0", "th1", "th2", "th3"),
  title = "PathwaySpace",
  xlab = "Pathway coordinates 1",
  ylab = "Pathway coordinates 2",
  zlab = "Density",
  font.size = 1,
  font.color = "white",
  zlim = NULL,
  slices = 25,
  add.grid = TRUE,
  grid.color = "white",
  add.summits = TRUE,
  label.summits = TRUE,
  summit.color = "white",
  add.marks = FALSE,
  marks = NULL,
  mark.size = 3,
  mark.color = "white",
  mark.padding = 0.5,
  mark.line.width = 0.5,
  use.dotmark = FALSE,
  add.image = FALSE
)

Arguments

ps

A PathwaySpace class object.

colors

A vector of colors.

bg.color

A single color for background.

si.color

A single color for silhouette. (see silhouetteMapping).

si.alpha

A transparency level in ⁠[0, 1]⁠, used to adjust the opacity of the silhouette. This parameter is useful for improving the perception of a background image, when one is available.

theme

Name of a custom PathwaySpace theme. These themes (from 'th0' to 'th3') consist mainly of preconfigured ggplot settings, which the user can subsequently refine using ggplot2.

title

A string for the title.

xlab

The title for the 'x' axis of a 2D-image space.

ylab

The title for the 'y' axis of a 2D-image space.

zlab

The title for the 'z' axis of the image signal.

font.size

A single numeric value passed to plot annotations.

font.color

A single color passed to plot annotations.

zlim

The 'z' limits of the plot (a numeric vector with two numbers). If NULL, limits are determined from the range of the input values.

slices

A single positive integer value used to split the image signal into equally-spaced intervals.

add.grid

A logical value indicating whether to add gridlines to the image space. However, gridlines will only appear when the image is decorated with graph silhouettes (see silhouetteMapping).

grid.color

A color passed to geom_point.

add.summits

A logical value indicating whether to add contour lines to 'summits' (when summits are available; see summitMapping).

label.summits

A logical value indicating whether to label summits.

summit.color

A color passed to 'summits'.

add.marks

A logical value indicating whether to plot vertex labels.

marks

A vector of vertex names to be highlighted in the image space. This argument overrides 'add.labels'.

mark.size

A size argument passed to geom_text.

mark.color

A color passed to geom_text.

mark.padding

A box padding argument passed to geom_text_repel.

mark.line.width

A line width argument passed to geom_text_repel.

use.dotmark

A logical value indicating whether "marks" should be represented as dots.

add.image

A logical value indicating whether to add a background image, when one is available (see GraphSpace).

Value

A ggplot-class object.

Author(s)

Sysbiolab Team, Mauro Castro.

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# # Check graph validity
gs <- GraphSpace(gtoy1)

gs <- normalizeGraphSpace(gs)

# Create a PathwaySpace object
ps <- buildPathwaySpace(gs, nrc = 300)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Create a 2D-landscape image
ps <- circularProjection(ps, k = 2,
   decay.fun = weibullDecay(pdist = 0.4))

# Plot a 2D-landscape image
plotPathwaySpace(ps)

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# # Check graph validity
gs <- GraphSpace(gtoy1)

gs <- normalizeGraphSpace(gs)

# Create a PathwaySpace object
ps <- buildPathwaySpace(gs, nrc = 300)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Create a 2D-landscape image
ps <- circularProjection(ps, k = 2,
   decay.fun = weibullDecay(pdist = 0.4))

# Plot a 2D-landscape image
plotPathwaySpace(ps)

Polar transformation functions

Description

Creates polar transformation functions for polarProjection internal calls. These functions are used to adjusts signal decay according to point-to-edge angular distances, with options to attenuate angular shapes.

Usage

polarDecay(
  method = c("power", "gaussian", "logistic"),
  s = 0.5,
  k = 10,
  m = 0.5
)
polarDecay(
  method = c("power", "gaussian", "logistic"),
  s = 0.5,
  k = 10,
  m = 0.5
)

Arguments

method

String indicating the transformation to apply. Must be one of: "power", "gaussian", or "logistic".

s

Single numeric value in [0, 1]. Controls the spread around the x mean of the Gaussian function.

k

Single numeric value >=1. Controls the steepness of the logistic function.

m

Single numeric value in [0, 1]. Specifies the midpoint of the logistic function.

Details

The polar transformation controls how much the projected signal decays as a function of the angular distance between a point in pathway space and a reference edge axis. The function returned by polarDecay() expects two arguments, with the following signature: function(x, beta) { ... }.

Power:

$x^{\beta}$

where $x$ is a vector of normalized angular distances (in [0, 1]) and $beta$ is a non-negative exponent that controls the rate of signal decay. Increasing $beta$ results in a steeper decay rate, modulating the angular span of the projection.

Gaussian:

$\exp\left(-\frac{(1-x)^2}{2\sigma^2}\right)^{\beta}$

where $sigma$ controls the spread around the mean, creating fuzzier effect on projections.

Logistic:

$(1 / (1 + \exp(k (x - m))))^{\beta}$

where $k$ is the steepness and $m$ is the function's midpoint, making more gradual transitions.

These transformations are intended to be plugged into the higher-level polarProjection function, allowing user control over the polar projection profiles.

Value

Returns a function of the form: function(x, beta) { ... }, that applies the specified shape-based transformation.

Author(s)

Sysbiolab Team

Examples

polar.fun <- polarDecay("power")

polar.fun <- polarDecay("power")

Polar Projection of Graph-Associated Signals

Description

polarProjection implements a convolution algorithm to project signals across a 2D-coordinate system.

Usage

## S4 method for signature 'PathwaySpace'
polarProjection(
  ps,
  k = 2,
  beta = 10,
  decay.fun = weibullDecay(pdist = 1),
  aggregate.fun = signalAggregation(),
  polar.fun = polarDecay(),
  directional = FALSE,
  edge.norm = TRUE,
  rescale = TRUE,
  verbose = TRUE,
  theta = deprecated(),
  pdist = deprecated()
)
## S4 method for signature 'PathwaySpace'
polarProjection(
  ps,
  k = 2,
  beta = 10,
  decay.fun = weibullDecay(pdist = 1),
  aggregate.fun = signalAggregation(),
  polar.fun = polarDecay(),
  directional = FALSE,
  edge.norm = TRUE,
  rescale = TRUE,
  verbose = TRUE,
  theta = deprecated(),
  pdist = deprecated()
)

Arguments

ps

A PathwaySpace class object.

k

A single positive integer determining the k-top signals for the convolution operation.

beta

An exponent (in [0, +Inf)) used in the polar projection functions (see polarDecay). It controls the shape of the polar projection by modulating the angular span. For example, $beta = 0$ yields a circular projection, $beta = 1$ produces a cardioid-like shape, and beta > 1 progressively narrows the projection along a reference edge axis.

decay.fun

aggregate.fun

polar.fun

A polar decay function (see polarDecay).

directional

If directional edges are available, this argument can be used to orientate the signal projection on directed graphs.

edge.norm

Scale distances based on edge lengths (when edge.norm=TRUE) or based on full coordinate space (when edge.norm=FALSE).

rescale

verbose

A logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

theta

Deprecated as of PathwaySpace 1.0.2; use 'beta' instead.

pdist

Deprecated as of PathwaySpace 1.0.2; this parameter is now passed internally through decay.fun.

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

Examples

# Load a demo igraph
data('gtoy2', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy2, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Set edge weight
# gs_edge_attr(ps, "weight") <- c(-1, 1, 1, 1, 1, 1)

# Create a 2D-landscape image
ps <- polarProjection(ps, pdist=1)

# Load a demo igraph
data('gtoy2', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy2, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Set edge weight
# gs_edge_attr(ps, "weight") <- c(-1, 1, 1, 1, 1, 1)

# Create a 2D-landscape image
ps <- polarProjection(ps, pdist=1)

A simple vector of colors for PathwaySpace images

Description

A simple vector of colors for PathwaySpace images

Usage

pspace.cols(n = 25, ...)
pspace.cols(n = 25, ...)

Arguments

n

The number of colors to generate in the output palette.

...

Additional arguments (not used).

Value

A vector with hexadecimal color codes.

Examples

pspace.cols()

pspace.cols()

Create interpolated color palettes for PathwaySpace images

Description

Creates mixed color palettes by interpolating and offsetting hues, useful for generating transitions between hues.

Usage

pspace.pals(
  colors = c("#303f9d", "#578edb", "#63b946", "#f3930c", "#a60d0d"),
  trim.colors = c(3, 2, 1, 2, 3),
  offset = 0.5,
  n = 25
)
pspace.pals(
  colors = c("#303f9d", "#578edb", "#63b946", "#f3930c", "#a60d0d"),
  trim.colors = c(3, 2, 1, 2, 3),
  offset = 0.5,
  n = 25
)

Arguments

colors

A vector of five base colors used to construct the custom diverging palette. These colors are interpolated according to the trim.colors values.

trim.colors

A vector of five positive integers that control the relative weight of each hue in the five-color diverging palette.

offset

Adjusts brightness by shifting hues toward the center, either brighter (offset > 0) or darker ( offset < 0).

n

The number of colors to generate in the output palette.

Value

A vector with hexadecimal color codes.

Examples

pspace.pals()

pspace.pals()

Signal aggregation functions

Description

Signal aggregation functions for circularProjection and polarProjection internal calls. The aggregation should be symmetric with respect to signal polarity, ensuring that opposite signals produce corresponding outputs.

Usage

signalAggregation(method = c("mean", "wmean", "log.wmean", "exp.wmean"))
signalAggregation(method = c("mean", "wmean", "log.wmean", "exp.wmean"))

Arguments

method

A character string specifying the method for signal aggregation, returning either a customized mean or weighted.mean function.

Value

Returns a function of the form: function(x) { ... }

Author(s)

Sysbiolab Team

Examples

aggregate.fun <- signalAggregation()

aggregate.fun <- signalAggregation()

Deprecated function

Description

Use weibullDecay, expDecay, and linearDecay.

Usage

signalDecay(...)
signalDecay(...)

Arguments

...

Deprecated arguments

Value

Stop unconditionally

Author(s)

Sysbiolab Team

Examples

decay.fun <- weibullDecay()

decay.fun <- weibullDecay()

Decorating PathwaySpace Images with Graph Silhouettes

Description

silhouetteMapping constructs an image baseline used to outline the graph layout in a PathwaySpace image.

Usage

## S4 method for signature 'PathwaySpace'
silhouetteMapping(
  ps,
  pdist = 0.05,
  baseline = 0.01,
  fill.cavity = TRUE,
  verbose = TRUE
)
## S4 method for signature 'PathwaySpace'
silhouetteMapping(
  ps,
  pdist = 0.05,
  baseline = 0.01,
  fill.cavity = TRUE,
  verbose = TRUE
)

Arguments

ps

A PathwaySpace class object.

pdist

A term (in [0,1]) determining a distance unit for the silhouette projection.

baseline

A fraction (in [0,1]) of the silhouette projection, representing the level over which a silhouette will outline the graph layout. When baseline = 0 (i.e. lower level of the projection), the silhouette will extend over the entire image space, so no outline will be visible.

fill.cavity

A logical value specifying to fill cavities in the silhouette mask (when fill.cavity=TRUE) or not (when fill.cavity=FALSE).

verbose

A logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

Examples

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Map graph silhouette
ps <- silhouetteMapping(ps, pdist = 0.1)

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy1, nrc = 100)
# note: adjust 'nrc' to increase image resolution

# Set '1s' as vertex signal
vertexSignal(ps) <- 1

# Map graph silhouette
ps <- silhouetteMapping(ps, pdist = 0.1)

Mapping Summits on PathwaySpace Images

Description

The summitMapping method implements a segmentation strategy to identify summits on a 2D-landscape image (see summitWatershed).

Usage

## S4 method for signature 'PathwaySpace'
summitMapping(
  ps,
  maxset = 30,
  minsize = 30,
  threshold = 0.5,
  verbose = TRUE,
  segm_fun = summitWatershed,
  ...
)
## S4 method for signature 'PathwaySpace'
summitMapping(
  ps,
  maxset = 30,
  minsize = 30,
  threshold = 0.5,
  verbose = TRUE,
  segm_fun = summitWatershed,
  ...
)

Arguments

ps

A PathwaySpace class object.

maxset

A single positive integer indicating the maximum number of summits to be returned by the segmentation function.

minsize

A single positive integer indicating the minimum size of the summits.

threshold

A threshold provided as a fraction (in [0,1]) of the max signal intensity.

verbose

A logical value specifying to display detailed messages (when verbose=TRUE) or not (when verbose=FALSE).

segm_fun

A segmentation function used to detect summits (see summitWatershed).

...

Additional arguments passed to the segmentation function.

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

Examples

# Load a large igraph
data("PCv12_pruned_igraph", package = "PathwaySpace")

# Continue this example from the PathwaySpace vignette,
# in the 'PathwaySpace decoration' section

# Load a large igraph
data("PCv12_pruned_igraph", package = "PathwaySpace")

# Continue this example from the PathwaySpace vignette,
# in the 'PathwaySpace decoration' section

Variation of the watershed algorithm for summit detection

Description

The summitWatershed function implements a segmentation strategy to identify summits within a landscape image generated by the PathwaySpace package. This function is entirely coded in R, which helps alleviating users from the task of loading an excessive number of dependencies. Nonetheless, while this novel implementation prevents the burden a 'dependency heaviness', it still requires optimization as it currently exhibits slower performance compared to well-established implementations such as the watershed function from the EBImage package. The summitWatershed maintain a certain level of compatibility with the EBImage's watershed function, and both can be used in the PathwaySpace package.

Usage

summitWatershed(x, tolerance = 0.1, ext = 1)
summitWatershed(x, tolerance = 0.1, ext = 1)

Arguments

x

A 2D-numeric array in which each point represents the coordinates of a signal in a landscape image.

tolerance

The minimum signal intensity of a summit (in ⁠[0,1]⁠), representing a fraction of the maximum signal intensity.

ext

Radius (in pixels) for detecting neighboring objects.

Value

A matrix with labeled summits.

Author(s)

Sysbiolab Team, Mauro Castro.

Examples

# Load a demo landscape image
data('gimage', package = 'PathwaySpace')

# Scale down the image for a quicker demonstration
gimage <- gimage[200:300, 200:300]

# Check signal range
range(gimage, na.rm = TRUE)
# [1] 0 1

# Check image

image(gimage)


# Threshold the signal intensity, for example:
gimage[gimage < 0.5] <- 0

# Run summit segmentation
gmask <- summitWatershed(x = gimage)

# Check resulting image mask

image(gimage)


# Load a demo landscape image
data('gimage', package = 'PathwaySpace')

# Scale down the image for a quicker demonstration
gimage <- gimage[200:300, 200:300]

# Check signal range
range(gimage, na.rm = TRUE)
# [1] 0 1

# Check image

image(gimage)


# Threshold the signal intensity, for example:
gimage[gimage < 0.5] <- 0

# Run summit segmentation
gmask <- summitWatershed(x = gimage)

# Check resulting image mask

image(gimage)

Accessor Functions for PathwaySpace Objects

Description

Get or set 'signal' and 'decay' functions in a PathwaySpace class object.

Usage

## S4 method for signature 'PathwaySpace'
vertexSignal(x)

## S4 replacement method for signature 'PathwaySpace'
vertexSignal(x) <- value

## S4 method for signature 'PathwaySpace'
vertexDecay(x)

## S4 replacement method for signature 'PathwaySpace'
vertexDecay(x) <- value
## S4 method for signature 'PathwaySpace'
vertexSignal(x)

## S4 replacement method for signature 'PathwaySpace'
vertexSignal(x) <- value

## S4 method for signature 'PathwaySpace'
vertexDecay(x)

## S4 replacement method for signature 'PathwaySpace'
vertexDecay(x) <- value

Arguments

x

A PathwaySpace class object.

value

The new value of the attribute.

Value

Updated PathwaySpace object.

Examples

data('gtoy1', package = 'RGraphSpace')
ps <- buildPathwaySpace(gtoy1, nrc = 100)

# Check vertex names
names(ps)

# Access signal values from all vertices
vertexSignal(ps)

# Modify signal value of a specific vertex
vertexSignal(ps)[1] <- 1

# Modify signal value of specific vertices
vertexSignal(ps)[c("n2","n3")] <- 1

# Set '1s' to all vertices
vertexSignal(ps) <- 1

#----

# Access decay function of a specific vertex
vertexDecay(ps)[["n3"]]

# Modify decay function of a specific vertex
vertexDecay(ps)[["n3"]] <- linearDecay()

# Modify decay functions of two vertices
vertexDecay(ps)[c("n1","n3")] <- list( weibullDecay() )

# Modify decay functions of all vertices
vertexDecay(ps) <- weibullDecay(shape = 2)

data('gtoy1', package = 'RGraphSpace')
ps <- buildPathwaySpace(gtoy1, nrc = 100)

# Check vertex names
names(ps)

# Access signal values from all vertices
vertexSignal(ps)

# Modify signal value of a specific vertex
vertexSignal(ps)[1] <- 1

# Modify signal value of specific vertices
vertexSignal(ps)[c("n2","n3")] <- 1

# Set '1s' to all vertices
vertexSignal(ps) <- 1

#----

# Access decay function of a specific vertex
vertexDecay(ps)[["n3"]]

# Modify decay function of a specific vertex
vertexDecay(ps)[["n3"]] <- linearDecay()

# Modify decay functions of two vertices
vertexDecay(ps)[c("n1","n3")] <- list( weibullDecay() )

# Modify decay functions of all vertices
vertexDecay(ps) <- weibullDecay(shape = 2)

Constructor of Weibull decay functions

Description

The weibullDecay() constructor either creates a decay function or returns a ggplot object for visualizing the decay model. It is a utility function used internally by circularProjection and polarProjection.

Usage

weibullDecay(
  decay = 0.001,
  pdist = 0.15,
  shape = 1.05,
  plot = FALSE,
  demo.signal = 1
)
weibullDecay(
  decay = 0.001,
  pdist = 0.15,
  shape = 1.05,
  plot = FALSE,
  demo.signal = 1
)

Arguments

decay

pdist

shape

A parameter (>=1) of a Weibull function. When shape=1 the Weibull decay follows an exponential decay. When shape>1 the function is first convex, then concave with an inflection point.

plot

A logical value indicating whether to return a ggplot object.

demo.signal

Details

The weibullDecay() constructor creates a decay model based on the Weibull distribution. It describes how a signal decreases as a function of distance, controlled by both a decay rate and a shape parameter.

The decay function is defined as:

$y = signal \times decay^{\left(\frac{x}{pdist}\right)^{shape}}$

where $signal$ represents the initial intensity, $decay$ controls the rate of attenuation, $x$ is a vector of normalized distances, and $shape$ adjusts the curvature of the decay. When $shape = 1$ , the function follows an exponential decay. For $shape > 1$ , the curve transitions from convex to concave, exhibiting an inflection point. The $pdist$ parameter anchors the model such that:

$y = signal$ when $x = 0$
$y = signal \times decay$ when $x = pdist$

Value

Returns either a function of the form function(x, signal) { ... } or, if plot = TRUE, a ggplot object illustrating the decay model.

Author(s)

Sysbiolab Team

Examples

# Return a decay function
decay_fun <- weibullDecay(decay = 0.5, pdist = 0.4, shape = 2)

# Plot decay model parameters
# weibullDecay(decay = 0.5, pdist = 0.4, shape = 2, plot = TRUE)

# Return a decay function
decay_fun <- weibullDecay(decay = 0.5, pdist = 0.4, shape = 2)

# Plot decay model parameters
# weibullDecay(decay = 0.5, pdist = 0.4, shape = 2, plot = TRUE)

Package 'PathwaySpace'

Help Index

Constructor of PathwaySpace-class Objects

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

COSMIC-CGC genes mapped to PathwaySpace images

Description

Usage

Format

Value

Source

References

Examples

Circular Projection of Graph-Associated Signals

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Constructor of exponential decay functions

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

getNearestNode

Description

Usage

Arguments

See Also

Examples

Accessors for Fetching Slots from a PathwaySpace Object

Description

Usage

Arguments

Value

Examples

An image matrix

Description

Usage

Format

Value

Source

Examples

Accessor Functions for PathwaySpace Objects

Description

Usage

Arguments

Value

Examples

A list with Hallmark gene sets (v2023.1)

Description

Usage

Format

Value

Source

References

Examples

Constructor of linear decay functions

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Calculate a pathway space distance between two vectors

Description

Usage