decline-curve 0.1.2__tar.gz

decline_curve-0.1.2/LICENSE

@@ -0,0 +1 @@
+Apache License 2.0

decline_curve-0.1.2/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: decline_curve
+Version: 0.1.2
+Summary: Decline curve analysis for oil well production using with Arps and LLM-based models
+Author: Kyle T. Jones
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: tqdm>=4.66
+Requires-Dist: transformers>=4.41
+Requires-Dist: torch>=2.0
+Requires-Dist: accelerate>=0.29
+Requires-Dist: einops>=0.7
+Requires-Dist: pmdarima>=2.0
+Requires-Dist: numpy-financial>=1.0
+Requires-Dist: requests>=2.25
+Requires-Dist: xlrd>=2.0
+Dynamic: license-file
+
+# Decline Analysis
+
+A Python package for decline curve analysis of oil well production using Arps models and LLM-based forecasting methods.
+
+## Features
+
+- Traditional Arps decline curve analysis (exponential, hyperbolic, harmonic)
+- Advanced forecasting with machine learning models (ARIMA, Chronos, TimesFM)
+- Economic analysis and reserves estimation
+- Sensitivity analysis capabilities
+- Data visualization and plotting tools
+
+## Installation
+
+```bash
+pip install decline-analysis
+```
+
+## Usage
+
+```python
+from decline_analysis import dca
+
+# Load your production data
+# Run decline curve analysis
+# Generate forecasts and economic metrics
+```
+
+## Development
+
+Install in development mode:
+
+```bash
+pip install -e .
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## License
+
+Apache-2.0

decline_curve-0.1.2/README.md

@@ -0,0 +1,45 @@
+# Decline Analysis
+
+A Python package for decline curve analysis of oil well production using Arps models and LLM-based forecasting methods.
+
+## Features
+
+- Traditional Arps decline curve analysis (exponential, hyperbolic, harmonic)
+- Advanced forecasting with machine learning models (ARIMA, Chronos, TimesFM)
+- Economic analysis and reserves estimation
+- Sensitivity analysis capabilities
+- Data visualization and plotting tools
+
+## Installation
+
+```bash
+pip install decline-analysis
+```
+
+## Usage
+
+```python
+from decline_analysis import dca
+
+# Load your production data
+# Run decline curve analysis
+# Generate forecasts and economic metrics
+```
+
+## Development
+
+Install in development mode:
+
+```bash
+pip install -e .
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## License
+
+Apache-2.0

decline_curve-0.1.2/decline_analysis/__init__.py

@@ -0,0 +1 @@
+from . import dca

decline_curve-0.1.2/decline_analysis/__main__.py

@@ -0,0 +1,51 @@
+import argparse
+
+import pandas as pd
+
+from . import dca
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Decline curve forecast tool")
+    parser.add_argument("csv", help="Input CSV file")
+    parser.add_argument(
+        "--model", default="arps", choices=["arps", "timesfm", "chronos"]
+    )
+    parser.add_argument(
+        "--kind",
+        default="hyperbolic",
+        choices=["exponential", "harmonic", "hyperbolic"],
+    )
+    parser.add_argument("--horizon", type=int, default=12)
+    parser.add_argument("--well", help="Well ID to forecast")
+    parser.add_argument("--benchmark", action="store_true")
+    parser.add_argument("--top_n", type=int, default=10)
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    df = pd.read_csv(args.csv)
+
+    if args.benchmark:
+        result = dca.benchmark(
+            df,
+            model=args.model,
+            kind=args.kind,
+            horizon=args.horizon,
+            top_n=args.top_n,
+            verbose=args.verbose,
+        )
+        print(result.to_string(index=False))
+    else:
+        if args.well is None:
+            raise ValueError("Must provide --well when not using --benchmark")
+        sub = df[df["well_id"] == args.well].copy()
+        sub["date"] = pd.to_datetime(sub["date"])
+        y = sub.set_index("date")["oil_bbl"].asfreq("MS")
+        yhat = dca.forecast(
+            y,
+            model=args.model,
+            kind=args.kind,
+            horizon=args.horizon,
+            verbose=args.verbose,
+        )
+        dca.plot(y, yhat, title=f"{args.well} {args.model}")

decline_curve-0.1.2/decline_analysis/data.py

@@ -0,0 +1,100 @@
+from pathlib import Path
+from typing import List, Optional
+
+import pandas as pd
+
+
+def load_production_csvs(
+    paths: List[str],
+    date_col: str = "date",
+    well_id_col: str = "well_id",
+    oil_col: str = "oil_bbl",
+) -> pd.DataFrame:
+    """Load and stack well-level production CSV files.
+
+    Args:
+        paths: List of CSV paths.
+        date_col: Name of the date column.
+        well_id_col: Name of the well id column.
+        oil_col: Name of the oil volume column.
+
+    Returns:
+        A DataFrame with [date, well_id, oil_bbl] and a DateTimeIndex.
+    """
+    frames = []
+    for p in paths:
+        df = pd.read_csv(p)
+        _assert_cols(df, [date_col, well_id_col, oil_col])
+        df[date_col] = pd.to_datetime(df[date_col])
+        frames.append(df[[date_col, well_id_col, oil_col]])
+    out = pd.concat(frames, ignore_index=True)
+    out = out.sort_values([well_id_col, date_col])
+    out = out.rename(
+        columns={date_col: "date", well_id_col: "well_id", oil_col: "oil_bbl"}
+    )
+    return out.set_index("date")
+
+
+def to_monthly(
+    df: pd.DataFrame, well_id_col: str = "well_id", oil_col: str = "oil_bbl"
+) -> pd.DataFrame:
+    """Aggregate to monthly frequency.
+
+    Args:
+        df: A DataFrame indexed by date.
+        well_id_col: Well id column.
+        oil_col: Oil volume column.
+
+    Returns:
+        A monthly panel by well.
+    """
+    return (
+        df.groupby(well_id_col)
+        .resample("M")[oil_col]
+        .sum()
+        .reset_index()
+        .set_index("date")
+    )
+
+
+def make_panel(df: pd.DataFrame, first_n_months: Optional[int] = None) -> pd.DataFrame:
+    """Create a relative-time panel for decline fitting.
+
+    Args:
+        df: Monthly panel with index date and columns well_id and oil_bbl.
+        first_n_months: Truncate each well to N months from first production.
+
+    Returns:
+        A panel with cycle (t) per well.
+    """
+    df = df.sort_values(["well_id", "date"]).copy()
+    df["t"] = df.groupby("well_id").cumcount()
+    if first_n_months is not None:
+        df = df[df["t"] < first_n_months]
+    return df
+
+
+def load_price_csv(
+    path: str, date_col: str = "date", price_col: str = "price"
+) -> pd.DataFrame:
+    """Load oil price CSV.
+
+    Args:
+        path: Path to price CSV.
+        date_col: Date column name.
+        price_col: Price column name.
+
+    Returns:
+        A DataFrame indexed by date with a single price column.
+    """
+    df = pd.read_csv(path)
+    _assert_cols(df, [date_col, price_col])
+    df[date_col] = pd.to_datetime(df[date_col])
+    df = df.rename(columns={date_col: "date", price_col: "price"}).set_index("date")
+    return df.sort_index()
+
+
+def _assert_cols(df: pd.DataFrame, cols: List[str]) -> None:
+    missing = [c for c in cols if c not in df.columns]
+    if missing:
+        raise ValueError(f"Missing columns: {missing}")

decline_curve-0.1.2/decline_analysis/dca.py

@@ -0,0 +1,164 @@
+from typing import Dict, List, Literal, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from .economics import economic_metrics
+from .evaluate import mae, rmse, smape
+from .forecast import Forecaster
+from .models import ArpsParams
+from .plot import plot_forecast
+from .reserves import forecast_and_reserves
+from .sensitivity import run_sensitivity
+from .utils.data_loader import scrape_ndic
+
+
+def forecast(
+    series: pd.Series,
+    model: Literal["arps", "timesfm", "chronos", "arima"] = "arps",
+    kind: Optional[Literal["exponential", "harmonic", "hyperbolic"]] = "hyperbolic",
+    horizon: int = 12,
+    verbose: bool = False,
+) -> pd.Series:
+    fc = Forecaster(series)
+    result = fc.forecast(model=model, kind=kind, horizon=horizon)
+    if verbose:
+        print(f"Forecast model: {model}, horizon: {horizon}")
+        print(result.head())
+    return result
+
+
+def evaluate(y_true: pd.Series, y_pred: pd.Series) -> dict:
+    common = y_true.index.intersection(y_pred.index)
+    yt = y_true.loc[common]
+    yp = y_pred.loc[common]
+    return {
+        "rmse": rmse(yt, yp),
+        "mae": mae(yt, yp),
+        "smape": smape(yt, yp),
+    }
+
+
+def plot(
+    y: pd.Series,
+    yhat: pd.Series,
+    title: str = "Forecast",
+    filename: Optional[str] = None,
+):
+    plot_forecast(y, yhat, title, filename)
+
+
+def benchmark(
+    df: pd.DataFrame,
+    model: Literal["arps", "timesfm", "chronos", "arima"] = "arps",
+    kind: Optional[str] = "hyperbolic",
+    horizon: int = 12,
+    well_col: str = "well_id",
+    date_col: str = "date",
+    value_col: str = "oil_bbl",
+    top_n: int = 10,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    out = []
+    wells = df[well_col].unique()[:top_n]
+    for wid in wells:
+        wdf = df[df[well_col] == wid].copy()
+        wdf = wdf[[date_col, value_col]].dropna()
+        wdf[date_col] = pd.to_datetime(wdf[date_col])
+        wdf = wdf.set_index(date_col).asfreq("MS")
+        if len(wdf) < 24:
+            continue
+        try:
+            y = wdf[value_col]
+            yhat = forecast(y, model=model, kind=kind, horizon=horizon)
+            metrics = evaluate(y, yhat)
+            metrics[well_col] = wid
+            out.append(metrics)
+            if verbose:
+                print(f"{wid}: {metrics}")
+        except Exception as e:
+            if verbose:
+                print(f"{wid} failed: {e}")
+            continue
+    return pd.DataFrame(out)
+
+
+def sensitivity_analysis(
+    param_grid: List[Tuple[float, float, float]],
+    prices: List[float],
+    opex: float,
+    discount_rate: float = 0.10,
+    t_max: float = 240,
+    econ_limit: float = 10.0,
+    dt: float = 1.0,
+) -> pd.DataFrame:
+    """
+    Run sensitivity analysis across Arps parameters and oil/gas prices.
+
+    Args:
+        param_grid: List of (qi, di, b) tuples to test
+        prices: List of oil/gas prices to test
+        opex: Operating cost per unit
+        discount_rate: Annual discount rate (default 0.10)
+        t_max: Time horizon in months (default 240)
+        econ_limit: Minimum economic production rate (default 10.0)
+        dt: Time step in months (default 1.0)
+
+    Returns:
+        DataFrame with sensitivity results including EUR, NPV, and payback
+    """
+    return run_sensitivity(
+        param_grid, prices, opex, discount_rate, t_max, econ_limit, dt
+    )
+
+
+def economics(
+    production: pd.Series, price: float, opex: float, discount_rate: float = 0.10
+) -> Dict:
+    """
+    Calculate economic metrics from production forecast.
+
+    Args:
+        production: Monthly production forecast
+        price: Unit price ($/bbl or $/mcf)
+        opex: Operating cost per unit
+        discount_rate: Annual discount rate (default 0.10)
+
+    Returns:
+        Dictionary with NPV, cash flow, and payback period
+    """
+    return economic_metrics(production.values, price, opex, discount_rate)
+
+
+def reserves(
+    params: ArpsParams, t_max: float = 240, dt: float = 1.0, econ_limit: float = 10.0
+) -> Dict:
+    """
+    Generate production forecast and compute EUR (Estimated Ultimate Recovery).
+
+    Args:
+        params: Arps decline parameters (qi, di, b)
+        t_max: Time horizon in months (default 240)
+        dt: Time step in months (default 1.0)
+        econ_limit: Minimum economic production rate (default 10.0)
+
+    Returns:
+        Dictionary with forecast, time arrays, and EUR
+    """
+    return forecast_and_reserves(params, t_max, dt, econ_limit)
+
+
+def load_ndic_data(
+    months_list: List[str], output_dir: str = "ndic_raw"
+) -> pd.DataFrame:
+    """
+    Load North Dakota Industrial Commission (NDIC) production data.
+
+    Args:
+        months_list: List of month strings (e.g., ['2023-01', '2023-02'])
+        output_dir: Directory to save raw data files (default 'ndic_raw')
+
+    Returns:
+        Combined DataFrame with production data
+    """
+    return scrape_ndic(months_list, output_dir)

decline_curve-0.1.2/decline_analysis/economics.py

@@ -0,0 +1,33 @@
+from typing import Dict
+
+import numpy as np
+from numpy_financial import npv
+
+
+def economic_metrics(
+    q: np.ndarray,
+    price: float,
+    opex: float,
+    discount_rate: float = 0.10,
+    time_step_months: float = 1.0,
+) -> Dict:
+    """
+    Calculate economics from forecasted production.
+
+    Args:
+        q: Production forecast (monthly).
+        price: Unit price.
+        opex: Operating cost.
+        discount_rate: Annual discount rate.
+        time_step_months: Length of time step in months.
+
+    Returns:
+        Dict with cash flow, NPV, payback.
+    """
+    monthly_rate = discount_rate / 12
+    net_revenue = (price - opex) * q
+    cash_flow = net_revenue
+    npv_val = npv(monthly_rate, cash_flow)
+    cum_cf = np.cumsum(cash_flow)
+    payback_month = int(np.argmax(cum_cf > 0)) if np.any(cum_cf > 0) else -1
+    return {"npv": npv_val, "cash_flow": cash_flow, "payback_month": payback_month}

decline_curve-0.1.2/decline_analysis/evaluate.py

@@ -0,0 +1,56 @@
+"""
+Evaluation metrics for decline curve analysis forecasts.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def rmse(y_true: pd.Series, y_pred: pd.Series) -> float:
+    """Root Mean Square Error."""
+    return np.sqrt(np.mean((y_true - y_pred) ** 2))
+
+
+def mae(y_true: pd.Series, y_pred: pd.Series) -> float:
+    """Mean Absolute Error."""
+    return np.mean(np.abs(y_true - y_pred))
+
+
+def smape(y_true: pd.Series, y_pred: pd.Series) -> float:
+    """Symmetric Mean Absolute Percentage Error."""
+    numerator = np.abs(y_pred - y_true)
+    denominator = (np.abs(y_true) + np.abs(y_pred)) / 2
+    return np.mean(numerator / denominator) * 100
+
+
+def mape(y_true: pd.Series, y_pred: pd.Series) -> float:
+    """Mean Absolute Percentage Error."""
+    return np.mean(np.abs((y_true - y_pred) / y_true)) * 100
+
+
+def r2_score(y_true: pd.Series, y_pred: pd.Series) -> float:
+    """R-squared coefficient of determination."""
+    ss_res = np.sum((y_true - y_pred) ** 2)
+    ss_tot = np.sum((y_true - np.mean(y_true)) ** 2)
+
+    # Handle constant values case where ss_tot = 0
+    if ss_tot == 0:
+        # If actual values are constant and predictions match, R² = 1
+        if ss_res == 0:
+            return 1.0
+        # If actual values are constant but predictions don't match, R² = 0
+        else:
+            return 0.0
+
+    return 1 - (ss_res / ss_tot)
+
+
+def evaluate_forecast(y_true: pd.Series, y_pred: pd.Series) -> dict:
+    """Comprehensive evaluation of forecast performance."""
+    return {
+        "rmse": rmse(y_true, y_pred),
+        "mae": mae(y_true, y_pred),
+        "smape": smape(y_true, y_pred),
+        "mape": mape(y_true, y_pred),
+        "r2": r2_score(y_true, y_pred),
+    }

decline_curve-0.1.2/decline_analysis/example.py

@@ -0,0 +1,9 @@
+import pandas as pd
+
+from decline_analysis import dca
+
+# Example usage - replace with your actual data
+# df = pd.read_csv("your_production_data.csv")
+# series = df[df["well_id"] == "WELL_001"].set_index("date")["oil_bbl"]
+# yhat = dca.forecast(series, model="arps", kind="hyperbolic", horizon=12)
+# dca.plot(series, yhat)

decline_curve-0.1.2/decline_analysis/forecast.py

@@ -0,0 +1,109 @@
+from typing import Literal, Optional
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from .forecast_chronos import forecast_chronos
+from .forecast_timesfm import forecast_timesfm
+from .models import fit_arps, predict_arps
+
+try:
+    from .forecast_arima import forecast_arima
+
+    ARIMA_AVAILABLE = True
+except ImportError:
+    ARIMA_AVAILABLE = False
+
+    def forecast_arima(*args, **kwargs):
+        raise ImportError("ARIMA forecasting is not available due to dependency issues")
+
+
+from .evaluate import mae, rmse, smape
+from .plot import _range_markers, tufte_style
+
+
+class Forecaster:
+    def __init__(self, series: pd.Series):
+        if not isinstance(series.index, pd.DatetimeIndex):
+            raise ValueError("Input must be indexed by datetime")
+        if not series.index.freq:
+            series = series.asfreq(pd.infer_freq(series.index))
+        self.series = series.dropna().copy()
+        self.last_forecast = None
+
+    def forecast(
+        self,
+        model: Literal["arps", "timesfm", "chronos", "arima"],
+        kind: Optional[Literal["exponential", "harmonic", "hyperbolic"]] = "hyperbolic",
+        horizon: Optional[int] = 12,
+    ) -> pd.Series:
+        if model == "arps":
+            t = np.arange(len(self.series))
+            q = self.series.to_numpy()
+            params = fit_arps(t, q, kind=kind)
+            full_t = np.arange(len(self.series) + horizon)
+            yhat = predict_arps(full_t, params)
+            idx = pd.date_range(
+                self.series.index[0], periods=len(yhat), freq=self.series.index.freq
+            )
+            forecast = pd.Series(yhat, index=idx, name=f"arps_{kind}")
+
+        elif model == "timesfm":
+            forecast = forecast_timesfm(self.series, horizon=horizon)
+
+        elif model == "chronos":
+            forecast = forecast_chronos(self.series, horizon=horizon)
+
+        elif model == "arima":
+            forecast_part = forecast_arima(self.series, horizon=horizon)
+            # Combine historical and forecast data
+            full_index = pd.date_range(
+                self.series.index[0],
+                periods=len(self.series) + horizon,
+                freq=self.series.index.freq,
+            )
+            full_forecast = pd.concat([self.series, forecast_part])
+            forecast = pd.Series(
+                full_forecast.values, index=full_index, name="arima_forecast"
+            )
+
+        else:
+            raise ValueError(f"Unknown model: {model}")
+
+        self.last_forecast = forecast
+        return forecast
+
+    def evaluate(self, actual: pd.Series) -> dict:
+        if self.last_forecast is None:
+            raise RuntimeError("Call .forecast() first.")
+        common = self.last_forecast.index.intersection(actual.index)
+        if len(common) == 0:
+            raise ValueError("No overlapping dates to compare.")
+        yhat = self.last_forecast.loc[common]
+        ytrue = actual.loc[common]
+        return {
+            "rmse": rmse(ytrue, yhat),
+            "mae": mae(ytrue, yhat),
+            "smape": smape(ytrue, yhat),
+        }
+
+    def plot(self, title: str = "Forecast", filename: Optional[str] = None):
+        if self.last_forecast is None:
+            raise RuntimeError("Call .forecast() first.")
+        tufte_style()
+        fig, ax = plt.subplots()
+        hist = self.series
+        fcst = self.last_forecast
+
+        ax.plot(hist.index, hist.values, lw=1.0, label="history")
+        ax.plot(fcst.index, fcst.values, lw=1.2, label="forecast")
+
+        _range_markers(ax, hist.values)
+        ax.set_xlabel("Date")
+        ax.set_ylabel("Production")
+        ax.set_title(title)
+        ax.legend()
+        if filename:
+            plt.savefig(filename, bbox_inches="tight")
+        plt.show()