Changes in version 19.0 - apply_parc: change default FUN from mean to colMeans - new Connectome Workbench paths - write_cifti: delete intermediate files once no longer used Changes in version 18.0 - fix HCP_32k_mwall_template - fix: set pixdim and pixunits when writing NIFTIs. - bug fix in resample_gifti when resamp_res and original_res are NULL - update NIFTI --> CIFTI conversion info - update README w/ Limbic A and B in Yeo 17 info - updates to vignette - add message to load_surf if hemisphere not provided - add replace_NA_with_label - add qform <-> transformation matrix conversions for reference Changes in version 17.4 - Set read/write default for brainstructures to "existing" (rather than all or just cortex). - impute_xifti: Add this function which imputes values based on nearby locations. - newdata_xifti and as.matrix: Add subcortex_by_bs argument. - make_xifti: Allow character input for intent. - convert_xifti: Keep old names and labels if present. - Update workbench path for Mac - Convert unacceptable subcortex brain structures to "Other" - Fixes to match_exactly. - Clean up package and documentation. Changes in version 16.1 - move_to_submask and move_from_submask - add support for writing older xiftis w/o "Other" level in sub labels - fix subcortex bugs Changes in version 15.0 - Make default of read_cifti all brain structures, instead of left and right cortex only - add "Other" to subcortex levels Changes in version 14.0 Minor fixes and improvements. Changes in version 13.2 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. Changes in version 12.0 New features - Proper writing out of dlabel CIFTI data. Fixed problems if multiple columns or with subcortical data. - Add even_vert_samp. - Add apply_parc. - Add set_names_xifti. - Add NA_color argument to view_xifti_surface. - Add shadows argument to view_xifti_surface. - mask_surf takes in a "surf" object now. - Misc. documentation and warning improvements. Changes in version 11.0 Changes to default behaviors - Add 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. - Change default of orientation_labels in view_xifti_volume to TRUE. - Allow NA and NaN values in "xifti" objects with label data. Leave these values alone rather than making them into factor levels. - Add warning if surface data are being upsampled - Delete helper file surfaces written by smooth_cifti rather than returning their file paths. New features - Add adaptive resampling for surface data. The default remains barycentric. - Add surface manipulation functions from BayesfMRI. - Allow xii + mat (and other operations) - Add scientific argument to view_xifti. By default, scientific notation is determined automatically (as before). - Misc. patches Documentation - Add lit vs unlit comparison to README - Improved citations Changes in version 10.0 - Fix error during resampling when only one hemisphere is present - Better file I/O on mounted Google Drive - Add new viridis color palettes - Coerce new data input to newdata_xifti to numeric - Add file extension to file name in write_xifti automatically, if not provided Changes in version 9.0 New features - Add convention and orientation_labels to view_xifti_volume (default: neurological, instead of radiological as it's been previously) - Add together_ncol to view_xifti_* to control compositing layout - Add fname argument to view_comp to save the result to a PNG file - Allow "xifti" objects to have different resolutions in the left and right cortex - Add citation to welcome message Behind-the-scenes improvements - Better file path management for system commands - Better use of S3 group methods for Math, Ops, Summary functions - Replace coveralls with codecov - Misc. patches Changes in version 8.0 - Add more support for reading in v1 CIFTI files - Better handling of file paths - Better handling of optional "xifti" metadata - remove_xifti can delete individual subcortical structures now - Add scale_xifti which works like scale Changes in version 7.0 - Add view_comp, and the argument together to view_xifti_surface and view_xifti_volume - Fixes to view_xifti_surface and view_xifti_volume - Add limited support for v1 CIFTI - Fix some file paths of written files - Lower default surface smoothing from sigma = 5 to sigma = 3 - Add trans_units to subcortex metadata - Rename write_cifti_components as write_xifti2 and export - Add (in)equalities between "xifti" objects - Add workbench download URL to start message. - Add internal functions vox_locations and edit_mask_surf Changes in version 6.0 - Revamped subcortical visualization with view_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. - Revamped summary/print for "xifti" objects - Faster border computation in read_xifti_surface Changes in version 5.0 - Oops! The MNI image was removed in one of the recent versions. Added it back. - Minor fixes Changes in version 4.3 - Fix bug in read_cifti_convert where surfaces are not included - Switch from ciftiTools.files back to a function, ciftiTools.files(), because the latter doesn't actually work - Better handling of bad argument inputs and of the case where rgl.useNULL() in view_xifti_surface Changes in version 4.2 - Rename unmask_vol to unmask_subcortex Changes in version 4.1 Changes affecting users - New interface for reading in data included in the package - ciftiTools.files replaces demo_files(). This variable is created in the user's environment upon library(ciftiTools) with lazy loading - ciftiTools.files will only contain the inflated surface. To import the other two surfaces, use load_surf(). Removed the "surf" option from ciftiTools.setOption. - Better handling of surfaces - add_surf will automatically resample the surfaces if needed - read_surf has the argument resamp_res to enable resampling upon reading in the surface, similar to read_xifti - newdata_xifti will accept a length-one vector, to create a constant-valued "xifti" Notes for developers - ciftiTools.data contains the surfaces and parcellations building blocks, and the HCP 32k medial wall Changes in version 4.0 Changes affecting users - New surfaces! Check out ciftiTools.setOption("surf", ...) The default surface is still very inflated, but different. - Parcellations are now included in the package! Check out load_parc. - Add apply_xifti - Add move_to_mwall and move_from_mwall - Add idx argument to read_xifti and related functions - Add ... argument to transform_xifti - Add write_surf, an alias for write_surf_gifti - Export fix_xifti, which ensures xifti$data entries are matrices - Fix legend plot file placement in view_xifti_surface Notes for developers - Updated package documentation - make_surf is now an alias for read_surf, instead of the other way around Changes in version 3.1 Changes affecting users - convert_xifti accepts CIFTI files too - Add as.matrix S3 method - Fix interactive papayar view for view_xifti_volume Notes for developers None Changes in version 3.0 Changes affecting users - Rename concat_xifti as merge_xifti - Rename gifti_to_surf as read_surf - Add combine_xifti - Add convert_xifti and make the individual conversion functions (e.g. convert_to_dlabel) internal - Add smooth_gifti for metric GIFTI smoothing - Add S3 method dim for xifti objects - Add legend_alllevels arg to view_xifti_surface - More control over legend file name in view_xifti_surface - Add intent to summary output - write_xifti will infer the intent/extension if not included in output file name Notes for developers None Changes in version 2.2 Changes affecting users None Notes for developers - Add run_ciftiTools_tests.R to .Rbuildignore Changes in version 2.1 Changes affecting users - Search for "wb_path" during ciftiTools.setOption call, and never afterward - Ignore Workbench warnings, for the most part - Remove arguments concerning intermediate files in resample_cifti and read_cifti - Too many changes to document for view_xifti_surface! - transform_xifti improvements - Export remove_xifti - Add rotate_surf, select_xifti and concat_xifti Changes in version 2.0 Changes affecting users - Replace surface_sigma with surf_FWHM and likewise for volume - Better handling of plotting surface or volume in view_xifti Changes in version 1.6.1 Changes affecting users - Warn user (instead of raising an error) when the data has more medial wall vertices than non-medial wall vertices. - New handling of color mode, default colors and color limits. - Save color legends too, if saving surface plots. - Label for widget slider. - Move fields and rgl from Suggests to Imports. - Remove wb_path argument. (Use ciftiTools.setOption("wb_path", "path/to/workbench")) - transform_xifti to apply unary functions - Add mathematical operations: exp(cii) / 5 + cii2 - newdata_xifti to substitute data Changes in version 1.6 Changes affecting users - smooth_cifti - Add smoothing a xifti directly - cifti_target_fname is optional to smooth_cifti; will be auto-generated if NULL - Use the surfaces included with the ciftiTools package if not provided to smooth_cifti when corresponding cortex data exists - view_xifti_surface - Rename arguments regarding interactivity - Add option to draw borders for qualitative coloring - Add color legend with names of labels for qualitative coloring - Rename surface class to surf - as.xifti - Use HCP 32k mwall when not provided, by default (add option to control) - Add option to add column names - Retain more CIFTI metadata during resampling - Reduce package size to < 5 for CRAN by resampling demo files. Notes for developers - Add run_ciftiTools_tests.R (and add to .Rbuildignore) - Do not try linking to RColorBrewer::brewer.pal.info because it is an object, not a function. - Correct ciftiTools.listOptions and ciftiTools_msg - Make gifti_to_surf an alias to make_surf Changes in version 1.5 Changes affecting users - Add widget with slider for view_xifti_surface when more than one idx is requested! - Replace mode argument with interactive argument - Automatically use widget or video frames if more than one idx - Resilience to missing "MetaData" entry in CIFTI$Matrix Changes in version 1.4.2 Changes affecting users - view_xifti_surface - Option to draw vertices and edges - Automatically use (and resample to match data resolution) included surfaces, in most cases where surfaces were not provided - view_xifti_volume - Fix error when data are integers - Check that image dimensions and transformation matrix match with MNI template before plotting - Use 9 slices instead of 12 by default (when not using papayar) - New argument mwall_values to relevant functions. - The values will be used to infer the medial wall if the medial wall is not explicitly specified - Default: NA and NaN - This argument can be set to NULL to not infer the medial wall from the data - Better reading & writing of NIFTI and GIFTI files - Export and import 4x4 transformation matrix with CIFTI and NIFTI files - Use the TransformationMatrixIJKtoXYZ in CIFTI files - Use the sform codes in NIFTI files - Export and import label table and column names with CIFTI and GIFTI files (for dlabel and dscalar) - Write NIFTI with RNifti instead of oro.nifti - Corrected separating, writing and resampling *.dlabel.nii files - Make cifti_fname in read_cifti optional (can read in just the surfaces) - Warning if brainstructure is requested but not available (instead of error) - Convert smoothed dlabel to dscalar (and add warning, because it's probably something you don't want to do) - Documentation improvements Notes for developers - Improved handling of bad arguments to make_subcort - Split info_cifti_raw into header_cifti and xml_cifti - Add the internal functions remove_xifti, expect_equal_xifti and fix_gifti_mwall - view_surf is now a wrapper to view_xifti_surface instead of being its own function - Move color functions to utils_color. - Make ROY_BIG_BL have an extra value to fix legend range. - Handle constant-valued data in view_xifti_surface - Export color functions - Add "hemisphere" metadata to \code{"surf"} objects, and check that it matches if it exists. For example, as.xifti(surfL=surfR_gii) will cause an error - Move rgl and fields to Suggests - Add a few new tests based on these changes Changes in version 1.4 Changes Affecting Users - Spheres are no longer required to input for resampling - In-register spheres are generated automatically based on the cortical resolution - Full label table list for dlabel.nii files - Add smooth_cifti - Add resample_cifti_from_template - Add helpful error message if plot(xii) is called without any surface or subcortical data - view_xifti_surface improvements: - Use column index or name as the default title - Improved qualitative color mode - Use qualitative color mode and label table colors if the CIFTI is a dlabel.nii file (intent 3007) - view_xifti_volume improvements: - Fix num.slices argument - Add ... for additional arguments - Add view_surface for "surface" objects - Add summary and plot methods for "surface" objects - Warning if GIFTI version is too old (need the one on github for writegii) - Tweaks to view_xifti_surface defaults - Add view_xifti_volume without structural image - If a function writes a file(s) as its main side effect, return a named character vector of the written file paths. - Previously some functions returned TRUE while others returned a list or data.frame of written file paths - Out-of-mask values (medial wall for cortex and non-subcortical voxels for subcortex) are no longer inferred from the data values when making a "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.xifti - Rename make_surface as make_surf - Rename is.surface as is.surf - Rename side argument as hemisphere argument (same choices: "left" or "right") - Fixed the alias functions, e.g. readCIfTI and readcii for read_cifti Demo files - The demo files from NITRC are now included with ciftiTools: https://www.nitrc.org/frs/download.php/8541/cifti-2_test_data-1.2.zip Notes for Developers - Add tests for most user functions - Rename write_xifti_components as write_cifti_components - Remove metric_resample and surface_resample (use resample_gifti directly) - Rename make_helper_spheres as write_spheres, and do not export it - Rename unmask as unmask_vol (to distinguish from unmask_cortex) - Remove data-raw from R package build - Require gifti > 0.7.5 - Clean up onAttach and .Rbuildignore Vignette! It 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" Changes in version 1.3 - introduce "xifti" object: can be made from CIFTI file, GIFTI surfaces, or new data - To make a "xifti" from data: as.xifti(...) - To make a "xifti" from a CIFTI file: read_cifti(cifti_fname) - To make a "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) - This allows for reading in more metadata such as time start/step for .dtseries.nii - write_surf_gifti and write_metric_gifti as wrappers to the new gifti::writegii - Currently depends on damondpham/gifti but this will hopefully be merged to main repo soon - write_subcort_nifti to write out subcortical components from "xifti" to a NIFTI file - write_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 object Changes in version 1.2 - read_cifti_flat and read_cifti_separate - flatten subcortical data in "cifti" object. unflattening functions. - image view mode - write_cifti - better handling of medial wall - Subcortical color table added for writing CIFTIs. Taken from: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT Changes in version 1.1 New names Most 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: - Arguments referring to file names all end in _fname instead of beginning with fname_. - The cortical data, surf_L or cortex_left, are now cortexL (likewise for right). - The surface geometry data, gifti_left or surf_left, are now surfL (likewise for right). - The helper sphere for resampling, 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). - The resampling resolution, target_res or resample, is now resamp_res. - The Connectome Workbench argument wb_cmd is now wb_path. - outdir is now write_dir. New functionality There are a few new functions: - read_cifti_flat() reads the cortical and surface data together as a single matrix. - It is much faster than read_cifti(). - It works by using the Connectome Workbench command -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. - Each component can be provided as a file name or R object. - view_cifti() plots the CIFTI data. - It calls 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. - The default separated and resampled file names have been updated; see cifti_component_suffix. Other updates: - Print execution times for each step in separate_cifti() and resample_cifti() if verbose==TRUE. - Add option to set Connectome Workbench directory for the entire session with ciftiTools.setOption('wb_path', 'path/to/workbench'). - Either the folder or executable path can be provided. - Handling of spaces and parentheses in file names. - The ROI data can be separated and resampled. However, the "cifti" object does not support ROIs, so they are ultimately not loaded. - Please contact the developers if you are interested in this functionality. - A workaround would be to separate/resample the ROIs, and then read them in with make_xifti() (haven't tested this yet). - Add option to store a zero-value threshold, EPS. Set it with ciftiTools.setOption("EPS", 1e-8). This is used by view_cifti() and flatten_cifti() to detect constant zero brainordinates. - Several function aliases, for example readCIfTI() and readcii() for read_cifti(). - plot() method for "cifti" objects. Removed functionality - The overwrite and make_helper_files arguments were removed. All functions will overwrite existing files, and this cannot be changed. - A "cifti" object will only support one surface geometry model at a time. - view_cifti() can accept a surface GIFTI file directly. - The default brainstructures are left and right only (excludes the subcortical data). Notes for developers - Replaced oro.nifti::readNIfTI() with RNifti::readNifti() for faster reading of subcortical data. - Made formal classes for each CIFTI file component: "cifti_surface", "cifti_subcortical", "cifti_cortex", "cifti_volume" and "cifti_label". - Replaced read_separate_cifti() with read_cifti(), which calls separate_cifti(), resample_cifti_components() (optionally), and make_xifti() in that order. - Rewrote 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().) - Moved common argument/parameter descriptions to rox_args_docs.R. Use @inheritParams to reference these descriptions. This should make maintaining them across the entire package easier. - Wrapper functions 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. - Split utility functions into utils.R for general functions and utils_cifti.R for CIFTI-specific functions.