Package {PathwaySpace}

Type:	Package
Title:	Spatial Projection of Network Signals along Geodesic Paths
Version:	1.4.1
Depends:	R(≥ 4.5), methods, RGraphSpace(≥ 1.4.0)
Imports:	grDevices, rlang, stats, scales, RANN, igraph, ggplot2, grid, ggnewscale, ggrepel, colorspace, patchwork, 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 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>.
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:	pspace-checks.R pspace-supplements.R pspace-misc.R pspace-watershed.R pspace-decay.R pspace-classes.R pspace-generics.R pspace-methods.R pspace-plots.R annotation-pspace.R
Encoding:	UTF-8
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-06-25 19:16:21 UTC; maac
Author:	Sysbiolab Team [aut], Victor Apolonio [ctb], Jonathan Back [ctb], Lana Querne [ctb], Vinicius Chagas [ctb], Bahar Tercan [ctb], Mauro Castro [cre]
Maintainer:	Mauro Castro <mauro.a.castro@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-26 05:40:09 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 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.

Details

For a hands-on introduction, see the vignette: vignette("PathwaySpace").

The full set of documented topics can also be browsed in HTML by running help.start() and selecting the PathwaySpace package from the package list.

Author(s)

Maintainer: Mauro Castro mauro.a.castro@gmail.com (ORCID)

Authors:

• Sysbiolab Team

Other contributors:

• Victor Apolonio [contributor]

• Jonathan Back [contributor]

• Lana Querne [contributor]

• Vinicius Chagas [contributor]

• Bahar Tercan [contributor]

References

To cite this package, use citation("PathwaySpace").

See Also

Useful links:

• https://sysbiolab.github.io/PathwaySpace/

• https://github.com/sysbiolab/PathwaySpace

• Report bugs at https://github.com/sysbiolab/PathwaySpace/issues

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)

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

Value

Updated PathwaySpace object.

Examples

library(PathwaySpace)

# Load a demo igraph
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

PathwaySpace: An S4 class for signal projection on image spaces

Description

PathwaySpace extends the GraphSpace class with signal projection slots. It stores projected signal matrices, projection parameters, and workflow status, and is the main object used by the PathwaySpace package.

Value

A PathwaySpace object.

Slots

nodes

Inherited from GraphSpace.

edges

Inherited from GraphSpace.

graph

Inherited from GraphSpace.

image

Inherited from GraphSpace.

fdata

Inherited from GraphSpace.

pars

Inherited from GraphSpace.

misc

Inherited from GraphSpace.

uuid

Inherited from GraphSpace.

projection

A SpaceProjection object storing the intermediate and final matrices produced by a projection method.

pars_ps

A list with PathwaySpace parameters.

status

A vector containing the processing status of the PathwaySpace object.

Constructor

See buildPathwaySpace.

Author(s)

Sysbiolab Team, Mauro Castro (mauro.castro@ufpr.br)

See Also

GraphSpace, SpaceProjection, buildPathwaySpace, circularProjection

Projection Data Container for PathwaySpace Objects

Description

SpaceProjection is an S4 class that stores the intermediate and final matrices produced during signal projection in a PathwaySpace object. It is created internally by circularProjection or polarProjection and is not intended to be constructed directly by the user.

Value

A SpaceProjection object.

Slots

coordinates

A numeric matrix with one row per graph node and four columns (X, Y, Xint, Yint), storing continuous and integer grid coordinates for each node.

floor

A numeric matrix of dimensions nrc x nrc representing the projection floor, used to mask regions outside the graph silhouette.

signal

A numeric matrix of dimensions nrc x nrc storing the smoothed signal values before final scaling.

result

A numeric matrix of dimensions nrc x nrc containing the final projected signal, scaled to [0, 1] (or [-1, 1] for "negpos" scale types).

See Also

PathwaySpace

Annotation Functions for PathwaySpace Plots

Description

annotation_pspace_signal() annotates a ggplot-based PathwaySpace plot with the projected signal layer, rendered as a raster heatmap bounded to the normalized unit space [0, 1].

Usage

annotation_pspace_signal(
  ps,
  title = activeFeature(ps),
  colors = pspace.cols(),
  bg.color = "grey95",
  si.color = "grey85",
  si.alpha = 1,
  zlab = "Density",
  zlim = NULL,
  slices = 25,
  interpolate = FALSE,
  ...
)

Arguments

Value

A list of ggplot2 layer objects that can be added to a ggplot() call with +.

See Also

circularProjection

Examples

data("gtoy1", package = "RGraphSpace")
ps <- buildPathwaySpace(gtoy1, nrc = 100)
vertexSignal(ps) <- 1
ps <- circularProjection(ps)

## Not run: 
ggplot(ps) +
  annotation_pspace_signal(ps, si.alpha = 0.8) +
  theme_gspace_coords(is_norm = TRUE)

## End(Not run)

Constructor of PathwaySpace-class Objects

Description

buildPathwaySpace is a constructor of PathwaySpace-class objects.

Usage

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

Arguments

Value

A pre-processed PathwaySpace class object.

Author(s)

Sysbiolab Team

See Also

circularProjection, polarProjection

Examples

library(PathwaySpace)

# 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

Circular Projection of Graph-Associated Signals

Description

circularProjection() implements a convolution algorithm to project vertex-associated signals onto a 2D image space using a circular decay function.

Usage

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

Arguments

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

See Also

buildPathwaySpace

Examples

library(PathwaySpace)

# 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

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

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)

getNearestNode

Description

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

Usage

getNearestNode(ps)

Arguments

Value

A data.frame with columns from, to, and dist, listing each node's nearest neighbor and the Euclidean distance between them.

See Also

nn2

Examples

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

Arguments

Value

Content from slots in the PathwaySpace object.

Examples

library(PathwaySpace)

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

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

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

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

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

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,
  title = activeFeature(ps),
  colors = pspace.cols(),
  bg.color = "grey95",
  si.color = "grey85",
  si.alpha = 1,
  theme = "th0",
  xlab = "Graph coordinates 1",
  ylab = "Graph 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

Value

A ggplot-class object.

Author(s)

Sysbiolab Team, Mauro Castro.

See Also

circularProjection, polarProjection

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)

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

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 vertex-associated signals onto a 2D image space along graph edges, using a polar decay function.

Usage

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

Arguments

Details

Nodes without edges (isolated nodes) still receive a projection: their signal is spread as a circle whose area matches that of a minimally connected (degree-1) node, so isolated nodes do not appear disproportionately large or small relative to connected ones. This treatment is the same whether directional is TRUE or FALSE. The area-matching guarantee is derived for the default polarDecay("power") method; it is not guaranteed to hold exactly for the "gaussian" or "logistic" alternatives.

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

See Also

buildPathwaySpace

Examples

library(PathwaySpace)

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

# Create a new PathwaySpace object
ps <- buildPathwaySpace(gtoy2, nrc = 300)
# 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)

# Set a decay function for all vertices
vertexDecay(ps) <- weibullDecay(shape=2, pdist = 0.2)

# Create a 2D-landscape image
ps <- polarProjection(ps, beta = 5)

plotPathwaySpace(ps)

A simple vector of colors for PathwaySpace images

Description

A simple vector of colors for PathwaySpace images

Usage

pspace.cols(n = 25)

Arguments

Value

A vector with hexadecimal color codes.

See Also

plotPathwaySpace, pspace.pals

Examples

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
)

Arguments

Value

A vector with hexadecimal color codes.

See Also

plotPathwaySpace

Examples

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

Arguments

Details

At each point in pathway space, multiple vertices may each contribute a decayed signal value; method controls how these contributions are combined into a single value:

• mean: a plain, unweighted average. Because the same number of potential contributors is assumed throughout the image, points reached by few vertices can show a diluted value compared to points reached by many, even when the underlying signals are equally strong.

• wmean: each contribution is weighted by its own magnitude, so the strongest nearby signal dominates the result regardless of how many (or how weak) the other contributions are.

• log.wmean: like wmean, but the weighting is compressed, giving moderate signals comparatively more influence relative to the single strongest one.

• exp.wmean: like wmean, but the weighting is sharpened, so the strongest nearby signal dominates the result even more than under wmean.

Unlike mean, the weighted variants are not affected by the dilution described above, since contributions with zero weight do not affect their result. mean is a reasonable default for simple or binary signals, such as those used in introductory examples; for continuous, more nuanced analyses, wmean (or one of its variants) is generally preferable. For other aggregation rules, see fuzzy logic functions in the online tutorials: https://sysbiolab.github.io/PathwaySpace/

Value

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

Author(s)

Sysbiolab Team

See Also

circularProjection, polarProjection, weighted.mean

Examples

aggregate.fun <- signalAggregation()

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

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

See Also

circularProjection

Examples

library(PathwaySpace)

# 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,
  segm.fun = summitWatershed,
  ...
)

Arguments

Value

A preprocessed PathwaySpace class object.

Author(s)

Sysbiolab Team

See Also

circularProjection

Examples

library(PathwaySpace)

# 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

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)

Update a PathwaySpace object

Description

Updates outdated PathwaySpace objects serialized from previous package versions, adding any missing slots with default values.

Usage

## S4 method for signature 'PathwaySpace'
updatePathwaySpace(x, verbose = TRUE)

Arguments

Value

An updated PathwaySpace object.

Accessor Functions for PathwaySpace Objects

Description

Get or set vertex signals, decay functions, and the active feature in a PathwaySpace object.

vertexSignal() gets or sets the numeric signal assigned to each vertex, used as input for spatial projection.

vertexDecay() gets or sets the decay function assigned to each vertex, controlling how the signal attenuates with distance.

activeFeature() gets or sets the active feature name, which automatically extracts the corresponding signal from the fdata slot or node attributes and assigns it to vertexSignal().

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'
activeFeature(x)

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

Arguments

Value

The updated PathwaySpace object.

Examples

library(PathwaySpace)

# Load a demo igraph
data('gtoy1', package = 'RGraphSpace')
ps <- buildPathwaySpace(gtoy1, nrc = 100)

# Check vertex names
names(ps)

##--------------------------------------
## 'vertexSignal' accessor

# 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

##--------------------------------------
## 'activeFeature' accessor

# Assign a signal feature matrix
signal_mtx <- matrix(
  rep(rnorm(gs_vcount(ps)), 2),
  ncol = 2,
  dimnames = list(names(ps), c("feature1", "feature2"))
)
gs_fdata(ps) <- signal_mtx

# Set the active feature — automatically updates vertexSignal()
activeFeature(ps) <- "feature1"

##--------------------------------------
## 'vertexDecay' accessor

# 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

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

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)