The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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.

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 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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.