petrelpy.gslib
==============

.. py:module:: petrelpy.gslib

.. autoapi-nested-parse::

   Work with gslib geomodel format.



Functions
---------

.. autoapisummary::

   petrelpy.gslib.load_from_petrel
   petrelpy.gslib.get_midpoint_cell_columns
   petrelpy.gslib.load_petrel_tops_file
   petrelpy.gslib.match_well_to_cell
   petrelpy.gslib.match_ijz_petrel
   petrelpy.gslib.aggregate_well_properties
   petrelpy.gslib.get_facies_stats
   petrelpy.gslib.get_facies_histograms


Module Contents
---------------

.. py:function:: load_from_petrel(fin: pathlib.Path | str, npartitions=60) -> dask.dataframe.DataFrame

   Load GSLIB geomodel file.

   :param fin: gslib Petrel output
   :type fin: Path | str
   :param npartitions: number of partitions for dask dataframe. Defaults to 60.
   :type npartitions: int, optional

   :returns: lazy-evaluated dataframe with geomodel properties
   :rtype: dd.DataFrame


.. py:function:: get_midpoint_cell_columns(geomodel: dask.dataframe.DataFrame, dir_out: str)

   Find cell columns where UWI-index exists in the geomodel.

   :param geomodel: geocellular model extracted from gslib file
   :type geomodel: dd.DataFrame
   :param dir_out: folder to store the parquet file in
   :type dir_out: str

   :returns: vertical column of cells around the well's midpoint
   :rtype: pd.DataFrame


.. py:function:: load_petrel_tops_file(tops_file: pathlib.Path | str)

   Load in petrel tops file and return pandas dataframe.


.. py:function:: match_well_to_cell(midpoints: pandas.DataFrame, geomodel: pandas.DataFrame, distance_upper_bound: float = 2000) -> pandas.DataFrame

   Give each well in df_wells the i,j,k index of the nearest cell in df_cells.

   :param midpoints: well midpoint locations. Columns include Well,X,Y,Z
   :type midpoints: pd.DataFrame
   :param geomodel: geocellular model. Columns include x_coord,y_coord,z_coord
   :type geomodel: pd.DataFrame
   :param distance_upper_bound: max distance between well and center of cell.
                                Defaults to 2000.
   :type distance_upper_bound: float, optional

   :returns: geomodel cells nearest to each well midpoint
   :rtype: pd.DataFrame


.. py:function:: match_ijz_petrel(geomodel: dask.dataframe.DataFrame, uwi_to_index: pandas.DataFrame, wdir: str, zdmax: float = 1000)

   Merge geomodel with wells to assign properties to wells.

   :param geomodel: dask dataframe of the geomodel, must include a column
                    called 'UWI-index', ijk indices, and z coordinate
   :type geomodel: dask.DataFrame
   :param uwi_to_index: pandas dataframe with UWI-Index column and UWI column to do
                        merging
   :type uwi_to_index: pd.DataFrame
   :param wdir: string pointing to the working directory for behind-the-scenes parquet file
                creation
   :type wdir: str
   :param zdmax: maximum z variation from cells in ij column to point including a UWI-index
   :type zdmax: float

   :returns: merged dataframe that has all your favorite attributes in an ij column with
             less than zdmax vertical separation from midpoint at UWI-index.
   :rtype: pd.DataFrame


.. py:function:: aggregate_well_properties(geomodel_ijmatched: pandas.DataFrame, well_midponts: pandas.DataFrame | None = None, zdmax: float = 200, agg_arg='mean', uwi_col='UWI-Index') -> pandas.DataFrame

   Find average geocellular properties about well midpoint.

   :param geomodel_ijmatched: geomodel after paring down to nearby cells
   :type geomodel_ijmatched: pd.DataFrame
   :param well_midponts: geocells nearest each well midpoint.
                         Defaults to None. If none, cuts geomodel_ijmatched down to those with a valid uwi_col
   :type well_midponts: pd.DataFrame | None, optional
   :param zdmax: Max vertical distance between well and geocell. Defaults to 200.
   :type zdmax: float, optional
   :param agg_arg: method for aggregating. Defaults to "mean".
   :type agg_arg: str, optional
   :param uwi_col: geocellular column with well identifier. Defaults to "UWI-Index".
   :type uwi_col: str, optional

   :returns: average properties for each well index
   :rtype: pd.DataFrame


.. py:function:: get_facies_stats(df, zonename='Mainzones', faciesname='Facies', attrs=None)

   Get aggregated statistics for different facies and zones.


.. py:function:: get_facies_histograms(geomodel: dask.dataframe.DataFrame, zone_name: str = 'Mainzones', facies_name: str = 'Facies', properties: list[str] | None = None, ooip_name: str = 'OOIP') -> tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]

   Calculate histogram of original oil in place for geomodel by zone, facies, properties.

   :param geomodel: geocellular model with zone, facies, properties
   :type geomodel: dd.DataFrame
   :param zone_name: column naming the zone. Defaults to "Mainzones".
   :type zone_name: str, optional
   :param facies_name: column naming the facies. Defaults to "Facies".
   :type facies_name: str, optional
   :param properties: columns holding properties to compute histogram over.
                      Defaults to ["Phi", "Sw"].
   :type properties: list[str], optional
   :param ooip_name: Property to calculate the histogram over. Defaults to "OOIP".
   :type ooip_name: str, optional

   :returns:

             ooip_splits, index_conversion, and
                 max property values
   :rtype: tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]