mathUtils — biskit 3.0.0a1 documentation

# mathUtils

general purpose math methods

Functions Overview

`SD` | Standard deviation, S{sigma}
`aboveDiagonal` | Collect all the values above the diagonal in a square matrix.
`accumulate` | cumulative sum of C{ a[0], a[0]+a[1], a[0]+a[1]+[a2], …
`area` | Numerically add up the area under the given curve.
`arrayEqual` | Compare 2 arrays or lists of numbers for equality.
`cartesian2D` | Convert from polar (r,w) to rectangular (x,y) x = r cos(w) y = r sin(w) Author: Victor Gil
`cartesianToPolar` | Convert cartesian coordinate array to polar coordinate array: C{ x,y,z -> r, S{theta}, S{phi} }
`cbrt` | cubic root.
`cubic` | x^3 + ax^2 + bx + c = 0 (or ax^3 + bx^2 + cx + d = 0) With substitution x = y-t and t = a/3, the cubic equation reduces to y^3 + py + q = 0, where p = b-3t^2 and q = c-bt+2t^3.
`difference` | All members of a that are not in b C{ difference([any], [any]) -> [any] }
`eulerRotation` | Builds a rotation matrix from successive rotations: 1.
`intersection` | Intersection of the two lists (i.e.
`linfit` | Calculate linear least-square fit to the points given by x and y.
`listToMatrix` | Convert result of `matrixToList` back into Numeric array
`matrixToList` | Convert matrix into standard python list remembering the dimensions.
`nonredundant` | All members of a list without duplicates C{ noredundant( [any] ) -> [any] }
`outliers` | Iterative detection of outliers in a set of numeric values.
`packBinaryMatrix` | Compress sparse array of 0 and ones to list of one-positions (space saving function, upack with `unpackBinaryMatrix`).
`pairwiseDistances` | Pairwise distances between two arrays.
`polar2D` | Convert from rectangular (x,y) to polar (r,w) r = sqrt(x^2 + y^2) w = arctan(y/x) = [-pi,pi] = [-180,180]
`polarToCartesian` | Convert polar coordinate array to cartesian coordinate array: C{ r, S{theta}, S{phi} -> x,y,z }
`projectOnSphere` | Project the coordinates xyz on a sphere with a given radius around a given center.
`quadratic` | x^2 + ax + b = 0 (or ax^2 + bx + c = 0) By substituting x = y-t and t = a/2, the equation reduces to y^2 + (b-t^2) = 0 which has easy solution y = +/- sqrt(t^2-b)
`random2DArray` | Create randomized 2D array containing ones and zeros.
`randomMask` | Create random array of given lenght and number of ones.
`randomRange` | Creates a set of n unique integers randomly distributed between start and stop.
`randomRotation` | Get random rotation matrix.
`removeFromList` | Remove all or first occurrence(s) of v from l.
`rotateAxis` | Calculate a left multiplying rotation matrix that rotates theta rad around vector.
`runningAverage` | Running average (smoothing) over a given data window.
`slidingAverage` |
`union` | Union of two lists (without duplicates) C{ union( [any], [any] ) -> [any] }
`unpackBinaryMatrix` | Uncompress array of 0 and 1 that was compressed with `packBinaryMatrix`.
`variance` | Variance, S{sigma}^2
`wMean` | Weighted mean: Mean of data (x) weighted by (w).
`wSD` | Standard deviation of weighted data.
`wVar` | Variance of weighted (w) data (x).

Classes Overview

Exceptions Defined in this Module

`MathUtilError` |

## mathUtils Module Details

exception `biskit.mathUtils.` `MathUtilError`

`biskit.mathUtils.` `accumulate`(a)

  cumulative sum of C{ a[0], a[0]+a[1], a[0]+a[1]+[a2], … } normalized by C{ N0.sum( a ) }

  Parameters: | a (array) – array(‘f’) or float
  Returns: | float
  Return type: | float

`biskit.mathUtils.` `variance`(x, avg=None)

  Variance, S{sigma}^2

  Parameters: | x (array('f') or float) – data avg (float OR None) – use this average, otherwise calculated from x
  Returns: | float
  Return type: | float

`biskit.mathUtils.` `SD`(x, avg=None)

  Standard deviation, S{sigma}

  Parameters: | x (array('f') or float) – data avg (float OR None) – use this average, otherwise calculated from x
  Returns: | float
  Return type: | float

`biskit.mathUtils.` `wMean`(x, w=None)

  Weighted mean: Mean of data (x) weighted by (w).

  Parameters: | x (array) – X-D array with numbers w (array) – 1-D array of same length as x with weight factors
  Returns: | array(‘f’) or float
  Return type: | array(‘f’) or float

`biskit.mathUtils.` `wVar`(x, w)

  Variance of weighted (w) data (x).

  Parameters: | x (array) – X-D array with numbers w (array) – 1-D array of same length as x with weight factors
  Returns: | array(‘f’) or float
  Return type: | array(‘f’) or float

`biskit.mathUtils.` `wSD`(x, w)

  Standard deviation of weighted data.

  Parameters: | x (array) – X-D array with numbers w (array) – 1-D array of same length as x with weight factors
  Returns: | array(‘f’) or float
  Return type: | array(‘f’) or float

`biskit.mathUtils.` `aboveDiagonal`(pw_m)

  Collect all the values above the diagonal in a square matrix.

  Parameters: | pw_m (2-D array) – symmetric square matrix
  Returns: | raveled list of ‘unique’ values without diagonal
  Return type: | list

`biskit.mathUtils.` `arrayEqual`(a, b)

  Compare 2 arrays or lists of numbers for equality.

  Parameters: | a (array / list) – first array (multi-dimensional is supported) b (array / list) – second array (multi-dimensional is supported)
  Returns: | 1 if array/list a equals array/list b
  Return type: | 1|0

`biskit.mathUtils.` `pairwiseDistances`(u, v)

  Pairwise distances between two arrays.

  Parameters: | u (array) – first array v (array) – second array
  Returns: | array( len(u) x len(v) ) of double
  Return type: | array

`biskit.mathUtils.` `randomMask`(nOnes, length)

  Create random array of given lenght and number of ones.

  Parameters: | nOnes (int) – number of ones length (int) – lenght of array
  Returns: | array with ones and zeros
  Return type: | array( 1|0 )

`biskit.mathUtils.` `random2DArray`(matrix, ranNr=1, mask=None)

  Create randomized 2D array containing ones and zeros.

  Parameters: | matrix (2D array) – matrix to randomize mask (list(1|0)) – mask OR None (default: None) ranNr (integer) – number of matricies to add up (default: 1)
  Returns: | 2D array or |ranNr| added contact matricies

  :rtype:2D array

  Raises: | MathUtilError – if mask does not fit matrix

`biskit.mathUtils.` `runningAverage`(x, interval=2, preserve_boundaries=0)

  Running average (smoothing) over a given data window.

  Parameters: | x (list of int/float) – data interval (int) – window size C{ (-(interval-1)/2 to +(interval-1)/2) } (default: 2) preserve_boundaries (0|1) – shrink window at edges to keep original start and end value (default: 0)
  Returns: | list of floats
  Return type: | [ float ]

`biskit.mathUtils.` `area`(curve, start=0.0, stop=1.0)

  Numerically add up the area under the given curve. The curve is a 2-D array or list of tupples. The x-axis is the first column of this array (curve[:,0]). (originally taken from biskit.Statistics.ROCalyzer)

  Parameters: | curve ([ (y,x), ] or N0.array) – a list of x,y coordinates start (float) – lower boundary (in x) (default: 0.0) stop (float) – upper boundary (in x) (default: 1.0)
  Returns: | the area underneath the curve between start and stop.
  Return type: | float

`biskit.mathUtils.` `packBinaryMatrix`(cm)

  Compress sparse array of 0 and ones to list of one-positions (space saving function, upack with `unpackBinaryMatrix`).

  Parameters: | cm (2D array) – X by Y array of int
  Returns: | {‘shape’:(X,Y), ‘nonzero’:[int] }
  Return type: | dict

`biskit.mathUtils.` `unpackBinaryMatrix`(pcm, raveled=0)

  Uncompress array of 0 and 1 that was compressed with `packBinaryMatrix`.

  Parameters: | pcm (dict) – {‘shape’:(X,Y,..), ‘nonzero’:[int]} raveled (1|0) – return raveled (default: 0)
  Returns: | N0.array(X by Y by ..) of int
  Return type: | 2D array

`biskit.mathUtils.` `matrixToList`(cm)

  Convert matrix into standard python list remembering the dimensions. Unpack with `listToMatrix`.

  Note: Not used right now.

  Parameters: | cm (2D array) – array of int
  Returns: | {‘shape’:(int,..), ‘lst’:[..] }
  Return type: | dict

`biskit.mathUtils.` `listToMatrix`(lcm)

  Convert result of `matrixToList` back into Numeric array

  Note: Not used right now.

  Parameters: | lcm (dict) – {‘shape’:(int,..), ‘lst’:[..] }
  Returns: | array
  Return type: |

`biskit.mathUtils.` `eulerRotation`(alpha, beta, gamma)
  Builds a rotation matrix from successive rotations:
    1. rotation about y-axis by angle alpha
    2. rotation about x-axis by angle beta
    3. rotation about z-axis by angle gamma

  Written by Michael Habeck.

  Parameters: | alpha (float) – euler angle S{alpha} beta (float) – euler angle S{beta} gamma (float) – euler angle S{gamma}
  Returns: | 3 x 3 array of float
  Return type: | array

`biskit.mathUtils.` `randomRotation`()

  Get random rotation matrix.

  Written by Michael Habeck.

  Returns: | 3 x 3 array of float
  Return type: | array

`biskit.mathUtils.` `intersection`(a, b, optimize=1)

  Intersection of the two lists (i.e. all values common to both two lists). C{ intersection( [any], [any] ) -> [any] }

  Parameters: | a ([any]) – first list b ([any]) – second list optimize (1|0) – result is sorted like the shorter of the two lists (default: 1)
  Returns: | list
  Return type: | [any]

`biskit.mathUtils.` `nonredundant`(l)

  All members of a list without duplicates C{ noredundant( [any] ) -> [any] }

  Parameters: | l ([any]) – list
  Returns: | list
  Return type: | [any]

`biskit.mathUtils.` `union`(a, b)

  Union of two lists (without duplicates) C{ union( [any], [any] ) -> [any] }

  Parameters: | a ([any]) – first list b ([any]) – second list
  Returns: | list
  Return type: | [any]

`biskit.mathUtils.` `difference`(a, b)

  All members of a that are not in b C{ difference([any], [any]) -> [any] }

  Parameters: | a ([any]) – first list b ([any]) – second list
  Returns: | list
  Return type: | [any]

`biskit.mathUtils.` `removeFromList`(l, v, all=1)

  Remove all or first occurrence(s) of v from l. C{ removeFromList( l, v, [all=1] ) }

  Parameters: | l ([ any ]) – list v (any or [ any ]) – remove these values all (0|1) – remove all occurrences (1) or only first one (0) (default: 1)
  Returns: | list
  Return type: | [any]

`biskit.mathUtils.` `randomRange`(start, stop, n)

  Creates a set of n unique integers randomly distributed between start and stop.

  Parameters: | start (int) – minimal index stop (int) – 1+maximal index n (int) – number of indices
  Returns: | set of unique integers evenly distributed between start and stop
  Return type: | [int]

`biskit.mathUtils.` `linfit`(x, y)

  Calculate linear least-square fit to the points given by x and y. see U{http://mathworld.wolfram.com/LeastSquaresFitting.html}

  Parameters: | x ([ float ]) – x-data y ([ float ]) – y-data
  Returns: | m, n, r^2 (slope, intersection, corr. coefficient)
  Return type: | float, float, float
  Raises: | BiskitError – if x and y have different number of elements

`biskit.mathUtils.` `cartesianToPolar`(xyz)

  Convert cartesian coordinate array to polar coordinate array: C{ x,y,z -> r, S{theta}, S{phi} }

  Parameters: | xyz (array) – array of cartesian coordinates (x, y, z)
  Returns: | array of polar coordinates (r, theta, phi)
  Return type: | array

`biskit.mathUtils.` `polarToCartesian`(rtp)

  Convert polar coordinate array to cartesian coordinate array: C{ r, S{theta}, S{phi} -> x,y,z }

  Parameters: | rtp (array) – array of cartesian coordinates (r, theta, phi)
  Returns: | array of cartesian coordinates (x, y, z)
  Return type: | array

`biskit.mathUtils.` `projectOnSphere`(xyz, radius=None, center=None)

  Project the coordinates xyz on a sphere with a given radius around a given center.

  Parameters: | xyz (array N x 3 of float) – cartesian coordinates radius (float) – radius of target sphere, if not provided the maximal distance to center will be used (default: None) center (array 0 x 3 of float) – center of the sphere, if not given the average of xyz will be assigned to the center (default: None)
  Returns: | array of cartesian coordinates (x, y, z)
  Return type: | array

`biskit.mathUtils.` `rotateAxis`(theta, vector)

  Calculate a left multiplying rotation matrix that rotates theta rad around vector.

  Taken from: http://osdir.com/ml/python.bio.devel/2008-09/msg00084.html

  Example:

      >>> m=rotateAxis(pi, N0.array([1,0,0]))

  Parameters: | theta (float) – the rotation angle vector (`Vector`) – the rotation axis
  Returns: | The rotation matrix, a 3x3 Numeric array.

`biskit.mathUtils.` `cbrt`(x)

  cubic root. Author: Victor Gil.

`biskit.mathUtils.` `cartesian2D`(r, w, deg=0)

  Convert from polar (r,w) to rectangular (x,y) x = r cos(w) y = r sin(w) Author: Victor Gil

`biskit.mathUtils.` `polar2D`(x, y, deg=0)

  Convert from rectangular (x,y) to polar (r,w) r = sqrt(x^2 + y^2) w = arctan(y/x) = [-pi,pi] = [-180,180]

  Author: Victor Gil

`biskit.mathUtils.` `quadratic`(a, b, c=None)

  x^2 + ax + b = 0 (or ax^2 + bx + c = 0) By substituting x = y-t and t = a/2, the equation reduces to y^2 + (b-t^2) = 0 which has easy solution y = +/- sqrt(t^2-b)

  Author: Victor Gil

`biskit.mathUtils.` `cubic`(a, b, c, d=None)

  x^3 + ax^2 + bx + c = 0 (or ax^3 + bx^2 + cx + d = 0) With substitution x = y-t and t = a/3, the cubic equation reduces to

  > y^3 + py + q = 0,

  where p = b-3t^2 and q = c-bt+2t^3. Then, one real root y1 = u+v can be determined by solving

  > w^2 + qw - (p/3)^3 = 0

  where w = u^3, v^3. From Vieta’s theorem,
    y1 + y2 + y3 = 0 y1 y2 + y1 y3 + y2 y3 = p y1 y2 y3 = -q,
  the other two (real or complex) roots can be obtained by solving
    y^2 + (y1)y + (p+y1^2) = 0

  Author: Victor Gil

`biskit.mathUtils.` `outliers`(a, z=5, it=5)

  Iterative detection of outliers in a set of numeric values. Requirement: len(a) > 0; outlier detection is only performed if len(a)>2

  Parameters: | a ([ float ]) – array or list of values z (float) – z-score threshold for iterative refinement of median and SD it (int) – maximum number of iterations
  Returns: | outlier mask, median and standard deviation of last iteration
  Return type: | N0.array( int ), float, float