Miscellaneous Utilities (fatiando.utils)

Miscellaneous utility functions and classes.

Mathematical functions

Unit conversion

Coordinate system conversions

Others

  • fromimage: Load a matrix from an image file
  • contaminate: Contaminate a vector with pseudo-random Gaussian noise
  • dircos: Get the 3 coordinates of a unit vector
  • ang2vec: Convert intensity, inclination and declination to a 3-component vector
  • vecnorm: Get the norm of a vector or list of vectors
  • vecmean: Take the mean array out of a list of arrays
  • vecstd: Take the standard deviation array out of a list of arrays
  • SparseList: Store only non-zero elements on an immutable list
  • sec2hms: Convert seconds to hours, minutes, and seconds
  • sec2year: Convert seconds to Julian years
  • year2sec: Convert Julian years to seconds

class fatiando.utils.SparseList(size, elements=None)[source]

Bases: object

Store only non-zero elements on an immutable list.

Can iterate over and access elements just like if it were a list.

Parameters:

  • size
    : int

    Size of the list.

  • elements
    : dict

    Dictionary used to initialize the list. Keys are the index of the elements and values are their respective values.

Example:

>>> l = SparseList(5)
>>> l[3] = 42.0
>>> print len(l)
5
>>> print l[1], l[3]
0.0 42.0
>>> l[1] += 3.0
>>> for i in l:
...     print i,
0.0 3.0 0.0 42.0 0.0
>>> l2 = SparseList(4, elements={1:3.2, 3:2.8})
>>> for i in l2:
...     print i,
0.0 3.2 0.0 2.8
fatiando.utils.ang2vec(intensity, inc, dec)[source]

Convert intensity, inclination and declination to a 3-component vector

Note

Coordinate system is assumed to be x->North, y->East, z->Down. Inclination is positive down and declination is measured with respect to x (North).

Parameter:

  • intensity
    : float or array

    The intensity (norm) of the vector

  • inc
    : float

    The inclination of the vector (in degrees)

  • dec
    : float

    The declination of the vector (in degrees)

Returns:

  • vec
    : array = [x, y, z]

    The vector

Examples:

>>> import numpy
>>> print ang2vec(3, 45, 45)
[ 1.5         1.5         2.12132034]
>>> print ang2vec(numpy.arange(4), 45, 45)
[[ 0.          0.          0.        ]
 [ 0.5         0.5         0.70710678]
 [ 1.          1.          1.41421356]
 [ 1.5         1.5         2.12132034]]
fatiando.utils.contaminate(data, stddev, percent=False, return_stddev=False, seed=None)[source]

Add pseudorandom gaussian noise to an array.

Noise added is normally distributed with zero mean.

Parameters:

  • data
    : array or list of arrays

    Data to contaminate

  • stddev
    : float or list of floats

    Standard deviation of the Gaussian noise that will be added to data

  • percent
    : True or False

    If True, will consider stddev as a decimal percentage and the standard deviation of the Gaussian noise will be this percentage of the maximum absolute value of data

  • return_stddev
    : True or False

    If True, will return also the standard deviation used to contaminate data

  • seed
    : None or int

    Seed used to generate the pseudo-random numbers. If None, will use a different seed every time. Use the same seed to generate the same random sequence to contaminate the data.

Returns:

if return_stddev is False:

  • contam
    : array or list of arrays

    The contaminated data array

else:

  • results
    : list = [contam, stddev]

    The contaminated data array and the standard deviation used to contaminate it.

Examples:

>>> import numpy as np
>>> data = np.ones(5)
>>> noisy = contaminate(data, 0.1, seed=0)
>>> print noisy
[ 1.03137726  0.89498775  0.95284582  1.07906135  1.04172782]
>>> noisy, std = contaminate(data, 0.05, seed=0, percent=True,
...                          return_stddev=True)
>>> print std
0.05
>>> print noisy
[ 1.01568863  0.94749387  0.97642291  1.03953067  1.02086391]
>>> data = [np.zeros(5), np.ones(3)]
>>> noisy = contaminate(data, [0.1, 0.2], seed=0)
>>> print noisy[0]
[ 0.03137726 -0.10501225 -0.04715418  0.07906135  0.04172782]
>>> print noisy[1]
[ 0.81644754  1.20192079  0.98163167]
fatiando.utils.dircos(inc, dec)[source]

Returns the 3 coordinates of a unit vector given its inclination and declination.

Note

Coordinate system is assumed to be x->North, y->East, z->Down. Inclination is positive down and declination is measured with respect to x (North).

Parameter:

  • inc
    : float

    The inclination of the vector (in degrees)

  • dec
    : float

    The declination of the vector (in degrees)

Returns:

  • vect
    : list = [x, y, z]

    The unit vector

fatiando.utils.eotvos2si(value)[source]

Convert a value from Eotvos to SI units.

Parameters:

  • value
    : number or array

    The value in Eotvos

Returns:

  • value
    : number or array

    The value in SI

fatiando.utils.fromimage(fname, ranges=None, shape=None)[source]

Load an array of normalized gray-scale values from an image file.

The values will be in the range [0, 1]. The shape of the array is the shape of the image (ny, nx), i.e., number of pixels in vertical (height) and horizontal (width) dimensions.

Parameters:

  • fname
    : str

    Name of the image file

  • ranges
    : [vmax, vmin] = floats

    If not None, will set the gray-scale values to this range.

  • shape
    : (ny, nx)

    If not None, will interpolate the array to match this new shape

Returns:

  • values
    : 2d-array

    The array of gray-scale values

fatiando.utils.gaussian(x, mean, std)[source]

Non-normalized Gaussian function

\[G(x,\bar{x},\sigma) = \exp\left(-\frac{(x-\bar{x})^2}{\sigma^2} \right)\]

Parameters:

  • x
    : float or array

    Values at which to calculate the Gaussian function

  • mean
    : float

    The mean of the distribution \(\bar{x}\)

  • std
    : float

    The standard deviation of the distribution \(\sigma\)

Returns:

  • gauss
    : array

    Gaussian function evaluated at x

fatiando.utils.gaussian2d(x, y, sigma_x, sigma_y, x0=0, y0=0, angle=0.0)[source]

Non-normalized 2D Gaussian function

Parameters:

  • x, y
    : float or arrays

    Coordinates at which to calculate the Gaussian function

  • sigma_x, sigma_y
    : float

    Standard deviation in the x and y directions

  • x0, y0
    : float

    Coordinates of the center of the distribution

  • angle
    : float

    Rotation angle of the gaussian measure from the x axis (north) growing positive to the east (positive y axis)

Returns:

  • gauss
    : array

    Gaussian function evaluated at x, y

fatiando.utils.mgal2si(value)[source]

Convert a value from mGal to SI units.

Parameters:

  • value
    : number or array

    The value in mGal

Returns:

  • value
    : number or array

    The value in SI

fatiando.utils.normal(x, mean, std)[source]

Normal distribution.

\[N(x,\bar{x},\sigma) = \frac{1}{\sigma\sqrt{2 \pi}} \exp\left(-\frac{(x-\bar{x})^2}{\sigma^2}\right)\]

Parameters:

  • x
    : float or array

    Value at which to calculate the normal distribution

  • mean
    : float

    The mean of the distribution \(\bar{x}\)

  • std
    : float

    The standard deviation of the distribution \(\sigma\)

Returns:

  • normal
    : array

    Normal distribution evaluated at x

fatiando.utils.nt2si(value)[source]

Convert a value from nanoTesla to SI units.

Parameters:

  • value
    : number or array

    The value in nanoTesla

Returns:

  • value
    : number or array

    The value in SI

fatiando.utils.safe_diagonal(matrix)[source]

Get the diagonal of a matrix using the appropriate method.

Parameters:

  • matrix
    : 2d-array, matrix, sparse matrix

    The matrix...

Returns:

  • diag
    : 1d-array

    A numpy array with the diagonal of the matrix

fatiando.utils.safe_dot(a, b)[source]

Make the dot product using the appropriate method.

If a and b are dense, will use numpy.dot. If either is sparse (from scipy.sparse) will use the multiplication operator (i.e., *).

Parameters:

  • a, b
    : array or matrix

    The vectors/matrices to take the dot product of.

Returns:

  • prod
    : array or matrix

    The dot product of a and b

fatiando.utils.safe_inverse(matrix)[source]

Calculate the inverse of a matrix using an apropriate algorithm.

Uses the standard numpy.linalg.inv if matrix is dense. If it is sparse (from scipy.sparse) then will use scipy.sparse.linalg.inv.

Parameters:

  • matrix
    : 2d-array

    The matrix

Returns:

  • inverse
    : 2d-array

    The inverse of matrix

fatiando.utils.safe_solve(matrix, vector)[source]

Solve a linear system using an apropriate algorithm.

Uses the standard numpy.linalg.solve if both matrix and vector are dense.

If any of the two is sparse (from scipy.sparse) then will use the Conjugate Gradient Method (scipy.sparse.cgs).

Parameters:

  • matrix
    : 2d-array

    The matrix defining the linear system

  • vector
    : 1d or 2d-array

    The right-side vector of the system

Returns:

  • solution
    : 1d or 2d-array

    The solution of the linear system

fatiando.utils.sec2hms(seconds)[source]

Convert seconds into a string with hours, minutes and seconds.

Parameters:

  • seconds
    : float

    Time in seconds

Returns:

  • time
    : str

    String in the format '%dh %dm %2.5fs'

Example:

>>> print sec2hms(62.2)
0h 1m 2.20000s
>>> print sec2hms(3862.12345678)
1h 4m 22.12346s
fatiando.utils.sec2year(seconds)[source]

Convert seconds into decimal Julian years.

Julian years have 365.25 days.

Parameters:

  • seconds
    : float

    Time in seconds

Returns:

  • years
    : float

    Time in years

Example:

>>> print sec2year(31557600)
1.0
fatiando.utils.si2eotvos(value)[source]

Convert a value from SI units to Eotvos.

Parameters:

  • value
    : number or array

    The value in SI

Returns:

  • value
    : number or array

    The value in Eotvos

fatiando.utils.si2mgal(value)[source]

Convert a value from SI units to mGal.

Parameters:

  • value
    : number or array

    The value in SI

Returns:

  • value
    : number or array

    The value in mGal

fatiando.utils.si2nt(value)[source]

Convert a value from SI units to nanoTesla.

Parameters:

  • value
    : number or array

    The value in SI

Returns:

  • value
    : number or array

    The value in nanoTesla

fatiando.utils.sph2cart(lon, lat, height)[source]

Convert spherical coordinates to Cartesian geocentric coordinates.

Parameters:

  • lon, lat, height
    : floats

    Spherical coordinates. lon and lat in degrees, height in meters. height is the height above mean Earth radius.

Returns:

  • x, y, z
    : floats

    Converted Cartesian coordinates

fatiando.utils.vec2ang(vector)[source]

Convert a 3-component vector to intensity, inclination and declination.

Note

Coordinate system is assumed to be x->North, y->East, z->Down. Inclination is positive down and declination is measured with respect to x (North).

Parameter:

  • vector
    : array = [x, y, z]

    The vector

Returns:

  • [intensity, inclination, declination]
    : floats

    The intensity, inclination and declination (in degrees)

Examples:

>>> s = vec2ang([1.5, 1.5, 2.121320343559643])
>>> print "%.3f %.3f %.3f" % tuple(s)
3.000 45.000 45.000
fatiando.utils.vecmean(arrays)[source]

Take the mean array out of a list of arrays.

Parameter:

  • arrays
    : list

    List of arrays

Returns:

  • mean
    : array

    The mean of each element in the arrays

Example:

>>> print vecmean([[1, 1, 2], [2, 3, 5]])
[ 1.5  2.   3.5]
fatiando.utils.vecnorm(vectors)[source]

Get the l2 norm of each vector in a list.

Use this to get, for example, the magnetization intensity from a list of magnetization vectors.

Parameters:

  • vectors
    : list of arrays

    The vector

Returns:

  • norms
    : list

    The norms of the vectors

Examples:

>>> v = [[1, 1, 1], [2, 2, 2], [3, 3, 3]]
>>> print vecnorm(v)
[ 1.73205081  3.46410162  5.19615242]
fatiando.utils.vecstd(arrays)[source]

Take the standard deviation array out of a list of arrays.

Parameter:

  • arrays
    : list

    List of arrays

Returns:

  • std
    : array

    Standard deviation of each element in the arrays

Example:

>>> print vecstd([[1, 1, 2], [2, 3, 5]])
[ 0.5  1.   1.5]
fatiando.utils.year2sec(years)[source]

Convert decimal Julian years into seconds.

Julian years have 365.25 days.

Parameters:

  • years
    : float

    Time in years

Returns:

  • seconds
    : float

    Time in seconds

Example:

>>> print year2sec(1)
31557600.0