pygimli.utils¶

Overview¶

Functions

GKtoUTM(ea[, no, zone, gk, gkzone])	Transform any Gauss-Krueger to UTM autodetect GK zone from offset.
boxprint(s[, width, sym])	Print string centered in a box.
chi2(a, b, err[, trans])	Return chi square value.
computeInverseRootMatrix(CM[, thrsh, verbose])	Compute inverse square root (C^{-0.5} of matrix.
convertCRSIndex2Map(rowIdx, colPtr)	Converts CRS indices to uncompressed indices (row, col).
covarianceMatrix(mesh[, nodes])	Geostatistical covariance matrix (cell or node) for given mesh.
createDateTimeString([now])	Return datetime as string (e.g.
createResultFolder(subfolder[, now])	Create a result Folder.
createfolders(foldername_list)	Create the folder structure specified by the list.
cumDist(p)	The progressive, i.e., cumulative length for a path p.
diff(v)	Calculate approximate derivative.
dist(p[, c])	Calculate the distance for each position in p relative to pos c(x,y,z).
filterIndex(seq, idx)	TODO DOCUMENTME.
filterLinesByCommentStr(lines[, comment_str])	Filter all lines from a file.readlines output which begins with one of the symbols in the comment_str.
findNearest(x, y, xp, yp[, radius])	TODO DOCUMENTME.
findUTMZone(lon, lat)	Find utm zone for lon and lat values.
generateGeostatisticalModel(mesh, **kwargs)	Generate geostatistical model (cell or node) for given mesh.
getIndex(seq, f)	TODO DOCUMENTME.
getProjection(name[, ref])	Syntactic sugar to get some default Projections.
getSavePath([folder, subfolder, now])	TODO.
getUTMProjection(zone[, ellps])	Create and return the current coordinate projection.
gmat2numpy(mat)	Convert pygimli matrix into numpy.array.
grange(start, end[, dx, n, log])	Create array with possible increasing spacing.
hankelFC(order)	Filter coefficients for Hankel transformation.
interpExtrap(x, xp, yp)	numpy.interp interpolation function extended by linear extrapolation.
interperc(a[, trimval, islog, bins])	Return symmetric interpercentiles for alpha-trim outliers, e.g.
inthist(a, vals[, bins, islog])	Return point of integral (cumulative) histogram, e.g.
iterateBounds(inv[, dchi2, maxiter, change])	Find parameter bounds by iterating model parameter.
logDropTol(p[, droptol])	Create logarithmic scaled copy of p.
modCovar(inv)	Formal model covariance matrix (MCM) from inversion.
nanrms(v[, axis])	Compute the root mean square excluding nan values.
niceLogspace(vMin, vMax[, nDec])	Create nice logarithmic space from the next decade lower to vMin to decade larger then vMax.
num2str(a[, fmtstr])	List of strings (deprecated, for backward-compatibility).
numpy2gmat(nmat)	Convert numpy.array into pygimli RMatrix.
rand(n[, minVal, maxVal])	Create RVector of length n with normally distributed random numbers.
randN(n[, minVal, maxVal])	Create RVector of length n with normally distributed random numbers.
readGPX(fileName)	Extract GPS Waypoint from GPS Exchange Format (GPX).
rms(v[, axis])	Compute the root mean square.
rmsWithErr(a, b, err[, errtol])	Compute (abs-)root mean square of values with error above a threshold
rmswitherr(a, b, err[, errtol])	Compute (abs-)root mean square of values with error above a threshold
rndig(a[, ndig])	Round float using a number of counting digits.
saveResult(fname, data[, rrms, chi2, mode])	Save rms/chi2 results into filename.
sparseMatrix2Array(matrix[, indices, getInCRS])	Extract indices and value from sparse matrix (SparseMap or CRS)
sparseMatrix2coo(A[, rowOffset, colOffset])	Convert SparseMatrix to scipy.coo_matrix.
sparseMatrix2csr(A)	Convert SparseMatrix to scipy.csr_matrix.
trimDocString(docstring)	Return properly formatted docstring.
unicodeToAscii(text)	TODO DOCUMENTME.
unique(a)	Return list of unique elements ever seen with preserving order.
uniqueAndSum(indices, to_sum[, …])	Summs double values found by indices in a various number of arrays.
unique_everseen(iterable[, key])	Return iterator of unique elements ever seen with preserving order.
unique_rows(array)	Return unique rows in a 2D array.

Classes

ProgressBar(its[, width, sign])

Animated text-based progressbar.

Functions¶

GKtoUTM

pygimli.utils.GKtoUTM(ea, no=None, zone=32, gk=None, gkzone=None)[source]¶

Transform any Gauss-Krueger to UTM autodetect GK zone from offset.

boxprint

pygimli.utils.boxprint(s, width=80, sym='#')[source]¶

Print string centered in a box.

Examples

>>> from pygimli.utils import boxprint
>>> boxprint("This is centered in a box.", width=40, sym='+')
++++++++++++++++++++++++++++++++++++++++
+      This is centered in a box.      +
++++++++++++++++++++++++++++++++++++++++

chi2

pygimli.utils.chi2(a, b, err, trans=None)[source]¶

Return chi square value.

computeInverseRootMatrix

pygimli.utils.computeInverseRootMatrix(CM, thrsh=0.001, verbose=False)[source]¶

Compute inverse square root (C^{-0.5} of matrix.

convertCRSIndex2Map

pygimli.utils.convertCRSIndex2Map(rowIdx, colPtr)[source]¶

Converts CRS indices to uncompressed indices (row, col).

covarianceMatrix

pygimli.utils.covarianceMatrix(mesh, nodes=False, **kwargs)[source]¶

Geostatistical covariance matrix (cell or node) for given mesh.

Parameters:	mesh : gimliapi:GIMLI::Mesh Mesh nodes : bool [False] use node positions, otherwise (default) cell centers are used **kwargs I : float or list of floats correlation lengths (range) in individual directions dip : float dip angle (in degree) of major axis (I[0]) strike : float strike angle (for 3D)
Returns:	Cm : np.array (square matrix of size cellCount/nodeCount) covariance matrix

createDateTimeString

pygimli.utils.createDateTimeString(now=None)[source]¶

Return datetime as string (e.g. for saving results).

createResultFolder

pygimli.utils.createResultFolder(subfolder, now=None)[source]¶

Create a result Folder.

createfolders

pygimli.utils.createfolders(foldername_list)[source]¶

Create the folder structure specified by the list.

cumDist

pygimli.utils.cumDist(p)[source]¶

The progressive, i.e., cumulative length for a path p.

d = [0.0, d[0]+ | p[1]-p[0] |, d[1] + | p[2]-p[1] | + …]

Parameters:	p : ndarray(N,2) | ndarray(N,3) | pg.R3Vector Position array
Returns:	d : ndarray(N) Distance array

Examples

>>> import pygimli as pg
>>> from pygimli.utils import cumDist
>>> import numpy as np
>>> p = pg.R3Vector(4)
>>> p[0] = [0.0, 0.0]
>>> p[1] = [0.0, 1.0]
>>> p[2] = [0.0, 1.0]
>>> p[3] = [0.0, 0.0]
>>> print(cumDist(p))
[0. 1. 1. 2.]

diff

pygimli.utils.diff(v)[source]¶

Calculate approximate derivative.

Calculate approximate derivative from v as d = [v_1-v_0, v2-v_1, …]

Parameters:	v : array(N) | pg.R3Vector(N) Array of double values or positions
Returns:	d : [type(v)](N-1) | derivative array

Examples

>>> import pygimli as pg
>>> from pygimli.utils import diff
>>> p = pg.R3Vector(4)
>>> p[0] = [0.0, 0.0]
>>> p[1] = [0.0, 1.0]
>>> print(diff(p)[0])
RVector3: (0.0, 1.0, 0.0)
>>> print(diff(p)[1])
RVector3: (0.0, -1.0, 0.0)
>>> print(diff(p)[2])
RVector3: (0.0, 0.0, 0.0)
>>> p = pg.RVector(3)
>>> p[0] = 0.0
>>> p[1] = 1.0
>>> p[2] = 2.0
>>> print(diff(p))
2 [1.0, 1.0]

dist

pygimli.utils.dist(p, c=None)[source]¶

Calculate the distance for each position in p relative to pos c(x,y,z).

Parameters:	p : ndarray(N,2) | ndarray(N,3) | pg.R3Vector Position array c : [x,y,z] [None] relative origin. default = [0, 0, 0]
Returns:	d : ndarray(N) Distance array

Examples

>>> import pygimli as pg
>>> from pygimli.utils import dist
>>> import numpy as np
>>> p = pg.R3Vector(4)
>>> p[0] = [0.0, 0.0]
>>> p[1] = [0.0, 1.0]
>>> print(dist(p))
[0. 1. 0. 0.]
>>> x = pg.RVector(4, 0)
>>> y = pg.RVector(4, 1)
>>> print(dist(np.array([x, y]).T))
[1. 1. 1. 1.]

filterIndex

pygimli.utils.filterIndex(seq, idx)[source]¶

TODO DOCUMENTME.

filterLinesByCommentStr

pygimli.utils.filterLinesByCommentStr(lines, comment_str='#')[source]¶

Filter all lines from a file.readlines output which begins with one of the symbols in the comment_str.

findNearest

pygimli.utils.findNearest(x, y, xp, yp, radius=-1)[source]¶

TODO DOCUMENTME.

findUTMZone

pygimli.utils.findUTMZone(lon, lat)[source]¶

Find utm zone for lon and lat values.

lon -180 – -174 -> 1 … 174 – 180 -> 60 lat < 0 hemisphere = S, > 0 hemisphere = N

Parameters:	lon : float lat : float
Returns:	str : zone + hemisphere

generateGeostatisticalModel

pygimli.utils.generateGeostatisticalModel(mesh, **kwargs)[source]¶

Generate geostatistical model (cell or node) for given mesh.

Parameters:	mesh : gimliapi:GIMLI::Mesh Mesh nodes : bool [False] use node positions, otherwise (default) cell centers are used **kwargs I : float or list of floats correlation lengths (range) in individual directions dip : float dip angle of major axis (I[0]) strike : float strike angle (for 3D)
Returns:	res : np.array of size cellCount or nodeCount (nodes=True)

getIndex

pygimli.utils.getIndex(seq, f)[source]¶

TODO DOCUMENTME.

getProjection

pygimli.utils.getProjection(name, ref=None, **kwargs)[source]¶

Syntactic sugar to get some default Projections. https://svn.oss.deltares.nl/repos/openearthtools//websites/trunk/python/applications/osm2hydro/dist/win32/osm2hydro/pyproj-1.9.0-py2.7-win32.egg/pyproj/data/epsg

getSavePath

pygimli.utils.getSavePath(folder=None, subfolder='', now=None)[source]¶

TODO.

getUTMProjection

pygimli.utils.getUTMProjection(zone, ellps='WGS84')[source]¶

Create and return the current coordinate projection.

This is a proxy for pyproj.

Parameters:	utmZone : str Zone for for UTM ellipsoid : str ellipsoid based on [‘wgs84’]
Returns:	Pyproj Projection

gmat2numpy

pygimli.utils.gmat2numpy(mat)[source]¶

Convert pygimli matrix into numpy.array.

TODO implement correct rval

grange

pygimli.utils.grange(start, end, dx=0, n=0, log=False)[source]¶

Create array with possible increasing spacing.

Create either array from start step-wise filled with dx until end reached [start, end] (like np.array with defined end). Fill the array from start to end with n steps. [start, end] (like np.linespace) Fill the array from start to end with n steps but logarithmic increasing, dx will be ignored.

Parameters:	start: float First value of the resulting array end: float Last value of the resulting array dx: float Linear step length, n will be ignored n: int Amount of steps log: bool
Returns:	ret: :gimliapi:`GIMLI::RVector` Return resulting array

Examples

>>> from pygimli.utils import grange
>>> v1 = grange(start=0, end=10, dx=3)
>>> v2 = grange(start=0, end=10, n=3)
>>> print(v1)
4 [0.0, 3.0, 6.0, 9.0]
>>> print(v2)
3 [0.0, 5.0, 10.0]

Examples using pygimli.utils.grange

hankelFC

pygimli.utils.hankelFC(order)[source]¶

Filter coefficients for Hankel transformation.

10 data points per decade.

DOCUMENTME .. Author RUB?

Parameters:	order : int order=1: NY=+0.5 (SIN) order=2: NY=-0.5 (COS) order=3: NY=0.0 (J0) order=4: NY=1.0 (J1)
Returns:	fc : np.array() Filter coefficients nc0 : int fc[nc0] refers to zero argument

interpExtrap

pygimli.utils.interpExtrap(x, xp, yp)[source]¶

numpy.interp interpolation function extended by linear extrapolation.

interperc

pygimli.utils.interperc(a, trimval=3.0, islog=False, bins=None)[source]¶

Return symmetric interpercentiles for alpha-trim outliers, e.g. interperc(a, 3) returns range of inner 94% (useful for colorscales).

inthist

pygimli.utils.inthist(a, vals, bins=None, islog=False)[source]¶

Return point of integral (cumulative) histogram, e.g. inthist(a, [25, 50, 75]) provides quartiles and median of an array

iterateBounds

pygimli.utils.iterateBounds(inv, dchi2=0.5, maxiter=100, change=1.02)[source]¶

Find parameter bounds by iterating model parameter.

Find parameter bounds by iterating model parameter until error bound is reached

Parameters:	inv : gimli inversion object dchi2 : allowed variation of chi^2 values [0.5] maxiter : maximum iteration number for parameter iteration [100] change: changing factor of parameters [1.02, i.e. 2%]

logDropTol

pygimli.utils.logDropTol(p, droptol=0.001)[source]¶

Create logarithmic scaled copy of p.

Examples

>>> from pygimli.utils import logDropTol
>>> x = logDropTol((-10, -1, 0, 1, 100))
>>> print(x.array())
[-4. -3.  0.  3.  5.]

modCovar

pygimli.utils.modCovar(inv)[source]¶

Formal model covariance matrix (MCM) from inversion.

var, MCMs = modCovar(inv)

Parameters:	inv : pygimli inversion object
Returns:	var : variances (inverse square roots of MCM matrix) MCMs : scaled MCM (such that diagonals are 1.0)

Examples

>>> # import pygimli as pg
>>> # import matplotlib.pyplot as plt
>>> # from matplotlib.cm import bwr
>>> # INV = pg.RInversion(data, f)
>>> # par = INV.run()
>>> # var, MCM = modCovar(INV)
>>> # i = plt.imshow(MCM, interpolation='nearest',
>>> #                 cmap=bwr, vmin=-1, vmax=1)
>>> # plt.colorbar(i)

nanrms

pygimli.utils.nanrms(v, axis=None)[source]¶

Compute the root mean square excluding nan values.

niceLogspace

pygimli.utils.niceLogspace(vMin, vMax, nDec=10)[source]¶

Create nice logarithmic space from the next decade lower to vMin to decade larger then vMax.

Parameters:	vMin : float lower limit need to be > 0 vMax : float upper limit need to be >= vMin nDec : int Amount of logarithmic equidistant steps for one decade

Examples

>>> from pygimli.utils import niceLogspace
>>> v1 = niceLogspace(vMin=0.1, vMax=0.1, nDec=1)
>>> print(v1)
[0.1 1. ]
>>> v1 = niceLogspace(vMin=0.09, vMax=0.11, nDec=1)
>>> print(v1)
[0.01 0.1  1.  ]
>>> v1 = niceLogspace(vMin=0.09, vMax=0.11, nDec=10)
>>> print(len(v1))
21
>>> print(v1)
[0.01       0.01258925 0.01584893 0.01995262 0.02511886 0.03162278
 0.03981072 0.05011872 0.06309573 0.07943282 0.1        0.12589254
 0.15848932 0.19952623 0.25118864 0.31622777 0.39810717 0.50118723
 0.63095734 0.79432823 1.        ]

num2str

pygimli.utils.num2str(a, fmtstr='%g')[source]¶

List of strings (deprecated, for backward-compatibility).

numpy2gmat

pygimli.utils.numpy2gmat(nmat)[source]¶

Convert numpy.array into pygimli RMatrix.

TODO implement correct rval

rand

pygimli.utils.rand(n, minVal=0.0, maxVal=1.0)[source]¶

Create RVector of length n with normally distributed random numbers.

randN

pygimli.utils.randN(n, minVal=0.0, maxVal=1.0)[source]¶

Create RVector of length n with normally distributed random numbers.

readGPX

pygimli.utils.readGPX(fileName)[source]¶

Extract GPS Waypoint from GPS Exchange Format (GPX).

Currently only simple waypoint extraction is supported.

<gpx version=”1.0” creator=”creator”>

<metadata> <name>Name</name> </metadata> <wpt lat=”51.” lon=”11.”> <name>optional</name> <time>optional</time> <description>optional</description> </wpt>

</gpx>

rms

pygimli.utils.rms(v, axis=None)[source]¶

Compute the root mean square.

rmsWithErr

pygimli.utils.rmsWithErr(a, b, err, errtol=1)[source]¶

Compute (abs-)root mean square of values with error above a threshold

rmswitherr

pygimli.utils.rmswitherr(a, b, err, errtol=1)¶

Compute (abs-)root mean square of values with error above a threshold

rndig

pygimli.utils.rndig(a, ndig=3)[source]¶

Round float using a number of counting digits.

saveResult

pygimli.utils.saveResult(fname, data, rrms=None, chi2=None, mode='w')[source]¶

Save rms/chi2 results into filename.

sparseMatrix2Array

pygimli.utils.sparseMatrix2Array(matrix, indices=True, getInCRS=True)[source]¶

Extract indices and value from sparse matrix (SparseMap or CRS)

Get python Arrays from SparseMatrix or SparseMapMatrix in either CRS convention (row index, column Start_End, values) or row index, column index, values.

Parameters:	matrix: pg.SparseMapMatrix or pg.SparseMatrix Input matrix to be transformed to numpy arrays. indices: boolean (True) Decides weather the indices of the matrix will be returned or not. getInCSR: boolean (True) If returned, the indices can have the format of a compressed row storage (CSR), the default or uncompressed lists with column and row indices.
Returns:	vals: numpy.ndarray Entries of the matrix. indices: list, list Optional. Returns additional array with the indices for reconstructing the matrix in the defined format.

sparseMatrix2coo

pygimli.utils.sparseMatrix2coo(A, rowOffset=0, colOffset=0)[source]¶

Convert SparseMatrix to scipy.coo_matrix.

Parameters:	A: pg.SparseMapMatrix | pg.SparseMatrix Matrix to convert from.
Returns:	mat: scipy.coo_matrix Matrix to convert into.

sparseMatrix2csr

pygimli.utils.sparseMatrix2csr(A)[source]¶

Convert SparseMatrix to scipy.csr_matrix.

Compressed Sparse Row matrix, i.e., Compressed Row Storage (CRS)

Parameters:	A: pg.SparseMapMatrix | pg.SparseMatrix Matrix to convert from.
Returns:	mat: scipy.csr_matrix Matrix to convert into.

trimDocString

pygimli.utils.trimDocString(docstring)[source]¶

Return properly formatted docstring.

From: https://www.python.org/dev/peps/pep-0257/

Examples

>>> from pygimli.utils import trimDocString
>>> docstring = '    This is a string with indention and whitespace.   '
>>> trimDocString(docstring).replace('with', 'without')
'This is a string without indention and whitespace.'

unicodeToAscii

pygimli.utils.unicodeToAscii(text)[source]¶

TODO DOCUMENTME.

unique

pygimli.utils.unique(a)[source]¶

Return list of unique elements ever seen with preserving order.

See also

unique_everseen, unique_rows

Examples

>>> from pygimli.utils import unique
>>> unique((1,1,2,2,3,1))
[1, 2, 3]

uniqueAndSum

pygimli.utils.uniqueAndSum(indices, to_sum, return_index=False, verbose=False)[source]¶

Summs double values found by indices in a various number of arrays.

Returns the sorted unique elements of a column_stacked array of indices. Another column_stacked array is returned with values at the unique indices, while values at double indices are properly summed.

Parameters:	ar : array_like Input array. This will be flattened if it is not already 1-D. to_sum : array_like Input array to be summed over axis 0. Other exsisting axes will be broadcasted remain untouched. return_index : bool, optional If True, also return the indices of ar (along the specified axis, if provided, or in the flattened array) that result in the unique array.
Returns:	unique : ndarray The sorted unique values. summed_array : ndarray The summed array, whereas all values for a specific index is the sum over all corresponding nonunique values. unique_indices : ndarray, optional The indices of the first occurrences of the unique values in the original array. Only provided if return_index is True.

unique_everseen

pygimli.utils.unique_everseen(iterable, key=None)[source]¶

Return iterator of unique elements ever seen with preserving order.

Return iterator of unique elements ever seen with preserving order.

From: http://docs.python.org/library/itertools.html#recipes

See also

unique, unique_rows

Examples

>>> from pygimli.utils import unique_everseen
>>> s1 = 'AAAABBBCCDAABBB'
>>> s2 = 'ABBCcAD'
>>> list(unique_everseen(s1))
['A', 'B', 'C', 'D']
>>> list(unique_everseen(s2, key=str.lower))
['A', 'B', 'C', 'D']

unique_rows

pygimli.utils.unique_rows(array)[source]¶

Return unique rows in a 2D array.

Examples

>>> from pygimli.utils import unique_rows
>>> import numpy as np
>>> A = np.array(([1,2,3],[3,2,1],[1,2,3]))
>>> unique_rows(A)
array([[1, 2, 3],
       [3, 2, 1]])

Classes¶

ProgressBar

class pygimli.utils.ProgressBar(its, width=80, sign=':')[source]¶

Animated text-based progressbar.

Animated text-based progressbar for intensive loops. Should work in the console and in the IPython Notebook.

TODO:

• optional: ‘estimated time’ instead of ‘x of y complete’

Parameters:	its : int Number of iterations of the process. width : int Width of the ProgressBar, default is 80. sign : str Sign used to fill the bar.

[+++++++++++ 30% ] 6 of 20 complete

Methods

__call__(it[, msg])	Call self as a function.
update(iteration[, msg])	Update ProgressBar by iteration number starting at 0 with optional message.

__init__(its, width=80, sign=':')[source]¶

Constructor.

update(iteration, msg='')[source]¶

Update ProgressBar by iteration number starting at 0 with optional message.