Skip to content

Latest commit

 

History

History
445 lines (346 loc) · 22.2 KB

NEWS.md

File metadata and controls

445 lines (346 loc) · 22.2 KB
Raw

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

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)

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.