Configuration

Configuring Neuropythy

Neuropythy is most useful when it knows where to find your FreeSurfer subject data or where you want it to store datasets or Human Connectome Project files. These configuration items can be set in a number of ways:

• On startup, neuropythy looks for a file ~/.npythyrc (though this file name may be changed by setting the NPYTHYRC environment variable). The contents of this file should be a JSON dictionary with configurable variables (such as "freesurfer_subject_paths") as the keys. An example configuration file:

  {"freesurfer_subject_paths": "/Volumes/server/Freesurfer_subjects",
   "data_cache_root":          "~/Temp/npythy_cache",
   "hcp_subject_paths":        "/Volumes/server/Projects/HCP/subjects",
   "hcp_auto_download":        true,
   "hcp_credentials":          "~/.hcp-passwd"}

• Each config variable in the NPYTHYRC file may be overrided using an associated environment variable. Usually the environment variable names are either the config variables in uppercase or NPYTHY_ + the variable in uppercase: NPYTHY_DATA_CACHE_ROOT, HCP_CREDENTIALS, HCP_AUTO_DOWNLOAD. The SUBJECTS_DIR environment is used for the FreeSurfer subject paths, and the HCP_SUBJECTS_DIR variable is used for the HCP subject paths (both may be :-separated lists of directories).
• The config items may be retrieved and set directly using neuropythy.config. Values that are set in this way override the NPYTHYRC file and all environment variables. For example:

  import neuropythy as ny
  ny.config['data_cache_root']
  #=> '/Users/nben/Temp/npythy_cache'
  ny.config['data_cache_root'] = '~/Documents/npythy_data'
  ny.config['data_cache_root']
  #=> '/Users/nben/Documents/npythy_data'

Understood Configuration Variables

The following configuration variables are understood by neruopythy. The "name" listed below is the name that neuropythy uses for the variable (in the ~/.npythyrc file and neuropythy.config) while the "environment name" is the name of the environment variable that can be used to set the variable.

Name	Environment Name	Default Value	Description
"data_cache_root"	NPYTHY_DATA_CACHE_ROOT	None	The path where neuropythy should look for, download, and store datasets such as the Benson and Winawer (2018) dataset. If this is None (the default), then a temporary directory is created when a dataset must be downloaded; this temporary directory is automatically deleted when python exits.
"benson_winawer_2018_path"	NPYTHY_BENSON_WINAWER_2018_PATH	None	The path where the database from Benson and Winawer (2018) should be searched for and, if downloaded, stored. If this is None, then the path is the subdirectory benson_winawer_2018 of the path in the data_cache_root configuration variable.
"freesurfer_subject_paths"	SUBJECTS_DIR	None	The directory where neuropythy should look for FreeSurfer subjects. May be a colon-separated list of directories.
"hcp_subjects_path"	HCP_SUBJECTS_PATH	None	The directory where neuropythy should look for HCP subjects, whose subject directories must be their ID numbers. May be a colon-separated list of directories.
"hcp_auto_download"	HCP_AUTO_DOWNLOAD	False	If you wish to enable auto-downloading of HCP subjects, set this to be true; you will also need to at least give neuropythy your S3 credentials for the HCP.
"hcp_credentials"	HCP_CREDENTIALS	None	May be one of several things: (1) a list of [hcp_key, hcp_secret] strings; (2) a string "<key>:<secret>"; or (3) the name of a file that contains a string (like in (2)).
"hcp_auto_path"	HCP_AUTO_PATH	None	May specify the directory into which auto-downloaded subjects should be placed; if this is not specified (None), then uses the "hcp_subjects_path"--the first if there are many paths.
"hcp_auto_database"	HCP_AUTO_DATABASE	None	Generally not necessary; if you wish to specify an HCP database aside from hcp-openaccess, you can set this to specify it.
"hcp_auto_release"	HCP_AUTO_RELEASE	None	Generally not necessary; if you wish to specify an HCP subject release set other than "HCP_1200", you can set it here.

A list of all understood config variables for the version of the library you are currently using can be obtained also:

import neuropythy as ny
sorted(ny.config.keys())

The neuropythy.config Structure

Neuropythy exposes the configuration variables listed above in a data structure, neuropythy.config. This structure behaves roughly like a dict object (though it is in fact a static class). When you set the value of a configuration variable in the config object, some preprocessing is done and errors are raised if the value is known to be invalid. Values set in this way override the npythyrc file and environment variables.

import neuropythy as ny
# See my FreeSurfer directory:
ny.config['freesurfer_subject_paths']
#=> ['/Volumes/server/Freesurfer_subjects']
ny.config['freesurfer_subject_paths'] = '/Volumes/server/Freesurfer_subjects:~/data/subjects'
ny.config['freesurfer_subject_paths']
#=> ['/Volumes/server/Freesurfer_subjects', '/Users/nben/data/subjects']