feature module

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

Classes:

`Lineation`(*args)	A class to represent axial (non-oriented) linear feature (lineation).
`Foliation`(*args)	A class to represent non-oriented planar feature (foliation).
`Pair`(*args)	The class to store pair of planar and linear feature.
`Fault`(*args)	The class to store `Pair` with associated sense of movement.
`Cone`(*args)	The class to store cone with given axis, secant line and revolution angle in degrees.
`DeformationGradient3`(*args)	The class to represent 3D deformation gradient tensor.
`VelocityGradient3`(*args)	The class to represent 3D velocity gradient tensor.
`Stress3`(*args)	The class to represent 3D stress tensor.
`Ellipsoid`(*args)	The class to represent 3D ellipsoid.
`OrientationTensor3`(*args)	Represents an 3D orientation tensor, which characterize data distribution using eigenvalue method.
`DeformationGradient2`(*args)	The class to represent 2D deformation gradient tensor.
`VelocityGradient2`(*args)	The class to represent 2D velocity gradient tensor.
`Stress2`(*args)	The class to represent 2D stress tensor.
`Ellipse`(*args)	The class to represent 2D ellipse
`OrientationTensor2`(*args)	Represents an 2D orientation tensor, which characterize data distribution using eigenvalue method.
`Vector2Set`(data[, name])	Class to store set of `Vector2` 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.Lineation(*args)

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

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

property geo: Return tuple of dip direction and dip

to_json(): Return as JSON dict

dipvec(): Return dip vector

pole(): Return plane normal as vector

rake(rake): Return rake vector

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

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)

label(): Return label

to_json(): Return as JSON dict

classmethod random(): Random Pair

property fol: Return a planar feature of Pair as Foliation.

property lin: Return a linear feature of Pair as Lineation.

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

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 f and l could be Vector3 like objects, e.g. Foliation and Lineation
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) – sense of movement -/+1 hanging-wall up/down reverse/normal

fvec

corrected vector normal to plane

Type: Vector3

lvec

corrected vector of linear feature

Type: Vector3

sense

sense of movement (+/-1)

Type: int

Example

>>> fault()
>>> fault(p)
>>> fault(f, l)
>>> fault(fazi, finc, lazi, linc, sense)
>>> f = fault(140, 30, 110, 26, -1)

to_json(): Return as JSON dict

classmethod random(): Random Fault

p_vector(ptangle=90): Return P axis as Vector3

t_vector(ptangle=90): Return T-axis as Vector3.

property p: Return P-axis as Lineation

property t: Return T-axis as Lineation

property m: Return kinematic M-plane as Foliation

property d: Return dihedra plane as Fol

class apsg.feature.Cone(*args)

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)

label(): Return label

to_json(): Return as JSON dict

classmethod random(): Random Cone

apical_angle(): Return apical angle

property rotated_secant: Return revangle rotated secant vector

class apsg.feature.DeformationGradient3(*args)

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

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

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.

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

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.

rate(): Return rate of deformation tensor

spin(): Return spin tensor

class apsg.feature.Stress3(*args)

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

classmethod from_comp(xx=0, xy=0, xz=0, yy=0, yz=0, zz=0)

Return Stress tensor. Default is zero tensor.

Note that stress tensor must be 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.]]

property mean_stress: Mean stress

property hydrostatic: Mean hydrostatic stress tensor component

property deviatoric: A stress deviator tensor component

effective(fp)

A effective stress tensor reduced by fluid pressure

Parameters: fp (flot) – fluid pressure

property sigma1: A maximum principal stress (max compressive)

property sigma2: A intermediate principal stress

property sigma3: A minimum principal stress (max tensile)

property sigma1dir: Return unit length vector in direction of maximum principal stress (max compressive)

property sigma2dir: Return unit length vector in direction of intermediate principal stress

property sigma3dir: Return unit length vector in direction of minimum principal stress (max tensile)

property sigma1vec: Return maximum principal stress vector (max compressive)

property sigma2vec: Return intermediate principal stress vector

property sigma3vec: Return minimum principal stress vector (max tensile)

property I1: First invariant

property I2: Second invariant

property I3: Third invariant

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

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)

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 +

stress_comp(n): Return normal and shear stress Vector3 components on plane given by normal vector.

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.

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

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

property shape_ratio: Return shape ratio R (Gephart & Forsyth 1984)

class apsg.feature.Ellipsoid(*args)

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)

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 kind: str: Return descriptive type of ellipsoid

property strength: float: Return the Woodcock strength.

property shape: float: return the Woodcock shape.

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 e1: float: Return the maximum natural principal strain.

property e2: float: Return the middle natural principal strain.

property e3: float: Return the minimum natural principal strain.

property Rxy: float: Return the Rxy ratio.

property Ryz: float: Return the Ryz ratio.

property e12: float: Return the e1 - e2.

property e13: float: Return the e1 - e3.

property e23: float: Return the e2 - e3.

property k: float: Return the strain symmetry.

property d: float: Return the strain intensity.

property K: float: Return the strain symmetry (Ramsay, 1983).

property D: float: Return the strain intensity.

property r: float: Return the strain intensity (Watterson, 1968).

property goct: float: Return the natural octahedral unit shear (Nadai, 1963).

property eoct: float: Return the natural octahedral unit strain (Nadai, 1963).

property lode: float: Return Lode parameter (Lode, 1926).

property P: float: Point index (Vollmer, 1990).

property G: float: Girdle index (Vollmer, 1990).

property R: float: Random index (Vollmer, 1990).

property B: float: Cylindricity index (Vollmer, 1990).

property Intensity: float: Intensity index (Lisle, 1985).

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 aMAD: float: Return approximate deviation according to shape

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 MAD: float: Return maximum angular deviation (MAD)

class apsg.feature.OrientationTensor3(*args)

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

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

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

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

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.

velgrad(time=1): Return VelocityGradient2 for given time

class apsg.feature.VelocityGradient2(*args)

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.

rate(): Return rate of deformation tensor

spin(): Return spin tensor

class apsg.feature.Stress2(*args)

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

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 mean_stress: Mean stress

property hydrostatic: Mean hydrostatic stress tensor component

property deviatoric: A stress deviator tensor component

property sigma1: A maximum principal stress (max compressive)

property sigma2: A minimum principal stress

property sigma1dir: Return unit length vector in direction of maximum principal stress (max compressive)

property sigma2dir: Return unit length vector in direction of minimum principal stress

property sigma1vec: Return maximum principal stress vector (max compressive)

property sigma2vec: Return minimum principal stress vector

property I1: First invariant

property I2: Second invariant

property I3: Third invariant

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

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)

stress_comp(n): Return normal and shear stress Vector2 components on plane given by normal vector.

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.

signed_shear_stress(n): Return signed shear stress magnitude on plane given by normal vector.

class apsg.feature.Ellipse(*args)

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)

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 S1: float: Return the maximum principal stretch.

property S2: float: Return the minimum principal stretch.

property e1: float: Return the maximum natural principal strain.

property e2: float: Return the minimum natural principal strain.

property ar: float: Return the ellipse axial ratio.

property orientation: Return the orientation of the maximum eigenvector.

property e12: float: Return the difference between natural principal strains.

class apsg.feature.OrientationTensor2(*args)

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

property x: Return numpy array of x-components

property y: Return numpy array of y-components

property direction: Return array of direction angles

proj(vec): Return projections of all features in FeatureSet onto vector.

dot(vec): Return array of dot products of all features in FeatureSet with vector.

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.

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.

normalized(): Return FeatureSet object with normalized (unit length) elements.

uv(): Return FeatureSet object with normalized (unit length) elements.

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

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

fisher_statistics()

Fisher’s statistics

fisher_statistics returns dictionary with keys:: k estimated precision parameter, csd estimated angular standard deviation a95 confidence limit

var()

Spherical variance based on resultant length (Mardia 1972).

var = 1 - abs(R) / n

delta()

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

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

rdegree()

Degree of preffered orientation of vectors in FeatureSet.

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

ortensor(): Return orientation tensor Ortensor of Group.

halfspace(): Change orientation of vectors in FeatureSet, so all have angle<=90 with resultant.

classmethod from_direction(angles, name='Default')

Create FeatureSet object from arrays of direction angles

Parameters: angles – list or angles
Keyword Arguments: name – name of FeatureSet object. Default is ‘Default’

Example

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

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

Create FeatureSet 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 FeatureSet object. Default is ‘Default’

Example

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

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

Method to create FeatureSet 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 FeatureSet 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))

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

Bases: object

Base class for containers

to_json(): Return as JSON dict

label(): Return label

rotate(axis, phi): Rotate FeatureSet object phi degress about axis.

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}

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

Bases: FeatureSet

Class to store set of Vector3 features

property x: Return numpy array of x-components

property y: Return numpy array of y-components

property z: Return numpy array of z-components

property geo: Return arrays of azi and inc according to apsg_conf[‘notation’]

to_lin(): Return LineationSet object with all data converted to Lineation.

to_fol(): Return FoliationSet object with all data converted to Foliation.

to_vec(): Return Vector3Set object with all data converted to Vector3.

project(vec): Return projections of all features in FeatureSet onto vector.

proj(vec): Return projections of all features in FeatureSet onto vector.

reject(vec): Return rejections of all features in FeatureSet onto vector.

dot(vec): Return array of dot products of all features in FeatureSet with vector.

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.

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.

normalized(): Return FeatureSet object with normalized (unit length) elements.

uv(): Return FeatureSet object with normalized (unit length) elements.

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

is_upper(): Return boolean array of z-coordinate negative test

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

fisher_statistics()

Fisher’s statistics

fisher_statistics returns dictionary with keys:: k estimated precision parameter, csd estimated angular standard deviation a95 confidence limit

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

var()

Spherical variance based on resultant length (Mardia 1972).

var = 1 - abs(R) / n

delta()

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

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

rdegree()

Degree of preffered orientation of vectors in FeatureSet.

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

ortensor(): Return orientation tensor Ortensor of Group.

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

halfspace(): Change orientation of vectors in FeatureSet, so all have angle<=90 with resultant.

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) 

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

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_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])

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

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

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)

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

property fol: Return Foliations of pairs as FoliationSet

property fvec: Return planar normal vectors of pairs as Vector3Set

property lin: Return Lineation of pairs as LineationSet

property lvec: Return lineation vectors of pairs as Vector3Set

property misfit: Return array of misfits

property rax: Return vectors perpendicular to both planar and linear parts of pairs as Vector3Set

property ortensor: Return Lisle (1989) orientation tensor OrientationTensor3 of orientations defined by pairs

label(): Return label

classmethod random(n=25): Create PairSet of random pairs

classmethod from_csv(filename, delimiter=',', facol=0, ficol=1, lacol=2, licol=3): Read PairSet from csv file

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

classmethod from_array(fazis, fincs, lazis, lincs, name='Default')

Create PairSet from arrays of azimuths and inclinations

Parameters

azis – list or array of azimuths
incs – list or array of inclinations

Keyword Arguments

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

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

Bases: PairSet

Class to store set of Fault features

property sense: Return array of sense values

property p_vector: Return p-axes of FaultSet as Vector3Set

property t_vector: Return t-axes of FaultSet as Vector3Set

property p: Return p-axes of FaultSet as LineationSet

property t: Return t-axes of FaultSet as LineationSet

property m: Return m-planes of FaultSet as FoliationSet

property d: Return dihedra planes of FaultSet as FoliationSet

classmethod random(n=25): Create PairSet of random pairs

classmethod from_csv(filename, delimiter=',', facol=0, ficol=1, lacol=2, licol=3, scol=4): Read FaultSet from csv file

to_csv(filename, delimiter=',')

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

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

Create PairSet from arrays of azimuths and inclinations

Parameters

azis – list or array of azimuths
incs – list or array of inclinations

Keyword Arguments

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

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 e1: ndarray: Return the maximum natural principal strains.

property e2: ndarray: Return the array of minimum natural principal strains.

property ar: ndarray: Return the array of axial ratios.

property orientation: ndarray: Return the array of orientations of the maximum eigenvector.

property e12: ndarray: Return the array of differences between natural principal strains.

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

Bases: FeatureSet

Class to store set of Ellipsoid features

property strength: ndarray: Return the array of the Woodcock strength.

property shape: ndarray: Return the array of the Woodcock shape.

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 e1: ndarray: Return the array of the maximum natural principal strain.

property e2: ndarray: Return the array of the middle natural principal strain.

property e3: ndarray: Return the array of the minimum natural principal strain.

property Rxy: ndarray: Return the array of the Rxy ratios.

property Ryz: ndarray: Return the array of the Ryz ratios.

property e12: ndarray: Return the array of the e1 - e2 values.

property e13: ndarray: Return the array of the e1 - e3 values.

property e23: ndarray: Return the array of the e2 - e3 values.

property k: ndarray: Return the array of the strain symmetries.

property d: ndarray: Return the array of the strain intensities.

property K: ndarray: Return the array of the strain symmetries K (Ramsay, 1983).

property D: ndarray: Return the array of the strain intensities D (Ramsay, 1983)..

property r: ndarray: Return the array of the strain intensities (Watterson, 1968).

property goct: ndarray: Return the array of the natural octahedral unit shears (Nadai, 1963).

property eoct: ndarray: Return the array of the natural octahedral unit strains (Nadai, 1963).

property lode: ndarray: Return the array of Lode parameters (Lode, 1926).

property P: ndarray: Return the array of Point indexes (Vollmer, 1990).

property G: ndarray: Return the array of Girdle indexes (Vollmer, 1990).

property R: ndarray: Return the array of Random indexes (Vollmer, 1990).

property B: ndarray: Return the array of Cylindricity indexes (Vollmer, 1990).

property Intensity: ndarray: Return the array of Intensity indexes (Lisle, 1985).

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 aMAD: ndarray: Return approximate deviation according to the 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 MAD: ndarray: Return approximate deviation according to shape

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.

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

linkage(**kwargs)

Do linkage of distance matrix

Keyword Arguments: method – The linkage algorithm to use

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.

property R: Return group of clusters resultants.

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

classmethod from_pmd(filename)

Return Core instance generated from PMD file.

Parameters: filename – PMD file

write_pmd(filename=None)

Save Core instance to 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’]

write_rs3(filename=None)

Save Core instance to RS3 file.

Parameters: filename – RS3 file

property datatable: Return data list of strings

show(): Show data

property MAG: Returns numpy array of MAG values

property nsteps: Returns steps as numpy array of numbers

property V: Returns Vector3Set of vectors in sample (or core) coordinates system

property geo: Returns Vector3Set of vectors in in-situ coordinates system

property tilt: Returns Vector3Set of vectors in tilt‐corrected coordinates system

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