Add usage for 5 of the modules

.gitignore

@@ -4,7 +4,6 @@
 ecl2df.egg-info
 .tox
 *.swp
-*.csv
 *.pyc
 *~
 docs/modules.rst

docs/conf.py

@@ -42,6 +42,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",

docs/index.rst

@@ -10,6 +10,7 @@ data format.
    :maxdepth: 2
 
    introduction
+   usage
    scripts
    modules
    installation

docs/introduction.rst

@@ -48,6 +48,8 @@ Short description of each submodule
 Extracts summary data from `.UNSMRY` files, at requested time sampling and
 for requested vectors.
 
+More documentation on :doc:`usage/summary`.
+
 ``grid``
 ^^^^^^^^
 
@@ -56,6 +58,8 @@ are optional to extract, and dates must be picked (or all). Data is
 merged into one DataFrame by the `i`, `j` and `k` indices. Bulk cell
 volume is included. Cells are indexed as in Eclipse, starting with 1.
 
+More documentation on :doc:`usage/grid`.
+
 ``nnc``
 ^^^^^^^
 
@@ -64,13 +68,17 @@ output data in EGRID, not the NNC input keyword), as pairs of
 `ijk`-indices and the associated transmissiblity. Optional filtering
 to vertical connections (along pillars).
 
+More documentation on :doc:`usage/nnc`.
+
 ``pillars``
 ^^^^^^^^^^^
 
 Compute statistics pr cornerpoint pillar, and optionally compute hydrocarbon
 fluid contacts pr. pillar and pr. date based on saturation cutoffs. Data
 can be grouped and aggregated over a region parameter.
 
+More documentation on :doc:`usage/pillars`.
+
 ``trans``
 ^^^^^^^^^
 
@@ -81,6 +89,8 @@ out transmissibilities over f.ex. a FIPNUM interface. Data can also be aggregate
 over the region interface to give a grid-independent quantification of region
 communication.
 
+More documentation on :doc:`usage/trans`.
+
 ``rft``
 ^^^^^^^
 
@@ -91,6 +101,8 @@ For multisegment wells, the well topology is calculated and data
 is merged accordingly, for example when ICD segments are used, enabling
 easy calculations of the pressure drop over an ICD valve.
 
+More documentation on :doc:`usage/rft`.
+
 ``fipreports``
 ^^^^^^^^^^^^^^
 
@@ -100,19 +112,25 @@ in the ASCII table in the PRT file and organize into a dataframe,
 currently-in-place, outflow to wells, outflows to regions, etc. It also
 supports custom FIPxxxxx names.
 
+More documentation on :doc:`usage/fipreports`.
+
 
 ``satfunc``
 ^^^^^^^^^^^
 
 Extracts saturation functions (SWOF, SGOF, etc) from the deck and merges
 into one DataFrame. Can write back to Eclipse include files.
 
+More documentation on :doc:`usage/satfunc`.
+
 ``equil``
 ^^^^^^^^^
 
 Extracts the information in the `EQUIL` table, `RSVD` and `RVVD` in the
 input deck. Can write back to Eclipse include files.
 
+More documentation on :doc:`usage/equil`.
+
 ``compdat``
 ^^^^^^^^^^^
 
@@ -123,6 +141,8 @@ data is available as three different dataframes, which can be merged.
 It is also possible to parse individual "include" files, not only a
 finished working deck.
 
+More documentation on :doc:`usage/compdat`.
+
 ``gruptree``
 ^^^^^^^^^^^^
 
@@ -131,18 +151,24 @@ all timesteps, from the input deck. The tree structure at each relevant
 date can be returned as a dataframe of the edges, as a nested dictionary
 or as a `treelib` tree.
 
+More documentation on :doc:`usage/gruptree`.
+
 ``pvt``
 ^^^^^^^
 
 Extracts PVT data from an Eclipse deck, from the keywords `PVTO`, `PVDG`,
 `DENSITY`, `ROCK` etc. Can write data back to Eclipse include files.
 
+More documentation on :doc:`usage/pvt`.
+
 ``wcon``
 ^^^^^^^^
 
 Extracts `WCONxxxx` keywords from the Schedule section, and providing the
 associated data in a dataframe format.
 
+More documentation on :doc:`usage/wcon`.
+
 ``eclfiles``
 ^^^^^^^^^^^^
 

docs/usage.rst

@@ -0,0 +1,13 @@
+Usage and examples
+==================
+
+This section will go through each module in more detail, with examples.
+
+.. toctree::
+   :maxdepth: 1
+
+   usage/nnc
+   usage/equil
+   usage/fipreports
+   usage/pillars
+   usage/pvt

docs/usage/equil-example.csv

@@ -0,0 +1,7 @@
+EQLNUM,KEYWORD,Z,PRESSURE,OWC,GOC,RS
+1,EQUIL,2469.0,382.4,1700.0,0.0,
+2,EQUIL,2469.0,382.4,1000.0,0.0,
+1,RSVD,1500.0,,,,184.0
+1,RSVD,4000.0,,,,184.0
+2,RSVD,1500.0,,,,184.0
+2,RSVD,4000.0,,,,184.0

docs/usage/equil.rst

@@ -0,0 +1,69 @@
+equil
+-----
+
+This is the ecl2df module for processing the ``SOLUTION`` section of
+the Eclipse input deck.
+
+Supported keywords are ``EQUIL``, ``RSVD`` and ``RVVD``. Typical usage
+is
+
+.. code-block:: python
+
+    from ecl2df import equil, EclFiles
+
+    dframe = equil.df(EclFiles('MYECLDECK.DATA'))
+
+Which will provide a dataframe similar to the example below. Note that the column
+`Z` is used both for datum depth and the depth values in ``RSVD`` tables. The
+amount of columns obtained depends on the input dataset, and should be possible
+to link up with the Eclipse documentation. API doc: :func:`ecl2df.equil.df`
+
+..
+  dframe = equil.df(EclFiles('tests/data/reek/eclipse/model/2_R001_REEK-0.DATA'))
+  dframe[['EQLNUM', 'KEYWORD', 'Z', 'PRESSURE', 'OWC', 'GOC', 'RS']]\
+  .to_csv(index=False))
+
+.. csv-table:: Equil dataframe example
+   :file: equil-example.csv
+   :header-rows: 1
+
+The dataframe obtained can be exported to CSV using ``.to_csv()`` for further
+processing or visualization, or it can be transformed using Python (Pandas)
+operations.
+
+Transforming data
+^^^^^^^^^^^^^^^^^
+
+Shifting all oil-water contacts down by one meter could for example
+be accomplished by the operation
+
+.. code-block:: python
+
+   dframe["OWC"] = dframe["OWC"] + 1
+
+This statement will not interfere with the ``RSVD`` lines, as they are NaN for
+this column. But still, you might want to push your `Rs` initialization down
+one meter for compatibility, which you could do by the statements:
+
+.. code-block:: python
+
+   rsvd_rows = dframe["KEYWORD"] == "RSVD"
+   dframe.loc[rsvd_rows, "Z"] = dframe.loc[rsvd_rows, "Z"] + 1
+
+
+Re-exporting tables to Eclipse include files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you are done with the table, you can generate new include files for
+Eclipse from your modified data by issuing
+
+.. code-block:: python
+
+   inc_string = equil.df2ecl(dframe)
+
+   # Write inc_string to a file
+   with open("solution.inc", "w") as file_handle:
+      file_handle.write(inc_string)
+
+The last step can also be done using the ``csv2ecl`` command line utility
+if you dump to CSV from your Python code instead.

docs/usage/fipreports-example.csv

@@ -0,0 +1,9 @@
+DATE,FIPNAME,REGION,DATATYPE,TO_REGION,STOIIP_OIL,ASSOCIATEDOIL_GAS,STOIIP_TOTAL,WATER_TOTAL,GIIP_GAS,ASSOCIATEDGAS_OIL,GIIP_TOTAL
+2000-01-01,FIPZON,2,CURRENTLY IN PLACE,,21091398.0,,21091398.0,4590182.0,-0.0,483594842.0,483594842.0
+2000-01-01,FIPZON,2,OUTFLOW TO OTHER REGIONS,,76266.0,,76266.0,75906.0,0.0,1818879.0,1818879.0
+2000-01-01,FIPZON,2,OUTFLOW THROUGH WELLS,,,,0.0,0.0,,,0.0
+2000-01-01,FIPZON,2,MATERIAL BALANCE ERROR.,,,,0.0,0.0,,,0.0
+2000-01-01,FIPZON,2,ORIGINALLY IN PLACE,,21136892.0,,21136892.0,4641214.0,0.0,484657561.0,484657561.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,1.0,143128.0,,143128.0,-161400.0,0.0,3017075.0,3017075.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,3.0,-66862.0,,-66862.0,198900.0,-0.0,-1198195.0,-1198195.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,8.0,0.0,,0.0,38405.0,0.0,0.0,0.0

docs/usage/fipreports-example.txt

@@ -0,0 +1,20 @@
+  REPORT   0     1 JAN 2000 
+                                                =================================
+                                                : FIPZON  REPORT REGION    2    :
+                                                :     PAV =        139.76  BARSA:
+                                                :     PORV=     27777509.   RM3 :
+                           :--------------- OIL    SM3  ---------------:-- WAT    SM3  -:--------------- GAS    SM3  ---------------:
+                           :     LIQUID         VAPOUR         TOTAL   :       TOTAL    :       FREE      DISSOLVED         TOTAL   :
+ :-------------------------:-------------------------------------------:----------------:-------------------------------------------:
+ :CURRENTLY IN PLACE       :     21091398.                    21091398.:       4590182. :           -0.    483594842.     483594842.
+ :-------------------------:-------------------------------------------:----------------:-------------------------------------------:
+ :OUTFLOW TO OTHER REGIONS :        76266.                       76266.:         75906. :            0.      1818879.       1818879.
+ :OUTFLOW THROUGH WELLS    :                                         0.:             0. :                                         0.
+ :MATERIAL BALANCE ERROR.  :                                         0.:             0. :                                         0.
+ :-------------------------:-------------------------------------------:----------------:-------------------------------------------:
+ :ORIGINALLY IN PLACE      :     21136892.                    21136892.:       4641214. :            0.    484657561.     484657561.
+ :-------------------------:-------------------------------------------:----------------:-------------------------------------------:
+ :OUTFLOW TO REGION   1    :       143128.                      143128.:       -161400. :            0.      3017075.       3017075.
+ :OUTFLOW TO REGION   3    :       -66862.                      -66862.:        198900. :           -0.     -1198195.      -1198195.
+ :OUTFLOW TO REGION   8    :            0.                           0.:         38405. :            0.            0.             0.
+ ====================================================================================================================================

docs/usage/fipreports.rst

@@ -0,0 +1,27 @@
+fipreports
+----------
+
+fipreports is a parser for the Eclipse PRT output file, extracting data
+from these tables:
+
+.. literalinclude:: fipreports-example.txt
+
+This table found in a PRT file will be parsed to the following dataframe:
+
+..
+  Generated with ecl2csv fipreports -v --fipname FIPZON fipreports-example.PRT -o fipreports-example.csv
+  Date added manually
+
+.. csv-table:: FIPZON table from PRT file
+   :file: fipreports-example.csv
+   :header-rows: 1
+
+In this particular example, ``FIPZON`` was selected explicitly, either using the command line client or the Python API
+through an option to the :func:`ecl2df.fipreports.df` function.
+
+Using this module is easiest through ``ecl2csv fipreports``.
+
+
+
+
+

docs/usage/nnc.csv

@@ -0,0 +1,16 @@
+I1,J1,K1,I2,J2,K2,TRAN
+30,4,2,31,4,1,0.021288443
+30,4,3,31,4,1,0.009700679
+30,4,3,31,4,2,0.007962288
+30,4,4,31,4,1,0.015650248
+30,4,4,31,4,2,0.011269862
+30,4,4,31,4,3,0.011947993
+30,4,5,31,4,1,0.01754331
+30,4,5,31,4,2,0.012022105
+30,4,5,31,4,3,0.012787791
+30,4,5,31,4,4,0.010922459
+30,4,6,31,4,1,0.01070403
+30,4,6,31,4,2,0.008370555
+30,4,6,31,4,3,0.0087851025
+30,4,6,31,4,4,0.007625016
+30,4,6,31,4,5,0.005188691

docs/usage/nnc.rst

@@ -0,0 +1,35 @@
+nnc
+---
+
+nnc will extract Non-Neighbour-Connections from your Eclipse grid as pairs
+of *ijk* indices together with their associated transmissibilities.
+
+..
+  nnc.df(EclFiles('tests/data/reek/eclipse/model/2_R001_REEK-0.DATA')).head(15).to_csv('docs/usage/nnc.csv', index=False)
+
+.. code-block:: python
+
+   from ecl2df import nnc, EclFiles
+
+   eclfiles = EclFiles('MYDATADECK.DATA')
+   dframe = nnc.df(eclfiles)
+
+.. csv-table:: Example nnc table
+   :file: nnc.csv
+   :header-rows: 1
+
+
+Alternatively, the same data can be produced as a CSV file using the command line
+
+.. code-block:: console
+
+  ecl2csv nnc MYDATADECK.DATA --verbose --output nnc.csv
+
+It is possible to add *xyz* coordinates for each connection (as the
+average of the xyz for each of the cells involved in a connection pair) as
+extra columns.
+
+If you only want vertical connections, add the option ``--pillars`` or ``-vertical``,
+or set ``pillars=True`` if using the Python API.
+
+

docs/usage/outflow.csv

@@ -0,0 +1,9 @@
+DATE,FIPNAME,REGION,DATATYPE,TO_REGION,STOIIP_OIL,ASSOCIATEDOIL_GAS,STOIIP_TOTAL,WATER_TOTAL,GIIP_GAS,ASSOCIATEDGAS_OIL,GIIP_TOTAL
+2000-01-01,FIPZON,2,CURRENTLY IN PLACE,,21091398.0,,21091398.0,4590182.0,-0.0,483594842.0,483594842.0
+2000-01-01,FIPZON,2,OUTFLOW TO OTHER REGIONS,,76266.0,,76266.0,75906.0,0.0,1818879.0,1818879.0
+2000-01-01,FIPZON,2,OUTFLOW THROUGH WELLS,,,,0.0,0.0,,,0.0
+2000-01-01,FIPZON,2,MATERIAL BALANCE ERROR.,,,,0.0,0.0,,,0.0
+2000-01-01,FIPZON,2,ORIGINALLY IN PLACE,,21136892.0,,21136892.0,4641214.0,0.0,484657561.0,484657561.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,1.0,143128.0,,143128.0,-161400.0,0.0,3017075.0,3017075.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,3.0,-66862.0,,-66862.0,198900.0,-0.0,-1198195.0,-1198195.0
+2000-01-01,FIPZON,2,OUTFLOW TO REGION,8.0,0.0,,0.0,38405.0,0.0,0.0,0.0

docs/usage/pillars-dyn1-stacked.csv

@@ -0,0 +1,6 @@
+DATE,GASVOL,OILVOL,OWC,PERMX,PERMY,PERMZ,PILLAR,PORO,PORV,VOLUME,WATVOL,X,Y,Z
+2000-01-01,0.0,9762.7,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89917.5,460480.6,5933271.1,1716.3
+2000-07-01,0.0,9846.4,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89833.8,460480.6,5933271.1,1716.3
+2001-02-01,0.0,9892.4,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89787.8,460480.6,5933271.1,1716.3
+2001-08-01,0.0,9874.8,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89805.4,460480.6,5933271.1,1716.3
+2000-01-01,0.0,1918.3,1699.9,1737.7,1740.5,385.7,14-31,0.2,128119.9,735191.0,126201.6,460840.8,5932584.7,1712.6

docs/usage/pillars-dyn1-unstacked.csv

@@ -0,0 +1,6 @@
+DATE,GASVOL,OILVOL,OWC,PERMX,PERMY,PERMZ,PILLAR,PORO,PORV,VOLUME,WATVOL,X,Y,Z
+2000-01-01,0.0,9762.7,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89917.5,460480.6,5933271.1,1716.3
+2000-07-01,0.0,9846.4,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89833.8,460480.6,5933271.1,1716.3
+2001-02-01,0.0,9892.4,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89787.8,460480.6,5933271.1,1716.3
+2001-08-01,0.0,9874.8,1698.4,397.2,405.1,142.9,14-26,0.1,99680.2,843873.2,89805.4,460480.6,5933271.1,1716.3
+2000-01-01,0.0,1918.3,1699.9,1737.7,1740.5,385.7,14-31,0.2,128119.9,735191.0,126201.6,460840.8,5932584.7,1712.6

docs/usage/pillars-example1.csv

@@ -0,0 +1,6 @@
+PILLAR,X,Y,Z,VOLUME,PERMX,PERMY,PERMZ,PORV,PORO
+1-1,456620.8,5935659.6,1753.6,1053244.0,1095.9,1140.2,108.6,182502.8,0.2
+1-10,457336.4,5934421.1,1742.2,1078104.1,776.9,758.3,82.8,171530.9,0.2
+1-11,457416.0,5934283.4,1743.0,1035282.9,1332.2,1332.6,301.4,200754.5,0.2
+1-12,457495.9,5934145.8,1745.8,1084271.9,1713.9,1639.4,336.1,218128.4,0.2
+1-13,457575.9,5934008.2,1746.1,1097513.3,1531.9,1451.0,296.1,203463.0,0.2