move_to_submask and move_from_submaskread_cifti all brain structures, instead of left and right cortex onlyMinor fixes and improvements.
ciftiTools now has a couple functions which make working with parcellations easier. (A parcellation is a single-column dlabel CIFTI or "xifti" object. Each label level, or "Key", represents a "parcel." Each location belongs to exactly one parcel. Parcels are usually contiguous regions--but not necessarily. ciftiTools includes a few of the most commonly-used parcellations. These can be loaded with load_parc. Any other parcellation CIFTI file can be read in with read_cifti.)
apply_parc: Apply a parcellation "xifti" to a data "xifti". Can be used to compute the mean of each column, e.g. for FC calculation, but also supports applying any other function parcel-wise.parc_vals_to_xifti: Create a "xifti" from a parcellation and a numeric matrix of values corresponding to each parcel.Other new functions:
remap_cifti: an extension of resampling. Beware, we might revamp this function in the future.surf_area: computes the surface area attributable to each vertex or face of a "surf" object.Changes to existing functions:
convert_xifti, convert_to_dlabel: arguments related to levels & labels have been renamed to match factor more closely.separate_cifti and write_xifti2: now require users to provide either the write_dir argument, or file names for each desired output file. This gives users more flexibility to control which files are written.view_xifti qualitative color legend: add black outline.view_xifti, view_volume: print out indices of the selected subcortical slices.unmask_subcortex: now expects xifti input. If necessary, use the internal function ciftiTools:::unvec_vol to unmask a numeric matrix directly.Bug fixes:
view_xifti: fix bug where legend image was still written if legend_fname=NULL.13.1 also includes misc. documentation and warning improvements.
New features
dlabel CIFTI data. Fixed problems if multiple columns or with subcortical data.even_vert_samp.apply_parc.set_names_xifti.NA_color argument to view_xifti_surface.shadows argument to view_xifti_surface.mask_surf takes in a "surf" object now.Changes to default behaviors
crop to view_xifti_volume; the default is TRUE. Previously the subcortical images were cropped to the anatomical image; now the default is to crop them to the data.orientation_labels in view_xifti_volume to TRUE.NA and NaN values in "xifti" objects with label data. Leave these values alone rather than making them into factor levels.smooth_cifti rather than returning their file paths.New features
BayesfMRI.xii + mat (and other operations)scientific argument to view_xifti. By default, scientific notation is determined automatically (as before).Documentation
New features
Behind-the-scenes improvements
"xifti" metadataremove_xifti can delete individual subcortical structures nowscale_xifti which works like scaleview_comp, and the argument together to view_xifti_surface and view_xifti_volumeview_xifti_surface and view_xifti_volumetrans_units to subcortex metadatawrite_cifti_components as write_xifti2 and export"xifti" objectsvox_locations and edit_mask_surfview_xifti_volume! Added tests for it.plot will now show both the cortex and subcortex, if both are present. The plots will share the color mode, color palette, and zlim.summary/print for "xifti" objectsread_xifti_surfaceread_cifti_convert where surfaces are not includedciftiTools.files back to a function, ciftiTools.files(), because the latter doesn't actually workrgl.useNULL() in view_xifti_surfaceunmask_vol to unmask_subcortexciftiTools.files replaces demo_files(). This variable is created in the user's environment upon library(ciftiTools) with lazy loadingciftiTools.files will only contain the inflated surface. To import the other two surfaces, use load_surf(). Removed the "surf" option from ciftiTools.setOption.add_surf will automatically resample the surfaces if neededread_surf has the argument resamp_res to enable resampling upon reading in the surface, similar to read_xiftinewdata_xifti will accept a length-one vector, to create a constant-valued "xifti"ciftiTools.data contains the surfaces and parcellations building blocks, and the HCP 32k medial wallciftiTools.setOption("surf", ...) The default surface is still very inflated, but different.load_parc.apply_xiftimove_to_mwall and move_from_mwallidx argument to read_xifti and related functions... argument to transform_xiftiwrite_surf, an alias for write_surf_giftifix_xifti, which ensures xifti$data entries are matricesview_xifti_surfacemake_surf is now an alias for read_surf, instead of the other way aroundconvert_xifti accepts CIFTI files tooas.matrix S3 methodview_xifti_volumeNone
concat_xifti as merge_xiftigifti_to_surf as read_surfcombine_xifticonvert_xifti and make the individual conversion functions (e.g. convert_to_dlabel) internalsmooth_gifti for metric GIFTI smoothingdim for xifti objectslegend_alllevels arg to view_xifti_surfaceview_xifti_surfacewrite_xifti will infer the intent/extension if not included in output file nameNone
None
run_ciftiTools_tests.R to .RbuildignoreciftiTools.setOption call, and never afterwardresample_cifti and read_ciftiview_xifti_surface!transform_xifti improvementsremove_xiftirotate_surf, select_xifti and concat_xiftisurface_sigma with surf_FWHM and likewise for volumeview_xiftifields and rgl from Suggests to Imports.wb_path argument. (Use ciftiTools.setOption("wb_path", "path/to/workbench"))transform_xifti to apply unary functionsexp(cii) / 5 + cii2newdata_xifti to substitute datasmooth_cifti
xifti directlycifti_target_fname is optional to smooth_cifti; will be auto-generated if NULLciftiTools package if not provided to smooth_cifti when corresponding cortex data existsview_xifti_surface
surface class to surfas.xifti
run_ciftiTools_tests.R (and add to .Rbuildignore)ciftiTools.listOptions and ciftiTools_msggifti_to_surf an alias to make_surfview_xifti_surface when more than one idx is requested!
mode argument with interactive argumentidxview_xifti_surface
view_xifti_volume
papayar)mwall_values to relevant functions.
NA and NaNNULL to not infer the medial wall from the dataTransformationMatrixIJKtoXYZ in CIFTI filessform codes in NIFTI filesdlabel and dscalar)RNifti instead of oro.nifti*.dlabel.nii filescifti_fname in read_cifti optional (can read in just the surfaces)dlabel to dscalar (and add warning, because it's probably something you don't want to do)make_subcortinfo_cifti_raw into header_cifti and xml_ciftiremove_xifti, expect_equal_xifti and fix_gifti_mwallview_surf is now a wrapper to view_xifti_surface instead of being its own functionutils_color.ROY_BIG_BL have an extra value to fix legend range.view_xifti_surfaceas.xifti(surfL=surfR_gii) will cause an errorrgl and fields to Suggestsdlabel.nii filessmooth_ciftiresample_cifti_from_templateplot(xii) is called without any surface or subcortical dataview_xifti_surface improvements:
dlabel.nii file (intent 3007)view_xifti_volume improvements:
num.slices argument... for additional argumentsview_surface for "surface" objectssummary and plot methods for "surface" objectswritegii)view_xifti_surface defaultsview_xifti_volume without structural imageTRUE while others returned a list or data.frame of written file paths"xifti" from GIFTI and NIFTI files. Previously, if a mask was not provided then constant 0, NA, or NaN values were deemed out-of-mask. Now, ciftiTools uses ROI files to keep track of the out-of-mask values in read_cifti_separate and resample_cifti, and requires the masks to be explicitly provided in as.xiftimake_surface as make_surfis.surface as is.surfside argument as hemisphere argument (same choices: "left" or "right")readCIfTI and readcii for read_cifticiftiTools: https://www.nitrc.org/frs/download.php/8541/cifti-2_test_data-1.2.zipwrite_xifti_components as write_cifti_componentsmetric_resample and surface_resample (use resample_gifti directly)make_helper_spheres as write_spheres, and do not export itunmask as unmask_vol (to distinguish from unmask_cortex)data-raw from R package buildgifti > 0.7.5onAttach and .RbuildignoreIt will be located here: https://htmlpreview.github.io/?https://github.com/mandymejia/ciftiTools/blob/master/vignettes/ciftiTools_vignette.html once we push to master. Until then, replace "master" with "1.4"
"xifti" object: can be made from CIFTI file, GIFTI surfaces, or new data
"xifti" from data: as.xifti(...)"xifti" from a CIFTI file: read_cifti(cifti_fname)"xifti" from a GIFTI surface: as.xifti(surfL=make_surf(surfL_fname))read_cifti_flat now uses XML metadata directly (but still obtains XML via Connectome Workbench)
.dtseries.niiwrite_surf_gifti and write_metric_gifti as wrappers to the new gifti::writegii
damondpham/gifti but this will hopefully be merged to main repo soonwrite_subcort_nifti to write out subcortical components from "xifti" to a NIFTI filewrite_cifti can also write the surfaces attached to the "xifti""xifti" objects can contain surfaces without any data.
view_xifti_surface can view a surface without any data: plot(as.xifti(surfL=left_surf))resample_surf to resample a surface objectread_cifti_flat and read_cifti_separate"cifti" object. unflattening functions.write_ciftiMost of the functions were renamed. In general, cifti_[action] is now [action]_cifti. So to open and visualize a CIFTI file, one would use read_cifti() followed by view_cifti(). To save a resampled version of a CIFTI file, one would use resample_cifti().
Arguments were also renamed for consistency across functions:
_fname instead of beginning with fname_.surf_L or cortex_left, are now cortexL (likewise for right).gifti_left or surf_left, are now surfL (likewise for right).sphere_L, is now sphereL (likewise for right).sphere_orig_L is now sphereL_original (likewise for right; likewise for other original files).sphere_target_L is now sphereL_target (likewise for right; likewise for other target files).target_res or resample, is now resamp_res.wb_cmd is now wb_path.outdir is now write_dir.There are a few new functions:
read_cifti_flat() reads the cortical and surface data together as a single matrix.
read_cifti().-cifti-convert -to-gifti-ext.flatten_cifti() converts a "cifti" object to this same matrix.read_cifti() with flat==TRUE will call read_cifti_flat().make_xifti() creates a "cifti" object from its components.
view_cifti() plots the CIFTI data.
view_cifti_surface() unless no cortical data exists, in which case it will try view_cifti_volume().view_cifti_surface() was rewritten using the rgl package directly.And, a few new arguments:
sep_keep and resamp_keep indicate whether separated or resampled files should be deleted after reading in the CIFTI data (read_cifti()) or writing the resampled CIFTI file (resample_cifti()). Their default values are FALSE. in which case these files are written to a temporary directory (regardless of write_dir).sep_fnames and resamp_fnames can be used to set the file names for the respective files made by read_cifti and resample_cifti.
cifti_component_suffix.Other updates:
separate_cifti() and resample_cifti() if verbose==TRUE.ciftiTools.setOption('wb_path', 'path/to/workbench').
"cifti" object does not support ROIs, so they are ultimately not loaded.
make_xifti() (haven't tested this yet).EPS. Set it with ciftiTools.setOption("EPS", 1e-8). This is used by view_cifti() and flatten_cifti() to detect constant zero brainordinates.readCIfTI() and readcii() for read_cifti().plot() method for "cifti" objects.overwrite and make_helper_files arguments were removed. All functions will overwrite existing files, and this cannot be changed."cifti" object will only support one surface geometry model at a time.
view_cifti() can accept a surface GIFTI file directly.left and right only (excludes the subcortical data).oro.nifti::readNIfTI() with RNifti::readNifti() for faster reading of subcortical data."cifti_surface", "cifti_subcortical", "cifti_cortex", "cifti_volume" and "cifti_label".read_separate_cifti() with read_cifti(), which calls separate_cifti(), resample_cifti_components() (optionally), and make_xifti() in that order.resample_cifti(). The new version calls separate_cifti(), resample_cifti_components(), and then uses a template to create the new CIFTI file. (The first half is nearly identical to read_separate_cifti().)rox_args_docs.R. Use @inheritParams to reference these descriptions. This should make maintaining them across the entire package easier.separate_cifti_wrapper() and resample_cifti_wrapper() to avoid duplicate code across read_cifti() and resample_cifti(). These should not be used by end-users, so they are not exported.utils.R for general functions and utils_cifti.R for CIFTI-specific functions.