NEWS.md

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

15.0

• Make default of read_cifti all brain structures, instead of left and right cortex only
• add "Other" to subcortex levels

14.0

Minor fixes and improvements.

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.

12.0 (Jul 28, 2023)

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.

11.0 (Jan 23, 2023)

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

10.0 (July 5, 2022)

• 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

9.0 (May 16, 2022)

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

8.0 (February 1, 2022)

• 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

7.0 (November 16, 2021)

• 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

6.0 (September 13, 2021)

• 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

5.0 (August 31, 2021)

• Oops! The MNI image was removed in one of the recent versions. Added it back.
• Minor fixes

4.3 (August 14, 2021)

• 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

4.2 (August 10, 2021)

• Rename unmask_vol to unmask_subcortex

4.1 (August 7, 2021)

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

4.0 (August 4, 2021)

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

3.1 (June 16, 2021)

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

3.0 (June 13, 2021)

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

2.2 (March 16, 2021)

Changes affecting users

None

Notes for developers

• Add run_ciftiTools_tests.R to .Rbuildignore

2.1 (March 15, 2021)

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

2.0 (February 2, 2021)

Changes affecting users

• Replace surface_sigma with surf_FWHM and likewise for volume
• Better handling of plotting surface or volume in view_xifti

1.6.1 (January 29, 2021)

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

1.6 (November 10, 2020)

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

1.5 (October 2, 2020)

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

1.4.2 (September 25, 2020)

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

1.4 (August 31, 2020)

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"

1.3 (August 24, 2020)

• 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

1.2 (August 7, 2020)

• 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

1.1 (July 24, 2020)

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.