well-log-toolkit 0.1.134__tar.gz → 0.1.136__tar.gz

{well_log_toolkit-0.1.134 → well_log_toolkit-0.1.136}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: well-log-toolkit
-Version: 0.1.134
+Version: 0.1.136
 Summary: Fast LAS file processing with lazy loading and filtering for well log analysis
 Author-email: Kristian dF Kollsgård <kkollsg@gmail.com>
 License: MIT

{well_log_toolkit-0.1.134 → well_log_toolkit-0.1.136}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "well-log-toolkit"
-version = "0.1.134"
+version = "0.1.136"
 description = "Fast LAS file processing with lazy loading and filtering for well log analysis"
 readme = "README.md"
 requires-python = ">=3.9"

{well_log_toolkit-0.1.134 → well_log_toolkit-0.1.136}/well_log_toolkit/regression.py

@@ -757,11 +757,182 @@ class PowerRegression(RegressionBase):
         return f"y = {self.a:.4f}*x^{self.b:.4f}"
 
 
+class PolynomialExponentialRegression(RegressionBase):
+    """Polynomial-Exponential regression: y = 10^(a + b*x + c*x² + ... + n*x^degree)
+
+    This is an exponential function with a polynomial in the exponent.
+    Equivalent to: log₁₀(y) = a + b*x + c*x² + ... + n*x^degree
+
+    This form is particularly useful for petrophysical relationships like
+    porosity-permeability where data spans orders of magnitude and the
+    relationship has curvature in log-space.
+
+    Note: Only valid for positive y values.
+
+    Example:
+        >>> # Quadratic exponential (default degree=2)
+        >>> reg = PolynomialExponentialRegression(degree=2)
+        >>> reg.fit([0.1, 0.15, 0.2, 0.25], [0.1, 1.0, 10.0, 50.0])
+        >>> reg.predict([0.3])
+        array([150.])
+        >>> print(reg.equation())
+        y = 10^(-2.5694 + 25.2696*x - 21.0434*x²)
+
+        # Linear exponential (degree=1, same as exponential but base 10)
+        >>> reg = PolynomialExponentialRegression(degree=1)
+        >>> reg.fit(x, y)
+
+        # Lock specific coefficients
+        >>> reg = PolynomialExponentialRegression(degree=2, locked_params={'c0': 0.0})
+        >>> reg.fit(x, y)  # Forces constant term to 0
+    """
+
+    def __init__(self, degree: int = 2, locked_params: Optional[Dict[str, float]] = None):
+        """Initialize polynomial-exponential regression.
+
+        Args:
+            degree: Polynomial degree in the exponent (default: 2 for quadratic)
+            locked_params: Dictionary to lock coefficients. Keys: 'c0', 'c1', ..., 'c{degree}'
+                          where c0 is the constant term, c1 is the linear coefficient, etc.
+        """
+        super().__init__(locked_params)
+        if degree < 1:
+            raise ValueError("Polynomial degree must be at least 1")
+        self.degree = degree
+        self.coefficients: Optional[np.ndarray] = None
+
+    def fit(self, x: ArrayLike, y: ArrayLike) -> 'PolynomialExponentialRegression':
+        """Fit polynomial-exponential regression model.
+
+        Args:
+            x: Independent variable values
+            y: Dependent variable values (must be positive)
+
+        Returns:
+            Self for method chaining
+        """
+        x_clean, y_clean = self._prepare_data(x, y)
+
+        # Check for positive y values
+        if np.any(y_clean <= 0):
+            raise ValueError("Polynomial-Exponential regression requires all y values to be positive")
+
+        # Transform to polynomial: log₁₀(y) = a + b*x + c*x² + ...
+        log_y = np.log10(y_clean)
+
+        # Check for locked coefficients
+        locked_indices = {int(k[1:]): v for k, v in self._locked_params.items() if k.startswith('c')}
+
+        if not locked_indices:
+            # No locked coefficients - use standard polyfit
+            # Note: polyfit returns coefficients from highest to lowest degree
+            # We need to reverse to get [constant, linear, quadratic, ...]
+            self.coefficients = np.polyfit(x_clean, log_y, self.degree)[::-1]
+        else:
+            # Initialize coefficients array [c0, c1, c2, ...]
+            self.coefficients = np.zeros(self.degree + 1)
+
+            # Set locked coefficients
+            for idx, val in locked_indices.items():
+                if idx < 0 or idx > self.degree:
+                    raise ValueError(f"Coefficient index c{idx} out of range for degree {self.degree}")
+                self.coefficients[idx] = val
+
+            # Subtract contribution of locked coefficients from log(y)
+            log_y_adjusted = log_y.copy()
+            for idx, val in locked_indices.items():
+                log_y_adjusted -= val * (x_clean ** idx)
+
+            # Fit only unlocked coefficients
+            unlocked_indices = [i for i in range(self.degree + 1) if i not in locked_indices]
+
+            if unlocked_indices:
+                # Build design matrix for unlocked terms
+                X = np.column_stack([x_clean ** i for i in unlocked_indices])
+
+                # Solve least squares
+                coefs_unlocked = np.linalg.lstsq(X, log_y_adjusted, rcond=None)[0]
+
+                # Assign unlocked coefficients
+                for i, idx in enumerate(unlocked_indices):
+                    self.coefficients[idx] = coefs_unlocked[i]
+
+        # Calculate metrics (in log space for better R² with data spanning orders of magnitude)
+        log_y_pred = np.sum([self.coefficients[i] * (x_clean ** i) for i in range(self.degree + 1)], axis=0)
+        y_pred = 10 ** log_y_pred
+        self._calculate_metrics(x_clean, y_clean, y_pred, use_log_space=True)
+
+        self.fitted = True
+        return self
+
+    def predict(self, x: ArrayLike) -> np.ndarray:
+        """Predict y values using polynomial-exponential model.
+
+        Args:
+            x: Independent variable values
+
+        Returns:
+            Predicted y values
+        """
+        if not self.fitted:
+            raise ValueError("Model must be fitted before prediction. Call fit() first.")
+
+        x = np.asarray(x, dtype=float)
+
+        # Calculate polynomial in exponent
+        log_y = np.sum([self.coefficients[i] * (x ** i) for i in range(self.degree + 1)], axis=0)
+
+        # Return 10^(polynomial)
+        return 10 ** log_y
+
+    def equation(self) -> str:
+        """Return the polynomial-exponential equation as a string."""
+        if not self.fitted:
+            return "Model not fitted"
+
+        # Build polynomial terms
+        terms = []
+        for i, coef in enumerate(self.coefficients):
+            if abs(coef) < 1e-10:  # Skip near-zero coefficients
+                continue
+
+            # Format coefficient
+            if not terms:  # First term
+                coef_str = f"{coef:.4f}"
+            else:
+                sign = "+" if coef >= 0 else "-"
+                coef_str = f"{sign} {abs(coef):.4f}"
+
+            # Format power
+            if i == 0:
+                term = coef_str
+            elif i == 1:
+                term = f"{coef_str}*x"
+            elif i == 2:
+                term = f"{coef_str}*x²"
+            elif i == 3:
+                term = f"{coef_str}*x³"
+            else:
+                term = f"{coef_str}*x^{i}"
+
+            terms.append(term)
+
+        if not terms:
+            return "y = 10^(0)"
+
+        poly_str = "".join(terms).strip()
+        # Clean up leading plus sign
+        poly_str = poly_str.replace("+ -", "- ")
+
+        return f"y = 10^({poly_str})"
+
+
 __all__ = [
     'RegressionBase',
     'LinearRegression',
     'LogarithmicRegression',
     'ExponentialRegression',
     'PolynomialRegression',
-    'PowerRegression'
+    'PowerRegression',
+    'PolynomialExponentialRegression'
 ]

{well_log_toolkit-0.1.134 → well_log_toolkit-0.1.136}/well_log_toolkit/visualization.py

@@ -23,7 +23,7 @@ if TYPE_CHECKING:
 # Import regression classes at module level for performance
 from .regression import (
     LinearRegression, LogarithmicRegression, ExponentialRegression,
-    PolynomialRegression, PowerRegression
+    PolynomialRegression, PowerRegression, PolynomialExponentialRegression
 )
 from .exceptions import PropertyNotFoundError
 
@@ -38,30 +38,96 @@ def _create_regression(regression_type: str, **kwargs):
     """Factory function to create regression objects efficiently.
 
     Args:
-        regression_type: Type of regression (linear, polynomial, etc.)
-        **kwargs: Additional parameters (e.g., degree for polynomial)
+        regression_type: Type of regression with optional degree suffix
+                        Examples: 'linear', 'polynomial', 'polynomial_3', 'exponential-polynomial_4'
+        **kwargs: Additional parameters (deprecated, use suffix notation instead)
 
     Returns:
         Regression object instance
     """
     regression_type = regression_type.lower()
+
+    # Parse degree suffix (e.g., polynomial_3 → degree=3)
+    degree = None
+    if "_" in regression_type:
+        parts = regression_type.split("_")
+        try:
+            degree = int(parts[-1])
+            regression_type = "_".join(parts[:-1])  # Remove degree suffix
+        except ValueError:
+            pass  # Not a degree suffix, keep original
+
+    # Simple regression types
     if regression_type == "linear":
         return LinearRegression()
     elif regression_type == "logarithmic":
         return LogarithmicRegression()
     elif regression_type == "exponential":
         return ExponentialRegression()
-    elif regression_type == "polynomial":
-        degree = kwargs.get('degree', 2)
-        return PolynomialRegression(degree=degree)
     elif regression_type == "power":
         return PowerRegression()
+
+    # Polynomial with degree
+    elif regression_type == "polynomial":
+        # Use suffix degree, then kwargs, then default
+        if degree is None:
+            degree = kwargs.get('degree', 2)
+        return PolynomialRegression(degree=degree)
+
+    # Exponential-polynomial (renamed from polynomial-exponential)
+    elif regression_type == "exponential-polynomial":
+        if degree is None:
+            degree = kwargs.get('degree', 2)
+        return PolynomialExponentialRegression(degree=degree)
+
+    # Backward compatibility: old name polynomial-exponential
+    elif regression_type == "polynomial-exponential":
+        import warnings
+        warnings.warn(
+            "'polynomial-exponential' is deprecated. Use 'exponential-polynomial' instead.",
+            DeprecationWarning,
+            stacklevel=3
+        )
+        if degree is None:
+            degree = kwargs.get('degree', 2)
+        return PolynomialExponentialRegression(degree=degree)
+
     else:
-        raise ValueError(
-            f"Unknown regression type: {regression_type}. "
-            f"Choose from: linear, logarithmic, exponential, polynomial, power"
+        # Create detailed error message with equation formats
+        error_msg = (
+            f"Unknown regression type: '{regression_type}'. "
+            f"Available types:\n\n"
+            f"  • linear:                 y = a*x + b\n"
+            f"  • logarithmic:            y = a*ln(x) + b\n"
+            f"  • exponential:            y = a*e^(b*x)\n"
+            f"  • polynomial:             y = a + b*x + c*x² (default: degree=2)\n"
+            f"    - polynomial_1:         y = a + b*x (1st degree)\n"
+            f"    - polynomial_3:         y = a + b*x + c*x² + d*x³ (3rd degree)\n"
+            f"  • exponential-polynomial: y = 10^(a + b*x + c*x²) (default: degree=2)\n"
+            f"    - exponential-polynomial_1: y = 10^(a + b*x) (1st degree)\n"
+            f"    - exponential-polynomial_3: y = 10^(a + b*x + c*x² + d*x³) (3rd degree)\n"
+            f"  • power:                  y = a*x^b\n\n"
+            f"Did you mean one of these?"
         )
 
+        # Check for common typos
+        suggestions = []
+        if "expo" in regression_type or "exp" in regression_type:
+            suggestions.append("exponential or exponential-polynomial")
+        if "poly" in regression_type:
+            suggestions.append("polynomial or exponential-polynomial")
+        if "log" in regression_type:
+            suggestions.append("logarithmic")
+        if "lin" in regression_type:
+            suggestions.append("linear")
+        if "pow" in regression_type:
+            suggestions.append("power")
+
+        if suggestions:
+            error_msg += f"\n  Possible matches: {', '.join(suggestions)}"
+
+        raise ValueError(error_msg)
+
 
 def _downsample_for_plotting(depth: np.ndarray, values: np.ndarray, max_points: int = 2000) -> tuple[np.ndarray, np.ndarray]:
     """
@@ -3475,22 +3541,48 @@ class Crossplot:
         Returns:
             Tuple of (segment_number, matplotlib_location_string)
         """
-        # Get x and y bounds
+        # Get x and y data values
         x_vals = data['x'].values
         y_vals = data['y'].values
 
-        # Handle log scales for binning
+        # Get axes limits to convert data coordinates to axes-normalized coordinates (0-1)
+        # This ensures we're dividing the GRAPH AREA, not the data space
+        if self.ax is not None:
+            x_lim = self.ax.get_xlim()
+            y_lim = self.ax.get_ylim()
+        else:
+            # Fallback if ax not available yet
+            x_lim = (np.nanmin(x_vals), np.nanmax(x_vals))
+            y_lim = (np.nanmin(y_vals), np.nanmax(y_vals))
+
+        # Handle logarithmic axes - transform to log space for proper visual segment calculation
+        # On log axes, equal visual spacing corresponds to equal ratios, not equal differences
         if self.x_log:
-            x_vals = np.log10(x_vals[x_vals > 0])
+            # Filter out non-positive values before log transform
+            x_valid = x_vals > 0
+            x_vals_transformed = np.where(x_valid, np.log10(x_vals), np.nan)
+            x_lim_transformed = (np.log10(max(x_lim[0], 1e-10)), np.log10(max(x_lim[1], 1e-10)))
+        else:
+            x_vals_transformed = x_vals
+            x_lim_transformed = x_lim
+
         if self.y_log:
-            y_vals = np.log10(y_vals[y_vals > 0])
+            # Filter out non-positive values before log transform
+            y_valid = y_vals > 0
+            y_vals_transformed = np.where(y_valid, np.log10(y_vals), np.nan)
+            y_lim_transformed = (np.log10(max(y_lim[0], 1e-10)), np.log10(max(y_lim[1], 1e-10)))
+        else:
+            y_vals_transformed = y_vals
+            y_lim_transformed = y_lim
 
-        x_min, x_max = np.nanmin(x_vals), np.nanmax(x_vals)
-        y_min, y_max = np.nanmin(y_vals), np.nanmax(y_vals)
+        # Normalize transformed coordinates to axes coordinates (0-1)
+        # This divides the visible graph area properly, accounting for log scales
+        x_norm = (x_vals_transformed - x_lim_transformed[0]) / (x_lim_transformed[1] - x_lim_transformed[0])
+        y_norm = (y_vals_transformed - y_lim_transformed[0]) / (y_lim_transformed[1] - y_lim_transformed[0])
 
-        # Create 3x3 grid and count points in each square
-        x_bins = np.linspace(x_min, x_max, 4)
-        y_bins = np.linspace(y_min, y_max, 4)
+        # Create 3x3 grid in axes-normalized space (0-1)
+        x_bins = np.linspace(0, 1, 4)
+        y_bins = np.linspace(0, 1, 4)
 
         # Map segments 1-9 to grid positions (i, j)
         # Segment numbering:
@@ -3522,12 +3614,12 @@ class Crossplot:
             9: 'lower right',
         }
 
-        # Count points in each segment
-        total_points = len(x_vals)
+        # Count points in each segment using normalized coordinates
+        total_points = len(x_norm)
         segment_counts = {}
         for segment, (i, j) in segment_to_grid.items():
-            x_mask = (x_vals >= x_bins[i]) & (x_vals < x_bins[i+1])
-            y_mask = (y_vals >= y_bins[j]) & (y_vals < y_bins[j+1])
+            x_mask = (x_norm >= x_bins[i]) & (x_norm < x_bins[i+1])
+            y_mask = (y_norm >= y_bins[j]) & (y_norm < y_bins[j+1])
             count = np.sum(x_mask & y_mask)
             segment_counts[segment] = count
 
@@ -3638,20 +3730,24 @@ class Crossplot:
         is_edge = self._is_edge_location(location)
 
         # Determine base anchor point from location string
-        # Map location to (x, y) coordinates in figure space
+        # Map location to (x, y) coordinates in AXES space (0-1 within the graph area)
+        # These match the segment corners:
+        # Segment 1=upper left (0,1), 2=upper center (0.5,1), 3=upper right (1,1)
+        # Segment 4=center left (0,0.5), 5=center (0.5,0.5), 6=center right (1,0.5)
+        # Segment 7=lower left (0,0), 8=lower center (0.5,0), 9=lower right (1,0)
         anchor_map = {
-            'upper left': (0.02, 0.98),
-            'upper center': (0.5, 0.98),
-            'upper right': (0.98, 0.98),
-            'center left': (0.02, 0.5),
+            'upper left': (0, 1),
+            'upper center': (0.5, 1),
+            'upper right': (1, 1),
+            'center left': (0, 0.5),
             'center': (0.5, 0.5),
-            'center right': (0.98, 0.5),
-            'lower left': (0.02, 0.02),
-            'lower center': (0.5, 0.02),
-            'lower right': (0.98, 0.02),
+            'center right': (1, 0.5),
+            'lower left': (0, 0),
+            'lower center': (0.5, 0),
+            'lower right': (1, 0),
         }
 
-        base_x, base_y = anchor_map.get(location, (0.98, 0.98))
+        base_x, base_y = anchor_map.get(location, (1, 1))
 
         if is_edge:
             # Stack vertically on edges
@@ -3664,23 +3760,23 @@ class Crossplot:
                 framealpha=0.9,
                 edgecolor='black',
                 bbox_to_anchor=(base_x, base_y),
-                bbox_transform=self.fig.transFigure
+                bbox_transform=self.ax.transAxes
             )
             shape_legend.get_title().set_fontweight('bold')
             shape_legend.set_clip_on(False)  # Prevent clipping outside axes
             self.ax.add_artist(shape_legend)
 
             # Calculate offset for color legend below shape legend
-            # Estimate shape legend height and add spacing
-            shape_height = len(shape_handles) * 0.025 + 0.05  # Rough estimate
+            # Estimate shape legend height in axes coordinates
+            shape_height = len(shape_handles) * 0.05 + 0.08  # Adjusted for axes space
 
             # Adjust y position for color legend
             if 'upper' in location:
-                color_y = base_y - shape_height - 0.02  # Stack below
+                color_y = base_y - shape_height  # Stack below
             elif 'lower' in location:
-                color_y = base_y + shape_height + 0.02  # Stack above
+                color_y = base_y + shape_height  # Stack above
             else:  # center
-                color_y = base_y - shape_height / 2 - 0.01  # Stack below
+                color_y = base_y - shape_height / 2  # Stack below
 
             color_legend = self.ax.legend(
                 handles=color_handles,
@@ -3690,19 +3786,19 @@ class Crossplot:
                 framealpha=0.9,
                 edgecolor='black',
                 bbox_to_anchor=(base_x, color_y),
-                bbox_transform=self.fig.transFigure
+                bbox_transform=self.ax.transAxes
             )
             color_legend.get_title().set_fontweight('bold')
             color_legend.set_clip_on(False)  # Prevent clipping outside axes
         else:
             # Place side by side for non-edge locations (top, bottom, center)
-            # Estimate width of each legend
-            legend_width = 0.15
+            # Estimate width of each legend in axes coordinates
+            legend_width = 0.20
 
             if 'center' in location and location != 'center left' and location != 'center right':
                 # For center positions, place them side by side
-                shape_x = base_x - legend_width / 2 - 0.01
-                color_x = base_x + legend_width / 2 + 0.01
+                shape_x = base_x - legend_width / 2
+                color_x = base_x + legend_width / 2
 
                 shape_legend = self.ax.legend(
                     handles=shape_handles,
@@ -3712,7 +3808,7 @@ class Crossplot:
                     framealpha=0.9,
                     edgecolor='black',
                     bbox_to_anchor=(shape_x, base_y),
-                    bbox_transform=self.fig.transFigure
+                    bbox_transform=self.ax.transAxes
                 )
                 shape_legend.get_title().set_fontweight('bold')
                 shape_legend.set_clip_on(False)  # Prevent clipping outside axes
@@ -3726,7 +3822,7 @@ class Crossplot:
                     framealpha=0.9,
                     edgecolor='black',
                     bbox_to_anchor=(color_x, base_y),
-                    bbox_transform=self.fig.transFigure
+                    bbox_transform=self.ax.transAxes
                 )
                 color_legend.get_title().set_fontweight('bold')
                 color_legend.set_clip_on(False)  # Prevent clipping outside axes
@@ -3738,18 +3834,20 @@ class Crossplot:
                     loc=location,
                     frameon=True,
                     framealpha=0.9,
-                    edgecolor='black'
+                    edgecolor='black',
+                    bbox_to_anchor=(base_x, base_y),
+                    bbox_transform=self.ax.transAxes
                 )
                 shape_legend.get_title().set_fontweight('bold')
                 shape_legend.set_clip_on(False)  # Prevent clipping outside axes
                 self.ax.add_artist(shape_legend)
 
-                # Estimate offset
-                shape_height = len(shape_handles) * 0.025 + 0.05
+                # Estimate offset in axes coordinates
+                shape_height = len(shape_handles) * 0.05 + 0.08
                 if 'upper' in location:
-                    color_y = base_y - shape_height - 0.02
+                    color_y = base_y - shape_height
                 else:
-                    color_y = base_y + shape_height + 0.02
+                    color_y = base_y + shape_height
 
                 color_legend = self.ax.legend(
                     handles=color_handles,
@@ -3759,7 +3857,7 @@ class Crossplot:
                     framealpha=0.9,
                     edgecolor='black',
                     bbox_to_anchor=(base_x, color_y),
-                    bbox_transform=self.fig.transFigure
+                    bbox_transform=self.ax.transAxes
                 )
                 color_legend.get_title().set_fontweight('bold')
                 color_legend.set_clip_on(False)  # Prevent clipping outside axes
@@ -3837,14 +3935,32 @@ class Crossplot:
                 secondary_loc = 'lower right'
 
             # Determine descriptive title based on regression type
+            # Extract the regression type and add it to the title
+            reg_type_str = None
             if self.regression_by_color_and_shape:
-                regression_title = 'Regressions by color and shape'
+                base_title = 'Regressions by color and shape'
+                config = self._parse_regression_config(self.regression_by_color_and_shape)
+                reg_type_str = config.get('type', None)
             elif self.regression_by_color:
-                regression_title = 'Regressions by color'
+                base_title = 'Regressions by color'
+                config = self._parse_regression_config(self.regression_by_color)
+                reg_type_str = config.get('type', None)
             elif self.regression_by_group:
-                regression_title = 'Regressions by group'
+                base_title = 'Regressions by group'
+                config = self._parse_regression_config(self.regression_by_group)
+                reg_type_str = config.get('type', None)
             else:
-                regression_title = 'Regressions'
+                base_title = 'Regressions'
+                if self.regression:
+                    config = self._parse_regression_config(self.regression)
+                    reg_type_str = config.get('type', None)
+
+            # Add regression type to title (e.g., "Regressions by color - Power")
+            if reg_type_str:
+                reg_type_display = reg_type_str.capitalize()
+                regression_title = f"{base_title} - {reg_type_display}"
+            else:
+                regression_title = base_title
 
             # Import legend from matplotlib
             from matplotlib.legend import Legend
@@ -4284,11 +4400,15 @@ class Crossplot:
         if self.y_log:
             self.ax.set_yscale('log')
 
-        # Disable scientific notation on axes
+        # Disable scientific notation on linear axes only
+        # (log axes use matplotlib's default log formatter for proper log scale labels)
         from matplotlib.ticker import ScalarFormatter
         formatter = ScalarFormatter(useOffset=False)
         formatter.set_scientific(False)
-        self.ax.yaxis.set_major_formatter(formatter)
+
+        # Only apply to linear axes - log axes need their default formatter
+        if not self.y_log:
+            self.ax.yaxis.set_major_formatter(formatter)
         if not self.x_log:
             self.ax.xaxis.set_major_formatter(formatter)
 

{well_log_toolkit-0.1.134 → well_log_toolkit-0.1.136}/well_log_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: well-log-toolkit
-Version: 0.1.134
+Version: 0.1.136
 Summary: Fast LAS file processing with lazy loading and filtering for well log analysis
 Author-email: Kristian dF Kollsgård <kkollsg@gmail.com>
 License: MIT