Metadata-Version: 2.1
Name: fractopo
Version: 0.0.5
Summary: Brittle Geology Analysis Toolkit
Home-page: https://github.com/nialov/fractopo
Author: Nikolas Ovaskainen
Author-email: nikolasovaskainen@gmail.com
License: UNKNOWN
Project-URL: Bug Reports, https://github.com/nialov/fractopo/issues
Project-URL: Source, https://github.com/nialov/fractopo/
Description: fractopo
        ========
        
        |Documentation Status| |PyPI Status| |CI Test| |Lint| |Coverage|
        |Binder|
        
        ``fractopo`` is a Python module that contains tools for validating and
        analysing lineament and fracture trace maps (fracture networks).
        
        .. figure:: https://raw.githubusercontent.com/nialov/fractopo/master/docs_src/imgs/fractopo_2d_diagram.png
           :alt: Overview of fractopo
        
           Overview of fractopo
        
        Development status
        ------------------
        
        -  In constant development, will have breaking changes.
        -  Critical issues:
        
           -  Installation on Windows is currently not supported due to problems
              with installation of ``gdal``-based packages like geopandas.
           -  Contour grid sampling is sometimes slow and requires refactor at
              some point.
           -  ``snap_traces`` in branch and node determination is not completely
              stable. Some edge cases cause artifacts which only sometimes are
              recognized as error branches. (Mostly solved as of 1.3.2021).
        
              -  Reinforces that some amount of responsibility is always in the
                 hands of the digitizer.
              -  Issue mostly avoided with a ``snap_threshold`` of 0.001
        
        Full documentation
        ------------------
        
        -  Documentation hosted on Read the Docs:
        
           -  `Documentation <https://fractopo.readthedocs.io/en/latest/index.html>`__
        
        Installation
        ------------
        
        Currently installation is supported only for linux-based operating
        systems. 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.
        
        .. code:: bash
        
           # Non-development installation
           pip install fractopo
        
        Or locally for development:
        
        .. code:: bash
        
           git clone https://github.com/nialov/fractopo --depth 1
           cd fractopo
           # Omit [dev] from end if you do not want installation for development
           pip install --editable .[dev]
        
        Pipenv
        ~~~~~~
        
        .. code:: bash
        
           git clone https://github.com/nialov/fractopo --depth 1
           cd fractopo
           # Omit --dev from end if you do not want installation for development
           pipenv sync --dev
        
        Usage
        -----
        
        See `Notebooks with examples <https://tinyurl.com/yb4tj47e>`__ for more
        advanced 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:
        
        -  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 and target area data can be validated for further analysis with a
        ``Validation`` object.
        
        .. code:: python
        
           from fractopo.tval.trace_validation 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.
        
        .. code:: bash
        
           # 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 (``GeoDataFrame``\ s) 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.analysis.network import Network
           network = Network(
               trace_data, area_data, name="mynetwork", determine_branches_nodes=True,
           )
        
           # Properties are easily accessible
           # e.g.
           network.branch_counts
           network.node_counts
        
           # Plotting is done by plot_ -prefixed methods
           network.plot_trace_lengths()
        
        .. |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/test-and-publish/badge.svg
           :target: https://github.com/nialov/fractopo/actions/workflows/test-and-publish.yaml?query=branch%3Amaster
        .. |Lint| image:: https://github.com/nialov/fractopo/workflows/lint/badge.svg
           :target: https://github.com/nialov/fractopo/actions/workflows/lint.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/ec3f44fcc5d51dcbda442cb2e322fd09a3629261?filepath=docs_src%2Fnotebooks%2Ffractopo_network_1.ipynb
        
Keywords: sample setuptools development
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: coverage
