Metadata-Version: 2.4
Name: fractopo
Version: 0.9.2
Summary: Fracture Network Analysis
License-Expression: MIT
License-File: LICENSE.md
Keywords: data,gis,geology,fracture,topology
Author: nialov
Author-email: nikolasovaskainen@gmail.com
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Provides-Extra: api
Provides-Extra: dev
Requires-Dist: beartype (>=0.19.0)
Requires-Dist: click
Requires-Dist: codespell (>=2.2.2) ; extra == "dev"
Requires-Dist: cogapp (>=3.3.0) ; extra == "dev"
Requires-Dist: coverage (>=6.5.0) ; extra == "dev"
Requires-Dist: fastapi ; extra == "api"
Requires-Dist: geopandas (>=1.0.0)
Requires-Dist: hypothesis ; extra == "dev"
Requires-Dist: ipython ; extra == "dev"
Requires-Dist: ipython ; extra == "dev"
Requires-Dist: joblib (>=1.2.0)
Requires-Dist: json5 ; extra == "dev"
Requires-Dist: jupyterlab ; extra == "dev"
Requires-Dist: marimo ; extra == "api"
Requires-Dist: marimo ; extra == "dev"
Requires-Dist: matplotlib (>=3.5.3)
Requires-Dist: nbsphinx ; extra == "dev"
Requires-Dist: nbstripout (>=0.6.1) ; extra == "dev"
Requires-Dist: numpy (>=1.26.0,<3.0.0)
Requires-Dist: pandas (>=2.1.0,<3.0.0)
Requires-Dist: powerlaw (>=1.4.6,<2.0.0)
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pyinstrument ; extra == "dev"
Requires-Dist: pyproj (>=3.6.0)
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pytest-regressions (>=2.2.0,<3.0.0) ; extra == "dev"
Requires-Dist: python-ternary
Requires-Dist: rich (>=11.0.0)
Requires-Dist: scikit-learn
Requires-Dist: scipy (>=1.9.1)
Requires-Dist: seaborn
Requires-Dist: shapely (>=2.0.0,<3.0.0)
Requires-Dist: sphinx (>=7.0.0,<8.0.0) ; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints (>2.0.0) ; extra == "dev"
Requires-Dist: sphinx-design ; extra == "dev"
Requires-Dist: sphinx-gallery ; extra == "dev"
Requires-Dist: sphinx-rtd-theme (>2.0) ; extra == "dev"
Requires-Dist: sphinx-sitemap ; extra == "dev"
Requires-Dist: toml ; extra == "dev"
Requires-Dist: typer (>=0.4)
Project-URL: Documentation, https://nialov.github.io/fractopo/
Project-URL: Homepage, https://github.com/nialov/fractopo
Project-URL: Repository, https://github.com/nialov/fractopo
Description-Content-Type: text/x-rst

fractopo
========

|PyPI Status| |CI Test| |Conda Test| |Binder| |Zenodo| |JOSS| |Conda Version|

-  `Full Documentation is hosted on GitHub
   <https://nialov.github.io/fractopo/index.html#full-documentation>`__

``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.

.. figure:: https://git.io/JBRuK
   :alt: Overview of fractopo

   Overview of fractopo

.. figure:: /docs_src/imgs/fractopo-visualizations.png
   :alt: Data visualization

   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``.

.. contents:: **Quick navigation**
   :depth: 2
   :local:

Installation
------------

``pip`` and ``poetry`` installation only supported for ``linux`` -based
operating systems. For Windows and MacOS install using
`(ana)conda <#conda>`__. A container exists for exposing a simplified
web interface, created with `marimo <https://github.com/marimo-team/marimo>`__.

conda
~~~~~

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

.. code:: bash

   # 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 <https://www.pypi.org>`__.

.. code:: bash

   pip install fractopo

poetry
~~~~~~

For usage:

.. code:: bash

   poetry add fractopo

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

.. code:: bash

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

container (web interface)
~~~~~~~~~~~~~~~~~~~~~~~~~

A `marimo <https://github.com/marimo-team/marimo>`__ +
`FastAPI <https://github.com/fastapi/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:

.. code:: bash

   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`_
========================================================  ======================

.. _Validation 1:
   https://nialov.github.io/fractopo/notebooks/fractopo_validation_1.html
.. _Validation 2:
   https://nialov.github.io/fractopo/notebooks/fractopo_validation_2.html
.. _Visualizing:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Visualizing-trace-map-data
.. _Network:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Network
.. _Topological:
   https://nialov.github.io/fractopo/auto_examples/plot_branches_and_nodes.html#sphx-glr-auto-examples-plot-branches-and-nodes-py
.. _Length-distributions:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Length-distributions
.. _Orientation 1:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Rose-plots
.. _Orientation 2:
   https://nialov.github.io/fractopo/auto_examples/plot_rose_plot.html#sphx-glr-auto-examples-plot-rose-plot-py
.. _Proportions:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Node-and-branch-proportions
.. _Relationships 1:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Crosscutting-and-abutting-relationships
.. _Relationships 2:
   https://nialov.github.io/fractopo/auto_examples/plot_azimuth_set_relationships.html#sphx-glr-auto-examples-plot-azimuth-set-relationships-py
.. _Parameters:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Numerical-Fracture-Network-Characterization-Parameters
.. _Contour-grids:
   https://nialov.github.io/fractopo/notebooks/fractopo_network_1.html#Contour-Grids
.. _Multi-scale:
   https://nialov.github.io/fractopo/auto_examples/plot_multi_scale_networks.html#sphx-glr-auto-examples-plot-multi-scale-networks-py

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``:

.. code:: python

   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 <https://nialov.github.io/fractopo/validation/errors.html>`__
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:

.. code:: python

   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.

.. code:: bash

   # 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.

.. code:: python

   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:

.. code:: bash

   # 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


.. figure:: /docs_src/imgs/fractopo_workflow_visualisation.jpg
   :alt: Data analysis workflow visualisation for fracture trace data.

   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:

.. code:: text

   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 <https://doi.org/10.1016/j.jsg.2015.01.005>`__

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

-  `Ovaskainen et al, 2022 <https://doi.org/10.1016/j.jsg.2022.104528>`__

   -  Application of ``fractopo`` for subsampling analysis of fracture networks.

-  `Ovaskainen et al, 2023 <https://doi.org/10.5194/se-14-603-2023>`__

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

-  `Nyberg et al., 2018 <https://doi.org/10.1130/GES01595.1>`__

   -  A similar package to ``fractopo`` with a ``QGIS`` GUI.
   -  `NetworkGT GitHub <https://github.com/BjornNyberg/NetworkGT>`__

-  `Sanderson and Peacock,
   2020 <https://www.sciencedirect.com/science/article/abs/pii/S001282521930594X>`__

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

-  `Alstott et al.
   2014 <https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0085777>`__

   -  Length distribution modelling using the Python 3 ``powerlaw``
      package which ``fractopo`` uses
   -  `powerlaw GitHub <https://github.com/jeffalstott/powerlaw>`__

-  `Bonnet et al.,
   2001 <https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/1999RG000074>`__

   -  Length distribution modelling review.

-  `My Master’s Thesis, Ovaskainen,
   2020 <http://urn.fi/URN:NBN:fi-fe202003259211>`__

   -  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 </CONTRIBUTING.rst>`__

-----

.. |PyPI Status| image:: https://img.shields.io/pypi/v/fractopo.svg
   :target: https://pypi.python.org/pypi/fractopo
.. |Conda Version| image:: https://img.shields.io/conda/vn/conda-forge/fractopo.svg
   :target: https://anaconda.org/conda-forge/fractopo
.. .. |Documentation Status| image:: https://github.com/nialov/fractopo/actions/workflows/main.yaml/badge.svg
..    :target: https://nialov.github.io/fractopo/
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.05300/status.svg
   :target: https://doi.org/10.21105/joss.05300
.. |CI Test| image:: https://github.com/nialov/fractopo/actions/workflows/main.yaml/badge.svg
   :target: https://github.com/nialov/fractopo/actions/workflows/main.yaml?query=branch%3Amaster
.. |Conda Test| image:: https://github.com/nialov/fractopo/actions/workflows/conda.yaml/badge.svg
   :target: https://github.com/nialov/fractopo/actions/workflows/conda.yaml?query=branch%3Amaster
.. |Binder| image:: http://mybinder.org/badge_logo.svg
   :target: https://mybinder.org/v2/gh/nialov/fractopo/HEAD?filepath=docs_src%2Fnotebooks%2Ffractopo_network_1.ipynb
.. |Zenodo| image:: https://zenodo.org/badge/297451015.svg
   :target: https://zenodo.org/badge/latestdoi/297451015

