gifti_xml: Get GIFTI XML representation of data.

Description

Creates a GIFTI XML tree from your datasets (vectors and matrices). The tree can be further modified to add additional data, or written to a file as is to produce a valid GIFTI file (see gifti_xml_write).

Usage

gifti_xml(
  data_array,
  intent = "NIFTI_INTENT_SHAPE",
  datatype = "NIFTI_TYPE_FLOAT32",
  encoding = "GZipBase64Binary",
  endian = "LittleEndian",
  transform_matrix = NULL,
  force = FALSE
)

Value

xml tree, see xml2 package. One could modify this tree as needed using xml2 functions, e.g., add metadata.

Arguments

data_array: list of data vectors and/or data matrices.
intent: vector of NIFTI intent strings for the data vectors in 'data_array' parameter, see convert_intent. Example: 'NIFTI_INTENT_SHAPE'. See https://nifti.nimh.nih.gov/nifti-1/documentation/nifti1fields/nifti1fields_pages/group__NIFTI1__INTENT__CODES.html.
datatype: vector of NIFTI datatype strings. Example: 'NIFTI_TYPE_FLOAT32'. Should be suitable for your data.
encoding: vector of encoding definition strings. One of 'ASCII', 'Base64Binary', 'GZipBase64Binary'.
endian: vector of endian definition strings. One of 'LittleEndian' or 'BigEndian'. See convert_endian.
transform_matrix: optional, a list of transformation matrices, one for each data_array. If one of the data arrays has none, pass `NA`. Each transformation matrix in the outer list has to be a 4x4 matrix or given as a named list with entries 'transform_matrix', 'data_space', and 'transformed_space'. Here is an example: list('transform_matrix'=diag(4), 'data_space'='NIFTI_XFORM_UNKNOWN', 'transformed_space'='NIFTI_XFORM_UNKNOWN').
force: logical, whether to force writing the data, even if issues like a mismatch of datatype and data values are detected.

References

See https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf

Examples

Run this code

if (FALSE) {
  my_data_sets = list(rep(3.1, 3L), matrix(seq(6)+0.1, nrow=2L));
  transforms = list(NA, list('transform_matrix'=diag(4), 'data_space'='NIFTI_XFORM_UNKNOWN',
   'transformed_space'='NIFTI_XFORM_UNKNOWN'));
  xmltree = gifti_xml(my_data_sets, datatype='NIFTI_TYPE_FLOAT32', transform_matrix=transforms);
  # Verify that the tree is a valid GIFTI file:
  gifti_xsd = "https://www.nitrc.org/frs/download.php/158/gifti.xsd";
  xml2::xml_validate(xmltree, xml2::read_xml(gifti_xsd));
}