diff --git a/docs/peak_finder_app/Makefile b/docs/peak_finder_app/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/peak_finder_app/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/peak_finder_app/environnment.yml b/docs/peak_finder_app/environnment.yml new file mode 100644 index 00000000..6358ac26 --- /dev/null +++ b/docs/peak_finder_app/environnment.yml @@ -0,0 +1,18 @@ +name: gempy-drivers-docs + +channels: + - conda-forge + - defaults +dependencies: + - python=3.10 + - pip + - pip: + - sphinx + - sphinx_issues + - sphinx_rtd_theme + - sphinxcontrib-bibtex + - sphinxcontrib-googleanalytics + - numpydoc + - geoh5py + - geoapps-utils + - curve-apps diff --git a/docs/peak_finder_app/make.bat b/docs/peak_finder_app/make.bat new file mode 100644 index 00000000..dc1312ab --- /dev/null +++ b/docs/peak_finder_app/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/peak_finder_app/source/THIRD_PARTY_SOFTWARE.rst b/docs/peak_finder_app/source/THIRD_PARTY_SOFTWARE.rst new file mode 100644 index 00000000..0860af60 --- /dev/null +++ b/docs/peak_finder_app/source/THIRD_PARTY_SOFTWARE.rst @@ -0,0 +1,47 @@ +Third Party Software +==================== + +The Peak-Finder repository and source distributions bundle several libraries that are +compatibly licensed. We list these here. + + +.. list-table:: + :widths: 30 30 60 + :header-rows: 1 + + * - Name + - License + - Description + * - `curve-apps `_ + - MIT + - Application for the creation of geoh5 Curves object from data. + * - `Dask `_ + - BSD-3-Clause + - Parallel PyData with Task Scheduling + * - `dash-daq `_ + - MIT + - DAQ components for Dash + * - `geoapps-utils `_ + - MIT + - Collection of utilities for creating applications and manipulating geoh5 objects. + * - `geoh5py `_ + - LGPL-3.0-or-later + - Python API for geoh5, an open file format for geoscientific data + * - `libhwloc `_ + - BSD-3-Clause + - Portable Hardware Locality (hwloc) + * - `numpy `_ + - BSD-3-Clause + - Fundamental package for array computing in Python + * - `plotly `_ + - MIT + - An open-source, interactive data visualization library for Python + * - `pyside `_ + - LGPL + - Python bindings for the Qt cross-platform application and UI framework + * - `scipy `_ + - BSD-3-Clause + - Fundamental algorithms for scientific computing in Python + * - `tqdm `_ + - MPL-2.0 or MIT + - A Fast, Extensible Progress Bar for Python and CLI diff --git a/docs/peak_finder_app/source/conf.py b/docs/peak_finder_app/source/conf.py new file mode 100644 index 00000000..63f1e09b --- /dev/null +++ b/docs/peak_finder_app/source/conf.py @@ -0,0 +1,74 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +from datetime import datetime +from importlib.metadata import version + +from packaging.version import Version + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "peak-finder" + +# The full version, including alpha/beta/rc tags. +release = version("peak-finder-app") +# The short X.Y.Z version. +version = Version(release).base_version + +project_copyright = "%Y, Mira Geoscience Ltd" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +autodoc_mock_imports = [ + "curve_apps", + "dash", + "dask", + "flask", + "geoapps_utils", + "geoh5py", + "numpy", + "plotly", + "pyqtwebengine", + "pyside2", + "scipy", + "tqdm", +] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.todo", +] + +templates_path = ["_templates"] +exclude_patterns = [] +todo_include_todos = True + +# -- Options for auto-doc ---------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc + +autodoc_typehints = "signature" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_theme_options = { + "description": f"version {release}", +} + +# Enable numref +numfig = True + + +def get_copyright_notice(): + return f"Copyright {datetime.now().strftime(project_copyright)}" + + +rst_epilog = f""" +.. |copyright_notice| replace:: {get_copyright_notice()}. +""" diff --git a/docs/peak_finder_app/source/getting_started.rst b/docs/peak_finder_app/source/getting_started.rst new file mode 100644 index 00000000..e36d912d --- /dev/null +++ b/docs/peak_finder_app/source/getting_started.rst @@ -0,0 +1,112 @@ +.. _getting_started: + +Getting Started +=============== + +Whether you are a developer or an end-user, this page will help you get started with the **peak-finder**. + +Installation +------------ + +Install Conda +~~~~~~~~~~~~~ + +Install Conda for Python 3.10 or higher. Follow this link to download its Windows installer (~140 MB of disk space): + +`Miniforge `_ `(Windows x86_64) `_ + +.. figure:: /images/getting_started/Miniforge3_Setup-1.png + :align: center + :width: 200 + +.. figure:: /images/getting_started/Miniforge3_Setup-3.png + :align: center + :width: 200 + +Registering the Conda distribution as the default Python 3.10 interpreter is optional. +Preferably uncheck that box if you already have Python 3 installed on your system. + +.. note:: We recommend installing **Miniforge**: beyond being smaller, + it also installs packages from the conda-forge repository by default, + which has no restriction for commercial use, while both Miniconda and Anaconda distributions use + the Anaconda repository by default: see `Anaconda Terms of Service `_ for details. + In any case, the installation of **peak-finder** forces the usage of the conda-forge repository, + and is thus not affected by the Anaconda Terms of Service. + +Download the latest peak-finder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow this link to `download from the GitHub repository `_. + +Extract the package to your drive (SSD if available) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extract the package to your drive, preferably an SSD if available. + +.. figure:: /images/getting_started/extract.png + :align: center + :width: 50% + + +Run ``Install_or_Update.bat`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The same batch file can be used to install or update **peak-finder**. +A conda environment named ``peak-finder`` will be created to prevent conflicts with other software that may rely on Python. + +.. figure:: /images/getting_started/install_or_update.png + :align: center + :width: 50% + +.. note:: The assumption is made that Conda has been installed in one + of the default directories, depending on the distribution + (miniforge3, mambaforge, miniconda3, anaconda3): + + - %LOCALAPPDATA%\\ + - %USERPROFILE%\\ + - %LOCALAPPDATA%\\Continuum\\ + - %PROGRAMDATA%\\ + +If Conda gets installed in a different directory, users will need to add/edit a +``get_custom_conda.bat`` file to add their custom path to the ``conda.bat`` file: + +.. figure:: /images/getting_started/Install_start_bat.png + :align: center + :width: 75% + + +Running the application +----------------------- +At this point, you will have all required packages to run the applications. +Geoscience ANALYST pro users can run the application with a **ui.json** file +by drag-and-drop: + +.. figure:: /images/getting_started/drag_and_drop.png + :align: center + :width: 75% + +or by Python menu dropdown by placing a **ui.json** file +in the Python scripts folder. + +**1.** + +.. figure:: /images/getting_started/python_scripts_folder.png + :align: center + :width: 75% + +**2.** + +.. figure:: /images/getting_started/python_menu_uijson.png + :align: center + :width: 75% + +**3.** + +.. figure:: /images/getting_started/dropdown_scripts.png + :align: center + :width: 75% + +Either operation will result in the rendering of a ui.json file within the +Geoscience ANALYST viewport. To learn about the ui.json interface and how +to run the application in one of two modes, proceed to the +:ref:`Basic Usage ` section. diff --git a/docs/peak_finder_app/source/images/getting_started/Install_start_bat.png b/docs/peak_finder_app/source/images/getting_started/Install_start_bat.png new file mode 100644 index 00000000..dfc2372a Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/Install_start_bat.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-1.png b/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-1.png new file mode 100644 index 00000000..60f11ad1 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-1.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-3.png b/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-3.png new file mode 100644 index 00000000..e564d1c7 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/Miniforge3_Setup-3.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/drag_and_drop.png b/docs/peak_finder_app/source/images/getting_started/drag_and_drop.png new file mode 100644 index 00000000..75cbc824 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/drag_and_drop.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/dropdown_scripts.png b/docs/peak_finder_app/source/images/getting_started/dropdown_scripts.png new file mode 100644 index 00000000..b48c1c75 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/dropdown_scripts.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/extract.png b/docs/peak_finder_app/source/images/getting_started/extract.png new file mode 100644 index 00000000..9fc47d8c Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/extract.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/install_or_update.png b/docs/peak_finder_app/source/images/getting_started/install_or_update.png new file mode 100644 index 00000000..43ca0302 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/install_or_update.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/python_menu_uijson.png b/docs/peak_finder_app/source/images/getting_started/python_menu_uijson.png new file mode 100644 index 00000000..b06d0c2a Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/python_menu_uijson.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/python_scripts_folder.png b/docs/peak_finder_app/source/images/getting_started/python_scripts_folder.png new file mode 100644 index 00000000..3f23a080 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/python_scripts_folder.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/uijson_parameters.png b/docs/peak_finder_app/source/images/getting_started/uijson_parameters.png new file mode 100644 index 00000000..c625dfa7 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/uijson_parameters.png differ diff --git a/docs/peak_finder_app/source/images/getting_started/using_interface.png b/docs/peak_finder_app/source/images/getting_started/using_interface.png new file mode 100644 index 00000000..83070538 Binary files /dev/null and b/docs/peak_finder_app/source/images/getting_started/using_interface.png differ diff --git a/docs/peak_finder_app/source/images/interactive/ui_controls.png b/docs/peak_finder_app/source/images/interactive/ui_controls.png new file mode 100644 index 00000000..84da0607 Binary files /dev/null and b/docs/peak_finder_app/source/images/interactive/ui_controls.png differ diff --git a/docs/peak_finder_app/source/images/interactive/visualizations.png b/docs/peak_finder_app/source/images/interactive/visualizations.png new file mode 100644 index 00000000..8666ee1a Binary files /dev/null and b/docs/peak_finder_app/source/images/interactive/visualizations.png differ diff --git a/docs/peak_finder_app/source/images/introduction/app_overview.png b/docs/peak_finder_app/source/images/introduction/app_overview.png new file mode 100644 index 00000000..b512cfe0 Binary files /dev/null and b/docs/peak_finder_app/source/images/introduction/app_overview.png differ diff --git a/docs/peak_finder_app/source/images/methodology/merge_peaks.png b/docs/peak_finder_app/source/images/methodology/merge_peaks.png new file mode 100644 index 00000000..4de89361 Binary files /dev/null and b/docs/peak_finder_app/source/images/methodology/merge_peaks.png differ diff --git a/docs/peak_finder_app/source/images/methodology/min_amplitude.png b/docs/peak_finder_app/source/images/methodology/min_amplitude.png new file mode 100644 index 00000000..20e28d6f Binary files /dev/null and b/docs/peak_finder_app/source/images/methodology/min_amplitude.png differ diff --git a/docs/peak_finder_app/source/images/methodology/min_value.png b/docs/peak_finder_app/source/images/methodology/min_value.png new file mode 100644 index 00000000..bc9b75cc Binary files /dev/null and b/docs/peak_finder_app/source/images/methodology/min_value.png differ diff --git a/docs/peak_finder_app/source/images/methodology/min_width.png b/docs/peak_finder_app/source/images/methodology/min_width.png new file mode 100644 index 00000000..d64ed9a6 Binary files /dev/null and b/docs/peak_finder_app/source/images/methodology/min_width.png differ diff --git a/docs/peak_finder_app/source/images/methodology/peak_finder_params.png b/docs/peak_finder_app/source/images/methodology/peak_finder_params.png new file mode 100644 index 00000000..41ed6d97 Binary files /dev/null and b/docs/peak_finder_app/source/images/methodology/peak_finder_params.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/flip_y.png b/docs/peak_finder_app/source/images/parameters/data_selection/flip_y.png new file mode 100644 index 00000000..cc0c66af Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/flip_y.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/group_colors.png b/docs/peak_finder_app/source/images/parameters/data_selection/group_colors.png new file mode 100644 index 00000000..eb095579 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/group_colors.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/lines.png b/docs/peak_finder_app/source/images/parameters/data_selection/lines.png new file mode 100644 index 00000000..21597dba Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/lines.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/masking_data.png b/docs/peak_finder_app/source/images/parameters/data_selection/masking_data.png new file mode 100644 index 00000000..60ed489c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/masking_data.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/outward_line_compare.png b/docs/peak_finder_app/source/images/parameters/data_selection/outward_line_compare.png new file mode 100644 index 00000000..73b2924b Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/outward_line_compare.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/outward_lines.png b/docs/peak_finder_app/source/images/parameters/data_selection/outward_lines.png new file mode 100644 index 00000000..8f388322 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/outward_lines.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection/select_line.png b/docs/peak_finder_app/source/images/parameters/data_selection/select_line.png new file mode 100644 index 00000000..725fc75e Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection/select_line.png differ diff --git a/docs/peak_finder_app/source/images/parameters/data_selection_parameters.png b/docs/peak_finder_app/source/images/parameters/data_selection_parameters.png new file mode 100644 index 00000000..207b3b4c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/data_selection_parameters.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/export.png b/docs/peak_finder_app/source/images/parameters/detection/export.png new file mode 100644 index 00000000..6a07b3ac Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/export.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/group_separation.png b/docs/peak_finder_app/source/images/parameters/detection/group_separation.png new file mode 100644 index 00000000..400f6190 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/group_separation.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/live_link.png b/docs/peak_finder_app/source/images/parameters/detection/live_link.png new file mode 100644 index 00000000..131feeb3 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/live_link.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/max_migration.png b/docs/peak_finder_app/source/images/parameters/detection/max_migration.png new file mode 100644 index 00000000..02153a61 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/max_migration.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/merge_peaks.png b/docs/peak_finder_app/source/images/parameters/detection/merge_peaks.png new file mode 100644 index 00000000..09b4550c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/merge_peaks.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/minimum_amplitude.png b/docs/peak_finder_app/source/images/parameters/detection/minimum_amplitude.png new file mode 100644 index 00000000..61478c6c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/minimum_amplitude.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/minimum_channels.png b/docs/peak_finder_app/source/images/parameters/detection/minimum_channels.png new file mode 100644 index 00000000..d0d2a670 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/minimum_channels.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/minimum_data.png b/docs/peak_finder_app/source/images/parameters/detection/minimum_data.png new file mode 100644 index 00000000..fd232bca Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/minimum_data.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/minimum_width.png b/docs/peak_finder_app/source/images/parameters/detection/minimum_width.png new file mode 100644 index 00000000..44874f6b Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/minimum_width.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/output_path.png b/docs/peak_finder_app/source/images/parameters/detection/output_path.png new file mode 100644 index 00000000..a16f823c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/output_path.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/save_as.png b/docs/peak_finder_app/source/images/parameters/detection/save_as.png new file mode 100644 index 00000000..28524f25 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/save_as.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection/smoothing.png b/docs/peak_finder_app/source/images/parameters/detection/smoothing.png new file mode 100644 index 00000000..f99171c4 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection/smoothing.png differ diff --git a/docs/peak_finder_app/source/images/parameters/detection_parameters.png b/docs/peak_finder_app/source/images/parameters/detection_parameters.png new file mode 100644 index 00000000..c87a0649 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/detection_parameters.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visual_parameters.png b/docs/peak_finder_app/source/images/parameters/visual_parameters.png new file mode 100644 index 00000000..743e82e4 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visual_parameters.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/linear_threshold.png b/docs/peak_finder_app/source/images/parameters/visualization/linear_threshold.png new file mode 100644 index 00000000..7cb4552d Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/linear_threshold.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-3p2.png b/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-3p2.png new file mode 100644 index 00000000..770b8802 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-3p2.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-5p1.png b/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-5p1.png new file mode 100644 index 00000000..29323592 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/linthresh10e-5p1.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/linthresh_compare.png b/docs/peak_finder_app/source/images/parameters/visualization/linthresh_compare.png new file mode 100644 index 00000000..0a59aa9e Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/linthresh_compare.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/markers.png b/docs/peak_finder_app/source/images/parameters/visualization/markers.png new file mode 100644 index 00000000..90c036fa Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/markers.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/outward_lines_1.png b/docs/peak_finder_app/source/images/parameters/visualization/outward_lines_1.png new file mode 100644 index 00000000..38c42617 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/outward_lines_1.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/plot_markers.png b/docs/peak_finder_app/source/images/parameters/visualization/plot_markers.png new file mode 100644 index 00000000..6f94eb57 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/plot_markers.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/plot_residuals.png b/docs/peak_finder_app/source/images/parameters/visualization/plot_residuals.png new file mode 100644 index 00000000..e09df9d6 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/plot_residuals.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/residuals.png b/docs/peak_finder_app/source/images/parameters/visualization/residuals.png new file mode 100644 index 00000000..1dc926f1 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/residuals.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/section_xlabel.png b/docs/peak_finder_app/source/images/parameters/visualization/section_xlabel.png new file mode 100644 index 00000000..6a7c431b Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/section_xlabel.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/trend_lines.png b/docs/peak_finder_app/source/images/parameters/visualization/trend_lines.png new file mode 100644 index 00000000..6031a57c Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/trend_lines.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/xlabel.png b/docs/peak_finder_app/source/images/parameters/visualization/xlabel.png new file mode 100644 index 00000000..40c807d7 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/xlabel.png differ diff --git a/docs/peak_finder_app/source/images/parameters/visualization/yscale.png b/docs/peak_finder_app/source/images/parameters/visualization/yscale.png new file mode 100644 index 00000000..20f8d898 Binary files /dev/null and b/docs/peak_finder_app/source/images/parameters/visualization/yscale.png differ diff --git a/docs/peak_finder_app/source/images/standalone/ui.png b/docs/peak_finder_app/source/images/standalone/ui.png new file mode 100644 index 00000000..7e87d264 Binary files /dev/null and b/docs/peak_finder_app/source/images/standalone/ui.png differ diff --git a/docs/peak_finder_app/source/images/usage/general_parameters.png b/docs/peak_finder_app/source/images/usage/general_parameters.png new file mode 100644 index 00000000..0ad960f5 Binary files /dev/null and b/docs/peak_finder_app/source/images/usage/general_parameters.png differ diff --git a/docs/peak_finder_app/source/images/usage/groups.png b/docs/peak_finder_app/source/images/usage/groups.png new file mode 100644 index 00000000..8c118d39 Binary files /dev/null and b/docs/peak_finder_app/source/images/usage/groups.png differ diff --git a/docs/peak_finder_app/source/images/usage/optional_parameters.png b/docs/peak_finder_app/source/images/usage/optional_parameters.png new file mode 100644 index 00000000..221e9f1f Binary files /dev/null and b/docs/peak_finder_app/source/images/usage/optional_parameters.png differ diff --git a/docs/peak_finder_app/source/images/usage/xlabel.png b/docs/peak_finder_app/source/images/usage/xlabel.png new file mode 100644 index 00000000..40c807d7 Binary files /dev/null and b/docs/peak_finder_app/source/images/usage/xlabel.png differ diff --git a/docs/peak_finder_app/source/index.rst b/docs/peak_finder_app/source/index.rst new file mode 100644 index 00000000..bc55fbb7 --- /dev/null +++ b/docs/peak_finder_app/source/index.rst @@ -0,0 +1,74 @@ +About +===== + +Peak-finder has been designed for the detection and grouping of time-domain +electromagnetic (TEM) anomalies measured along flight lines. Anomaly markers +can be exported to `Geoscience ANALYST `_, +along with various metrics for characterization and targeting. + +.. figure:: /images/interactive/visualizations.png + +The peak-finder application can operate in two modes: + + - :ref:`Interactive ` (shown above) + - :ref:`Standalone ` + +While initially designed for TEM data, the same application can be used for +characterization of anomalies of mixed data types (eg. magnetics, gravity, +topography, etc..). + +.. toctree:: + :maxdepth: 1 + + getting_started + usage + methodology + interactive_application + standalone_application + THIRD_PARTY_SOFTWARE + + +New user? +--------- + +Visit the :ref:`getting_started` page. + + +License +^^^^^^^ +MIT License + +Copyright (c) 2023-2025 Mira Geoscience + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +Third Party Software +^^^^^^^^^^^^^^^^^^^^ +The octree-creation-app Software may provide links to third party libraries or code (collectively “Third Party Software”) +to implement various functions. Third Party Software does not comprise part of the Software. +The use of Third Party Software is governed by the terms of such software license(s). +Third Party Software notices and/or additional terms and conditions are located in the +`THIRD_PARTY_SOFTWARE.rst`_ file. + +.. _THIRD_PARTY_SOFTWARE.rst: THIRD_PARTY_SOFTWARE.rst + + +Copyright +^^^^^^^^^ +|copyright_notice| diff --git a/docs/peak_finder_app/source/interactive_application.rst b/docs/peak_finder_app/source/interactive_application.rst new file mode 100644 index 00000000..f0e31f1f --- /dev/null +++ b/docs/peak_finder_app/source/interactive_application.rst @@ -0,0 +1,138 @@ +.. _interactive_application: + +Interactive Application +======================= + +If you are using **peak-finder** through the interactive application you will see +a window with visualizations and ui controls. The visualization contains both a +section of data along a single line and a plan view to locate the chosen and +adjacent lines and anomaly picks in cartesian space. + +.. figure:: /images/interactive/visualizations.png + + +The ui controls section is divided into three subsections: + +- `Detection Parameters`_ +- `Visual Parameters`_ + +.. figure:: /images/interactive/ui_controls.png + + +Detection Parameters +~~~~~~~~~~~~~~~~~~~~ + +The detection parameters are those that the peak-finder application uses to +tune the characterization and detection of anomalies within the data. Most +of these are already described in the :ref:`Methodology` section. Follow +the links for detailed descriptions of each parameter. + +.. figure:: /images/parameters/detection_parameters.png + :align: left + + +- :ref:`Smoothing window ` +- :ref:`Minimum Amplitude (%) ` +- :ref:`Minimum Value ` +- :ref:`Minimum Width (m) ` +- :ref:`Max Peak Migration (m) ` +- :ref:`Minimum # Channels ` +- :ref:`Merge # Peaks ` +- :ref:`Max Separation ` + + +Visual Parameters +~~~~~~~~~~~~~~~~~ + +This section controls the appearance of the plotting area. + +.. figure:: /images/parameters/visual_parameters.png + :align: left + + +N Outward Lines +_______________ + +Number of lines to display on either side of the selected line in the plan view. The ``Survey figure`` option must be +selected to see the effect of this parameter. + +.. figure:: /images/parameters/visualization/outward_lines_1.png + + The plan view with 1 outward line on either side of the selected line. + + +X-axis Label +____________ + +Updates the label on the data section view x-axis. + +.. figure:: /images/parameters/visualization/section_xlabel.png + + The x-axis label is updated to reflect the selection. + +Y-axis Scaling +______________ + +Updates the scaling of the y-axis of the data section view + + +Linear threshold +________________ + +When Symlog is chosen for Y-axis scaling, this parameter will set the +region in which linear scaling is used. + +.. figure:: /images/parameters/visualization/linthresh_compare.png + :scale: 60% + + Comparing the data visualization with a symlog linear threshold set to + 10E-3.2 (left) and 10E-5.1 (right). + +Plot residuals +______________ + +Switches on and off the residual visualization that shows the difference +between the raw and smoothed data. See the :ref:`Smoothing` section for more details. + +.. figure:: /images/parameters/visualization/residuals.png + :scale: 40% + + The residual layer is used to show the effect of the smoothing factor. + +Plot markers +____________ + +Switches on and off the markers outlining the character of each anomaly + +.. figure:: /images/parameters/visualization/markers.png + :scale: 40% + + Markers are used to indicate the left and right edges, the center, + and the inflection point in curvature of each anomaly. + + + +Output Parameters +~~~~~~~~~~~~~~~~~ + +Create trend line +__________________ + +Run a trend line detection algorithm on the result of the Peak Finder algorithm. Results are stored as a curve object in the geoh5 file +with the same group ID as the Peak Finder result. + + +.. figure:: /images/parameters/visualization/trend_lines.png + + +Save as +_______ + +.. autoproperty:: peak_finder.params.PeakFinderParams.ga_group_name + +Name of the group in the geoh5 file where the results will be saved. The default is ``peak_finder``. + +Export +______ + +Run the algorithm with the parameters selected and save the result to geoh5. diff --git a/docs/peak_finder_app/source/methodology.rst b/docs/peak_finder_app/source/methodology.rst new file mode 100644 index 00000000..f8260d55 --- /dev/null +++ b/docs/peak_finder_app/source/methodology.rst @@ -0,0 +1,181 @@ +.. _methodology: + +Methodology +=========== + +This section provides technical details regarding the algorithm used for the +detection of anomalies along profile. + +Anomalies are identified from the detection of maximum, minimum and inflection +points calculated from the first and second order derivatives of individual +data channels. +Detection parameters are available for filtering and grouping co-located +anomalies. The selection process is done in the following order: + +Primary detection +----------------- +Loop over the selected data channels: + +#. Apply the `Minimum Data Value`_ threshold. + +#. For every maximum (peak) found on a profile, look on either side for + inflection and minimum points. This forms an anomaly. + +#. Keep all anomalies larger than the `Minimum Amplitude`_ + +Grouping +-------- + +Anomalies found along individual data channels are grouped based on spatial +proximity: + +#. Find all peaks within the `Maximum Peak Migration`_ distance. The nearest peak is + used if multiple peaks are found on a single channel. + +#. Create an anomaly group that satisfies the following criteria: + + - The data channels must be part of a continuous series (maximum of one channel + skip is allowed) + + - A group must satisfy the `Minimum number of channels`_ + + +.. figure:: /images/methodology/peak_finder_params.png + :name: anomaly + +Detection Parameters +-------------------- + +.. _Masking Data: + +Masking Data +~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.masking_data + +Masking data is used to filter out data points that are not considered by the algorithm. +This is useful for focusing on specific regions of interest. + +.. _Smoothing: + +Smoothing +~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.smoothing + +The running mean replaces each data by the average of it's ``N`` neighbours: + +.. math:: + d_i = \frac{1}{N}\sum_{j=-\frac{N}{2}}^{\frac{N}{2}}d_{i+j} + +where averaging becomes one sided at both ends of the profile. The result is a +smoothed data set where the degree of smoothing scales with the number of +neighbours used in the mean. + +.. figure:: /images/parameters/visualization/residuals.png + + The residual between the original and smoothed data. + + +.. _Minimum Amplitude: + +Minimum Amplitude +~~~~~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.min_amplitude + +Threshold value (:math:`\delta A`) for filtering small anomalies based on the anomaly +minimum (:math:`d_{min}`) and maximum (:math:`d_{max}`). + +.. math:: + + \delta A = \left|\left|\frac{d_{max} - d_{min}}{d_{min}}\right|\right| \cdot 100 + +See :ref:`figure ` for a visual example of the anomaly amplitude. + +.. figure:: /images/methodology/min_amplitude.png + :name: amplitude + + +.. _Minimum Data Value: + +Minimum Data Value +~~~~~~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.min_value + +The minimum data threshold (:math:`\delta_d`) (see :ref:`Figure `) can be defined by: + +.. math:: + + \begin{equation} + d_i = + \begin{cases} + d_i & \;\text{for } d_i > \delta_d \\ + nan & \;\text{for } d_i \leq \delta_d\\ + \end{cases} + \end{equation} + +.. figure:: /images/methodology/min_value.png + :name: value + + +.. _Minimum Width: + +Minimum Width +~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.min_width + +The minimum distance (m) between the start and the end of an anomaly group to be considered. + +.. figure:: /images/methodology/min_width.png + :name: width + + +.. _Maximum Peak Migration: + +Maximum Peak Migration +~~~~~~~~~~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.max_migration + +The maximum distance (m) between the peaks within a group of anomalies. This +parameter depends on the :ref:`Minimum number of channels `. + +See :ref:`figure ` for a visual example of migration within a +group of anomalies. + +.. _Minimum number of channels: + +Minimum number of channels +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.min_channels + +The minimum number of data channels required to form a group of anomalies. + +See :ref:`figure ` for a visual example of channels making up a +group of anomalies. + +.. _Merge N Peaks: + +Merge N Peaks +~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.n_groups + +Post-grouping of anomalies based on the number of consicutive peaks. The parameter +depends on the :ref:`Max Group Separation `. + +.. figure:: /images/methodology/merge_peaks.png + :name: merge + +.. _Max Group Separation: + +Max Group Separation +~~~~~~~~~~~~~~~~~~~~ + +.. autoproperty:: peak_finder.params.PeakFinderParams.max_separation + +The maximum distance (m) between the start and the end of a neighboring groups. diff --git a/docs/peak_finder_app/source/standalone_application.rst b/docs/peak_finder_app/source/standalone_application.rst new file mode 100644 index 00000000..4b749165 --- /dev/null +++ b/docs/peak_finder_app/source/standalone_application.rst @@ -0,0 +1,32 @@ +.. _standalone_application: + +Standalone Application +====================== + +The standalone application contains no visualization and operates on the entire +data object provided in the :ref:`General Parameters ` section of the ui.json. +For this reason we will limit the discussion here to the :ref:`detection parameters ` +as well as the :ref:`grouping parameters ` that affect not only the visual representation +in the interactive application, but also the grouping for detection within the +standalone application. + +.. _detection parameters: + +.. figure:: /images/standalone/ui.png + + Detection parameters section of the peak finder ui.json. + +- :ref:`Smoothing window ` +- :ref:`Minimum Amplitude (%) ` +- :ref:`Minimum Value ` +- :ref:`Minimum Width (m) ` +- :ref:`Max Peak Migration (m) ` +- :ref:`Minimum # Channels ` +- :ref:`Merge # Peaks ` +- :ref:`Max Separation ` + +Masking Data +____________ + +Provide an Mask (boolean) data object to focus the peak finder process on an area +of interest. diff --git a/docs/peak_finder_app/source/usage.rst b/docs/peak_finder_app/source/usage.rst new file mode 100644 index 00000000..523b72bf --- /dev/null +++ b/docs/peak_finder_app/source/usage.rst @@ -0,0 +1,75 @@ +.. _usage: + +User interface +============== + +The main entry point is the ``peak_finder.ui.json`` file +(stored under `peak-finder-assets `_) +for the peak-finder application that can be rendered by Geoscience ANALYST. The interface has two sections: + + - :ref:`General Parameters ` (required) + - :ref:`Optional Parameters ` + +ui.json interface +~~~~~~~~~~~~~~~~~ + +The ui.json interface has two sections: + +.. _General Parameters: + +1. General Parameters +_____________________ + +The general parameters must be set before running the application, regardless of +the mode of operation. + +.. figure:: /images/usage/general_parameters.png + :scale: 40% + + +- *Object*: Curve entity containing the data and line ID information. +- *Line Field*: [Optional] Referenced data defining the line identifier. If omitted, the line ID + is inferred from the unique curve parts. +- *Property Group*: Property group data to be used in the detection and grouping. To add more groups, see + the :ref:`Optional Parameters ` section. +- *Color*: Hex color code used to label the peaks identified. A default value is provided that will + suffice in most cases. +- *Save as*: Name of the output group holding the results. +- *Export all markers*: If selected, all markers will be exported to the output group. If not selected, + only the peak group centers will be exported. +- *Create trend lines*: If selected, trend lines are created connecting the peak group centers across survey lines. See + the `Trend Line `_ + documentation page for more information. +- *Run interactive app*: If selected, the ui.json parameters will be + used to initialize an interactive application. In this mode, any changes made + through the ui will override the values set in the ui.json. Without the + *run interactive app* checkbox selected, the application will be run in a terminal + with the parameters set in the ui.json (standalone mode). + +.. _Optional Parameters: + +2. Optional Parameters +______________________ + + +These parameters are required to run in :ref:`Standalone `, but not necessary to run the application in :ref:`Interactive ` mode. + +.. figure:: /images/usage/optional_parameters.png + :scale: 40% + +Note that the group parameters have no equivalent in the interactive application, +and must be set in the optional parameters tab. If a user wishes to find peaks in more +than one group of time channels, say, they must add the groups here. + +.. _grouping parameters: + +.. figure:: /images/usage/groups.png + :scale: 40% + + Groups can be added by checking the box to enable and selecting a property group and + color representation. + +To learn more about the algorithm and its parameters, see the :ref:`methodology ` +section. To see how the parameters are exposed in each of the application modes visit the +:ref:`interactive ` and :ref:`standalone ` +pages