well-log-toolkit 0.1.135__py3-none-any.whl → 0.1.136__py3-none-any.whl

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/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]:
     """

{well_log_toolkit-0.1.135.dist-info → well_log_toolkit-0.1.136.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: well-log-toolkit
-Version: 0.1.135
+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.135.dist-info → well_log_toolkit-0.1.136.dist-info}/RECORD

@@ -4,12 +4,12 @@ well_log_toolkit/las_file.py,sha256=Tj0mRfX1aX2s6uug7BBlY1m_mu3G50EGxHGzD0eEedE,
 well_log_toolkit/manager.py,sha256=PuHF8rqypirNIN77STHcvg8WneExikpq6ZvkcRbcQpg,109776
 well_log_toolkit/operations.py,sha256=z8j8fGBOwoJGUQFy-Vawjq9nm3OD_dUt0oaNh8yuG7o,18515
 well_log_toolkit/property.py,sha256=B-3mXNJmvIqjjMdsu1kgVSwMgEwbJ36wn_n_oppdJFw,76769
-well_log_toolkit/regression.py,sha256=7D3oI-1XVlFb-mOoHTxTTtUHERFyvQSBAzJzAGVoZnk,25192
+well_log_toolkit/regression.py,sha256=JDcRxaODJnFikAdPJyTq8eUV7iY0vCDmvnGufqlojxs,31625
 well_log_toolkit/statistics.py,sha256=_huPMbv2H3o9ezunjEM94mJknX5wPK8V4nDv2lIZZRw,16814
 well_log_toolkit/utils.py,sha256=O2KPq4htIoUlL74V2zKftdqqTjRfezU9M-568zPLme0,6866
-well_log_toolkit/visualization.py,sha256=vnO8QjSNvvnQHGKXpe7BsLaQ0CMdLr0ruBt7poD-8Mc,199727
+well_log_toolkit/visualization.py,sha256=HsTpd4UQCbu6pluVJ3AD9WWRg5mue8XGnlNhJUVIhF8,202585
 well_log_toolkit/well.py,sha256=Aav5Y-rui8YsJdvk7BFndNPUu1O9mcjwDApAGyqV9kw,104535
-well_log_toolkit-0.1.135.dist-info/METADATA,sha256=q39tCQUCWVP2XaMzNgtega97YSMCukEnIgSnodrCxfI,59810
-well_log_toolkit-0.1.135.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-well_log_toolkit-0.1.135.dist-info/top_level.txt,sha256=BMOo7OKLcZEnjo0wOLMclwzwTbYKYh31I8RGDOGSBdE,17
-well_log_toolkit-0.1.135.dist-info/RECORD,,
+well_log_toolkit-0.1.136.dist-info/METADATA,sha256=AzJXzMRdRNY-AF61SUz-BBdxWrXNGaPd_8eyzozMX6w,59810
+well_log_toolkit-0.1.136.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+well_log_toolkit-0.1.136.dist-info/top_level.txt,sha256=BMOo7OKLcZEnjo0wOLMclwzwTbYKYh31I8RGDOGSBdE,17
+well_log_toolkit-0.1.136.dist-info/RECORD,,