NeuroFormats

tdd()

Get the path of the NeuroFormats test data directory.

This is useful if you do not have own neuroimaging data at hand but still want to try NeuroFormats: you can use the unit test data that comes with the package. Explore the returned directory to see what is available.

Examples

julia> curv_file = joinpath(tdd(), "subjects_dir/subject1/surf/lh.thickness");

export_to_obj(file:: AbstractString, bm::BrainMesh)

Export a brain mesh to a Wavefront Object File.

Use read_surf to obtain a mesh to export. Exporting to the popular OBJ format is useful for loading the mesh in 3D modeling or visualization applications, like Blender3D.

Examples

julia> surf_file = joinpath(tdd(), "subjects_dir/subject1/surf/lh.white");
julia> surf = read_surf(surf_file);
julia> export_to_obj(tempname(), surf.mesh)

export_to_obj(file:: AbstractString, x::FsSurface)

Export the mesh of a FreeSurfer surface to a Wavefront Object File.

Use read_surf to obtain a mesh to export.

Examples

julia> surf_file = joinpath(tdd(), "subjects_dir/subject1/surf/lh.white");
julia> surf = read_surf(surf_file);
julia> export_to_obj(tempname(), surf)

label_from_rgb(r::Integer, g::Integer, b::Integer, a::Integer=0)

Compute the label from the color code of an FsAnnot brain region. Returns an integer, the label code.

Examples

julia> annot_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.aparc.annot");
julia> annot = read_annot(annot_file);
julia> label_from_rgb(annot.colortable.r[1], annot.colortable.g[1], annot.colortable.b[1])

mgh_vox2ras(mgh::Mgh)

Compute the vox2ras matrix for an Mgh instance. Requires valid RAS header data. The vox2ras matrix can be used to compute the x, y, z RAS coordinates of a voxel based on its i, j and k indices in the first three dimensions of the volume. Its inverse, the ras2vox matrix, can be used to compute the indices of the voxel that occupies a point in space given by its x, y, z RAS coordinates.

Examples

julia> mgh_file = joinpath(tdd(), "subjects_dir/subject1/mri/brain.mgz");
julia> mgh = read_mgh(mgh_file);
julia> mgh_vox2ras(mgh)

Compute the number of faces contained in a BrainMesh struct.

Compute the number of faces contained in an FsSurfaceHeader struct.

Compute the number of faces contained in an FsSurface struct.

Compute the number of vertices contained in a BrainMesh struct.

Compute the number of vertices contained in an FsSurfaceHeader struct.

Compute the number of vertices contained in an FsSurface struct.

read_annot(file::AbstractString)

Read a FreeSurfer brain parcellation from an annot file. A brain parcellation divides the cortex into a set of non-overlapping regions, based on a brain atlas. FreeSurfer parcellations assign a region label and a color to each vertex of the mesh representing the reconstructed cortex.

See also: read_surf to read the mesh that belongs the parcellation, and read_curv to read per-vertex data for the mesh or brain region vertices. Also see the convenience functions regions, region_vertices, label_from_rgb and vertex_regions to work with FsAnnot structs.

Returns an FsAnnot struct.

Examples

julia> annot_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.aparc.annot");
julia> annot = read_annot(annot_file);
julia> regions(annot)
julia> Base.length(region_vertices(annot, "bankssts")) # show vertex count of bankssts brain region.

read_curv(file::AbstractString; with_header::Bool=false)

Read per-vertex data for brain meshes from the Curv file file. The file must be in FreeSurfer binary Curv format, like lh.thickness. Returns an Array{Float32,1} with the data unless with_header is set, in which case a Curv struct is returned instead.

See also: write_curv

Examples

julia> curv_file = joinpath(tdd(), "subjects_dir/subject1/surf/lh.thickness");
julia> curv = read_curv(curv_file);
julia> sum(curv)/length(curv) # show mean cortical thickness

 read_label(file::AbstractString)

Read a FreeSurfer ASCII label file and return the contents as a DataFrame. Both surface labels and volume labels are supported.

A label contains a set of vertex or voxel indices (some brain region, note though that the vertices must not be adjacent: the region can consist of several patches). It can also assign a value to each vertex/voxel. Sometimes the values are all left at zero, typically this is the case when one only wants to store the vertex/voxel indices (e.g., because they make up some region of interest). There seems to be no definite way to tell whether a label file contains a volume label (voxel indices) or a surface label (vertices). But it seems that if your label contains negative indices, it has to be a volume label.

Note that we use surface label terminology in the code to refer to the fields, but what is called 'vertexindices' below may mean 'voxelindices' in case of a volume label.

Returns a DataFrames.DataFrame.

Examples

julia> label_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.entorhinal_exvivo.label");
julia> label = read_label(label_file);
julia> sum(label[!, "value"])

read_mgh(file::AbstractString)

Read a file in FreeSurfer MGH or MGZ format.

These files typically contain 3D or 4D images, i.e., they represent voxel-based MRI data. They can also be used to store surface-based data though, in which case only 1 dimension is used (or 2 dimensions if data for several subjects or time points in included).

Examples

julia> mgh_file = joinpath(tdd(), "subjects_dir/subject1/mri/brain.mgz");
julia> mgh = read_mgh(mgh_file);
julia> Base.ndims(mgh.data) # Show data dimensions.

read_surf(file::AbstractString)

Read a brain surface model represented as a mesh from a file in FreeSurfer binary surface format. Such a file typically represents a single hemisphere. Returns an FsSurface struct.

Examples

julia> surf_file = joinpath(tdd(), "subjects_dir/subject1/surf/lh.white");
julia> surf = read_surf(surf_file);
julia> Base.size(surf.mesh.faces, 1) # Get face count.

region_vertices(annot::FsAnnot, region::String)

Get all vertices of a region in an FsAnnot brain surface parcellation. Returns an integer vector, the vertex indices.

Examples

julia> annot_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.aparc.annot");
julia> annot = read_annot(annot_file);
julia> region_vertices(annot, "bankssts") # show all vertices which are part of bankssts region.

regions(annot::FsAnnot)

Return the brain region names of the FsAnnot surface annotation.

Examples

julia> annot_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.aparc.annot");
julia> annot = read_annot(annot_file);
julia> regions(annot) # show all regions

vertex_regions(annot::FsAnnot)

Compute the region names for all vertices in an FsAnnot brain surface parcellation.

Examples

julia> annot_file = joinpath(tdd(), "subjects_dir/subject1/label/lh.aparc.annot");
julia> annot = read_annot(annot_file);
julia> vertex_regions(annot) # show for each vertex the brain region it is part of.

write_curv(file::AbstractString, curv_data::Vector{<:Number})

Write a numeric vector to a binary file in FreeSurfer Curv format. The data will be coverted to Float32.

This function is typically used to write surface-based neuroimaging data, like per-vertex cortical thickness measurements from a reconstructed brain mesh.

See also: read_curv

Examples

julia> write_curv("~/study1/subject1/surf/lh.thickness", convert(Array{Float32}, zeros(100)))

Models a trimesh. Vertices are defined by their xyz coordinates and contained in the vertices field as an n*3 matrix, and faces are given as indices into the vertex array in the faces field.

Models the brain region table included in an FsAnnot FreeSurfer annotation. Each entry describes a brain region, which has a running numerical id, a name, a display color (r,g,b), and a unique integer label (computed from the color code) which is used in the corresponding FsAnnot to identify the region of a vertex.

Models the structure of a file in Curv format. The header field contains a CurvHeader, the data field is a Float32 vector of per-vertex values. The values appear in the same order as the the vertices in the corresponding brain mesh (surf) file.

Models the header section of a file in Curv format.

Models a FreeSurfer brain surface parcellation from an annot file. This is the result of applying a brain atlas (like Desikan-Killiani) to a subject. The vertex_indices are the 0-based indices used in FreeSurfer and should be ignored. The vertex_labels field contains the mesh vertices in order, and assigns to each vertex a brain region using the label field (not the id field!) from the colortable. The field colortable contains a ColorTable struct that describes the brain regions.

Models FreeSurfer Surface file. The header field is an FsSurfaceHeader struct that can usually be ignored, the mesh field is a BrainMesh struct.

Models the header section of a file in FreeSurfer Surface format. The files are big endian. This header can usually be ignored.

Models a FreeSurfer brain volume file in MGH or MGZ format. The field header is an MghHeader struct, and the data field is a 4-dimensional numerical array. The exact data type of the data array depends on the file contents.

Models the header of a FreeSurfer brain volume file in MGH or MGZ format. The data in the delta, mdc and p_xyz_c fields must be used only if is_ras_good is 1, otherwise their contents is random.

Alternate MghHeader constructor that does not require valid RAS information.

read_tck(file::AbstractString)

Read DTI tracks from a MRtrix3 file in TCK format.

Returns a DtiTck struct.

See also: read_trk reads tracks from DiffusionToolkit files.

Examples

julia> tck_file = joinpath(tdd(), "DTI/simple_big_endian.tck");
julia> tck = read_tck(tck_file);
julia> Base.length(tck.tracks) # show track count

read_trk(file::AbstractString)

Read DTI tracks from a file in the TRK format used by DiffusionToolkit and TrackVis.

Returns a DtiTrk struct.

See also: read_tck reads tracks from MRtrix3 files.

Examples

julia> trk_file = joinpath(tdd(), "DTI/complex_big_endian.trk");
julia> trk = read_trk(trk_file);
julia> Base.length(trk.tracks) # show track count

Models a DTI TCK file. The header field contains a dictionary with the header fields, which can be anything a software decides to put there. The tracks fields contains a vector of DtiTrack structs.

Models a single track. The field point_coords contains an nx3 matrix of point coordinates. The point_scalars vector contains zero or more scalar values for each point of the track. The track_properties vector contains zero or more scalar values for the whole track. See the corresponding header for interpretation of point_scalars and track_properties.

Models a DTI TRK file. The header field contains a DtiTrkHeader struct. The tracks fields contains a vector of DtiTrack structs.

Models the header of a TRK format file containing fiber tracks.