mandymejia / ciftiTools / 84

pending completion

Build # 84

Build Type

Pull #24

travis-ci-com

Committed by

web-flow

Commit Message

<a href="https://github.com/mandymejia/ciftiTools/commit/<a class=hub.com/mandymejia/ciftiTools/commit/<a class="double-link" href="https://git"><a class=hub.com/mandymejia/ciftiTools/commit/<a class="double-link" href="https://git"><a class=hub.com/mandymejia/ciftiTools/commit/<a class="double-link" href="https://git"><a class=hub.com/mandymejia/ciftiTools/commit/a9aad872d49e63a3529b38428ef5afa763c6152f">a9aad872d">&lt;a href=&quot;https://github.com/mandymejia/ciftiTools/commit/</a><a class="double-link" href="https://github.com/mandymejia/ciftiTools/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/mandymejia/ciftiTools/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/mandymejia/ciftiTools/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/mandymejia/ciftiTools/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/mandymejia/ciftiTools/commit/a9aad872d49e63a3529b38428ef5afa763c6152f">a9aad872d</a><a href="https://github.com/mandymejia/ciftiTools/commit/a9aad872d49e63a3529b38428ef5afa763c6152f">&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/mandymejia/ciftiTools/commit/&lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/mandymejia/ciftiTools/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/mandymejia/ciftiTools/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/mandymejia/ciftiTools/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/mandymejia/ciftiTools/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/mandymejia/ciftiTools/commit/a9aad872d49e63a3529b38428ef5afa763c6152f&quot;&gt;a9aad872d&lt;/a&gt;&lt;a href=&quot;https://github.com/mandymejia/ciftiTools/commit/a9aad872d49e63a3529b38428ef5afa763c6152f&quot;&gt;&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/mandymejia/ciftiTools/commit/&amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp... (continued)

Pull Request Pull Request #24: 3.0

Run Details

229 of 229 new or added lines in 14 files covered. (100.0%)

22 of 4016 relevant lines covered (0.55%)

0.02 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/R/read_cifti.R

#' Read a CIFTI file
#' 
#' Read a CIFTI file as a \code{"xifti"} object.
#' 
#' First, metadata is obtained with \code{\link{info_cifti}}. Then, if no 
#'  resampling is requested, the \code{-cifti-convert -to-gifti-ext} Workbench 
#'  Command is used to "flatten" the data and save it as a metric GIFTI file, 
#'  which is read in and separated by brainstructure according to the metadata 
#'  (\code{\link{read_cifti_convert}}). Otherwise, if sampling is requested, 
#'  then the CIFTI is separated into its GIFTI and NIFTI components, resampled,
#'  and then re-assembled (\code{\link{read_cifti_separate}}). The former is
#'  much faster for large CIFTI files, so the latter is only used when necessary
#'  for resampling.
#' 
#' If \code{cifti_fname} is not provided, then only the surfaces are read in.
#' 
#' @inheritSection Connectome_Workbench_Description Connectome Workbench Requirement
#' @inheritSection labels_Description Label Levels
#' 
#' @inheritParams cifti_fname_Param
#' @inheritParams surfL_fname_Param
#' @inheritParams surfR_fname_Param
#' @inheritParams brainstructures_Param_LR 
#' @param resamp_res Resolution to resample the cortical data and surface to.
#'  Default: \code{NULL} (do not resample). If not \code{NULL}, the data will 
#'  have to be read in with \code{-cifti-separate}, which is slower than 
#'  \code{-cifti-convert -to-gifti-ext}.
#' @param flat Should the result be flattened into a single matrix?
#' 
#'  If \code{FALSE} (default), the result will be a \code{"xifti"} object.
#' 
#'  If \code{TRUE}, the result will be a \eqn{T x G} matrix (\eqn{T} 
#'  measurements, \eqn{G} greyordinates not including the medial wall if it's 
#'  excluded from the ROI). All below arguments will be ignored because the 
#'  brain structures cannot be identified. Surfaces will not be appended. 
#'  Resampling is also not possible. \code{flat==TRUE} is the fastest way to 
#'  read in just the CIFTI data. 
#' 
#'  If \code{TRUE}, the greyordinates will be ordered by left cortex, right 
#'  cortex, and then subcortex. Subcortical voxels will be ordered by alphabetical 
#'  label. However, where each brainstructure (and subcortical structure) begins
#'  and ends cannot be determined. The medial wall locations and subcortical 
#'  brain mask are also not included. The data matrix will be identical to that 
#'  created by \code{-cifti-convert -to-gifti-ext}. 
#' @param mwall_values If the medial wall locations are not indicated in the
#'  CIFTI, use these values to infer the medial wall mask. Default: 
#'  \code{c(NA, NaN)}. If \code{NULL}, do not attempt to infer the medial wall.
#' @inheritParams verbose_Param_FALSE
#' @param ... Additional arguments to \code{\link{read_cifti_convert}} or 
#'  \code{\link{read_cifti_separate}}.
#'
#' @return If \code{!flat}, a \code{"xifti"} object. Otherwise, a \eqn{T x G} 
#'  matrix (\eqn{T} measurements, \eqn{G} greyordinates). 
#' 
#' @export
#'
read_cifti <- function(
  cifti_fname=NULL,
  surfL_fname=NULL, surfR_fname=NULL,
  brainstructures=c("left","right"), 
  resamp_res=NULL, flat=FALSE,
  mwall_values=c(NA, NaN), verbose=FALSE, ...){

  if (is.null(cifti_fname)) {
    if (is.null(surfL_fname) && is.null(surfR_fname)) {
      warning("`cifti_fname`, `surfL_fname` and `surfR_fname` were all NULL: Nothing to read!\n")
      return(template_xifti())
    } else {
      xifti <- template_xifti()
      xifti <- add_surf(xifti, surfL=surfL_fname, surfR=surfR_fname)
      if (!is.null(resamp_res)) {
        if (!is.null(xifti$surf$cortex_left)) {
          xifti$surf$cortex_left <- resample_surf(xifti$surf$cortex_left, resamp_res, "left")
        }
        if (!is.null(xifti$surf$cortex_right)) {
          xifti$surf$cortex_right <- resample_surf(xifti$surf$cortex_right, resamp_res, "right")
        }
      }
      return(xifti)
    }
  }

  # ----------------------------------------------------------------------------
  # Handle flat method. --------------------------------------------------------
  # ----------------------------------------------------------------------------

  if (flat) {
    if (!is.null(resamp_res)) {
      ciftiTools_warn(paste(
        "Resampling is not possible with the flat method.",
        "Ignoring `resamp_res`.\n"
      ))
    }
    return( read_cifti_flat(cifti_fname) )
  }

  # ----------------------------------------------------------------------------
  # Check arguments. -----------------------------------------------------------
  # ----------------------------------------------------------------------------

  require_separate_method <- !is.null(resamp_res)

  brainstructures <- match_input(
    brainstructures, c("left","right","subcortical","all"),
    user_value_label="brainstructures"
  )
  if ("all" %in% brainstructures) { 
    brainstructures <- c("left","right","subcortical")
  }

  # ----------------------------------------------------------------------------
  # Read. ----------------------------------------------------------------------
  # ----------------------------------------------------------------------------

  if (!require_separate_method) {
    return(read_cifti_convert(
      cifti_fname,
      surfL_fname=surfL_fname, surfR_fname=surfR_fname,
      brainstructures=brainstructures, 
      mwall_values=mwall_values, verbose=verbose,
      ...
    ))

  } else {
    return(read_cifti_separate(
      cifti_fname,
      surfL_fname=surfL_fname, surfR_fname=surfR_fname,
      brainstructures=brainstructures, 
      resamp_res=resamp_res, 
      mwall_values=mwall_values, verbose=verbose,
      ...
    ))
  }
}

#' @rdname read_cifti
#' @export
readCIfTI <- function(
  cifti_fname=NULL,
  surfL_fname=NULL, surfR_fname=NULL,
  brainstructures=c("left","right"), 
  resamp_res=NULL, flat=FALSE,
  mwall_values=c(NA, NaN), verbose=FALSE, ...){

  read_cifti(
    cifti_fname=cifti_fname,
    surfL_fname=surfL_fname, surfR_fname=surfR_fname,
    brainstructures=brainstructures, 
    resamp_res=resamp_res, flat=flat, 
    mwall_values=mwall_values, verbose=verbose, ...
  )
}

#' @rdname read_cifti
#' @export
readcii <- function(
  cifti_fname=NULL,
  surfL_fname=NULL, surfR_fname=NULL,
  brainstructures=c("left","right"), 
  resamp_res=NULL, flat=FALSE,
  mwall_values=c(NA, NaN), verbose=FALSE, ...){

  read_cifti(
    cifti_fname=cifti_fname,
    surfL_fname=surfL_fname, surfR_fname=surfR_fname,
    brainstructures=brainstructures, 
    resamp_res=resamp_res, flat=flat, 
    mwall_values=mwall_values, verbose=verbose, ...
  )
}

#' @rdname read_cifti
#' @export
read_xifti <- function(
  cifti_fname=NULL,
  surfL_fname=NULL, surfR_fname=NULL,
  brainstructures=c("left","right"), 
  resamp_res=NULL, flat=FALSE,
  mwall_values=c(NA, NaN), verbose=FALSE, ...){

  read_cifti(
    cifti_fname=cifti_fname,
    surfL_fname=surfL_fname, surfR_fname=surfR_fname,
    brainstructures=brainstructures, 
    resamp_res=resamp_res, flat=flat, 
    mwall_values=mwall_values, verbose=verbose, ...
  )
}

1	#' Read a CIFTI file
2	#'
3	#' Read a CIFTI file as a \code{"xifti"} object.
4	#'
5	#' First, metadata is obtained with \code{\link{info_cifti}}. Then, if no
6	#' resampling is requested, the \code{-cifti-convert -to-gifti-ext} Workbench
7	#' Command is used to "flatten" the data and save it as a metric GIFTI file,
8	#' which is read in and separated by brainstructure according to the metadata
9	#' (\code{\link{read_cifti_convert}}). Otherwise, if sampling is requested,
10	#' then the CIFTI is separated into its GIFTI and NIFTI components, resampled,
11	#' and then re-assembled (\code{\link{read_cifti_separate}}). The former is
12	#' much faster for large CIFTI files, so the latter is only used when necessary
13	#' for resampling.
14	#'
15	#' If \code{cifti_fname} is not provided, then only the surfaces are read in.
16	#'
17	#' @inheritSection Connectome_Workbench_Description Connectome Workbench Requirement
18	#' @inheritSection labels_Description Label Levels
19	#'
20	#' @inheritParams cifti_fname_Param
21	#' @inheritParams surfL_fname_Param
22	#' @inheritParams surfR_fname_Param
23	#' @inheritParams brainstructures_Param_LR
24	#' @param resamp_res Resolution to resample the cortical data and surface to.
25	#' Default: \code{NULL} (do not resample). If not \code{NULL}, the data will
26	#' have to be read in with \code{-cifti-separate}, which is slower than
27	#' \code{-cifti-convert -to-gifti-ext}.
28	#' @param flat Should the result be flattened into a single matrix?
29	#'
30	#' If \code{FALSE} (default), the result will be a \code{"xifti"} object.
31	#'
32	#' If \code{TRUE}, the result will be a \eqn{T x G} matrix (\eqn{T}
33	#' measurements, \eqn{G} greyordinates not including the medial wall if it's
34	#' excluded from the ROI). All below arguments will be ignored because the
35	#' brain structures cannot be identified. Surfaces will not be appended.
36	#' Resampling is also not possible. \code{flat==TRUE} is the fastest way to
37	#' read in just the CIFTI data.
38	#'
39	#' If \code{TRUE}, the greyordinates will be ordered by left cortex, right
40	#' cortex, and then subcortex. Subcortical voxels will be ordered by alphabetical
41	#' label. However, where each brainstructure (and subcortical structure) begins
42	#' and ends cannot be determined. The medial wall locations and subcortical
43	#' brain mask are also not included. The data matrix will be identical to that
44	#' created by \code{-cifti-convert -to-gifti-ext}.
45	#' @param mwall_values If the medial wall locations are not indicated in the
46	#' CIFTI, use these values to infer the medial wall mask. Default:
47	#' \code{c(NA, NaN)}. If \code{NULL}, do not attempt to infer the medial wall.
48	#' @inheritParams verbose_Param_FALSE
49	#' @param ... Additional arguments to \code{\link{read_cifti_convert}} or
50	#' \code{\link{read_cifti_separate}}.
51	#'
52	#' @return If \code{!flat}, a \code{"xifti"} object. Otherwise, a \eqn{T x G}
53	#' matrix (\eqn{T} measurements, \eqn{G} greyordinates).
54	#'
55	#' @export
56	#'
57	read_cifti <- function(
58	cifti_fname=NULL,
59	surfL_fname=NULL, surfR_fname=NULL,
60	brainstructures=c("left","right"),
61	resamp_res=NULL, flat=FALSE,
62	mwall_values=c(NA, NaN), verbose=FALSE, ...){
63
64	if (is.null(cifti_fname)) {	×
65	if (is.null(surfL_fname) && is.null(surfR_fname)) {	×
66	warning("`cifti_fname`, `surfL_fname` and `surfR_fname` were all NULL: Nothing to read!\n")	×
67	return(template_xifti())	×
68	} else {
69	xifti <- template_xifti()	×
70	xifti <- add_surf(xifti, surfL=surfL_fname, surfR=surfR_fname)	×
71	if (!is.null(resamp_res)) {	×
72	if (!is.null(xifti$surf$cortex_left)) {	×
73	xifti$surf$cortex_left <- resample_surf(xifti$surf$cortex_left, resamp_res, "left")	×
74	}
75	if (!is.null(xifti$surf$cortex_right)) {	×
76	xifti$surf$cortex_right <- resample_surf(xifti$surf$cortex_right, resamp_res, "right")	×
77	}
78	}
79	return(xifti)	×
80	}
81	}
82
83	# ----------------------------------------------------------------------------
84	# Handle flat method. --------------------------------------------------------
85	# ----------------------------------------------------------------------------
86
87	if (flat) {	×
88	if (!is.null(resamp_res)) {	×
89	ciftiTools_warn(paste(	×
90	"Resampling is not possible with the flat method.",	×
91	"Ignoring `resamp_res`.\n"	×
92	))
93	}
94	return( read_cifti_flat(cifti_fname) )	×
95	}
96
97	# ----------------------------------------------------------------------------
98	# Check arguments. -----------------------------------------------------------
99	# ----------------------------------------------------------------------------
100
101	require_separate_method <- !is.null(resamp_res)	×
102
103	brainstructures <- match_input(	×
104	brainstructures, c("left","right","subcortical","all"),	×
105	user_value_label="brainstructures"	×
106	)
107	if ("all" %in% brainstructures) {	×
108	brainstructures <- c("left","right","subcortical")	×
109	}
110
111	# ----------------------------------------------------------------------------
112	# Read. ----------------------------------------------------------------------
113	# ----------------------------------------------------------------------------
114
115	if (!require_separate_method) {	×
116	return(read_cifti_convert(	×
117	cifti_fname,	×
118	surfL_fname=surfL_fname, surfR_fname=surfR_fname,	×
119	brainstructures=brainstructures,	×
120	mwall_values=mwall_values, verbose=verbose,	×
121	...
122	))
123
124	} else {
125	return(read_cifti_separate(	×
126	cifti_fname,	×
127	surfL_fname=surfL_fname, surfR_fname=surfR_fname,	×
128	brainstructures=brainstructures,	×
129	resamp_res=resamp_res,	×
130	mwall_values=mwall_values, verbose=verbose,	×
131	...
132	))
133	}
134	}
135
136	#' @rdname read_cifti
137	#' @export
138	readCIfTI <- function(
139	cifti_fname=NULL,
140	surfL_fname=NULL, surfR_fname=NULL,
141	brainstructures=c("left","right"),
142	resamp_res=NULL, flat=FALSE,
143	mwall_values=c(NA, NaN), verbose=FALSE, ...){
144
145	read_cifti(	×
146	cifti_fname=cifti_fname,	×
147	surfL_fname=surfL_fname, surfR_fname=surfR_fname,	×
148	brainstructures=brainstructures,	×
149	resamp_res=resamp_res, flat=flat,	×
150	mwall_values=mwall_values, verbose=verbose, ...	×
151	)
152	}
153
154	#' @rdname read_cifti
155	#' @export
156	readcii <- function(
157	cifti_fname=NULL,
158	surfL_fname=NULL, surfR_fname=NULL,
159	brainstructures=c("left","right"),
160	resamp_res=NULL, flat=FALSE,
161	mwall_values=c(NA, NaN), verbose=FALSE, ...){
162
163	read_cifti(	×
164	cifti_fname=cifti_fname,	×
165	surfL_fname=surfL_fname, surfR_fname=surfR_fname,	×
166	brainstructures=brainstructures,	×
167	resamp_res=resamp_res, flat=flat,	×
168	mwall_values=mwall_values, verbose=verbose, ...	×
169	)
170	}
171
172	#' @rdname read_cifti
173	#' @export
174	read_xifti <- function(
175	cifti_fname=NULL,
176	surfL_fname=NULL, surfR_fname=NULL,
177	brainstructures=c("left","right"),
178	resamp_res=NULL, flat=FALSE,
179	mwall_values=c(NA, NaN), verbose=FALSE, ...){
180
181	read_cifti(	×
182	cifti_fname=cifti_fname,	×
183	surfL_fname=surfL_fname, surfR_fname=surfR_fname,	×
184	brainstructures=brainstructures,	×
185	resamp_res=resamp_res, flat=flat,	×
186	mwall_values=mwall_values, verbose=verbose, ...	×
187	)
188	}

mandymejia / ciftiTools / 84

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous