Merge pull request #53 from trhallam/t20-master

T20 Finish

README.rst

@@ -170,15 +170,18 @@ following attributes are extracted or reserved for use by ``SEGY-SAK``.
  * ``ns`` number of samples per trace
  * ``ds`` sample interval
  * ``text`` ebcidc header as ascii text
- * ``d3_units`` vertical units of the data
+ * ``measurement_sys`` vertical units of the data
  * ``d3_domain`` vertical domain of the data
  * ``epsg`` data epsg code
  * ``corner_points`` corner points of the dataset in grid coordinates
  * ``corner_points_xy`` corner points of the dataset in xy
  * ``source_file`` name of the file the dataset was created from
- * ``srd`` seismic reference datum of the data in vertical units ``d3_units``
+ * ``srd`` seismic reference datum of the data in vertical units ``measurement_sys``
    and ``d3_domain``
  * ``datatype`` the data type e.g. amplitude, velocity, attribute
+ * ``percentiles`` this is an array of approximate percentile values created during
+   scanning from SEGY. Primarily this is useful for plotting by limiting the dynamic
+   range of the display. The percentiles are in percent 0, 0.1, 10, 50, 90, 99.9 & 100.
 
 Complete Documentation
 ----------------------

docs/api.rst

@@ -108,6 +108,7 @@ segysak xarray accessor modules
   SeisGeom.is_depth
   SeisGeom.is_empty
   SeisGeom.zeros_like
+  SeisGeom.get_measurement_system
 
 ``seisnc`` data tools
 
@@ -123,4 +124,10 @@ segysak xarray accessor modules
   :toctree: generated/
 
   SeisGeom.xysel
+  SeisGeom.interp_line
   SeisGeom.surface_from_points
+
+``seisnc`` plotting functions
+  :toctree: generated/
+
+  SeisGeom.plot_bounds

docs/command-line-tool.rst

@@ -16,7 +16,7 @@ convert between data formats.
 
 .. program-output:: segysak scan --help
 
-**segysak scan**
+**segysak scrape**
 
 .. program-output:: segysak scrape --help
 

docs/conf.py

@@ -124,12 +124,19 @@
 data_dir.mkdir(exist_ok=True)
 nb_dir.mkdir(exist_ok=True)
 
-data = ["volve10r12-full-twt-sub3d.sgy", "hor_twt_hugin_fm_top.dat"]
+data = [
+    "volve10r12-full-twt-sub3d.sgy",
+    "hor_twt_hugin_fm_top.dat",
+    "volve10r12-full-twt-arb.sgy",
+    "arbitrary_line.shp",
+]
 nbs = [
     "example_segysak_basics.ipynb",
     "example_segysak_dask.ipynb",
-    "example_extract_data_on_a_horizon.ipynb",
+    "example_amplitude_extraction_displays.ipynb",
     "example_segy_headers.ipynb",
+    "QuickOverview.ipynb",
+    "example_extract_arbitrary_line.ipynb",
 ]
 
 # copy data

docs/examples.rst

@@ -7,5 +7,6 @@ Examples
 
     _examples/notebooks/example_segysak_basics
     _examples/notebooks/example_segy_headers
-    _examples/notebooks/example_extract_data_on_a_horizon
-    _examples/notebooks/example_segysak_dask
+    _examples/notebooks/example_amplitude_extraction_displays
+    _examples/notebooks/example_extract_arbitrary_line
+    _examples/notebooks/example_segysak_dask

docs/index.rst

@@ -1,34 +1,52 @@
 segysak: A library for loading and manipulating SEG-Y data with Python using **xarray**
 ========================================================================================
 
-**segysak** is a ...
+**SEGYSAK** can be use as a tool to handle *SEGY*
+files inside Python environment.
 
-**segysak** leverages Xarray_ and Pandas_, to simplify handling of seismic data with
-coordinates and meta data. It also offered a large number of utilities for common
-seismic operations. To handle large data files it uses netCDF_ files, which were 
-also the source of xarray's data model.
+By including  **SEGYSAK** in your toolbox you will be
+able to load or transform the original binary *SEGY* data into more accessible and
+Python friendly formats. It leverages the work of Segyio_ to simplify
+loading of common SEGY formats into ``xarray.Dataset`` objects for east of use and
+to NetCDF4_ files for better on disk and large file performance using dask_.
+Tools to help users create new volumes and to return data to SEGY are also included.
 
+Additional features include
+----------------------------
+
+ - **Arbitrary slicing and extration**
+
+  - label based slicing
+  - horizon
+  - well path extraction
+
+ - **Integrates with the existing Python scientific stack**
+
+  - Leverage Xarray_ for easy coordinate management merging and plotting
+  - Inheritted compatibility with core Python libraries (NumPy_, Scipy and Pandas_).
+  - Works well with matplotlib_ and Pyvista_
+
+ - **Scalability**
+
+  - NetCDF4 files work with dask to scale your Python code to multi-core and
+    distributed memory computing
+
+.. _Segyio: https://segyio.readthedocs.io/en/latest/segyio.html
 .. _NumPy: http://www.numpy.org
 .. _Pandas: http://pandas.pydata.org
 .. _dask: http://dask.org
-.. _netCDF: http://www.unidata.ucar.edu/software/netcdf
+.. _NetCDF4: http://www.unidata.ucar.edu/software/netcdf
 .. _Xarray: http://xarray.pydata.org/en/stable/
+.. _Pyvista: https://docs.pyvista.org/
+.. _matplotlib: https://matplotlib.org/
 
 
 Documentation
 -------------
 
 **Getting Started**
 
-TODO:
- - quick-overview
-
 * :doc:`why-segysak`
-* :doc:`faq`
-
-.. * :doc:`quick-overview`
-
-* :doc:`examples`
 * :doc:`installation`
 
 .. toctree::
@@ -38,37 +56,27 @@ TODO:
 
    why-segysak
    installation
-   examples
-   faq
-
-..    quick-overview
+   _examples/notebooks/QuickOverview
 
 **User Guide**
 
-TODO:
-  - seisnc-standard
-  - terminology
-  - common-tasks
-
 * :doc:`seisnc-standard`
+* :doc:`examples`
 * :doc:`command-line-tool`
+* :doc:`faq`
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents
    :hidden:
 
    seisnc-standard
+   examples
    command-line-tool
-..    terminology
-..    common-tasks
+   faq
 
 **Help & Reference**
 
-TODO:
-  - contributing
-  - related-projects
-
 * :doc:`api`
 
 .. * :doc:`contributing`
@@ -86,10 +94,9 @@ See also
 
 Fundamental Python libraries to segysak are segyio_ and xarray_.
 
-.. _segyio: https://segyio.readthedocs.io/en/latest/
 .. _xarray: http://xarray.pydata.org/en/stable/
 
-The full Volve dataset was published by Equinor and you can read_ about it 
+The full Volve dataset was published by Equinor and you can read_ about it
 or get a copy of it here_.
 
 .. _read: https://www.equinor.com/en/news/14jun2018-disclosing-volve-data.html
@@ -98,9 +105,11 @@ or get a copy of it here_.
 Get in touch
 ------------
 
-Contact through swung channel
-
+Contact us through our Swung Slack channel - |slack|
 
+.. |slack| image:: https://img.shields.io/badge/slack-help-blueviolet?logo=slack
+   :alt: help
+   :target: https://swung.slack.com/messages/t20-segysak/
 
 History
 -------
@@ -109,7 +118,7 @@ in Python. The ground work was layed by Tony Hallam but development really began
 during the Transform 2020 Software Underground Hackathon held online across
 the world due to the cancellation of of the EAGE Annual in June of that year.
 Significant contributions during the hackathon
-were made by Steve Purves, Gijs Straathof and Fabio ... .
+were made by Steve Purves, Gijs Straathof, Fabio Contreras and Alessandro Amato del Monte.
 
 License
 -------

docs/installation.rst

@@ -1,7 +1,11 @@
 Installation
 -------------
 
-*SEGY-SAK* can be installed by using pip or python setuptools.
+*SEGY-SAK* can be installed by using pip or python setuptools, we also provide an ``environment.yml`` for use
+with conda and is available through Github_.
+
+.. _Github: https://github.com/trhallam/segysak
+
 
 Python Package Index via ``pip``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -20,3 +24,9 @@ Clone the SEGY-SAK Github repository and in the top level directory run setuptoo
 .. code-block:: shell
 
    python setup.py install
+
+And to run the tests
+
+.. code-block:: shell
+
+   python setup.py test

docs/seisnc-standard.rst

@@ -1,2 +1,78 @@
-SEISNC Standard
-===============
+SEISNC Standard for `xarray`
+============================
+
+The ``xarray`` seismic specification termed ``seisnc`` can be used by segysak to
+output NETCDF4 files is more performant for Python operations than standard SEG-Y.
+Unlike SEG-Y, ``xarray`` compatable files fit neatly into the Python scientific
+stack providing operations like lazy loading, easy slicing, compatability with
+multi-core and multi-node operations using ``dask`` as well as important features
+such as labelled axes and coordinates.
+
+This specification is not meant to be prescriptive but outlines some basic
+requirements for ``xarray`` datasets to work with *SEGYSAK* functionality.
+
+*SEGY-SAK* uses the convention ``.seisnc`` for the suffix on NETCDF4 files it
+creates. These files are datasets with specific 1D and 2D coordiates and have a
+single variable called ``data``.
+The ``data`` variable contains the seismic cube volume or 2D line traces.
+Attributes can be used to provide further metadata about the cube.
+
+3D and 3D Gathers
+^^^^^^^^^^^^^^^^^
+
+*SEGY-SAK* uses the convention labels of ``iline``, ``xline`` and ``offset`` to
+describe
+the bins of 3D data. Vertical dimensions are ``twt`` and ``depth``. A typical
+``xarray`` dataset created by *SEGY-SAK* will return for example
+
+.. code-block:: python
+
+   >>> seisnc_3d = segysak.segy_loader('test3d.sgy', iline=189, xline=193)
+   >>> seisnc_3d.dims
+
+   Frozen(SortedKeysDict({'iline': 61, 'xline': 202, 'twt': 850}))
+
+
+2D and 2D Gathers
+^^^^^^^^^^^^^^^^^
+
+For 2D data SEGY-SAK uses the dimensino labels ``cdp`` and ``offset``. This allows
+the package to distinguish between 2D and 3D data to allow automation on saving
+and convience wrappers. The same vertical dimensions apply as for 3D.
+A typical ``xarray`` in 2D format would return
+
+.. code-block:: python
+
+   >>> seisnc_2d = segysak.segy_loader('test2d.sgy', cdp=21)
+   >>> seisnc_2d.dims
+
+   Frozen(SortedKeysDict({'cdp': 61, 'twt': 850}))
+
+Coordinates
+^^^^^^^^^^^^
+
+If the ``cdpx`` and ``cdpy`` byte locations are specified during loading the
+SEGY the coordinates will be populated from the headers with the variable names
+``cdp_x`` and ``cdp_y``. These will have dimensions equivalent to the horizontal
+dimensions of the data (``iline``, ``xline`` for 3D and ``cdp`` for 2D).
+
+Attributes
+^^^^^^^^^^^
+Any number of attributes can be added to a ``siesnc`` file. Currently the
+following attributes are extracted or reserved for use by ``SEGY-SAK``.
+
+ * ``ns`` number of samples per trace
+ * ``ds`` sample interval
+ * ``text`` ebcidc header as ascii text
+ * ``measurement_sys`` vertical units of the data
+ * ``d3_domain`` vertical domain of the data
+ * ``epsg`` data epsg code
+ * ``corner_points`` corner points of the dataset in grid coordinates
+ * ``corner_points_xy`` corner points of the dataset in xy
+ * ``source_file`` name of the file the dataset was created from
+ * ``srd`` seismic reference datum of the data in vertical units ``measurement_sys``
+   and ``d3_domain``
+ * ``datatype`` the data type e.g. amplitude, velocity, attribute
+ * ``percentiles`` this is an array of approximate percentile values created during
+   scanning from SEGY. Primarily this is useful for plotting by limiting the dynamic
+   range of the display. The percentiles are in percent 0, 0.1, 10, 50, 90, 99.9 & 100.

docs/why-segysak.rst

@@ -1,2 +1,27 @@
-Overview: Why segysak?
-======================
+Overview: Why SEGY-SAK?
+========================
+
+The objective of SEGY-SAK was to bring together the usefulness of `segyio` and
+`xarray` to improve accessibility of seismic data for geoscientists using Python.
+Key objectives for this project are to make loading and exporting SEG-Y easier
+by offering common simple interfaces to `segyio` and to then load data into an
+`xarray` format either directly into memory or by streaming large files to disk.
+
+Currently SEGY-SAK can load 2D, 2D gathers, 3D and 3D gathers into a common format
+stable format called `seisnc` that you can use faithfully in your downstream
+applications. The `seisnc` format is outlined in the standard section of the
+documentation and is the basis for all of the other functionality provided by
+SEGY-SAK.
+
+Beyond that, the `segysak` package has enhancements to `xarray` that reduce
+complexity for common seismic related tasks to extracting information from seismic
+such as arbitrary line, well-deviation or horizon extractions. We also offer a
+long list of notebook examples to help new and experienced Python users alike
+traverse the intricacies of Xarray and demonstrate how to do common tasks with
+`segysak`.
+
+Finally, the use of Xarray and the NetCDF4 format allows you to scale your problems
+using Dask. Dask can lazily load and process data across multiple cores and even
+distributed memory allowing you to apply your Python code to large seismic volumes.
+This process also means you can plot slices from your volumes in Python
+without loading the full dataset into memory.

environment.yml

@@ -26,7 +26,6 @@ dependencies:
   - pip
   - click
   - attrdict
-  - seaborn
   - pyshp
   - pip:
       - sphinxcontrib-programoutput