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
- sample (numpy.ndarray): \((n \times 6)\) array that contains the same values than the
-
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 eigenvaluesortedEigVal[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 thegetEigSorted
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. usefig.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()
- 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
-
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])
- x (numpy.ndarray or list) – Abscises of just one ellipse’s boundary
on the \(\mathscr{P}-\) plane. It is obtained from the
-
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)
- 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
-
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]]
- iter1 (numpy.ndarray or list) – An iterable element which is
paired to