Package 'neurosurf'

Description

Extracts all data from a NeuroSurfaceVector as a matrix.

Usage

## S4 method for signature 'NeuroSurfaceVector,missing,missing,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

A numeric matrix containing all data

Description

Extracts columns (time points) from a NeuroSurfaceVector.

Usage

## S4 method for signature 'NeuroSurfaceVector,missing,numeric,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

A numeric matrix or vector of extracted column data

Description

Extracts rows (vertices) from a NeuroSurfaceVector.

Usage

## S4 method for signature 'NeuroSurfaceVector,numeric,missing,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

A numeric matrix or vector of extracted row data

Description

Extracts a subset of data from a NeuroSurfaceVector.

Usage

## S4 method for signature 'NeuroSurfaceVector,numeric,numeric,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

A numeric matrix or vector of the extracted data subset

Description

Subsets an 'ROISurface' object by selecting specific vertex indices.

Usage

## S4 method for signature 'ROISurface,numeric,missing,ANY'
x[i, j, drop]

Arguments

Value

A new ROISurface object containing only the selected vertices and their associated data from the original ROI.

Description

Extracts data from a NeuroSurfaceVector using bracket notation.

Usage

## S4 method for signature 'NeuroSurfaceVector,numeric'
x[[i]]

Arguments

Value

A numeric vector of data values for the specified column

Description

This helper adds an outline-only layer to an existing "neurosurf_plot" object using ROI labels. It configures sensible defaults for boundary aesthetics (including a light halo and a small depth offset) so that atlas outlines remain legible over filled statistical maps.

Usage

add_atlas_outline(
  x,
  labels,
  rois = NULL,
  label = "atlas",
  outline_col = "black",
  outline_lwd = 1.5,
  outline_offset = 0.5,
  outline_halo = TRUE,
  outline_halo_col = "white",
  outline_halo_lwd = NULL,
  outline_lty = c("solid", "dashed"),
  ...
)

Arguments

Value

A modified "neurosurf_plot" object.

Examples

fs <- load_fsaverage_std8("inflated")
p  <- surface_plot(fs$lh, fs$rh)
# roi_labels <- ... # per-vertex ROI ids
# p <- add_atlas_outline(p, roi_labels)

Description

Add a data layer to a surface plot

Usage

add_surface_layer(
  x,
  data,
  cmap = "viridis",
  alpha = 1,
  irange = NULL,
  color_range = NULL,
  thresh = NULL,
  vertices = NULL,
  smoothing = c("auto", "nearest"),
  smoothing_steps = 20,
  as_outline = FALSE,
  zero_transparent = TRUE,
  show_colorbar = TRUE,
  label = NULL,
  outline_col = "black",
  outline_lwd = 1.5,
  outline_offset = 0,
  outline_halo = FALSE,
  outline_halo_col = NULL,
  outline_halo_lwd = NULL,
  outline_rois = NULL,
  outline_lty = c("solid", "dashed"),
  hemi = c("both", "left", "right")
)

Arguments

Value

A modified "neurosurf_plot" object.

Examples

# Requires FreeSurfer-like surface files
# sp <- surface_plot(left = "lh.pial", right = "rh.pial")
# sp <- add_surface_layer(sp, data = rnorm(163842))

Description

Add a vector field overlay

Usage

add_vector_layer(
  x,
  vectors,
  vertices = NULL,
  scale = NULL,
  color = "red",
  alpha = 0.8,
  lwd = 1.5,
  hemi = c("both", "left", "right")
)

Arguments

Value

A modified "neurosurf_plot" object.

Examples

# Requires FreeSurfer-like surface files
# sp <- surface_plot(left = "lh.pial", right = "rh.pial")
# vectors <- matrix(rnorm(163842 * 3), ncol = 3)
# sp <- add_vector_layer(sp, vectors = vectors)

Description

Get Adjacency Graph

Usage

adjacency(x, attr, ...)

## S4 method for signature 'SurfaceGeometry,numeric'
adjacency(x, attr)

## S4 method for signature 'SurfaceGeometry,character'
adjacency(x, attr)

## S4 method for signature 'SurfaceGeometry,missing'
adjacency(x)

Arguments

Value

A sparse adjacency matrix of class dgCMatrix

Description

This class supports the AFNI 1D file format for surface-based data

Value

An object of class AFNISurfaceFileDescriptor.

Description

Apply a precomputed surface sampler to a volume

Usage

apply_surface_sampler(
  sampler,
  vol,
  fun = c("avg", "nn", "mode"),
  sigma = 8,
  fill = 0
)

Arguments

Value

NeuroSurface with mapped data.

Examples

# Requires surface sampler and volume data
# sampler <- surface_sampler(geometry, vol)
# result <- apply_surface_sampler(sampler, vol)

Description

Arithmetic Operations for NeuroSurface Objects

Usage

## S4 method for signature 'NeuroSurface,NeuroSurface'
Arith(e1, e2)

## S4 method for signature 'NeuroSurface,numeric'
Arith(e1, e2)

## S4 method for signature 'numeric,NeuroSurface'
Arith(e1, e2)

## S4 method for signature 'NeuroSurface,NeuroSurfaceVector'
Arith(e1, e2)

Arguments

Value

NeuroSurface object with arithmetic operation results

Description

Arithmetic Operations for NeuroSurfaceVector Objects

Usage

## S4 method for signature 'NeuroSurfaceVector,NeuroSurfaceVector'
Arith(e1, e2)

## S4 method for signature 'NeuroSurfaceVector,numeric'
Arith(e1, e2)

## S4 method for signature 'numeric,NeuroSurfaceVector'
Arith(e1, e2)

## S4 method for signature 'NeuroSurfaceVector,NeuroSurface'
Arith(e1, e2)

Arguments

Value

NeuroSurfaceVector object with arithmetic operation results

Description

Methods to convert NeuroSurface objects to other types.

Value

The converted object (e.g., a numeric vector when converting to "vector").

Description

Converts surface data to a matrix representation.

Usage

## S4 method for signature 'ROISurfaceVector'
as.matrix(x)

## S4 method for signature 'NeuroSurfaceVector'
as.matrix(x)

## S4 method for signature 'BilatNeuroSurfaceVector'
as.matrix(x)

Arguments

Value

A numeric matrix with vertices as rows and time points/features as columns

Description

Converts surface data to a numeric vector.

Usage

## S4 method for signature 'NeuroSurface'
as.vector(x)

Arguments

Value

A numeric vector of surface data values

Description

Represents surface data for both left and right hemispheres.

Details

The BilatNeuroSurfaceVector class provides a convenient container for organizing and analyzing data from both hemispheres of the brain simultaneously. It holds two NeuroSurfaceVector objects, one for each hemisphere, allowing researchers to:

• Analyze bilateral symmetric or asymmetric patterns in brain data

• Compare corresponding regions across hemispheres

• Represent whole-brain surface data with proper hemisphere separation

• Apply operations to both hemispheres while maintaining their distinct identities

This class is particularly useful for studies examining interhemispheric differences, bilateral effects, or any analysis that requires maintaining separate representations of the two hemispheres while treating them as parts of a unified whole.

Value

An object of class BilatNeuroSurfaceVector.

Slots

left

NeuroSurfaceVector instance for the left hemisphere

right

NeuroSurfaceVector instance for the right hemisphere

See Also

NeuroSurfaceVector

Examples

# Create two simple tetrahedron meshes (one for each hemisphere)
# Left hemisphere
lh_vertices <- c(
  0, 0, 0,
  -1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
# Right hemisphere
rh_vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)

triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d objects
lh_mesh <- rgl::mesh3d(vertices = lh_vertices, triangles = triangles)
rh_mesh <- rgl::mesh3d(vertices = rh_vertices, triangles = triangles)

# Create graph representations
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
lh_graph <- igraph::graph_from_edgelist(edges)
rh_graph <- igraph::graph_from_edgelist(edges)

# Create SurfaceGeometry objects
lh_geometry <- new("SurfaceGeometry",
                  mesh = lh_mesh,
                  graph = lh_graph,
                  hemi = "left")
rh_geometry <- new("SurfaceGeometry",
                  mesh = rh_mesh,
                  graph = rh_graph,
                  hemi = "right")

# Define indices for all vertices
indices <- 1:4

# Create Matrix data for each hemisphere
# Each has 4 vertices and 2 measures
require(Matrix)
lh_data <- Matrix(
  c(0.5, 1.2, 0.8, 0.6,   # Measure 1 values
    0.7, 0.3, 1.5, 0.9),  # Measure 2 values
  nrow = 4, ncol = 2,
  byrow = FALSE
)

rh_data <- Matrix(
  c(0.4, 1.1, 0.7, 0.5,   # Measure 1 values (slightly different from left)
    0.8, 0.4, 1.6, 1.0),  # Measure 2 values (slightly different from left)
  nrow = 4, ncol = 2,
  byrow = FALSE
)

# Create NeuroSurfaceVector objects for each hemisphere
lh_nsv <- new("NeuroSurfaceVector",
             geometry = lh_geometry,
             indices = indices,
             data = lh_data)

rh_nsv <- new("NeuroSurfaceVector",
             geometry = rh_geometry,
             indices = indices,
             data = rh_data)

# Create the BilatNeuroSurfaceVector object
bilat_nsv <- new("BilatNeuroSurfaceVector",
                left = lh_nsv,
                right = rh_nsv)

# Now you can access each hemisphere separately:
# bilat_nsv@left@data  # Left hemisphere data
# bilat_nsv@right@data # Right hemisphere data

Description

Clear geodesic cache

Usage

clear_geodesic_cache()

Value

TRUE (invisibly)

Examples

clear_geodesic_cache()

Description

Apply Cluster-Extent Threshold to Surface Data

Usage

cluster_threshold(x, threshold, size, ...)

## S4 method for signature 'NeuroSurfaceVector'
cluster_threshold(x, threshold, size = 10, index = 1)

## S4 method for signature 'NeuroSurface'
cluster_threshold(x, threshold, size = 10)

Arguments

Value

A thresholded surface object of the same class as x

See Also

conn_comp

Description

This function creates a ColorMappedNeuroSurface object, which represents a single set of data values associated with nodes on a surface geometry, with pre-defined color mapping parameters.

Usage

ColorMappedNeuroSurface(geometry, indices, data, cmap, irange, thresh)

Arguments

Details

This object bundles the surface geometry, data, and specific color mapping parameters ('cmap', 'irange', 'thresh'). This is useful for ensuring consistent visualization across different plots or for saving a predefined view. The actual application of the color map happens during rendering (e.g., when using 'plot()”).

Value

An instance of class ColorMappedNeuroSurface.

See Also

SurfaceGeometry, NeuroSurface

Examples

# Load a sample surface geometry
surf_file <- system.file("extdata", "std.8_lh.inflated.asc", package = "neurosurf")
surf_geom <- read_surf_geometry(surf_file)

# Get vertex count and generate some random data
n_verts <- nrow(coords(surf_geom))
set.seed(123)
vertex_data <- rnorm(n_verts)

# Define indices (all vertices in this case)
vertex_indices <- 1:n_verts

# Define color mapping parameters
my_cmap <- colorRampPalette(c("blue", "white", "red"))(256) # Blue-white-red colormap
my_irange <- c(-2, 2) # Map data values from -2 to 2 onto the colormap
my_thresh <- c(-1, 1) # Define thresholds (e.g., for transparency later)

# Create the ColorMappedNeuroSurface object
mapped_surf <- ColorMappedNeuroSurface(geometry = surf_geom,
                                       indices = vertex_indices,
                                       data = vertex_data,
                                       cmap = my_cmap,
                                       irange = my_irange,
                                       thresh = my_thresh)

# Print the object summary
print(mapped_surf)

# The object can now be plotted, and the plotting function will use
# the stored cmap, irange, and thresh parameters by default.
# plot(mapped_surf) # Requires rgl package

Description

A three-dimensional surface consisting of a set of triangle vertices with one value per vertex, mapped to colors using a specified colormap and range.

Details

This class extends NeuroSurface by adding color mapping functionality. The cmap slot contains a vector of hex color codes that define the colormap. The irange slot specifies the range of data values to be mapped to the colormap. The thresh slot defines the visibility thresholds: data values below thresh[1] or above thresh[2] are visible, while values in between are not visible.

The color mapping process works as follows:

1. Data values are linearly mapped to the range [0,1] based on irange

2. These normalized values are used to interpolate colors from the cmap

3. Values falling between the thresholds in thresh are marked as invisible

This approach is particularly useful for visualizing statistical maps (e.g., t-statistics) where researchers are often interested in highlighting values above or below certain significance thresholds.

Value

An object of class ColorMappedNeuroSurface

Slots

geometry

The surface geometry, an instance of SurfaceGeometry or SurfaceSet

indices

An integer vector specifying the subset of valid surface nodes encoded in the geometry object

data

The 1-D vector of data values at each vertex of the mesh

cmap

A character vector of hex color codes representing the colormap

irange

A numeric vector of length 2 specifying the low and high values for color mapping

thresh

A numeric vector of length 2 specifying the low and high thresholds for visibility

See Also

view_surface, plot-methods

Examples

# First create a simple tetrahedron mesh
vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d object
mesh <- rgl::mesh3d(vertices = vertices, triangles = triangles)

# Create a graph representation
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
graph <- igraph::graph_from_edgelist(edges)

# Create a SurfaceGeometry object
geometry <- new("SurfaceGeometry",
               mesh = mesh,
               graph = graph,
               hemi = "left")

# Define indices for all vertices
indices <- 1:4

# Create data values for each vertex
vertex_data <- c(-1.5, -0.5, 0.8, 2.0)  # example values for the vertices

# Define a simple colormap (blue to red)
colormap <- c("#0000FF", "#FFFFFF", "#FF0000")

# Define intensity range for mapping data to colors
intensity_range <- c(-2.0, 2.0)

# Define thresholds (values between -0.5 and 0.5 will be invisible)
thresholds <- c(-0.5, 0.5)

# Create the ColorMappedNeuroSurface object
colored_surface <- new("ColorMappedNeuroSurface",
                      geometry = geometry,
                      indices = indices,
                      data = vertex_data,
                      cmap = colormap,
                      irange = intensity_range,
                      thresh = thresholds)

# In this example:
# - Vertex 1 (-1.5) will be visible and colored blue (below lower threshold)
# - Vertex 2 (-0.5) will be exactly at the lower threshold
# - Vertex 3 (0.8) will be visible and colored light red (above upper threshold)
# - Vertex 4 (2.0) will be visible and colored bright red (above upper threshold)

Description

Comparison Operations for NeuroSurface Objects

Usage

## S4 method for signature 'NeuroSurface,NeuroSurface'
Compare(e1, e2)

Arguments

Value

NeuroSurface object with comparison results

Description

Comparison Operations for NeuroSurface Objects

Usage

## S4 method for signature 'NeuroSurface,numeric'
Compare(e1, e2)

Arguments

Value

NeuroSurface object with comparison results

Description

Comparison Operations for NeuroSurfaceVector Objects

Usage

## S4 method for signature 'NeuroSurfaceVector,NeuroSurfaceVector'
Compare(e1, e2)

## S4 method for signature 'NeuroSurfaceVector,numeric'
Compare(e1, e2)

## S4 method for signature 'numeric,NeuroSurfaceVector'
Compare(e1, e2)

Arguments

Value

NeuroSurfaceVector object with comparison results

Description

Compute boundary hull points in world space (C++)

Usage

compute_hull_world_cpp(vol, dims, grid2world, thresh, n_points, mask)

Arguments

Value

numeric matrix (n_points x 3) of (x,y,z) in world coords

Description

This method identifies connected components on a NeuroSurface object based on a given threshold.

Usage

## S4 method for signature 'NeuroSurfaceVector'
conn_comp(x, threshold, index = 1)

## S4 method for signature 'NeuroSurface'
conn_comp(x, threshold)

Arguments

Details

This method computes connected components on the surface by:

1. Thresholding the surface data using the provided threshold values.

2. Creating a subgraph of the surface mesh containing only the vertices that pass the threshold.

3. Identifying connected components in this subgraph.

4. Assigning component indices and sizes to the original vertices.

Vertices that do not pass the threshold are assigned a value of 0 in both output surfaces.

Value

A list containing two NeuroSurface objects:

See Also

NeuroSurface, components

Examples

# Load a sample surface from the package
surf_file <- system.file("extdata", "std.8_lh.inflated.asc", package = "neurosurf")
surf_geom <- read_surf_geometry(surf_file)

# Create random data for the surface with some clusters
n_vertices <- nrow(coords(surf_geom))
set.seed(123)
random_data <- rnorm(n_vertices, mean = 0, sd = 1)

# Create a few clusters of higher values
cluster_centers <- sample(1:n_vertices, 5)
g <- graph(surf_geom)

# For each cluster center, set nearby vertices to higher values
for (center in cluster_centers) {
  # Get neighbors within 2 steps
  neighbors <- unlist(igraph::neighborhood(g, 2, center))
  random_data[neighbors] <- random_data[neighbors] + 2
}

# Create a NeuroSurface object
neuro_surf <- NeuroSurface(geometry = surf_geom,
                          indices = 1:n_vertices,
                          data = random_data)

# Find connected components with threshold c(-Inf, 1.5)
# This will identify clusters where values are >= 1.5
components <- conn_comp(neuro_surf, c(-Inf, 1.5))

# Check the number of components found
max(series(components$index, seq_len(n_vertices)))

# Check the size of the largest component
max(series(components$size, seq_len(n_vertices)))

# Count vertices in components of size >= 10
sum(series(components$size, seq_len(n_vertices)) >= 10)

Description

Extracts the 3D coordinates of vertices from a surface object.

Usage

## S4 method for signature 'ROISurface'
coords(x)

## S4 method for signature 'SurfaceGeometry'
coords(x)

## S4 method for signature 'igraph'
coords(x)

## S4 method for signature 'NeuroSurfaceVector'
coords(x)

## S4 method for signature 'NeuroSurface'
coords(x)

Arguments

Value

A numeric matrix with three columns (x, y, z) and one row per vertex

Description

This function maps a vector of surface curvature values (e.g., mean curvature) to a binary color scheme, typically used to distinguish gyri (outward folds) from sulci (inward folds) on a brain surface visualization.

Usage

curv_cols(vals, incol = "#B3B3B3", outcol = "#404040")

Arguments

Details

Surface curvature provides information about the local shape of the surface. Mean curvature is often used, where positive values typically indicate outward curvature (gyri) and negative values indicate inward curvature (sulci). This function simplifies the curvature map into two colors based on whether the value is above or below the median curvature, providing a quick visual distinction between these features. Note the default coloring assigns 'incol' to values *above* the median and 'outcol' to values *at or below* the median. You might need to adjust 'incol' and 'outcol' depending on the specific interpretation of curvature values in your data (e.g., if positive values represent sulci).

Value

A character vector of the same length as 'vals', containing hex color codes based on the binary classification of curvature values relative to the median.

See Also

curvature, view_surface

Examples

# Generate some example curvature values
set.seed(123)
curvature_values <- rnorm(100, mean = 0, sd = 0.1)

# Get binary colors using default light/dark gray
gray_colors <- curv_cols(curvature_values)
table(gray_colors)

# Use different colors (e.g., red for above median, blue for below)
red_blue_colors <- curv_cols(curvature_values, incol = "#FF0000", outcol = "#0000FF")
table(red_blue_colors)

Description

Maps surface curvature values to a continuous grayscale gradient, producing a FreeSurfer-style sulcal shading that is visually smoother than the binary mapping of curv_cols.

Usage

curv_cols_smooth(
  vals,
  light = "#C8C8C8",
  dark = "#4D4D4D",
  quantiles = c(0.05, 0.95),
  sharpness = 6
)

Arguments

Details

Values are clamped to the range defined by quantiles to prevent outliers from washing out the colour map. The clamped values are then centred on their median (the gyral/sulcal boundary) and passed through a logistic contrast curve governed by sharpness before being interpolated between dark (sulcal fundi) and light (gyral crowns).

A plain linear ramp leaves most vertices near mid-grey, so the fold pattern tends to disappear once surface lighting is applied. Pushing values toward the two extremes with a logistic curve keeps the sulci clearly dark and the gyri clearly light, which reads as anatomical folding under lighting much the way FreeSurfer / Connectome Workbench curvature overlays do.

Value

A character vector of hex color codes the same length as vals.

See Also

curv_cols, curvature, view_surface

Examples

set.seed(1)
curv <- rnorm(500, sd = 0.1)
cols <- curv_cols_smooth(curv)
head(cols)

# Softer, more continuous gradient
cols_soft <- curv_cols_smooth(curv, sharpness = 2)

Description

Compute Surface Curvature Vector

Usage

curvature(x, ...)

curvature(x, ...)

## S4 method for signature 'SurfaceGeometry'
curvature(x)

Arguments

Value

A numeric vector of curvature values, one per vertex

Description

Creates a column reader object for accessing surface data.

Usage

## S4 method for signature 'SurfaceGeometryMetaInfo'
data_reader(x)

## S4 method for signature 'NIMLSurfaceDataMetaInfo'
data_reader(x)

Arguments

Value

A ColumnReader object for accessing surface data columns

Description

This function helps diagnose issues with surfwidget rendering by checking common problems and providing debugging information.

Usage

debug_surfwidget(x, verbose = TRUE)

Arguments

Value

Invisibly returns a list of diagnostic information

Examples

# Load a surface and check it
surf_file <- system.file("extdata", "std.8_lh.smoothwm.asc", package="neurosurf")
surf <- read_surf(surf_file)
debug_surfwidget(surf)

Description

This is a convenience wrapper around render_surface_plot that arranges rendered panels into a single static figure using the grid graphics system. It supersamples, crops whitespace, and preserves per-panel aspect ratios to avoid tiny or distorted brains when assembled.

Usage

draw_surface_plot(
  x,
  colorbar = TRUE,
  cbar_location = c("bottom", "right"),
  cbar_kws = list()
)

Arguments

Value

A grob object that can be drawn with grid::grid.draw().

Examples

# Requires FreeSurfer-like surface files
# sp <- surface_plot(left = "lh.pial", right = "rh.pial")
# g <- draw_surface_plot(sp)
# grid::grid.draw(g)

Description

Extracts the triangle faces from a surface object, providing a standardized interface across different surface representations.

Usage

faces(x, ...)

## S4 method for signature 'SurfaceGeometry'
faces(x)

## S4 method for signature 'NeuroSurface'
faces(x)

## S4 method for signature 'NeuroSurfaceVector'
faces(x)

Arguments

Value

A matrix where each row represents a triangular face, containing the 1-based vertex indices that form the triangle.

See Also

vertices, nodes

Examples

geom <- example_surface_geometry()
face_data <- faces(geom)
num_faces <- nrow(face_data)

Description

Identifies all neighboring nodes within a specified radius for a given surface mesh.

Usage

find_all_neighbors(
  surf,
  radius,
  edgeWeights,
  nodes = NULL,
  distance_type = c("euclidean", "geodesic", "spherical")
)

Arguments

Details

The function supports three distance metrics: Euclidean, geodesic, and spherical. For spherical distances, the surface is assumed to be a sphere. The internal k-nearest-neighbor search is capped at vcount(g) - 1 to avoid requesting more neighbors than exist in the graph.

Value

A list of matrices, each containing neighbor information:

Examples

# Load a sample inflated surface from the package
surf_file <- system.file("extdata", "std.8_lh.inflated.asc", package = "neurosurf")
surf <- read_surf_geometry(surf_file)

# Create edge weights (using uniform weights for simplicity)
g <- graph(surf)
edge_weights <- rep(1, length(igraph::E(g)))

# Find neighbors within a 10mm radius for the first 5 vertices
neighbors <- find_all_neighbors(surf, radius = 10,
                               edgeWeights = edge_weights,
                               nodes = 1:5,
                               distance_type = "geodesic")

# Check the number of neighbors found for the first vertex
nrow(neighbors[[1]])

# Look at the first few neighbors of the first vertex
head(neighbors[[1]])

Description

Find the nearest surface vertex to a 3D point

Usage

find_nearest_vertex(surface, point)

Arguments

Value

Integer vertex index (1-based) of the closest vertex.

Examples

geom <- example_surface_geometry()
find_nearest_vertex(geom, c(0.9, 0, 0))

Description

This function identifies boundaries between regions of interest (ROIs) defined on a triangular surface mesh. It is a translation of the core parts of Stuart Oldham's findROIboundaries MATLAB function, adapted for use with neurosurf objects.

Usage

find_roi_boundaries(
  vertices,
  faces,
  vertex_id,
  boundary_method = c("midpoint", "faces", "edge_vertices"),
  verbose = FALSE,
  use_cpp = TRUE
)

Arguments

Details

Three boundary representations are currently supported:

• "midpoint" (default): returns crisp single-width contour segments that run between differing labels, through the midpoints of the mesh edges that separate them. This is the recommended method for drawing clean ROI/atlas outlines: shared borders are drawn once (no double lines) and adjacent segments join into continuous contours.

• "faces": returns a logical vector indicating which faces lie on a boundary between ROIs.

• "edge_vertices": returns boundary polygons traced through mesh vertices. Borders are traced along vertices on both sides of a boundary, which can read as a thicker double line on coarse meshes.

Value

A list with elements:

boundary

For "faces": logical vector of length nrow(faces) indicating boundary faces. For "midpoint": list of $2 \times 3$ coordinate matrices, one per contour segment. For "edge_vertices": list of coordinate matrices ($k \times 3$) giving boundary polygons for each connected ROI component.

boundary_roi_id

Integer vector giving the ROI id associated with each boundary polygon (empty for "faces").

roi_components

Integer vector giving the number of connected components for each ROI (indexed parallel to sort(unique(vertex_id))).

boundary_verts

For "edge_vertices": list of integer vectors giving the vertex ids used for each boundary polygon; NULL for "faces".

Examples

# Simple cube mesh with two ROIs (bottom vs top)
vertices <- matrix(c(
  0,0,0, 1,0,0, 1,1,0, 0,1,0,
  0,0,1, 1,0,1, 1,1,1, 0,1,1
), ncol = 3, byrow = TRUE)

faces <- matrix(c(
  1,2,3, 1,3,4,
  5,6,7, 5,7,8,
  1,2,6, 1,6,5,
  3,4,8, 3,8,7,
  1,4,8, 1,8,5,
  2,3,7, 2,7,6
), ncol = 3, byrow = TRUE)

roi <- c(1,1,1,1, 2,2,2,2)

b <- find_roi_boundaries(vertices, faces, roi, boundary_method = "edge_vertices")
str(b$boundary)

Description

This generic function identifies boundaries between different regions or parcellations on a surface. The implementation depends on the class of the input object.

Usage

findBoundaries(x, method = "midpoint", ...)

## S4 method for signature 'NeuroSurface'
findBoundaries(x, method = c("midpoint", "edge_vertices", "faces"), ...)

Arguments

Details

This function provides a high-level interface for finding boundaries between different regions on a surface mesh. It typically returns coordinates and metadata describing the boundaries between regions.

Value

An object containing boundary information. The specific structure depends on the method implementation.

A list as returned by find_roi_boundaries.

See Also

find_roi_boundaries

find_roi_boundaries

Examples

# Requires surface with ROI labels
# boundaries <- findBoundaries(labeled_surface)

Description

This class supports the Freesurfer Ascii file format for surface geometry

Value

An object of class FreesurferAsciiSurfaceFileDescriptor.

Examples

# Create a FreesurferAsciiSurfaceFileDescriptor object
fs_ascii_descriptor <- new("FreesurferAsciiSurfaceFileDescriptor")

# This descriptor would typically be used when loading Freesurfer ASCII surfaces
# Example of a path to a Freesurfer ASCII surface file:
# fs_ascii_file <- "/path/to/subject/surf/lh.pial.asc"

# In practice, this descriptor would be used in code like:
# surface_geo <- loadSurfaceGeometry(fs_ascii_file, descriptor = fs_ascii_descriptor)

Description

This class supports the Freesurfer binary file format for surface geometry

Value

An object of class FreesurferBinarySurfaceFileDescriptor.

Examples

# Create a FreesurferBinarySurfaceFileDescriptor object
fs_binary_descriptor <- new("FreesurferBinarySurfaceFileDescriptor")

# This descriptor would typically be used when loading Freesurfer binary surfaces
# Example of a path to a Freesurfer binary surface file:
# fs_binary_file <- "/path/to/subject/surf/lh.pial"

# In practice, this descriptor would be used in code like:
# surface_geo <- loadSurfaceGeometry(fs_binary_file, descriptor = fs_binary_descriptor)

Description

The 'FreesurferSurfaceGeometryMetaInfo' class extends 'SurfaceGeometryMetaInfo' to specifically handle meta information for Freesurfer-formatted brain surface geometries.

Details

This class inherits all slots from the parent 'SurfaceGeometryMetaInfo' class and is specialized for working with Freesurfer surface files (e.g., .asc, .pial, .white, .inflated). It maintains the same structure but is used specifically when the surface data originates from Freesurfer processing pipelines.

Value

An object of class FreesurferSurfaceGeometryMetaInfo.

Examples

fs_meta <- new("FreesurferSurfaceGeometryMetaInfo",
               header_file = "lh.white.asc",
               data_file = "lh.white.asc",
               file_descriptor = new("FileFormat"),
               vertices = 140000L,
               faces = 279998L,
               embed_dimension = 3L,
               label = "white",
               hemi = "lh")

Description

Create per-vertex Gaussian falloff maps centred on coordinates or vertices. Distances can be measured either in straight-line Euclidean space or along the mesh using geodesic paths (Dijkstra on edge lengths).

Usage

gaussian_splat(surface, center, sigma, use_geodesic = FALSE)

gaussian_splat_vertex(surface, vertex_idx, sigma, use_geodesic = FALSE)

gaussian_splat_multi(
  surface,
  centers,
  sigmas,
  weights = NULL,
  use_geodesic = FALSE
)

Arguments

Value

A NeuroSurface with values $\exp(-d^2 / (2 * sigma^2))$ at every vertex. For gaussian_splat_multi the per-centre maps are summed (after weighting).

Examples

geom <- example_surface_geometry()
g1 <- gaussian_splat(geom, center = c(0, 0, 0), sigma = 1)
v_idx <- find_nearest_vertex(geom, c(0.1, 0, 0))
g2 <- gaussian_splat_vertex(geom, vertex_idx = v_idx, sigma = 1)
g_multi <- gaussian_splat_multi(
  geom,
  centers = rbind(c(0, 0, 0), c(1, 0, 0)),
  sigmas = c(0.5, 1)
)

Description

All-pairs geodesic distance matrix (chunked)

Usage

geodesic_distance_matrix(
  geometry,
  vertices = NULL,
  targets = NULL,
  weights = NULL,
  mode = c("sparse", "dense"),
  chunk_size = 2000,
  cache = TRUE,
  cache_key = NULL,
  algorithm = c("dijkstra")
)

Arguments

Value

A distance matrix (sparse or dense) of size length(vertices) x length(targets).

Examples

geom <- example_surface_geometry()
dmat <- geodesic_distance_matrix(geom, vertices = 1:2)

Description

Convenience wrapper returning a numeric vector/matrix.

Usage

geodesic_distances(
  geometry,
  sources,
  targets = NULL,
  weights = NULL,
  algorithm = c("dijkstra"),
  chunk_size = 2000
)

Arguments

Value

Numeric vector if one source, otherwise a matrix.

Examples

geom <- example_surface_geometry()
d <- geodesic_distances(geom, sources = 1, targets = 2:4)

Description

Extracts the geometric representation from a surface object.

Usage

geometry(x)

## S4 method for signature 'NeuroSurface'
geometry(x)

## S4 method for signature 'NeuroSurfaceVector'
geometry(x)

Arguments

Value

A geometry object representing the surface structure

See Also

vertices, nodes

Examples

# Load a sample surface
surf_file <- system.file("extdata", "std.8_lh.smoothwm.asc", package = "neurosurf")
surf <- read_surf_geometry(surf_file)
# Create a NeuroSurface with some data
ns <- NeuroSurface(surf, indices = 1:100, data = rnorm(100))
# Extract the geometry
geom <- geometry(ns)
class(geom)

Description

Retrieve a geometry from a SurfaceSet

Usage

get_surface(x, label = NULL)

Arguments

Value

A 'SurfaceGeometry' object.

Examples

geom <- example_surface_geometry()
ss <- surface_set(inflated = geom)
get_surface(ss, "inflated")

Description

This class contains meta information for surface-based data for the GIFTI data format

Value

An object of class GIFTISurfaceDataMetaInfo.

Slots

info

the underlying gifti object returned by readgii

Examples

# First create a SurfaceDataMetaInfo parent object
meta_info <- new("SurfaceDataMetaInfo",
                 header_file = "rscan01_lh.gii",
                 data_file = "rscan01_lh.gii",
                 file_descriptor = new("FileFormat"),
                 node_count = 40000L,
                 nels = 1L,
                 label = "thickness")

# Use the example file included in the package
example_gii_file <- system.file("extdata", "rscan01_lh.gii", package = "neurostyle")

if (file.exists(example_gii_file) && requireNamespace("gifti", quietly = TRUE)) {
  # Load the actual GIFTI file
  gifti_obj <- gifti::readgii(example_gii_file)

  # Create GIFTISurfaceDataMetaInfo object with the real file
  gifti_data_meta <- new("GIFTISurfaceDataMetaInfo",
                        header_file = meta_info@header_file,
                        data_file = meta_info@data_file,
                        file_descriptor = meta_info@file_descriptor,
                        node_count = meta_info@node_count,
                        nels = meta_info@nels,
                        label = meta_info@label,
                        info = gifti_obj)
}

Description

This class supports the GIFTI file format for surface-based data

Value

An object of class GIFTISurfaceFileDescriptor.

Description

This class contains meta information for surface-based geometry for the GIFTI data format

Value

An object of class GIFTISurfaceGeometryMetaInfo.

Slots

info

the underlying gifti object returned by readgii

Examples

# First create a SurfaceGeometryMetaInfo parent object
meta_info <- new("SurfaceGeometryMetaInfo",
                 header_file = "rscan01_lh.gii",
                 data_file = "rscan01_lh.gii",
                 file_descriptor = new("FileFormat"),
                 vertices = 40000L,
                 faces = 79998L,
                 embed_dimension = 3L,
                 label = "white",
                 hemi = "lh")

# Use the example file included in the package
example_gii_file <- system.file("extdata", "rscan01_lh.gii", package = "neurostyle")

if (file.exists(example_gii_file) && requireNamespace("gifti", quietly = TRUE)) {
  # Load the actual GIFTI file
  gifti_obj <- gifti::readgii(example_gii_file)

  # Create GIFTISurfaceGeometryMetaInfo object with the real file
  gifti_meta <- new("GIFTISurfaceGeometryMetaInfo",
                   header_file = meta_info@header_file,
                   data_file = meta_info@data_file,
                   file_descriptor = meta_info@file_descriptor,
                   vertices = meta_info@vertices,
                   faces = meta_info@faces,
                   embed_dimension = meta_info@embed_dimension,
                   label = meta_info@label,
                   hemi = meta_info@hemi,
                   info = gifti_obj)
}

Description

extract igraph object

Usage

graph(x, ...)

## S4 method for signature 'SurfaceGeometry'
graph(x)

## S4 method for signature 'NeuroSurface'
graph(x, ...)

## S4 method for signature 'NeuroSurfaceVector'
graph(x, ...)

Arguments

Value

An igraph object representing the surface mesh connectivity

Description

Extracts the vertex indices from surface objects.

Usage

## S4 method for signature 'ROISurface'
indices(x)

## S4 method for signature 'ROISurfaceVector'
indices(x)

## S4 method for signature 'NeuroSurfaceVector'
indices(x)

## S4 method for signature 'NeuroSurface'
indices(x)

Arguments

Value

An integer vector of vertex indices

Description

Represents a 3D surface with labeled vertices, extending NeuroSurface.

Details

The LabeledNeuroSurface class provides a way to represent anatomical parcellations or other categorical divisions of a brain surface. Each vertex is assigned a label based on its data value, which typically represents a region ID. The class maintains a mapping between these IDs and human-readable labels, along with colors for visualization.

This is particularly useful for displaying anatomical atlases or the results of clustering algorithms on the brain surface.

Value

An object of class LabeledNeuroSurface.

Slots

labels

Character vector of label annotations

cols

Character vector of hex color codes for labels

See Also

NeuroSurface

Examples

# Create a simple tetrahedron mesh for the example
vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d object
mesh <- rgl::mesh3d(vertices = vertices, triangles = triangles)

# Create a graph representation
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
graph <- igraph::graph_from_edgelist(edges)

# Create a SurfaceGeometry object
geometry <- new("SurfaceGeometry",
               mesh = mesh,
               graph = graph,
               hemi = "left")

# Define indices for all vertices
indices <- 1:4

# Create data values for each vertex
vertex_data <- c(1, 2, 1, 3)  # Values representing region IDs

# Define the unique labels for the regions
labels <- c("Region A", "Region B", "Region C")

# Define colors for each label (in the same order as labels)
colors <- c("#FF0000", "#00FF00", "#0000FF")  # Red, Green, Blue

# Create the LabeledNeuroSurface object
labeled_surface <- new("LabeledNeuroSurface",
                      geometry = geometry,
                      indices = indices,
                      data = vertex_data,
                      labels = labels,
                      cols = colors)

# In this example, vertices are labeled as follows:
# - Vertices 1 and 3 belong to "Region A" (Red)
# - Vertex 2 belongs to "Region B" (Green)
# - Vertex 4 belongs to "Region C" (Blue)

Description

Compute Graph Laplacian

Usage

laplacian(x, normalized, weights, ...)

## S4 method for signature 'SurfaceGeometry,missing,missing'
laplacian(x)

## S4 method for signature 'SurfaceGeometry,missing,numeric'
laplacian(x, weights)

Arguments

Value

A sparse Laplacian matrix of class dgCMatrix

Description

Get Left Hemisphere

Usage

left(x)

## S4 method for signature 'BilatNeuroSurfaceVector'
left(x)

Arguments

Value

Left hemisphere of the surface

Examples

# Requires bilateral surface data
# lh <- left(bilat_surface)

Description

Returns the number of vertices in a surface object.

Usage

## S4 method for signature 'ROISurface'
length(x)

Arguments

Value

An integer giving the number of vertices

Description

Loads surface geometry data from a source object.

Usage

## S4 method for signature 'NeuroSurfaceVectorSource'
load_data(x)

## S4 method for signature 'NeuroSurfaceSource'
load_data(x)

## S4 method for signature 'FreesurferSurfaceGeometryMetaInfo'
load_data(x)

## S4 method for signature 'GIFTISurfaceGeometryMetaInfo'
load_data(x)

## S4 method for signature 'SurfaceGeometrySource'
load_data(x)

Arguments

Value

A SurfaceGeometry object containing the loaded mesh data

Description

This is a high-level wrapper that mirrors the API of neuromaps' fetch_fsaverage() but is currently limited to the "std.8" decimated fsaverage surfaces that ship with neurosurf. The function name uses "load" rather than "fetch" to follow common R idioms.

Usage

load_fsaverage(
  density = "std.8",
  surf = c("smoothwm", "pial", "inflated", "white", "sphere")
)

Arguments

Value

A named list with elements "lh" and "rh", each a SurfaceGeometry instance.

Examples

fs <- load_fsaverage(density = "std.8", surf = "inflated")
if (interactive()) {
  show_surface_plot(fs$lh, fs$rh, views = c("lateral", "medial"))
}

Description

Load a bundle of fsaverage surface variants as a SurfaceSet

Usage

load_fsaverage_bundle(
  density = "std.8",
  surfs = c("smoothwm", "pial", "inflated", "white", "sphere"),
  default_label = "smoothwm"
)

Arguments

Value

A named list with elements \"lh\" and \"rh\", each a SurfaceSet containing the requested variants.

Examples

bundle <- load_fsaverage_bundle()
lh_set <- bundle$lh
rh_set <- bundle$rh

Description

This convenience helper loads the FreeSurfer fsaverage surfaces that ship with neurosurf (the std.8 decimated variant) and returns them as SurfaceGeometry objects.

Usage

load_fsaverage_std8(
  surf = c("smoothwm", "pial", "inflated", "white", "sphere")
)

Arguments

Value

A named list with elements "lh" and "rh", each a SurfaceGeometry instance for the requested surface type.

Examples

fs <- load_fsaverage_std8("smoothwm")
if (interactive()) {
  show_surface_plot(fs$lh, fs$rh, views = c("lateral", "medial"))
}

Description

load Freesurfer ascii surface

Usage

loadFSSurface(meta_info, surf_to_world = diag(4))

Arguments

Details

requires rgl library

Value

a class of type SurfaceGeometry

Examples

# Requires FreeSurfer surface file
# meta <- read_meta_info(FreesurferAsciiSurfaceFileDescriptor(), "lh.pial.asc")
# geom <- loadFSSurface(meta)

Description

Loads a GIFTI (.surf.gii) surface into a SurfaceGeometry. The usual public entry point for reading a surface from disk is read_surf_geometry / read_surf; this function is the GIFTI-specific loader it dispatches to. For convenience it also accepts a file path directly, in which case the header is read internally.

Usage

loadGIFTISurface(meta_info)

Arguments

Details

requires rgl library

Value

a class of type SurfaceGeometry

Examples

# Either pass a path directly ...
# geom <- loadGIFTISurface("lh.midthickness.surf.gii")
# ... or go through the meta-info object:
# meta <- read_meta_info(neurosurf:::GIFTI_SURFACE_DSET, "lh.midthickness.surf.gii")
# geom <- loadGIFTISurface(meta)

Description

Map Values for NeuroSurface with List Lookup

Usage

## S4 method for signature 'NeuroSurface,list'
map_values(x, lookup)

Arguments

Value

A NeuroSurface object with remapped values

Description

Map Values for NeuroSurface with Matrix Lookup

Usage

## S4 method for signature 'NeuroSurface,matrix'
map_values(x, lookup)

Arguments

Value

A NeuroSurface object with remapped values

Description

This function creates an igraph object representing the connectivity structure of a 3D mesh based on its vertices and triangular faces.

Usage

meshToGraph(vertices, nodes)

Arguments

Details

The function converts a triangular mesh into a graph representation where:

• Vertices of the graph correspond to vertices of the mesh

• Edges of the graph correspond to the edges of triangular faces in the mesh

The function performs the following steps:

1. Extracts all unique edges from the triangular faces

2. Creates an undirected graph from these edges

3. Simplifies the graph to remove duplicate edges and loops

4. Calculates Euclidean distances between connected vertices

5. Adds vertex coordinates and edge distances as attributes to the graph

Note that the input nodes matrix should use 0-based indexing (starting from 0), as the function will increment indices by 1 when creating the graph.

Value

An igraph object representing the mesh connectivity. The graph has the following attributes:

• Vertex attributes: "x", "y", and "z" coordinates from the vertices matrix

• Edge attribute: "dist" (Euclidean distance between connected vertices)

See Also

SurfaceGeometry, graph_from_edgelist

Examples

# Create a simple cube mesh with 8 vertices
vertices <- matrix(c(
  0, 0, 0,  # vertex 1
  1, 0, 0,  # vertex 2
  1, 1, 0,  # vertex 3
  0, 1, 0,  # vertex 4
  0, 0, 1,  # vertex 5
  1, 0, 1,  # vertex 6
  1, 1, 1,  # vertex 7
  0, 1, 1   # vertex 8
), ncol = 3, byrow = TRUE)

# Define triangular faces with 0-based indices
faces <- matrix(c(
  # bottom face (z=0)
  0, 1, 2,
  0, 2, 3,
  # top face (z=1)
  4, 5, 6,
  4, 6, 7,
  # front face (y=0)
  0, 1, 5,
  0, 5, 4,
  # back face (y=1)
  2, 3, 7,
  2, 7, 6,
  # left face (x=0)
  0, 3, 7,
  0, 7, 4,
  # right face (x=1)
  1, 2, 6,
  1, 6, 5
), ncol = 3, byrow = TRUE)

# Create the graph representation of the mesh
graph <- meshToGraph(vertices, faces)

# Examine the graph properties
cat("Number of vertices:", igraph::vcount(graph), "\n")
cat("Number of edges:", igraph::ecount(graph), "\n")

# Plot the graph if igraph is available
if (interactive() && requireNamespace("igraph", quietly = TRUE) &&
    requireNamespace("rgl", quietly = TRUE)) {
  # First visualize the mesh
  rgl::open3d()
  mesh <- rgl::tmesh3d(
    vertices = t(vertices),
    indices = t(faces) + 1,  # rgl uses 1-based indexing
    homogeneous = FALSE
  )
  rgl::shade3d(mesh, col = "lightblue")
  rgl::title3d(main = "Original Mesh")

  # Visualize the graph connections using the 3D coordinates
  rgl::open3d()
  # Plot vertices
  rgl::points3d(vertices[,1], vertices[,2], vertices[,3], size = 10, col = "red")
  # Plot edges
  edges <- igraph::as_edgelist(graph)
  for (i in 1:nrow(edges)) {
    v1 <- edges[i, 1]
    v2 <- edges[i, 2]
    coords <- vertices[c(v1, v2), ]
    rgl::lines3d(coords[,1], coords[,2], coords[,3], col = "black", lwd = 2)
  }
  rgl::title3d(main = "Graph Representation")
}

Description

This generic function constructs a neighborhood graph from a surface mesh using edge weights. It allows for flexible definition of neighborhoods based on edge radius and custom edge weights.

Usage

neighbor_graph(x, radius, edgeWeights = missing(), nodes = missing(), ...)

## S4 method for signature 'igraph,numeric,missing,missing'
neighbor_graph(
  x,
  radius,
  edgeWeights = NULL,
  nodes = NULL,
  distance_type = c("geodesic", "euclidean", "spherical")
)

## S4 method for signature 'SurfaceGeometry,numeric,missing,missing'
neighbor_graph(
  x,
  radius,
  edgeWeights = NULL,
  nodes = NULL,
  distance_type = c("geodesic", "euclidean", "spherical")
)

## S4 method for signature 'SurfaceGeometry,numeric,numeric,missing'
neighbor_graph(
  x,
  radius,
  edgeWeights,
  distance_type = c("geodesic", "euclidean", "spherical")
)

## S4 method for signature 'SurfaceGeometry,numeric,numeric,integer'
neighbor_graph(
  x,
  radius,
  edgeWeights,
  nodes,
  distance_type = c("geodesic", "euclidean", "spherical")
)

## S4 method for signature 'SurfaceGeometry,numeric,missing,integer'
neighbor_graph(
  x,
  radius,
  nodes,
  distance_type = c("geodesic", "euclidean", "spherical")
)

Arguments

Details

The neighborhood graph is constructed by considering edges within the specified radius and applying the provided edge weights. This function is particularly useful in neuroimaging analyses for defining local connectivity on brain surfaces.

Value

An object representing the constructed neighborhood graph. The specific class depends on the method implementation.

See Also

graph, vertices

Examples

geom <- example_surface_geometry()
graph <- neighbor_graph(geom, radius = 1)
igraph::vcount(graph)



# Build a neighbor graph from a simple SurfaceGeometry
geom <- example_surface_geometry()
g_geom <- neighbor_graph(geom, radius = 1)
igraph::vcount(g_geom)

Description

Data structures and IO for surface-based neuroimaging data.

Author(s)

Maintainer: Bradley R Buchsbaum [email protected] [copyright holder]

See Also

Useful links:

• https://github.com/bbuchsbaum/neurosurf

• Report bugs at https://github.com/bbuchsbaum/neurosurf/issues

Description

Downloads larger test data files that are not included in the CRAN package due to size constraints. These files are hosted on GitHub releases and are useful for running the full test suite or exploring additional file formats.

Usage

neurosurf_download_testdata(
  files = "all",
  destdir = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

The test data files are hosted on GitHub releases for the neurosurf package. This function requires an internet connection to download the files.

If you are running tests locally and want the full test suite, run neurosurf_download_testdata("all") once after installing the package.

Value

Invisibly returns the paths to downloaded files.

Examples

# Download all test data
neurosurf_download_testdata("all")

# Download only the GIFTI file
neurosurf_download_testdata("rscan01_lh.gii")

Description

This function creates a new NeuroSurface object, which represents a single set of data values associated with nodes on a surface geometry.

Usage

NeuroSurface(geometry, indices, data)

Arguments

Details

The NeuroSurface object is designed to store and manipulate a single set of data values associated with nodes on a surface. This can represent various neuroimaging measures such as cortical thickness, functional activation, or any other node-wise metric.

The length of the data vector should match the length of the indices vector. Nodes not included in the indices vector are considered to have no data or to be invalid.

Value

A new object of class NeuroSurface containing:

See Also

SurfaceGeometry, NeuroSurfaceVector

Examples

surf_geom <- example_surface_geometry()
indices <- seq_len(nrow(coords(surf_geom)))  # all vertices
data_values <- rnorm(length(indices))        # Example data
neuro_surf <- NeuroSurface(surf_geom, indices, data_values)

Description

a three-dimensional surface consisting of a set of triangle vertices with one value per vertex.

Details

The NeuroSurface class is a fundamental representation of surface-based neuroimaging data. It combines geometric information about a brain surface with data values mapped to each vertex of that surface.

The class consists of three core components:

• geometry: The underlying 3D surface structure, containing vertex coordinates, face definitions, and topological information

• indices: Identifiers for the subset of vertices in the geometry that have associated data values

• data: A numeric vector containing one value per vertex, representing measurements such as cortical thickness, functional activation, or any other surface-mapped metric

This class serves as the foundation for more specialized surface representations like ColorMappedNeuroSurface, VertexColoredNeuroSurface, and LabeledNeuroSurface. It facilitates common operations such as visualization, statistical analysis, and spatial processing of surface-based neuroimaging data.

Value

An object of class NeuroSurface.

Slots

geometry

the surface geometry, an instance of SurfaceGeometry or SurfaceSet

indices

an integer vector specifying the subset of valid surface nodes encoded in the geometry object.

data

the 1-D vector of data value at each vertex of the mesh

Examples

# Create a simple tetrahedron mesh for the example
vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d object
mesh <- rgl::mesh3d(vertices = vertices, triangles = triangles)

# Create a graph representation
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
graph <- igraph::graph_from_edgelist(edges)

# Create a SurfaceGeometry object
geometry <- new("SurfaceGeometry",
               mesh = mesh,
               graph = graph,
               hemi = "left")

# Define indices for all vertices
indices <- 1:4

# Create data values for each vertex
vertex_data <- c(0.5, 1.2, 0.8, 1.5)  # example values for the vertices

# Create the NeuroSurface object
neuro_surface <- new("NeuroSurface",
                    geometry = geometry,
                    indices = indices,
                    data = vertex_data)

# The data values are now mapped to the surface vertices
# and can be visualized or analyzed

Description

The 'NeuroSurfaceSource' class serves as a factory for creating NeuroSurface instances. It encapsulates all necessary information to construct a neuroimaging surface, including geometry, metadata, and indexing information.

Usage

NeuroSurfaceSource(
  surface_geom,
  surface_data_name,
  colind = NULL,
  nodeind = NULL
)

Arguments

Details

This class is designed to facilitate the creation of NeuroSurface objects by providing a standardized way to store and access all required components. It combines geometric information, metadata, and indexing details necessary for constructing a complete neuroimaging surface representation.

Value

An object of class NeuroSurfaceSource or NeuroSurfaceVectorSource that contains information about the surface geometry and associated data. If the data has multiple columns (colind > 1), a NeuroSurfaceVectorSource is returned; otherwise, a NeuroSurfaceSource is returned. These objects can be used to load and map neuroimaging data onto brain surfaces.

Slots

geometry

An object of class SurfaceGeometry representing the underlying surface structure.

data_meta_info

An object of class SurfaceDataMetaInfo containing metadata about the surface data.

colind

An integer specifying the column index of the surface map to be loaded.

nodeind

An integer vector specifying the node indices of the surface map to be loaded.

See Also

NeuroSurface, SurfaceGeometry, SurfaceDataMetaInfo

Examples

# Create a simple mesh for the example
vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d object
mesh <- rgl::mesh3d(vertices = vertices, triangles = triangles)

# Create a graph representation
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
graph <- igraph::graph_from_edgelist(edges)

# Create a SurfaceGeometry object
geometry <- new("SurfaceGeometry",
               mesh = mesh,
               graph = graph,
               hemi = "left")

# Create a SurfaceDataMetaInfo object
data_meta_info <- new("SurfaceDataMetaInfo",
                      header_file = "data_meta.txt",
                      data_file = "surface_data.1D",
                      file_descriptor = new("FileFormat"),
                      node_count = 4L,
                      nels = 1L,
                      label = "thickness")

# Create a NeuroSurfaceSource object
neuro_source <- new("NeuroSurfaceSource",
                    geometry = geometry,
                    data_meta_info = data_meta_info,
                    colind = 1L,
                    nodeind = 1:4)

Description

construct a new NeuroSurfaceVector

Usage

NeuroSurfaceVector(geometry, indices, mat)

Arguments

Value

A NeuroSurfaceVector object containing the geometry, node indices, and data matrix.

Description

Represents a 3D surface with multiple values per vertex.

Details

The NeuroSurfaceVector class extends the concept of NeuroSurface to handle multiple measurements for each vertex across the entire surface. Unlike NeuroSurface which stores a single value per vertex, NeuroSurfaceVector stores a matrix of values where columns represent different measures and rows correspond to vertices.

This structure is particularly useful for:

• Time series data where each column represents a different timepoint

• Multi-modal data where each column represents a different imaging modality

• Statistical results where columns represent different statistical parameters

• Feature vectors for machine learning applications

The data matrix organization (vertices as rows, measures as columns) facilitates efficient vertex-wise operations and analyses. This is in contrast to ROISurfaceVector where the matrix is transposed (measures as rows, vertices as columns).

Value

An object of class NeuroSurfaceVector

Slots

geometry

SurfaceGeometry instance representing the surface structure

indices

Integer vector of valid surface node indices

data

Matrix of values, where columns represent different measures and rows correspond to surface nodes

Note

The number of rows in 'data' must match the number of nodes in 'geometry'.

See Also

SurfaceGeometry, NeuroSurface

Examples

# Create a simple tetrahedron mesh for the example
vertices <- c(
  0, 0, 0,
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)
triangles <- c(
  1, 2, 3,
  1, 2, 4,
  1, 3, 4,
  2, 3, 4
)

# Create mesh3d object
mesh <- rgl::mesh3d(vertices = vertices, triangles = triangles)

# Create a graph representation
edges <- rbind(
  c(1,2), c(1,3), c(1,4),
  c(2,3), c(2,4),
  c(3,4)
)
graph <- igraph::graph_from_edgelist(edges)

# Create a SurfaceGeometry object
geometry <- new("SurfaceGeometry",
               mesh = mesh,
               graph = graph,
               hemi = "left")

# Define indices for all vertices
indices <- 1:4

# Create a Matrix with multiple measures for each vertex
# Each row corresponds to a vertex, each column to a different measure
require(Matrix)
vertex_data <- Matrix(
  c(0.5, 1.2, 0.8,    # Measure 1 values for vertices 1-4
    0.7, 0.3, 1.5, 0.9,  # Measure 2 values for vertices 1-4
    1.1, 0.6, 0.4, 1.3), # Measure 3 values for vertices 1-4
  nrow = 4, ncol = 3,
  byrow = FALSE
)

# Create the NeuroSurfaceVector object
neuro_surface_vector <- new("NeuroSurfaceVector",
                         geometry = geometry,
                         indices = indices,
                         data = vertex_data)

# The data matrix now maps multiple values to each surface vertex
# Vertex 1 has values: 0.5, 0.7, 1.1
# Vertex 2 has values: 1.2, 0.3, 0.6
# etc.

Description

A class that is used to produce a NeuroSurfaceVector instance

Value

An object of class NeuroSurfaceVectorSource.

Slots

geometry

a SurfaceGeometry instance

data_meta_info

a SurfaceDataMetaInfo instance

colind

the column indices vector of the surface maps to be loaded

Description

This class contains meta information for surface-based data for the NIML data format

Value

An object of class NIMLSurfaceDataMetaInfo.

Slots

data

the numeric data matrix of surface values (rows = nodes, columns=surface vectors)

node_indices

the indices of the nodes for mapping to associated surface geometry.

Examples

meta_info <- new("SurfaceDataMetaInfo",
                 header_file = "data_header.txt",
                 data_file = "surface_data.niml.dset",
                 file_descriptor = new("FileFormat"),
                 node_count = length(nodes(geometry)),
                 nels = 2L,
                 label = "thickness")

surface_data <- matrix(rnorm(meta_info@node_count * meta_info@nels),
                       nrow = meta_info@node_count, ncol = meta_info@nels)

niml_meta <- new("NIMLSurfaceDataMetaInfo",
                header_file = meta_info@header_file,
                data_file = meta_info@data_file,
                file_descriptor = meta_info@file_descriptor,
                node_count = meta_info@node_count,
                nels = meta_info@nels,
                label = meta_info@label,
                data = surface_data,
                node_indices = seq_len(meta_info@node_count))

Description

This class supports the NIML file format for surface-based data

Value

An object of class NIMLSurfaceFileDescriptor.

Description

Retrieves the node numbers from a surface object.

Usage

nodes(x)

## S4 method for signature 'SurfaceGeometry'
nodes(x)

## S4 method for signature 'NeuroSurface'
nodes(x)

## S4 method for signature 'NeuroSurfaceVector'
nodes(x)

Arguments

Value

A vector of node numbers.

See Also

vertices

Examples

geom <- example_surface_geometry()
nodes(geom)

Description

Parcel boundary contact matrix

Usage

parcel_boundary_contact(
  labeled_surface,
  component_policy = c("error", "largest", "each", "merge"),
  counts = FALSE
)

Arguments

Value

Matrix (logical or integer) indicating parcel-unit boundary contacts.

Examples

# Requires a LabeledNeuroSurface
# lsurf <- read_freesurfer_annot("lh.aparc.annot", geom)
# contact <- parcel_boundary_contact(lsurf)

Description

Parcel centroids using geodesic medoids

Usage

parcel_geodesic_centroid(
  labeled_surface,
  method = c("medoid", "euclidean"),
  component_policy = c("error", "largest", "each", "merge"),
  weights = NULL,
  chunk_size = 2000,
  cache = TRUE
)

Arguments

Value

Data frame with one row per parcel unit: unit, parcel_id, component, size, centroid_vertex, and Cartesian coordinates.

Examples

# Requires a LabeledNeuroSurface
# lsurf <- read_freesurfer_annot("lh.aparc.annot", geom)
# centroids <- parcel_geodesic_centroid(lsurf)

Description

Parcel-to-parcel geodesic distances

Usage

parcel_geodesic_distance_matrix(
  labeled_surface,
  metric = c("centroid", "min"),
  component_policy = c("error", "largest", "each", "merge"),
  weights = NULL,
  chunk_size = 2000,
  cache = TRUE
)

Arguments

Value

A numeric matrix with parcel-unit names as dimnames.

Examples

# Requires a LabeledNeuroSurface
# lsurf <- read_freesurfer_annot("lh.aparc.annot", geom)
# dmat <- parcel_geodesic_distance_matrix(lsurf)

Description

Plot Surface as an HTMLWidget

Usage

plot_js(x, width = NULL, height = NULL, ...)

## S4 method for signature 'SurfaceGeometry'
plot_js(x, width = NULL, height = NULL, ...)

Arguments

Value

An HTMLWidget object

Examples

geom <- example_surface_geometry()
widget <- plot_js(geom)

Description

Renders a surface object using the interactive viewer.

Usage

## S4 method for signature 'SurfaceGeometry,missing'
plot(
  x,
  vals = NA,
  cmap = grDevices::gray(seq(0, 1, length.out = 255)),
  vert_clrs = NULL,
  irange = range(vals),
  thresh = c(0, 0),
  alpha = 1,
  specular = "black",
  bgcol = "lightgray",
  ...
)

## S4 method for signature 'NeuroSurface,missing'
plot(
  x,
  cmap = grDevices::gray(seq(0, 1, length.out = 255)),
  vert_clrs = NULL,
  irange = range(x@data, na.rm = TRUE),
  thresh = c(0, 0),
  alpha = 1,
  specular = "black",
  bgcol = "lightgray",
  ...
)

## S4 method for signature 'LabeledNeuroSurface,missing'
plot(
  x,
  cmap = x@cols,
  vert_clrs = NULL,
  irange = range(x@data, na.rm = TRUE),
  thresh = c(0, 0),
  alpha = 1,
  specular = "black",
  bgcol = "lightgray",
  ...
)

## S4 method for signature 'ColorMappedNeuroSurface,missing'
plot(
  x,
  vert_clrs = NULL,
  alpha = 1,
  specular = "black",
  bgcol = "lightgray",
  ...
)

## S4 method for signature 'VertexColoredNeuroSurface,missing'
plot(x, alpha = 1, specular = "black", bgcol = "lightgray", ...)

Arguments

Value

An htmlwidget object for interactive visualization

Description

This is a convenience wrapper that renders a multi-panel surface layout and draws it to a new grid device.

Usage

## S3 method for class 'neurosurf_plot'
plot(x, ...)

Arguments

Value

Invisibly returns the input neurosurf_plot object.

Description

Plot method for SurfaceGeometry objects

Usage

## S3 method for class 'SurfaceGeometry'
plot(x, y, ...)

Arguments

Value

Invisibly returns the object ID(s) from the RGL scene.

Examples

geom <- example_surface_geometry()
if (interactive()) {
  plot(geom)
}

Description

Plot method for SurfaceSet objects

Usage

## S3 method for class 'SurfaceSet'
plot(x, y, label = NULL, ...)

Arguments

Value

Invisibly returns the object ID(s) from the RGL scene.

Examples

geom <- example_surface_geometry()
ss <- surface_set(inflated = geom)
if (interactive()) {
  plot(ss)
}

Description

Print Method for Searchlight Iterator

Usage

## S3 method for class 'Searchlight'
print(x, ...)

Arguments

Value

Invisibly returns the Searchlight object (called for side effect).

Description

This function projects a set of 3D coordinates onto a given surface and creates a NeuroSurface object with the smoothed values. The projection is performed by finding the closest points on the surface, and then a kernel density smoother is applied locally to produce the final values.

Usage

projectCoordinates(surfgeom, points, sigma = 5, ...)

Arguments

Details

The function first projects each 3D coordinate onto the closest point on the surface defined by surfgeom. The values at these projected points are then smoothed using a kernel density smoother, where the sigma parameter controls the extent of the smoothing. The result is a NeuroSurface object containing the smoothed values, suitable for further analysis or visualization.

Value

A NeuroSurface object with the smoothed values mapped onto the surface.

Examples

# Load a sample surface from the package
surf_file <- system.file("extdata", "std.8_lh.inflated.asc", package = "neurosurf")
surfgeom <- read_surf_geometry(surf_file)

# Get the surface coordinates
surf_coords <- coords(surfgeom)

# Create some sample 3D coordinates to project
# We'll use a subset of the surface vertices with small random offsets
set.seed(123)
sample_indices <- sample(1:nrow(surf_coords), 50)
sample_coords <- surf_coords[sample_indices, ] + matrix(rnorm(150, 0, 0.5), ncol = 3)

# Project these coordinates onto the surface
projected_surface <- projectCoordinates(surfgeom, sample_coords, sigma = 3)

# Check the result
vals <- series(projected_surface, indices(projected_surface))
max(vals)        # Maximum density value
sum(vals > 0)    # Number of vertices with non-zero values

Description

Creates an iterator that randomly samples searchlight regions on a surface mesh using geodesic distance to define regions.

Usage

RandomSurfaceSearchlight(
  surfgeom,
  radius = 8,
  nodeset = NULL,
  as_deflist = FALSE
)

Arguments

Details

On each call to nextElem, a set of surface nodes is returned. These nodes index into the vertices of the igraph instance. When as_deflist=TRUE, the random ordering of centers is fixed when the object is created. Use set.seed before construction for reproducible sequences.

Value

An iterator object of class "RandomSurfaceSearchlight".

Examples

file <- system.file("extdata", "std.8_lh.smoothwm.asc", package = "neurosurf")
geom <- read_surf(file)
searchlight <- RandomSurfaceSearchlight(geom, 12)
set.seed(42)
dl <- RandomSurfaceSearchlight(geom, 12, as_deflist=TRUE)
attr(dl[[1]], "center")
nodes <- searchlight$nextElem()
length(nodes) > 1

Description

Reads a Freesurfer annotation file and creates a LabeledNeuroSurface object.

Usage

read_freesurfer_annot(file_name, geometry)

Arguments

Details

This function reads binary data from a FreeSurfer annotation file, which includes vertex labels, color information, and label names. It then constructs a LabeledNeuroSurface object using this information along with the provided surface geometry.

Value

A LabeledNeuroSurface object containing:

Examples

# Read a FreeSurfer annotation file (requires actual annotation file)
geom <- example_surface_geometry()
# labeled_surface <- read_freesurfer_annot("lh.aparc.annot", geom)

Description

Generic function to read image meta info given a file and a FileFormat instance from neuroim2.

Usage

## S4 method for signature 'AFNISurfaceFileDescriptor'
read_meta_info(x, file_name)

## S4 method for signature 'NIMLSurfaceFileDescriptor'
read_meta_info(x, file_name)

## S4 method for signature 'FreesurferAsciiSurfaceFileDescriptor'
read_meta_info(x, file_name)

## S4 method for signature 'FreesurferBinarySurfaceFileDescriptor'
read_meta_info(x, file_name)

## S4 method for signature 'GIFTISurfaceFileDescriptor'
read_meta_info(x, file_name)

Arguments

Value

A meta info object containing header information from the surface file

A metadata information object describing the surface file structure

Description

This function reads surface data from a file in one of the supported formats.

Usage

read_surf(
  surface_name,
  surface_data_name = NULL,
  colind = NULL,
  nodeind = NULL
)

Arguments