log2frame 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log2frame
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -63,6 +63,12 @@ When `simpandas` is installed, `log2frame` can preserve curve units and index un
 # to read log files
 Simply call the function `read()` with the path or path pattern as argument:
 
+# to export / write LAS files
+Use `write_las()` to export a `Log` back to a LAS file:
+- `log2frame.write_las( log, path_to_file )` — writes LAS 2.0 by default
+- `log2frame.write_las( log, path_to_file, version=1.2 )` — LAS 1.2
+- `log.to_las( path_to_file )` — equivalent convenience method on `Log`
+
 ## a single log file
 To load a single _.las_, _.lis_ or _.dlis_ file. The function will return a `Log` instance containing the data:  
 - `log2frame.read( path_to_file )` 

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

@@ -16,6 +16,12 @@ When `simpandas` is installed, `log2frame` can preserve curve units and index un
 # to read log files
 Simply call the function `read()` with the path or path pattern as argument:
 
+# to export / write LAS files
+Use `write_las()` to export a `Log` back to a LAS file:
+- `log2frame.write_las( log, path_to_file )` — writes LAS 2.0 by default
+- `log2frame.write_las( log, path_to_file, version=1.2 )` — LAS 1.2
+- `log.to_las( path_to_file )` — equivalent convenience method on `Log`
+
 ## a single log file
 To load a single _.las_, _.lis_ or _.dlis_ file. The function will return a `Log` instance containing the data:  
 - `log2frame.read( path_to_file )` 

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

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

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

@@ -1,14 +1,29 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Thu Jan 19 19:01:21 2023
+"""log2frame — well-log data reader and writer.
+
+This package reads well-log files in LAS, DLIS, and LIS formats and
+returns the curve data as unit-aware :class:`Log` (single file) or
+:class:`Pack` (multiple files) containers built on top of
+:class:`pandas.DataFrame` (or :class:`simpandas.SimDataFrame` when the
+optional ``simpandas`` package is installed).
 
-@author: Martín Carlos Araya <martinaraya@gmail.com>
+The package also provides :func:`write_las` to export any :class:`Log`
+back to a LAS 1.2 / 2.0 file.
+
+Public API
+----------
+read(path, ...)          Read one or many log files.
+write_las(log, path)     Write a Log to a LAS file.
+concat(logs)             Concatenate a list of Log objects into a single DataFrame.
 """
+# Created on Thu Jan 19 19:01:21 2023
+# @author: Martín Carlos Araya <martinaraya@gmail.com>
 from .las import las2frame
 from .dlis import dlis2frame
 from .lis import lis2frame
 from .pack import Pack, concat
 from .log import Log
+from .writer import write_las
 import glob
 import os.path
 import logging
@@ -17,12 +32,26 @@ from .rft import *
 for name in ("lasio", "lasio.reader", "lasio.las", "unyts"):
     logging.getLogger(name).setLevel(logging.WARNING)
 
-__version__ = '0.2.2'
-__release__ = 20260427
-__all__ = ['read', 'concat']
+__version__ = '0.2.4'
+__release__ = 20261015
+__all__ = ['read', 'concat', 'write_las']
 
 
 class _Log2FrameParams(object):
+    """Package-level singleton holding runtime configuration flags.
+
+    Attributes
+    ----------
+    simpandas_ : bool
+        ``True`` when the optional ``simpandas`` package is importable.
+        Used by all readers to decide whether to return a
+        :class:`simpandas.SimDataFrame` or a plain
+        :class:`pandas.DataFrame`.
+    raise_error_ : bool
+        Default value for the *raise_error* parameter of :func:`read`.
+        Set to ``True`` to propagate parse errors; ``False`` silently
+        skips unreadable files.
+    """
     def __init__(self):
         try:
             import simpandas as spd
@@ -36,6 +65,23 @@ _params_ = _Log2FrameParams()
 
 
 def _read_one(path: str, raise_error=True, use_simpandas=None, correct_units=True):
+    """Dispatch a single file path to the appropriate format reader.
+
+    Parameters
+    ----------
+    path : str
+        Path to a ``.las``, ``.dlis``, or ``.lis`` / ``.lti`` file.
+    raise_error : bool, default True
+        Whether to propagate parse errors or return ``None``.
+    use_simpandas : bool | None, default None
+        Passed through to the format-specific reader.
+    correct_units : bool, default True
+        Passed through to the format-specific reader.
+
+    Returns
+    -------
+    Log | None
+    """
     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)
@@ -66,14 +112,36 @@ def read(path: str, recursive=True, raise_error=False, squeeze=True, use_simpand
     Parameters
     ----------
     path : str | list[str]
-        Path to the ``.las``, ``.dlis``, or ``.lis`` file(s). Glob expressions and directory paths are supported.
+        Path to the ``.las``, ``.dlis``, or ``.lis`` file(s).  Glob
+        expressions (``**/*.*``) and bare directory paths are supported.
     recursive : bool, default True
-        If reading a path pattern with globs, controls whether directories are searched recursively.
+        Whether ``**`` glob patterns recurse into subdirectories.
     squeeze : bool, default True
-        If True and only one log is inside a resulting pack, return that single Log object instead of the Pack.
+        Return a single :class:`Log` directly when the result would be a
+        one-entry :class:`Pack`.
     use_simpandas : bool | None, default None
+        Use :class:`simpandas.SimDataFrame` for curve storage when
+        ``True``; plain :class:`pandas.DataFrame` when ``False``;
+        auto-detect when ``None`` (default).
     raise_error : bool, default False
+        Raise exceptions for unreadable files.  When ``False`` (default)
+        unreadable files are silently skipped.
     correct_units : bool, default True
+        Normalise unit strings using the built-in correction dictionary
+        (e.g. ``GAPI`` → ``gAPI``).
+
+    Returns
+    -------
+    Log | Pack
+        A :class:`Log` if a single file was resolved; a :class:`Pack`
+        otherwise (unless *squeeze* collapses a one-entry Pack).
+
+    Examples
+    --------
+    >>> import log2frame
+    >>> log = log2frame.read('well.las')
+    >>> pack = log2frame.read('data/**/*.las')
+    >>> log = log2frame.read(['run1.las', 'run2.las'], squeeze=False)
     """
     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.")

log2frame-0.2.4/src/log2frame/dictionaries/units.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""Unit-name correction mapping for LAS/DLIS/LIS mnemonics.
+
+Loads ``units_dictionary.json`` (stored alongside this file) and
+exposes :func:`correct_units` to normalise non-standard unit strings to
+their canonical forms (e.g. ``'GAPI'`` → ``'gAPI'``,
+``'OHMM'`` → ``'ohm.m'``).
+
+Module-level attributes
+-----------------------
+units_correction_dict_ : dict
+    The raw ``{non_canonical: canonical}`` mapping loaded from the JSON
+    dictionary.  An empty dict is used as a safe fallback when the file
+    is missing or malformed (a :class:`UserWarning` is emitted).
+"""
+
+import json
+from os.path import dirname
+from pathlib import Path
+
+this_path_ = Path(__file__).with_name('units_dictionary.json').absolute()
+this_path_ = dirname(this_path_) + '/'
+
+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):
+    """Normalise unit strings using the built-in correction dictionary.
+
+    Parameters
+    ----------
+    units : str | dict
+        A single unit string, or a ``{mnemonic: unit}`` dict whose
+        values are corrected.  Any other type is returned unchanged.
+
+    Returns
+    -------
+    str | dict
+        The corrected unit string (when *units* is a ``str``) or a new
+        dict with corrected values (when *units* is a ``dict``).  Returns
+        the input unchanged when *units* is neither.
+
+    Examples
+    --------
+    >>> from log2frame.dictionaries.units import correct_units
+    >>> correct_units('GAPI')
+    'gAPI'
+    >>> correct_units({'GR': 'GAPI', 'RHOB': 'G/C3'})
+    {'GR': 'gAPI', 'RHOB': 'g/c3'}
+    """
+    if type(units) is dict:
+        return {k: (units_correction_dict_[u]
+                    if u in units_correction_dict_
+                    else u)
+                for k, u in units.items()}
+    elif type(units) is str and units in units_correction_dict_:
+        return units_correction_dict_[units]
+    else:
+        return units

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

@@ -1,8 +1,13 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Thu Jan 19 20:07:16 2023
+"""DLIS reader — parse DLIS files into :class:`Log` or :class:`Pack` containers.
+
+This module wraps ``dlisio`` to provide curve data and metadata as
+unit-aware :class:`Log` objects.  When a DLIS file contains multiple
+logical files or frames, a :class:`Pack` grouping all frames is returned.
 
-@author: Martín Carlos Araya <martinaraya@gmail.com>
+Public API
+----------
+dlis2frame(path, ...)    Read a ``.dlis`` file.
 """
 
 import logging
@@ -19,16 +24,14 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.2'
-__release__ = 20260427
+__version__ = '0.2.3'
+__release__ = 20260503
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
 
 class DLISIOError(Exception):
-    """
-    Error raised while reading LAS file.
-    """
+    """Raised when ``dlisio`` fails to parse a DLIS file."""
     def __init__(self, message='raised by dlisio.'):
         self.message = 'ERROR: reading DLIS file ' + message
 
@@ -61,6 +64,7 @@ def dlis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tr
     """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
+    original_path = path
     if type(path) is str:
         path = path.replace('\\', '/')
 
@@ -154,10 +158,10 @@ def dlis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tr
             data=data[0] if not use_simpandas else spd.SimDataFrame(data=data[0], units=data[2].to_dict(),
                                                                     name=data[3],
                                                                     meta=data[1],
-                                                                    source=str(path)),
+                                                                    source=str(original_path)),
             header=data[1],
             units=data[2],
-            source=str(path),
+            source=str(original_path),
             well=data[3]) for name, data in frames.items()}
         return frames[list(frames.keys())[0]]
     else:
@@ -167,11 +171,11 @@ def dlis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tr
                                                                     meta=data[1],
                                                                     source='logical file ' + str(name[0]) +
                                                                            ', frame ' + str(name[1]) +
-                                                                           ' in: ' + path),
+                                                                           ' in: ' + str(original_path)),
             header=data[1],
             units=data[2],
             source='logical file ' + str(name[0]) +
                    ', frame ' + str(name[1]) +
-                   ' in: ' + path,
+                   ' in: ' + str(original_path),
             well=data[3]) for name, data in frames.items()}
         return Pack(frames)

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

@@ -1,8 +1,12 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Thu Jan 19 19:02:12 2023
+"""LAS reader — parse LAS 1.2, 2.0, and 3.0 files into :class:`Log` containers.
+
+This module wraps ``lasio`` to provide curve data and metadata as
+unit-aware :class:`Log` objects.
 
-@author: Martín Carlos Araya <martinaraya@gmail.com>
+Public API
+----------
+las2frame(path, ...)    Read a ``.las`` file.
 """
 import logging
 import lasio
@@ -18,16 +22,14 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.2'
-__release__ = 20260427
+__version__ = '0.2.3'
+__release__ = 20260503
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
 
 class LASIOError(Exception):
-    """
-    Error raised while reading LAS file.
-    """
+    """Raised when ``lasio`` fails to parse a LAS file."""
     def __init__(self, message='raised by lasio.'):
         self.message = 'ERROR: reading LAS file ' + message
 
@@ -68,6 +70,7 @@ def las2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
     """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
+    original_path = path
     if type(path) is str:
         path = path.replace('\\', '/')
 
@@ -125,10 +128,10 @@ def las2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
                                 units=las_units,
                                 name=well_name,
                                 meta=las_header,
-                                source=path)
+                                source=original_path)
 
     return Log(data=data,
                header=las_header,
                units=pd.Series(las_units, name='curves_units'),
-               source=path,
+               source=original_path,
                well=well_name)

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

@@ -1,8 +1,15 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Thu Jan 19 20:07:16 2023
+"""LIS reader — parse LIS files into :class:`Log` or :class:`Pack` containers.
+
+This module wraps ``dlisio.lis`` to provide curve data and metadata as
+unit-aware :class:`Log` objects.  When a LIS file contains multiple
+logical files or format specs with different sample rates, each
+combination is returned as a separate :class:`Log` grouped in a
+:class:`Pack`.
 
-@author: Martín Carlos Araya <martinaraya@gmail.com>
+Public API
+----------
+lis2frame(path, ...)    Read a ``.lis`` or ``.lti`` file.
 """
 
 import logging
@@ -18,16 +25,14 @@ try:
 except ModuleNotFoundError:
     pass
 
-__version__ = '0.2.2'
-__release__ = 20260427
+__version__ = '0.2.3'
+__release__ = 20260503
 
 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
 
 
 class DLISIOError(Exception):
-    """
-    Error raised while reading LAS file.
-    """
+    """Raised when ``dlisio`` fails to parse a LIS file."""
     def __init__(self, message='raised by dlisio.'):
         self.message = 'ERROR: reading LIS file ' + message
 
@@ -59,6 +64,7 @@ def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
     """
     if not os.path.isfile(path):
         raise FileNotFoundError("The provided path can't be found:\n" + str(path))
+    original_path = path
     if type(path) is str:
         path = path.replace('\\', '/')
 
@@ -69,6 +75,28 @@ def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
         raise ModuleNotFoundError("SimPandas is not installed, please install it or set parameter `use_simpandas` to False.")
 
     def _get_frame(data, l_count, i, sr):
+        """Return the curve data for one format spec and sample rate.
+
+        When *use_simpandas* is ``True``, wraps the raw structured array
+        in a :class:`simpandas.SimDataFrame` with units and index
+        settings applied.  Otherwise returns a plain
+        :class:`pandas.DataFrame` with the index set to the depth column.
+
+        Parameters
+        ----------
+        data : pandas.DataFrame
+            Raw DataFrame produced from :func:`dlisio.lis.curves`.
+        l_count : int
+            Logical-file counter key into ``frames``.
+        i : int
+            Format-spec index within the logical file.
+        sr : int | float
+            Sample-rate key within the format spec.
+
+        Returns
+        -------
+        pandas.DataFrame | simpandas.SimDataFrame
+        """
         if frames[l_count][i]['index_name'] in data:
             index_name = frames[l_count][i]['index_name']
         elif len([c for c in data.columns if c.startswith(frames[l_count][i]['index_name'])]) > 0:
@@ -90,12 +118,31 @@ def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
                                           if frames[l_count]['header']['name'] is not None
                                              and len(frames[l_count]['header']['name']) > 0 else None),
                                     meta=_make_header(l_count=l_count, i=i, sr=sr),
-                                    source='logical file ' + str(l_count) + ', frame ' + str(i) + ', sample rate ' + str(sr) + ' in: ' + str(path))
+                                    source='logical file ' + str(l_count) + ', frame ' + str(i) + ', sample rate ' + str(sr) + ' in: ' + str(original_path))
         else:
             return data.set_index(index_name)
 
 
     def _make_header(l_count, i, sr):
+        """Build a merged header DataFrame for one logical file / frame / sample rate.
+
+        Concatenates curve units, wellsite data, and LIS file/reel header
+        into a single :class:`pandas.DataFrame` indexed by mnemonic.
+
+        Parameters
+        ----------
+        l_count : int
+            Logical-file index.
+        i : int
+            Format-spec index within the logical file.
+        sr : int | float
+            Sample-rate key.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Combined header table; empty cells are replaced with ``''``.
+        """
         to_concat = []
         if 'curves_units' in frames[l_count][i] and sr in frames[l_count][i]['curves_units']:
             to_concat.append(pd.DataFrame(frames[l_count][i]['curves_units'][sr],
@@ -110,6 +157,18 @@ def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
         return pd.concat(to_concat, axis=0).fillna(value='')
 
     def _try_frame(data):
+        """Attempt to wrap *data* in a :class:`pandas.DataFrame`.
+
+        Parameters
+        ----------
+        data : structured numpy array or similar
+            Raw curve data returned by :func:`dlisio.lis.curves`.
+
+        Returns
+        -------
+        pandas.DataFrame | None
+            ``None`` when the conversion raises any exception.
+        """
         try:
             return pd.DataFrame(data)
         except:
@@ -186,7 +245,7 @@ def lis2frame(path: str, use_simpandas=None, raise_error=True, correct_units=Tru
                     source='logical file ' + str(l_count) +
                            ', frame ' + str(i) +
                            ', sample rate ' + str(sr) +
-                           ' in: ' + str(path),
+                           ' in: ' + str(original_path),
                     well=(
                         frames[l_count]['header']['service_name'] if frames[l_count]['header']['service_name'] is not None and len(
                             frames[l_count]['header']['service_name']) > 0 else