Miscellaneous Utilities (`fatiando.utils`)¶

Miscellaneous utility functions and classes.

Mathematical functions

normal
gaussian
gaussian2d
safe_solve
safe_dot
safe_diagonal
safe_inverse

Unit conversion

si2mgal
mgal2si
si2eotvos
eotvos2si
si2nt
nt2si

Coordinate system conversions

sph2cart

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

Miscellaneous Utilities (fatiando.utils)¶

Miscellaneous Utilities (`fatiando.utils`)¶