Documentation details

Author: tobiste

NAMESPACE

@@ -42,6 +42,7 @@ S3method(flinn,ellipsoid)
 S3method(flinn,ortensor)
 S3method(flinn_plot,default)
 S3method(flinn_plot,ellipsoid)
+S3method(flinn_plot,list)
 S3method(flinn_plot,ortensor)
 S3method(flinn_plot,spherical)
 S3method(geodesic_mean,Line)

R/best_pole.R

@@ -457,7 +457,7 @@ regression_greatcircle <- function(x, val = seq_len(nrow(x)), iterations = 1000L
   }
 
   rot_vec <- as.Vec3(rot[, 3])
-  
+
   result <- list(
     vec = Spherical(rot_vec, class(x)[1]),
     range = a,
@@ -478,7 +478,7 @@ regression_greatcircle <- function(x, val = seq_len(nrow(x)), iterations = 1000L
     result$points <- lapply(
       seq(from = min(val), to = max(val), length.out = (n_points + 1)),
       result$prediction
-    ) |> 
+    ) |>
       list_vec()
   }
 

R/confidence.R

@@ -79,4 +79,3 @@ confidence_ellipse <- function(x, n_iter = 10000L, alpha = 0.05, res = 512L, iso
     ellipse = ellipse
   )
 }
-

R/data.R

@@ -166,7 +166,7 @@
 "ramsay"
 
 
-#' 3D Strain Data
+#' 3D Strain Data I
 #'
 #' Example data from Holst and Fossen (1987) containing 3D strain data from 17 localities in the West Norwegian Caledonides.
 #' The data gives the  difference of the  \eqn{\epsilon_1} and \eqn{\epsilon_2} (`e1e2`) and \eqn{\epsilon_2} and \eqn{\epsilon_3} (`e2e3`)
@@ -183,6 +183,25 @@
 "holst"
 
 
+#' 3D Strain Data II
+#'
+#' Example data from J.R. Hossack (1968) containing 3D strain data from 81
+#' localities from the Bygdin Conglomerate by the Upper Jotun Nappe. The data
+#' gives the mean axial ratios (X, Y, Z) of the deformed pebbles.
+#' Different to Hossack, here X is the longest axes, and Z the shortest.
+#'
+#' @docType data
+#'
+#' @usage data('hossack1968')
+#'
+#' @format An object of class `matrix`
+#' @family datasets
+#' @keywords datasets
+#' @examples
+#' data("hossack1968")
+#' head(hossack1968)
+"hossack1968"
+
 #' Vorticity from Rotated Porphyroclasts
 #'
 #' 194 measurements of aspect ratio and orientation (wrt. foliation) of rotated

R/deftensor.R

@@ -32,7 +32,7 @@
 #'
 #' \item{`defgrad_from_vectors()` creates `"defgrad"` tensor representing rotation around the
 #' axis perpendicular to both vectors and rotate `v1` to `v2`.}
-#' 
+#'
 #' \item{`defgrad_from_axisangle`  creates `"defgrad"` tensor representing a rigid-body
 #' rotation about an axis and an angle.}
 #'

R/density.R

@@ -335,7 +335,7 @@ density_calc <- function(x,
                          weights = NULL, upper.hem = FALSE, r = 1) {
   x_grid <- y_grid <- seq(-1, 1, length.out = n)
 
-  grid <- expand.grid(x_grid, y_grid) |> 
+  grid <- expand.grid(x_grid, y_grid) |>
     as.matrix()
   dg <- density_grid(x, weights = weights, upper.hem = upper.hem, kamb = TRUE, FUN = FUN, sigma = sigma, ngrid = n, r = r)
   density_matrix <- matrix(dg$density, nrow = n, byrow = FALSE)

R/ellipsoid.R

@@ -13,6 +13,10 @@
 #' @family ellipsoid
 #' @seealso [ortensor()]
 #'
+#' @details
+#' The eigenvalues \eqn{\lambda} of the deformation matrix are the quadratic
+#' forms of the principal stretches \eqn{s} (\eqn{s = 1 + \epsilon = l/l_0}).
+#'
 #' @returns
 #' `is.ellipsoid` returns `TRUE` if `x` is an `"ellipsoid"` object, and `FALSE` otherwise.
 #'
@@ -78,9 +82,19 @@ print.ellipsoid <- function(x, ...) {
 #' @returns object of class `"ellipsoid"`
 #' @export
 #'
+#' @details
+#' The eigenvalues \eqn{\lambda} of the deformation matrix are the quadratic
+#' forms of the principal stretches \eqn{s} (\eqn{s = 1 + \epsilon = l/l_0}).
+#'
+#' @family ellipsoid
+#'
 #' @examples
 #' el <- ellipsoid_from_stretch(4, 3, 1)
 #' principal_stretch(el)
+#'
+#' lapply(seq.int(nrow(hossack1968)), function(i) {
+#'   ellipsoid_from_stretch(hossack1968[i, 3], hossack1968[i, 2], hossack1968[i, 1])
+#' })
 ellipsoid_from_stretch <- function(x = 1, y = 1, z = 1) {
   el <- matrix(c(
     x^2, 0, 0,
@@ -97,31 +111,35 @@ ellipsoid_from_stretch <- function(x = 1, y = 1, z = 1) {
 #' lengths (in any order), an object of class `"ellipsoid"`, or an object of class `"ortensor"`.
 #'
 #' @returns positive numeric
+#' @family ellipsoid
 #' @name ellipsoid-params
 #'
-#' @details
-#'
-#' \deqn{e_i = \log s_i} with \eqn{s1 \geq s2 \geq s3} the semi-axis lengths of the ellipsoid.
+#' @details The natural strain is
+#' \deqn{\bar{\epsilon}_i = \log s_i = \log(1 + \epsilon_i)} with \eqn{s_1 \geq s_2 \geq s_3} the semi-axis lengths of the ellipsoid, or
+#' \eqn{\epsilon_i} the strains (elongation) given by \eqn{\epsilon = \frac{l-l_0}{l_0}} (hence \eqn{s = \frac{l}{l_0}}).
 #'
-#' Lode's shape parameter:
-#' \deqn{\nu = \frac{2 e_2 - e_1 - e_3}{e_1-e_3}}
-#' with \eqn{e_1 \geq e_2 \geq e_3}. Note that \eqn{\nu}  is undefined for spheres,
-#' but we arbitrarily declare \eqn{\nu=0} for them.
-#' Otherwise \eqn{-1 \geq \nu \geq 1}. \eqn{\nu=-1} for prolate spheroids and \eqn{\nu=1} for oblate spheroids.
+#' Lode's parameter for **strain symmetry**:
+#' \deqn{\nu = \frac{2 \bar{\epsilon}_2 - \bar{\epsilon}_1 - \bar{\epsilon}_3}{\bar{\epsilon}_1-\bar{\epsilon}_3}}
+#' with \eqn{\bar{\epsilon}_1 \geq \bar{\epsilon}_2 \geq \bar{\epsilon}_3}. Note that \eqn{\nu} is undefined for spheres,
+#' but we arbitrarily declare \eqn{\nu=0} for them (plane strain).
+#' Otherwise \eqn{-1 \geq \nu \geq 1}. \eqn{\nu=-1} for prolate spheroids (constriction) and \eqn{\nu=1} for oblate spheroids (flattening).
 #'
-#' Octahedral shear strain \eqn{e_s} (Nadai 1963):
-#' \deqn{e_s = \sqrt{\frac{(e_1 - e_2)^2 + (e_2 - e_3)^2 + (e_1 - e_3)^2 }{3}}}
+#' **Octahedral shear strain** \eqn{\bar{\epsilon}_s} (Nádai 1963):
+#' \deqn{\bar{\epsilon}_s = \sqrt{\frac{(\bar{\epsilon}_1 - \bar{\epsilon}_2)^2 + (\bar{\epsilon}_2 - \bar{\epsilon}_3)^2 + (\bar{\epsilon}_1 - \bar{\epsilon}_3)^2 }{3}}}
+#' This is the amount of strain assuming coaxial deformation (pure-shear).
 #'
-#' Strain symmetry (Flinn 1963):
+#' **Strain symmetry** (Flinn 1963):
 #' \deqn{k = \frac{s_1/s_2 - 1}{s_2/s_3 - 1}}
+#' The value ranges from 0 to \eqn{\infty}, and is 0 for oblate ellipsoids
+#' (flattening), 1 for plane strain and  \eqn{\infty} for prolate ellipsoids (constriction).
 #'
-#' and strain intensity (Flinn 1963):
+#' and **strain intensity** (Flinn 1963):
 #' \deqn{d = \sqrt{(s_1/s_2 - 1)^2 + (s_2/s_3 - 1)^2}}
-#'
+#' This is analogous to Nadai's strain parameter.
 #'
 #' Jelinek (1981)'s \eqn{P_j} parameter:
-#' \deqn{P_j = e^{\sqrt{2 \vec{v}\cdot \vec{v}}}}
-#' with \eqn{\vec{v} = e_i - \frac{\sum e_i}{3}}
+#' \deqn{P_j = \bar{\epsilon}^{\sqrt{2 \vec{v}\cdot \vec{v}}}}
+#' with \eqn{\vec{v} = \bar{\epsilon}_i - \frac{\sum \bar{\epsilon}_i}{3}}
 #'
 #' @references
 #' Flinn, Derek.(1963): "On the statistical analysis of fabric diagrams."
@@ -133,15 +151,15 @@ ellipsoid_from_stretch <- function(x = 1, y = 1, z = 1) {
 #'  the metals iron, copper and nickel"*], Zeitschrift für Physik, vol. 36 (November),
 #'  pp. 913–939, \doi{10.1007/BF01400222}
 #'
-#' Nadai, A., and Hodge, P. G., Jr. (1963): "Theory of Flow and Fracture of Solids,
+#' Nádai, A., and Hodge, P. G., Jr. (1963): "Theory of Flow and Fracture of Solids,
 #' vol. II." ASME. J. Appl. Mech. December 1963; 30(4): 640. \doi{10.1115/1.3636654}
 #'
 #' Jelinek, Vit. "Characterization of the magnetic fabric of rocks."
 #' Tectonophysics 79.3-4 (1981): T63-T67.
 #'
-#' @seealso [shape_params()], [ot_eigen()]
+#' @seealso [shape_params()], [ot_eigen()], [hsu_plot()], [flinn_plot()]
 #' @examples
-#' # Generate some random data
+#' # Generate some random orientation data
 #' set.seed(20250411)
 #' dat <- rvmf(100, k = 20)
 #' s <- principal_stretch(dat)
@@ -158,7 +176,7 @@ ellipsoid_from_stretch <- function(x = 1, y = 1, z = 1) {
 #' # Shape-related tensor invariant of ellipsoids
 #' shape_invariant(s)
 #'
-#' # Lode's shape parameter
+#' # Lode's shape parameter for the strain symmetry ratio
 #' lode(s)
 #'
 #' # Nadai's octahedral shear strain
@@ -171,6 +189,12 @@ ellipsoid_from_stretch <- function(x = 1, y = 1, z = 1) {
 #' flinn(s)
 #'
 #' kind(s)
+#'
+#' # Ellipsoid data
+#' hossack_ell <- lapply(seq.int(nrow(hossack1968)), function(i) {
+#'   ellipsoid_from_stretch(hossack1968[i, 3], hossack1968[i, 2], hossack1968[i, 1])
+#' })
+#' sapply(hossack_ell, nadai)
 NULL
 
 

R/fabric_plots.R

@@ -1,6 +1,6 @@
 # Fabric intensities and plots -------------------------------------------------
 
-#' Orientation tensor fabric intensity and shape
+#' Fabric Intensity and Shape of Orientation Tensor
 #'
 #' Fabric intensity and shape parameters of the orientation tensor based on Vollmer (1990)
 #'
@@ -66,7 +66,7 @@ vollmer <- function(x) {
   c(P = P, G = G, R = R, B = B, C = C, I = I, D = D, U = U)
 }
 
-#' Fabric plot of Vollmer (1990)
+#' Fabric Plot of Vollmer (1990)
 #'
 #' Creates a fabric plot using the eigenvalue method
 #'
@@ -219,7 +219,7 @@ vollmer_plot.list <- function(x, labels = NULL, add = FALSE, ngrid = c(5, 5, 5),
 }
 
 
-#' Fabric plot of Woodcock (1977)
+#' Fabric Plot of Woodcock (1977)
 #'
 #' Creates a fabric plot using the eigenvalue method
 #'
@@ -294,23 +294,48 @@ woodcock_plot <- function(x, labels = NULL, add = FALSE, max = 7, main = "Woodco
   invisible(x_eigen)
 }
 
-#' Fabric plot of Hsu (1965)
+#' Fabric Plot of Hsu (1965)
 #'
-#' 3D strain diagram using the Hsu (1965) method to display the natural
-#' octahedral strain (Nádai, 1950) and Lode's parameter (Lode, 1926).
+#' 3D strain diagram using the Hsu (1965) method to display the amount of the natural
+#' octahedral strain, \eqn{\bar{\epsilon}_s} (Nádai, 1950) and Lode's parameter
+#' for the symmetry of strain \eqn{\nu} (Lode, 1926).
 #'
-#' @param x accepts the following objects: a two-column matrix where first column is the ratio of maximum strain and
-#' intermediate strain (X/Y) and second column is the the ratio of intermediate strain and minimum strain (Y/Z);
-#' objects of class `"Vec3"`, `"Line"`, `"Ray"`, or `"Plane"`; or `"ortensor"` objects.
+#' @param x accepts the following objects: a two-column matrix where first
+#' column is the ratio of maximum strain and
+#' intermediate strain (X/Y) and second column is the the ratio of intermediate
+#' strain and minimum strain (Y/Z);
+#' objects of class `"Vec3"`, `"Line"`, `"Ray"`, `"Plane"`, `"ortensor"` and `"ellipsoid"` objects.
+#' Tensor objects can also be lists of such objects (`"ortensor"` and `"ellipsoid"`).
 #' @inheritParams Rphi_plot
 #' @param labels character. text labels
 #' @param add logical. Should data be plotted to an existing plot?
 #' @param ... plotting arguments passed to [graphics::points()]
 #' @param es.max maximum strain for scaling.
 #'
-#' @returns plot and when stored as object, a list containing the Lode parameter `lode` and the natural octahedral strain `es`.
+#' @returns a list containing the Lode parameter `lode` and the natural octahedral strain `es`.
 #' @family fabric-plot
 #' @seealso [lode()] for Lode parameter, and [nadai] for natural octahedral strain.
+#' [ellipsoid()] class, [ortensor()] class
+#'
+#' @details
+#' The **amount of strain** related to the natural octahedral unit shear \eqn{\bar{\gamma}_o}
+#' is (Nádai, 1963, p.73):
+#' \deqn{\bar{\epsilon}_s = \frac{\sqrt{3}}{2} \bar{\gamma}_o}
+#' where \eqn{\bar{\gamma}_o} is defined as
+#' \deqn{\bar{\gamma}_o = \frac{2}{3} \sqrt{(\bar{\epsilon}_1 - \bar{\epsilon}_2)^2 + (\bar{\epsilon}_2 - \bar{\epsilon}_3)^2 + (\bar{\epsilon}_3 - \bar{\epsilon}_1)^2}}
+#' and \eqn{\bar{\epsilon}} is the natural strain (\eqn{\bar{\epsilon} = \log{1+\epsilon}})
+#' and \eqn{\epsilon} is the conventional strain given by \eqn{\epsilon = \frac{l-l_0}{l_0}}
+#' where \eqn{l} and \eqn{l_0} is the length after and before the strain, respectively (Nádai, 1959, p.70).
+#' The amount of strain \eqn{\bar{\epsilon}_s} is directly proportional to the
+#' amount of mechanical work applied in the coaxial component of strain.
+#'
+#' The **symmetry of strain** is defined by Lode’s (1926, p.932) ratio (\eqn{\nu}):
+#' \deqn{\nu = \frac{2 \bar{\epsilon}_2 - \bar{\epsilon}_1 - \bar{\epsilon}_3}{\bar{\epsilon}_1 - \bar{\epsilon}_3}}
+#' The values range between -1 and +1, where -1 gives constriction, 0 gives
+#' plane strain, and +1 gives flattening.
+#'
+#' @note Hossack (1968) was the first one to use this graphical representation
+#' of 3D strain and called the plot "Strain plane plot"
 #'
 #' @name hsu_plot
 #'
@@ -328,10 +353,12 @@ woodcock_plot <- function(x, labels = NULL, add = FALSE, max = 7, main = "Woodco
 #' (Southern Norway). Tectonophysics, 5(4), 315–339. \doi{10.1016/0040-1951(68)90035-8}
 #'
 #' @examples
+#' # default
 #' R_XY <- holst[, "R_XY"]
 #' R_YZ <- holst[, "R_YZ"]
 #' hsu_plot(cbind(R_XY, R_YZ), col = "#B63679", pch = 16, type = "b")
 #'
+#' # orientation data
 #' set.seed(20250411)
 #' mu <- Line(120, 50)
 #' x <- rvmf(100, mu = mu, k = 1)
@@ -340,6 +367,12 @@ woodcock_plot <- function(x, labels = NULL, add = FALSE, max = 7, main = "Woodco
 #' set.seed(20250411)
 #' y <- rvmf(100, mu = mu, k = 20)
 #' hsu_plot(ortensor(y), labels = "y", col = "red", add = TRUE)
+#'
+#' # ellipsoid objects
+#' hossack_ell <- lapply(seq.int(nrow(hossack1968)), function(i) {
+#'   ellipsoid_from_stretch(hossack1968[i, 3], hossack1968[i, 2], hossack1968[i, 1])
+#' })
+#' hsu_plot(hossack_ell, col = "#B63679", pch = 16)
 NULL
 
 #' @rdname hsu_plot
@@ -532,16 +565,31 @@ hsu_plot.list <- function(x, labels = NULL, add = FALSE, es.max = 3, main = "Hsu
 }
 
 
-#' Flinn diagram
+#' Flinn Diagram
+#'
+#' Plots the strain ratios X/Y against Y/Z and shows the strain intensity and
+#' the strain symmetry after Flinn (1965)
 #'
 #' @inheritParams hsu_plot
 #' @param R.max numeric. Maximum aspect ratio for scaling.
 #' @param log logical. Whether the axes should be in logarithmic scale.
 #'
-#' @returns plot and when stored as an object, the multiplication factors for X, Y and Z.
+#' @returns list. Relative magnitudes of X, Y and Z (Z=1).
 #'
 #' @family fabric-plot
 #' @name flinn_plot
+#' @seealso [ellipsoid()] class, [ortensor()] class, [flinn()] for Flinn's
+#' strain parameters.
+#'
+#' @details **Strain symmetry** (Flinn 1965):
+#' \deqn{k = \frac{s_1/s_2 - 1}{s_2/s_3 - 1}}
+#' where \eqn{s_1 \geq s_2 \geq s_3} the semi-axis lengths of the ellipsoid.
+#' The value ranges from 0 to \eqn{\infty}, and is 0 for oblate ellipsoids
+#' (flattening), 1 for plane strain and  \eqn{\infty} for prolate ellipsoids (constriction).
+#'
+#' and **strain intensity** (Flinn 1965):
+#' \deqn{d = \sqrt{(s_1/s_2 - 1)^2 + (s_2/s_3 - 1)^2}}
+#'
 #'
 #' @references Flinn, D. (1965). On the Symmetry Principle and the Deformation
 #' Ellipsoid. Geological Magazine, 102(1), 36–45. \doi{10.1017/S0016756800053851}
@@ -553,6 +601,12 @@ hsu_plot.list <- function(x, labels = NULL, add = FALSE, es.max = 3, main = "Hsu
 #' flinn_plot(cbind(R_XY, R_YZ), log = FALSE, col = "#B63679", pch = 16)
 #' flinn_plot(cbind(R_XY, R_YZ), log = TRUE, col = "#B63679", pch = 16, type = "b")
 #'
+#' # ellipsoid objects
+#' hossack_ell <- lapply(seq.int(nrow(hossack1968)), function(i) {
+#'   ellipsoid_from_stretch(hossack1968[i, 3], hossack1968[i, 2], hossack1968[i, 1])
+#' })
+#' flinn_plot(hossack_ell, col = "#B63679", pch = 16, log = TRUE)
+#'
 #' set.seed(20250411)
 #' mu <- Line(120, 50)
 #' x <- rvmf(100, mu = mu, k = 1)
@@ -669,3 +723,16 @@ flinn_plot.ellipsoid <- function(x, ...) {
 flinn_plot.spherical <- function(x, ...) {
   flinn_plot.ortensor(ortensor(x), ...)
 }
+
+#' @rdname flinn_plot
+#' @export
+flinn_plot.list <- function(x, ...) {
+  a <- lapply(x, principal_stretch) |>
+    sapply(sort, decreasing = TRUE) |>
+    t()
+
+  R_xy <- a[, 1] / a[, 2]
+  R_yz <- a[, 2] / a[, 3]
+
+  flinn_plot.default(cbind(R_xy, R_yz), ...)
+}

R/geodesic_mean.R

@@ -552,4 +552,3 @@ symmetry_group <- function(group = c("triclinic", "ray_in_plane", "line_in_plane
     )
   }
 }
-