log2frame 0.2.1__tar.gz → 0.2.2__tar.gz

{log2frame-0.2.1/src/log2frame.egg-info → log2frame-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log2frame
-Version: 0.2.1
+Version: 0.2.2
 Summary: A function to facilitate loading well log data, in las or dlis format, as dataframe.
 Author-email: Martin Carlos Araya <martinaraya@gmail.com>
 License: MIT License
@@ -51,8 +51,8 @@ Dynamic: license-file
 
 A function to read well log data in LAS, LIS and DLIS formats and extract curves data as DataFrame.
 
-The curves and header data are stored in an instance of `Log` class, designed to hold this data and operate with it.
-If multiple log files are read together, the __Log__ instances are packed in a `Pack` instance, designed to hold `Log` instances and operate with them.
+The curves and header data are stored in an instance of ``Log`` class, designed to hold this data and operate with it. It provides convenient access to metadata like well name, UWI, and curve units (via ``.units`` or the safer ``.units_dict()``).
+If multiple log files are read together, the __Log__ instances are packed in a ``Pack`` instance, designed to hold ``Log`` instances and operate with them.
 
 # unit-aware mode
 When `simpandas` is installed, `log2frame` can preserve curve units and index units through the `use_simpandas` option.

{log2frame-0.2.1 → log2frame-0.2.2}/README.md

@@ -4,8 +4,8 @@
 
 A function to read well log data in LAS, LIS and DLIS formats and extract curves data as DataFrame.
 
-The curves and header data are stored in an instance of `Log` class, designed to hold this data and operate with it.
-If multiple log files are read together, the __Log__ instances are packed in a `Pack` instance, designed to hold `Log` instances and operate with them.
+The curves and header data are stored in an instance of ``Log`` class, designed to hold this data and operate with it. It provides convenient access to metadata like well name, UWI, and curve units (via ``.units`` or the safer ``.units_dict()``).
+If multiple log files are read together, the __Log__ instances are packed in a ``Pack`` instance, designed to hold ``Log`` instances and operate with them.
 
 # unit-aware mode
 When `simpandas` is installed, `log2frame` can preserve curve units and index units through the `use_simpandas` option.

{log2frame-0.2.1 → log2frame-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "log2frame"
-version = "0.2.1"
+version = "0.2.2"
 authors = [
   { name="Martin Carlos Araya", email="martinaraya@gmail.com" },
 ]

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/__init__.py

@@ -14,8 +14,11 @@ import os.path
 import logging
 from .rft import *
 
-__version__ = '0.2.1'
-__release__ = 20260426
+for name in ("lasio", "lasio.reader", "lasio.las", "unyts"):
+    logging.getLogger(name).setLevel(logging.WARNING)
+
+__version__ = '0.2.2'
+__release__ = 20260427
 __all__ = ['read', 'concat']
 
 
@@ -55,6 +58,23 @@ def _read_one(path: str, raise_error=True, use_simpandas=None, correct_units=Tru
 
 
 def read(path: str, recursive=True, raise_error=False, squeeze=True, use_simpandas=None, correct_units=True):
+    """Read a well-log file (LAS, DLIS, LIS) into a units-aware :class:`Log` container.
+
+    Accepts individual file paths or a list of paths/globs. If multiple files are
+    read, they are returned grouped in a :class:`Pack` container.
+
+    Parameters
+    ----------
+    path : str | list[str]
+        Path to the ``.las``, ``.dlis``, or ``.lis`` file(s). Glob expressions and directory paths are supported.
+    recursive : bool, default True
+        If reading a path pattern with globs, controls whether directories are searched recursively.
+    squeeze : bool, default True
+        If True and only one log is inside a resulting pack, return that single Log object instead of the Pack.
+    use_simpandas : bool | None, default None
+    raise_error : bool, default False
+    correct_units : bool, default True
+    """
     if use_simpandas is not None and use_simpandas is True and not _params_.simpandas_:
         raise ModuleNotFoundError("SimPandas is not installed, please install it or set parameter `use_simpandas` to False.")
     use_simpandas = _params_.simpandas_ if use_simpandas is None else bool(use_simpandas)

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/dictionaries/units.py

@@ -12,8 +12,17 @@ from pathlib import Path
 this_path_ = Path(__file__).with_name('units_dictionary.json').absolute()
 this_path_ = dirname(this_path_) + '/'
 
-with open(this_path_ + 'units_dictionary.json', 'r') as f:
-    units_correction_dict_ = json.load(f)
+try:
+    with open(this_path_ + 'units_dictionary.json', 'r') as f:
+        units_correction_dict_ = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError) as e:
+    import warnings
+    warnings.warn(
+        f"log2frame: units-correction dictionary not found "
+        f"({type(e).__name__}: {e}); proceeding with unit-correction disabled.",
+        UserWarning,
+    )
+    units_correction_dict_ = {}
 
 
 def correct_units(units):

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/dlis.py

@@ -19,8 +19,8 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
@@ -34,6 +34,31 @@ class DLISIOError(Exception):
 
 
 def dlis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=True):
+    """Read a DLIS file into a :class:`Log` container.
+
+    Parameters
+    ----------
+    path : str
+        Path to the ``.dlis`` file.
+    use_simpandas : bool | None, default None
+        If True, the returned :class:`Log` wraps a
+        :class:`simpandas.SimDataFrame` and units propagate through
+        operations. If False, plain :class:`pandas.DataFrame` is used.
+        ``None`` falls back to True when SimPandas is installed.
+    raise_error : bool, default True
+        If False, parse errors are caught and ``None`` is returned
+        instead of raising.
+    correct_units : bool, default True
+        Apply the LAS-mnemonic-to-canonical-unit corrections (GR's
+        ``GAPI`` ↔ ``gAPI`` etc.) defined in
+        :data:`dictionaries.units_correction_dict_`.
+
+    Returns
+    -------
+    Log | Pack | None
+        The parsed log; or a ``Pack`` of logs if multiple frames are present; 
+        ``None`` if parsing failed and ``raise_error=False``.
+    """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
     if type(path) is str:

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/las.py

@@ -18,8 +18,8 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
@@ -33,6 +33,39 @@ class LASIOError(Exception):
 
 
 def las2frame(path: str, use_simpandas=None, raise_error=True, correct_units=True):
+    """Read a LAS file (1.2 / 2.0 / 3.0) into a :class:`Log` container.
+
+    Parameters
+    ----------
+    path : str
+        Path to the ``.las`` file.
+    use_simpandas : bool | None, default None
+        If True, the returned :class:`Log` wraps a
+        :class:`simpandas.SimDataFrame` and units propagate through
+        operations. If False, plain :class:`pandas.DataFrame` is used.
+        ``None`` falls back to True when SimPandas is installed.
+    raise_error : bool, default True
+        If False, parse errors are caught and ``None`` is returned
+        instead of raising.
+    correct_units : bool, default True
+        Apply the LAS-mnemonic-to-canonical-unit corrections (GR's
+        ``GAPI`` ↔ ``gAPI`` etc.) defined in
+        :data:`dictionaries.units_correction_dict_`.
+
+    Returns
+    -------
+    Log | None
+        The parsed log; ``None`` if parsing failed and
+        ``raise_error=False``.
+
+    Examples
+    --------
+    >>> log = log2frame.las2frame("well.las")
+    >>> log.curves
+    ['GR', 'NPHI', 'RHOB', 'DT']
+    >>> log.units_dict()['GR']
+    'gAPI'
+    """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
     if type(path) is str:

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/lis.py

@@ -18,8 +18,8 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
@@ -32,6 +32,31 @@ class DLISIOError(Exception):
         self.message = 'ERROR: reading LIS file ' + message
 
 def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=True):
+    """Read a LIS file into a :class:`Log` container.
+
+    Parameters
+    ----------
+    path : str
+        Path to the ``.lis`` or ``.lti`` file.
+    use_simpandas : bool | None, default None
+        If True, the returned :class:`Log` wraps a
+        :class:`simpandas.SimDataFrame` and units propagate through
+        operations. If False, plain :class:`pandas.DataFrame` is used.
+        ``None`` falls back to True when SimPandas is installed.
+    raise_error : bool, default True
+        If False, parse errors are caught and ``None`` is returned
+        instead of raising.
+    correct_units : bool, default True
+        Apply the LAS-mnemonic-to-canonical-unit corrections (GR's
+        ``GAPI`` ↔ ``gAPI`` etc.) defined in
+        :data:`dictionaries.units_correction_dict_`.
+
+    Returns
+    -------
+    Log | Pack | None
+        The parsed log; or a ``Pack`` of logs if multiple frames are present; 
+        ``None`` if parsing failed and ``raise_error=False``.
+    """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
     if type(path) is str:

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/log.py

@@ -9,8 +9,8 @@ import pandas as pd
 import unyts
 
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 __all__ = ['Log']
 
 logging.basicConfig(level=logging.INFO)
@@ -22,6 +22,43 @@ class Log2FrameType(type):
 
 
 class Log(object, metaclass=Log2FrameType):
+    """A single well-log file represented as a units-aware container.
+
+    Public attributes
+    -----------------
+    name : str
+        Well name (from the ``WELL`` mnemonic).
+    uwi : str | None
+        Unique Well Identifier (from ``UWI`` / ``API``); ``None`` if absent.
+    path : str
+        Path to the source file.
+    source : str
+        Format identifier — ``"LAS"`` / ``"DLIS"`` / ``"LIS"``.
+    data : SimDataFrame | DataFrame
+        Curves, indexed by depth.
+    columns : list[str]
+        Curve mnemonics.
+    index_units : str
+        Unit of the depth index (``"M"`` / ``"FT"`` / …).
+    units : pandas.Series
+        Per-mnemonic units. **Multi-element Series**; do not test for
+        truthiness directly — see :meth:`units_dict`.
+    well : object
+        WELL-section attribute access (``log.well.STRT`` etc.).
+    header, meta, curves : ...
+        Free-form access to the LAS / DLIS sections.
+
+    Methods
+    -------
+    index_to(unit) → Log
+        Return a copy with the depth index converted to *unit*.
+    to(unit) → Log
+        Convert *all* curves to *unit* where the conversion is defined.
+    set_index(curve), set_index_name(name), set_index_units(unit)
+        Mutators on the depth index.
+    rename, copy, sort, keys
+        DataFrame-style helpers.
+    """
 
     def __init__(self, data=None, header=None, units=None, source=None, well=None):
         self.data = data
@@ -122,17 +159,60 @@ class Log(object, metaclass=Log2FrameType):
 
     @property
     def index_units(self):
+        units_str = None
         if hasattr(self.data, 'index_units'):
-            return self.data.index_units
+            units_str = self.data.index_units
         elif self.data.index.name in self.units:
-            return self.units[self.data.index.name]
+            units_str = self.units[self.data.index.name]
         else:
             logging.warning("index units are not defined.")
+            
+        if isinstance(units_str, str):
+            _DEPTH_UNIT_CANONICAL = {
+                "m": "m", "metre": "m", "meter": "m", "meters": "m", "metres": "m",
+                "ft": "ft", "foot": "ft", "feet": "ft",
+            }
+            return _DEPTH_UNIT_CANONICAL.get(units_str.strip().lower(), units_str)
+        return units_str
 
     @index_units.setter
     def index_units(self, units: str):
         self.set_index_units(units)
 
+    @property
+    def units(self) -> pd.Series:
+        """Per-mnemonic units as a pandas ``Series`` (not a dict).
+
+        .. note::
+            ``Log.units`` is a multi-element ``Series``, **not** a dict.
+            The conventional ``dict(log.units or {})`` pattern silently
+            evaluates to ``{}`` because of pandas' truthiness behaviour.
+            Use :meth:`units_dict` or ``dict(log.units)`` explicitly.
+        """
+        return self._units
+
+    @units.setter
+    def units(self, value):
+        self._units = value
+
+    def units_dict(self) -> dict:
+        """Return the curve→unit mapping as a plain ``dict``.
+
+        Use this instead of ``dict(log.units)`` if you want to support both
+        the (unusual) zero-curve case and the normal multi-curve case in a
+        single line.
+
+        >>> units = log.units_dict()
+        >>> units.get('GR', 'unknown')
+        'gAPI'
+        """
+        if self._units is None:
+            return {}
+        s = self._units
+        if hasattr(s, "empty") and s.empty:
+            return {}
+        return dict(s)
+
     def keys(self):
         return self.data.columns
 

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/pack.py

@@ -9,8 +9,8 @@ import numpy as np
 import pandas as pd
 from .log import Log, Log2FrameType
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 __all__ = ['Pack', 'concat']
 
 logging.basicConfig(level=logging.INFO)

{log2frame-0.2.1 → log2frame-0.2.2}/src/log2frame/rft.py

@@ -8,8 +8,8 @@ import pandas as pd
 import glob
 import os
 
-__version__ = '0.2.1'
-__release__ = 20260426
+__version__ = '0.2.2'
+__release__ = 20260427
 __all__ = ['rft_summaries_from_folders', 'rft_summary']
 
 

{log2frame-0.2.1 → log2frame-0.2.2/src/log2frame.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log2frame
-Version: 0.2.1
+Version: 0.2.2
 Summary: A function to facilitate loading well log data, in las or dlis format, as dataframe.
 Author-email: Martin Carlos Araya <martinaraya@gmail.com>
 License: MIT License
@@ -51,8 +51,8 @@ Dynamic: license-file
 
 A function to read well log data in LAS, LIS and DLIS formats and extract curves data as DataFrame.
 
-The curves and header data are stored in an instance of `Log` class, designed to hold this data and operate with it.
-If multiple log files are read together, the __Log__ instances are packed in a `Pack` instance, designed to hold `Log` instances and operate with them.
+The curves and header data are stored in an instance of ``Log`` class, designed to hold this data and operate with it. It provides convenient access to metadata like well name, UWI, and curve units (via ``.units`` or the safer ``.units_dict()``).
+If multiple log files are read together, the __Log__ instances are packed in a ``Pack`` instance, designed to hold ``Log`` instances and operate with them.
 
 # unit-aware mode
 When `simpandas` is installed, `log2frame` can preserve curve units and index units through the `use_simpandas` option.