Getting Started and Setting Up freesurfer in R

Setting Up Your R Environment for freesurfer

To use the freesurfer R package, you’ll first need a working installation of Freesurfer itself. You can download and install Freesurfer from its official website.

The freesurfer R package relies on successfully detecting your Freesurfer installation. The core of this detection process is handled by a series of functions get_fs_home(), which attempts to locate your FREESURFER_HOME directory.

The detection process for FREESURFER_HOME follows a specific order:

1. It looks for the R option getOption("freesurfer.home").
   
2. If that is not found, freesurfer checks your system’s environment variables for FREESURFER_HOME.
   
3. As a last resort, it tries common default installation paths, such as:
   • /usr/local/freesurfer
     
   • /Applications/freesurfer
     
   • /usr/freesurfer
   • /usr/bin/freesurfer

As a first step, use the fs_sitrep() function to get detailed information about the setup between R and Freesurfer on your system.

library(freesurfer)

fs_sitrep()

This function provides useful information about which issues may be present regarding the integration of R and Freesurfer on your system. Ideally all checks should pass with a green tick. Any red ticks or warnings should be addressed to ensure smooth use of this package. As you can see, there are several things to make sure are in order. As a minimun, you should have the freesurfer.home option or FREESURFER_HOME variable set. If you see a red tick for freesurfer.home or FREESURFER_HOME, it means that the package cannot find your Freesurfer installation. However, as long as this is set and has a green tick, the remaining options are likely set to sensible defaults.

options(
    freesurfer.home = "/path/to/freesurfer",
    freesurfer.subj_dir = "/path/to/freesurfer/subjects",
    freesurfer.license = "/path/to/freesurfer/.license",
    freesurfer.output_type = "hdr",
    freesurfer.sh = "/path/to/freesurfer/FreeSurferEnv.sh",
    freesurfer.mni_dir = "/Applications/freesurfer/mni/Library/Perl/Updates/5.12.3",
    freesurfer.verbose = TRUE
)

# or using environment variables
Sys.setenv(
    FREESURFER_HOME = "/path/to/freesurfer",
    FREESURFER_SUBJ_DIR = "/path/to/freesurfer/subjects",
    FS_LICENSE = "/path/to/freesurfer/.license",
    FSF_OUTPUT_FORMAT = "hdr",
    FREESURFER_SH = "/path/to/freesurfer/FreeSurferEnv.sh",
    MNI_DIR = "/Applications/freesurfer/mni/Library/Perl/Updates/5.12.3",
    FREESURFER_VERBOSE = TRUE
)

have_fs()

if (have_fs()) {
  print("Freesurfer is installed! Huzzah!")
}

Understanding Freesurfer Output Formats

Freesurfer commands often default to a specific output format for image files, which is controlled by the option freesurfer.output_type or FSF_OUTPUT_FORMAT environment variable. You can check this setting using get_fs_output(). If it’s not explicitly set, it typically defaults to nii.gz. You can also retrieve the corresponding file extension with fs_imgext().

get_fs_output()
fs_imgext()

# Generate a shell command to set up FreeSurfer with the default `bin` directory
get_fs(bin_app = "bin")

# Generate a shell command to include MNI environment setup
# This is important if you plan to use FreeSurfer's MNI tools.
get_fs(bin_app = "mni/bin")

Organizing Your Freesurfer Analyses

During Freesurfer installation, several environment variables are set in addition to FREESURFER_HOME. One of these is SUBJECTS_DIR, which points to a directory containing the analysis output for all your subjects.

The fs_subj_dir function will return the path to this Freesurfer subjects directory if it’s already set. If not, it defaults to file.path(fs_dir(), "subjects").

fs_subj_dir()

You also have the flexibility to explicitly set the freesurfer.subj_dir option or SUBJECTS_DIR environment variable.

This default SUBJECTS_DIR setup in Freesurfer allows you to simply specify a subject identifier when running analyses, rather than needing to provide a specific file path or multiple intermediate files.

However, this default setup might not be ideal if you prefer to structure your data differently. For example, if you have data from multiple studies, you might want to organize them into different folders located in various places.

Some Freesurfer functions rely on the SUBJECTS_DIR variable to run. These functions typically take the subject name as their primary argument, rather than a file path, which is a more common approach in other tools. To offer maximum flexibility, freesurfer allows most functions to specify a file or a different directory, rather than solely relying on the SUBJECTS_DIR and subject name. Let’s look at an example: the asegstats2table Freesurfer function.

Freesurfer performs segmentations of anatomical images into distinct structures, and it provides associated statistics for each region, such as volume and mean intensity. The asegstats2table function transforms these anatomical segmentation statistics from images into a structured table. By default, asegstats2table expects you to pass in a subject name rather than a direct file path. However, the freesurfer asegstats2table function in R allows you to specify either the subject name or an alternative file name.

When you specify a file name, the function temporarily sets SUBJECTS_DIR to a temporary directory, copies your file there, executes the Freesurfer command, and then resets the SUBJECTS_DIR variable to its original state. This provides a much more flexible workflow, allowing you to manage your data structure without overriding the default SUBJECTS_DIR. This means you can have separate folders for subjects and easily read in data by simply switching the subj_dir argument in the R function. The lookup order for using a subject directory is:

1. function argument
   
2. options(freesurfer.subj_dir = "/path/to/freesurfer/subjects")
   
3. System variable (Sys.getenv("FREESURFER_SUBJ_DIR"))
4. file.path(fs_dir(), "subjects")
   • Which may utilise educated guesses based on common Freesurfer installation paths.