distributions

Module: distributions.distribute_models

class dmipy.distributions.distribute_models.DistributedModel

Contains various properties of distributed models.

Attributes

Methods

add_linked_parameters_to_parameters(parameters)

Adds the linked parameters to the optimized parameters.

Parameters:

parameters: dictionary of model parameters, :

contains the optimized parameters.

Returns:

parameters: dictionary of model parameters, :

contains the optimzed and linked parameters.

copy()

Retuns a different instantiation of the DistributedModel with the same configuration, which can be used together with the original in a MultiCompartmentModel. For example, to do NODDI with multiple orientations.

fod(vertices, **kwargs)

Returns the Fiber Orientation Distribution (FOD) of a dispersed model.

Parameters:

vertices: array of size (N_samples, 3) :

cartesian unit vectors at which to sample the FOD

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

integrated_model(acquisition_scheme, **kwargs)

The spatially integrated function call for spatial distributions like Gamma. Currently, the model assumed we are distributing diameters.

First, the linked parameters are added to the optimized parameters, and the probability that a water particle exists inside a cylinder of a certain size in the distribution is sampled for a range of diameters. The volume fractions are also converted from nested to regular ones (although typically not more than 1 model is used for a Gamma distribution).

Then, for every model in the DistributedModel, the signal attenuations of the model are are recovered for the sampled diameters and multiplied and integrated over their probabilities. The resulting values are multiplied with the volume fractions and finally the integrated signal attenuation is returned.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

parameter_names

Retuns the DistributedModel parameter names.

set_equal_parameter(parameter_name_in, parameter_name_out)

Allows the user to set two parameters equal to each other. This is used for example in the NODDI model to set the parallel diffusivities of the Stick and Zeppelin compartment to the same value.

The second input parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

parameter_name_in: string :

the first parameter name, see self.parameter_names.

parameter_name_out: string, :

the second parameter name, see self.parameter_names. This is the parameter that will be removed form the optimzed parameters.

set_fixed_parameter(parameter_name, value)

Allows the user to fix an optimization parameter to a static value. The fixed parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

parameter_name: string :

name of the to-be-fixed parameters, see self.parameter_names.

value: float or list of corresponding parameter_cardinality. :

the value to fix the parameter at in SI units.

set_tortuous_parameter(lambda_perp, lambda_par, volume_fraction_intra)

Allows the user to set a tortuosity constraint on the perpendicular diffusivity of the extra-axonal compartment, which depends on the intra-axonal volume fraction and parallel diffusivity.

The perpendicular diffusivity parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

lambda_perp: string :

name of the perpendicular diffusivity parameter, see self.parameter_names.

lambda_par: string :

name of the parallel diffusivity parameter, see self.parameter_names.

volume_fraction_intra: string :

name of the intra-axonal volume fraction parameter, see self.parameter_names.

sh_convolved_model(acquisition_scheme, **kwargs)

The spherical harmonics convolved function call for spherically distributions like Watson and Bingham.

First, the linked parameters are added to the optimized parameters, and the spherical harmonics of the spherical distribution are recovered. The volume fractions are also converted from nested to regular ones.

Then, for every model in the DistributedModel, and for every acquisition shell, the rotational harmonics of the model are recovered and convolved with the distribution spherical harmonics. The resulting values are multiplied with the volume fractions and finally the dispersed signal attenuation is returned.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

class dmipy.distributions.distribute_models.SD1WatsonDistributed(models, parameter_links=None)

The DistributedModel instantiation for a Watson-dispersed model. Multiple models can be dispersed at the same time (like a Stick and Zeppelin for NODDI for example). The parameter ‘mu’ of the models will be removed and replaced by the ‘mu’ and ‘odi’ of the Watson distribution.

After instantiation the WatsonDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

class dmipy.distributions.distribute_models.SD2BinghamDistributed(models, parameter_links=None)

The DistributedModel instantiation for a Bingham-dispersed model. Multiple models can be dispersed at the same time (like a Stick and Zeppelin for NODDI for example). The parameter ‘mu’ of the models will be removed and replaced by the ‘mu’, ‘odi’, ‘beta_fraction’ and ‘psi’ of the Bingham distribution.

After instantiation the BinghamDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

class dmipy.distributions.distribute_models.DD1GammaDistributed(models, parameter_links=None, target_parameter='diameter')

The DistributedModel instantiation for a Gamma-distributed model for cylinder or sphere models. Multiple models can be distributed at the same time (but such multi-cylinder-distribution models have never been used as far as we know). The parameter ‘diameter’ of the models will be removed and replaced by the ‘alpha’ and ‘beta’, of the Gamma distribution.

After instantiation the GammaDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

rotational_harmonics_representation(acquisition_scheme, **kwargs)

The rotational harmonics of the model, such that Y_lm = Yl0. Axis aligned with z-axis to be used as kernel for spherical convolution. Returns an array with rotational harmonics for each shell.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

Returns:

rh_array : array, shape(Nshells, N_rh_coef),

Rotational harmonics coefficients for each shell.

set_diameter_constrained_parameter_beta(diameter_min, diameter_max)

spherical_mean(acquisition_scheme, **kwargs)

Estimates spherical mean for every shell in acquisition scheme.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

Returns:

E_mean : float,

spherical mean of the model for every acquisition shell.

class dmipy.distributions.distribute_models.ReturnFixedValue(value)

Parameter fixing class for parameter links.

Methods

Module: distributions.distributions

Document Module

dmipy.distributions.distributions.get_sh_order_from_odi(odi)

Returns minimum sh_order to estimate spherical harmonics for given odi.

class dmipy.distributions.distributions.SD1Watson(mu=None, odi=None)

The Watson spherical distribution model [R16] [R17].

Parameters:

mu : array, shape(2),

angles [theta, phi] representing main orientation on the sphere. theta is inclination of polar angle of main angle mu [0, pi]. phi is polar angle of main angle mu [-pi, pi].

kappa : float,

concentration parameter of the Watson distribution.

References

[R16]

(1, 2) Kaden et al. “Parametric spherical deconvolution: inferring anatomical connectivity using diffusion MR imaging”. NeuroImage (2007)

[R17]

(1, 2) Zhang et al. “NODDI: practical in vivo neurite orientation dispersion and density imaging of the human brain”. NeuroImage (2012)

Attributes

Methods

spherical_harmonics_representation(sh_order=None, **kwargs)

The Watson spherical distribution model in spherical harmonics. The minimum order is automatically derived from numerical experiments to ensure fast function executation and accurate results.

Parameters:

sh_order : int,

maximum spherical harmonics order to be used in the approximation.

Returns:

watson_sh : array,

spherical harmonics of Watson probability density.

class dmipy.distributions.distributions.SD2Bingham(mu=None, psi=None, odi=None, beta_fraction=None)

The Bingham spherical distribution model [R18] [R19] [R20] using angles.

Parameters:

mu : array, shape(2),

angles [theta, phi] representing main orientation on the sphere. theta is inclination of polar angle of main angle mu [0, pi]. phi is polar angle of main angle mu [-pi, pi].

psi : float,

angle in radians of the bingham distribution around mu [0, pi].

kappa : float,

first concentration parameter of the Bingham distribution. defined as kappa = kappa1 - kappa3.

beta : float,

second concentration parameter of the Bingham distribution. defined as beta = kappa2 - kappa3. Bingham becomes Watson when beta=0.

References

[R18]

(1, 2) Kaden et al. “Parametric spherical deconvolution: inferring anatomical connectivity using diffusion MR imaging”. NeuroImage (2007)

[R19]

(1, 2) Sotiropoulos et al. “Ball and rackets: inferring fiber fanning from diffusion-weighted MRI”. NeuroImage (2012)

[R20]

(1, 2) Tariq et al. “Bingham–NODDI: Mapping anisotropic orientation dispersion of neurites using diffusion MRI”. NeuroImage (2016)

Attributes

Methods

spherical_harmonics_representation(sh_order=None, **kwargs)

The Bingham spherical distribution model in spherical harmonics. The minimum order is automatically derived from numerical experiments to ensure fast function executation and accurate results.

Parameters:

sh_order : int,

maximum spherical harmonics order to be used in the approximation.

Returns:

bingham_sh : array,

spherical harmonics of Bingham probability density.

class dmipy.distributions.distributions.DD1Gamma(alpha=None, beta=None, Nsteps=30, normalization='standard')

A Gamma distribution of cylinder diameter for given alpha and beta parameters. NOTE: This is a distribution for axon DIAMETER and not SURFACE. To simulate the diffusion signal of an ensemble of gamma-distributed cylinders the probability still needs to be corrected for cylinder surface by multiplying by np.pi * radius ** 2 and renormalizing [R21]. Reason being that diffusion signals are generated by the volume of spins inside axons (cylinders), which is proportional to cylinder surface and not to diameter.

Parameters:

alpha : float,

shape of the gamma distribution.

beta : float,

scale of the gamma distrubution. Different from Bingham distribution!

References

[R21]

(1, 2) Assaf, Yaniv, et al. “AxCaliber: a method for measuring axon diameter distribution from diffusion MRI.” Magnetic resonance in medicine 59.6 (2008): 1347-1354.

Attributes

Methods

calculate_sampling_start_and_end_points(norm_func, gridsize=50)

For a given normalization function calculates the best start and end points to sample for all possible values of alpha, beta. This is done to make sure the function does not sample where the probability of basically zero.

The function is based on first doing a dense sampling and then finding out which points need to be included to have sampled at least 99% of the area under the probability density curve.

It sets two interpolator functions that can be called for any combination of alpha,beta and to return the appropriate start and end sampling points.

Parameters:

norm_func : normalization function,

normalization of the model, depends on if it’s a sphere/cylinder.

gridsize : integer,

value that decides how big the grid will be on which we define the start and end sampling points.

length_plane(radius)

The distance normalization function for planes.

surface_cylinder(radius)

The surface normalization function for cylinders.

unity(radius)

The standard normalization for the Gamma distribution (none).

volume_sphere(radius)

The volume normalization function for spheres.

dmipy.distributions.distributions.odi2kappa(odi)

Calculates concentration (kappa) from orientation dispersion index (odi).

dmipy.distributions.distributions.kappa2odi(kappa)

Calculates orientation dispersion index (odi) from concentration (kappa).

DD1GammaDistributed

class dmipy.distributions.distribute_models.DD1GammaDistributed(models, parameter_links=None, target_parameter='diameter')

Bases: dmipy.distributions.distribute_models.DistributedModel

The DistributedModel instantiation for a Gamma-distributed model for cylinder or sphere models. Multiple models can be distributed at the same time (but such multi-cylinder-distribution models have never been used as far as we know). The parameter ‘diameter’ of the models will be removed and replaced by the ‘alpha’ and ‘beta’, of the Gamma distribution.

After instantiation the GammaDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

__init__(models, parameter_links=None, target_parameter='diameter')

rotational_harmonics_representation(acquisition_scheme, **kwargs)

The rotational harmonics of the model, such that Y_lm = Yl0. Axis aligned with z-axis to be used as kernel for spherical convolution. Returns an array with rotational harmonics for each shell.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

Returns:

rh_array : array, shape(Nshells, N_rh_coef),

Rotational harmonics coefficients for each shell.

set_diameter_constrained_parameter_beta(diameter_min, diameter_max)

spherical_mean(acquisition_scheme, **kwargs)

Estimates spherical mean for every shell in acquisition scheme.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

Returns:

E_mean : float,

spherical mean of the model for every acquisition shell.

DistributedModel

class dmipy.distributions.distribute_models.DistributedModel

Contains various properties of distributed models.

Attributes

Methods

add_linked_parameters_to_parameters(parameters)

Adds the linked parameters to the optimized parameters.

Parameters:

parameters: dictionary of model parameters, :

contains the optimized parameters.

Returns:

parameters: dictionary of model parameters, :

contains the optimzed and linked parameters.

copy()

Retuns a different instantiation of the DistributedModel with the same configuration, which can be used together with the original in a MultiCompartmentModel. For example, to do NODDI with multiple orientations.

fod(vertices, **kwargs)

Returns the Fiber Orientation Distribution (FOD) of a dispersed model.

Parameters:

vertices: array of size (N_samples, 3) :

cartesian unit vectors at which to sample the FOD

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

integrated_model(acquisition_scheme, **kwargs)

The spatially integrated function call for spatial distributions like Gamma. Currently, the model assumed we are distributing diameters.

First, the linked parameters are added to the optimized parameters, and the probability that a water particle exists inside a cylinder of a certain size in the distribution is sampled for a range of diameters. The volume fractions are also converted from nested to regular ones (although typically not more than 1 model is used for a Gamma distribution).

Then, for every model in the DistributedModel, the signal attenuations of the model are are recovered for the sampled diameters and multiplied and integrated over their probabilities. The resulting values are multiplied with the volume fractions and finally the integrated signal attenuation is returned.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

parameter_names

Retuns the DistributedModel parameter names.

set_equal_parameter(parameter_name_in, parameter_name_out)

Allows the user to set two parameters equal to each other. This is used for example in the NODDI model to set the parallel diffusivities of the Stick and Zeppelin compartment to the same value.

The second input parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

parameter_name_in: string :

the first parameter name, see self.parameter_names.

parameter_name_out: string, :

the second parameter name, see self.parameter_names. This is the parameter that will be removed form the optimzed parameters.

set_fixed_parameter(parameter_name, value)

Allows the user to fix an optimization parameter to a static value. The fixed parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

parameter_name: string :

name of the to-be-fixed parameters, see self.parameter_names.

value: float or list of corresponding parameter_cardinality. :

the value to fix the parameter at in SI units.

set_tortuous_parameter(lambda_perp, lambda_par, volume_fraction_intra)

Allows the user to set a tortuosity constraint on the perpendicular diffusivity of the extra-axonal compartment, which depends on the intra-axonal volume fraction and parallel diffusivity.

The perpendicular diffusivity parameter will be removed from the optimized parameters and added as a linked parameter.

Parameters:

lambda_perp: string :

name of the perpendicular diffusivity parameter, see self.parameter_names.

lambda_par: string :

name of the parallel diffusivity parameter, see self.parameter_names.

volume_fraction_intra: string :

name of the intra-axonal volume fraction parameter, see self.parameter_names.

sh_convolved_model(acquisition_scheme, **kwargs)

The spherical harmonics convolved function call for spherically distributions like Watson and Bingham.

First, the linked parameters are added to the optimized parameters, and the spherical harmonics of the spherical distribution are recovered. The volume fractions are also converted from nested to regular ones.

Then, for every model in the DistributedModel, and for every acquisition shell, the rotational harmonics of the model are recovered and convolved with the distribution spherical harmonics. The resulting values are multiplied with the volume fractions and finally the dispersed signal attenuation is returned.

Parameters:

acquisition_scheme : DmipyAcquisitionScheme instance,

An acquisition scheme that has been instantiated using dMipy.

kwargs: keyword arguments to the model parameter values, :

Is internally given as **parameter_dictionary.

OrderedDict

class dmipy.distributions.distribute_models.OrderedDict(*args, **kwds)

Bases: dict

Dictionary that remembers insertion order

Methods

__init__(*args, **kwds)

Initialize an ordered dictionary. The signature is the same as regular dictionaries, but keyword arguments are not recommended because their insertion order is arbitrary.

clear() → None. Remove all items from od.

copy() → a shallow copy of od

classmethod fromkeys(S[, v]) → New ordered dictionary with keys from S.

If not specified, the value defaults to None.

items() → list of (key, value) pairs in od

iteritems()

od.iteritems -> an iterator over the (key, value) pairs in od

iterkeys() → an iterator over the keys in od

itervalues()

od.itervalues -> an iterator over the values in od

keys() → list of keys in od

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), return and remove a (key, value) pair.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(k[, d]) → od.get(k,d), also set od[k]=d if k not in od

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of values in od

viewitems() → a set-like object providing a view on od's items

viewkeys() → a set-like object providing a view on od's keys

viewvalues() → an object providing a view on od's values

ReturnConstrainedBeta

class dmipy.distributions.distribute_models.ReturnConstrainedBeta(diameter_min, diameter_max)

Optimization parameter class to constrain gamma distribution mean.

Methods

__init__(diameter_min, diameter_max)

ReturnFixedValue

class dmipy.distributions.distribute_models.ReturnFixedValue(value)

Parameter fixing class for parameter links.

Methods

__init__(value)

SD1WatsonDistributed

class dmipy.distributions.distribute_models.SD1WatsonDistributed(models, parameter_links=None)

Bases: dmipy.distributions.distribute_models.DistributedModel

The DistributedModel instantiation for a Watson-dispersed model. Multiple models can be dispersed at the same time (like a Stick and Zeppelin for NODDI for example). The parameter ‘mu’ of the models will be removed and replaced by the ‘mu’ and ‘odi’ of the Watson distribution.

After instantiation the WatsonDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

__init__(models, parameter_links=None)

SD2BinghamDistributed

class dmipy.distributions.distribute_models.SD2BinghamDistributed(models, parameter_links=None)

Bases: dmipy.distributions.distribute_models.DistributedModel

The DistributedModel instantiation for a Bingham-dispersed model. Multiple models can be dispersed at the same time (like a Stick and Zeppelin for NODDI for example). The parameter ‘mu’ of the models will be removed and replaced by the ‘mu’, ‘odi’, ‘beta_fraction’ and ‘psi’ of the Bingham distribution.

After instantiation the BinghamDistributed model can be treated exactly the same as a CompartmentModel as an input for a MultiCompartmentModel.

Parameters:

models: list of length 1 or more, :

list of models to be Watson-dispersed.

parameters_links: list of length 1 or more, :

deprecated for testing use only.

Attributes

Methods

__init__(models, parameter_links=None)

chain

class dmipy.distributions.distribute_models.chain

Bases: object

chain(*iterables) –> chain object

Return a chain object whose .next() method returns elements from the first iterable until it is exhausted, then elements from the next iterable, until all of the iterables are exhausted.

Methods

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

from_iterable()

chain.from_iterable(iterable) –> chain object

Alternate chain() contructor taking a single iterable argument that evaluates lazily.

next

T1_tortuosity

dmipy.distributions.distribute_models.T1_tortuosity(lambda_par, vf_intra, vf_extra=None)

Tortuosity model for perpendicular extra-axonal diffusivity [1, 2, 3]. If vf_extra=None, then vf_intra must be a nested volume fraction, in the sense that E_bundle = vf_intra * E_intra + (1 - vf_intra) * E_extra, with vf_intra + (1 - vf_intra) = 1. If both vf_intra and vf_extra are given, then they have be be normalized fractions, in the sense that vf_intra + vf_extra <= 1.

Parameters:

lambda_par : float,

parallel diffusivity.

vf_intra : float,

intra-axonal volume fraction [0, 1].

vf_extra : float, (optional)

extra-axonal volume fraction [0, 1].

Returns:

lambda_perp : float,

Rotation matrix.

References :

——- :

.. [1] Bruggeman, Von DAG. “Berechnung verschiedener physikalischer :

Konstanten von heterogenen Substanzen. I. Dielektrizitätskonstanten und Leitfähigkeiten der Mischkörper aus isotropen Substanzen.” Annalen der physik 416.7 (1935): 636-664.

.. [2] Sen et al. “A self-similar model for sedimentary rocks with :

application to the dielectric constant of fused glass beads.” Geophysics 46.5 (1981): 781-795.

.. [3] Szafer et al. “Theoretical model for water diffusion in tissues.” :

Magnetic resonance in medicine 33.5 (1995): 697-712.

parameter_equality

dmipy.distributions.distribute_models.parameter_equality(param)

Function to force two model parameters to be equal in the optimization

sh_convolution

dmipy.distributions.distribute_models.sh_convolution(f_distribution_sh, kernel_rh)

Spherical convolution between a fiber distribution (f) in spherical harmonics and a kernel in terms of rotational harmonics (oriented along the z-axis).

Parameters:

f_distribution_sh : array, shape (sh_coef)

spherical harmonic coefficients of a fiber distribution.

kernel_rh : array, shape (sh_coef),

rotational harmonic coefficients of the convolution kernel. In our case this is the spherical signal of one micro-environment at one b-value.

Returns:

f_kernel_convolved : array, shape (sh_coef)

spherical harmonic coefficients of the convolved kernel and distribution.

DD1Gamma

class dmipy.distributions.distributions.DD1Gamma(alpha=None, beta=None, Nsteps=30, normalization='standard')

Bases: dmipy.core.modeling_framework.ModelProperties

A Gamma distribution of cylinder diameter for given alpha and beta parameters. NOTE: This is a distribution for axon DIAMETER and not SURFACE. To simulate the diffusion signal of an ensemble of gamma-distributed cylinders the probability still needs to be corrected for cylinder surface by multiplying by np.pi * radius ** 2 and renormalizing [R22]. Reason being that diffusion signals are generated by the volume of spins inside axons (cylinders), which is proportional to cylinder surface and not to diameter.

Parameters:

alpha : float,

shape of the gamma distribution.

beta : float,

scale of the gamma distrubution. Different from Bingham distribution!

References

[R22]

(1, 2) Assaf, Yaniv, et al. “AxCaliber: a method for measuring axon diameter distribution from diffusion MRI.” Magnetic resonance in medicine 59.6 (2008): 1347-1354.

Attributes

Methods

__init__(alpha=None, beta=None, Nsteps=30, normalization='standard')

calculate_sampling_start_and_end_points(norm_func, gridsize=50)

For a given normalization function calculates the best start and end points to sample for all possible values of alpha, beta. This is done to make sure the function does not sample where the probability of basically zero.

The function is based on first doing a dense sampling and then finding out which points need to be included to have sampled at least 99% of the area under the probability density curve.

It sets two interpolator functions that can be called for any combination of alpha,beta and to return the appropriate start and end sampling points.

Parameters:

norm_func : normalization function,

normalization of the model, depends on if it’s a sphere/cylinder.

gridsize : integer,

value that decides how big the grid will be on which we define the start and end sampling points.

length_plane(radius)

The distance normalization function for planes.

surface_cylinder(radius)

The surface normalization function for cylinders.

unity(radius)

The standard normalization for the Gamma distribution (none).

volume_sphere(radius)

The volume normalization function for spheres.

HemiSphere

class dmipy.distributions.distributions.HemiSphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Bases: dipy.core.sphere.Sphere

Points on the unit sphere.

A HemiSphere is similar to a Sphere but it takes antipodal symmetry into account. Antipodal symmetry means that point v on a HemiSphere is the same as the point -v. Duplicate points are discarded when constructing a HemiSphere (including antipodal duplicates). edges and faces are remapped to the remaining points as closely as possible.

The HemiSphere can be constructed using one of three conventions:

HemiSphere(x, y, z)
HemiSphere(xyz=xyz)
HemiSphere(theta=theta, phi=phi)

Parameters:

x, y, z : 1-D array_like

Vertices as x-y-z coordinates.

theta, phi : 1-D array_like

Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.

xyz : (N, 3) ndarray

Vertices as x-y-z coordinates.

faces : (N, 3) ndarray

Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.

edges : (N, 2) ndarray

Edges between vertices. If unspecified, the edges are derived from the faces.

tol : float

Angle in degrees. Vertices that are less than tol degrees apart are treated as duplicates.

See also

Sphere

Attributes

Methods

__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Create a HemiSphere from points

faces()

find_closest(xyz)

Find the index of the vertex in the Sphere closest to the input vector, taking into account antipodal symmetry

Parameters:

xyz : array-like, 3 elements

A unit vector

classmethod from_sphere(klass, sphere, tol=1e-05)

Create instance from a Sphere

mirror()

Create a full Sphere from a HemiSphere

subdivide(n=1)

Create a more subdivided HemiSphere

See Sphere.subdivide for full documentation.

ModelProperties

class dmipy.distributions.distributions.ModelProperties

Contains various properties for CompartmentModels.

Attributes

parameter_cardinality

Returns the cardinality of model parameters

parameter_names

Returns the names of model parameters.

parameter_ranges

Returns the optimization ranges of the model parameters. These ranges are given in O(1) scale so optimization algorithms don’t suffer from large scale differences in optimization parameters.

parameter_scales

Returns the optimization scales for the model parameters. The scales scale the parameter_ranges to their actual size inside optimization algorithms.

parameter_types

Returns the optimization scales for the model parameters. The scales scale the parameter_ranges to their actual size inside optimization algorithms.

SD1Watson

class dmipy.distributions.distributions.SD1Watson(mu=None, odi=None)

Bases: dmipy.core.modeling_framework.ModelProperties

The Watson spherical distribution model [R23] [R24].

Parameters:

mu : array, shape(2),

angles [theta, phi] representing main orientation on the sphere. theta is inclination of polar angle of main angle mu [0, pi]. phi is polar angle of main angle mu [-pi, pi].

kappa : float,

concentration parameter of the Watson distribution.

References

[R23]

(1, 2) Kaden et al. “Parametric spherical deconvolution: inferring anatomical connectivity using diffusion MR imaging”. NeuroImage (2007)

[R24]

(1, 2) Zhang et al. “NODDI: practical in vivo neurite orientation dispersion and density imaging of the human brain”. NeuroImage (2012)

Attributes

Methods

__init__(mu=None, odi=None)

spherical_harmonics_representation(sh_order=None, **kwargs)

The Watson spherical distribution model in spherical harmonics. The minimum order is automatically derived from numerical experiments to ensure fast function executation and accurate results.

Parameters:

sh_order : int,

maximum spherical harmonics order to be used in the approximation.

Returns:

watson_sh : array,

spherical harmonics of Watson probability density.

SD2Bingham

class dmipy.distributions.distributions.SD2Bingham(mu=None, psi=None, odi=None, beta_fraction=None)

Bases: dmipy.core.modeling_framework.ModelProperties

The Bingham spherical distribution model [R25] [R26] [R27] using angles.

Parameters:

mu : array, shape(2),

angles [theta, phi] representing main orientation on the sphere. theta is inclination of polar angle of main angle mu [0, pi]. phi is polar angle of main angle mu [-pi, pi].

psi : float,

angle in radians of the bingham distribution around mu [0, pi].

kappa : float,

first concentration parameter of the Bingham distribution. defined as kappa = kappa1 - kappa3.

beta : float,

second concentration parameter of the Bingham distribution. defined as beta = kappa2 - kappa3. Bingham becomes Watson when beta=0.

References

[R25]

(1, 2) Kaden et al. “Parametric spherical deconvolution: inferring anatomical connectivity using diffusion MR imaging”. NeuroImage (2007)

[R26]

(1, 2) Sotiropoulos et al. “Ball and rackets: inferring fiber fanning from diffusion-weighted MRI”. NeuroImage (2012)

[R27]

(1, 2) Tariq et al. “Bingham–NODDI: Mapping anisotropic orientation dispersion of neurites using diffusion MRI”. NeuroImage (2016)

Attributes

Methods

__init__(mu=None, psi=None, odi=None, beta_fraction=None)

spherical_harmonics_representation(sh_order=None, **kwargs)

The Bingham spherical distribution model in spherical harmonics. The minimum order is automatically derived from numerical experiments to ensure fast function executation and accurate results.

Parameters:

sh_order : int,

maximum spherical harmonics order to be used in the approximation.

Returns:

bingham_sh : array,

spherical harmonics of Bingham probability density.

get_sh_order_from_odi

dmipy.distributions.distributions.get_sh_order_from_odi(odi)

Returns minimum sh_order to estimate spherical harmonics for given odi.

get_sphere

dmipy.distributions.distributions.get_sphere(name='symmetric362')

provide triangulated spheres

Parameters:

name : str

which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns:

sphere : a dipy.core.sphere.Sphere class instance

Examples

>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name') 
Traceback (most recent call last):
    ...
DataError: No sphere called "not a sphere name"

join

dmipy.distributions.distributions.join(a, *p)

Join two or more pathname components, inserting ‘/’ as needed. If any component is an absolute path, all previous path components will be discarded. An empty last part will result in a path that ends with a separator.

kappa2odi

dmipy.distributions.distributions.kappa2odi(kappa)

Calculates orientation dispersion index (odi) from concentration (kappa).

odi2kappa

dmipy.distributions.distributions.odi2kappa(odi)

Calculates concentration (kappa) from orientation dispersion index (odi).

optional_package

dmipy.distributions.distributions.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:

name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.

Returns:

pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

real_sym_sh_mrtrix

dmipy.distributions.distributions.real_sym_sh_mrtrix(sh_order, theta, phi)

Compute real spherical harmonics as in mrtrix, where the real harmonic \(Y^m_n\) is defined to be:

Real(:math:`Y^m_n`)       if m > 0
:math:`Y^0_n`             if m = 0
Imag(:math:`Y^|m|_n`)     if m < 0

This may take scalar or array arguments. The inputs will be broadcasted against each other.

Parameters:

sh_order : int

The maximum degree or the spherical harmonic basis.

theta : float [0, pi]

The polar (colatitudinal) coordinate.

phi : float [0, 2*pi]

The azimuthal (longitudinal) coordinate.

Returns:

y_mn : real float

The real harmonic \(Y^m_n\) sampled at theta and phi as implemented in mrtrix. Warning: the basis is Tournier et al 2004 and 2007 is slightly different.

m : array

The order of the harmonics.

n : array

The degree of the harmonics.