feature module

The apsg.feature module provides classes to store and analyze structural geology data. It includes representations of planar and linear features (Foliation, Lineation, Fault, Cone, Pair), their corresponding sets (FoliationSet, LineationSet, etc.), tensor classes (Stress3, Ellipsoid, OrientationTensor3), and higher-level analysis tools like ClusterSet for clustering of orientation data.

The main APSG namespace provides lowercase aliases for commonly used classes (e.g. fol for Foliation, lin for Lineation, vec for Vector3). See Welcome to APSG’s documentation! for the full list.

Usage

Create individual features:

>>> from apsg import fol, lin, fault, pair, cone, vec
>>> f = fol(120, 30)                 # dip direction=120, dip=30
>>> l = lin(210, 45)                 # trend=210, plunge=45
>>> f2 = fault(120, 30, 80, 20, 1)   # dip direction, dip, trend, plunge, sense
>>> p = pair(300, 20, 200, 60)       # dip direction, dip, trend, plunge
>>> c = cone(vec(45, 30), 20)        # axis + half-angle

Create sets of features for batch analysis:

>>> from apsg import folset, linset, vecset
>>> fols = folset.random_fisher(position=f, kappa=50, n=30)
>>> lins = linset.random_fisher(position=l, kappa=100, n=30)
>>> vecs = vecset.uniform_gss(n=50)

Analyze orientation data:

>>> ot = fols.ortensor()
>>> ot.eigenvalues()
>>> ot.eigenvectors()
>>> fols.fisher_statistics()

Cluster analysis:

>>> from apsg import cluster
>>> cs = cluster(fols)
>>> cs.cluster(k=3)

Tensor analysis:

>>> from apsg import ellipsoid, stress, ortensor
>>> e = ellipsoid.from_stretch(2, 1, 0.5)
>>> s = stress.from_ratio(r=0.5, mag=1)
>>> ot = ortensor.from_features(fols)

Serialization:

>>> from apsg.feature import feature_from_json
>>> data = f.to_json()
>>> f2 = feature_from_json(data)
>>> fols.to_csv('foliations.csv')

Classes:

`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.
`Rotation3`(args, *kwargs)	The class to represent 3D rotation matrix.
`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.
`Rotation2`(args, *kwargs)	The class to represent 2D rotation matrix.
`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.
`Stress3Set`(data[, name])	Class to store set of `Stress3` 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.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.

Examples

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

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.

Examples

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

Examples

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

strike(): Return strike as Direction.

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

Examples

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

Returns:: The transformed foliation.
Return type:: Foliation

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

Examples

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

property rake: Return a rake of linear feature on planar feature of Pair in degrees.

classmethod random(): Random Pair.

rotate(axis, phi)

Rotates Pair by angle phi about axis.

Parameters:

axis (Vector3) – axis of rotation
phi (float) – angle of rotation in degrees

Examples

>>> p = pair(fol(140, 30), lin(110, 26))
>>> p.rotate(lin(40, 50), 120)
P:210/83-287/60

Returns:: The rotated pair.
Return type:: 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

Examples

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

Returns:: The transformed pair.
Return type:: Pair

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 3 arguments fazi, finc, rake
with 5 arguments fazi, finc, lazi, linc, 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

Examples

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

angular_misfit(sigma)

Angular misfit (°) between observed slip and predicted shear-traction direction.

Parameters:: sigma (Stress3) – Stress tensor
Returns:: The angular misfit in degrees.
Return type:: float

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

Parameters:

*args – Variable length argument list. See descriptions above.
**kwargs – Additional keyword arguments.

axis

axis of the cone

Type:: Vector3

secant

secant line

Type:: Vector3

revangle

revolution angle

Type:: float

Examples

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

rotate(axis, phi)

Rotates Cone by angle phi about axis.

Parameters:

axis (Vector3) – axis of rotation
phi (float) – angle of rotation in degrees

Examples

>>> c = cone(lin(140, 30), lin(110, 26), 360)
>>> c.rotate(lin(40, 50), 120)
C:210/83-287/60

Returns:: The rotated cone.
Return type:: 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.

Examples

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

property V: Return stretching part of DeformationGradient3 from left polar.

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

Examples

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

Returns:: DeformationGradient3 defined by individual components.
Return type:: DeformationGradient3

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

Examples

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

Returns:: isochoric DeformationGradient3 tensor with axial stretches.
Return type:: DeformationGradient3

is_rotation(): Return True if DeformationGradient3 is rotation.

velgrad(time=1)

Return VelocityGradient3 calculated as matrix logarithm divided by given time.

Keyword Arguments:: time (float) – total time. Default 1

Examples

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

Returns:: VelocityGradient3 calculated as matrix logarithm divided by given time.
Return type:: VelocityGradient3

class apsg.feature.Rotation3(*args, **kwargs)

Bases: DeformationGradient3

The class to represent 3D rotation matrix.

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

Examples

>>> R = rotation.from_axisangle(lin(120, 60), 50)

angle(): Return rotation angle.

axisangle(): Return rotation as (axis, angle) tuple.

euler(seq)

Return rotation as Euler angles specified in degrees.

Note: Each character in seq defines one axis around which angles turns.

Parameters:: seq (str) – sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations.
Returns:: rotation as Euler angles specified in degrees.
Return type:: ndarray

classmethod from_axisangle(vector, theta)

Return Rotation3 representing rotation around axis.

Parameters:

vector – Rotation axis as Vector3 like object
theta – Angle of rotation in degrees

Examples

>>> F = rotation.from_axisangle(lin(120, 30), 45)

Returns:: Rotation3 representing rotation around axis.
Return type:: Rotation3

classmethod from_declination(lat, lon, year=None, alt=0)

Return Rotation3 representing rotation of coordinates correcting magnetic declination at given coordinates and given time.

Parameters:

lat (float) – latitude
lon (float) – longitude

Keyword Arguments:

year (float) – decimal year
alt (float) – altitude in km

Examples

>>> R = rotation.from_declination(48.6, 13.2, alt=0.6)
>>> f = fol(20, 48)
>>> f.transform(R)
S:25/48

Returns:: Rotation3 representing rotation of coordinates correcting magnetic declination.
Return type:: Rotation3

classmethod from_euler(seq, angles)

Return Rotation3 representing rotation of coordinates created from unit norm quaternion.

Parameters:

seq (str) – sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations.
angles (array_like) – Euler angles specified in degrees. Each character in seq defines one axis around which angles turns.

Examples

>>> R = rotation.from_euler('zxz', [30,-64, 125])
>>> f = fol(20, 48)
>>> f.transform(R)
S:74/70

Returns:: Rotation3 representing rotation of coordinates created from Euler angles.
Return type:: Rotation3

classmethod from_pair(p)

Return Rotation3 representing rotation defined by Pair.

Rotation bring x-axis to lineation and z-axis to normal to plane.

Parameters:: p (Pair) – Pair object

Examples

>>> p = pair(40, 20, 75, 16)
>>> F = defgrad.from_pair(p)

Returns:: Rotation3 representing rotation defined by Pair.
Return type:: Rotation3

classmethod from_quat(quat, scalar_first=False)

Return Rotation3 representing rotation of coordinates created from unit norm quaternion.

Parameters:: quat (array_like) – quaternion
Keyword Arguments:: scalar_first (bool) – Whether the scalar component goes first or last. Default is False

Examples

>>> q = [-0.11543715, 0.19994301, 0.39988603, 0.88701083]
>>> R = rotation.from_quat(q)
>>> f = fol(20, 48)
>>> f.transform(R)
S:82/23

Returns:: Rotation3 representing rotation of coordinates created from unit norm quaternion.
Return type:: Rotation3

classmethod from_two_pairs(p1, p2, symmetry=False)

Return Rotation3 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

Examples

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

Returns:: Rotation3 representing rotation of coordinates from system defined by Pair.
Return type:: Rotation3

classmethod from_two_vectors(v1, v2)

Return Rotation3 representing rotation around axis perpendicular to both vectors and rotate v1 to v2.

Parameters:

v1 – Vector3 like object
v2 – Vector3 like object

Examples

>>> F = rotation.from_two_vectors(lin(120, 30), lin(210, 60))

Returns:: Rotation3 representing rotation around axis perpendicular to both vectors.
Return type:: Rotation3

classmethod from_vectors_axis(v1, v2, a)

Return Rotation3 representing rotation of vector v1 to v2 around axis a.

If v1.angle(a) is not equal to v2.angle(b), the minimum adjustment of rotation axis is done automatically.

Parameters:

v1 – Vector3 like object
v2 – Vector3 like object
a – estimated rotation axis Vector3 like object

Examples

>>> v1 = lin(130, 49)
>>> v2 = lin(209, 77)
>>> a = lin(30, 30)
>>> R = rotation.from_vectors_axis(v1, v2, a)
>>> v1.transform(R) == v2
True
>>> a_fix, theta = R.axisangle()
>>> lin(a_fix)
L:31/30

Returns:: Rotation3 representing rotation of vector v1 to v2 around axis a.
Return type:: Rotation3

quat(scalar_first=False)

Return rotation as quaternion.

Keyword Arguments:: scalar_first (bool) – Whether the scalar component goes first or last. Default is False
Returns:: rotation as quaternion.
Return type:: ndarray

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.

Examples

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

Returns:

DeformationGradient3 tensor accumulated after given time.

Return type:

DeformationGradient3

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

Examples

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

Returns:: VelocityGradient3 defined by individual components. Default is zero tensor.
Return type:: VelocityGradient3

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.

Examples

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

Examples

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

Returns:: stress vector associated with plane given by normal vector.
Return type:: Vector3

property deviatoric: A stress deviator tensor component.

property diagonalized: Returns diagonalized Stress tensor and orthogonal matrix R, which transforms 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
Returns:: dilation tendency of the plane.
Return type:: float

effective(fp)

Return effective stress tensor reduced by fluid pressure.

Parameters:: fp (flot) – fluid pressure
Returns:: effective stress tensor reduced by fluid pressure.
Return type:: Stress3

fault(n)

Return Fault object derived from given by normal vector.

Parameters:: n – normal given as Vector3 or Foliation object

Examples

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

Returns:: Fault object derived from given by normal vector.
Return type:: Fault

classmethod from_comp(**kwargs)

Return Stress tensor. Default is zero tensor.

Note that stress tensor is always symmetrical.

Keyword Arguments:: zz (xx, xy|yx, xz|zx, yy, yz|zy,) – tensor components

Examples

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

Returns:: Stress tensor. Default is zero tensor.
Return type:: Stress3

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.

Examples

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

Returns:: Stress tensor with given shape ration.
Return type:: Stress3

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.

Returns:: normal stress magnitude on plane given by normal vector.
Return type:: float

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

shear_stress(n)

Return shear stress magnitude on plane given by normal vector.

Returns:: shear stress magnitude on plane given by normal vector.
Return type:: float

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

property sigma1dir: Return unit length vector in direction of maximum.

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.

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.

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

Returns:

slip tendency calculated as the ratio of shear stress to normal stress.

Return type:

float

stress_comp(n)

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

Returns:: normal and shear stress Vector3 components.
Return type:: tuple

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.

Examples

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

property MAD_p: float: Return maximum angular deviation (MAD) of planarly distributed vectors.

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

Parameters:

F – DeformationGradient3 tensor
form – ‘left’ or ‘B’ for left Cauchy–Green (Finger) deformation tensor, ‘right’ or ‘C’ for right Cauchy–Green (Green’s) deformation tensor. Default ‘left’.

Returns:

deformation tensor from Defgrad3.

Return type:

Ellipsoid

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)

Examples

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

Examples

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

Returns:: orientation tensor of data in Vector3Set of features.
Return type:: OrientationTensor3

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

Examples

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

Returns:: Lisle (1989) orientation tensor of orthogonal data in PairSet.
Return type:: OrientationTensor3

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:: 2D deformation gradient tensor.
Return type:: DeformationGradient2

Examples

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

classmethod from_comp(**kwargs)

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

Examples

>>> F = defgrad2.from_comp(xy=2)
>>> F
DeformationGradient2
[[1. 2.]
 [0. 1.]]

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

Examples

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

is_rotation(): Return True if DeformationGradient3 is rotation.

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

class apsg.feature.Rotation2(*args, **kwargs)

Bases: DeformationGradient2

The class to represent 2D rotation matrix.

Parameters:: a (2x2 array_like) – Input data, that can be converted to 2x2 2D array. This includes lists, tuples and ndarrays.
Returns:: 2D rotation matrix.
Return type:: Rotation2

Examples

>>> R = rotation2.from_angle(lin(120, 60), 50)

angle(): Return rotation angle.

classmethod from_angle(theta)

Return Rotation2 representing rotation by angle theta.

Parameters:: theta – Angle of rotation in degrees

Examples

>>> F = rotation2.from_angle(45)
>>> F
Rotation2
[[ 0.707 -0.707]
 [ 0.707  0.707]]

classmethod from_two_vectors(v1, v2)

Return rotation2 representing rotation around axis perpendicular to both vectors and rotate v1 to v2.

Parameters:

v1 – Vector2 like object
v2 – Vector2 like object

Examples

>>> F = rotation2.from_two_vectors(vec2(1, 1), vec2(0, 1))
>>> F
Rotation2
[[ 0.707 -0.707]
 [ 0.707  0.707]]

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:: 2D velocity gradient tensor.
Return type:: VelocityGradient2

Examples

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

Returns:

DeformationGradient2 tensor accumulated after given time.

Return type:

DeformationGradient2

classmethod from_comp(**kwargs)

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

Examples

>>> L = velgrad2.from_comp(xy=2)
>>> L
VelocityGradient2
[[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:: 2D stress tensor.
Return type:: Stress2

Examples

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

Examples

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

Returns:: stress vector associated with plane given by normal vector.
Return type:: Vector2

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(**kwargs)

Return Stress2 tensor. Default is zero tensor.

Note that stress tensor must be symmetrical.

Keyword Arguments:: yy (xx, xy|yx,) – tensor components

Examples

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

Returns:: normal stress magnitude on plane given by normal vector.
Return type:: float

shear_stress(n)

Return shear stress magnitude on plane given by normal vector.

Returns:: shear stress magnitude on plane given by normal vector.
Return type:: float

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.

Returns:: signed shear stress magnitude on plane given by normal vector.
Return type:: float

stress_comp(n)

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

Returns:: normal and shear stress Vector2 components.
Return type:: tuple

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:: 2D ellipse object.
Return type:: Ellipse

Examples

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

Parameters:: 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’.
Returns:: deformation tensor from Defgrad2.
Return type:: Ellipse

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:: 2D orientation tensor object.
Return type:: OrientationTensor2

Examples

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

Examples

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

Returns:: orientation tensor of data in Vector2Set features.
Return type:: OrientationTensor2

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
Returns:: The resultant vector.
Return type:: Vector2

angle(other=None): Return angles of all data in Vector2Set object.

cross(other=None): Return cross products of all features in Vector2Set.

delta(): Cone angle containing ~63% of the data in degrees.

property direction: Return array of direction angles.

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

fisher_statistics(level=0.95)

Fisher’s statistics.

Parameters:

level – confidence level. Default 0.95 for 95 %.

Returns:

with keys mu (mean axis), k (precision parameter),: csd (angular standard deviation), alpha (confidence cone half-angle), and uniform (Rayleigh test result).

Return type:

dict

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

Examples

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

Returns:: The created feature set.
Return type:: Vector2Set

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

Examples

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

Returns:: The created feature set.
Return type:: Vector2Set

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

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

Examples

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

Returns:: The created feature set.
Return type:: Vector2Set

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

Examples

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

Returns:: The created feature set.
Return type:: Vector2Set

rdegree(): Degree of preffered orientation of vectors in Vector2Set.

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
Returns:: The transformed feature set.
Return type:: Vector2Set

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

var(): Spherical variance based on resultant length (Mardia 1972).

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, replace=True)

Return generator of bootstraped samples from FeatureSet.

Parameters:

n (int) – number of samples to be generated. Default 100.
size (int) – number of data in sample. Default is same as FeatureSet.
replace (bool) – Whether the sample is with or without replacement. Default is True.

Examples

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

Returns:: generator of bootstraped samples from FeatureSet.
Return type:: generator

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
Returns:: The resultant vector.
Return type:: Vector3

align(other): Return best estimate rotation as DeformationGradient3 to align with others.

angle(other=None): Return angles of all data in FeatureSet object.

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.
Returns:: The rotated feature set.
Return type:: FeatureSet

cross(other=None): Return cross products of all features in FeatureSet.

delta(): Cone angle containing ~63% of the data in degrees.

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

fisher_cone(level=0.95)

Confidence limit cone based on Fisher’s statistics.

Parameters:: level – confidence level. Default 0.95 for 95 %.
Returns:: Confidence cone around the mean direction with given level.
Return type:: Cone

fisher_cone_csd(): Angular standard deviation cone based on Fisher’s statistics.

fisher_statistics(level=0.95)

Fit Fisher distribution and return statistics.

Parameters:

level – confidence level. Default 0.95 for 95 %.

Returns:

with keys mu (mean axis), k (precision parameter),: csd (angular standard deviation), alpha (confidence cone half-angle), and uniform (Rayleigh test result).

Return type:

dict

Note

Calculated alpha for level 0.95 means, you can be 95% confident that the true population mean axis lies within alpha degrees of the mu.

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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.

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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.

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

rdegree(): Degree of preffered orientation of vectors in FeatureSet.

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

similarity(other, **kwargs)

Tests whether two sets of 3D vectors are sampled from the same distribution. H0 hypothesis is that two samples are from same distribution.

Note on methods:

Hotelling’s T² Test: Parametric. Multivariate generalisation of the: two-sample t-test. Sensitive to differences in mean but assumes multivariate normality.
Energy Distance Test: Non-parametric permutation test based on the: energy statistic (Székely & Rizzo 2004). Detects any distributional difference (mean, variance, shape, etc.).
MMD Test (RBF kernel): Non-parametric permutation test using Maximum: Mean Discrepancy with a Gaussian kernel. Also detects arbitrary distributional differences.

Parameters:

method – One of “hotelling”, “energy_distance” or “mmd”.
alpha – significance level. Default 0.05.
n_permutations – Number of permutations. Default 999.
random_state – Random state. Default 42.
bandwidth – Bandwidth for RBF kernel. Default None for median heuristic.

Returns:

(statistic, p-value, reject_H0) where reject_H0 is False for different distributions.

Return type:

tuple

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.

Returns:: None

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
Returns:: The transformed feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

Examples

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

Returns:: The created feature set.
Return type:: FeatureSet

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

var(): Spherical variance based on resultant length (Mardia 1972).

watson_statistics(level=0.95)

Fit Watson distribution and return statistics.

Parameters:

level – confidence level. Default 0.95 for 95 %.

Returns:

with keys mu (mean axis), k (precision parameter),: and alpha (confidence cone half-angle).

Return type:

dict

Note

Calculated alpha for level 0.95 means, you can be 95% confident that the true population mean axis lies within alpha degrees of the mu.

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.

strike(): Return Direction2Set object with strikes of planar features.

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.

property fol: Return Foliations of pairs as FoliationSet.

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

Create PairSet 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’.

Returns:

The created feature set.

Return type:

PairSet

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.

ortensor(): Return Lisle (1989) orientation tensor OrientationTensor3 of orientations.

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

property rax: Return vectors perpendicular to both planar and linear parts.

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.

Returns:: None

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.

angular_misfit(sigma)

Angular misfit (°) between observed slip and predicted shear-traction direction.

Parameters:: sigma (Stress3) – Stress tensor
Returns:: Array of angular misfits in degrees.
Return type:: np.ndarray

property d: Return dihedra planes of FaultSet as FoliationSet.

classmethod from_array(fazis, fincs, lazis, lincs, senses=None, 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’.

Returns:

The created feature set.

Return type:

FaultSet

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.

p_vector(ptangle=90): 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.

stress_inversion(bootstrap=False, n=100)

Stress inversion from fault-slip data.

The 4-D inversion method developed by Michael (1984) is a classic approach in structural geology. It determines the orientation of the principal stress axes (σ1, σ2, σ3) and the stress ratio R by assuming that the slip on a fault occurs in the direction of the maximum resolved shear stress.

Parameters:

bootstrap (bool) – When True return set of stress tensors.
n (int) – number of boostrapped samples. Default 100.

Returns:

Stress inversion from fault-slip data.

Return type:

Stress3

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

t_vector(ptangle=90): 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.

Returns:: None

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
Returns:: The transformed feature set.
Return type:: EllipseSet

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.

property MAD_p: ndarray: Return maximum angular deviation (MAD) of planarly distributed vectors.

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

Parameters:: F – Transformation matrix. Array-like value e.g. DeformationGradient3
Returns:: The transformed feature set.
Return type:: EllipsoidSet

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.

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

Bases: FeatureSet

Class to store set of Stress3 features.

property sigma1: ndarray: Return the array of the maximum principal stress (max compressive).

property sigma1dir: Vector3Set: Return Vector3Set of unit length vector in direction of maximum.

property sigma2: ndarray: Return the array of the intermediate principal stress (max compressive).

property sigma2dir: Vector3Set: Return Vector3Set of unit length vector in direction of intermediate.

property sigma3: ndarray: Return the array of the minimum principal stress (max tensile).

property sigma3dir: Vector3Set: Return Vector3Set of unit length vector in direction of minimum.

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.

Examples

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

Returns:: The created container.
Return type:: FeatureSet

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:

d (FeatureSet) – Data to cluster, e.g. Vector3Set, Vector2Set or PairSet.

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.

Returns:

None

dendrogram(**kwargs): Show dendrogram.

elbow(no_plot=False, n=None): Plot within groups variance vs. number of clusters.

linkage(**kwargs)

Do linkage of distance matrix.

Keyword Arguments:: method – The linkage algorithm to use.
Returns:: None

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.

Return type:

Core

property MAG: Return numpy array of MAG values.

property V: Return 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
Returns:: Core instance generated from PMD file.
Return type:: Core

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

Return Core instance generated from PMD file.

Parameters:: filename – Remasoft rs3 file
Keyword Arguments:: exclude – Labels to be excluded. Default [‘C’, ‘G’]
Returns:: Core instance generated from RS3 file.
Return type:: Core

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

property nsteps: Return 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

Returns:

principal component and MAD.

Return type:

tuple

show(): Show data.

property tilt: Return Vector3Set of vectors in tilt-corrected coordinates system.

write_pmd(filename=None)

Save Core instance to PMD file.

Parameters:: filename – PMD file
Returns:: Core instance saved to PMD file.
Return type:: Core

write_rs3(filename=None)

Save Core instance to RS3 file.

Parameters:: filename – RS3 file