fractopo 0.9.2

Fracture Network Analysis

• Full Documentation is hosted on GitHub

fractopo is a Python library/application that contains tools for validating and analysing lineament and fracture trace maps (fracture networks). It is targeted at structural geologists working on the characterization of bedrock fractures from outcrops and through remote sensing. fractopo is available as a Python library and through a command-line interface. As a Python library, the use of fractopo requires prior (Python) programming knowledge. However, if used through the command-line, using fractopo only requires general knowledge of command-line interfaces in your operating system of choice.

Overview of fractopo

Visualisation of fractopo data. fractopo analyses the trace data that can e.g. be digitized from drone orthophotographs (=fractures) or from digital elevation models (=lineaments). The displayed branches and nodes are extracted with fractopo.

Quick navigation

• Installation

  • conda

  • pip

  • poetry

  • container (web interface)

• Usage

  • Input data

  • Trace validation

  • Geometric and topological trace network analysis

• Documentation

• Citing

• Support

• References

• Development

Installation

pip and poetry installation only supported for linux -based operating systems. For Windows and MacOS install using (ana)conda. A container exists for exposing a simplified web interface, created with marimo.

conda

• This is the only supported installation method for Windows and MacOS!

# Create new environment for fractopo (recommended but optional)
conda env create -n fractopo-env
conda activate fractopo-env
# Install to the newly created environment
# Available on conda-forge channel
conda install -c conda-forge fractopo

pip

The module is on PyPI.

pip install fractopo

poetry

For usage:

poetry add fractopo

For development, use poetry to install the latest development version of fractopo:

git clone https://github.com/nialov/fractopo
cd fractopo
poetry install --all-extras

container (web interface)

A marimo + FastAPI app exists in ./marimos, api.py. This is included in the ghcr.io/nialov/fractopo-app:latest image. By default, when the image is run, the network analysis app is run accessible at root (/). To access validation functinality, use path /validation when accessing the container (e.g. localhost:2718/validation). Network analysis is also explicitly available at /network.

The app host and port can be chosen with HOST (default is 0.0.0.0) and PORT (default is 2718) environment variables. With docker you can, of course, expose in whichever port you choose.

Example docker invocations are below.

To run app:

docker run --rm --interactive --tty --publish 2718:2718 ghcr.io/nialov/fractopo-app:latest

After running the above command, the network analysis functionality should be available at http://localhost:2718/network and validation functionality at http://localhost:2718/validation.

Usage

fractopo has two main use cases:

1. Validation of lineament & fracture trace data

2. Analysis of lineament & fracture trace data

Validation is done to make sure the data is valid for the analysis and is crucial as analysis cannot take into account different kinds of geometric and topological inconsistencies between the traces. Capabilities and associated guides are inexhaustibly listed in the table below.

Functionality	Tutorial/Guide/Example
Validation of trace data	Validation 1; Validation 2
Visualize trace map data	Visualizing
Topological branches and nodes	Network; Topological
Trace and branch length distributions	Length-distributions
Orientation rose plots	Orientation 1; Orientation 2
Plot topological ternary node and branch proportions	Proportions
Cross-cutting and abutting relationships	Relationships 1; Relationships 2;
Geometric and topological fracture network parameters	Parameters
Contour grids of fracture network parameters	Contour-grids
Multi-scale length distributions	Multi-scale

For a short tutorial on use of fractopo, continue reading:

Input data

Reading and writing spatial filetypes is done in geopandas and you should see geopandas documentation for more advanced read-write use cases:

• https://geopandas.org/

Simple example with trace and area data in GeoPackages:

import geopandas as gpd

# Trace data is in a file `traces.gpkg` in current working directory
# Area data is in a file `areas.gpkg` in current working directory
trace_data = gpd.read_file("traces.gpkg")
area_data = gpd.read_file("areas.gpkg")

Trace data should consists of polyline geometries, i.e., of LineString type. Trace data in MultiLineString format area not supported. Area data should consists of polygon geometries, i.e., of either Polygon or MultiPolygon type.

Trace validation

Trace data must be validated using fractopo validation functionality before analysis. The topological analysis of lineament & fracture traces implemented in fractopo will not tolerate uncertainty related to the topological abutting and snapping relationships between traces. See the documentation for further info on validation error types. Trace validation is recommended before all analysis using Network. Trace and target area data can be validated for further analysis with a Validation object:

from fractopo import Validation

validation = Validation(
    trace_data,
    area_data,
    name="mytraces",
    allow_fix=True,
)

# Validation is done explicitly with `run_validation` method
validated_trace_data = validation.run_validation()

Trace validation is also accessible through the fractopo command-line interface, fractopo tracevalidate which is more straightforward to use than through Python calls. Note that all subcommands of fractopo are available by appending them after fractopo.

tracevalidate always requires the target area that delineates trace data.

# Get full up-to-date command-line interface help
fractopo tracevalidate --help

# Basic usage example:
fractopo tracevalidate /path/to/trace_data.shp /path/to/target_area.shp\
   --output /path/to/validated_trace_data.shp

# Or with a printed summary and automatic saving to validated/ directory
fractopo tracevalidate /path/to/trace_data.shp /path/to/target_area.shp\
   --summary

Geometric and topological trace network analysis

fractopo can be used to extract lineament & fracture size, abundance and topological parameters from two-dimensional lineament and fracture trace, branch and node data.

Trace and target area data (GeoDataFrames) are passed into a Network object which has properties and functions for returning and visualizing different parameters and attributes of trace data.

from fractopo import Network

# Initialize Network object and determine the topological branches and nodes
network = Network(
    trace_data,
    area_data,
    # Give the Network a name!
    name="mynetwork",
    # Specify whether to determine topological branches and nodes
    # (Required for almost all analysis)
    determine_branches_nodes=True,
    # Specify the snapping distance threshold to define when traces are
    # snapped to each other. The unit is the same as the one in the
    # coordinate system the trace and area data are in.
    # In default values, fractopo assumes a metric unit and using metric units
    # is heavily recommended.
    snap_threshold=0.001,
    # If the target area used in digitization is a circle, the knowledge can
    # be used in some analysis
    circular_target_area=True,
    # Analysis on traces can be done for the full inputted dataset or the
    # traces can be cropped to the target area before analysis (cropping
    # recommended)
    truncate_traces=True,
)

# Properties are easily accessible
# e.g.,
network.branch_counts
network.node_counts

# Plotting is done by plot_ -prefixed methods
network.plot_trace_lengths()

Network analysis is also available through the fractopo command-line interface but using the Python interface (e.g. marimo, jupyter lab, ipython) is recommended when analysing Networks to have access to all available analysis and plotting methods. The command-line entrypoint is opinionated in what outputs it produces. Brief example of command-line entrypoint:

# Use --help to see all up-to-date arguments and help
fractopo network --help

fractopo network /path/to/trace_data.shp /path/to/area_data.shp\
   --name mynetwork

Data analysis workflow visualisation for fracture trace data (KB11). A. Target area for trace digitisation. B. Digitized traces and target area. C. Orthomosaic used as the base raster from which the traces are digitized from. D. Equal-area length-weighted rose plot of the fracture trace azimuths. E. Length distribution analysis of the trace lengths. F. Determined branches and nodes through topological analysis. G. Cross-cut and abutting relationships between chosen azimuth sets. H. Ternary plot of node (X, Y and I) proportions. I. Ternary plot of branch (C-C, C-I, I-I) proportions.

Documentation

Please visit the full documentation at: https://nialov.github.io/fractopo/index.html. I recommend starting with the tutorial notebook demonstrating network analysis functionality at https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html. The documentation source is in docs_src and examples directories and is built with sphinx.

Citing

To cite this software:

Ovaskainen, N., (2023). fractopo: A Python package for fracture
network analysis. Journal of Open Source Software, 8(85), 5300,
https://doi.org/10.21105/joss.05300

• To cite a specific version of fractopo you can use a zenodo provided DOI. E.g. https://doi.org/10.5281/zenodo.5957206 for version v0.2.6. See the zenodo page of fractopo for the DOI of each version: https://doi.org/10.5281/zenodo.5517485

Support

For issues of any kind: please create a GitHub issue here! Alternatively, you can contact the main developer by email at [e-mail].

References

For the scientific background, prior works, definition of traces, branches and nodes along with the explanation of the plots and the plotted parameters, you are referred to multiple sources:

• Sanderson and Nixon, 2015

  • Trace and branch size, abundance and topological parameter definitions.

• Ovaskainen et al, 2022

  • Application of fractopo for subsampling analysis of fracture networks.

• Ovaskainen et al, 2023

  • Application of fractopo for multi-scale lineament and fracture analysis

• Nyberg et al., 2018

  • A similar package to fractopo with a QGIS GUI.

  • NetworkGT GitHub

• Sanderson and Peacock, 2020

  • Discussion around rose plots and justification for using length-weighted equal-area rose plots.

• Alstott et al. 2014

  • Length distribution modelling using the Python 3 powerlaw package which fractopo uses

  • powerlaw GitHub

• Bonnet et al., 2001

  • Length distribution modelling review.

• My Master’s Thesis, Ovaskainen, 2020

  • Plots used in my Thesis were done with an older version of the same code used for this plugin.

Development

• The package interfaces are nearing stability and breaking changes in code should for the most part be included in the CHANGELOG.md after 25.4.2023. However, this is not guaranteed until the version reaches v1.0.0. The interfaces of Network and Validation can be expected to be the most stable.

• For general contributing guidelines, see CONTRIBUTING.rst

---