pygimli.utils

Useful utility functions.

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
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

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.

Contents

Navigation

Tutorial & example gallery

Quick links

Code status

  • Latest release

    • Latest release tag

  • Development version

    • Code Quality Commits since latest release



2019 - GIMLi Development Team
Created using Bootstrap, Sphinx and pyGIMLi 1.0.11+13.gf5c9f4f6 on May 16, 2019.