The fatiando package has been deprecated. Please check out the new tools in the Fatiando a Terra website: www.fatiando.org

# Miscellaneous Utilities (fatiando.utils)¶

Miscellaneous utility functions and classes.

Mathematical functions

Unit conversion

Coordinate system conversions

Others

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 = 42.0
>>> print len(l)
5
>>> print l, l
0.0 42.0
>>> l += 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.03137726 -0.10501225 -0.04715418  0.07906135  0.04172782]
>>> print noisy
[ 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