gyral_structure.cost package: defining the cost function

Individual classes are not documented on this page. Their full documentation can be found here.

Defines individual terms of the cost function.

Normal arithmetic can be used to add the cost function terms together, e.g. Watson + 0.01 * L2

Terms are separated based on what they affect:

gyral_structure.cost.core module

Defines subclasses for all cost function terms

  • GenericCost serves as the superclass of all cost functions

  • CostFunc serves as any cost function on the vector field rather than the parameters directly (see cost.param for the latter)

  • SympyCost puts a constraint on the vector field defined by any sympy equation (which is generally easier than defining the cost function and its derivative in python)

In addition this module defines CostEvaluator, which combines any cost function with a basis function. This class contains the actual optimisation code.

gyral_structure.cost.dens module

Defines cost functions that act on the density (i.e. norm) of the vector field, independent of its orientation

  • MinInner: Encourages the density of streamlines crossing a surface exceeds a certain value

  • TargetInner: Sets a target value for the density of streamlines crossing a surface element

  • InnerCost: Sets a target value for the density of streamlines crossing a surface element (same as TargetInner)

  • TotalIntersect: Sets a target value for the total number of streamlines crossing a whole surface

  • L1Density: L1 norm in the vector field density

  • L2Density: L2 norm in the vector field density

  • SameDensity: Encourages two fields to have the same vector field density (useful as a smoothness constraint)

gyral_structure.cost.meta module

Defines cost functions that take other cost functions as input

Most of these can be created by adding/subtracting/multiplying cost functions, except for:

  • ExponentAdd: add cost function terms exponentially

  • Smoothness: compares the vector field in neighbouring voxels

  • MinCost: use the minimum of several cost functions for fitting (useful when fitting to crossing fibers)

gyral_structure.cost.orient module

Defines terms for the cost function that constrain the fibre orientation independent of fiber density

  • VonMises: encourages alignment with the direction of a reference field (disallows flipping)

  • Watson: encourages alignment with the orientation of a reference field (allows for flipping)

  • BinghamDistribution: encourages alignment with a reference field with an ellipsoidal uncertainty (allows for flipping)

gyral_structure.cost.param module

Terms of the cost function that take the model parameters rather than the vector field as input

  • ParamCost: superclass of all such cost functions

  • L2Params: L2 constraint on the parameters

  • ParamVecMult: minimize the multiplication of the parameters with a vector

  • ParamMatMult: minimize \(p A p - q p\) for some matrix \(A\) and vector \(q\) (for parameters \(p\))

  • ParamTargetVec: minimize \(|A p - q|\) for some matrix \(A\) and vector \(q\) (for parameters \(p\))