GitLocker: The Coding Marketplace

Description:

fractopo 0.6.0

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.

Full Documentation is hosted on GitHub

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.

Installation
pip and poetry installation only supported for linux -based
operating systems. For Windows and MacOS install using (ana)conda.

conda

Only (supported) installation method for Windows and MacOS!

# Create new environment for fractopo (recommended but optional)
conda env create fractopo-env
conda activate fractopo-env
# Available on conda-forge channel
conda install -c conda-forge fractopo

pip
The module is on PyPI.
# Non-development installation
pip install fractopo

poetry
For usage:
poetry add fractopo
For development, only poetry installation of fractopo is
supported:
git clone https://github.com/nialov/fractopo
cd fractopo
poetry install

Usage
fractopo has two main use cases:

Validation of lineament & fracture trace data
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 inexhaustively 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 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 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. 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:
fractopo network /path/to/trace_data.shp /path/to/area_data.shp\
--name mynetwork

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

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.

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
nikolasovaskainen@gmail.com.

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.

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

Development dependencies for fractopo include:

poetry

Used to handle Python package dependencies.

# Use poetry run to execute poetry installed cli tools such as invoke,
# nox and pytest.
poetry run '<cmd>'

copier

copier is a project templater. Many Python projects follow a similar
framework for testing, creating documentations and overall placement of
files and configuration. copier allows creating a template project
(e.g., https://github.com/nialov/nialov-py-template) which can be firstly

copier

copier is a project templater. Many Python projects follow a similar
framework for testing, creating documentations and overall placement of
files and configuration. copier allows creating a template project
(e.g., https://github.com/nialov/nialov-py-template) which can be firstly
cloned as the framework for your own package and secondly to pull updates
from the template to your already started project.

# To pull copier update from github/nialov/nialov-py-template
poetry run copier update

nix

fractopo is also packaged with nix. nix provides
declarative and immutable packaging which should make fractopo
last longer.

# To run the fractopo command-line using nix
nix run github:nialov/fractopo#fractopo -- --help

pytest

pytest is a Python test runner. It is used to run defined tests to
check that the package executes as expected. The defined tests in
./tests contain many regression tests (done with
pytest-regressions) that make it almost impossible
to add features to fractopo that changes the results of functions
and methods.

# To run tests implemented in ./tests directory and as doctests
# within project itself:
poetry run pytest

coverage
sphinx

Creates documentation from files in ./docs_src.

Big thanks to all maintainers of the above packages!

License
Copyright © 2020-2023, Nikolas Ovaskainen.