2. tools

Module which contains the functions that are supportive tools for the functions contained in the jelinekstat.py module which is the guideline of the second-order tensors statistical proposal of Jelínek (1978).

Note

  • The packages numpy, matplotlib and mplstereonet are required for using the jelinekstat.py module. All of them are downloadable from the PyPI repository.
  • The mathematical notation in this documentation is taken from the original reference Jelínek (1978).
  • Copyright (c) 2018, Universidad Nacional de Colombia, Medellín. Copyright (c) 2018, Exneyder A. Monotoya-Araque and Ludger O. Suarez-Burgoa. BSD-2-Clause or higher.
tools.dataFromFile(file)[source]

Loads the .txt file with all second-order tensors components.

Parameters:file (str) – txt file tabulated with tabular spaces as delimiter. The file is structured as a \((n \times 6)\) array, where \(n\) is the number of tensors and each row contains the vector form with the 6 components of a tensor in the following order \(t_{11}, t_{22}, t_{33}, t_{12}, t_{23}, t_{13}\).
Returns:Two elements are returned; they are described below.
  • sample (numpy.ndarray): \((n \times 6)\) array that contains the same values than the .txt file.
  • numTensors (int): Number of tensors.

Examples

>>> from jelinekstat.tools import dataFromFile
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> sample
array([[ 1.02327,  1.02946,  0.94727, -0.01495, -0.03599, -0.05574],
       [ 1.02315,  1.01803,  0.95882, -0.00924, -0.02058, -0.03151],
       [ 1.02801,  1.03572,  0.93627, -0.03029, -0.03491, -0.06088],
       [ 1.02775,  1.00633,  0.96591, -0.01635, -0.04148, -0.02006],
       [ 1.02143,  1.01775,  0.96082, -0.02798, -0.04727, -0.02384],
       [ 1.01823,  1.01203,  0.96975, -0.01126, -0.02833, -0.03649],
       [ 1.01486,  1.02067,  0.96446, -0.01046, -0.01913, -0.03864],
       [ 1.04596,  1.01133,  0.94271, -0.0166 , -0.04711, -0.03636]])
>>> numTensors
8
tools.tensorvect2matrixform(tensorVect)[source]

Converts a second order tensor from the vector form of to its matricial form.

Parameters:tensorVect (list or numpy.ndarray) – \((n \times 6)\) tensor components written as column vector with the following order \(t_{11}, t_{22}, t_{33}, t_{12}, t_{23}, t_{13}\).
Returns:\((3 \times 3)\) second-order tensor expressed as a \(3\times 3\) matrix.
Return type:(numpy.ndarray)

Examples

>>> from jelinekstat.tools import tensorvect2matrixform
>>> tensorVect = [11, 22, 33, 12, 23, 13]
>>> tensorvect2matrixform(tensorVect)
array([[11, 12, 13],
       [12, 22, 23],
       [13, 23, 33]])
tools.vector2plungetrend(vector)[source]

Converts a \(\mathbb{R}^3\) vector to the plunge \(\delta\), trend \(\delta_\mathrm{dir}\) notation used in Structural Geology and Rock Mechanics.

The \(\mathbb{R}^3\) notation is assumed to be coincident with the NED notation (i.e North, East, Nadir).

Parameters:vector (list or numpy.ndarray) – \(\left(x, y, z \right)\) vector.
Returns:\(\left(\delta, \delta_\mathrm{dir}\right)\) of the input vector in degrees.
Return type:(tuple)

Examples

>>> from jelinekstat.tools import vector2plungetrend
>>> vector = [1, 0, 0]
>>> vector2plungetrend(vector)
(0.0, 0.0)
>>> from jelinekstat.tools import vector2plungetrend
>>> vector = [0, 1, 0]
>>> vector2plungetrend(vector)
(0.0, 90.0)
>>> from jelinekstat.tools import vector2plungetrend
>>> vector = [1, 1, 1]
>>> vector2plungetrend(vector)
(35.264389682754654, 45.0)
tools.getEigSorted(matrix)[source]

Obtains eigenvalues and eigenvectors of a diagonalizable matrix. The eigenvalues are sorted descending.

Parameters:matrix (numpy.ndarray) – \((3 \times 3)\) diagonalizable matrix.
Returns:Two elements are returned; they are described below.
  • sortedEigVal (numpy.ndarray): \((3 \times 1)\) array with the eigenvalues ordered descending.
  • sortedEigVec (numpy.ndarray): \((3 \times 3)\) array with the eigenvectors, such that the column sortedEigVec[:, i] is the eigenvector corresponding to the eigenvalue sortedEigVal[i]

Examples

>>> from numpy import array
>>> from jelinekstat.tools import getEigSorted
>>> matrix = array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> sortedEigVal, sortedEigVec = getEigSorted(matrix)
>>> sortedEigVal
array([  1.61168440e+01,  -9.75918483e-16,  -1.11684397e+00])
>>> sortedEigVec
array([[-0.23197069,  0.40824829, -0.78583024],
       [-0.52532209, -0.81649658, -0.08675134],
       [-0.8186735 ,  0.40824829,  0.61232756]])
tools.confRegions2PPlanes(majorAxis, minorAxis, theta, want2plot=True, confLvl=0.95)[source]

Determines the \(\mathbb{R}^2\) coordinates of each confidence ellipse in the local Cartesyan System of the \(\mathscr{P}-\) planes that contain them. It is donde from their geometric parameters obtained from the eigVectsRegions function. If it is wanted, plots them too.

Parameters:
  • majorAxis (numpy.ndarray) – Array with the three lengths of the ellipses’ major axis that define the confidence region. The order is acording to the principal values returned from the getEigSorted function.
  • minorAxis (list) – list with the three couples of \(\boldsymbol{\mathrm{W}_i}\)‘s eigenvalues obtained with the getEigSorted function. The order is acording to the principal values returned from the getEigSorted function.
  • theta (list) – list with the three ellipse inclinations in radians measured from the horizontal axis of the local Cartesian System of each ellipse to the respective major axis counter clockwise.
  • want2plot (bool) – Logical variable to indicate if is wanted to plot the ellipes. True is the default value.
  • confLvl (float) – Confidence level of the limits of the variabilities of \(\boldsymbol{k}\)‘s principal vectors and values. 0.95 is the default value.
Returns:

Three elements are returned; they are described below.

  • x (list): List of three arrays that contain the abscises of the each ellipse.
  • y (list): List of three arrays that contain the ordinates of the each ellipse.
  • fig (list): matplotlib object. use fig.show() for displaying the plot

Examples

>>> from numpy import array
>>> from jelinekstat.tools import confRegions2PPlanes
>>> majorAxis = array([ 0.66888885,  0.66949335,  0.13745895])
>>> minorAxis = array([ 0.09950548,  0.09615434,  0.04640122])
>>> theta = array([-0.01949436, -1.51693959, -0.81162812])
>>> x, y, fig = confRegions2PPlanes(majorAxis, minorAxis, theta,
>>>                                 want2plot=True, confLvl=0.95)
>>> fig.show()
tools_confRegions2PPlanes_example

example script.

tools.rotateaxis2proyectellipses(axisN, axisE, axisD)[source]

Since it is easier, the projection of an ellpise (confidence region) on the stereogrpahic net is thought as a serie of rotations from the bottom of the semi-sphere, i.e., the nadir.

This function determines the axes names around which is necesary to rotate a confidence ellipse once it is placed at nadir of a semi-sphere to poject her from the nadir to the real position on the semi-sphere. Besides, it determines the angles to rotate at each axis name.

The mplstereonet reference system has the \(x, y\) and \(z\) vectors as its base, and they correspond to the nadir, east and north vectors in the NED reference system of the semi-spherical space of the Stereographic Projection.

It is implicit that the three input vectors are orthogonal to each other due to they correspond to the principal vectors of \(\boldsymbol{k}\).

Parameters:
  • axisN (numpy.ndarray) – Array with the coordinates \(x, y, z\) of the eigenvector that will point to the north-axis once the ellipse is placed at nadir of the semi-sphere, i.e., its othogonal eigenvector associated points downward.
  • axisE (numpy.ndarray) – Array with the coordinates \(x, y, z\) of the eigenvector that will point to the east-axis once the ellipse is placed at nadir of the semi-sphere, i.e., its othogonal eigenvector associated points downward.
  • axisD (numpy.ndarray) – Array with the coordinates \(x, y, z\) of the eigenvector that is othogonal to the ellipse.
Returns:

Two elements are returned; they are described below.

  • axis2rot (list): Strings with the axis-names of the NED system around which will be done the rotatios to project the confidence ellipse.
  • angles2rot (list): List of the angles in degrees for rotating a ellipse once it is placed orthogonal to the nadir.

Examples

>>> from numpy import array
>>> from jelinekstat.tools import rotateaxis2proyectellipses
>>> axis2rot, angles2rot = rotateaxis2proyectellipses(
>>>     array([2, 2, 1]), array([-2, 1, 2]), array([1, -2, 2]))
>>> axis2rot
['E', 'D', 'N', 'D']
>>> angles2rot
[-180, 26.565051177077976, 48.189685104221404, 206.56505117707798]
tools.proyAnEllipse2LongLat(x, y, axis2rot, angles2rot)[source]

Pojects just an ellipse from the \(\mathbb{R}^2\) coordinates of the \(\mathscr{P}-\) plane that contains it to the real position on the stereographic projection through some rotations from an initial position at the nadir of the semi-sphere.

Parameters:
  • x (numpy.ndarray or list) – Abscises of just one ellipse’s boundary on the \(\mathscr{P}-\) plane. It is obtained from the confRegions2PPlanes function.
  • y (numpy.ndarray or list) – Ordinates of just one ellipse’s boundary on the \(\mathscr{P}-\) plane. It is obtained from the confRegions2PPlanes function.
  • axis2rot (list) – Strings with the axis-names of the NED system around which will be done the rotatios to project the confidence ellipse. It is obtained from the rotateaxis2proyectellipses function.
  • angles2rot (list) – List of the angles in degrees for rotating a ellipse once it is placed orthogonal to the nadir. It is obtained from the rotateaxis2proyectellipses function.
Returns:

Two elements are returned; they are described below.

  • ellipLong (numpy.ndarray): Longitudes of the ellipse’s boundary after being rotated to its right position in the stereographic projection.
  • ellipLat (numpy.ndarray): Latitudes of the ellipse’s boundary after being rotated to its right position in the stereographic projection.

Examples

>>> from numpy import array
>>> from jelinekstat.tools import confRegions2PPlanes
>>> majorAxis = array([ 0.66888885,  0.66949335,  0.13745895])
>>> minorAxis = array([ 0.09950548,  0.09615434,  0.04640122])
>>> theta = array([-0.01949436, -1.51693959, -0.81162812])
>>> x, y = confRegions2PPlanes(majorAxis, minorAxis, theta, False,
>>>                            0.95)
>>> ellipLong, ellipLat = proyAnEllipse2LongLat(
>>>     x[0], y[0], ['E', 'D', 'N', 'D'], [-180, 116.37, 70.93, 77.98])
tools.eigVects2PlgTrd(tensor, tensorVectForm=True)[source]

Obtains the principal vectors of a second-order tensor and returns them in the the plunge, trend \(\left(\delta, \delta_\mathrm{dir}\right)\) notation used in Structural Geology and Rock Mechanics.

Parameters:
  • tensor (numpy.ndarray) – A secon-order tensor.
  • tensorVectForm (bool) – Logical variable to indicate if the input tensor is in vector form. True is the default value.
Returns:

Two elements are returned; they are described below.

  • eigVecPlg (list): Plunges of the three principal vectors of the input tensor. The order is acording to the principal values returned from the getEigSorted function.
  • eigVecTrd (list): Trends of the three principal vectors of the input tensor. The order is acording to the principal values returned from the getEigSorted function.

Examples

>>> from numpy import array
>>> from jelinekstat.tools import eigVects2PlgTrd
>>> tensor = array([1.023, 1.0295,  0.9473, -0.0150, -0.0360, -0.056])
>>> eigVecPlg, eigVecTrd = eigVects2PlgTrd(
>>>     tensor, tensorVectForm=True)
>>> eigVecPlg
[31.176002127688509, 7.2363353791762837, 57.806971200122995]
>>> eigVecTrd
[198.07283722120425, 292.47894708173089, 34.114473250861067]
tools.proyAllEllipses2LongLat(x, y, meanTensor, tensorVectForm=True)[source]

Pojects all the three confidence ellipses from the \(mathbb{R}^2\) coordinates of the \(mathscr{P}-\) plane that contain them to the real position on the stereographic projection through some rotations from an initial position at the nadir of the semi-sphere.

Parameters:
  • x (numpy.ndarray or list) – Arrangement of the three lists each one with the abscises of an ellipse’s boundary on the \(mathscr{P}-\) plane. They are obtained from the confRegions2PPlanes function.
  • y (numpy.ndarray or list) – Arrangement of the three lists each one with the ordinates of an ellipse’s boundary on the \(mathscr{P}-\) plane. They are obtained from the confRegions2PPlanes function.
  • meanTensor (numpy.ndarray) – mean tensor \(\boldsymbol{k}\) of the sample either in vector or matrix form.
  • tensorVectForm (bool) – Logical variable to indicate if the input \(\boldsymbol{k}\) is in vector form. True is the default value.
Returns:

Two elements are returned; they are described below.

  • long (numpy.ndarray): Array of the three lists each one with the longitudes (in radians) of all the ellipse’s boundary after being rotated to its right position in the stereographic projection.
  • lat (numpy.ndarray): Array of the three lists each one with the latitudes (in radians) of all the ellipse’s boundary after being rotated to its right position in the stereographic projection.

Examples

>>> from numpy import array
>>> from jelinekstat.tools import *
>>> from jelinekstat.jelinekstat import meantensor
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
>>>     sample, normalized=True)
>>> majorAxis = array([ 0.66888885,  0.66949335,  0.13745895])
>>> minorAxis = array([ 0.09950548,  0.09615434,  0.04640122])
>>> theta = array([-0.01949436, -1.51693959, -0.81162812])
>>> x, y = confRegions2PPlanes(
>>>     majorAxis, minorAxis, theta, False, 0.95)
>>> long, lat = proyAllEllipses2LongLat(x, y, meanTensorVect)
tools.splitIterables(iter1, iter2)[source]

Splits two iterable elements which are paired by selecting the math:n common indexes where there are sign changes in both inputs at the same time. If there is any index to split the inputs, it returns the same inputs within a list.

Parameters:
  • iter1 (numpy.ndarray or list) – An iterable element which is paired to iter2.
  • iter2 (numpy.ndarray or list) – An iterable element which is paired to iter1.
Returns:

Two elements are returned; they are described below.

  • iter1Splitted (list): Segments of the original iter1 input after being splitted.
  • iter2splitted (list): Segments of the original iter2 input after being splitted.

Examples

>>> from jelinekstat.tools import splitIterables
>>> iter1, iter2 = [1, -2, -3, 4, 5, 6], [-3, -2, -1, 0, 1, 2]
>>> iter1Splitted, iter2splitted = splitIterables(iter1, iter2)
>>> iter1Splitted
[[1, -2, -3], [4, 5, 6]]
>>> iter2splitted
[[-3, -2, -1], [0, 1, 2]]