Skip to content
danjgmoyoPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

RoseLab — Circular Orientation Analysis for QGIS

RoseLab is a comprehensive orientation analysis plugin for QGIS. It produces publication-quality rose diagrams and performs full circular statistics, length distribution analysis, fracture intensity metrics, sampling bias correction, and two-sample comparison for any line vector dataset.

Designed for structural geology (lineaments, faults, joints, veins, dykes), but applicable to any azimuthal line data — drainage networks, roads, coastal features, landslide scarps, or remote sensing lineaments.


Requirements

  • QGIS 3.16 or later (tested on 3.28 LTS and 3.36)
  • Python 3 (bundled with QGIS)
  • scipy — for KDE, fracture set detection, and distribution fitting

Install via the OSGeo4W Shell (Windows) or terminal (Linux/macOS):

pip install scipy

Installation

From the QGIS Plugin Repository (recommended)

  1. Plugins → Manage and Install Plugins
  2. Search RoseLab
  3. Enable Show experimental plugins if needed
  4. Click Install Plugin

From ZIP

  1. Download the latest ZIP from Releases
  2. Plugins → Manage and Install Plugins → Install from ZIP
  3. Select the ZIP and click Install Plugin

Manual

Copy the roselab/ folder to your QGIS plugins directory:

Platform Path
Windows C:\Users\<username>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\
Linux ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
macOS ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/

Then restart QGIS and enable the plugin under Plugins → Manage and Install Plugins → Installed.


Quick Start

Processing Algorithm

  1. Load a line vector layer (shapefile, GeoPackage, etc.)
  2. Open Processing Toolbox → RoseLab → Rose Diagram — Orientation Analysis
  3. Select your layer
  4. Set output file paths for PNG and CSV
  5. Click Run

Interactive Studio

  1. Click the RoseLab toolbar button (or Plugins → RoseLab → RoseLab Studio)
  2. Select a line layer from the Layer dropdown
  3. Adjust parameters — the preview updates automatically
  4. Click Export Outputs... to save all figures and CSVs to a folder

Features

Rose Diagram

  • Bidirectional (0–180°, for undirected features like joints and lineaments) or Full circle (0–360°, for directed features like palaeocurrent indicators)
  • Half-rose option (clips display to northern hemisphere)
  • Weight types — frequency count | frequency % | cumulative length | length %
  • Petal scaling — linear | square-root | logarithmic | area-proportion (recommended by Sanderson & Peacock 2020)
  • Attribute field weight — weight petals by any numeric field (aperture, displacement, confidence score, intensity rating)
  • Auto bin-size recommendation (Sanderson & Peacock 2020)

Overlays

  • Von Mises KDE smooth density curve (avoids bin-boundary sensitivity)
  • Automatic fracture set detection — up to 4 dominant sets (S1–S4)
  • Set isolation — click a detected set to filter bearings to that window and re-run all analysis
  • Mean vector ray with Watson (1956) confidence arc at 90/95/99%
  • Concentric reference circles
  • User-defined tectonic reference directions (e.g. Rift:045; Shear Zone:130)

Multi-layer

  • Overlay a second dataset as outlined petals on the same rose (visual two-sample comparison)
  • Watson U2 non-parametric two-sample test (Watson 1962) — recommended over Watson-Williams F-test for multimodal structural data (Landler et al. 2021)

Statistics

Statistic Method
Circular mean azimuth (0–180° and 0–360°) Mardia & Jupp (2000)
Circular standard deviation Mardia & Jupp (2000)
Mean resultant length R Mardia & Jupp (2000)
Anisotropy index Woodcock (1977) eigenvalue method
Shannon entropy H —
Rayleigh test (p-value) Tests H₀: uniform distribution
Kuiper test More powerful for multimodal data
Cardinal quadrant summary N / NE / E / SE %

Filters

  • Min/max length filter (exclude short or long segments)
  • Up to two azimuth filter windows (isolate a known fault set)
  • Rotation offset (correct for magnetic declination or regional reference frame)

Sampling Bias

  • Terzaghi (1965) correction for systematic under-sampling of features parallel to the scanline or DEM illumination direction

Fracture Intensity (requires study area polygon layer)

Metric Definition
P20 Fracture traces per unit area
P21 Total trace length per unit area
P22 Dimensionless intensity (P21 × mean length)

After Sanderson & Nixon (2015), J. Struct. Geol. 72:55–66.

Length Distribution Analysis

Four distributions fitted by Maximum Likelihood Estimation:

  • Power law (Pareto) — exponent α, lower bound x_min
  • Lognormal — μ and σ
  • Exponential — rate λ
  • Gamma — shape and scale

Model selection by AIC (lower = better) and KS test p-value. Output is a 6-panel figure: PDF (linear), log-binned PDF, model comparison bar chart, log-log PDF, CDF, CCDF.

Bias warnings included for: right-censoring, truncation (detection limit), and scale dependence.


Outputs

Output Format Description
Rose diagram PNG, PDF, SVG Publication-quality at selectable DPI
Distribution analysis PNG 6-panel MLE figure
Statistics CSV All computed statistics
Bin data CSV Per-bin bearing edges, frequency, length — compatible with RockWorks, Stereonet, GEOrient, Dips, OpenStereo, Excel

Known Biases

Right-censoring

Fracture traces terminating at the study area boundary are recorded shorter than their true length. Treat length statistics as minimum estimates when many lineaments reach the map edge. Ref: Mauring & Tveranger (2025), Solid Earth.

Truncation (detection limit)

Lineaments shorter than your detection threshold (~3–5 pixel lengths for DEM/satellite data) are absent. Do not interpret the distribution shape below this limit. Ref: Bonnet et al. (2001), Rev. Geophysics.

Scale dependence

Results from regional satellite lineaments (km-scale) and outcrop fracture traces (m-scale) cannot be directly compared. Always report the scale range of your dataset.

Geographic CRS

If your layer CRS uses geographic degrees (longitude/latitude), length values will be in degrees — not meaningful for length distribution or intensity analysis. Reproject to a projected CRS (e.g. UTM) before running RoseLab.


Method References

Method Reference
Bin size recommendation Sanderson & Peacock (2020), Earth-Sci. Rev. 201, 103055
Power-law fitting Clauset et al. (2009), SIAM Review 51(4)
Length distributions Bonnet et al. (2001), Rev. Geophysics 39(3)
Distribution model selection Rizzo et al. (2024), J. Struct. Geol.
Censoring Mauring & Tveranger (2025), Solid Earth 16
Rayleigh test Mardia & Jupp (2000), Directional Statistics, Wiley
Kuiper test Fisher (1993), Statistical Analysis of Circular Data
Watson U2 test Watson (1962), Biometrika 49(1/2)
Watson U2 recommendation Landler et al. (2021), Scientific Reports 11
Confidence arc Watson (1956)
Anisotropy index Woodcock (1977), GSA Bulletin 88(9)
Terzaghi correction Terzaghi (1965), Geotechnique 15(3)
P20/P21 intensity Sanderson & Nixon (2015), J. Struct. Geol. 72

Citing RoseLab

If you use RoseLab in published work, please cite the key methodological references relevant to your analysis and describe the tool as:

"Orientation analysis was performed using RoseLab v1.0.0, a QGIS plugin (Moyo 2024), implementing methods following Sanderson & Peacock (2020), Clauset et al. (2009), and Sanderson & Nixon (2015)."


License

GNU General Public License v2 or later. See LICENSE.


Author

Daniel Moyo moyodanj@gmail.com github.com/moyodanj/roselab

Bug reports and feature requests via GitHub Issues.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages