Package 'ggsegExtra'

Description

This function will create an atlas ready data.frame for ggseg3d to plot with plotly.

Usage

aparc_2_mesh(
  subject = "fsaverage5",
  hemisphere = "rh",
  surface = "inflated",
  annot = "aparc",
  subjects_dir = freesurfer::fs_subj_dir(),
  annot_dir = file.path(subjects_dir, subject, "label"),
  output_dir = tempdir(),
  cleanup = TRUE,
  verbose = TRUE
)

Arguments

Details

Based on A. Winkler scripts

Value

data frame with one row per label

Examples

## Not run: 
dt <- aparc_2_mesh()
dt <- aparc_2_mesh(surface = "white")
dt <- aparc_2_mesh(hemisphere = "lh")
dt <- aparc_2_mesh(annot = "aparc.a2009s")

## End(Not run)

Description

Create a FreeSurfer colortab based on labels. Calls FreeSurfer's mris_lab2ctab

Usage

atlas_lab2ctab(output_dir, verbose)

Arguments

Value

returns nothing, creates files on the file system

Description

Turn volumetric files into labels for use in annotations. Calls FreeSurfer's mri_vol2label.

Usage

atlas_vol2label(annot_lab, output_dir, verbose, ncores = 2)

Arguments

Value

invisibly returns the list of labels.

Description

Transform a Nifti volume to a surface file for FreeSurfer. Calls FreeSurfer's mri_vol2surf for the transformation.

Usage

atlas_vol2surf(input_file, output_dir, projfrac = 0.5, verbose = TRUE)

Arguments

Value

nothing, creates surface files

Description

Change meshes to new system

Usage

change_meshes(mesh)

Arguments

Description

Check if FS can be run

Usage

check_fs(msg = NULL)

Arguments

Value

logical

Description

Function to convert Freesurfer curvature file into .ply

Usage

curv2ply(input_file, output_file = paste(input_file, ".ply"), verbose = TRUE)

Arguments

Value

.ply text

Description

Available Freesurfer curvatures

Usage

fs_curvatures()

Value

character

Examples

fs_curvatures()

Description

Available Freesurfer no fix curvatures

Usage

fs_nofixcurv()

Value

character

Examples

fs_nofixcurv()

Description

Available Freesurfer surfaces

Usage

fs_surfaces()

Value

character

Examples

fs_surfaces()

Description

.ply files contain a lot of information. for ggseg3d, we only need information on the vertices and faces of the mesh. Thes function opens a ply file, and organises the meshes and faces into a single list.

Usage

get_mesh(ply, ...)

Arguments

Value

list of meshes and faces

Examples

## Not run: 
get_mesh("path/to/surface.ply")

# Turn off showing the ply when reading
get_mesh("path/to/surface.ply", ShowSpecimen = FALSE)

## End(Not run)

Description

Function to easily find all online repositories that contain ggseg atlases

Usage

ggseg_atlas_repos(pattern = NULL, ...)

Arguments

Value

data frame of online repositories with ggseg-atlases

Examples

ggseg_atlas_repos()

ggseg_atlas_repos("yeo")

Description

installs ggseg-atlas library from the ggseg r-universe <https://ggseg.r-universe.dev/ui#builds> .

Usage

install_ggseg_atlas(
  package,
  repos = c(ggseg = "https://ggseg.r-universe.dev", getOption("repos")),
  ...
)

Arguments

Details

To install, will temporarily alter your install repo settings to also use the ggseg r-universe build as source for packages. These settings will be restored when the function exits.

Examples

## Not run: 
yeo2011_repo <- ggseg_atlas_repos("yeo2011")
install_ggseg_atlas(yeo2011_repo$repo, yeo2011_repo$source)

## End(Not run)

Description

Calls ggseg_atlas_repos, and installs all libraries listed. Be careful calling this function, this will likely take quite some time to complete, and also will contain a lot of heavy data. We recommend only installing atlases you are likely to use and on demand.

Usage

install_ggseg_atlas_all(
  repos = c(ggseg = "https://ggseg.r-universe.dev", getOption("repos")),
  ...
)

Arguments

Examples

## Not run: 
install_ggseg_atlas_all()

## End(Not run)

Description

Check if object is colourtable

Usage

is_ctab(colourtable)

Arguments

Value

logical

Description

Convert LCBC surface file to other subjects

Usage

lcbc_surf2surf(
  input_volume,
  source_subject = "fsaverage",
  target_subject = "fsaverage5",
  hemisphere = "rh",
  subjects_dir = fs_subj_dir(),
  output_dir = file.path(subjects_dir, target_subject, "surf"),
  cortex = TRUE,
  verbose = TRUE
)

Arguments

Description

Function loops through hemispheres and surfaces to create a data frame that is ready to use with ggseg3d.

Usage

make_aparc_2_3datlas(
  annot,
  subject = "fsaverage5",
  hemisphere = c("rh", "lh"),
  surface = c("inflated", "LCBC"),
  subjects_dir = freesurfer::fs_subj_dir(),
  annot_dir = file.path(subjects_dir, subject, "label"),
  output_dir = tempdir(),
  ncores = parallel::detectCores() - 2,
  cleanup = TRUE,
  verbose = TRUE
)

Arguments

Details

It is recommended that you change the region names for the atlas, and the atlas name to something shorter. See the dk_3d atlas for examples.

Value

nested data frame as ggseg3d-atlas

Examples

## Not run: 
dt <- aparc_2_3datlas(annot = "aparc.a2009s")
dt <- aparc_2_3datlas(annot = "aparc.a2009s",
                      surface = "sphere")

## End(Not run)

Description

Function will create a data.frame based on a ggseg3d atlas, based on the contours of each segment.

Usage

make_ggseg3d_2_ggseg(
  ggseg3d_atlas,
  steps = 1:7,
  output_dir = tempdir(),
  tolerance = 0,
  smoothness = 5,
  cleanup = FALSE,
  ncores = 2
)

Arguments

Value

data.frame ready for manual cleaning before turning into a proper ggseg3d-atlas

Examples

## Not run: 

# Create the DKT atlas as found in the FreeSurfer Subjects directory
# And output the temporary files to the Desktop.
dkt_3d <- make_aparc_2_3datlas(annot = "aparc.DKTatlas",
    output_dir = "~/Desktop/")

## End(Not run)

Description

atlases in ggseg have palettes based on colours from the paper originally introducing the atlas. These colours are hard-coded into ggseg3d-atlases. This function extracts those and makes a object ready for incorporation to a ggseg-atlas repository

Usage

make_palette_ggseg(ggseg3d_atlas)

Arguments

Value

list with a colour palette

Examples

make_palette_ggseg(dk_3d)

Description

Function to create a ggseg3d-atlas from a volumetric parcellation. Currently only tested using .mgz extension images. Will call command-line tools to complete the process.

Usage

make_volumetric_2_3datlas(
  template,
  color_lut,
  subject = "fsaverage5",
  subjects_dir = freesurfer::fs_subj_dir(),
  steps = 1:5,
  output_dir = tempdir(),
  verbose = TRUE,
  ncores = parallel::detectCores() - 2,
  cleanup = TRUE
)

Arguments

Details

the function is aggressive in the number of cores used to minimize time taken to create the atlas. Set the ncores argument for less aggressive approach.

Value

returns a ggseg3d-atlas ready object. Might need manual cleaning to become a good atlas.

Examples

## Not run: 

fs_subject_dir <- freesurfer::fs_dir()
aseg_temp <- file.path(fs_subject_dir, "fsaverage5/mri/aseg.mgz")
colorlut <- file.path(fs_subject_dir, "ASegStatsLUT.txt")

make_volumetric_2_3datlas(aseg_temp, colorlut)

## End(Not run)

Description

If making an atlas from a non-cortical atlas, volumetric atlases are the best options. Instead of snapshotting images of inflated brain, will snapshot brain slices given x, y, z coordinates for the slices trhoush the slices argument.

Usage

make_volumetric_ggseg(
  label_file,
  subject = "fsaverage5",
  subjects_dir = fs_subj_dir(),
  output_dir = tempdir(),
  color_lut = NULL,
  steps = 1:8,
  skip_existing = TRUE,
  slices = data.frame(x = c(130, 122, 122), y = c(130, 235, 112), z = c(130, 100, 106),
    view = c("axial", "sagittal", "coronal"), stringsAsFactors = FALSE),
  vertex_size_limits = NULL,
  dilate = NULL,
  tolerance = 0,
  ncores = 2,
  smoothness = 5,
  verbose = TRUE,
  cleanup = FALSE
)

Arguments

Value

brain-atlas class

Examples

## Not run: 

   label_file <- file.path(fs_subj_dir(), subject, "mri/aseg.mgz")
   slices = data.frame(x=130, y=130, z=130, view="axial", stringsAsFactors = FALSE)
   
   aseg2 <- make_volumetric_ggseg(
      label_file =  label_file,
      slices = slices
   )

   # Have a look at the atlas
   plot(aseg2)

## End(Not run)

Description

Calls FreeSurfer's mri_annotation2label to split an annotation file into several labels.

Usage

mri_annotation2label(
  annot_name,
  subject = "fsaverage5",
  hemisphere = "lh",
  output_dir = fs_subj_dir(),
  verbose = TRUE,
  opts = NULL
)

Arguments

Value

nothing. Runs command line to write label files

Examples

if(freesurfer::have_fs()){
# for freesurfer help see:
freesurfer::fs_help("mri_annotation2label")
mri_annotation2label(annot_name = "aparc")

mri_annotation2label(annot_name = "aparc.a2009s")

mri_annotation2label(subject = "fsaverage", annot_name = "aparc.a2009s")
}

Description

Annotation files are subject specific. Most are registered for fsaverage, but we recommend using fsaverage5 for the mesh plots in ggseg3d, as these contain a decent balance in number of vertices for detailed rendering and speed.

Usage

mri_surf2surf_rereg(
  subject,
  annot,
  hemi = c("lh", "rh"),
  target_subject = "fsaverage5",
  output_dir = file.path(fs_subj_dir(), subject, "label"),
  verbose = TRUE
)

Arguments

Value

nothing

Examples

if(freesurfer::have_fs()){

# For help see:
freesurfer::fs_help("mri_surf2surf")

mri_surf2surf_rereg(subject = "bert", 
                    annot = "aparc.DKTatlas",
                    target_subject = "fsaverage5")
}

Description

Converts values in a volume or surface overlay to a label. The program searches the input for values equal to labelid. The xyz values for each point are then computed based on the tkregister voxel-to-RAS matrix (volume) or from the xyz of the specified surface. The xyz values are then stored in labelfile in the label file format. The statistic value is set to 0. While this program can be used with any mri volume, it was designed to convert parcellation volumes, which happen to be stored in mri format. Calls FreeSurfer's mri_vol2label.

Usage

mri_vol2label(
  input_file,
  label_id,
  hemisphere,
  output_dir,
  surface = NULL,
  subject = "fsaverage5",
  subjects_dir = fs_subj_dir(),
  opts = NULL,
  verbose = TRUE
)

Arguments

Value

returns nothing. Writes a label file.

Examples

if(freesurfer::have_fs()){
# for freesurfer help see:
freesurfer::fs_help("mri_vol2label")

out_dir <- tempdir()
vol <- file.path(freesurfer::fs_subj_dir(),
                 "fsaverage5/mri/aseg.mgz")

mri_vol2label(vol, 
     label_id = 2, 
     hemisphere = "rh", 
     output_dir = out_dir)
 
 # delete output dir when not needed
 unlink(out_dir)
}

Description

For a single subject, produces an annotation file, in which each cortical surface vertex is assigned a neuroanatomical label. This automatic procedure employs data from a previously-prepared atlas file. An atlas file is created from a training set, capturing region data manually drawn by neuroanatomists combined with statistics on variability correlated to geometric information derived from the cortical model (sulcus and curvature). Besides the atlases provided with FreeSurfer, new ones can be prepared using mris_ca_train).

Usage

mris_ca_label(
  subject = "fsaverage5",
  hemisphere = "lh",
  canonsurf = "sphere.reg",
  classifier = file.path(fs_dir(), "average/lh.DKTatlas40.gcs"),
  output_file,
  subjects_dir = fs_subj_dir(),
  opts = NULL
)

Arguments

Examples

if(freesurfer::have_fs()){
# for freesurfer help see:
freesurfer::fs_help("mris_ca_label")
mris_ca_label(output_file = "test.lh.annot")

mris_ca_label(hemisphere = "rh", output_file = "test.rh.annot")
}

Description

If you have labels rather than a full annotation file, these can be combined with FreeSurfer's mris_label2annot.

Usage

mris_label2annot(
  labels,
  hemisphere = "rh",
  ctab,
  subject = "fsaverage5",
  subjects_dir = fs_subj_dir(),
  output_dir = subjects_dir,
  opts = NULL,
  verbose = TRUE
)

Arguments

Examples

if(freesurfer::have_fs()){
# for freesurfer help see:
freesurfer::fs_help("mris_label2annot")

subj_dir <- freesurfer::fs_subj_dir()
# Split up aparc annot into labels
mri_annotation2label(annot_name = "aparc")

# get annot for colour labels
annot <- freesurfer::read_annotation(
              file.path(subj_dir, 
                        "fsaverage5/label/rh.aparc.annot"))

labels <- list.files(
   file.path(subj_dir, "fsaverage5/label/aparc"), 
    full.names = TRUE)

# Combine them again into annot.
mris_label2annot(labels, annot$colortable)

}

Description

Read in a FreeSurfer colortab file.

Usage

read_ctab(path)

Arguments

Value

a data.frame with index, label name and RGBA colours

Description

Change old atlas setup to new

Usage

restruct_old_3datlas(atlas_data)

Arguments

Description

Turn smooth file to ascii

Usage

smooth2srf(input_file, output_file, verbose)

Arguments

Description

This function goes through all specified subject, per hemisphere, surface, curvature and no fix curvature specified and turns them into ascii files.

Usage

subject_2_ascii(
  subject = "fsaverage5",
  hemisphere = c("rh", "lh"),
  surfaces = fs_surfaces(),
  curvatures = fs_curvatures(),
  nofix_curv = fs_nofixcurv(),
  subjects_dir = freesurfer::fs_subj_dir(),
  output_dir = subjects_dir,
  verbose = TRUE
)

Arguments

Value

no return. Writes files.

Examples

## Not run: 
subject_2_ascii()
subject_2_ascii("fsaverage")
subject_2_ascii("bert")

## End(Not run)

Description

Function to convert Freesurfer surface file into .ply

Usage

surf2ply(input_file, output_file = paste(input_file, ".ply"), verbose = TRUE)

Arguments

Value

ply text

Description

Function to split up a surface ply into several ply's based on a freesurfer label file.

Usage

surfsplit(
  srf_ply,
  label_path,
  prefix = "test",
  output_dir = dirname(label_path),
  verbose = TRUE
)

Arguments

Details

Script adapted to R and ggseg based on scripts from Anderson M. Winkler: http://brainder.org

Value

list of ply meshes. Will also write ply meshes to files.

Description

write a colortab to file, will be in a format that is accessible by FreeSurfer.

Usage

write_ctab(x, path)

Arguments

Value

returns nothing, writes file