R: Create or modify an NIfTI image object

asNifti {RNifti} | R Documentation

## Create or modify an NIfTI image object

### Description

This function converts a filename, array or other image class into an object of class `"niftiImage"`, and optionally updates its metadata from a reference image and/or changes its internal datatype. The dimensions and pixel dimensions from the `image` will replace those from the reference object, if they are available.

### Usage

    asNifti(x, reference = NULL, ...)

    ## Default S3 method:
    asNifti(x, reference = NULL, datatype = "auto", internal = NA, ...)

### Arguments

`x` | Any suitable object (see Details).
`reference` | An image, or a named list of NIfTI-1 properties like that produced by `niftiHeader`. The default of `NULL` will have no effect.
`...` | Additional parameters to methods.
`datatype` | The NIfTI datatype to use within the internal image. The default, `"auto"` uses the R type. Other possibilities are `"float"`, `"int16"`, etc., which may be preferred to reduce object size. However, no checks are done to ensure that the coercion maintains precision, and this option is for advanced usage only.
`internal` | Logical value. If `FALSE`, the result will be an array of class `"niftiImage"` containing the image pixel or voxel values, with some metadata in attributes. If `TRUE`, the result will be an object of class `"internalImage"`, which exposes some basic metadata to R but stores the pixel data internally. If `NA`, the default, the result will be an internal image only if the input `image` is. If a new `datatype` is set then this value is implicitly `TRUE`.

### Details

If the `image` has an internal NIfTI pointer, that will be retrieved directly. Otherwise, if it is a string, it will be taken to be a filename. If it looks like a `"nifti"` object (from package `oro.nifti`), or an `"MriImage"` object (from package `tractor.base`), a conversion will be performed. A list will be assumed to be of the form produced by `niftiHeader`. Finally, a numeric array or matrix, or RGB array, will be converted using default image parameters.

If `reference` is a complete list of NIfTI-1 header fields, like that produced by `niftiHeader`, or an image, then it will be used to create the internal object, and then the data and metadata associated with the `image` will overwrite the appropriate parts. If `reference` is an incomplete list, the `image` will be used to create the internal object, and then the specified fields will be overwritten from the list. This allows users to selectively update certain fields while leaving others alone (but see the note below).

If multiple values are passed for a field that expects a scalar (which is most of them), the first element of the vector will be used, with a warning. An empty vector will be ignored, also with a warning. If a value of the wrong length is passed to a vector-valued field, an error will be generated.

Datatype information in a list `reference` is ignored. The datatype can only be changed using the `datatype` argument, but in this case the internal object gets out of sync with the R array, so an internal image is returned to avoid the mismatch. Changing the internal datatype in this way is for advanced usage only.

`retrieveNifti` and `updateNifti` are soft-deprecated alternative interfaces to this function, which behave like the pre-existing functions of the same names. They may be removed in future.

### Value

An array or internal image, with class `"niftiImage"` (and possibly also `"internalImage"`).

### Note

The `scl_slope` and `scl_inter` fields affect the numerical interpretation of the pixel data, so it is impossible in general to change them without also changing the array values on both the C and the R side. Therefore, to avoid unexpected side-effects, these fields are not affected by this function. The `dim` and `pixdim` fields can be changed, but for most users the accessor functions of the same name are much safer, and should be used in preference.

### Author(s)

Jon Clayden <code@clayden.org>

### See Also

`readNifti`, `$.niftiImage`, `dim.internalImage`, `pixdim`, `xform`

[Package RNifti version 1.2.3 Index]