feature module

This module provide basic classes to store and analyze various type of structural data.

Classes:

Vector3(*args, **kwargs)	A class to represent a 3D vector.
Axial3(*args, **kwargs)	A class to represent a 3D axial vector.
Vector2(*args, **kwargs)	A class to represent a 2D vector.
Axial2(*args, **kwargs)	A class to represent a 2D axial vector.
Matrix3(*args, **kwargs)	A class to represent a 3x3 matrix.
Matrix2(*args, **kwargs)	A class to represent a 2x2 matrix.
Direction(*args, **kwargs)	A class to represent axial (non-oriented) 2D linear feature (direction).
Lineation(*args, **kwargs)	A class to represent axial (non-oriented) linear feature (lineation).
Foliation(*args, **kwargs)	A class to represent non-oriented planar feature (foliation).
Pair(*args, **kwargs)	The class to store pair of planar and linear feature.
Fault(*args, **kwargs)	The class to store Pair with associated sense of movement.
Cone(*args, **kwargs)	The class to store cone with given axis, secant line and revolution angle in degrees.
DeformationGradient3(*args, **kwargs)	The class to represent 3D deformation gradient tensor.
VelocityGradient3(*args, **kwargs)	The class to represent 3D velocity gradient tensor.
Stress3(*args, **kwargs)	The class to represent 3D stress tensor.
Ellipsoid(*args, **kwargs)	The class to represent 3D ellipsoid.
OrientationTensor3(*args, **kwargs)	Represents an 3D orientation tensor, which characterize data distribution using eigenvalue method.
DeformationGradient2(*args, **kwargs)	The class to represent 2D deformation gradient tensor.
VelocityGradient2(*args, **kwargs)	The class to represent 2D velocity gradient tensor.
Stress2(*args, **kwargs)	The class to represent 2D stress tensor.
Ellipse(*args, **kwargs)	The class to represent 2D ellipse
OrientationTensor2(*args, **kwargs)	Represents an 2D orientation tensor, which characterize data distribution using eigenvalue method.
Vector2Set(data[, name])	Class to store set of Vector2 features
Direction2Set(data[, name])	Class to store set of Direction features
FeatureSet(data[, name])	Base class for containers
Vector3Set(data[, name])	Class to store set of Vector3 features
LineationSet(data[, name])	Class to store set of Lineation features
FoliationSet(data[, name])	Class to store set of Foliation features
PairSet(data[, name])	Class to store set of Pair features
FaultSet(data[, name])	Class to store set of Fault features
ConeSet(data[, name])	Class to store set of Cone features
EllipseSet(data[, name])	Class to store set of Ellipse features
EllipsoidSet(data[, name])	Class to store set of Ellipsoid features
OrientationTensor2Set(data[, name])	Class to store set of OrientationTensor2 features
OrientationTensor3Set(data[, name])	Class to store set of OrientationTensor3 features
ClusterSet(d, **kwargs)	Provides a hierarchical clustering using scipy.cluster routines.
Core(**kwargs)	Core class to store palemomagnetic analysis data

Functions:

G(lst[, name])

Function to create appropriate container (FeatueSet) from list of features.

class apsg.feature.Vector3(*args, **kwargs)

Bases: Vector

A class to represent a 3D vector.

There are different way to create Vector3 object:

• without arguments create default Vector3 (1, 0, 0)

• with single argument v, where

  • v could be Vector3-like object

  • v could be string ‘x’, ‘y’ or ‘z’ - principal axes of coordinate system

  • v could be tuple of (x, y, z) - vector components

• with 2 arguments plunge direction and plunge

• with 3 numerical arguments defining vector components

Parameters:

• azi (float) – plunge direction of linear feature in degrees

• inc (float) – plunge of linear feature in degrees

Example

>>> vec()
>>> vec(1,2,-1)
>>> vec('y')
>>> vec(120, 30)
>>> v = vec(1, -2, 1)

property geo

Return tuple of plunge direction and signed plunge

is_upper()

Return True if vector points towards negative Z direction

lower()

Change vector direction to point towards positive Z direction

normalized()

Returns normalized (unit length) vector

classmethod random()

Create random 3D vector

transform(F, **kwargs)

Return affine transformation of vector u by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed vectors. [True or False] Default False

Returns:

vector representation of affine transformation (dot product) of self by F

Example

# Reflexion of y axis. >>> F = [[1, 0, 0], [0, -1, 0], [0, 0, 1]] >>> u = Vector3([1, 1, 1]) >>> u.transform(F) Vector3(1, -1, 1)

classmethod unit_x()

Create unit length vector in x-direction

classmethod unit_y()

Create unit length vector in y-direction

classmethod unit_z()

Create unit length vector in z-direction

uv()

Returns normalized (unit length) vector

property z

Return z-component of the vector

class apsg.feature.Axial3(*args, **kwargs)

Bases: Vector3

A class to represent a 3D axial vector.

Note: the angle between axial data cannot be more than 90°

class apsg.feature.Vector2(*args, **kwargs)

Bases: Vector

A class to represent a 2D vector.

There are different way to create Vector2 object:

• without arguments create default Vector2 (0, 0, 1)

• with single argument v, where

  • v could be Vector2-like object

  • v could be string ‘x’ or ‘y’ - principal axes of coordinate system

  • v could be tuple of (x, y) - vector components

  • v could be float - unit vector with given angle to ‘x’ axis

• with 2 numerical arguments defining vector components

Parameters:

ang (float) – angle between ‘x’ axis and vector in degrees

Example

>>> vec2()
>>> vec2(1, -1)
>>> vec2('y')
>>> vec2(50)
>>> v = vec2(1, -2)

property direction

Returns direction of the vector in degrees

normalized()

Returns normalized (unit length) vector

classmethod random()

Random 2D vector

transform(*args, **kwargs)

Return affine transformation of vector u by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed vectors. [True or False] Default False

Returns:

vector representation of affine transformation (dot product) of self by F

Example

# Reflexion of y axis. >>> F = [[1, 0], [0, -1]] >>> u = vec2([1, 1]) >>> u.transform(F) Vector2(1, -1)

classmethod unit_x()

Create unit length vector in x-direction

classmethod unit_y()

Create unit length vector in y-direction

uv()

Returns normalized (unit length) vector

class apsg.feature.Axial2(*args, **kwargs)

Bases: Vector2

A class to represent a 2D axial vector.

Note: the angle between axial data cannot be more than 90°

class apsg.feature.Matrix3(*args, **kwargs)

Bases: Matrix

A class to represent a 3x3 matrix.

There are different way to create Matrix3 object:

• without arguments create default identity Matrix3

• with single argument of Matrix3-like object

Parameters:

v – 2-dimensional array-like object

Example

>>> matrix()
Matrix3
[[1 0 0]
 [0 1 0]
 [0 0 1]]
>>> A = matrix([[2, 1, 0], [0, 0.5, 0], [0, -0.5, 1]])

property E1

First eigenvalue

property E2

Second eigenvalue

property E3

Third eigenvalue

property V1

First eigenvector

property V2

Second eigenvector

property V3

Third eigenvector

eigenvectors()

Return tuple of principal eigenvectors as Vector3 objects.

classmethod from_comp(**kwargs)

Return Matrix3 defined by individual components. Default is zero matrix.

Keyword Arguments:

• xx (float) – tensor component M_xx

• xy (float) – tensor component M_xy

• xz (float) – tensor component M_xz

• yx (float) – tensor component M_yx

• yy (float) – tensor component M_yy

• yz (float) – tensor component M_yz

• zx (float) – tensor component M_zx

• zy (float) – tensor component M_zy

• zz (float) – tensor component M_zz

Example

>>> M = matrix.from_comp(xy=1, zy=-0.5)
>>> M
[[ 0.   1.   0. ]
 [ 0.   0.   0. ]
 [ 0.  -0.5  0. ]]

scaled_eigenvectors()

Return tuple of principal eigenvectors as Vector3 objects with magnitudes of eigenvalues

property xz

Return xz-element of the matrix

property yz

Return yz-element of the matrix

property zx

Return zx-element of the matrix

property zy

Return zy-element of the matrix

property zz

Return zz-element of the matrix

class apsg.feature.Matrix2(*args, **kwargs)

Bases: Matrix

A class to represent a 2x2 matrix.

There are different way to create Matrix2 object:

• without arguments create default identity Matrix2

• with single argument of Matrix2-like object

Parameters:

v – 2-dimensional array-like object

Example

>>> matrix2()
Matrix2
[[1 0]
 [0 1]]
>>> A = Matrix2([[2, 1],[0, 0.5]])

property E1

First eigenvalue

property E2

Second eigenvalue

property V1

First eigenvector

property V2

Second eigenvector

eigenvectors()

Return tuple of principal eigenvectors as Vector3 objects.

classmethod from_comp(xx=0, xy=0, yx=0, yy=0)

Return Matrix2 defined by individual components. Default is zero matrix.

Keyword Arguments:

• xx (float) – tensor component M_xx

• xy (float) – tensor component M_xy

• yx (float) – tensor component M_yx

• yy (float) – tensor component M_yy

Example

>>> M = matrix2.from_comp(xy=2)
>>> M
Matrix2
[[0. 2.]
 [0. 0.]]

scaled_eigenvectors()

Return tuple of principal eigenvectors as Vector3 objects with magnitudes of eigenvalues

class apsg.feature.Direction(*args, **kwargs)

Bases: Axial2

A class to represent axial (non-oriented) 2D linear feature (direction).

There are different way to create Direction object:

• without arguments create default Direction D:0

• with single argument d, where:

  • d could be Vector2-like object

  • d could be string ‘x’ or ‘y’ - principal axes of coordinate system

  • d could be tuple of (x, y) - vector components

• with 1 argument direction

• with 2 numerical arguments defining vector components

Parameters:

direction (float) – plunge direction of linear feature in degrees

Example

>>> dir2()
>>> dir2('y')
>>> dir2(45)
>>> d = dir2(1, -1)

to_json()

Return as JSON dict

class apsg.feature.Lineation(*args, **kwargs)

Bases: Axial3

A class to represent axial (non-oriented) linear feature (lineation).

There are different way to create Lineation object:

• without arguments create default Lineation L:0/0

• with single argument l, where:

  • l could be Vector3-like object

  • l could be string ‘x’, ‘y’ or ‘z’ - principal axes of coordinate system

  • l could be tuple of (x, y, z) - vector components

• with 2 arguments plunge direction and plunge

• with 3 numerical arguments defining vector components

Parameters:

• azi (float) – plunge direction of linear feature in degrees

• inc (float) – plunge of linear feature in degrees

Example

>>> lin()
>>> lin('y')
>>> lin(1,2,-1)
>>> l = lin(110, 26)

cross(other)

Return Foliation defined by two linear features

property geo

Return tuple of plunge direction and plunge

to_json()

Return as JSON dict

class apsg.feature.Foliation(*args, **kwargs)

Bases: Axial3

A class to represent non-oriented planar feature (foliation).

There are different way to create Foliation object:

• without arguments create default Foliation S:180/0

• with single argument f, where:

  • f could be Vector3-like object

  • f could be string ‘x’, ‘y’ or ‘z’ - principal planes of coordinate system

  • f could be tuple of (x, y, z) - vector components

• with 2 arguments follows active notation. See apsg_conf.notation

• with 3 numerical arguments defining vector components of plane normal

Parameters:

• azi (float) – dip direction (or strike) of planar feature in degrees.

• inc (float) – dip of planar feature in degrees

Example

>>> fol()
>>> fol('y')
>>> fol(1,2,-1)
>>> f = fol(250, 30)

cross(other)

Return Lineation defined by intersection of planar features

dipvec()

Return dip vector

property geo

Return tuple of dip direction and dip

pole()

Return plane normal as vector

rake(rake)

Return rake vector

to_json()

Return as JSON dict

transform(F, **kwargs)

Return affine transformation by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed Foliation. [True or False] Default False

Returns:

vector representation of affine transformation (dot product) of self by F

Example

>>> # Reflexion of `y` axis.
>>> F = [[1, 0, 0], [0, -1, 0], [0, 0, 1]]
>>> f = fol(45, 20)
>>> f.transform(F)
S:315/20

class apsg.feature.Pair(*args, **kwargs)

Bases: object

The class to store pair of planar and linear feature.

When Pair object is created, both planar and linear feature are adjusted, so linear feature perfectly fit onto planar one. Warning is issued, when misfit angle is bigger than 20 degrees.

There are different way to create Pair object:

• without arguments create default Pair with fol(0,0) and lin(0,0)

• with single argument p, where:

  • p could be Pair

  • p could be tuple of (fazi, finc, lazi, linc)

  • p could be tuple of (fx, fy ,fz, lx, ly, lz)

• with 2 arguments f and l could be Vector3 like objects, e.g. Foliation and Lineation

• with four numerical arguments defining fol(fazi, finc) and lin(lazi, linc)

Parameters:

• fazi (float) – dip azimuth of planar feature in degrees

• finc (float) – dip of planar feature in degrees

• lazi (float) – plunge direction of linear feature in degrees

• linc (float) – plunge of linear feature in degrees

fvec

corrected vector normal to plane

Type:

Vector3

lvec

corrected vector of linear feature

Type:

Vector3

Example

>>> pair()
>>> pair(p)
>>> pair(f, l)
>>> pair(fazi, finc, lazi, linc)
>>> p = pair(140, 30, 110, 26)

property fol

Return a planar feature of Pair as Foliation.

label()

Return label

property lin

Return a linear feature of Pair as Lineation.

classmethod random()

Random Pair

to_json()

Return as JSON dict

transform(F, **kwargs)

Return an affine transformation of Pair by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed vectors. True or False. Default False

Returns:

representation of affine transformation (dot product) of self by F

Example

>>> F = defgrad.from_axisangle(lin(0,0), 60)
>>> p = pair(90, 90, 0, 50)
>>> p.transform(F)
P:270/30-314/23

class apsg.feature.Fault(*args, **kwargs)

Bases: Pair

The class to store Pair with associated sense of movement.

When Fault object is created, both planar and linear feature are adjusted, so linear feature perfectly fit onto planar one. Warning is issued, when misfit angle is bigger than 20 degrees.

There are different way to create Fault object:

• without arguments create default Fault with fol(0,0) and lin(0,0)

• with single argument p:

  • p could be Fault

  • p could be tuple of (fazi, finc, lazi, linc, sense)

  • p could be tuple of (fx, fy ,fz, lx, ly, lz)

• with 2 arguments p (Pair object) and sense

• with 3 arguments f, l (Vector3 like objects), e.g. Foliation and Lineation and sense

• with 5 numerical arguments defining fol(fazi, finc), lin(lazi, linc) and sense

Parameters:

• fazi (float) – dip azimuth of planar feature in degrees

• finc (float) – dip of planar feature in degrees

• lazi (float) – plunge direction of linear feature in degrees

• linc (float) – plunge of linear feature in degrees

• sense (float or str) – sense of movement +/-1 hanging-wall down/up. When str, must be one of ‘s’, ‘d’, ‘n’, ‘r’.

fvec

corrected vector normal to plane

Type:

Vector3

lvec

corrected vector of linear feature

Type:

Vector3

sense

sense of movement (+/-1)

Type:

int

Example

>>> f = fault(140, 30, 110, 26, -1)
>>> f = fault(140, 30, 110, 26, 'r')
>>> p = pair(140, 30, 110, 26)
>>> f = fault(p, 'n')
>>> f = fault(fol(120, 80), lin(32, 10), 's')

property d

Return dihedra plane as Fol

property m

Return kinematic M-plane as Foliation

property p

Return P-axis as Lineation

p_vector(ptangle=90)

Return P axis as Vector3

classmethod random()

Random Fault

property t

Return T-axis as Lineation

t_vector(ptangle=90)

Return T-axis as Vector3.

to_json()

Return as JSON dict

class apsg.feature.Cone(*args, **kwargs)

Bases: object

The class to store cone with given axis, secant line and revolution angle in degrees.

There are different way to create Cone object according to number of arguments:

• without args, you can create default``Cone`` with axis lin(0, 90), secant lin(0, 0) angle 360°

• with single argument c, where c could be Cone, 5-tuple of (aazi, ainc, sazi, sinc, revangle) or 7-tuple of (ax, ay ,az, sx, sy, sz, revangle)

• with 3 arguments, where axis and secant line could be Vector3 like objects, e.g. Lineation and third argument is revolution angle

• with 5 arguments defining axis lin(aazi, ainc), secant line lin(sazi, sinc) and angle of revolution

axis

axis of the cone

Type:

Vector3

secant

secant line

Type:

Vector3

revangle

revolution angle

Type:

float

Example

>>> cone()
>>> cone(c)
>>> cone(a, s, revangle)
>>> cone(aazi, ainc, sazi, sinc, revangle)
>>> c = cone(140, 30, 110, 26, 360)

apical_angle()

Return apical angle

label()

Return label

classmethod random()

Random Cone

property rotated_secant

Return revangle rotated secant vector

to_json()

Return as JSON dict

class apsg.feature.DeformationGradient3(*args, **kwargs)

Bases: Matrix3

The class to represent 3D deformation gradient tensor.

Parameters:

a (3x3 array_like) – Input data, that can be converted to 3x3 2D array. This includes lists, tuples and ndarrays.

Returns:

DeformationGradient3 object

Example

>>> F = defgrad(np.diag([2, 1, 0.5]))

property R

Return rotation part of DeformationGradient3 from polar decomposition.

property U

Return stretching part of DeformationGradient3 from right polar decomposition.

property V

Return stretching part of DeformationGradient3 from left polar decomposition.

axisangle()

Return rotation part of DeformationGradient3 as axis, angle tuple.

classmethod from_comp(**kwargs)

Return DeformationGradient3 defined by individual components. Default is identity tensor.

Keyword Arguments:

• xx (float) – tensor component F_xx

• xy (float) – tensor component F_xy

• xz (float) – tensor component F_xz

• yx (float) – tensor component F_yx

• yy (float) – tensor component F_yy

• yz (float) – tensor component F_yz

• zx (float) – tensor component F_zx

• zy (float) – tensor component F_zy

• zz (float) – tensor component F_zz

Example

>>> F = defgrad.from_comp(xy=1, zy=-0.5)
>>> F
DeformationGradient3
[[ 1.   1.   0. ]
 [ 0.   1.   0. ]
 [ 0.  -0.5  1. ]]

classmethod from_ratios(Rxy=1, Ryz=1)

Return isochoric DeformationGradient3 tensor with axial stretches defined by strain ratios. Default is identity tensor.

Keyword Arguments:

• Rxy (float) – XY strain ratio

• Ryz (float) – YZ strain ratio

Example

>>> F = defgrad.from_ratios(Rxy=2, Ryz=3)
>>> F
DeformationGradient3
[[2.289 0.    0.   ]
 [0.    1.145 0.   ]
 [0.    0.    0.382]]

classmethod from_two_pairs(p1, p2, symmetry=False)

Return DeformationGradient3 representing rotation of coordinates from system defined by Pair p1 to system defined by Pair p2.

Lineation in pair define x axis and normal to foliation in pair define z axis

Parameters:

• p1 (Pair) – from

• p2 (Pair) – to

Keyword Arguments:

symmetry (bool) – If True, returns minimum angle rotation of axial pairs

Returns:

Defgrad3 rotational matrix

Example

>>> p1 = pair(58, 36, 81, 34)
>>> p2 = pair(217,42, 162, 27)
>>> R = defgrad.from_two_pairs(p1, p2)
>>> p1.transform(R) == p2
True

velgrad(time=1)

Return VelocityGradient3 calculated as matrix logarithm divided by given time.

Keyword Arguments:

time (float) – total time. Default 1

Example

>>> F = defgrad.from_comp(xx=2, xy=1, zz=0.5)
>>> L = F.velgrad(time=10)
>>> L
VelocityGradient3
[[ 0.069  0.069  0.   ]
 [ 0.     0.     0.   ]
 [ 0.     0.    -0.069]]
>>> L.defgrad(time=10)
DeformationGradient3
[[2.  1.  0. ]
 [0.  1.  0. ]
 [0.  0.  0.5]]

class apsg.feature.VelocityGradient3(*args, **kwargs)

Bases: Matrix3

The class to represent 3D velocity gradient tensor.

Parameters:

a (3x3 array_like) – Input data, that can be converted to 3x3 2D array. This includes lists, tuples and ndarrays.

Returns:

VelocityGradient3 matrix

Example

>>> L = velgrad(np.diag([0.1, 0, -0.1]))

defgrad(time=1, steps=1)

Return DeformationGradient3 tensor accumulated after given time.

Keyword Arguments:

• time (float) – time of deformation. Default 1

• steps (int) – when bigger than 1, will return a list of DeformationGradient3 tensors for each timestep.

classmethod from_comp(**kwargs)

Return VelocityGradient3 defined by individual components. Default is zero tensor.

Keyword Arguments:

• xx (float) – tensor component L_xx

• xy (float) – tensor component L_xy

• xz (float) – tensor component L_xz

• yx (float) – tensor component L_yx

• yy (float) – tensor component L_yy

• yz (float) – tensor component L_yz

• zx (float) – tensor component L_zx

• zy (float) – tensor component L_zy

• zz (float) – tensor component L_zz

Example

>>> L = velgrad.from_comp(xy=1, zy=-0.5)
>>> L
[[ 0.   1.   0. ]
 [ 0.   0.   0. ]
 [ 0.  -0.5  0. ]]

rate()

Return rate of deformation tensor

spin()

Return spin tensor

class apsg.feature.Stress3(*args, **kwargs)

Bases: Tensor3

The class to represent 3D stress tensor.

The real eigenvalues of the stress tensor are what we call the principal stresses. There are 3 of these in 3D, available as properties E1, E2, and E3 in descending order of magnitude (max, intermediate, and minimum principal stresses) with orientations available as properties V1, V2 and V3. The minimum principal stress is simply the eigenvalue that has the lowest magnitude. Therefore, the maximum principal stress is the most tensile (least compressive) and the minimum principal stress is the least tensile (most compressive). Tensile normal stresses have positive values, and compressive normal stresses have negative values. If the maximum principal stress is <=0 and the minimum principal stress is negative then the stresses are completely compressive.

Note: Stress tensor has a special properties sigma1, sigma2 and sigma3 to follow common geological terminology. sigma1 is most compressive (least tensile) while sigma3 is most tensile (least compressive). Their orientation could be accessed with properties sigma1dir, sigma2dir and sigma3dir.

Parameters:

a (3x3 array_like) – Input data, that can be converted to 3x3 2D array. This includes lists, tuples and ndarrays.

Returns:

Stress3 object

Example

>>> S = stress([[-8, 0, 0],[0, -5, 0],[0, 0, -1]])

property I1

First invariant

property I2

Second invariant

property I3

Third invariant

cauchy(n)

Return stress vector associated with plane given by normal vector.

Parameters:

n – normal given as Vector3 or Foliation object

Example

>>> S = stress.from_comp(xx=-5, yy=-2, zz=10, xy=1)
>>> S.cauchy(fol(160, 30))
Vector3(-2.52, 0.812, 8.66)

property deviatoric

A stress deviator tensor component

property diagonalized

Returns diagonalized Stress tensor and orthogonal matrix R, which transforms actual coordinate system to the principal one.

dilation_tendency(n, fp=0)

Return dilation tendency of the plane.

Note: Providing fluid pressure effective stress is used

Keyword Arguments:

fp (float) – fluid pressure. Default 0

effective(fp)

A effective stress tensor reduced by fluid pressure

Parameters:

fp (flot) – fluid pressure

fault(n)

Return Fault object derived from given by normal vector.

Parameters:

n – normal given as Vector3 or Foliation object

Example

>>> S = stress.from_comp(xx=-5, yy=-2, zz=10, xy=8)
>>> S.fault(fol(160, 30))
F:160/30-141/29 +

classmethod from_comp(**kwargs)

Return Stress tensor. Default is zero tensor.

Note that stress tensor is always symmetrical.

Keyword Arguments:

zz (xx, xy, xz, yy, yz,) – tensor components

Example

>>> S = stress.from_comp(xx=-5, yy=-2, zz=10, xy=1)
>>> S
Stress3
[[-5.  1.  0.]
 [ 1. -2.  0.]
 [ 0.  0. 10.]]

classmethod from_ratio(r=0.5, mag=1)

Return Stress tensor with given shape ration.

Keyword Arguments:

• r (float) – shape ratio between 0 and 1. Default 0.5

• mag (float) – magnitude of differential stress. Default 1.

Example

>>> S = stress.from_ratio(r=0.25, mag=10)
>>> S
Stress3
[[-5.   0.   0. ]
 [ 0.  -2.5  0. ]
 [ 0.   0.   5. ]]

property hydrostatic

Mean hydrostatic stress tensor component

property mean_stress

Mean stress

normal_stress(n)

Return normal stress magnitude on plane given by normal vector.

property shape_ratio

Return shape ratio R (Gephart & Forsyth 1984)

shear_stress(n)

Return shear stress magnitude on plane given by normal vector.

property sigma1

A maximum principal stress (max compressive)

property sigma1dir

Return unit length vector in direction of maximum principal stress (max compressive)

property sigma1vec

Return maximum principal stress vector (max compressive)

property sigma2

A intermediate principal stress

property sigma2dir

Return unit length vector in direction of intermediate principal stress

property sigma2vec

Return intermediate principal stress vector

property sigma3

A minimum principal stress (max tensile)

property sigma3dir

Return unit length vector in direction of minimum principal stress (max tensile)

property sigma3vec

Return minimum principal stress vector (max tensile)

slip_tendency(n, fp=0, log=False)

Return slip tendency calculated as the ratio of shear stress to normal stress acting on the plane.

Note: Providing fluid pressure effective normal stress is calculated

Keyword Arguments:

• fp (float) – fluid pressure. Default 0

• log (bool) – when True, returns logarithm of slip tendency

stress_comp(n)

Return normal and shear stress Vector3 components on plane given by normal vector.

class apsg.feature.Ellipsoid(*args, **kwargs)

Bases: Tensor3

The class to represent 3D ellipsoid.

See following methods and properties for additional operations.

Parameters:

matrix (3x3 array_like) – Input data, that can be converted to 3x3 2D matrix. This includes lists, tuples and ndarrays.

Returns:

Ellipsoid object

Example

>>> E = ellipsoid([[8, 0, 0], [0, 2, 0], [0, 0, 1]])
>>> E
Ellipsoid
[[8 0 0]
 [0 2 0]
 [0 0 1]]
(S1:2.83, S2:1.41, S3:1)

property B: float

Cylindricity index (Vollmer, 1990).

property D: float

Return the strain intensity.

property G: float

Girdle index (Vollmer, 1990).

property Intensity: float

Intensity index (Lisle, 1985).

property K: float

Return the strain symmetry (Ramsay, 1983).

property MAD: float

Return maximum angular deviation (MAD)

property MAD_l: float

Return maximum angular deviation (MAD) of linearly distributed vectors.

Kirschvink 1980

property MAD_p: float

Return maximum angular deviation (MAD) of planarly distributed vectors.

Kirschvink 1980

property P: float

Point index (Vollmer, 1990).

property R: float

Random index (Vollmer, 1990).

property Rxy: float

Return the Rxy ratio.

property Ryz: float

Return the Ryz ratio.

property S1: float

Return the maximum principal stretch.

property S2: float

Return the middle principal stretch.

property S3: float

Return the minimum principal stretch.

property aMAD: float

Return approximate deviation according to shape

property aMAD_l: float

Return approximate angular deviation from the major axis along E1.

property aMAD_p: float

Return approximate deviation from the plane normal to E3.

property d: float

Return the strain intensity.

property e1: float

Return the maximum natural principal strain.

property e12: float

Return the e1 - e2.

property e13: float

Return the e1 - e3.

property e2: float

Return the middle natural principal strain.

property e23: float

Return the e2 - e3.

property e3: float

Return the minimum natural principal strain.

property eoct: float

Return the natural octahedral unit strain (Nadai, 1963).

classmethod from_defgrad(F, form='left', **kwargs) → Ellipsoid

Return deformation tensor from Defgrad3.

Kwargs:

form: ‘left’ or ‘B’ for left Cauchy–Green deformation tensor or

Finger deformation tensor ‘right’ or ‘C’ for right Cauchy–Green deformation tensor or Green’s deformation tensor. Default is ‘left’.

classmethod from_stretch(x=1, y=1, z=1, **kwargs) → Ellipsoid

Return diagonal tensor defined by magnitudes of principal stretches.

property goct: float

Return the natural octahedral unit shear (Nadai, 1963).

property k: float

Return the strain symmetry.

property kind: str

Return descriptive type of ellipsoid

property lode: float

Return Lode parameter (Lode, 1926).

property r: float

Return the strain intensity (Watterson, 1968).

property shape: float

return the Woodcock shape.

property strength: float

Return the Woodcock strength.

class apsg.feature.OrientationTensor3(*args, **kwargs)

Bases: Ellipsoid

Represents an 3D orientation tensor, which characterize data distribution using eigenvalue method. See (Watson 1966, Scheidegger 1965).

See following methods and properties for additional operations.

Parameters:

matrix (3x3 array_like) – Input data, that can be converted to 3x3 2D matrix. This includes lists, tuples and ndarrays. Array could be also Group (for backward compatibility)

Returns:

OrientationTensor3 object

Example

>>> ot = ortensor([[8, 0, 0], [0, 2, 0], [0, 0, 1]])
>>> ot
OrientationTensor3
[[8 0 0]
 [0 2 0]
 [0 0 1]]
(S1:2.83, S2:1.41, S3:1)

classmethod from_features(g) → OrientationTensor3

Return Ortensor of data in Vector3Set of features

Parameters:

g (Vector3Set) – Set of features

Example

>>> g = linset.random_fisher(position=lin(120,50))
>>> ot = ortensor.from_features(g)
>>> ot
OrientationTensor3
[[ 0.126 -0.149 -0.202]
 [-0.149  0.308  0.373]
 [-0.202  0.373  0.566]]
(S1:0.955, S2:0.219, S3:0.2)
>>> ot.eigenlins()
(L:119/51, L:341/31, L:237/21)

classmethod from_pairs(p, shift=True) → OrientationTensor3

Return Lisle (1989) Ortensor of orthogonal data in PairSet

Lisle, R. (1989). The Statistical Analysis of Orthogonal Orientation Data.

The Journal of Geology, 97(3), 360-364.

Note: Tensor is by default shifted towards positive eigenvalues, so it

could be used as Scheidegger orientation tensor for plotting. When original Lisle tensor is needed, set shift to False.

Parameters:

p – PairSet

Keyword Arguments:

shift (bool) – When True the tensor is shifted. Default True

Example

>>> p = pairset([pair(109, 82, 21, 10),
                 pair(118, 76, 30, 11),
                 pair(97, 86, 7, 3),
                 pair(109, 75, 23, 14)])
>>> ot = ortensor.from_pairs(p)
>>> ot
OrientationTensor3
[[0.577 0.192 0.029]
 [0.192 0.092 0.075]
 [0.029 0.075 0.332]]
(S1:0.807, S2:0.579, S3:0.114)

class apsg.feature.DeformationGradient2(*args, **kwargs)

Bases: Matrix2

The class to represent 2D deformation gradient tensor.

Parameters:

a (2x2 array_like) – Input data, that can be converted to 2x2 2D array. This includes lists, tuples and ndarrays.

Returns:

DeformationGradient2 object

Example

>>> F = defgrad2(np.diag([2, 0.5]))

property R

Return rotation part of DeformationGradient2 from polar decomposition.

property U

Return stretching part of DeformationGradient2 from right polar decomposition.

property V

Return stretching part of DeformationGradient2 from left polar decomposition.

angle()

Return rotation part of DeformationGradient2 as angle.

classmethod from_angle(theta)

Return DeformationGradient2 representing rotation by angle theta.

Parameters:

theta – Angle of rotation in degrees

Example

>>> F = defgrad2.from_angle(45)
>>> F
DeformationGradient2
[[ 0.707 -0.707]
 [ 0.707  0.707]]

classmethod from_comp(xx=1, xy=0, yx=0, yy=1)

Return DeformationGradient2 defined by individual components. Default is zero tensor.

Keyword Arguments:

• xx (float) – tensor component F_xx

• xy (float) – tensor component F_xy

• yx (float) – tensor component F_yx

• yy (float) – tensor component F_yy

Example

>>> F = matrix2.from_comp(xy=2)
>>> F
[[0. 2.]
[0. 0.]]

classmethod from_ratio(R=1)

Return isochoric DeformationGradient2 tensor with axial stretches defined by strain ratio. Default is identity tensor.

Keyword Arguments:

R (float) – strain ratio

Example

>>> F = defgrad2.from_ratio(R=4)
>> F
DeformationGradient2
[[2.  0. ]
 [0.  0.5]]

velgrad(time=1)

Return VelocityGradient2 for given time

class apsg.feature.VelocityGradient2(*args, **kwargs)

Bases: Matrix2

The class to represent 2D velocity gradient tensor.

Parameters:

a (2x2 array_like) – Input data, that can be converted to 2x2 2D array. This includes lists, tuples and ndarrays.

Returns:

VelocityGradient2 object

Example

>>> L = velgrad2(np.diag([0.1, -0.1]))

defgrad(time=1, steps=1)

Return DeformationGradient2 tensor accumulated after given time.

Keyword Arguments:

• time (float) – time of deformation. Default 1

• steps (int) – when bigger than 1, will return a list of DeformationGradient2 tensors for each timestep.

classmethod from_comp(xx=0, xy=0, yx=0, yy=0)

Return VelocityGradient2 defined by individual components. Default is zero tensor.

Keyword Arguments:

• xx (float) – tensor component L_xx

• xy (float) – tensor component L_xy

• yx (float) – tensor component L_yx

• yy (float) – tensor component L_yy

Example

>>> L = velgrad2.from_comp(xy=2)
>>> L
[[0. 2.]
 [0. 0.]]

rate()

Return rate of deformation tensor

spin()

Return spin tensor

class apsg.feature.Stress2(*args, **kwargs)

Bases: Tensor2

The class to represent 2D stress tensor.

Parameters:

a (2x2 array_like) – Input data, that can be converted to 2x2 2D array. This includes lists, tuples and ndarrays.

Returns:

Stress2 object

Example

>>> S = Stress2([[-8, 0, 0],[0, -5, 0],[0, 0, -1]])

property I1

First invariant

property I2

Second invariant

property I3

Third invariant

cauchy(n)

Return stress vector associated with plane given by normal vector.

Parameters:

n – normal given as Vector2 object

Example

>>> S = Stress.from_comp(xx=-5, yy=-2, xy=1)
>>> S.cauchy(vec2(1,1))
V(-2.520, 0.812, 8.660)

property deviatoric

A stress deviator tensor component

property diagonalized

Returns diagonalized Stress tensor and orthogonal matrix R, which transforms actual coordinate system to the principal one.

classmethod from_comp(xx=0, xy=0, yy=0)

Return Stress2 tensor. Default is zero tensor.

Note that stress tensor must be symmetrical.

Keyword Arguments:

yy (xx, xy,) – tensor components

Example

>>> S = stress2.from_comp(xx=-5, yy=-2, xy=1)
>>> S
Stress2
[[-5.  1.]
 [ 1. -2.]]

property hydrostatic

Mean hydrostatic stress tensor component

property mean_stress

Mean stress

normal_stress(n)

Return normal stress magnitude on plane given by normal vector.

shear_stress(n)

Return shear stress magnitude on plane given by normal vector.

property sigma1

A maximum principal stress (max compressive)

property sigma1dir

Return unit length vector in direction of maximum principal stress (max compressive)

property sigma1vec

Return maximum principal stress vector (max compressive)

property sigma2

A minimum principal stress

property sigma2dir

Return unit length vector in direction of minimum principal stress

property sigma2vec

Return minimum principal stress vector

signed_shear_stress(n)

Return signed shear stress magnitude on plane given by normal vector.

stress_comp(n)

Return normal and shear stress Vector2 components on plane given by normal vector.

class apsg.feature.Ellipse(*args, **kwargs)

Bases: Tensor2

The class to represent 2D ellipse

See following methods and properties for additional operations.

Parameters:

matrix (2x2 array_like) – Input data, that can be converted to 2x2 2D matrix. This includes lists, tuples and ndarrays.

Returns:

Ellipse object

Example

>>> E = ellipse([[8, 0], [0, 2]])
>>> E
Ellipse
[[8. 0.]
 [0. 2.]]
(ar:2, ori:0)

property S1: float

Return the maximum principal stretch.

property S2: float

Return the minimum principal stretch.

property ar: float

Return the ellipse axial ratio.

property e1: float

Return the maximum natural principal strain.

property e12: float

Return the difference between natural principal strains.

property e2: float

Return the minimum natural principal strain.

classmethod from_defgrad(F, form='left', **kwargs) → Ellipse

Return deformation tensor from Defgrad2.

Kwargs:

form: ‘left’ or ‘B’ for left Cauchy–Green deformation tensor or

Finger deformation tensor ‘right’ or ‘C’ for right Cauchy–Green deformation tensor or Green’s deformation tensor. Default is ‘left’.

classmethod from_stretch(x=1, y=1, **kwargs) → Ellipse

Return diagonal tensor defined by magnitudes of principal stretches.

property orientation

Return the orientation of the maximum eigenvector.

class apsg.feature.OrientationTensor2(*args, **kwargs)

Bases: Ellipse

Represents an 2D orientation tensor, which characterize data distribution using eigenvalue method. See (Watson 1966, Scheidegger 1965).

See following methods and properties for additional operations.

Parameters:

matrix (2x2 array_like) – Input data, that can be converted to 2x2 2D matrix. This includes lists, tuples and ndarrays. Array could be also Group (for backward compatibility)

Returns:

OrientationTensor2 object

Example

>>> v = vec2set.random(n=1000)
>>> ot = v.ortensor()
>>> ot
OrientationTensor2
[[ 0.502 -0.011]
 [-0.011  0.498]]
(ar:1.02, ori:140)

classmethod from_features(g) → OrientationTensor2

Return Ortensor of data in Vector2Set features

Parameters:

g (Vector2Set) – Set of features

Example

>>> v = vec2set.random_vonmises(position=120)
>>> ot = v.ortensor()
>>> ot
OrientationTensor2
[[ 0.377 -0.282]
 [-0.282  0.623]]
(ar:2.05, ori:123)

class apsg.feature.Vector2Set(data, name='Default')

Bases: FeatureSet

Class to store set of Vector2 features

R(mean=False)

Return resultant of data in Vector2Set object.

Resultant is of same type as features in Vector2Set. Note that Axial2 is axial in nature so resultant can give other result than expected. Anyway for axial data orientation tensor analysis will give you right answer.

Parameters:

mean – if True returns mean resultant. Default False

angle(other=None)

Return angles of all data in Vector2Set object

Without arguments it returns angles of all pairs in dataset. If argument is Vector2Set of same length or single data object element-wise angles are calculated.

cross(other=None)

Return cross products of all features in Vector2Set

Without arguments it returns cross product of all pairs in dataset. If argument is Vector2Set of same length or single data object element-wise cross-products are calculated.

delta()

Cone angle containing ~63% of the data in degrees.

For enough large sample it approach angular standard deviation (csd) of Fisher statistics

property direction

Return array of direction angles

dot(vec)

Return array of dot products of all features in Vector2Set with vector.

fisher_statistics()

Fisher’s statistics

fisher_statistics returns dictionary with keys:

k estimated precision parameter, csd estimated angular standard deviation a95 confidence limit

classmethod from_directions(angles, name='Default')

Create Vector2Set object from arrays of direction angles

Parameters:

angles – list or angles

Keyword Arguments:

name – name of Vector2Set object. Default is ‘Default’

Example

>>> f = vec2set.from_angles([120,130,140,125, 132. 131])

classmethod from_xy(x, y, name='Default')

Create Vector2Set object from arrays of x and y components

Parameters:

• x – list or array of x components

• y – list or array of y components

Keyword Arguments:

name – name of Vector2Set object. Default is ‘Default’

Example

>>> v = vec2set.from_xy([-0.4330127, -0.4330127, -0.66793414],
                        [0.75, 0.25, 0.60141061])

halfspace()

Change orientation of vectors in Vector2Set, so all have angle<=90 with resultant.

normalized()

Return Vector2Set object with normalized (unit length) elements.

ortensor()

Return orientation tensor Ortensor of Group.

proj(vec)

Return projections of all features in Vector2Set onto vector.

classmethod random(n=100, name='Default')

Method to create Vector2Set of features with uniformly distributed random orientation.

Keyword Arguments:

• n – number of objects to be generated

• name – name of dataset. Default is ‘Default’

Example

>>> np.random.seed(58463123)
>>> l = vec2set.random(100)

classmethod random_vonmises(n=100, position=0, kappa=5, name='Default')

Return Vector2Set of random vectors sampled from von Mises distribution around center position with concentration kappa.

Parameters:

• n – number of objects to be generated

• position – mean orientation given as angle. Default 0

• kappa – precision parameter of the distribution. Default 20

• name – name of dataset. Default is ‘Default’

Example

>>> l = linset.random_fisher(position=lin(120,50))

rdegree()

Degree of preffered orientation of vectors in Vector2Set.

D = 100 * (2 * abs(R) - n) / n

to_dir2()

Return Direction2Set object with all data converted to Direction.

to_vec2()

Return Vector2Set object with all data converted to Vector2.

transform(F, **kwargs)

Return affine transformation of all features Vector2Set by matrix ‘F’.

Parameters:

F – Transformation matrix. Array-like value e.g. DeformationGradient3

Keyword Arguments:

norm – normalize transformed features. True or False. Default False

uv()

Return Vector2Set object with normalized (unit length) elements.

var()

Spherical variance based on resultant length (Mardia 1972).

var = 1 - abs(R) / n

property x

Return numpy array of x-components

property y

Return numpy array of y-components

class apsg.feature.Direction2Set(data, name='Default')

Bases: Vector2Set

Class to store set of Direction features

class apsg.feature.FeatureSet(data, name='Default')

Bases: object

Base class for containers

bootstrap(n=100, size=None)

Return generator of bootstraped samples from FeatureSet.

Parameters:

• n – number of samples to be generated. Default 100.

• size – number of data in sample. Default is same as FeatureSet.

Example

>>> np.random.seed(6034782)
>>> l = Vector3Set.random_fisher(n=100, position=lin(120,40))
>>> sm = [lb.R() for lb in l.bootstrap()]
>>> l.fisher_statistics()
{'k': 19.91236110604979, 'a95': 3.249027370399397, 'csd': 18.15196473425630}
>>> Vector3Set(sm).fisher_statistics()
{'k': 1735.360206701859, 'a95': 0.3393224356447341, 'csd': 1.944420546779801}

filter(**kwargs)

Filter FeatureSet objects attrs

label()

Return label

rotate(axis, phi)

Rotate FeatureSet object phi degress about axis.

to_json()

Return as JSON dict

class apsg.feature.Vector3Set(data, name='Default')

Bases: FeatureSet

Class to store set of Vector3 features

R(mean=False)

Return resultant of data in FeatureSet object.

Resultant is of same type as features in FeatureSet. Note that Foliation and Lineation are axial in nature so resultant can give other result than expected. Anyway for axial data orientation tensor analysis will give you right answer.

Parameters:

mean – if True returns mean resultant. Default False

angle(other=None)

Return angles of all data in FeatureSet object

Without arguments it returns angles of all pairs in dataset. If argument is FeatureSet of same length or single data object element-wise angles are calculated.

centered(max_vertical=False)

Rotate FeatureSet object to position that eigenvectors are parallel to axes of coordinate system: E1||X (north-south), E2||X(east-west), E3||X(vertical)

Parameters:

max_vertical – If True E1 is rotated to vertical. Default False

cross(other=None)

Return cross products of all features in FeatureSet

Without arguments it returns cross product of all pairs in dataset. If argument is FeatureSet of same length or single data object element-wise cross-products are calculated.

delta()

Cone angle containing ~63% of the data in degrees.

For enough large sample it approach angular standard deviation (csd) of Fisher statistics

dot(vec)

Return array of dot products of all features in FeatureSet with vector.

fisher_cone_a95()

Confidence limit cone based on Fisher’s statistics

Cone axis is resultant and apical angle is a95 confidence limit

fisher_cone_csd()

Angular standard deviation cone based on Fisher’s statistics

Cone axis is resultant and apical angle is angular standard deviation

fisher_statistics()

Fisher’s statistics

fisher_statistics returns dictionary with keys:

k estimated precision parameter, csd estimated angular standard deviation a95 confidence limit

classmethod from_array(azis, incs, name='Default')

Create FeatureSet object from arrays of azimuths and inclinations

Parameters:

• azis – list or array of azimuths

• incs – list or array of inclinations

Keyword Arguments:

name – name of FeatureSet object. Default is ‘Default’

Example

>>> f = folset.from_array([120,130,140], [10,20,30])
>>> l = linset.from_array([120,130,140], [10,20,30])

classmethod from_csv(filename, acol=0, icol=1)

Create FeatureSet object from csv file of azimuths and inclinations

Parameters:

filename (str) – name of CSV file to load

Keyword Arguments:

• acol (int or str) – azimuth column (starts from 0). Default 0

• icol (int or str) – inclination column (starts from 0). Default 1 When acol and icol are strings they are used as column headers.

Example

>>> gf = folset.from_csv('file1.csv')
>>> gl = linset.from_csv('file2.csv', acol=1, icol=2)

classmethod from_xyz(x, y, z, name='Default')

Create FeatureSet object from arrays of x, y and z components

Parameters:

• x – list or array of x components

• y – list or array of y components

• z – list or array of z components

Keyword Arguments:

name – name of FeatureSet object. Default is ‘Default’

Example

>>> v = vecset.from_xyz([-0.4330127, -0.4330127, -0.66793414],
                        [0.75, 0.25, 0.60141061],
                        [0.5, 0.8660254, 0.43837115])

property geo

Return arrays of azi and inc according to apsg_conf.notation

halfspace()

Change orientation of vectors in FeatureSet, so all have angle<=90 with resultant.

is_upper()

Return boolean array of z-coordinate negative test

normalized()

Return FeatureSet object with normalized (unit length) elements.

ortensor()

Return orientation tensor Ortensor of Group.

proj(vec)

Return projections of all features in FeatureSet onto vector.

project(vec)

Return projections of all features in FeatureSet onto vector.

classmethod random_fisher(n=100, position=Vector3(0, 0, 1), kappa=20, name='Default')

Return FeatureSet of random vectors sampled from von Mises Fisher distribution around center position with concentration kappa.

Parameters:

• n – number of objects to be generated

• position – mean orientation given as Vector3. Default Vector3(0, 0, 1)

• kappa – precision parameter of the distribution. Default 20

• name – name of dataset. Default is ‘Default’

Example

>>> l = linset.random_fisher(position=lin(120,50))

classmethod random_fisher2(n=100, position=Vector3(0, 0, 1), kappa=20, name='Default')

Method to create FeatureSet of vectors distributed according to Fisher distribution.

Note: For proper von Mises Fisher distrinbution implementation use random.fisher method.

Parameters:

• n – number of objects to be generated

• position – mean orientation given as Vector3. Default Vector3(0, 0, 1)

• kappa – precision parameter of the distribution. Default 20

• name – name of dataset. Default is ‘Default’

Example

>>> l = linset.random_fisher2(position=lin(120,50))

classmethod random_kent(p, n=100, kappa=20, beta=None, name='Default')

Return FeatureSet of random vectors sampled from Kent distribution (Kent, 1982) - The 5-parameter Fisher–Bingham distribution.

Parameters:

• p – Pair object defining orientation of data

• N – number of objects to be generated

• kappa – concentration parameter. Default 20

• beta – ellipticity 0 <= beta < kappa

• name – name of dataset. Default is ‘Default’

Example

>>> p = pair(150, 40, 150, 40)
>>> l = linset.random_kent(p, n=300, kappa=30)

classmethod random_normal(n=100, position=Vector3(0, 0, 1), sigma=20, name='Default')

Method to create FeatureSet of normaly distributed features.

Keyword Arguments:

• n – number of objects to be generated

• position – mean orientation given as Vector3. Default Vector3(0, 0, 1)

• sigma – sigma of normal distribution. Default 20

• name – name of dataset. Default is ‘Default’

Example

>>> np.random.seed(58463123)
>>> l = linset.random_normal(100, lin(120, 40))
>>> l.R
L:120/39

rdegree()

Degree of preffered orientation of vectors in FeatureSet.

D = 100 * (2 * abs(R) - n) / n

reject(vec)

Return rejections of all features in FeatureSet onto vector.

to_csv(filename, delimiter=',')

Save FeatureSet object to csv file of azimuths and inclinations

Parameters:

filename (str) – name of CSV file to save.

Keyword Arguments:

delimiter (str) – values delimiter. Default ‘,’

Note: Written values are rounded according to ndigits settings in apsg_conf

to_fol()

Return FoliationSet object with all data converted to Foliation.

to_lin()

Return LineationSet object with all data converted to Lineation.

to_vec()

Return Vector3Set object with all data converted to Vector3.

transform(F, **kwargs)

Return affine transformation of all features FeatureSet by matrix ‘F’.

Parameters:

F – Transformation matrix. Array-like value e.g. DeformationGradient3

Keyword Arguments:

norm – normalize transformed features. True or False. Default False

classmethod uniform_gss(n=100, name='Default')

Method to create FeatureSet of uniformly distributed vectors. Golden Section Spiral points on a sphere algorithm.

http://www.softimageblog.com/archives/115

Parameters:

• n – number of objects to be generated. Default 1000

• name – name of dataset. Default is ‘Default’

Example

>>> v = vecset.uniform_gss(300)
>>> v.ortensor().eigenvalues()
(0.33335688569571587, 0.33332315115436933, 0.33331996314991513)

classmethod uniform_sfs(n=100, name='Default')

Method to create FeatureSet of uniformly distributed vectors. Spherical Fibonacci Spiral points on a sphere algorithm adopted from John Burkardt.

http://people.sc.fsu.edu/~jburkardt/

Keyword Arguments:

• n – number of objects to be generated. Default 1000

• name – name of dataset. Default is ‘Default’

Example

>>> v = vecset.uniform_sfs(300)
>>> v.ortensor().eigenvalues()
(0.3334645347163635, 0.33333474915201167, 0.33320071613162483)

uv()

Return FeatureSet object with normalized (unit length) elements.

var()

Spherical variance based on resultant length (Mardia 1972).

var = 1 - abs(R) / n

property x

Return numpy array of x-components

property y

Return numpy array of y-components

property z

Return numpy array of z-components

class apsg.feature.LineationSet(data, name='Default')

Bases: Vector3Set

Class to store set of Lineation features

class apsg.feature.FoliationSet(data, name='Default')

Bases: Vector3Set

Class to store set of Foliation features

dipvec()

Return FeatureSet object with plane dip vector.

class apsg.feature.PairSet(data, name='Default')

Bases: FeatureSet

Class to store set of Pair features

angle(other=None)

Return angles of all data in PairSet object

Without arguments it returns angles of all pairs in dataset. If argument is PairSet of same length or single data object element-wise angles are calculated.

property fol

Return Foliations of pairs as FoliationSet

classmethod from_array(fazis, fincs, lazis, lincs, senses=[], name='Default')

Create FaultSet from arrays of azimuths, inclinations and senses

Parameters:

• fazis – list or array of azimuths

• fincs – list or array of inclinations

• lazis – list or array of azimuths

• lincs – list or array of inclinations

Keyword Arguments:

name – name of PairSet object. Default is ‘Default’

classmethod from_csv(filename, delimiter=',', sense_str=False, facol=0, ficol=1, lacol=2, licol=3, scol=4)

Read PairSet from csv file

property fvec

Return planar normal vectors of pairs as Vector3Set

label()

Return label

property lin

Return Lineation of pairs as LineationSet

property lvec

Return lineation vectors of pairs as Vector3Set

property misfit

Return array of misfits

property ortensor

Return Lisle (1989) orientation tensor OrientationTensor3 of orientations defined by pairs

classmethod random(n=25)

Create PairSet of random pairs

property rax

Return vectors perpendicular to both planar and linear parts of pairs as Vector3Set

to_csv(filename, delimiter=',')

Save PairSet object to csv file

Parameters:

filename (str) – name of CSV file to save.

Keyword Arguments:

delimiter (str) – values delimiter. Default ‘,’

Note: Written values are rounded according to ndigits settings in apsg_conf

class apsg.feature.FaultSet(data, name='Default')

Bases: PairSet

Class to store set of Fault features

angle(other=None)

Return angles of all data in FaultSet object

Without arguments it returns angles of all pairs in dataset. If argument is FaultSet of same length or single data object element-wise angles are calculated.

property d

Return dihedra planes of FaultSet as FoliationSet

classmethod from_array(fazis, fincs, lazis, lincs, senses=[], name='Default')

Create FaultSet from arrays of azimuths, inclinations and senses

Parameters:

• fazis – list or array of azimuths

• fincs – list or array of inclinations

• lazis – list or array of azimuths

• lincs – list or array of inclinations

• senses – list or array of senses

Keyword Arguments:

name – name of FaultSet object. Default is ‘Default’

classmethod from_csv(filename, delimiter=',', sense_str=False, facol=0, ficol=1, lacol=2, licol=3, scol=4)

Read FaultSet from csv file

property m

Return m-planes of FaultSet as FoliationSet

property p

Return p-axes of FaultSet as LineationSet

property p_vector

Return p-axes of FaultSet as Vector3Set

classmethod random(n=25)

Create FaultSet of random faults

property sense

Return array of sense values

property sense_str

Return array of sense characters

property t

Return t-axes of FaultSet as LineationSet

property t_vector

Return t-axes of FaultSet as Vector3Set

to_csv(filename, delimiter=',', sense_str=False)

Save FaultSet object to csv file

Parameters:

filename (str) – name of CSV file to save.

Keyword Arguments:

• delimiter (str) – values delimiter. Default ‘,’

• sense_str (bool) – save sense as N, R, S or D. Default False

Note: Written values are rounded according to ndigits settings in apsg_conf

class apsg.feature.ConeSet(data, name='Default')

Bases: FeatureSet

Class to store set of Cone features

class apsg.feature.EllipseSet(data, name='Default')

Bases: FeatureSet

Class to store set of Ellipse features

property S1: ndarray

Return the array of maximum principal stretches.

property S2: ndarray

Return the array of minimum principal stretches.

property ar: ndarray

Return the array of axial ratios.

property e1: ndarray

Return the maximum natural principal strains.

property e12: ndarray

Return the array of differences between natural principal strains.

property e2: ndarray

Return the array of minimum natural principal strains.

property orientation: ndarray

Return the array of orientations of the maximum eigenvector.

transform(F)

Return transformation of all features EllipseSet by matrix ‘F’.

Parameters:

F – Transformation matrix. Array-like value e.g. DeformationGradient3

class apsg.feature.EllipsoidSet(data, name='Default')

Bases: FeatureSet

Class to store set of Ellipsoid features

property B: ndarray

Return the array of Cylindricity indexes (Vollmer, 1990).

property D: ndarray

Return the array of the strain intensities D (Ramsay, 1983)..

property G: ndarray

Return the array of Girdle indexes (Vollmer, 1990).

property Intensity: ndarray

Return the array of Intensity indexes (Lisle, 1985).

property K: ndarray

Return the array of the strain symmetries K (Ramsay, 1983).

property MAD: ndarray

Return approximate deviation according to shape

property MAD_l: ndarray

Return maximum angular deviation (MAD) of linearly distributed vectors. Kirschvink 1980

property MAD_p: ndarray

Return maximum angular deviation (MAD) of planarly distributed vectors. Kirschvink 1980

property P: ndarray

Return the array of Point indexes (Vollmer, 1990).

property R: ndarray

Return the array of Random indexes (Vollmer, 1990).

property Rxy: ndarray

Return the array of the Rxy ratios.

property Ryz: ndarray

Return the array of the Ryz ratios.

property S1: ndarray

Return the array of maximum principal stretches.

property S2: ndarray

Return the array of middle principal stretches.

property S3: ndarray

Return the array of minimum principal stretches.

property aMAD: ndarray

Return approximate deviation according to the shape

property aMAD_l: ndarray

Return approximate angular deviation from the major axis along E1.

property aMAD_p: ndarray

Return approximate deviation from the plane normal to E3.

property d: ndarray

Return the array of the strain intensities.

property e1: ndarray

Return the array of the maximum natural principal strain.

property e12: ndarray

Return the array of the e1 - e2 values.

property e13: ndarray

Return the array of the e1 - e3 values.

property e2: ndarray

Return the array of the middle natural principal strain.

property e23: ndarray

Return the array of the e2 - e3 values.

property e3: ndarray

Return the array of the minimum natural principal strain.

property eoct: ndarray

Return the array of the natural octahedral unit strains (Nadai, 1963).

property goct: ndarray

Return the array of the natural octahedral unit shears (Nadai, 1963).

property k: ndarray

Return the array of the strain symmetries.

property lode: ndarray

Return the array of Lode parameters (Lode, 1926).

property r: ndarray

Return the array of the strain intensities (Watterson, 1968).

property shape: ndarray

Return the array of the Woodcock shape.

property strength: ndarray

Return the array of the Woodcock strength.

transform(F)

Return transformation of all features EllipsoidSet by matrix ‘F’.

Args: F: Transformation matrix. Array-like value e.g. DeformationGradient3

class apsg.feature.OrientationTensor2Set(data, name='Default')

Bases: EllipseSet

Class to store set of OrientationTensor2 features

class apsg.feature.OrientationTensor3Set(data, name='Default')

Bases: EllipsoidSet

Class to store set of OrientationTensor3 features

apsg.feature.G(lst, name='Default')

Function to create appropriate container (FeatueSet) from list of features.

Parameters:

lst (list) – Homogeneous list of objects of Vector2, Vector3, Lineation, Foliation, Pair, Cone, Ellipse or OrientationTensor3.

Keyword Arguments:

name (str) – name of feature set. Default Default

Example

>>> fols = [fol(120,30), fol(130, 40), fol(126, 37)]
>>> f = G(fols)

class apsg.feature.ClusterSet(d, **kwargs)

Bases: object

Provides a hierarchical clustering using scipy.cluster routines. The distance matrix is calculated as an angle between features, where Foliation and Lineation use axial angles while Vector3 uses direction angles.

Parameters:

• azi (float) – plunge direction of linear feature in degrees

• inc (float) – plunge of linear feature in degrees

Keyword Arguments:

• maxclust (int) – Desired number of clusters. Default 2

• angle (float) – Forms flat clusters so that the original observations in each cluster have no greater angle. Default is None to use maxclust criterion.

• method (str) – Method for calculating the distance between the newly formed cluster and observations. Default is ‘average’ for UPGMA algorithm

property R

Return group of clusters resultants.

cluster(**kwargs)

Do clustering on data

Result is stored as tuple of Groups in groups property.

Keyword Arguments:

• maxclust – number of clusters

• distance – maximum cophenetic distance in clusters

dendrogram(**kwargs)

Show dendrogram

See scipy.cluster.hierarchy.dendrogram for possible kwargs.

elbow(no_plot=False, n=None)

Plot within groups variance vs. number of clusters. Elbow criterion could be used to determine number of clusters.

linkage(**kwargs)

Do linkage of distance matrix

Keyword Arguments:

method – The linkage algorithm to use

class apsg.feature.Core(**kwargs)

Bases: object

Core class to store palemomagnetic analysis data

Keyword Arguments:

• info

• specimen

• filename

• alpha

• beta

• strike

• dip

• volume

• date

• steps

• a95

• comments

• vectors

Returns:

Core object instance

property MAG

Returns numpy array of MAG values

property V

Returns Vector3Set of vectors in sample (or core) coordinates system

property datatable

Return data list of strings

classmethod from_pmd(filename)

Return Core instance generated from PMD file.

Parameters:

filename – PMD file

classmethod from_rs3(filename, exclude=['C', 'G'])

Return Core instance generated from PMD file.

Parameters:

filename – Remasoft rs3 file

Kwargs:

exclude: Labels to be excluded. Default [‘C’, ‘G’]

property geo

Returns Vector3Set of vectors in in-situ coordinates system

property nsteps

Returns steps as numpy array of numbers

pca(kind='geo', origin=False)

PCA analysis to calculate principal component and MAD

Keyword Arguments:

• kind (str) – “V”, “geo” or “tilt”. Default “geo”

• origin (bool) – Whether to include origin. Default False

show()

Show data

property tilt

Returns Vector3Set of vectors in tilt‐corrected coordinates system

write_pmd(filename=None)

Save Core instance to PMD file.

Parameters:

filename – PMD file

write_rs3(filename=None)

Save Core instance to RS3 file.

Parameters:

filename – RS3 file