VertexWiseR v1.5.4

FIXES

• The label mapping for the allaseg surface had the wrong labels in the cluster summaries and plot_surf3d() when the 1.5.3 atlas was introduced. The maps downloadable on github were updated and plot_surf3d() fixed to show the right parcellation name when hovering the cursor. Other regions remain unaffected. To get the most up-to-date maps for SubCortexMesh objects if downloaded already, users need to remove it: extdatadir=system.file(‘extdata/scm_database/’, package=‘VertexWiseR’).
• Fix for TFCE models with the “inverse=TRUE” option. Permutated models were not indexing systematically the right contrast variable when producing a random t-map at each permutation. This did not apply for RFT or the mixed models.

VertexWiseR v1.5.3

NEW FEATURES

• Since SubCortexMesh v1.1.0, some subcortical ROIs (in fsaverage space) also have atlas sub-parcellations. They can be selected as descriptive region labels in the outputs of RFT and TFCE models, as well as in the hovering information in plotsurf_3d() (atlas=1 for default base ROI, atlas=2 for the anatomical atlas). This works with the thalamus, hippocampus, amygdala, ventral DC, pallidum, cerebellum and brain-stem. The “Example analyses with VertexWiseR - Example 3” vignette shows an example of it.

To get the most up-to-date maps for SubCortexMesh objects, users need to remove: extdatadir=system.file(‘extdata/scm_database/’, package=‘VertexWiseR’). VertexWiseR will then prompt users to download them again from Github whenever they try to analyse SubCortexMesh’s subcortical regions. Example 3 was also fixed accordingly.

FIXES

• The installable version of Miniconda in VWRfirstrun() has been updated to fix compatibility issue with BrainStat’s dependencies. It now installs Miniconda binaries for Python 3.10.

VertexWiseR v1.5.2

NEW FEATURES

• New conversion functions fslr_to_fs5() and fs5_to_fslr() to remap surface data in the fslr32k template to data in the fsaverage5 template, and vice versa

FIXES

• SURFvextract() now also detects the FreeSurfer license path set in the FS_LICENSE environment variable instead of only checking a default path.
• SCMvextract() was mishandling subject surface file detection when a subject’s ID was contained in another (e.g., processing for “sub-10” would include “sub-100”’s surfaces). A safeguard is now added to prevent it.

VertexWiseR v1.5.1

NEW FEATURES

• VertexWiseR can now analyse subcortical surfaces from SubCortexMesh in both the fsaverage ASeg template and fslfirst template as provided by the python toolbox. Template data required can be downloaded separately according to which template is used. ASEGvextract() is now SCMvextract() as it covers more than FreeSurfer’s segmentations.

FIXES

• There was a mismatch in VertexWiseR 1.5.0’s template data and SubCortexMesh’s template data for the allaseg surface, which has been reordered since to standardize across FreeSurfer and FSL FIRST-based SCM outputs. This is now fixed.
• plot_overlay_surf’s custom limits did not work properly with the NULL option breaking the plotter. This is now fixed

VertexWiseR v1.5.0

NEW FEATURES

• VertexWiseR can now analyse surface-based metrics for FreeSurfer’s ASeg subcortical regions, converted to surface meshes via the python module SubCortexMesh, and extracted with the new R function ASEGvextract(). A new example tutorial was created as a demonstration: “Example analyses with VertexWiseR - Example 3”.
• plot_overlay_surf() now works with HippUnfold’s hippocampal data (CIT168 template) and SubCortexMesh subcortical data.
• plot_surf(), and plot_overlay_surf() and plot_surf3d() now have a smooth_mesh argument to make the surface appear smoother in the plot.

FIXES

• In VWRfirstrun(), the check and message prompt for the neurosynth database now prints the path in which it is meant to be stored, instead of an empty “()”.
• The model_check() internal function inside the modelling functions could fail if ‘model’ or ‘contrast’ were given as a one-column data.frame instead of a simple vector, as the inherits() checks would not detect numeric or character classes.
• plot_surf() (with show.plot.window=TRUE) will no longer plot on top of the previous plot in the RStudio “Plots” tab when running the function multiple times, and will reset it first.
• plot_overlay_surf() now accepts a custom limits_2 instead of failing.
• Clearer error message for plot_surf() when provided with surf_data that only contains NA values, and if surf_data has multiple rows, empty rows are simply not plotted.
• Clearer error management and messaging when the title argument is wrongly inputted in plot_surf() (e.g. if there are more titles than there are surface rows).

VertexWiseR v1.4.5

NEW FEATURES

• The formula option now also works with (non-data.frame) single-vector data and will automatically name the single variable after whatever IV name was written inside the formula.

FIXES

• Model checks for single-column/vector factor variables failed and prevented models from running. The script has been corrected.

VertexWiseR v1.4.4

NEW FEATURES

• RFT_vertex_analysis(), TFCE_vertex_analysis() and TFCE_vertex_analysis_mixed() now have an “inverse” boolean argument allowing to treat every vertex of the surface data as the predictor, and the “contrast” variable as the dependent variable, keeping the other covariates in place. Note that this increases the modelling time substantially.
• plot_surf3d now has the option to disable the background grid and to save the image with a transparent background.

FIXES

• In special circumstances, possibly due to the conversion of python objects in recent reticulate versions, the cluster-wise p.value/cluster IDs ended up being a list object instead of numeric, which caused various errors when attempting to report cluster-wise results. This is now accounted for.
• plot_surf no longer fails if given as surf_data a 1-row matrix or data.frame object instead of a simple numeric vector for single subject data.
• plot_surf3d is now able to render all colour palettes provided with RColorBrewer.
• TFCE_vertex_analysis_mixed was cleaning up the temp.dir which affected functions that store files there in the same session, such as the default plot_surf(). It is now let for R to clean it up itself after the R session ends.
• TFCE permutation optimisation: more data is preloaded and internal python calls regulated to use strictly one thread per parallel jobs. The phenomenon of computing time increasing with nthreads for certain CPU systems (as in the paper’s Table 6) should no longer manifest itself, as it seems parallel jobs would use more threads than required in their python processes.

VertexWiseR v1.4.3

FIXES

• Dependency fixes for the different python installation options in VWRfirstrun(). netneurotools version 0.2.5 is now a dependency as the subsequent versions conflict with brainstat’s use of netneurotools.civet (notably, to fetch fsaverage templates when running VWRfirstrun()). VWRfirstrun() will automatically install 0.2.5, and current users may do it themselves via reticulate::py_install(“netneurotools==0.2.5”).
• Brainstat was installed automatically in the available reticulate miniconda installation, but this should not happen if python alone was installed as the preferred environment beforehand, this is now fixed.
• reticulate::py_discover_config() no longer detects r-miniconda if installed before VertexWiseR. VWRfirsturn() now searches for it, based on reticulate::miniconda_path(). It will not be possible to automatically detect standalone python installation made with reticulate::install_python() independently from VWRfirstrun(). An alternative is to predefine your python path yourself.

VertexWiseR v1.4.2

FIXES

• decode_surf_data() does not work with nilearn package version > 0.12.0 (as currently imported by NiMARE, used for the meta-analytic decoding). By default, Brainstat’s installation collected nilearn v0.11.1 already (in the classic Miniconda or Python installations), but this does not happen when the default UV Python virtual environment is installed with VWRfirstrun(). Now, nilearn v0.11.1 is also installed systematically with the virtual environment. Current virtual environment users encountering the error can install the right version themselves (reticulate::py_require(“nilearn”, action = “remove”); reticulate::py_install(“nilearn==0.11.1”)), or install a new fresh python virtual environment following this tutorial.

VertexWiseR v1.4.1

NEW FEATURES

• The ciftiTools package and connectome workbench are no longer needed to extract FSLR32K surface when using FSLRvextract() or DTSERIESvextract(). The surface extraction tutorial was updated accordingly.

FIXES

• If Brainstat was not installed, CAT12vextract() failed as it assumed the nibabel package (a dependency of Brainstat) to be installed and only checked for Python. Brainstat is now required for the function to run, to simplify dependency management. It will also be required for FSLRvextract() and DTSERIESvextract().

VertexWiseR v1.4.0

NEW FEATURES

• New function getting_started(): allows users to run through the package’s tutorials and to download all the demo data at once. Article vignettes now propose downloading the demo data in bulk rather than running a downloading line every step of the way.
• New function plot_overlay_surf(): allows users to plot two surfaces on top of each other, with boundaries, varying opacity, color maps and value ranges (for cortical surfaces). A new tutorial/vignette called Overlaying plots and transparent thresholding was also created to showcase it.
• New function DTSERIESvextract(): allows users to extract vertex-wise surface-based CIFTI dense time-series data from an individual dtseries .nii file from HCP, fMRIprep or XCP-D preprocessed directories.
• New options for plot_surf: alpha setting to reduce transparency of non-NaN vertices, and option to not plot the NaN vertices.

FIXES

• When VWRfirstrun() was set to promptless, it checked the wrong directory path for brainstat’s fslr32k data and considered it missing.
• Successful check message stopped showing except when promptless==FALSE, which should be the opposite.
• Fix to ensure the right numpy version gets installed when installing miniconda, in case brainstat does not upon installation.
• Fix to still run UV if the RETICULATE_PYTHON variable was explicitly set to NA (a suggestion given in our article for users whose systems already have , a python installed but want to dedicate VWR to a virtual environment).

VertexWiseR v1.3.2

FIXES

• Function argument: FSLRvextract()’s argument “dscaler” changed to “dscalar”

VertexWiseR v1.3.1

NEW FEATURES

• Slight modification of the cluster building process, which speeds up TFCE analyses.
• plot_surf() now includes the transparent_bg argument which uses a boolean to make the plot’s background transparent (default is FALSE, white background).
• fslr32k can now be used in surf_to_vol() and decode_surf_data()
• BrainStat’s Yeo parcellation data are no longer required by VWRfirstrun(). They were fetched by default in BrainStat’s SLM script, when VertexWiseR used it with hippocampal surfaces.
• Slightly clearer message in VWRfirstrun()’s check of the BrainStat data path: the actual user’s home path is printed instead of “$HOME_DIR/”.

FIXES

• Documentation mistake: surf_to_vol() does NOT work with fsaverage6.

VertexWiseR v1.3.0

NEW FEATURES

• TFCE computation is now optimized for speed: previously, the parallel steps in the permutation loop were building the linear model again every time; now the model will be saved as a file in a temporary directory (tempdir(), which will automatically be cleaned up), and loaded within the loops instead of rebuilt.

FIXES

• TFCE_vertex_analysis_mixed(): The random variable was not being processed identically in BrainStat across the permuted and unpermuted models, because of a setting factorizing the variable in only one case. Now random variables are factorized in both. This error affected the coefficients and t-stat estimations, and by extension the results of Example 2, which no longer shows negative clusters and now displays a smaller positive cluster for TFCE. This makes the outcome more consistent with the RFT results (TFCE being more conservative instead of the opposite). We apologise for overlooking this inconsistency in the code. Please refer to Example 2 as presented in its vignette/website page for the most up-to-date and accurate results.

VertexWiseR v1.2.1

NEW FEATURES

• Reticulate’s last update allows users to install ephemeral Python environments with UV instead of requiring a stable Python/Miniconda installation. If users create their own with py_require() before running VertexWiseR, such environment will be selected automatically. If no Python environment is found, VertexWiseR now gives the choice to either install an ephemeral environment with UV, or to install Miniconda or Python via the classic ways.

FIXES

• SURFvextract() now gives a proper error message if subjects’ surface measure files could not be found. It also will get rid of the sublist.txt which was outputted automatically if subj_ID was set to FALSE.
• Fix for messages that were silenced by mistake during Miniconda’s installations process.
• Fix for the script using pip/pip3 to install properly vtk (9.3.1) when choosing the classic Python installation.

VertexWiseR v1.2.0

NEW FEATURES

• Update for RFT_vertex_analysis: now outputs also the unthresholded tstat map; Rdoc fixed accordingly (setting p=1 as previously advised caused errors, it doesn’t simply output the unthresholded tstat map)
• SURFvextract() now has the optional argument fshomepath. This ensures FreeSurfer’s environment is accessed by R and set up again if the function is used from RStudio and the FREESURFER_HOME variable has been defined before running Rstudio. This is needed because RStudio does not inherit the system variables set before opening it from a terminal.
• If the surf_data argument (in modelling or smoothing functions) is a list object with the subject list along with the surface matrix (as outputted by extraction functions with subj_ID=TRUE), the code automatically detects the matrix in that list, named “surf_obj”, instead of forcing users to specify the matrix.
• Modelling functions now accept a string with the path to the .rds file outputted by extraction functions, instead of only the matrix itself as the surf_data argument
• New function CAT12vextract() which allows surface data resampled to 32k meshes in CAT12 to be extracted and converted to a surface .rds object. This works with any measure applicable for the 32k resampled meshes (‘thickness’, ‘depth’, ‘fractaldimension’, ‘gyrification’, and ‘toroGI20mm’).
• New vignette/article gives advice on how to solve various Python-related issues
• Numpy’s version check is no longer present as pip replaces it upon BrainStat’s installation with the compatible version

FIXES

• Python package ‘vtk’ causes issues in latest 9.4.0 versions. The correct 9.3.1 version is now installed when installing Miniconda or reticulate’s Python environment via VWRfirstrun().
• The cmap argument in plot_surf() is now converted to class color if not in that class by default
• Surface extracters fix: Working directory is restored before saving the RDS instead of on exit for HIPvextract() and FSLRvextract(). This ensures the filename is not interpreted as relative to the sdirpath (subjects directory).
• Fixed a parameter that was skipping VWR_check if smooth_surf() or TFCE_threshold() were nested to avoid VWR_check’s repetition. This caused issues for non-interactive sessions/other nesting situations. Now, instead: For TFCE_threshold(), users calling it may manually set the argument VWR_check=FALSE if they want it to be skipped. For smooth_surf(), now VWR_check will be skipped if the parent function is identified as “model_check” as it will mean the smooth function is run from a function that already have a VWR_check (RFT_vertex_analysis, TFCE_vertex_analysis and TFCE_vertex_analysis_mixed functions).
• Fix for non-miniconda Python installation: numpy, vtk and brainstat were installed via system(’‘) but the optional use of pip or pip3 did not work properly in Windows due to a bash syntax error. The pip3 installation is now only triggered if an error occurs with the first system(’pip …’) call. Furthermore, reticulate’s environment is loaded immediately after the Python installation to make sure the pip function can be used subsequently to install the required packages. Other minor improvements in the messages printed during the VWRfirstrun() installation process.
• VWRfirstrun(): One message was still showing even if promptless=TRUE, this is now fixed
• FSLRvextract(): Default filename fixed (simply ‘fslr32k.rds’)
• To avoid instability, the reticulate Miniconda installation is now set at v.24.9.2 instead of the latest

VertexWiseR v1.1.0

NEW FEATURES

• New plotsurf_3d() function: allows surface data to be plotted in a 3D viewer via the plotly interface
• The extraction tutorial now also gives FreeSurfer preprocessed data for demonstration
• plot_surf() now accepts atlas ROI values from atlases supported by atlas_to_surf()
• atlas_to_surf() now works with hippocampal surface data
• smooth_surf() allows to enter a path to a surface .rds object instead of inputting the object itself

FIXES

• For miniconda/python libraries installations via VWRfirstrun(), pip3 added as an alternative used if pip install fails
• Fixed Surface extraction tutorial (download.file had the wrong url/method, untar added as alternative as unzip had possible failures for the demo surface data)
• Fixes for MacOS (better custom path management, SURFvextract() compatibility issue fixed)