Library

from_fod(
    model::TMC{𝒯},
    n_seeds::Int64;
    n_sphere,
    maxfod_start
) -> Any

Generate seeds from orientation distribution functions.

Keyword arguments

• maxfod_start = false The seeds are generated in voxels with non-zero average FOD with the orientations importance sampled.
• maxfod_start = true The seeds are generated in voxels with non-zero average FOD with the orientations corresponding to the maximum probability.

from_mask(
    model::TMC{𝒯},
    mask::AbstractArray{Bool, 3},
    n_seeds::Int64
) -> Any

Generate seeds from a 3D mask. The seeds are generated randomly inside voxels with non-zero values in the mask. The orientations are random.

struct PlottingSH <: Tractography.AbstractSPHEvaluation

Set up for plotting ODF.

struct PreComputeAllFOD <: Tractography.AbstractSPHEvaluation

Spherical harmonics evaluation based on Fibonacci sampling. All ODF are pre-computed once and saved in a cache. Their positivity is enforced with a max(0,⋅) or a mollifier.

Details

If you have na angles for sampling the unit sphere and the data is of size (nx, ny, nz, nsph), it yields a matrix of dimensions (nx, ny, nz, na).

struct FODData{𝒯, 𝒯d, 𝒯s, 𝒯t}

Structure to hold FOD data.

Fields

• filename::String: filename from which the (fod) data is read.

• data::Any: field which contains the FOD data.

• lmax::Int64: max l coordinate in of spherical harmonics.

• transform::Tractography.Transform: transform associated with data, see Transform.

• normalized::Bool: Are the data normalized? In this case fod[i,j,l,1] ∈ {0,1}.

Methods

• get_lmax(::FODData) returns the max l coordinate in of spherical harmonics.
• size(::FODData) returns the size of the data.
• get_range(::FODData) returns the range of the data in the real world coordinates.

struct TMC{𝒯, 𝒯alg<:Tractography.AbstractSPHEvaluation, 𝒯d, 𝒯C, 𝒯mol}

Tractography Markov Chain (TMC).

Fields (with default values):

• Δt::Any: Step size of the TMC. Default: 0.1

• evaluation_algo::Tractography.AbstractSPHEvaluation: Spherical harmonics evaluation algorithm. Can be FibonacciSH(), PreComputeAllFOD(). Default: PreComputeAllFOD()

• foddata::Any: ODF data from nifti file. Must be the list of ODF in the base of spherical harmonics. Hence, it should be an (abstract) 4d array. Default: nothing

• cone::Any: Cone function to restrict angle diffusion. You can use a Cone or a custom function (d1, d2) -> return_a_boolean. Default: Cone(90.0f0)

• proba_min::Any: Probability below which we stop tracking. Default: 0.0

• mollifier::Any: Mollifier, used to make the fodf non negative. During odf evaluation, we effectively use mollifier(fodf[angle,i,j,k]). Default: max_mollifier

Methods

• _apply_mask!(model, mask) apply a mask to the raw SH tensor. See its doc string.
• _getdata(model) return the fodf data associated with the TMC.
• size(model) return nx, ny, nz, nt.
• eltype(model) return the scalar type of the data (default Float64).
• get_lmax(model) return the max l coordinate in of spherical harmonics.

Constructors (use the fields!)

• TMC()
• TMC(Δt = 0.1f0) for a Float32 TMC
• TMC(Δt = 0.1, proba_min = 0.) for a Float64 TMC. You need to specify both fields Δt and proba_min
• TMC(odfdata = rand(10,10,10,45)) for custom ODF

struct Deterministic <: Tractography.DeterministicSampler

Tractography sampling performed with the argmax function. Can be used with FibonacciSH and PreComputeAllFOD.

struct Probabilistic <: Tractography.AbstractNotPureRejectionSampler

Tractography sampling performed with the cumulative sum distribution. Can be used with FibonacciSH and PreComputeAllFOD.

Constructor

Probabilistic()

struct Diffusion{T, Tmol, Tdmol} <: Tractography.AbstractSDESampler{T}

Tractography sampling performed with diffusive model. Basically, the streamlines (Xₜ)ₜ are solution of the SDE

dXₜ = γ⋅drift(Xₜ)⋅dt + √(2γ ⋅ γ_noise) ⋅ dnoiseₜ

where

drift(Xₜ) = (Xₜ², ∇log f(Xₜ))

Arguments (with default values):

• γ::Any: γ parameter of the diffusion process. It is related to the curvature of the streamline. Default: 1.0

• γ_noise::Any: parameter of the diffusion process to scale the variance. Default: 1.0

• mollifier::Any: mollifier. Default: Base.Fix2(softplus, 10)

• d_mollifier::Any: differential of mollifier. Default: Base.Fix2(∂softplus, 10)

• adaptive::Bool: Fixed time step? Default: false

Constructor

Example for Float32: Diffusion(γ = 1f0). If you want Float64, you have to pass the two scalars

```Diffusion(γ = 1.0, γ_noise = 1.0)```

Define a transport algorithm. Options are the same as for Diffusion.

Arguments (with default values):

• γ::Any: γ parameter of the diffusion process. It is related to the curvature of the streamline. Default: 1.0

• mollifier::Any: mollifier. Default: Base.Fix2(softplus, 10)

• d_mollifier::Any: differential of mollifier. Default: Base.Fix2(∂softplus, 10)

• adaptive::Bool: Fixed time step? Default: false

struct Connectivity{Talg} <: Tractography.AbstractSampler

Tractography based sampling of structural connectivity. Do not compute the full streamline but only return the first/last points and the streamlines lengths. This allows to compute many more streamlines on GPU where memory is limited.

Constructor example

• Connectivity(Probabilistic())

init(
    model::TMC{𝒯},
    alg;
    n_sphere,
    𝒯ₐ
) -> Tractography.ThreadedCache{_A, Nothing, _B, Nothing, Nothing} where {_A, _B}

Create a cache for computing streamlines in batches. This is interesting for use of memory limited environments (e.g. on GPU).

Arguments

• alg sampling algorithm, Deterministic, Probabilistic, Diffusion, etc.
• n_sphere::Int = 400 number of points to discretize the sphere on which we evaluate the spherical harmonics.
• 𝒯ₐ = Array{𝒯} specify the type of the arrays in the cache. If passed a GPU array type like CuArray for CUDA, the sampling occurs on the GPU. Leave it for computing on CPU.

sample(
    model::TMC{𝒯},
    alg::Tractography.AbstractSampler,
    seeds::AbstractArray{𝒯, 2};
    ...
) -> Tuple{Any, Any}
sample(
    model::TMC{𝒯},
    alg::Tractography.AbstractSampler,
    seeds::AbstractArray{𝒯, 2},
    mask::Union{Nothing, AbstractArray{Bool}};
    nt,
    n_sphere,
    maxfod_start,
    reverse_direction,
    nthreads,
    gputhreads,
    saveat
) -> Tuple{Any, Any}

Sample the TMC model.

Arguments

• model::TMC
• alg sampling algorithm, Deterministic, Probabilistic, Diffusion, etc.
• seeds matrix of size 6 x Nmc where Nmc is the number of Monte-Carlo simulations to be performed.
• mask = nothing matrix of boolean where to stop computation. See also _apply_mask.

Optional arguments

• nt::Int maximal number of steps to compute each streamline.
• n_sphere::Int = 400 number of points to discretize the sphere on which we evaluate the spherical harmonics.
• maxfod_start::Bool for each locations, use direction provided by the argmax of the ODF.
• reverse_direction::Bool reverse initial direction.
• nthreads::Int = 8 number of threads on CPU.
• gputhreads::Int = 512 number of threads on GPU.
• saveat::Int record the streamline every saveat step. Only available for alg <: Diffusion.

Output

• streamlines with shape 3 x nt x Nmc

sample!(
    streamlines,
    streamlines_length,
    model::TMC{𝒯},
    cache::Tractography.AbstractCache,
    alg,
    seeds;
    maxfod_start,
    reverse_direction,
    nthreads,
    gputhreads,
    nₜ,
    saveat,
    𝒯ₐ
) -> Any

Sample the TMC model inplace by overwriting result. This requires very little memory and can be run indefinitely on the GPU for example.

Arguments

• streamlines array with shape 3 x nt x Nmc. nt is maximal length of each streamline. Nmc is the number of Monte-Carlo simulations to be performed.
• streamlines_length length of the streamlines
• model::TMC
• alg sampling algorithm, Deterministic, Probabilistic, Diffusion, etc.
• seeds matrix of size 6 x Nmc where Nmc is the number of Monte-Carlo simulations to be performed.

Optional arguments

• maxfod_start::Bool for each locations, use direction provided by the argmax of the ODF.
• reverse_direction::Bool reverse initial direction.
• nthreads::Int = 8 number of threads on CPU.
• gputhreads::Int = 512 number of threads on GPU.

plot_streamlines!(ax, streamlines; k...)

Plot the streamlines.

The optional parameters are passed to lines!

plot_fod!(ax, model; n_sphere, radius, st, I, J, K, c0min)

Plot the the ODF with glyphs.

See also

• plot_fod(model; kwargs...)

Arguments

• model::TMC
• I, J, K range for displaying the ODF. Some of them can be a single element, like K = 40:40.
• radius radius of the glyph.
• st = 4 stride, only show one over st glyph in each direction.

Optional arguments

plot_slice(model; k...)

Plot a slice of the data.

See also

• plot_slice!

Arguments

• model::TMC

Optional arguments

• odf::Bool display the ODF with glyphs.
• slice::Bool display the brain slice from mean ODF value.
• interpolate::Bool interpolate the brain slice (reduces pixelization).
• alpha alpha value for brain slice.
• I,J,K range for displaying the ODF. One of them should be a single element, like K = 40:40.
• st::Int = 2
• c0min minimum mean ODF value for plotting the glyph.
• n_theta::Int number of points for showing the glyphs.
• radius = 0.1 radius of the glyphs.

struct Cone{𝒯<:Real}

Structure to encode a cone to limit sampling the direction. This ensures that the angle in degrees between to consecutive streamline directions is less than angle.

The implemented condition is for cn = Cone(angle).

(cn::Cone)(d1, d2) = dot(d1, d2) > cosd(cn.alpha)

Fields

• alpha::Real: half section angle in degrees

Constructor

Cone(angle)

_apply_mask!(model, mask)

Multiply the mask which is akin to a matrix of Bool with same size as the data stored in model. Basically, the mask mask[ix, iy, iz] ensures whether the voxel (ix, iy, iz) is discarded or not.

Arguments

• model::TMC.
• mask can be a AbstractArray{3, Bool} or a NIVolume.

Exp𝕊²(p, X, t) -> Any

Exponential map on the sphere.

We assume that t > 0

See https://github.com/JuliaManifolds/ManifoldsBase.jl/blob/5c4a61ed3e5e44755a22f7872cb296a621905f87/test/ManifoldsBaseTestUtils.jl#L63

spherical_to_euclidean(θ, ϕ) -> Tuple{Any, Any, Any}

Transform spherical to cartesian coordinates, the chart on the sphere minus the north/south poles.

Its coordinates are (sin(θ)cos(ϕ), sin(θ)sin(ϕ), cos(θ)).

Recall that θ ∈ [0, π] and ϕ ∈ [0, 2π].

euclidean_to_spherical(x, y, z) -> Tuple{Any, Any}

Transform cartesian to spherical coordinates. Assume that the vector has norm one. Return (θ, ϕ) where θ ∈ [0, π] and ϕ ∈ [-π, π].