mplstereonet Package¶

`mplstereonet` Package¶

class mplstereonet.StereonetAxes(*args, **kwargs)[source]¶

Bases: matplotlib.projections.geo.LambertAxes

An axes representing a lower-hemisphere “schmitt” (a.k.a. equal area) projection.

__init__(self, *args, **kwargs)[source]¶

Initialization is identical to a normal Axes object except for the following kwarg:

Parameters:	rotation : number The rotation of the stereonet in degrees clockwise from North. center_latitude : number The center latitude of the stereonet in degrees. center_longitude : number The center longitude of the stereonet in degrees. All additional args and kwargs are identical to Axes.__init__

cla(self)[source]¶: Clear the current axes.

cone(self, plunge, bearing, angle, segments=100, bidirectional=True, **kwargs)[source]¶

Plot a polygon of a small circle (a.k.a. a cone) with an angular radius of angle centered at a p/b of plunge, bearing. Additional keyword arguments are passed on to the PathCollection. (e.g. to have an unfilled small small circle, pass “facecolor=’none’”.)

Parameters:

plunge : number or sequence of numbers: The plunge of the center of the cone in degrees.
bearing : number or sequence of numbers: The bearing of the center of the cone in degrees.
angle : number or sequence of numbers: The angular radius of the cone in degrees.
segments : int, optional: The number of vertices to use for the cone. Defaults to 100.
bidirectional : boolean, optional: Whether or not to draw two patches (the one given and its antipode) for each measurement. Defaults to True.
**kwargs: Additional parameters are matplotlib.collections.PatchCollection properties.

Returns:

collection : matplotlib.collections.PathCollection

Notes

If bidirectional is True, two circles will be plotted, even if only one of each pair is visible. This is the default behavior.

density_contour(self, *args, **kwargs)[source]¶

Estimates point density of the given linear orientation measurements (Interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument.) and plots contour lines of the resulting density distribution.

Parameters:

*args : A variable number of sequences of measurements.

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for contouring.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

method : string, optional

The method of density estimation to use. Defaults to "exponential_kamb". May be one of the following:

"exponential_kamb" : Kamb with exponential smoothing: A modified Kamb method using exponential smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"linear_kamb" : Kamb with linear smoothing: A modified Kamb method using linear smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"kamb" : Kamb with no smoothing: Kamb’s method [2] with no smoothing. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"schmidt" : 1% counts: The traditional “Schmidt” (a.k.a. 1%) method. Counts points within a counting circle comprising 1% of the total area of the hemisphere. Does not take into account sample size. Units are in points per 1% area.

sigma : int or float, optional

The number of standard deviations defining the expected number of standard deviations by which a random sample from a uniform distribution of points would be expected to vary from being evenly distributed across the hemisphere. This controls the size of the counting circle, and therefore the degree of smoothing. Higher sigmas will lead to more smoothing of the resulting density distribution. This parameter only applies to Kamb-based methods. Defaults to 3.

gridsize : int or 2-item tuple of ints, optional

The size of the grid that the density is estimated on. If a single int is given, it is interpreted as an NxN grid. If a tuple of ints is given it is interpreted as (nrows, ncols). Defaults to 100.

weights : array-like, optional

The relative weight to be applied to each input measurement. The array will be normalized to sum to 1, so absolute value of the weights do not affect the result. Defaults to None.

**kwargs

Additional keyword arguments are passed on to matplotlib’s contour function.

Returns:

A matplotlib ContourSet.

See also

mplstereonet.density_grid
mplstereonet.StereonetAxes.density_contourf
matplotlib.pyplot.contour
matplotlib.pyplot.clabel

References

[1]	(1, 2, 3) Vollmer, 1995. C Program for Automatic Contouring of Spherical Orientation Data Using a Modified Kamb Method. Computers & Geosciences, Vol. 21, No. 1, pp. 31–49.

[2]	(1, 2) Kamb, 1959. Ice Petrofabric Observations from Blue Glacier, Washington, in Relation to Theory and Experiment. Journal of Geophysical Research, Vol. 64, No. 11, pp. 1891–1909.

Examples

Plot density contours of poles to the specified planes using a modified Kamb method with exponential smoothing [1].

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contour(strikes, dips)

Plot density contours of a set of linear orientation measurements.

>>> plunges, bearings = [-10, 20, -30], [120, 315, 86]
>>> ax.density_contour(plunges, bearings, measurement='lines')

Plot density contours of a set of rake measurements.

>>> strikes, dips, rakes = [120, 315, 86], [22, 85, 31], [-5, 20, 9]
>>> ax.density_contour(strikes, dips, rakes, measurement='rakes')

Plot density contours of a set of “raw” longitudes and latitudes.

>>> lon, lat = np.radians([-40, 30, -85]), np.radians([21, -59, 45])
>>> ax.density_contour(lon, lat, measurement='radians')

Plot density contours of poles to planes using a Kamb method [2] with the density estimated on a 10x10 grid (in long-lat space)

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contour(strikes, dips, method='kamb', gridsize=10)

Plot density contours of poles to planes with contours at [1,2,3] standard deviations.

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contour(strikes, dips, levels=[1,2,3])

density_contourf(self, *args, **kwargs)[source]¶

Estimates point density of the given linear orientation measurements (Interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument.) and plots filled contours of the resulting density distribution.

Parameters:

*args : A variable number of sequences of measurements.

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for contouring.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

method : string, optional

The method of density estimation to use. Defaults to "exponential_kamb". May be one of the following:

"exponential_kamb" : Kamb with exponential smoothing: A modified Kamb method using exponential smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"linear_kamb" : Kamb with linear smoothing: A modified Kamb method using linear smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"kamb" : Kamb with no smoothing: Kamb’s method [2] with no smoothing. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"schmidt" : 1% counts: The traditional “Schmidt” (a.k.a. 1%) method. Counts points within a counting circle comprising 1% of the total area of the hemisphere. Does not take into account sample size. Units are in points per 1% area.

sigma : int or float, optional

The number of standard deviations defining the expected number of standard deviations by which a random sample from a uniform distribution of points would be expected to vary from being evenly distributed across the hemisphere. This controls the size of the counting circle, and therefore the degree of smoothing. Higher sigmas will lead to more smoothing of the resulting density distribution. This parameter only applies to Kamb-based methods. Defaults to 3.

gridsize : int or 2-item tuple of ints, optional

The size of the grid that the density is estimated on. If a single int is given, it is interpreted as an NxN grid. If a tuple of ints is given it is interpreted as (nrows, ncols). Defaults to 100.

weights : array-like, optional

The relative weight to be applied to each input measurement. The array will be normalized to sum to 1, so absolute value of the weights do not affect the result. Defaults to None.

**kwargs

Additional keyword arguments are passed on to matplotlib’s contourf function.

Returns:

A matplotlib QuadContourSet.

See also

mplstereonet.density_grid
mplstereonet.StereonetAxes.density_contour
matplotlib.pyplot.contourf
matplotlib.pyplot.clabel

References

[1]	(1, 2, 3) Vollmer, 1995. C Program for Automatic Contouring of Spherical Orientation Data Using a Modified Kamb Method. Computers & Geosciences, Vol. 21, No. 1, pp. 31–49.

[2]	(1, 2) Kamb, 1959. Ice Petrofabric Observations from Blue Glacier, Washington, in Relation to Theory and Experiment. Journal of Geophysical Research, Vol. 64, No. 11, pp. 1891–1909.

Examples

Plot filled density contours of poles to the specified planes using a modified Kamb method with exponential smoothing [1].

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contourf(strikes, dips)

Plot filled density contours of a set of linear orientation measurements.

>>> plunges, bearings = [-10, 20, -30], [120, 315, 86]
>>> ax.density_contourf(plunges, bearings, measurement='lines')

Plot filled density contours of a set of rake measurements.

>>> strikes, dips, rakes = [120, 315, 86], [22, 85, 31], [-5, 20, 9]
>>> ax.density_contourf(strikes, dips, rakes, measurement='rakes')

Plot filled density contours of a set of “raw” longitudes and latitudes.

>>> lon, lat = np.radians([-40, 30, -85]), np.radians([21, -59, 45])
>>> ax.density_contourf(lon, lat, measurement='radians')

Plot filled density contours of poles to planes using a Kamb method [2] with the density estimated on a 10x10 grid (in long-lat space)

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contourf(strikes, dips, method='kamb', gridsize=10)

Plot filled density contours of poles to planes with contours at [1,2,3] standard deviations.

>>> strikes, dips = [120, 315, 86], [22, 85, 31]
>>> ax.density_contourf(strikes, dips, levels=[1,2,3])

format_coord(self, x, y)[source]¶: Format displayed coordinates during mouseover of axes.

get_azimuth_ticklabels(self, minor=False)[source]¶: Get the azimuth tick labels as a list of Text artists.

get_rotation(self)[source]¶: The rotation of the stereonet in degrees clockwise from North.

grid(self, b=None, which='major', axis='both', kind='arbitrary', center=None, **kwargs)[source]¶

Usage is identical to a normal axes grid except for the kind and center kwargs. kind="polar" will add a polar overlay.

The center and kind arguments allow you to add a grid from a differently-centered stereonet. This is useful for making “polar stereonets” that still use the same coordinate system as a standard stereonet. (i.e. a plane/line/whatever will have the same representation on both, but the grid is displayed differently.)

To display a polar grid on a stereonet, use kind="polar".

It is also often useful to display a grid relative to an arbitrary measurement (e.g. a lineation axis). In that case, use the lon_center and lat_center arguments. Note that these are in radians in “stereonet coordinates”. Therefore, you’ll often want to use one of the functions in stereonet_math to convert a line/plane/rake into the longitude and latitude you’d input here. For example: add_overlay(center=stereonet_math.line(plunge, bearing)).

If no parameters are specified, this is equivalent to turning on the standard grid. Configure the grid lines.

Parameters:

b : bool or None, optional

Whether to show the grid lines. If any kwargs are supplied, it is assumed you want the grid on and b will be set to True.

If b is None and there are no kwargs, this toggles the visibility of the lines.

which : {‘major’, ‘minor’, ‘both’}, optional

The grid lines to apply the changes on.

axis : {‘both’, ‘x’, ‘y’}, optional

The axis to apply the changes on.

**kwargs : .Line2D properties

Define the line properties of the grid, e.g.:

grid(color='r', linestyle='-', linewidth=2)

Valid keyword arguments are:

Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: float or None animated: bool antialiased or aa: bool clip_box: .Bbox clip_on: bool clip_path: Patch or (Path, Transform) or None color or c: color contains: callable dash_capstyle: {‘butt’, ‘round’, ‘projecting’} dash_joinstyle: {‘miter’, ‘round’, ‘bevel’} dashes: sequence of floats (on/off ink in points) or (None, None) data: (2, N) array or two 1D arrays drawstyle or ds: {‘default’, ‘steps’, ‘steps-pre’, ‘steps-mid’, ‘steps-post’}, default: ‘default’ figure: .Figure fillstyle: {‘full’, ‘left’, ‘right’, ‘bottom’, ‘top’, ‘none’} gid: str in_layout: bool label: object linestyle or ls: {‘-‘, ‘–’, ‘-.’, ‘:’, ‘’, (offset, on-off-seq), …} linewidth or lw: float marker: marker style markeredgecolor or mec: color markeredgewidth or mew: float markerfacecolor or mfc: color markerfacecoloralt or mfcalt: color markersize or ms: float markevery: None or int or (int, int) or slice or List[int] or float or (float, float) path_effects: .AbstractPathEffect picker: float or callable[[Artist, Event], Tuple[bool, dict]] pickradius: float rasterized: bool or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None solid_capstyle: {‘butt’, ‘round’, ‘projecting’} solid_joinstyle: {‘miter’, ‘round’, ‘bevel’} transform: matplotlib.transforms.Transform url: str visible: bool xdata: 1D array ydata: 1D array zorder: float

Notes

The axis is drawn as a unit, so the effective zorder for drawing the grid is determined by the zorder of each axis, not by the zorder of the .Line2D objects comprising the grid. Therefore, to set grid zorder, use .set_axisbelow or, for more control, call the ~matplotlib.axis.Axis.set_zorder method of each axis.

line(self, plunge, bearing, *args, **kwargs)[source]¶

Plot points representing linear features on the axes. Additional arguments and keyword arguments are passed on to plot.

Parameters:	plunge, bearing : number or sequence of numbers The plunge and bearing of the line(s) in degrees. The plunge is measured in degrees downward from the end of the feature specified by the bearing. **kwargs Additional parameters are passed on to plot.
Returns:	A sequence of Line2D artists representing the point(s) specified by strike and dip.

plane(self, strike, dip, *args, **kwargs)[source]¶

Plot lines representing planes on the axes. Additional arguments and keyword arguments are passed on to ax.plot.

Parameters:	strike, dip : number or sequences of numbers The strike and dip of the plane(s) in degrees. The dip direction is defined by the strike following the “right-hand rule”. segments : int, optional The number of vertices to use for the line. Defaults to 100. **kwargs Additional parameters are passed on to plot.
Returns:	A sequence of Line2D artists representing the lines specified by strike and dip.

pole(self, strike, dip, *args, **kwargs)[source]¶

Plot points representing poles to planes on the axes. Additional arguments and keyword arguments are passed on to ax.plot.

Parameters:	strike, dip : numbers or sequences of numbers The strike and dip of the plane(s) in degrees. The dip direction is defined by the strike following the “right-hand rule”. **kwargs Additional parameters are passed on to plot.
Returns:	A sequence of Line2D artists representing the point(s) specified by strike and dip.

rake(self, strike, dip, rake_angle, *args, **kwargs)[source]¶

Plot points representing lineations along planes on the axes. Additional arguments and keyword arguments are passed on to plot.

Parameters:

strike, dip : number or sequences of numbers: The strike and dip of the plane(s) in degrees. The dip direction is defined by the strike following the “right-hand rule”.
rake_angle : number or sequences of numbers: The angle of the lineation(s) on the plane(s) measured in degrees downward from horizontal. Zero degrees corresponds to the “right hand” direction indicated by the strike, while negative angles are measured downward from the opposite strike direction.
**kwargs: Additional arguments are passed on to plot.

Returns:

A sequence of Line2D artists representing the point(s) specified by
strike and dip.

rotation¶: The rotation of the stereonet in degrees clockwise from North.

set_azimuth_ticklabels(self, labels, fontdict=None, **kwargs)[source]¶

Sets the labels for the azimuthal ticks.

Parameters:	labels : A sequence of strings Azimuth tick labels **kwargs Additional parameters are text properties for the labels.

set_azimuth_ticks(self, angles, labels=None, frac=None, **kwargs)[source]¶

Sets the azimuthal tick locations (Note: tick lines are not currently drawn or supported.).

Parameters:	angles : sequence of numbers The tick locations in degrees. labels : sequence of strings The tick label at each location. Defaults to a formatted version of the specified angles. frac : number The radial location of the tick labels. 1.0 is the along the edge, 1.1 would be outside, and 0.9 would be inside. **kwargs Additional parameters are text properties for the labels.

set_longitude_grid(self, degrees)[source]¶: Set the number of degrees between each longitude grid.

set_longitude_grid_ends(self, value)[source]¶: Set the latitude(s) at which to stop drawing the longitude grids.

set_position(self, pos, which='both')[source]¶

Set the axes position.

Axes have two position attributes. The ‘original’ position is the position allocated for the Axes. The ‘active’ position is the position the Axes is actually drawn at. These positions are usually the same unless a fixed aspect is set to the Axes. See .set_aspect for details.

Parameters:	pos : [left, bottom, width, height] or ~matplotlib.transforms.Bbox The new position of the in .Figure coordinates. which : {‘both’, ‘active’, ‘original’}, optional Determines which position variables to change.

set_rotation(self, rotation)[source]¶: Set the rotation of the stereonet in degrees clockwise from North.

mplstereonet.pole(strike, dip)[source]¶

Calculates the longitude and latitude of the pole(s) to the plane(s) specified by strike and dip, given in degrees.

Parameters:	strike : number or sequence of numbers The strike of the plane(s) in degrees, with dip direction indicated by the azimuth (e.g. 315 vs. 135) specified following the “right hand rule”. dip : number or sequence of numbers The dip of the plane(s) in degrees.
Returns:	lon, lat : Arrays of longitude and latitude in radians.

mplstereonet.plane(strike, dip, segments=100, center=(0, 0))[source]¶

Calculates the longitude and latitude of segments points along the stereonet projection of each plane with a given strike and dip in degrees. Returns points for one hemisphere only.

Parameters:

strike : number or sequence of numbers: The strike of the plane(s) in degrees, with dip direction indicated by the azimuth (e.g. 315 vs. 135) specified following the “right hand rule”.
dip : number or sequence of numbers: The dip of the plane(s) in degrees.
segments : number or sequence of numbers: The number of points in the returned lon and lat arrays. Defaults to 100 segments.
center : sequence of two numbers (lon, lat): The longitude and latitude of the center of the hemisphere that the returned points will be in. Defaults to 0,0 (approriate for a typical stereonet).

Returns:

lon, lat : arrays: num_segments x num_strikes arrays of longitude and latitude in radians.

mplstereonet.line(plunge, bearing)[source]¶

Calculates the longitude and latitude of the linear feature(s) specified by plunge and bearing.

Parameters:	plunge : number or sequence of numbers The plunge of the line(s) in degrees. The plunge is measured in degrees downward from the end of the feature specified by the bearing. bearing : number or sequence of numbers The bearing (azimuth) of the line(s) in degrees.
Returns:	lon, lat : Arrays of longitude and latitude in radians.

mplstereonet.rake(strike, dip, rake_angle)[source]¶

Calculates the longitude and latitude of the linear feature(s) specified by strike, dip, and rake_angle.

Parameters:

strike : number or sequence of numbers: The strike of the plane(s) in degrees, with dip direction indicated by the azimuth (e.g. 315 vs. 135) specified following the “right hand rule”.
dip : number or sequence of numbers: The dip of the plane(s) in degrees.
rake_angle : number or sequence of numbers: The angle of the lineation on the plane measured in degrees downward from horizontal. Zero degrees corresponds to the “right- hand” direction indicated by the strike, while 180 degrees or a negative angle corresponds to the opposite direction.

Returns:

lon, lat : Arrays of longitude and latitude in radians.

mplstereonet.plunge_bearing2pole(plunge, bearing)[source]¶

Converts the given plunge and bearing in degrees to a strike and dip of the plane whose pole would be parallel to the line specified. (i.e. The pole to the plane returned would plot at the same point as the specified plunge and bearing.)

Parameters:	plunge : number or sequence of numbers The plunge of the line(s) in degrees. The plunge is measured in degrees downward from the end of the feature specified by the bearing. bearing : number or sequence of numbers The bearing (azimuth) of the line(s) in degrees.
Returns:	strike, dip : arrays Arrays of strikes and dips in degrees following the right-hand-rule.

mplstereonet.geographic2pole(lon, lat)[source]¶

Converts a longitude and latitude (from a stereonet) into the strike and dip of the plane whose pole lies at the given longitude(s) and latitude(s).

Parameters:	lon : array-like A sequence of longitudes (or a single longitude) in radians lat : array-like A sequence of latitudes (or a single latitude) in radians
Returns:	strike : array A sequence of strikes in degrees dip : array A sequence of dips in degrees

mplstereonet.vector2plunge_bearing(x, y, z)[source]¶

Converts a vector or series of vectors given as x, y, z in world coordinates into plunge/bearings.

Parameters:	x : number or sequence of numbers The x-component(s) of the normal vector y : number or sequence of numbers The y-component(s) of the normal vector z : number or sequence of numbers The z-component(s) of the normal vector
Returns:	plunge : array The plunge of the vector in degrees downward from horizontal. bearing : array The bearing of the vector in degrees clockwise from north.

mplstereonet.geographic2plunge_bearing(lon, lat)[source]¶

Converts longitude and latitude in stereonet coordinates into a plunge/bearing.

Parameters:	lon, lat : numbers or sequences of numbers Longitudes and latitudes in radians as measured from a lower-hemisphere stereonet
Returns:	plunge : array The plunge of the vector in degrees downward from horizontal. bearing : array The bearing of the vector in degrees clockwise from north.

mplstereonet.density_grid(*args, **kwargs)[source]¶

Estimates point density of the given linear orientation measurements (Interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument.). Returns a regular (in lat-long space) grid of density estimates over a hemispherical surface.

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for contouring.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

method : string, optional

The method of density estimation to use. Defaults to "exponential_kamb". May be one of the following:

"exponential_kamb" : Kamb with exponential smoothing: A modified Kamb method using exponential smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"linear_kamb" : Kamb with linear smoothing: A modified Kamb method using linear smoothing [1]. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"kamb" : Kamb with no smoothing: Kamb’s method [2] with no smoothing. Units are in numbers of standard deviations by which the density estimate differs from uniform.
"schmidt" : 1% counts: The traditional “Schmidt” (a.k.a. 1%) method. Counts points within a counting circle comprising 1% of the total area of the hemisphere. Does not take into account sample size. Units are in points per 1% area.

sigma : int or float, optional

The number of standard deviations defining the expected number of standard deviations by which a random sample from a uniform distribution of points would be expected to vary from being evenly distributed across the hemisphere. This controls the size of the counting circle, and therefore the degree of smoothing. Higher sigmas will lead to more smoothing of the resulting density distribution. This parameter only applies to Kamb-based methods. Defaults to 3.

gridsize : int or 2-item tuple of ints, optional

The size of the grid that the density is estimated on. If a single int is given, it is interpreted as an NxN grid. If a tuple of ints is given it is interpreted as (nrows, ncols). Defaults to 100.

weights : array-like, optional

The relative weight to be applied to each input measurement. The array will be normalized to sum to 1, so absolute value of the weights do not affect the result. Defaults to None.

Returns:

xi, yi, zi : 2D arrays: The longitude, latitude and density values of the regularly gridded density estimates. Longitude and latitude are in radians.

See also

mplstereonet.StereonetAxes.density_contourf
mplstereonet.StereonetAxes.density_contour

References

[1]	(1, 2) Vollmer, 1995. C Program for Automatic Contouring of Spherical Orientation Data Using a Modified Kamb Method. Computers & Geosciences, Vol. 21, No. 1, pp. 31–49.

[2]	Kamb, 1959. Ice Petrofabric Observations from Blue Glacier, Washington, in Relation to Theory and Experiment. Journal of Geophysical Research, Vol. 64, No. 11, pp. 1891–1909.

mplstereonet.plane_intersection(strike1, dip1, strike2, dip2)[source]¶

Finds the intersection of two planes. Returns a plunge/bearing of the linear intersection of the two planes.

Also accepts sequences of strike1s, dip1s, strike2s, dip2s.

Parameters:	strike1, dip1 : numbers or sequences of numbers The strike and dip (in degrees, following the right-hand-rule) of the first plane(s). strike2, dip2 : numbers or sequences of numbers The strike and dip (in degrees, following the right-hand-rule) of the second plane(s).
Returns:	plunge, bearing : arrays The plunge and bearing(s) (in degrees) of the line representing the intersection of the two planes.

mplstereonet.xyz2stereonet(x, y, z)[source]¶

Converts x, y, z in _world_ cartesian coordinates into lower-hemisphere stereonet coordinates.

Parameters:	x, y, z : array-likes Sequences of world coordinates
Returns:	lon, lat : arrays Sequences of longitudes and latitudes (in radians)

mplstereonet.stereonet2xyz(lon, lat)[source]¶

Converts a sequence of longitudes and latitudes from a lower-hemisphere stereonet into _world_ x,y,z coordinates.

Parameters:	lon, lat : array-likes Sequences of longitudes and latitudes (in radians) from a lower-hemisphere stereonet
Returns:	x, y, z : arrays The world x,y,z components of the vectors represented by the lon, lat coordinates on the stereonet.

mplstereonet.vector2pole(x, y, z)[source]¶

Converts a vector or series of vectors given as x, y, z in world coordinates into the strike/dip of the planes whose normal vectors are parallel to the specified vectors. (In other words, each xi,yi,zi is treated as a normal vector and this returns the strike/dip of the corresponding plane.)

Parameters:	x : number or sequence of numbers The x-component(s) of the normal vector y : number or sequence of numbers The y-component(s) of the normal vector z : number or sequence of numbers The z-component(s) of the normal vector
Returns:	strike : array The strike of the plane, in degrees clockwise from north. Dip direction is indicated by the “right hand rule”. dip : array The dip of the plane, in degrees downward from horizontal.

mplstereonet.antipode(lon, lat)[source]¶

Calculates the antipode (opposite point on the globe) of the given point or points. Input and output is expected to be in radians.

Parameters:	lon : number or sequence of numbers Longitude in radians lat : number or sequence of numbers Latitude in radians
Returns:	lon, lat : arrays Sequences (regardless of whether or not the input was a single value or a sequence) of longitude and latitude in radians.

mplstereonet.project_onto_plane(strike, dip, plunge, bearing)[source]¶

Projects a linear feature(s) onto the surface of a plane. Returns a rake angle(s) along the plane.

This is also useful for finding the rake angle of a feature that already intersects the plane in question.

Parameters:	strike, dip : numbers or sequences of numbers The strike and dip (in degrees, following the right-hand-rule) of the plane(s). plunge, bearing : numbers or sequences of numbers The plunge and bearing (in degrees) or of the linear feature(s) to be projected onto the plane.
Returns:	rake : array A sequence of rake angles measured downwards from horizontal in degrees. Zero degrees corresponds to the “right- hand” direction indicated by the strike, while a negative angle corresponds to the opposite direction. Rakes returned by this function will always be between -90 and 90 (inclusive).

mplstereonet.azimuth2rake(strike, dip, azimuth)[source]¶

Projects an azimuth of a linear feature onto a plane as a rake angle.

Parameters:	strike, dip : numbers The strike and dip of the plane in degrees following the right-hand-rule. azimuth : numbers The azimuth of the linear feature in degrees clockwise from north (i.e. a 0-360 azimuth).
Returns:	rake : number A rake angle in degrees measured downwards from horizontal. Negative values correspond to the opposite end of the strike.

mplstereonet.parse_azimuth(azimuth)[source]¶

Parses an azimuth measurement in azimuth or quadrant format.

Parameters:	azimuth : string or number An azimuth measurement in degrees or a quadrant measurement of azimuth.
Returns:	azi : float The azimuth in degrees clockwise from north (range: 0-360)

See also

parse_quadrant_measurement
parse_strike_dip
parse_plunge_bearing

mplstereonet.parse_quadrant_measurement(quad_azimuth)[source]¶

Parses a quadrant measurement of the form “AxxB”, where A and B are cardinal directions and xx is an angle measured relative to those directions.

In other words, it converts a measurement such as E30N into an azimuth of 60 degrees, or W10S into an azimuth of 260 degrees.

For ambiguous quadrant measurements such as “N30S”, a ValueError is raised.

Parameters:	quad_azimuth : string An azimuth measurement in quadrant form.
Returns:	azi : float An azimuth in degrees clockwise from north.

See also

parse_azimuth

mplstereonet.parse_strike_dip(strike, dip)[source]¶

Parses strings of strike and dip and returns strike and dip measurements following the right-hand-rule.

Dip directions are parsed, and if the measurement does not follow the right-hand-rule, the opposite end of the strike measurement is returned.

Accepts either quadrant-formatted or azimuth-formatted strikes.

For example, this would convert a strike of “N30E” and a dip of “45NW” to a strike of 210 and a dip of 45.

Parameters:	strike : string A strike measurement. May be in azimuth or quadrant format. dip : string The dip angle and direction of a plane.
Returns:	azi : float Azimuth in degrees of the strike of the plane with dip direction indicated following the right-hand-rule. dip : float Dip of the plane in degrees.

mplstereonet.parse_rake(strike, dip, rake)[source]¶

Parses strings of strike, dip, and rake and returns a strike, dip, and rake measurement following the right-hand-rule, with the “end” of the strike that the rake is measured from indicated by the sign of the rake (positive rakes correspond to the strike direction, negative rakes correspond to the opposite end).

Accepts either quadrant-formatted or azimuth-formatted strikes.

For example, this would convert a strike of “N30E”, dip of “45NW”, with a rake of “10NE” to a strike of 210, dip of 45, and rake of 170.

Rake angles returned by this function will always be between 0 and 180

If no directions are specified, the measuriement is assumed to follow the usual right-hand-rule convention.

Parameters:	strike : string A strike measurement. May be in azimuth or quadrant format. dip : string The dip angle and direction of a plane. rake : string The rake angle and direction that the rake is measured from.
Returns:	strike, dip, rake : floats Measurements of strike, dip, and rake following the conventions outlined above.

mplstereonet.parse_plunge_bearing(plunge, bearing)[source]¶

Parses strings of plunge and bearing and returns a consistent plunge and bearing measurement as floats. Plunge angles returned by this function will always be between 0 and 90.

If no direction letter(s) is present, the plunge is assumed to be measured from the end specified by the bearing. If a direction letter(s) is present, the bearing will be switched to the opposite (180 degrees) end if the specified direction corresponds to the opposite end specified by the bearing.

Parameters:	plunge : string A plunge measurement. bearing : string A bearing measurement. May be in azimuth or quadrant format.
Returns:	plunge, bearing: floats The plunge and bearing following the conventions outlined above.

Examples

>>> parse_plunge_bearing("30NW", 160)
... (30, 340)

mplstereonet.subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, subplot_kw=None, hemisphere='lower', projection='equal_area', **fig_kw)[source]¶

Identical to matplotlib.pyplot.subplots, except that this will default to producing equal-area stereonet axes.

This prevents constantly doing:

>>> fig, ax = plt.subplot(subplot_kw=dict(projection='stereonet'))

or

>>> fig = plt.figure()
>>> ax = fig.add_subplot(111, projection='stereonet')

Using this function also avoids having mplstereonet continually appear to be an unused import when one of the above methods are used.

Parameters:

nrows : int

Number of rows of the subplot grid. Defaults to 1.

ncols : int

Number of columns of the subplot grid. Defaults to 1.

hemisphere : string

Currently this has no effect. When upper hemisphere and dual hemisphere plots are implemented, this will control which hemisphere is displayed.

projection : string

The projection for the axes. Defaults to ‘equal_area’–an equal-area (a.k.a. “Schmidtt”) stereonet. May also be ‘equal_angle’ for an equal-angle (a.k.a. “Wulff”) stereonet or any other valid matplotlib projection (e.g. ‘polar’ or ‘rectilinear’ for a “normal” axes).

The following parameters are identical to matplotlib.pyplot.subplots:

sharex : string or bool

If True, the X axis will be shared amongst all subplots. If True and you have multiple rows, the x tick labels on all but the last row of plots will have visible set to False If a string must be one of “row”, “col”, “all”, or “none”. “all” has the same effect as True, “none” has the same effect as False. If “row”, each subplot row will share a X axis. If “col”, each subplot column will share a X axis and the x tick labels on all but the last row will have visible set to False.

sharey : string or bool

If True, the Y axis will be shared amongst all subplots. If True and you have multiple columns, the y tick labels on all but the first column of plots will have visible set to False If a string must be one of “row”, “col”, “all”, or “none”. “all” has the same effect as True, “none” has the same effect as False. If “row”, each subplot row will share a Y axis. If “col”, each subplot column will share a Y axis and the y tick labels on all but the last row will have visible set to False.

*squeeze* : bool

If True, extra dimensions are squeezed out from the returned axis object:

if only one subplot is constructed (nrows=ncols=1), the resulting single Axis object is returned as a scalar.

for Nx1 or 1xN subplots, the returned object is a 1-d numpy object array of Axis objects are returned as numpy 1-d arrays.

for NxM subplots with N>1 and M>1 are returned as a 2d array.

If False, no squeezing at all is done: the returned axis: object is always a 2-d array contaning Axis instances, even if it ends up being 1x1.

*subplot_kw* : dict

Dict with keywords passed to the add_subplot() call used to create each subplots.

*fig_kw* : dict

Dict with keywords passed to the figure() call. Note that all keywords not recognized above will be automatically included here.

Returns:

fig, ax : tuple

fig is the matplotlib.figure.Figure object
ax can be either a single axis object or an array of axis

objects if more than one supblot was created. The dimensions of the resulting array can be controlled with the squeeze keyword, see above.

mplstereonet.pole2plunge_bearing(strike, dip)[source]¶

Converts the given strike and dip in dgrees of a plane(s) to a plunge and bearing of its pole.

Parameters:	strike : number or sequence of numbers The strike of the plane(s) in degrees, with dip direction indicated by the azimuth (e.g. 315 vs. 135) specified following the “right hand rule”. dip : number or sequence of numbers The dip of the plane(s) in degrees.
Returns:	plunge, bearing : arrays Arrays of plunges and bearings of the pole to the plane(s) in degrees.

mplstereonet.fit_girdle(*args, **kwargs)[source]¶

Fits a plane to a scatter of points on a stereonet (a.k.a. a “girdle”).

Input arguments will be interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument. (Defaults to "poles".)

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be strikes & dips, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : {‘poles’, ‘lines’, ‘rakes’, ‘radians’}, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : Arguments are assumed to be sequences of strikes and

dips of planes. Poles to these planes are used for density contouring.

"lines" : Arguments are assumed to be sequences of plunges and

bearings of linear features.

"rakes" : Arguments are assumed to be sequences of strikes,

dips, and rakes along the plane.

"radians" : Arguments are assumed to be “raw” longitudes and

latitudes in the underlying projection’s coordinate system.

bidirectional : boolean, optional

Whether or not the antipode of each measurement will be used in the calculation. For almost all use cases, it should. Defaults to True.

Returns:

strike, dip: floats: The strike and dip of the plane.

Notes

The pole to the best-fit plane is extracted by calculating the smallest eigenvector of the covariance matrix of the input measurements in cartesian 3D space.

Examples

Calculate the plunge of a cylindrical fold axis from a series of strike/dip measurements of bedding from the limbs:

>>> strike = [270, 334, 270, 270]
>>> dip = [20, 15, 80, 78]
>>> s, d = mplstereonet.fit_girdle(strike, dip)
>>> plunge, bearing = mplstereonet.pole2plunge_bearing(s, d)

mplstereonet.fit_pole(*args, **kwargs)[source]¶

Fits the pole to a plane to a “bullseye” of points on a stereonet.

Input arguments will be interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument. (Defaults to "poles".)

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : {‘poles’, ‘lines’, ‘rakes’, ‘radians’}, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : Arguments are assumed to be sequences of strikes and

dips of planes. Poles to these planes are used for density contouring.

"lines" : Arguments are assumed to be sequences of plunges and

bearings of linear features.

"rakes" : Arguments are assumed to be sequences of strikes,

dips, and rakes along the plane.

"radians" : Arguments are assumed to be “raw” longitudes and

latitudes in the underlying projection’s coordinate system.

bidirectional : boolean, optional

Whether or not the antipode of each measurement will be used in the calculation. For almost all use cases, it should. Defaults to True.

Returns:

strike, dip: floats: The strike and dip of the plane.

Notes

The pole to the best-fit plane is extracted by calculating the largest eigenvector of the covariance matrix of the input measurements in cartesian 3D space.

Examples

Find the average strike/dip of a series of bedding measurements

>>> strike = [270, 65, 280, 300]
>>> dip = [20, 15, 10, 5]
>>> strike0, dip0 = mplstereonet.fit_pole(strike, dip)

mplstereonet.eigenvectors(*args, **kwargs)[source]¶

Finds the 3 eigenvectors and eigenvalues of the 3D covariance matrix of a series of geometries. This can be used to fit a plane/pole to a dataset or for shape fabric analysis (e.g. Flinn/Hsu plots).

Input arguments will be interpreted as poles, lines, rakes, or “raw” longitudes and latitudes based on the measurement keyword argument. (Defaults to "poles".)

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : {‘poles’, ‘lines’, ‘rakes’, ‘radians’}, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : Arguments are assumed to be sequences of strikes and

dips of planes. Poles to these planes are used for density contouring.

"lines" : Arguments are assumed to be sequences of plunges and

bearings of linear features.

"rakes" : Arguments are assumed to be sequences of strikes,

dips, and rakes along the plane.

"radians" : Arguments are assumed to be “raw” longitudes and

latitudes in the underlying projection’s coordinate system.

bidirectional : boolean, optional

Whether or not the antipode of each measurement will be used in the calculation. For almost all use cases, it should. Defaults to True.

Returns:

plunges, bearings, values : sequences of 3 floats each: The plunges, bearings, and eigenvalues of the three eigenvectors of the covariance matrix of the input data. The measurements are returned sorted in descending order relative to the eigenvalues. (i.e. The largest eigenvector/eigenvalue is first.)

Examples

Find the eigenvectors as plunge/bearing and eigenvalues of the 3D covariance matrix of a series of planar measurements:

>>> strikes = [270, 65, 280, 300]
>>> dips = [20, 15, 10, 5]
>>> plu, azi, vals = mplstereonet.eigenvectors(strikes, dips)

mplstereonet.kmeans(*args, **kwargs)[source]¶

Find centers of multi-modal clusters of data using a kmeans approach modified for spherical measurements.

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be strike & dip, both array-like sequences representing poles to planes. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

num : int

The number of clusters to find. Defaults to 2.

bidirectional : bool

Whether or not the measurements are bi-directional linear/planar features or directed vectors. Defaults to True.

tolerance : float

Iteration will continue until the centers have not changed by more than this amount. Defaults to 1e-5.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "poles". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for analysis.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

Returns:

centers : An Nx2 array-like: Longitude and latitude in radians of the centers of each cluster.

mplstereonet.find_mean_vector(*args, **kwargs)[source]¶

Returns the mean vector for a set of measurments. By default, this expects the input to be plunges and bearings, but the type of input can be controlled through the measurement kwarg.

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be plunge & bearing, both array-like sequences representing linear features. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "lines". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for analysis.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

Returns:

mean_vector : tuple of two floats: The plunge and bearing of the mean vector (in degrees).
r_value : float: The length of the mean vector (a value between 0 and 1).

mplstereonet.find_fisher_stats(*args, **kwargs)[source]¶

Returns the mean vector and summary statistics for a set of measurements. By default, this expects the input to be plunges and bearings, but the type of input can be controlled through the measurement kwarg.

Parameters:

*args : 2 or 3 sequences of measurements

By default, this will be expected to be plunge & bearing, both array-like sequences representing linear features. (Rake measurements require three parameters, thus the variable number of arguments.) The measurement kwarg controls how these arguments are interpreted.

conf : number

The confidence level (0-100). Defaults to 95%, similar to 2 sigma.

measurement : string, optional

Controls how the input arguments are interpreted. Defaults to "lines". May be one of the following:

"poles" : strikes, dips

Arguments are assumed to be sequences of strikes and dips of planes. Poles to these planes are used for analysis.

"lines" : plunges, bearings

Arguments are assumed to be sequences of plunges and bearings of linear features.

"rakes" : strikes, dips, rakes

Arguments are assumed to be sequences of strikes, dips, and rakes along the plane.

"radians" : lon, lat

Arguments are assumed to be “raw” longitudes and latitudes in the stereonet’s underlying coordinate system.

Returns:

mean_vector: tuple of two floats: A set consisting of the plunge and bearing of the mean vector (in degrees).
stats : tuple of three floats: (r_value, confidence, kappa) The r_value is the magnitude of the mean vector as a number between 0 and 1. The confidence radius is the opening angle of a small circle that corresponds to the confidence in the calculated direction, and is dependent on the input conf. The kappa value is the dispersion factor that quantifies the amount of dispersion of the given vectors, analgous to a variance/stddev.

mplstereonet.angular_distance(first, second, bidirectional=True)[source]¶

Calculate the angular distance between two linear features or elementwise angular distance between two sets of linear features. (Note: a linear feature in this context is a point on a stereonet represented by a single latitude and longitude.)

Parameters:

first : (lon, lat) 2xN array-like or sequence of two numbers: The longitudes and latitudes of the first measurements in radians.
second : (lon, lat) 2xN array-like or sequence of two numbers: The longitudes and latitudes of the second measurements in radians.
bidirectional : boolean: If True, only “inner” angles will be returned. In other words, all angles returned by this function will be in the range [0, pi/2] (0 to 90 in degrees). Otherwise, first and second will be treated as vectors going from the origin outwards instead of bidirectional infinite lines. Therefore, with bidirectional=False, angles returned by this function will be in the range [0, pi] (zero to 180 degrees).

Returns:

dist : array: The elementwise angular distance between each pair of measurements in (lon1, lat1) and (lon2, lat2).

Examples

Calculate the angle between two lines specified as a plunge/bearing

>>> angle = angular_distance(line(30, 270), line(40, 90))
>>> np.degrees(angle)
array([ 70.])

Let’s do the same, but change the “bidirectional” argument:

>>> first, second = line(30, 270), line(40, 90)
>>> angle = angular_distance(first, second, bidirectional=False)
>>> np.degrees(angle)
array([ 110.])

Calculate the angle between two planes.

>>> angle = angular_distance(pole(0, 10), pole(180, 10))
>>> np.degrees(angle)
array([ 20.])

# :undoc-members: