fractopo
========
|Documentation Status| |PyPI Status| |CI Test| |Conda Test| |Coverage| |Binder| |Zenodo|
``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 Read the Docs
<https://fractopo.readthedocs.io/en/latest/index.html#full-documentation>`__
.. 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``.
Installation
------------
``pip`` and ``poetry`` installation only supported for ``linux`` -based
operating systems. For Windows and MacOS install using `(ana)conda <#conda>`__.
conda
~~~~~
- Only (supported) installation method for ``Windows`` and ``MacOS``!
.. code:: bash
# 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 <https://www.pypi.org>`__.
.. code:: bash
# Non-development installation
pip install fractopo
poetry
~~~~~~
For usage:
.. code:: bash
poetry add fractopo
For development, only ``poetry`` installation of ``fractopo`` is
supported:
.. code:: bash
git clone https://github.com/nialov/fractopo
cd fractopo
poetry install
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 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`_
======================================================== ======================
.. _Validation 1:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_validation_1.html
.. _Validation 2:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_validation_2.html
.. _Visualizing:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Visualizing-trace-map-data
.. _Network:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Network
.. _Topological:
https://fractopo.readthedocs.io/en/latest/auto_examples/plot_branches_and_nodes.html#sphx-glr-auto-examples-plot-branches-and-nodes-py
.. _Length-distributions:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Length-distributions
.. _Orientation 1:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Rose-plots
.. _Orientation 2:
https://fractopo.readthedocs.io/en/latest/auto_examples/plot_rose_plot.html#sphx-glr-auto-examples-plot-rose-plot-py
.. _Proportions:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Node-and-branch-proportions
.. _Relationships 1:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Crosscutting-and-abutting-relationships
.. _Relationships 2:
https://fractopo.readthedocs.io/en/latest/auto_examples/plot_azimuth_set_relationships.html#sphx-glr-auto-examples-plot-azimuth-set-relationships-py
.. _Parameters:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Numerical-Fracture-Network-Characterization-Parameters
.. _Contour-grids:
https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Contour-Grids
.. _Multi-scale:
https://fractopo.readthedocs.io/en/latest/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 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://fractopo.readthedocs.io/en/latest/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 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. ``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
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
.. 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.
Citing
------
To cite this software:
- The software is introduced in https://doi.org/10.1016/j.jsg.2022.104528 and
you can cite that article as a general citation:
.. code:: text
Ovaskainen, N., Nordbäck, N., Skyttä, P. and Engström, J., 2022. A new
subsampling methodology to optimize the characterization of
two-dimensional bedrock fracture networks. Journal of Structural Geology,
p.104528.
- 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.
- `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>`__
Development dependencies for ``fractopo`` include:
- ``poetry``
- Used to handle Python package dependencies.
.. code:: bash
# Use poetry run to execute poetry installed cli tools such as invoke,
# nox and pytest.
poetry run '<cmd>'
- ``doit``
- A general task executor that is a replacement for a ``Makefile``
- Understands task dependencies and can run tasks in parallel
even while running them in the order determined from dependencies
between tasks. E.g., requirements.txt is a requirement for running
tests and therefore the task creating requirements.txt will always
run before the test task.
.. code:: bash
# Tasks are defined in dodo.py
# To list doit tasks from command line
poetry run doit list
# To run all tasks in parallel (recommended before pushing and/or
# committing)
# 8 is the number of cpu cores, change as wanted
# -v 0 sets verbosity to very low. (Errors will always still be printed.)
poetry run doit -n 8 -v 0
- ``nox``
- ``nox`` is a replacement for ``tox``. Both are made to create
reproducible Python environments for testing, making docs locally, etc.
.. code:: bash
# To list available nox sessions
# Sessions are defined in noxfile.py
poetry run nox --list
- ``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.
.. code:: bash
# To pull copier update from github/nialov/nialov-py-template
poetry run copier update
- ``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.
.. code:: bash
# To run tests implemented in ./tests directory and as doctests
# within project itself:
poetry run pytest
- ``coverage``
.. code:: bash
# To check coverage of tests
# (Implemented as nox session!)
poetry run nox --session test_pip
- ``sphinx``
- Creates documentation from files in ``./docs_src``.
.. code:: bash
# To create documentation
# (Implemented as nox session!)
poetry run nox --session docs
Big thanks to all maintainers of the above packages!
License
~~~~~~~
Copyright © 2020-2023, Nikolas Ovaskainen.
-----
.. |Documentation Status| image:: https://readthedocs.org/projects/fractopo/badge/?version=latest
:target: https://fractopo.readthedocs.io/en/latest/?badge=latest
.. |PyPI Status| image:: https://img.shields.io/pypi/v/fractopo.svg
:target: https://pypi.python.org/pypi/fractopo
.. |CI Test| image:: https://github.com/nialov/fractopo/workflows/CI/badge.svg
:target: https://github.com/nialov/fractopo/actions/workflows/main.yaml?query=branch%3Amaster
.. |Conda Test| image:: https://github.com/nialov/fractopo/workflows/conda/badge.svg
:target: https://github.com/nialov/fractopo/actions/workflows/conda.yaml?query=branch%3Amaster
.. |Coverage| image:: https://raw.githubusercontent.com/nialov/fractopo/master/docs_src/imgs/coverage.svg
:target: https://github.com/nialov/fractopo/blob/master/docs_src/imgs/coverage.svg
.. |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
Raw data
{
"_id": null,
"home_page": "https://github.com/nialov/fractopo",
"name": "fractopo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "data,gis,geology,fracture,topology",
"author": "nialov",
"author_email": "nikolasovaskainen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/61/d7/20c647049c6ea9672ec969a28dd9bc55ad918de9ea916886239943e1d77b/fractopo-0.5.3.tar.gz",
"platform": null,
"description": "fractopo\n========\n\n|Documentation Status| |PyPI Status| |CI Test| |Conda Test| |Coverage| |Binder| |Zenodo|\n\n``fractopo`` is a Python library/application that contains tools for\nvalidating and analysing lineament and fracture trace maps (fracture\nnetworks). It is targeted at structural geologists working on the\ncharacterization of bedrock fractures from outcrops and through remote\nsensing. ``fractopo`` is available as a Python library and through a\ncommand-line interface. As a Python library, the use of ``fractopo``\nrequires prior (Python) programming knowledge. However, if used through\nthe command-line, using ``fractopo`` only requires general knowledge of\ncommand-line interfaces in your operating system of choice.\n\n- `Full Documentation is hosted on Read the Docs\n <https://fractopo.readthedocs.io/en/latest/index.html#full-documentation>`__\n\n.. figure:: https://git.io/JBRuK\n :alt: Overview of fractopo\n\n Overview of fractopo\n\n.. figure:: /docs_src/imgs/fractopo-visualizations.png\n :alt: Data visualization\n\n Visualisation of ``fractopo`` data. ``fractopo`` analyses the trace\n data that can e.g. be digitized from drone orthophotographs\n (=fractures) or from digital elevation models (=lineaments). The\n displayed branches and nodes are extracted with ``fractopo``.\n\nInstallation\n------------\n\n``pip`` and ``poetry`` installation only supported for ``linux`` -based\noperating systems. For Windows and MacOS install using `(ana)conda <#conda>`__.\n\nconda\n~~~~~\n\n- Only (supported) installation method for ``Windows`` and ``MacOS``!\n\n.. code:: bash\n\n # Create new environment for fractopo (recommended but optional)\n conda env create fractopo-env\n conda activate fractopo-env\n # Available on conda-forge channel\n conda install -c conda-forge fractopo\n\npip\n~~~\n\nThe module is on `PyPI <https://www.pypi.org>`__.\n\n.. code:: bash\n\n # Non-development installation\n pip install fractopo\n\npoetry\n~~~~~~\n\nFor usage:\n\n.. code:: bash\n\n poetry add fractopo\n\nFor development, only ``poetry`` installation of ``fractopo`` is\nsupported:\n\n.. code:: bash\n\n git clone https://github.com/nialov/fractopo\n cd fractopo\n poetry install\n\nUsage\n-----\n\n``fractopo`` has two main use cases:\n\n1. Validation of lineament & fracture trace data\n2. Analysis of lineament & fracture trace data\n\nValidation is done to make sure the data is valid for the analysis and\nis crucial as analysis cannot take into account different kinds of\ngeometric and topological inconsistencies between the traces.\nCapabilities and associated guides are inexhaustively listed in the\ntable below.\n\n======================================================== ======================\nFunctionality Tutorial/Guide/Example\n======================================================== ======================\nValidation of trace data `Validation 1`_; `Validation 2`_\nVisualize trace map data `Visualizing`_\nTopological branches and nodes `Network`_; `Topological`_\nTrace and branch length distributions `Length-distributions`_\nOrientation rose plots `Orientation 1`_; `Orientation 2`_\nPlot topological ternary node and branch proportions `Proportions`_\nCross-cutting and abutting relationships `Relationships 1`_; `Relationships 2`_;\nGeometric and topological fracture network parameters `Parameters`_\nContour grids of fracture network parameters `Contour-grids`_\nMulti-scale length distributions `Multi-scale`_\n======================================================== ======================\n\n.. _Validation 1:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_validation_1.html\n.. _Validation 2:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_validation_2.html\n.. _Visualizing:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Visualizing-trace-map-data\n.. _Network:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Network\n.. _Topological:\n https://fractopo.readthedocs.io/en/latest/auto_examples/plot_branches_and_nodes.html#sphx-glr-auto-examples-plot-branches-and-nodes-py\n.. _Length-distributions:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Length-distributions\n.. _Orientation 1:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Rose-plots\n.. _Orientation 2:\n https://fractopo.readthedocs.io/en/latest/auto_examples/plot_rose_plot.html#sphx-glr-auto-examples-plot-rose-plot-py\n.. _Proportions:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Node-and-branch-proportions\n.. _Relationships 1:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Crosscutting-and-abutting-relationships\n.. _Relationships 2:\n https://fractopo.readthedocs.io/en/latest/auto_examples/plot_azimuth_set_relationships.html#sphx-glr-auto-examples-plot-azimuth-set-relationships-py\n.. _Parameters:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Numerical-Fracture-Network-Characterization-Parameters\n.. _Contour-grids:\n https://fractopo.readthedocs.io/en/latest/notebooks/fractopo_network_1.html#Contour-Grids\n.. _Multi-scale:\n https://fractopo.readthedocs.io/en/latest/auto_examples/plot_multi_scale_networks.html#sphx-glr-auto-examples-plot-multi-scale-networks-py\n\nFor a short tutorial on use of ``fractopo`` continue reading:\n\nInput data\n~~~~~~~~~~\n\nReading and writing spatial filetypes is done in ``geopandas`` and you\nshould see ``geopandas`` documentation for more advanced read-write use\ncases:\n\n- https://geopandas.org/\n\nSimple example with trace and area data in GeoPackages:\n\n.. code:: python\n\n import geopandas as gpd\n\n # Trace data is in a file `traces.gpkg` in current working directory\n # Area data is in a file `areas.gpkg` in current working directory\n trace_data = gpd.read_file(\"traces.gpkg\")\n area_data = gpd.read_file(\"areas.gpkg\")\n\nTrace validation\n~~~~~~~~~~~~~~~~\n\nTrace data must be validated using ``fractopo`` validation functionality\nbefore analysis. The topological analysis of lineament & fracture traces\nimplemented in ``fractopo`` will not tolerate uncertainty related to the\ntopological abutting and snapping relationships between traces. See `the\ndocumentation <https://fractopo.readthedocs.io/en/latest/validation/errors.html>`__\nfor further info on validation error types. Trace validation is\nrecommended before all analysis using ``Network``. Trace and target area\ndata can be validated for further analysis with a ``Validation`` object:\n\n.. code:: python\n\n from fractopo import Validation\n\n validation = Validation(\n trace_data,\n area_data,\n name=\"mytraces\",\n allow_fix=True,\n )\n\n # Validation is done explicitly with `run_validation` method\n validated_trace_data = validation.run_validation()\n\nTrace validation is also accessible through the ``fractopo``\ncommand-line interface, ``fractopo tracevalidate`` which is more\nstraightforward to use than through Python calls. Note that all\nsubcommands of ``fractopo`` are available by appending them after\n``fractopo``.\n\n``tracevalidate`` always requires the target area that delineates trace\ndata.\n\n.. code:: bash\n\n # Get full up-to-date command-line interface help\n fractopo tracevalidate --help\n\n # Basic usage example:\n fractopo tracevalidate /path/to/trace_data.shp /path/to/target_area.shp\\\n --output /path/to/validated_trace_data.shp\n\n # Or with automatic saving to validated/ directory\n fractopo tracevalidate /path/to/trace_data.shp /path/to/target_area.shp\\\n --summary\n\nGeometric and topological trace network analysis\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``fractopo`` can be used to extract lineament & fracture size,\nabundance and topological parameters from two-dimensional lineament and\nfracture trace, branch and node data.\n\nTrace and target area data (``GeoDataFrames``) are passed into a\n``Network`` object which has properties and functions for returning and\nvisualizing different parameters and attributes of trace data.\n\n.. code:: python\n\n from fractopo import Network\n\n # Initialize Network object and determine the topological branches and nodes\n network = Network(\n trace_data,\n area_data,\n # Give the Network a name!\n name=\"mynetwork\",\n # Specify whether to determine topological branches and nodes\n # (Required for almost all analysis)\n determine_branches_nodes=True,\n # Specify the snapping distance threshold to define when traces are\n # snapped to each other. The unit is the same as the one in the\n # coordinate system the trace and area data are in.\n # In default values, fractopo assumes a metric unit and using metric units\n # is heavily recommended.\n snap_threshold=0.001,\n # If the target area used in digitization is a circle, the knowledge can\n # be used in some analysis\n circular_target_area=True,\n # Analysis on traces can be done for the full inputted dataset or the\n # traces can be cropped to the target area before analysis (cropping\n # recommended)\n truncate_traces=True,\n )\n\n # Properties are easily accessible\n # e.g.,\n network.branch_counts\n network.node_counts\n\n # Plotting is done by plot_ -prefixed methods\n network.plot_trace_lengths()\n\nNetwork analysis is also available through the ``fractopo`` command-line\ninterface but using the Python interface (e.g. ``jupyter lab``,\n``ipython``) is recommended when analysing ``Networks`` to have access\nto all available analysis and plotting methods. The command-line\nentrypoint is **opinionated** in what outputs it produces. Brief example\nof command-line entrypoint:\n\n.. code:: bash\n\n fractopo network /path/to/trace_data.shp /path/to/area_data.shp\\\n --name mynetwork\n\n # Use --help to see all up-to-date arguments and help\n fractopo network --help\n\n.. figure:: /docs_src/imgs/fractopo_workflow_visualisation.jpg\n :alt: Data analysis workflow visualisation for fracture trace data.\n\n Data analysis workflow visualisation for fracture trace data\n (``KB11``). A. Target area for trace digitisation. B. Digitized\n traces and target area. C. Orthomosaic used as the base raster from\n which the traces are digitized from. D. Equal-area length-weighted\n rose plot of the fracture trace azimuths. E. Length distribution\n analysis of the trace lengths. F. Determined branches and nodes\n through topological analysis. G. Cross-cut and abutting relationships\n between chosen azimuth sets. H. Ternary plot of node (X, Y and I)\n proportions. I. Ternary plot of branch (C-C, C-I, I-I) proportions.\n\n\nCiting\n------\n\nTo cite this software:\n\n- The software is introduced in https://doi.org/10.1016/j.jsg.2022.104528 and\n you can cite that article as a general citation:\n\n.. code:: text\n\n Ovaskainen, N., Nordb\u00e4ck, N., Skytt\u00e4, P. and Engstr\u00f6m, J., 2022. A new\n subsampling methodology to optimize the characterization of\n two-dimensional bedrock fracture networks. Journal of Structural Geology,\n p.104528.\n\n- To cite a specific version of ``fractopo`` you can use a ``zenodo``\n provided ``DOI``. E.g. https://doi.org/10.5281/zenodo.5957206 for version\n ``v0.2.6``. See the ``zenodo`` page of ``fractopo`` for the ``DOI`` of each\n version: https://doi.org/10.5281/zenodo.5517485\n\nSupport\n-------\n\nFor issues of any kind: please create a GitHub issue here!\nAlternatively, you can contact the main developer by email at\nnikolasovaskainen@gmail.com.\n\nReferences\n----------\n\nFor the scientific background, prior works, definition of traces, branches and\nnodes along with the explanation of the plots and the plotted parameters, you\nare referred to multiple sources:\n\n- `Sanderson and Nixon,\n 2015 <https://doi.org/10.1016/j.jsg.2015.01.005>`__\n\n - Trace and branch size, abundance and topological parameter\n definitions.\n\n- `Ovaskainen et al, 2022 <https://doi.org/10.1016/j.jsg.2022.104528>`__\n\n - Application of ``fractopo`` for subsampling analysis of fracture networks.\n\n- `Nyberg et al., 2018 <https://doi.org/10.1130/GES01595.1>`__\n\n - A similar package to ``fractopo`` with a ``QGIS`` GUI.\n - `NetworkGT GitHub <https://github.com/BjornNyberg/NetworkGT>`__\n\n- `Sanderson and Peacock,\n 2020 <https://www.sciencedirect.com/science/article/abs/pii/S001282521930594X>`__\n\n - Discussion around rose plots and justification for using\n length-weighted equal-area rose plots.\n\n- `Alstott et al.\n 2014 <https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0085777>`__\n\n - Length distribution modelling using the Python 3 ``powerlaw``\n package which ``fractopo`` uses\n - `powerlaw GitHub <https://github.com/jeffalstott/powerlaw>`__\n\n- `Bonnet et al.,\n 2001 <https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/1999RG000074>`__\n\n - Length distribution modelling review.\n\n- `My Master\u2019s Thesis, Ovaskainen,\n 2020 <http://urn.fi/URN:NBN:fi-fe202003259211>`__\n\n - Plots used in my Thesis were done with an older version of the\n same code used for this plugin.\n\nDevelopment\n-----------\n\n- The package interfaces are nearing stability and breaking changes in\n code should for the most part be included in the ``CHANGELOG.md``\n after 25.4.2023. However, this is not guaranteed until the version\n reaches v1.0.0. The interfaces of ``Network`` and ``Validation`` can\n be expected to be the most stable.\n\n- For general contributing guidelines, see `CONTRIBUTING.rst </CONTRIBUTING.rst>`__\n\nDevelopment dependencies for ``fractopo`` include:\n\n- ``poetry``\n\n - Used to handle Python package dependencies.\n\n .. code:: bash\n\n # Use poetry run to execute poetry installed cli tools such as invoke,\n # nox and pytest.\n poetry run '<cmd>'\n\n\n- ``doit``\n\n - A general task executor that is a replacement for a ``Makefile``\n - Understands task dependencies and can run tasks in parallel\n even while running them in the order determined from dependencies\n between tasks. E.g., requirements.txt is a requirement for running\n tests and therefore the task creating requirements.txt will always\n run before the test task.\n\n .. code:: bash\n\n # Tasks are defined in dodo.py\n # To list doit tasks from command line\n poetry run doit list\n # To run all tasks in parallel (recommended before pushing and/or\n # committing)\n # 8 is the number of cpu cores, change as wanted\n # -v 0 sets verbosity to very low. (Errors will always still be printed.)\n poetry run doit -n 8 -v 0\n\n- ``nox``\n\n - ``nox`` is a replacement for ``tox``. Both are made to create\n reproducible Python environments for testing, making docs locally, etc.\n\n .. code:: bash\n\n # To list available nox sessions\n # Sessions are defined in noxfile.py\n poetry run nox --list\n\n- ``copier``\n\n - ``copier`` is a project templater. Many Python projects follow a similar\n framework for testing, creating documentations and overall placement of\n files and configuration. ``copier`` allows creating a template project\n (e.g., https://github.com/nialov/nialov-py-template) which can be firstly\n cloned as the framework for your own package and secondly to pull updates\n from the template to your already started project.\n\n .. code:: bash\n\n # To pull copier update from github/nialov/nialov-py-template\n poetry run copier update\n\n\n- ``pytest``\n\n - ``pytest`` is a Python test runner. It is used to run defined tests to\n check that the package executes as expected. The defined tests in\n ``./tests`` contain many regression tests (done with\n ``pytest-regressions``) that make it almost impossible\n to add features to ``fractopo`` that changes the results of functions\n and methods.\n\n .. code:: bash\n\n # To run tests implemented in ./tests directory and as doctests\n # within project itself:\n poetry run pytest\n\n\n- ``coverage``\n\n .. code:: bash\n\n # To check coverage of tests\n # (Implemented as nox session!)\n poetry run nox --session test_pip\n\n- ``sphinx``\n\n - Creates documentation from files in ``./docs_src``.\n\n .. code:: bash\n\n # To create documentation\n # (Implemented as nox session!)\n poetry run nox --session docs\n\nBig thanks to all maintainers of the above packages!\n\nLicense\n~~~~~~~\n\nCopyright \u00a9 2020-2023, Nikolas Ovaskainen.\n\n-----\n\n\n.. |Documentation Status| image:: https://readthedocs.org/projects/fractopo/badge/?version=latest\n :target: https://fractopo.readthedocs.io/en/latest/?badge=latest\n.. |PyPI Status| image:: https://img.shields.io/pypi/v/fractopo.svg\n :target: https://pypi.python.org/pypi/fractopo\n.. |CI Test| image:: https://github.com/nialov/fractopo/workflows/CI/badge.svg\n :target: https://github.com/nialov/fractopo/actions/workflows/main.yaml?query=branch%3Amaster\n.. |Conda Test| image:: https://github.com/nialov/fractopo/workflows/conda/badge.svg\n :target: https://github.com/nialov/fractopo/actions/workflows/conda.yaml?query=branch%3Amaster\n.. |Coverage| image:: https://raw.githubusercontent.com/nialov/fractopo/master/docs_src/imgs/coverage.svg\n :target: https://github.com/nialov/fractopo/blob/master/docs_src/imgs/coverage.svg\n.. |Binder| image:: http://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/nialov/fractopo/HEAD?filepath=docs_src%2Fnotebooks%2Ffractopo_network_1.ipynb\n.. |Zenodo| image:: https://zenodo.org/badge/297451015.svg\n :target: https://zenodo.org/badge/latestdoi/297451015\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fracture Network Analysis",
"version": "0.5.3",
"project_urls": {
"Bug Tracker": "https://github.com/nialov/fractopo/issues",
"Documentation": "https://fractopo.readthedocs.io/en/latest/",
"Homepage": "https://github.com/nialov/fractopo",
"Repository": "https://github.com/nialov/fractopo"
},
"split_keywords": [
"data",
"gis",
"geology",
"fracture",
"topology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c79a4f58668654cc2511f8c5f3d27de7dae52c896fe8f8ba0379e3f6d5f50c3c",
"md5": "0a1a3906255ed5aecebc74cdbda6f057",
"sha256": "18dbcb4fed36b9bfd284129841b775fadff2c83393cc3247223695a28cc7a693"
},
"downloads": -1,
"filename": "fractopo-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a1a3906255ed5aecebc74cdbda6f057",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 114891,
"upload_time": "2023-05-09T15:13:09",
"upload_time_iso_8601": "2023-05-09T15:13:09.806340Z",
"url": "https://files.pythonhosted.org/packages/c7/9a/4f58668654cc2511f8c5f3d27de7dae52c896fe8f8ba0379e3f6d5f50c3c/fractopo-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61d720c647049c6ea9672ec969a28dd9bc55ad918de9ea916886239943e1d77b",
"md5": "9a253d2aef74ac47b58d6feb7e69b747",
"sha256": "4eea868d7e82863c1e0dcc1a0b928c92f9c04fe670e21131f04871843d4e74cf"
},
"downloads": -1,
"filename": "fractopo-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "9a253d2aef74ac47b58d6feb7e69b747",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 111869,
"upload_time": "2023-05-09T15:13:12",
"upload_time_iso_8601": "2023-05-09T15:13:12.183472Z",
"url": "https://files.pythonhosted.org/packages/61/d7/20c647049c6ea9672ec969a28dd9bc55ad918de9ea916886239943e1d77b/fractopo-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-09 15:13:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nialov",
"github_project": "fractopo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fractopo"
}
JSON
