1. jelinekstat

Module which contains the required functions to apply the statistical model for a sample of \(n\) second-order tensors Jelínek (1978) in order to obtain the mean tensor \(\boldsymbol{k}\) of the sample, the \(\boldsymbol{k}\)‘s principal values \(k_1, k_2\ \&\ k_3\), with their confidence intervals, and the \(\boldsymbol{k}\)‘s principal directions \(\boldsymbol{p}_1, \boldsymbol{p}_2\ \&\ \boldsymbol{p}_3\) with their confidence regions.

This application program is able to plot the summary of the statistical model described above in a stereographic projection for a better understanding of the outcomes.

Note

  • The packages numpy, scipy, 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.
jelinekstat.normalizeTensors(sample)[source]

Divides all the tensor’s elements by the mean susceptibility \({k}\), i.e. gets \(\boldsymbol{k}_\mathrm{norm}\) using the equations (8) of Jelínek (1978).

Parameters:sample (numpy.ndarray) – \((n \times 6)\) array that contains the values obtained from the extractdata fuction.
Returns:\((n \times 6)\) array that contains the tensors \(\boldsymbol{k}_\mathrm{norm}\) with the same format and structure of the extractdata function’s output.
Return type:(numpy.ndarray)

Examples

>>> from jelinekstat.tools import dataFromFile
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> normalizeTensors(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.02775343,  1.00633335,  0.96591322, -0.01635005, -0.04148014,
      -0.02006007],
     [1.02143,  1.01775,  0.96082, -0.02798, -0.04727, -0.02384],
     [1.01822661,  1.01202663,  0.96974677, -0.01125996, -0.02832991,
      -0.03648988],
     [1.01486338,  1.0206734 ,  0.96446321, -0.01046003, -0.01913006,
      -0.03864013],
     [1.04596,  1.01133,  0.94271, -0.0166 , -0.04711, -0.03636]])
jelinekstat.meantensor(sample, normalized=False)[source]

Estimates the mean tensor \(\boldsymbol{k}\) of a randomly chosen sample of \(n\) specimens by using the equation (11) of Jelínek (1978) after being normalized the specimens through the normalizeTensors function.

Parameters:
  • sample (numpy.ndarray) – \((n \times 6)\) array that contains the values of the tensors after being imported with the extractdata function.
  • normalize (bool) –

    Logical variable to indicate if the tensors in the sample variable are already normalized by using the equation (11) of (Jelínek (1978)). False is the default value. In the case they are not normalized, they will be.
Returns:

Three elements are returned; they are described below.

  • meanTensorVect (numpy.ndarray): Mean tensor in vector form.
  • meanTensorMtx (numpy.ndarray): Mean tensor in matrix form.
  • numTensors (int): Number of tensors.

Examples

>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import meantensor
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
        sample, normalized=False)
>>> meanTensorVect
array([ 1.02533293,  1.01891542,  0.95575165, -0.01714126, -0.03435001,
>>>    -0.03794001])
>>> meanTensorMtx
array([[ 1.02533293, -0.01714126, -0.03794001],
       [-0.01714126,  1.01891542, -0.03435001],
       [-0.03794001, -0.03435001,  0.95575165]])
>>> numTensors
8
jelinekstat.covMtx2PPlane(covMtx, meanTensor, numTensors, tensorVectForm=True)[source]

Obtains the covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\) of the \(\boldsymbol{k^\mathrm{P}}\)‘s elements (i.e. going over to a Cartesian system determined by \(\boldsymbol{p}_1, \boldsymbol{p}_2\ \&\ \boldsymbol{p}_3\) as is shown equation (19) of Jelínek (1978)), by using the equation (20) and (21) of the same reference.

Parameters:
  • covMtx (numpy.ndarray) –

    \((6 \times 6)\) array that estimates the unbiased covariance matrix \(\boldsymbol{\mathrm{V}}\) of the tensors in the sample. It can be obtained by using the equation (13) of Jelínek (1978)) or the cov numpy function (as is shown in the example).

  • meanTensor (numpy.ndarray) – mean tensor \(\boldsymbol{k}\) of he sample either in vector or matrix form.
  • numTensors (int) – Number of tensors in the sample.
  • tensorVectForm (bool) – Logical variable to indicate if the input mean tensor is in vector form. True is the default value.
Returns:

\((6 \times 6)\) covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\) of \(\boldsymbol{k^\mathrm{P}}\)‘s elements.
Return type:

(numpy.ndarray)

Examples

>>> from numpy import cov
>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import meantensor, covMtx2PPlane
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> normTensors = normalizeTensors(sample)
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
>>>     normTensors, normalized=True)
>>> covMtx = cov(normTensors.T, bias=False)
>>> covMtx2PPlane(
>>>     covMtx, meanTensorVect, numTensors)
array([[  1.02065332e-04,   4.74951816e-05,  -1.49560514e-04,
         -1.65998575e-06,   3.81988803e-05,  -2.24249042e-05],
       [  4.74951816e-05,   5.55684188e-05,  -1.03063600e-04,
         -2.03320518e-05,  -5.50208910e-06,  -1.06377394e-05],
       [ -1.49560514e-04,  -1.03063600e-04,   2.52624114e-04,
          2.19920375e-05,  -3.26967912e-05,   3.30626436e-05],
       [ -1.65998575e-06,  -2.03320518e-05,   2.19920375e-05,
          2.95042484e-05,   2.05384181e-05,  -7.98602106e-06],
       [  3.81988803e-05,  -5.50208910e-06,  -3.26967912e-05,
          2.05384181e-05,   9.00227092e-05,  -7.40633382e-05],
       [ -2.24249042e-05,  -1.06377394e-05,   3.30626436e-05,
         -7.98602106e-06,  -7.40633382e-05,   9.59108639e-05]])
jelinekstat.localCovMtxs(meanTensor, pCovMtx, tensorVectForm=True)[source]

Determines the covariance matrix \(\boldsymbol{\mathrm{W}_i}\) of the random variables \(\left(\mathrm{d}p_{ji}, \mathrm{d}p_{ki}\right)\) from the local Cartesian System \(\mathrm{d}\boldsymbol{p}_i\) that define the \(\mathscr{P}-\) plane where each confidence area of the mean tensor’s princial direcions are drawn by using the equation (27) of Jelínek (1978).

Parameters:
  • meanTensor (numpy.ndarray) – mean tensor \(\boldsymbol{k}\) of the sample either in vector or matrix form.
  • pCovMtx (numpy.ndarray) – \((6 \times 6)\) covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\) of \(\boldsymbol{k^\mathrm{P}}\)‘s elements. It is obtained with the covMtx2PPlane function.
  • tensorVectForm (bool) – Logical variable to indicate if the input \(\boldsymbol{k}\) is in vector form. True is the default value.
Returns:

Three elements are returned; they are described below.

  • W (list): list of three \((2 \times 2)\) arrayes with the covariance matrix \(\boldsymbol{\mathrm{W}_i}\) described above.
  • eigVal_W (list): list with the three couples of \(\boldsymbol{\mathrm{W}_i}\)‘s eigenvalues obtained with the getEigSorted function.
  • eigVec_W (list): list with the three \((2 \times 2)\) arrayes of \(\boldsymbol{\mathrm{W}_i}\)‘s eigevectors obtained with the getEigSorted function.

Examples

>>> from numpy import cov
>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import meantensor, covMtx2PPlane
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> normTensors = normalizeTensors(sample)
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
>>>     normTensors, normalized=True)
>>> covMtx = cov(normTensors.T, bias=False)
>>> pCovMtx = covMtx2PPlane(
>>>     covMtx, meanTensorVect, numTensors)
>>> W, eigVal_W, eigVec_W = localCovMtxs(
>>>     meanTensorVect, pCovMtx)
>>> W
[array([[ 0.41635005, -0.00798796],
        [-0.00798796,  0.00679994]]),
 array([[ 0.00739345, -0.02211065],
        [-0.02211065,  0.41635005]]),
array([[ 0.00679994, -0.00565157],
       [-0.00565157,  0.00739345]])]
>>> eigVal_W
[array([ 0.41650579,  0.0066442 ]),
 array([ 0.41754201,  0.00620149]),
 array([ 0.01275605,  0.00143733])]
>>> eigVec_W
[array([[ 0.99980999,  0.01949312],
        [-0.01949312,  0.99980999]]),
 array([[ 0.05383071, -0.99855008],
        [-0.99855008, -0.05383071]]),
 array([[ 0.68831829, -0.7254088 ],
        [-0.7254088 , -0.68831829]])]
jelinekstat.eigValsIntervals(pCovMtx, numTensors, confLvl=0.95, estimate=True)[source]

Determines the limits of the variabilities of \(\boldsymbol{k}\)‘s principal values for a confidence level given. Ther are obtained by using the equation (29) of Jelínek (1978) or their estimate values by using the equation (35) of Jelínek (1978).

Parameters:
  • pCovMtx (numpy.ndarray) – \((6 \times 6)\) covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\) of \(\boldsymbol{k^\mathrm{P}}\)‘s elements. It is obtained with the covMtx2PPlane function.
  • numTensors (int) – Number of tensors in the sample.
  • confLvl (float) – Confidence level of the limits of the variabilities of \(\boldsymbol{k}\)‘s principal values. 0.95 is the default value.
  • estimate (bool) – Logical variable to indicate if the output is based whether on the real or estimate covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\). True is the default value.
Returns:

Array with the three limits of the variabilities of \(\boldsymbol{k}\)‘s principal values.
Return type:

(numpy.ndarray)

Examples

>>> from numpy import cov
>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import *
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> normTensors = normalizeTensors(sample)
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
>>>     normTensors, normalized=True)
>>> covMtx = cov(normTensors.T, bias=False)
>>> pCovMtx = covMtx2PPlane(
>>>     covMtx, meanTensorVect, numTensors)
>>> eigValsIntervals(
>>>     pCovMtx, numTensors, confLvl=0.95, estimate=True)
array([ 0.0084461 ,  0.00623205,  0.01328784])
jelinekstat.eigVectsRegions(W, eigVal_W, eigVec_W, numTensors, confLvl=0.95, estimate=True)[source]

Determines the ellipses’ geometric parameters of the confidence regions that define the limits of the variabilities of the \(\boldsymbol{k}\)‘s principal vectors.

The axes lenghts ara obtained by using the equation (32) of Jelínek (1978) or their estimated values by using the equation (35) of Jelínek (1978) and the inclination angles by using the equation (41) of the same reference.

Parameters:
  • W (list) – list of three \((2 \times 2)\) arrayes with the covariance matrix \(\boldsymbol{\mathrm{W}_i}\) described above. It is obtained from the eigValsIntervals function.
  • eigVal_W (list) – list with the three couples of \(\boldsymbol{\mathrm{W}_i}\)‘s eigenvalues obtained with the getEigSorted function. It is obtained from the eigValsIntervals function.
  • eigVec_W (list) – list with the three \((2 \times 2)\) arrayes of \(\boldsymbol{\mathrm{W}_i}\)‘s eigevectors obtained with the getEigSorted function. It is obtained from the eigValsIntervals function.
  • numTensors (int) – Number of tensors in the sample.
  • confLvl (float) – Confidence level of the limits of the variabilities of \(\boldsymbol{k}\)‘s principal vectors. 0.95 is the default value.
  • estimate (bool) – Logical variable to indicate if the output is based whether on the real or estimate covariance matrix \(\boldsymbol{\mathrm{V^\mathrm{P}}}\). True is the default value.
Returns:

Three elements are returned; they are described below.

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

Examples:

>>> from numpy import cov
>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import *
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> normTensors = normalizeTensors(sample)
>>> meanTensorVect, meanTensorMtx, numTensors = meantensor(
>>>     normTensors, normalized=True)
>>> covMtx = cov(normTensors.T, bias=False)
>>> pCovMtx = covMtx2PPlane(
>>>     covMtx, meanTensorVect, numTensors)
>>> W, eigVal_W, eigVec_W = localCovMtxs(
>>>     meanTensorVect, pCovMtx)
>>> majorAxis, minorAxis, theta = eigVectsRegions(
>>>     W, eigVal_W, eigVec_W, numTensors, confLvl=0.95,
>>>     estimate=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])
jelinekstat.tensorStat(sample, confLevel=0.95, want2plot=True, plotName='001', ext='pdf')[source]

Summarizes the Jelínek (1978) statisctic proposal for 2nd-order tensors and plots it if is wanted.

Parameters:
  • sample (numpy.ndarray) – \((n imes 6)\) array that contains the values obtained from the extractdata fuction.
  • confLvl (float) – Confidence level of the limits of the variabilities of \(oldsymbol{k}\)‘s principal vectors and values. 0.95 is the default value.
  • want2plot (bool) – Logical variable to indicate if is wanted to plot the summary. True is the default value.
  • plotName (str) – Sample name for saving the final plot. ‘01’ is the default value.
  • ext (str) – File extension for saving the final plot. ‘pdf’ is the default value.
Returns:

Summary of the Jelínek (1978) statisctic proposal for 2nd-order tensors where is stored the data related to the mean tensor and its variability expressed as the variability of their principal values and vectors.
Return type:

(dict)

Examples

>>> from jelinekstat.tools import dataFromFile
>>> from jelinekstat.jelinekstat import tensorStat
>>> sample, numTensors = dataFromFile('inputDataExample.txt')
>>> jelinekStatsSummary, stereonetPlot = tensorStat(
>>>     sample, confLevel=0.95, want2plot=True, plotName='example',
>>>     ext='pdf')
>>> jelinekStatsSummary
{'K': array([[ 1.02533293, -0.01714126, -0.03794001],
             [-0.01714126,  1.01891542, -0.03435001],
             [-0.03794001, -0.03435001,  0.95575165]]),
 'k': array([1.02533, 1.01891, 0.95575, -0.01714, -0.03435, -0.03794]),
 'n': 8,
 'k1': {'value': 1.042393712466853, 'variability': 0.008446101031382},
 'k2': {'value': 1.033975634080194, 'variability': 0.006232053391831},
 'k3': {'value': 0.92363065345295237, 'variability': 0.0132878448184},
 'p1': {'coords': array([-0.92438729,  0.196842  ,  0.32674357]),
  'plg': 19.071242330117354,
  'trd': 167.97880567817268,
  'majAx': 0.66888885495049721,
  'minAx': 0.099505476893979108,
  'incl': -1.1169443953398852},
 'p2': {'coords': array([-0.04467227, -0.90653975,  0.41975002]),
  'plg': 24.818806179014864,
  'trd': 267.17887306022931,
  'majAx': 0.66949335258868026,
  'minAx': 0.096154338416730253,
  'incl': -86.914236097035555},
 'p3': {'coords': array([-0.37883047, -0.37341521, -0.8467872 ]),
  'plg': 57.863927991299327,
  'trd': 44.587546531270618,
  'majAx': 0.13745894751107776,
  'minAx': 0.0464012210689351,
  'incl': -46.502865813326189}}
>>> stereonetPlot.show()
jelinekstat_tensorStat_example

example script.