plotting module

The apsg.plotting module provides plotting classes for structural geology data. It includes StereoNet for stereographic projection, RosePlot for rose diagrams, and fabric plot types (VollmerPlot, RamsayPlot, FlinnPlot, HsuPlot) for strain and fabric analysis.

Usage

Stereonet plots:

>>> from apsg import folset, linset
>>> from apsg.plotting import StereoNet
>>> fols = folset.random_fisher(kappa=50, n=20)
>>> lins = linset.random_fisher(kappa=100, n=20)
>>> f = fols.data[0]
>>> s = StereoNet(title="My data")
>>> s.point(fols)
>>> s.point(lins)
>>> s.great_circle(f)
>>> s.show()

Customize plot appearance:

>>> s = StereoNet(title="Custom", kind="equal-angle", hemisphere="upper")
>>> s.point(lins, marker="s", mfc="red", ms=8)
>>> s.contour(fols, levels=4, cmap="Blues", colorbar=True)
>>> s.show()

Quick plot one-liner:

>>> from apsg import quicknet
>>> quicknet(fols, lins, title="Quick net")

Rose diagrams:

>>> from apsg import vec2set
>>> from apsg.plotting import RosePlot
>>> v = vec2set.random_vonmises(position=120, kappa=100, n=50)
>>> p = RosePlot(grid=False)
>>> p.bar(v, fc="none", ec="k")
>>> p.pdf(v)
>>> p.muci(v)
>>> p.show()

Fabric plots:

>>> from apsg.feature import Ellipsoid, EllipsoidSet
>>> from apsg.plotting import VollmerPlot, FlinnPlot, RamsayPlot, HsuPlot
>>> e1 = Ellipsoid.from_stretch(2, 1, 0.5)
>>> e2 = Ellipsoid.from_stretch(1.5, 1.2, 0.8)
>>> es = EllipsoidSet([e1, e2])
>>> vp = VollmerPlot()
>>> vp.point(es)
>>> vp.show()
>>>
>>> fp = FlinnPlot()
>>> fp.point(es)
>>> fp.show()
>>>
>>> rp = RamsayPlot()
>>> rp.point(es)
>>> rp.show()
>>>
>>> hp = HsuPlot()
>>> hp.point(es)
>>> hp.show()

Save and load plots:

>>> s.save('stereonet.pkl')
>>> s2 = StereoNet.load('stereonet.pkl')
>>> s2.show()

Classes:

`StereoNet`(**kwargs)	Plot features on stereographic projection
`StereoGrid`(**kwargs)	The class to store values with associated uniformly positions.
`RosePlot`(**kwargs)	`RosePlot` class for rose histogram plotting.
`VollmerPlot`(args, *kwargs)	Represents the triangular fabric plot (Vollmer, 1989).
`RamsayPlot`(args, *kwargs)	Represents the Ramsay deformation plot.
`FlinnPlot`(args, *kwargs)	Represents the Ramsay deformation plot.
`HsuPlot`(args, *kwargs)	Represents the Hsu fabric plot.

Functions:

quicknet(*args, **kwargs)

Function to quickly show or save StereoNet from args

class apsg.plotting.StereoNet(**kwargs)

Bases: object

Plot features on stereographic projection

Keyword Arguments:

title (str) – figure title. Default None.
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
tight_layout (bool) – Matplotlib figure tight_layout. Default False
kind (str) – Equal area (“equal-area”, “schmidt” or “earea”) or equal angle (“equal-angle”, “wulff” or “eangle”) projection. Default is “equal-area”
hemisphere (str) – “lower” or “upper”. Default is “lower”
overlay_position (tuple or Pair) – Position of overlay X, Y, Z given by Pair. X is direction of linear element, Z is normal to planar. Default is (0, 0, 0, 0)
rotate_data (bool) – Whether data should be rotated together with overlay. Default False
minor_ticks (None or float) – Default None
major_ticks (None or float) – Default None
overlay (bool) – Whether to show overlay. Default is True
overlay_step (float) – Grid step of overlay. Default 15
overlay_resolution (float) – Resolution of overlay. Default 181
clip_pole (float) – Clipped cone around poles. Default 15
grid_type (str) – Type of contouring grid “gss” or “sfs”. Default “gss”
grid_n (int) – Number of counting points in grid. Default 3000

Examples

>>> l = linset.random_fisher(position=lin(120, 40))
>>> s = StereoNet(title="Random linear features")
>>> s.contour(l)
>>> s.point(l)
>>> s.show()

arc(*args, **kwargs)

Plot arc bewtween vectors along great circle(s)

Note: You should pass several features in connection order

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5

arrow(*args, **kwargs)

Plot arrow at position of first argument and oriented in direction of second

Note: You should pass two features

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

color (color) – Set the color of the arrow. Default None
width (int) – Width of arrow. Default 2
headwidth (int) – Width of arrow head. Default 5
pivot (str) – Arrow pivot. Default “mid”
units (str) – Arrow size units. Default “dots”

clear(): Clear plot

contour(*args, **kwargs)

Plot filled contours in multiples of uniform distribution.

Parameters:

feature (Vector3Set like)

Keyword Arguments:

method (str) – “kamb” for modified Kamb contouring technique with exponential smoothing or “sph” for spherical harmonics method. Default “sph”
levels (int or list) – number or values of contours. Default 6
cmap – matplotlib colormap used for filled contours. Default “Greys”
colorbar (bool) – Show colorbar. Default False
alpha (float) – transparency. Default None
antialiased (bool) – Default True
n_max (int) – maximum harmonic degree i.e. the angular resolution. Must be even number (for “sph” method). Default 6
sigma (float) – If None it is automatically calculated (for “kamb” method)
sigmanorm (bool) – If True scaled counts are normalized by sigma (for “kamb” method). Default True
trimzero (bool) – Remove values equal to 0. Default True
clines (bool) – Show contour lines instead filled contours. Default False
linewidths (float) – contour lines width
linestyles (str) – contour lines style
show_data (bool) – Show data as points. Default False
data_kws (dict) – arguments passed to point factory when show_data True

fault(*args, **kwargs)

Plot fault feature(s) as great circle and arrow

Note: Arrow is styled according to default arrow config

Parameters:

feature (Fault or FaultSet)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5

format_coord(x, y): Format stereonet coordinates

classmethod from_json(json_dict): Create stereonet from JSON dict

gc(*args, **kwargs)

Plot planar feature(s) as great circle(s)

Note: great_circle has also alias gc

Parameters:

feature (Foliation or FoliationSet)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5

great_circle(*args, **kwargs)

Plot planar feature(s) as great circle(s)

Note: great_circle has also alias gc

Parameters:

feature (Foliation or FoliationSet)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5

hoeppner(*args, **kwargs)

Plot fault feature(s) on Hoeppner (tangent lineation) plot

Note: Arrow is styled according to default arrow config

Parameters:

feature (Fault or FaultSet)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5

line(*args, **kwargs)

Plot linear feature(s) or poles of planar features as point(s)

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
mec (color) – Set the edge color. Default None
mfc (color) – Set the face color. Default None
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 6
marker (str) – Marker style string. Default “o”
ls (str) – Line style string (only for multiple features). Default None

classmethod load(filename)

Load stereonet from pickle file

Parameters:: filename (str) – name of picke file

pair(*args, **kwargs)

Plot pair feature(s) as great circle and point

Parameters:

feature (Pair or PairSet)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
line_marker (str) – Marker style string for point. Default “o”

plot(style, *args)

Plot features using apsg styles

Parameters:

style – apsg plotting style. See stereonet_styles
*arg – any number of features to be plotted

Note

Features in args are automatically filtered by style to accept only compatible features

point(*args, **kwargs)

Plot linear feature(s) or poles of planar features as point(s)

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
mec (color) – Set the edge color. Default None
mfc (color) – Set the face color. Default None
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 6
marker (str) – Marker style string. Default “o”
ls (str) – Line style string (only for multiple features). Default None

pole(*args, **kwargs)

Plot linear feature(s) or poles of planar features as point(s)

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
mec (color) – Set the edge color. Default None
mfc (color) – Set the face color. Default None
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 6
marker (str) – Marker style string. Default “o”
ls (str) – Line style string (only for multiple features). Default None

render2fig(fig)

Plot stereonet to already existing figure or subfigure

Parameters:: fig (Figure) – A mtplotlib Figure artist

save(filename)

Save stereonet to pickle file

Parameters:: filename (str) – name of picke file

savefig(filename='stereonet.png', **kwargs)

Save stereonet figure to graphics file

Keyword Arguments:: filename (str) – filename

All others kwargs are passed to matplotlib Figure.savefig

scatter(*args, **kwargs)

Plot vector-like feature(s) as point(s)

Note: This method is using scatter plot to allow variable colors: or sizes of points

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

s (list or array)
c (list or array)
alpha (scalar) – Set the alpha value. Default None
linewidths (float) – The linewidth of the marker edges. Default 1.5
marker (str) – Marker style string. Default “o”
cmap (str) – Mtplotlib colormap. Default None
legend (bool) – Whether to show legend. Default False
num (int) – NUmber of legend items. Default “auto”

show(): Show stereonet

stress(*args, **kwargs)

Plot principal stresses of stress tensor

Parameters:

feature (Stress3)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color. Default is red, green, blue for s1, s2, s3
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 12
marker (str) – Marker style string. Default “*”

tensor(*args, **kwargs)

Plot principal planes or principal directions of tensor

Parameters:

feature (OrientationTensor3 like)

Keyword Arguments:

planes (bool) – When True, plot principal planes, otherwise principal directions. Default True
alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color. Default is red, green, blue for s1, s2, s3
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 9
marker (str) – Marker style string. Default “o”

to_json(): Return stereonet as JSON dict

vector(*args, **kwargs)

Plot vector feature(s) as point(s)

Note: Markers are filled on lower and open on upper hemisphere.

Parameters:

feature (Vector3 or Vector3Set like)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
mec (color) – Set the edge color. Default None
mfc (color) – Set the face color. Default None
mew (float) – Set the marker edge width. Default 1
ms (float) – Set the marker size. Default 6
marker (str) – Marker style string. Default “o”
ls (str) – Line style string (only for multiple features). Default None

class apsg.plotting.StereoGrid(**kwargs)

Bases: object

The class to store values with associated uniformly positions.

StereoGrid is used to calculate continous functions on sphere e.g. density distribution.

Keyword Arguments:

kind (str) – Equal area (“equal-area”, “schmidt” or “earea”) or equal angle (“equal-angle”, “wulff” or “eangle”) projection. Default is “equal-area”
hemisphere (str) – “lower” or “upper”. Default is “lower”
overlay_position (tuple or Pair) – Position of overlay X, Y, Z given by Pair. X is direction of linear element, Z is normal to planar. Default is (0, 0, 0, 0)
rotate_data (bool) – Whether data should be rotated together with overlay. Default False
minor_ticks (None or float) – Default None
major_ticks (None or float) – Default None
overlay (bool) – Whether to show overlay. Default is True
overlay_step (float) – Grid step of overlay. Default 15
overlay_resolution (float) – Resolution of overlay. Default 181
clip_pole (float) – Clipped cone around poles. Default 15
grid_type (str) – Type of contouring grid “gss” or “sfs”. Default “gss”
grid_n (int) – Number of counting points in grid. Default 3000

Note: Euclidean norms are used as weights. Normalize data if you dont want to use weigths.

angmech(faults, **kwargs)

Implementation of Angelier-Mechler dihedra method

Parameters:: faults – FaultSet of data

Kwargs:: method: ‘probability’ or ‘classic’. Classic method assigns +/-1 to individual positions, while ‘probability’ returns maximum likelihood estimate. Other kwargs are passed to contourf

apply_func(func, *args, **kwargs)

Calculate values of user-defined function on sphere.

Function must accept Vector3 like (or 3 elements array) as first argument and return scalar value.

Parameters:

func (function) – function used to calculate values
*args – passed to function func as args
**kwargs – passed to function func as kwargs

calculate_density(features, **kwargs)

Calculate density distribution of vectors from FeatureSet object.

Parameters:

method (str) – “kamb” for modified Kamb contouring technique with exponential smoothing or “sph” for spherical harmonics method. Default “sph”
n_max (int) – maximum harmonic degree i.e. the angular resolution. Must be even number (for “sph” method). Default 6
sigma (float) – if none sigma is calculated automatically (for “kamb” method). Default None
sigmanorm (bool) – If True counting is normalized to sigma multiples (for “kamb” method). Default True
trimzero – if True, zero contour is not drawn. Default True

contour(*args, **kwargs)

Draw contour lines of values using tricontour.

Keyword Arguments:

levels (int or list) – number or values of contours. Default 6
cmap – matplotlib colormap used for filled contours. Default “Greys”
colorbar (bool) – Show colorbar. Default False
alpha (float) – transparency. Default None
antialiased (bool) – Default True
linewidths (float) – contour lines width
linestyles (str) – contour lines style

contourf(*args, **kwargs)

Draw filled contours of values using tricontourf.

Keyword Arguments:

levels (int or list) – number or values of contours. Default 6
cmap – matplotlib colormap used for filled contours. Default “Greys”
colorbar (bool) – Show colorbar. Default False
alpha (float) – transparency. Default None
antialiased (bool) – Default True

max(): Returns maximum value of the grid

max_at(): Returns position of maximum value of the grid as Lineation

min(): Returns minimum value of the grid

min_at(): Returns position of minimum value of the grid as Lineation

plotcountgrid(**kwargs): Show counting grid.

class apsg.plotting.RosePlot(**kwargs)

Bases: object

RosePlot class for rose histogram plotting.

Keyword Arguments:

title (str) – figure title. Default None
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
bins (int) – Number of bins. Default 36
density (bool) – Use density instead of counts. Default False
pdf (bool) – Plot Von Mises density function instead histogram. Default False
pdf_res (int) – Resolution of pdf. Default 901
kappa (float) – Shape parameter of Von Mises pdf. Default 250
scaled (bool) – Bins scaled by area instead value. Default False
ticks (bool) – show ticks. Default True
grid (bool) – show grid lines. Default False
grid_kws (dict) – Dict passed to Axes.grid. Default {}
plot. (Other keyword arguments are passed to matplotlib)

Note: Roseplot is weighted by magnitude of Direction or Vector2 features

Examples

>>> v = vec2set.random_vonmises(position=120)
>>> p = RosePlot(grid=False)
>>> p.pdf(v)
>>> p.bar(v, fc='none', ec='k', lw=1)
>>> p.muci(v)
>>> p.show()

bar(*args, **kwargs)

Plot rose histogram of angles

Parameters:

feature (Vector2Set)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ec (color) – Patch edge color. Default None
fc (color) – Patch face color. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
legend (bool) – Whether to show legend. Default False

clear(): Clear plot

classmethod from_json(json_dict): Create rose plot from JSON dict

classmethod load(filename)

Load stereonet from pickle file

Parameters:: filename (str) – name of picke file

muci(*args, **kwargs)

Plot circular mean with bootstrapped confidence interval

Parameters:

feature (Vector2Set)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
confidence_level (float) – Confidence interval. Default 95
n_resamples (int) – Number of bootstrapped samples. Default 9999

pdf(*args, **kwargs)

Plot Von Mises probability density function from angles

Parameters:

feature (Vector2Set)

Keyword Arguments:

alpha (scalar) – Set the alpha value. Default None
color (color) – Set the color of the point. Default None
ec (color) – Patch edge color. Default None
fc (color) – Patch face color. Default None
ls (str) – Line style string (only for multiple features). Default “-”
lw (float) – Set line width. Default 1.5
legend (bool) – Whether to show legend. Default False

plot(style, *args)

Plot features using apsg styles

Parameters:

style – apsg plotting style. See roseplot_styles
*arg – any number of features to be plotted

Note

Features in args are automatically filtered by style to accept only compatible features

render2fig(fig)

Plot stereonet to already existing figure or subfigure

Parameters:: fig (Figure) – A mtplotlib Figure artist

save(filename)

Save stereonet to pickle file

Parameters:: filename (str) – name of picke file

savefig(filename='roseplot.png', **kwargs)

Save rose plot figure to graphics file

Keyword Arguments:: filename (str) – filename

All others kwargs are passed to matplotlib Figure.savefig

show(): Show rose plot

to_json(): Return rose plot as JSON dict

class apsg.plotting.VollmerPlot(*args, **kwargs)

Bases: FabricPlot

Represents the triangular fabric plot (Vollmer, 1989).

Keyword Arguments:

title (str) – figure title. Default None.
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
ticks (bool) – Show ticks. Default True
n_ticks (int) – Number of ticks. Default 10
tick_size (float) – Size of ticks. Default 0.2
margin (float) – Size of margin. Default 0.05
grid (bool) – Show grid. Default is True
grid_color (str) – Matplotlib color of the grid. Default “k”
grid_style (str) – Matplotlib style of the grid. Default “:”

Examples

>>> l = linset.random_fisher(position=lin(120, 40))
>>> ot = l.ortensor()
>>> s = VollmerPlot(title="Point distribution")
>>> s.point(ot)
>>> s.show()

path(*args, **kwargs): Plot EllipsoidSet as path

point(*args, **kwargs): Plot ellipsoid as point

class apsg.plotting.RamsayPlot(*args, **kwargs)

Bases: FabricPlot

Represents the Ramsay deformation plot.

Keyword Arguments:

title (str) – figure title. Default None.
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
ticks (bool) – Show ticks. Default True
n_ticks (int) – Number of ticks. Default 10
tick_size (float) – Size of ticks. Default 0.2
margin (float) – Size of margin. Default 0.05
grid (bool) – Show grid. Default is True
grid_color (str) – Matplotlib color of the grid. Default “k”
grid_style (str) – Matplotlib style of the grid. Default “:”

Examples

>>> l = linset.random_fisher(position=lin(120, 40))
>>> ot = l.ortensor()
>>> s = RamsayPlot(title="Point distribution")
>>> s.point(ot)
>>> s.show()

path(*args, **kwargs): Plot EllipsoidSet as path

point(*args, **kwargs): Plot ellipsoid as point

class apsg.plotting.FlinnPlot(*args, **kwargs)

Bases: FabricPlot

Represents the Ramsay deformation plot.

Keyword Arguments:

title (str) – figure title. Default None.
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
ticks (bool) – Show ticks. Default True
n_ticks (int) – Number of ticks. Default 10
tick_size (float) – Size of ticks. Default 0.2
margin (float) – Size of margin. Default 0.05
grid (bool) – Show grid. Default is True
grid_color (str) – Matplotlib color of the grid. Default “k”
grid_style (str) – Matplotlib style of the grid. Default “:”

Examples

>>> l = linset.random_fisher(position=lin(120, 40))
>>> ot = l.ortensor()
>>> s = FlinnPlot(title="Point distribution")
>>> s.point(ot)
>>> s.show()

path(*args, **kwargs): Plot EllipsoidSet as path

point(*args, **kwargs): Plot Ellipsoid as point

class apsg.plotting.HsuPlot(*args, **kwargs)

Bases: FabricPlot

Represents the Hsu fabric plot.

Keyword Arguments:

title (str) – figure title. Default None.
title_kws (dict) – dictionary of keyword arguments passed to matplotlib suptitle method.
ticks (bool) – Show ticks. Default True
n_ticks (int) – Number of ticks. Default 10
tick_size (float) – Size of ticks. Default 0.2
margin (float) – Size of margin. Default 0.05
grid (bool) – Show grid. Default is True
grid_color (str) – Matplotlib color of the grid. Default “k”
grid_style (str) – Matplotlib style of the grid. Default “:”

Examples

>>> l = linset.random_fisher(position=lin(120, 40))
>>> ot = l.ortensor()
>>> s = HsuPlot(title="Point distribution")
>>> s.point(ot)
>>> s.show()

path(*args, **kwargs): Plot EllipsoidSet as path

point(*args, **kwargs): Plot Ellipsoid as point

apsg.plotting.quicknet(*args, **kwargs)

Function to quickly show or save StereoNet from args

Parameters:

args – object(s) to be plotted. Instaces of Vector3, Foliation, Lineation, Pair, Fault, Cone, Vector3Set, FoliationSet, LineationSet, PairSet or FaultSet.

Keyword Arguments:

savefig (bool) – True to save figure. Default False
filename (str) – filename for figure. Default stereonet.png
savefig_kwargs (dict) – dict passed to plt.savefig
fol_as_pole (bool) – True to plot planar features as poles, False for plotting as great circle. Default False
method (Additional kwargs are passed to StereoNet)

Example

>>> l = linset.random_fisher(position=lin(120, 50))
>>> f = folset.random_fisher(position=lin(300, 40))
>>> quicknet(f, l)