Type: Package
Title: Spatial Projection of Network Signals along Geodesic Paths
Version: 1.1.0
Depends: R(≥ 4.4), methods, RGraphSpace(≥ 1.1.0)
Imports: grDevices, stats, scales, RANN, igraph, ggplot2, ggrepel, lifecycle
Suggests: knitr, rmarkdown, testthat, RedeR
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 then uses a decay function to project these signals, creating geodesic paths on a 2D-image space. 'PathwaySpace' could have various applications, such as visualizing network data in a graphical format that highlights the relationships and signal strengths between vertices. It can be particularly useful for understanding the influence of signals through complex networks. By combining graph theory, signal processing, and visualization, the 'PathwaySpace' package provides a novel way of representing graph data.
License: Artistic-2.0
VignetteBuilder: knitr
URL: https://sysbiolab.github.io/PathwaySpace/, https://github.com/sysbiolab/PathwaySpace
BugReports: https://github.com/sysbiolab/PathwaySpace/issues
Collate: pspaceChecks.R pspaceSupplements.R pspaceMisc.R pspaceWatershed.R pspaceDecay.R pspaceClasses.R pspaceGenerics.R pspaceMethods.R pspacePlots.R
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-11-05 15:15:36 UTC; maac
Author: Victor Apolonio [ctb], Vinicius Chagas [ctb], Sysbiolab and Collaborators [fnd], Mauro Castro ORCID iD [aut, cre]
Maintainer: Mauro Castro <mauro.a.castro@gmail.com>
Repository: CRAN
Date/Publication: 2025-11-07 00:30:02 UTC

PathwaySpace: 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 then uses a decay function to propagate these signals, creating geodesic paths on a 2D-image space.

Details

Package: PathwaySpace
Type: Software
License: Artistic-2.0
Maintainer: Mauro Castro mauro.a.castro@gmail.com

Index

PathwaySpace-class: An S4 class for signal propagation on pathway spaces.
buildPathwaySpace: Constructor of PathwaySpace-class objects.
circularProjection: Creating 2D-landscape images from graph objects.
polarProjection: Creating 2D-landscape images from graph objects.
silhouetteMapping: Mapping graph silhouettes on PathwaySpace images.
summitMapping: Mapping summits on a 2D-landscape image.
getPathwaySpace: Accessory method for fetching slots from a PathwaySpace object.
plotPathwaySpace: Plotting 2D-landscape images for the PathwaySpace package.

Further information is available in the vignettes by typing vignette('PathwaySpace'). Documented topics are also available in HTML by typing help.start() and selecting the PathwaySpace package from the menu.

Author(s)

The Cancer Genome Atlas Analysis Network

References

The Cancer Genome Atlas Analysis Network (2023). PathwaySpace: Spatial propagation of network signals along geodesic paths. R package version 0.99.

See Also

Useful links:

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)

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)

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)

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)

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)

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)

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 (mauro.castro@ufpr.br)

Constructor of PathwaySpace-class Objects

Description

buildPathwaySpace is a constructor of PathwaySpace-class objects.

Usage

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

See Also

undirected_graph

Examples

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

# Check graph validity
gs <- GraphSpace(gtoy1, mar = 0.1)

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

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()
)

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

See Also

buildPathwaySpace, weibullDecay, expDecay, linearDecay

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)

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)

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:

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

See Also

linearDecay, weibullDecay

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)

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")

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')

An image matrix

Description

An image matrix used for workflow demonstrations.

Usage

data(gimage)

Format

matrix

Value

An image matrix.

Source

This package.

Examples

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

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

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)

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 '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:

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

See Also

expDecay, weibullDecay

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)

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)

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.

See Also

plotPathwaySpace

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"

Accessory function to plot pathway space distances

Description

Accessory function to plot pathway space distances

Usage

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)

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(),
  trim.colors = c(3, 2, 1, 2, 3),
  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. Each color is a specific hue used to create a customized color palette, interpolated according to the provided sequence in the vector of colors. The proportion of each color hue can be adjusted by the 'trim.colors' argument. This palette is designed to fine-tune the visibility of summits and valleys within the image space. To bypass this automatic palette generation and use the 'colors' input as-is, simply set 'trim.colors' to NULL.

trim.colors

An vector with 5 positive integer numbers. This argument can be used to adjust the proportion of each color hue in the palette.

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.

See Also

circularProjection

Examples

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

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

# 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, 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
)

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

See Also

polarProjection

Examples

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()
)

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

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

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

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

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

See Also

buildPathwaySpace

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)

A simple vector of colors for PathwaySpace images

Description

A simple vector of colors for PathwaySpace images

Usage

pspace.cols(n = 5)

Arguments

n

Number of colors.

Value

A vector with hexadecimal color codes.

See Also

plotPathwaySpace

Examples

pspace.cols()

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"))

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

See Also

circularProjection, polarProjection, weighted.mean

Examples

aggregate.fun <- signalAggregation()

Deprecated function

Description

Use weibullDecay, expDecay, and linearDecay.

Usage

signalDecay(...)

Arguments

...

Deprecated arguments

Value

Stop unconditionally

Author(s)

Sysbiolab Team

Examples

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
)

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 verbose=TRUE) or not (when verbose=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

See Also

circularProjection

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)

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

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

See Also

circularProjection

Examples

# 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)

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.

See Also

summitMapping

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)

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

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)

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
)

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.

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

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 '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:

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

See Also

linearDecay, expDecay

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)