Minor 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 * 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 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
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
"xifti"
metadataremove_xifti
can delete individual subcortical
structures nowscale_xifti
which works like
scale
view_comp
, and the argument together
to view_xifti_surface
and
view_xifti_volume
view_xifti_surface
and
view_xifti_volume
trans_units
to subcortex metadatawrite_cifti_components
as
write_xifti2
and export"xifti"
objectsvox_locations
and
edit_mask_surf
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.summary
/print
for
"xifti"
objectsread_xifti_surface
read_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_surface
unmask_vol
to unmask_subcortex
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 loadingciftiTools.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
neededread_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
ciftiTools.setOption("surf", ...)
The default surface is
still very inflated, but different.load_parc
.apply_xifti
move_to_mwall
and move_from_mwall
idx
argument to read_xifti
and related
functions...
argument to transform_xifti
write_surf
, an alias for
write_surf_gifti
fix_xifti
, which ensures xifti$data
entries are matricesview_xifti_surface
make_surf
is now an alias for read_surf
,
instead of the other way aroundconvert_xifti
accepts CIFTI files tooas.matrix
S3 methodview_xifti_volume
None # 3.0 (June 13, 2021)
concat_xifti
as merge_xifti
gifti_to_surf
as read_surf
combine_xifti
convert_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_surface
view_xifti_surface
write_xifti
will infer the intent/extension if not
included in output file name ## Notes for developersNone
None
run_ciftiTools_tests.R
to
.Rbuildignore
ciftiTools.setOption
call,
and never afterwardresample_cifti
and read_cifti
view_xifti_surface
!transform_xifti
improvementsremove_xifti
rotate_surf
, select_xifti
and
concat_xifti
surface_sigma
with surf_FWHM
and
likewise for volumeview_xifti
fields
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 + cii2
newdata_xifti
to substitute datasmooth_cifti
xifti
directlycifti_target_fname
is optional to
smooth_cifti
; will be auto-generated if
NULL
ciftiTools
package
if not provided to smooth_cifti
when corresponding cortex
data existsview_xifti_surface
surface
class to surf
as.xifti
run_ciftiTools_tests.R
(and add to
.Rbuildignore)ciftiTools.listOptions
and
ciftiTools_msg
gifti_to_surf
an alias to
make_surf
view_xifti_surface
when more
than one idx
is requested!
mode
argument with interactive
argumentidx
view_xifti_surface
view_xifti_volume
papayar
)mwall_values
to relevant functions.
NA
and NaN
NULL
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_subcort
info_cifti_raw
into header_cifti
and
xml_cifti
remove_xifti
,
expect_equal_xifti
and fix_gifti_mwall
view_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_surface
as.xifti(surfL=surfR_gii)
will
cause an errorrgl
and fields
to Suggestsdlabel.nii
filessmooth_cifti
resample_cifti_from_template
plot(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.xifti
make_surface
as make_surf
is.surface
as is.surf
side
argument as hemisphere
argument (same choices: "left"
or
"right"
)readCIfTI
and
readcii
for read_cifti
ciftiTools
:
https://www.nitrc.org/frs/download.php/8541/cifti-2_test_data-1.2.zipwrite_xifti_components
as
write_cifti_components
metric_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.5
onAttach
and .Rbuildignore
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”
"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.nii
write_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_cifti
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:
_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.