fractopo¶
fractopo
is a Python module that contains tools for validating and
analysing lineament and fracture trace maps (fracture networks).
Full documentation¶
Documentation is hosted on Read the Docs:
Installation¶
Currently installation is supported only for linux
-based operating
systems and MacOS
. There’s a known problem with installing any
gdal
-based Python package onto a Windows machine. (Could be
circumvented at some point by using conda
.)
Omit --dev
or [dev]
for regular installation. Keep if you want
to test/develop or otherwise install all development python
dependencies.
Pip¶
The module is on PyPI.
# Non-development installation
pip install fractopo
Or locally for development:
git clone https://github.com/nialov/fractopo
cd fractopo
# Omit [dev] from end if you do not want installation for development
pip install --editable .[dev]
poetry¶
For usage:
poetry add fractopo
For development:
git clone https://github.com/nialov/fractopo --depth 1
cd fractopo
poetry install
Usage¶
See Full documentation for usage guidance and examples.
Input data¶
Reading and writing spatial filetypes is done in geopandas
and you
should see geopandas
documentation for more advanced read-write use
cases:
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 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 as a command-line script,
tracevalidate
which is more straightforward to use than through
Python calls.
tracevalidate
always requires the target area that delineates trace
data.
# Get full up-to-date script help
tracevalidate --help
# Basic usage:
# --fix is recommended due to automatic fixing being very minor in effect
# currently
# --output can be omitted. By default the same spatial filetype
# as the input is used and the output is saved as e.g.
# /path/to/validated/trace_data_validated.shp
# i.e. a new folder is created (or used) for validated data
# --summary can be given to print out summary data of validation
# i.e. error types and error counts
tracevalidate /path/to/trace_data.shp /path/to/target_area.shp --fix --output /path/to/output_data.shp
# Or with automatic saving to validated/ directory
tracevalidate /path/to/trace_data.shp /path/to/target_area.shp --fix --summary
Geometric and topological trace network analysis¶
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
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()
Development status¶
Breaking changes are possible and expected.
Critical issues:
Installation on Windows is currently not supported due to problems with installation of gdal-based packages like geopandas.
Trace validation should be refactored at some point.
Though keeping in mind that the current implementation works well.
snap_traces
in branch and node determination is not perfect. Some edge cases cause artifacts which only sometimes are recognized as error branches. However these cases are very rare.Reinforces that some amount of responsibility is always in the hands of the digitizer.
Issue mostly avoided when using a
snap_threshold
of 0.001
Contents¶
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. Therefore the
trace validation is recommended before all analysis using Network
.
See above links for:
Basic trace data validation workflows
Examples of validation error types
For trace validation also see above guide on tracevalidate
command-line
tool. After trace data validation, Network
analysis can be conducted.
See above links for:
Workflow of analyzing trace data with visualizations of geometric topological network characteristics.
Example scripts showcasing different analysis and plotting functionality implemented in fractopo.
Notebook - Fractopo – KB11 Fracture Network Analysis is especially recommended.