# RESAID Package
A comprehensive collection of reservoir engineering tools for production forecasting and decline curve analysis.
## Features
- **Decline Curve Analysis (DCA)**: Arps decline curve fitting with exponential, hyperbolic, and harmonic decline models
- **Production Data Processing**: Normalization, outlier detection, and data preprocessing
- **Single-Phase Forecasting**: Traditional major phase analysis with ratio-based minor phase estimation
- **Three-Phase Forecasting**: Independent decline curve analysis for OIL, GAS, and WATER phases
- **Multiple Output Formats**: Flowstream, oneline, and typecurve generation
- **Economic Analysis**: NPV, IRR, and comprehensive cashflow modeling
- **Multi-Phase Economics**: Oil, gas, water, and NGL revenue calculations
- **Royalty & Interest Modeling**: Working interest, net revenue interest, and royalty calculations
- **Tax & Cost Modeling**: Severance taxes, ad valorem taxes, and operating costs
- **Vectorized Operations**: High-performance calculations for large datasets
## Installation
```bash
pip install resaid
```
## Quick Start
### Working Examples
The `examples/` folder contains working examples that demonstrate RESAID functionality:
- **`simple_example.py`**: Three-phase mode example generating ARIES, PhdWin, and Mosaic exports
- **`ratio_mode_example.py`**: Ratio mode example showing how to use ratios for multi-phase forecasting
Run these examples to see RESAID in action:
```bash
cd examples
python simple_example.py # Three-phase mode
python ratio_mode_example.py # Ratio mode
```
### Basic Single-Phase DCA Analysis
```python
import pandas as pd
from resaid.dca import decline_curve
# Load production data
prod_df = pd.read_csv('production_data.csv')
# Initialize DCA object
dca = decline_curve()
# Configure data columns
dca.dataframe = prod_df
dca.date_col = 'ProducingMonth'
dca.uid_col = 'API_UWI'
dca.oil_col = 'LiquidsProd_BBL'
dca.gas_col = 'GasProd_MCF'
dca.water_col = 'WaterProd_BBL'
dca.length_col = 'LateralLength_FT'
# Set analysis parameters
dca.min_h_b = 0.9
dca.max_h_b = 1.3
dca.backup_decline = True
dca.outlier_correction = False
# Run DCA analysis
dca.run_DCA()
# Generate outputs
dca.generate_oneline(num_months=1200, denormalize=True)
dca.generate_flowstream(num_months=1200, denormalize=True)
dca.generate_typecurve(num_months=1200, denormalize=True)
# Access results
oneline_results = dca.oneline_dataframe
flowstream_results = dca.flowstream_dataframe
typecurve_results = dca.typecurve
```
### Three-Phase Forecasting Mode
```python
# Enable three-phase mode
dca.three_phase_mode = True
# Run analysis (same as before)
dca.run_DCA()
# Generate outputs with independent phase analysis
dca.generate_oneline(num_months=1200, denormalize=True)
dca.generate_flowstream(num_months=1200, denormalize=True)
dca.generate_typecurve(num_months=1200, denormalize=True)
# Three-phase results include phase-specific parameters
oneline_3p = dca.oneline_dataframe
print("Phase-specific columns:", [col for col in oneline_3p.columns if col.startswith(('IPO', 'IPG', 'IPW', 'DO', 'DG', 'DW', 'BO', 'BG', 'BW'))])
```
### Ratio Mode Forecasting
```python
# Enable ratio mode for multi-phase forecasting using ratios
dca.three_phase_mode = False
# Run analysis (same as before)
dca.run_DCA()
# Generate outputs with ratio-based phase calculations
dca.generate_oneline(denormalize=True)
# Ratio mode uses MINOR_RATIO and WATER_RATIO from oneline data
# Gas production = MINOR_RATIO * OIL_QI
# Water production = WATER_RATIO * OIL_QI
# All phases use the same decline curve parameters
```
### Economic Analysis
RESAID provides comprehensive economic analysis tools for oil and gas projects, including NPV calculations, IRR analysis, and detailed cashflow modeling.
#### Basic NPV and IRR Calculations
```python
from resaid.econ import npv_calc
# Create cashflow array (negative for outflows, positive for inflows)
cashflow = np.array([-1000000, 500000, 400000, 300000, 200000])
# Initialize NPV calculator
npv = npv_calc(cashflow)
# Calculate NPV at 10% discount rate
npv_value = npv.get_npv(0.1)
print(f"NPV at 10%: ${npv_value:,.2f}")
# Calculate Internal Rate of Return
irr = npv.get_irr()
print(f"IRR: {irr:.1f}%")
```
#### Well Economics Analysis
```python
from resaid.econ import well_econ
# Initialize economics calculator
econ = well_econ(verbose=False)
# Set flowstream data (from DCA analysis)
econ.flowstreams = dca.flowstream_dataframe
econ.flowstream_uwi_col = 'UID'
econ.flowstream_t_index = 'T_INDEX'
# Set header data with well information
header_data = pd.DataFrame({
'UID': ['WELL001', 'WELL002'],
'NRI': [0.8, 0.75], # Net Revenue Interest
'WI': [1.0, 1.0], # Working Interest
'CAPEX': [2000000, 1800000] # Capital expenditure
})
econ.header_data = header_data
econ.header_uwi_col = 'UID'
econ.wi_col = 'WI'
econ.nri_col = 'NRI'
econ.capex_col = 'CAPEX'
# Set economic parameters
econ.oil_pri = 50.0 # Oil price $/bbl
econ.gas_pri = 3.0 # Gas price $/MCF
econ.discount_rate = 0.1 # 10% discount rate
# Operating costs
econ.opc_t = 1000 # Fixed operating cost $/month
econ.opc_oil = 5.0 # Variable oil cost $/bbl
econ.opc_gas = 0.5 # Variable gas cost $/MCF
econ.opc_water = 2.0 # Variable water cost $/bbl
# Taxes
econ.sev_oil = 0.05 # Oil severance tax rate
econ.sev_gas = 0.05 # Gas severance tax rate
econ.atx = 0.02 # Ad valorem tax rate
# Generate cashflow for all wells
cashflow = econ.generate_cashflow()
# Generate economic indicators
econ.generate_indicators()
indicators = econ.indicators
print("Economic Indicators:")
print(indicators[['UID', 'IRR', 'DCF', 'PAYOUT', 'BREAKEVEN']])
```
#### Advanced Economic Modeling
```python
# Gas processing and NGL modeling
econ.gas_shrink = 0.1 # 10% gas shrinkage
econ.ngl_yield = 0.05 # 5 bbl NGL per MCF gas
econ.ngl_price_fraction = 0.6 # NGL price as fraction of oil price
# Price differentials
econ.oil_diff = -2.0 # Oil price differential $/bbl
econ.gas_diff = 0.5 # Gas price differential $/MCF
# Scaling and timing
econ.scale_forecast = True # Scale forecast by well characteristics
econ.scale_column = 'LateralLength_FT'
econ.scale_base = 5280 # Base lateral length for scaling
# Generate well-specific cashflow
well_cashflow = econ.well_flowstream('WELL001')
print("Well cashflow columns:", list(well_cashflow.columns))
```
#### Economic Outputs
The economic analysis generates comprehensive outputs:
**Cashflow DataFrame** includes:
- Revenue streams: `oil_revenue`, `gas_revenue`, `ngl_revenue`
- Costs: `expense`, `royalty`, `taxes`, `capex`
- Cashflow: `cf` (undiscounted), `dcf` (discounted)
- Working interest: `wi_*` columns for WI calculations
- Net interest: `net_*` columns for NRI calculations
**Economic Indicators** include:
- `IRR`: Internal Rate of Return (%)
- `DCF`: Discounted Cash Flow ($)
- `ROI`: Return on Investment
- `PAYOUT`: Payback period (months)
- `BREAKEVEN`: Breakeven price ($/bbl or $/MCF)
- `EURO`, `EURG`, `EURW`: Estimated Ultimate Recovery by phase
## Data Requirements
### Input Data Format
Your production data should include the following columns:
- **Date Column**: Production date (e.g., 'ProducingMonth')
- **Well Identifier**: Unique well ID (e.g., 'API_UWI')
- **Production Data**: Oil, gas, and water production volumes
- **Well Characteristics**: Lateral length, hole direction, etc.
### Example Data Structure
The working examples in `examples/input_data/` show the expected format:
```csv
WELL_ID,DATE,OIL,GAS,WATER
WELL_001,2020-01-01,1500,2500,500
WELL_001,2020-02-01,1400,2400,480
...
```
For custom data, use these column names:
- **Date Column**: Production date (e.g., 'DATE')
- **Well Identifier**: Unique well ID (e.g., 'WELL_ID')
- **Production Data**: Oil, gas, and water production volumes
- **Well Characteristics**: Lateral length, hole direction, etc.
## Configuration Options
### DCA Parameters
- `min_h_b`, `max_h_b`: B-factor bounds for horizontal wells
- `default_initial_decline`: Default initial decline rate
- `default_b_factor`: Default Arps b-factor
- `MIN_DECLINE_RATE`: Minimum decline rate
- `GAS_CUTOFF`: Gas-oil ratio threshold for phase classification
### Analysis Settings
- `backup_decline`: Enable backup decline rate for failed fits
- `outlier_correction`: Enable outlier detection and filtering
- `iqr_limit`: Outlier detection threshold
- `filter_bonfp`: Bonferroni correction threshold
- `three_phase_mode`: Enable three-phase forecasting
### Economic Parameters
- `oil_pri`, `gas_pri`: Commodity prices ($/bbl, $/MCF)
- `discount_rate`: Discount rate for NPV calculations
- `opc_t`, `opc_oil`, `opc_gas`, `opc_water`: Operating costs
- `sev_oil`, `sev_gas`: Severance tax rates
- `atx`: Ad valorem tax rate
- `gas_shrink`, `ngl_yield`: Gas processing parameters
- `scale_forecast`: Enable production scaling by well characteristics
## Output Formats
### Oneline Results
Single-well summary with decline parameters and cumulative production:
- `UID`: Well identifier
- `MAJOR`: Major phase (OIL/GAS)
- `OIL`, `GAS`, `WATER`: Cumulative production
- `IPO`, `IPG`, `IPW`: Initial production rates
- `DE`, `DO`, `DG`, `DW`: Decline rates
- `B`, `BO`, `BG`, `BW`: Arps b-factors
- `ARIES_DE`, `ARIES_DO`, `ARIES_DG`, `ARIES_DW`: Aries-compatible decline rates
### Flowstream Results
Monthly production forecasts for each well:
- Multi-index DataFrame with `[UID, T_INDEX]`
- `OIL`, `GAS`, `WATER`: Monthly production rates
- Time series from T_INDEX=0 to specified number of months
### Typecurve Results
Statistical aggregation of decline parameters:
- Probability distributions (P10, P50, P90)
- Phase-specific parameter statistics
- Aggregated production forecasts
### Economic Results
Comprehensive economic analysis outputs:
- **Cashflow DataFrame**: Monthly cashflow with revenue, costs, and cashflow streams
- **Economic Indicators**: IRR, NPV, ROI, payback period, and breakeven analysis
- **Working Interest Calculations**: WI-adjusted cashflows and metrics
- **Net Revenue Interest**: NRI-adjusted cashflows and economic indicators
## Advanced Usage
### Custom Decline Curve Solver
```python
from resaid.dca import decline_solver
# Solve for missing parameters
solver = decline_solver(
qi=1000, # Initial rate
qf=100, # Final rate
eur=50000, # Estimated ultimate recovery
b=1.0, # Arps b-factor
dmin=0.01/12 # Minimum decline rate
)
qi, t_max, qf, de, eur, warning, delta = solver.solve()
```
### Parameter Optimization
```python
# Customize analysis parameters
dca.min_h_b = 0.5
dca.max_h_b = 2.0
dca.default_initial_decline = 0.6/12
dca.default_b_factor = 0.8
dca.GAS_CUTOFF = 2.5 # MSCF/STB
# Run analysis with custom settings
dca.run_DCA()
```
### Advanced Economic Modeling
```python
# Price forecasting with time-varying prices
econ.oil_pri = [45.0, 50.0, 55.0, 60.0, 65.0] # Price forecast
econ.gas_pri = [2.5, 3.0, 3.5, 4.0, 4.5] # Gas price forecast
# Complex royalty structures
econ.royalty_col = 'ROYALTY_RATE' # Column with well-specific royalty rates
econ.owned_royalty_col = 'OWNED_ROY' # Column with owned royalty interest
# Scaled CAPEX based on well characteristics
econ.scale_capex = True
econ.scale_column = 'LateralLength_FT'
econ.capex_val = 250000 # Base CAPEX per 1000 ft
# Timing adjustments
econ.spud_to_online = 3 # Months from spud to first production
econ.t_start_column = 'FIRST_PROD_MONTH' # Column with first production month
# Generate comprehensive economic analysis
cashflow = econ.generate_cashflow()
econ.generate_indicators()
# Access detailed results
print("Top performing wells by IRR:")
top_wells = econ.indicators.nlargest(5, 'IRR')
print(top_wells[['UID', 'IRR', 'DCF', 'PAYOUT']])
```
## Export Functionality
The `decline_curve` class includes integrated export capabilities for major economic software platforms.
### ARIES Export
Generate ARIES-compatible economic forecast files:
```python
from resaid.dca import decline_curve
# Initialize and run DCA
dca = decline_curve()
dca.dataframe = production_df
dca.date_col = 'DATE'
dca.uid_col = 'WELL_ID'
dca.oil_col = 'OIL'
dca.gas_col = 'GAS'
dca.water_col = 'WATER'
dca.phase_col = 'PHASE'
# Run DCA analysis first
dca.run_DCA()
dca.generate_oneline(denormalize=True)
# Generate ARIES export with error handling
try:
dca.generate_aries_export(
file_path="outputs/aries_forecast.txt",
scenario="RSC425",
dmin=6,
write_water=True
)
print("✓ ARIES export completed")
except Exception as e:
print(f"✗ ARIES export failed: {e}")
```
### Mosaic Export
Generate Mosaic-compatible Excel exports with all phases:
```python
# Generate Mosaic export with error handling
try:
dca.generate_mosaic_export(
file_path="outputs/mosaic_forecast.xlsx",
reserve_category="USON ARO",
dmin=8
)
print("✓ Mosaic export completed")
except Exception as e:
print(f"✗ Mosaic export failed: {e}")
```
### PhdWin Export
Generate PhdWin-compatible CSV exports:
```python
# Generate PhdWin export with error handling
try:
dca.generate_phdwin_export(
file_path="outputs/phdwin_forecast.csv",
dmin=6
)
print("✓ PhdWin export completed")
except Exception as e:
print(f"✗ PhdWin export failed: {e}")
```
### Utility Functions
#### 3-Month Average Production Calculation
Calculate 3-month average production rates for initial rate estimation:
```python
# Calculate 3-month averages
l3m_df = dca.qi_overwrite()
print(l3m_df.head())
```
#### Ratio Analysis
Create ratio dataframes for specialized analysis:
```python
# Generate ratio dataframes (GOR, yield, WOR, WGR)
ratio_df = dca.make_ratio_dfs(l3m_df)
print(ratio_df.head())
```
### Export Features
- **Multi-Phase Support**: All exports include OIL, GAS, and WATER phases
- **Three-Phase Mode Integration**: When `three_phase_mode=True`, exports use the existing three-phase analysis instead of creating separate DCA objects
- **Ratio Mode Integration**: When `three_phase_mode=False`, exports use ratio-based calculations (MINOR_RATIO and WATER_RATIO) for gas and water phases
- **Automatic DCA Integration**: Exports automatically run DCA analysis if not already performed
- **Flexible Configuration**: Customizable parameters for each export format
- **Error Handling**: Robust error handling with default values for missing data
- **Directory Creation**: Automatically creates output directories as needed
## Performance Considerations
- **Large Datasets**: The module uses vectorized operations for optimal performance
- **Memory Usage**: For very large datasets, consider processing in batches
- **Three-Phase Mode**: Requires more computation time but provides independent phase analysis
- **Economic Analysis**: Cashflow generation is optimized for large well portfolios
- **Progress Tracking**: Use `verbose=True` for progress bars on large datasets
## Validation
The package includes comprehensive validation tests:
```bash
# Run validation tests
python tests/dca_test.py
python tests/test_econ.py
python tests/test_decline_solver.py
python tests/test_export_functions.py
python tests/test_export_consistency.py
python tests/test_export_date_logic.py
python tests/three_phase_test.py
python tests/validate_three_phase.py
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/gregeasley/resaid",
"name": "resaid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "reservoir engineering, decline curve analysis, production forecasting, oil and gas, DCA, arps",
"author": "Greg Easley",
"author_email": "greg@easley.dev",
"download_url": "https://files.pythonhosted.org/packages/cc/ed/4dd7b6c2c38d22e556f76f4fe3053fb8f952bf01af046ddd5c274769d846/resaid-0.2.2.tar.gz",
"platform": null,
"description": "# RESAID Package\r\n\r\nA comprehensive collection of reservoir engineering tools for production forecasting and decline curve analysis.\r\n\r\n## Features\r\n\r\n- **Decline Curve Analysis (DCA)**: Arps decline curve fitting with exponential, hyperbolic, and harmonic decline models\r\n- **Production Data Processing**: Normalization, outlier detection, and data preprocessing\r\n- **Single-Phase Forecasting**: Traditional major phase analysis with ratio-based minor phase estimation\r\n- **Three-Phase Forecasting**: Independent decline curve analysis for OIL, GAS, and WATER phases\r\n- **Multiple Output Formats**: Flowstream, oneline, and typecurve generation\r\n- **Economic Analysis**: NPV, IRR, and comprehensive cashflow modeling\r\n- **Multi-Phase Economics**: Oil, gas, water, and NGL revenue calculations\r\n- **Royalty & Interest Modeling**: Working interest, net revenue interest, and royalty calculations\r\n- **Tax & Cost Modeling**: Severance taxes, ad valorem taxes, and operating costs\r\n- **Vectorized Operations**: High-performance calculations for large datasets\r\n\r\n## Installation\r\n\r\n```bash\r\npip install resaid\r\n```\r\n\r\n## Quick Start\r\n\r\n### Working Examples\r\n\r\nThe `examples/` folder contains working examples that demonstrate RESAID functionality:\r\n\r\n- **`simple_example.py`**: Three-phase mode example generating ARIES, PhdWin, and Mosaic exports\r\n- **`ratio_mode_example.py`**: Ratio mode example showing how to use ratios for multi-phase forecasting\r\n\r\nRun these examples to see RESAID in action:\r\n```bash\r\ncd examples\r\npython simple_example.py # Three-phase mode\r\npython ratio_mode_example.py # Ratio mode\r\n```\r\n\r\n### Basic Single-Phase DCA Analysis\r\n\r\n```python\r\nimport pandas as pd\r\nfrom resaid.dca import decline_curve\r\n\r\n# Load production data\r\nprod_df = pd.read_csv('production_data.csv')\r\n\r\n# Initialize DCA object\r\ndca = decline_curve()\r\n\r\n# Configure data columns\r\ndca.dataframe = prod_df\r\ndca.date_col = 'ProducingMonth'\r\ndca.uid_col = 'API_UWI'\r\ndca.oil_col = 'LiquidsProd_BBL'\r\ndca.gas_col = 'GasProd_MCF'\r\ndca.water_col = 'WaterProd_BBL'\r\ndca.length_col = 'LateralLength_FT'\r\n\r\n# Set analysis parameters\r\ndca.min_h_b = 0.9\r\ndca.max_h_b = 1.3\r\ndca.backup_decline = True\r\ndca.outlier_correction = False\r\n\r\n# Run DCA analysis\r\ndca.run_DCA()\r\n\r\n# Generate outputs\r\ndca.generate_oneline(num_months=1200, denormalize=True)\r\ndca.generate_flowstream(num_months=1200, denormalize=True)\r\ndca.generate_typecurve(num_months=1200, denormalize=True)\r\n\r\n# Access results\r\noneline_results = dca.oneline_dataframe\r\nflowstream_results = dca.flowstream_dataframe\r\ntypecurve_results = dca.typecurve\r\n```\r\n\r\n### Three-Phase Forecasting Mode\r\n\r\n```python\r\n# Enable three-phase mode\r\ndca.three_phase_mode = True\r\n\r\n# Run analysis (same as before)\r\ndca.run_DCA()\r\n\r\n# Generate outputs with independent phase analysis\r\ndca.generate_oneline(num_months=1200, denormalize=True)\r\ndca.generate_flowstream(num_months=1200, denormalize=True)\r\ndca.generate_typecurve(num_months=1200, denormalize=True)\r\n\r\n# Three-phase results include phase-specific parameters\r\noneline_3p = dca.oneline_dataframe\r\nprint(\"Phase-specific columns:\", [col for col in oneline_3p.columns if col.startswith(('IPO', 'IPG', 'IPW', 'DO', 'DG', 'DW', 'BO', 'BG', 'BW'))])\r\n```\r\n\r\n### Ratio Mode Forecasting\r\n\r\n```python\r\n# Enable ratio mode for multi-phase forecasting using ratios\r\ndca.three_phase_mode = False\r\n\r\n# Run analysis (same as before)\r\ndca.run_DCA()\r\n\r\n# Generate outputs with ratio-based phase calculations\r\ndca.generate_oneline(denormalize=True)\r\n\r\n# Ratio mode uses MINOR_RATIO and WATER_RATIO from oneline data\r\n# Gas production = MINOR_RATIO * OIL_QI\r\n# Water production = WATER_RATIO * OIL_QI\r\n# All phases use the same decline curve parameters\r\n```\r\n\r\n### Economic Analysis\r\n\r\nRESAID provides comprehensive economic analysis tools for oil and gas projects, including NPV calculations, IRR analysis, and detailed cashflow modeling.\r\n\r\n#### Basic NPV and IRR Calculations\r\n\r\n```python\r\nfrom resaid.econ import npv_calc\r\n\r\n# Create cashflow array (negative for outflows, positive for inflows)\r\ncashflow = np.array([-1000000, 500000, 400000, 300000, 200000])\r\n\r\n# Initialize NPV calculator\r\nnpv = npv_calc(cashflow)\r\n\r\n# Calculate NPV at 10% discount rate\r\nnpv_value = npv.get_npv(0.1)\r\nprint(f\"NPV at 10%: ${npv_value:,.2f}\")\r\n\r\n# Calculate Internal Rate of Return\r\nirr = npv.get_irr()\r\nprint(f\"IRR: {irr:.1f}%\")\r\n```\r\n\r\n#### Well Economics Analysis\r\n\r\n```python\r\nfrom resaid.econ import well_econ\r\n\r\n# Initialize economics calculator\r\necon = well_econ(verbose=False)\r\n\r\n# Set flowstream data (from DCA analysis)\r\necon.flowstreams = dca.flowstream_dataframe\r\necon.flowstream_uwi_col = 'UID'\r\necon.flowstream_t_index = 'T_INDEX'\r\n\r\n# Set header data with well information\r\nheader_data = pd.DataFrame({\r\n 'UID': ['WELL001', 'WELL002'],\r\n 'NRI': [0.8, 0.75], # Net Revenue Interest\r\n 'WI': [1.0, 1.0], # Working Interest\r\n 'CAPEX': [2000000, 1800000] # Capital expenditure\r\n})\r\necon.header_data = header_data\r\necon.header_uwi_col = 'UID'\r\necon.wi_col = 'WI'\r\necon.nri_col = 'NRI'\r\necon.capex_col = 'CAPEX'\r\n\r\n# Set economic parameters\r\necon.oil_pri = 50.0 # Oil price $/bbl\r\necon.gas_pri = 3.0 # Gas price $/MCF\r\necon.discount_rate = 0.1 # 10% discount rate\r\n\r\n# Operating costs\r\necon.opc_t = 1000 # Fixed operating cost $/month\r\necon.opc_oil = 5.0 # Variable oil cost $/bbl\r\necon.opc_gas = 0.5 # Variable gas cost $/MCF\r\necon.opc_water = 2.0 # Variable water cost $/bbl\r\n\r\n# Taxes\r\necon.sev_oil = 0.05 # Oil severance tax rate\r\necon.sev_gas = 0.05 # Gas severance tax rate\r\necon.atx = 0.02 # Ad valorem tax rate\r\n\r\n# Generate cashflow for all wells\r\ncashflow = econ.generate_cashflow()\r\n\r\n# Generate economic indicators\r\necon.generate_indicators()\r\nindicators = econ.indicators\r\n\r\nprint(\"Economic Indicators:\")\r\nprint(indicators[['UID', 'IRR', 'DCF', 'PAYOUT', 'BREAKEVEN']])\r\n```\r\n\r\n#### Advanced Economic Modeling\r\n\r\n```python\r\n# Gas processing and NGL modeling\r\necon.gas_shrink = 0.1 # 10% gas shrinkage\r\necon.ngl_yield = 0.05 # 5 bbl NGL per MCF gas\r\necon.ngl_price_fraction = 0.6 # NGL price as fraction of oil price\r\n\r\n# Price differentials\r\necon.oil_diff = -2.0 # Oil price differential $/bbl\r\necon.gas_diff = 0.5 # Gas price differential $/MCF\r\n\r\n# Scaling and timing\r\necon.scale_forecast = True # Scale forecast by well characteristics\r\necon.scale_column = 'LateralLength_FT'\r\necon.scale_base = 5280 # Base lateral length for scaling\r\n\r\n# Generate well-specific cashflow\r\nwell_cashflow = econ.well_flowstream('WELL001')\r\nprint(\"Well cashflow columns:\", list(well_cashflow.columns))\r\n```\r\n\r\n#### Economic Outputs\r\n\r\nThe economic analysis generates comprehensive outputs:\r\n\r\n**Cashflow DataFrame** includes:\r\n- Revenue streams: `oil_revenue`, `gas_revenue`, `ngl_revenue`\r\n- Costs: `expense`, `royalty`, `taxes`, `capex`\r\n- Cashflow: `cf` (undiscounted), `dcf` (discounted)\r\n- Working interest: `wi_*` columns for WI calculations\r\n- Net interest: `net_*` columns for NRI calculations\r\n\r\n**Economic Indicators** include:\r\n- `IRR`: Internal Rate of Return (%)\r\n- `DCF`: Discounted Cash Flow ($)\r\n- `ROI`: Return on Investment\r\n- `PAYOUT`: Payback period (months)\r\n- `BREAKEVEN`: Breakeven price ($/bbl or $/MCF)\r\n- `EURO`, `EURG`, `EURW`: Estimated Ultimate Recovery by phase\r\n\r\n## Data Requirements\r\n\r\n### Input Data Format\r\n\r\nYour production data should include the following columns:\r\n\r\n- **Date Column**: Production date (e.g., 'ProducingMonth')\r\n- **Well Identifier**: Unique well ID (e.g., 'API_UWI')\r\n- **Production Data**: Oil, gas, and water production volumes\r\n- **Well Characteristics**: Lateral length, hole direction, etc.\r\n\r\n### Example Data Structure\r\n\r\nThe working examples in `examples/input_data/` show the expected format:\r\n\r\n```csv\r\nWELL_ID,DATE,OIL,GAS,WATER\r\nWELL_001,2020-01-01,1500,2500,500\r\nWELL_001,2020-02-01,1400,2400,480\r\n...\r\n```\r\n\r\nFor custom data, use these column names:\r\n- **Date Column**: Production date (e.g., 'DATE')\r\n- **Well Identifier**: Unique well ID (e.g., 'WELL_ID')\r\n- **Production Data**: Oil, gas, and water production volumes\r\n- **Well Characteristics**: Lateral length, hole direction, etc.\r\n\r\n## Configuration Options\r\n\r\n### DCA Parameters\r\n\r\n- `min_h_b`, `max_h_b`: B-factor bounds for horizontal wells\r\n- `default_initial_decline`: Default initial decline rate\r\n- `default_b_factor`: Default Arps b-factor\r\n- `MIN_DECLINE_RATE`: Minimum decline rate\r\n- `GAS_CUTOFF`: Gas-oil ratio threshold for phase classification\r\n\r\n### Analysis Settings\r\n\r\n- `backup_decline`: Enable backup decline rate for failed fits\r\n- `outlier_correction`: Enable outlier detection and filtering\r\n- `iqr_limit`: Outlier detection threshold\r\n- `filter_bonfp`: Bonferroni correction threshold\r\n- `three_phase_mode`: Enable three-phase forecasting\r\n\r\n### Economic Parameters\r\n\r\n- `oil_pri`, `gas_pri`: Commodity prices ($/bbl, $/MCF)\r\n- `discount_rate`: Discount rate for NPV calculations\r\n- `opc_t`, `opc_oil`, `opc_gas`, `opc_water`: Operating costs\r\n- `sev_oil`, `sev_gas`: Severance tax rates\r\n- `atx`: Ad valorem tax rate\r\n- `gas_shrink`, `ngl_yield`: Gas processing parameters\r\n- `scale_forecast`: Enable production scaling by well characteristics\r\n\r\n## Output Formats\r\n\r\n### Oneline Results\r\n\r\nSingle-well summary with decline parameters and cumulative production:\r\n\r\n- `UID`: Well identifier\r\n- `MAJOR`: Major phase (OIL/GAS)\r\n- `OIL`, `GAS`, `WATER`: Cumulative production\r\n- `IPO`, `IPG`, `IPW`: Initial production rates\r\n- `DE`, `DO`, `DG`, `DW`: Decline rates\r\n- `B`, `BO`, `BG`, `BW`: Arps b-factors\r\n- `ARIES_DE`, `ARIES_DO`, `ARIES_DG`, `ARIES_DW`: Aries-compatible decline rates\r\n\r\n### Flowstream Results\r\n\r\nMonthly production forecasts for each well:\r\n\r\n- Multi-index DataFrame with `[UID, T_INDEX]`\r\n- `OIL`, `GAS`, `WATER`: Monthly production rates\r\n- Time series from T_INDEX=0 to specified number of months\r\n\r\n### Typecurve Results\r\n\r\nStatistical aggregation of decline parameters:\r\n\r\n- Probability distributions (P10, P50, P90)\r\n- Phase-specific parameter statistics\r\n- Aggregated production forecasts\r\n\r\n### Economic Results\r\n\r\nComprehensive economic analysis outputs:\r\n\r\n- **Cashflow DataFrame**: Monthly cashflow with revenue, costs, and cashflow streams\r\n- **Economic Indicators**: IRR, NPV, ROI, payback period, and breakeven analysis\r\n- **Working Interest Calculations**: WI-adjusted cashflows and metrics\r\n- **Net Revenue Interest**: NRI-adjusted cashflows and economic indicators\r\n\r\n## Advanced Usage\r\n\r\n### Custom Decline Curve Solver\r\n\r\n```python\r\nfrom resaid.dca import decline_solver\r\n\r\n# Solve for missing parameters\r\nsolver = decline_solver(\r\n qi=1000, # Initial rate\r\n qf=100, # Final rate\r\n eur=50000, # Estimated ultimate recovery\r\n b=1.0, # Arps b-factor\r\n dmin=0.01/12 # Minimum decline rate\r\n)\r\n\r\nqi, t_max, qf, de, eur, warning, delta = solver.solve()\r\n```\r\n\r\n### Parameter Optimization\r\n\r\n```python\r\n# Customize analysis parameters\r\ndca.min_h_b = 0.5\r\ndca.max_h_b = 2.0\r\ndca.default_initial_decline = 0.6/12\r\ndca.default_b_factor = 0.8\r\ndca.GAS_CUTOFF = 2.5 # MSCF/STB\r\n\r\n# Run analysis with custom settings\r\ndca.run_DCA()\r\n```\r\n\r\n### Advanced Economic Modeling\r\n\r\n```python\r\n# Price forecasting with time-varying prices\r\necon.oil_pri = [45.0, 50.0, 55.0, 60.0, 65.0] # Price forecast\r\necon.gas_pri = [2.5, 3.0, 3.5, 4.0, 4.5] # Gas price forecast\r\n\r\n# Complex royalty structures\r\necon.royalty_col = 'ROYALTY_RATE' # Column with well-specific royalty rates\r\necon.owned_royalty_col = 'OWNED_ROY' # Column with owned royalty interest\r\n\r\n# Scaled CAPEX based on well characteristics\r\necon.scale_capex = True\r\necon.scale_column = 'LateralLength_FT'\r\necon.capex_val = 250000 # Base CAPEX per 1000 ft\r\n\r\n# Timing adjustments\r\necon.spud_to_online = 3 # Months from spud to first production\r\necon.t_start_column = 'FIRST_PROD_MONTH' # Column with first production month\r\n\r\n# Generate comprehensive economic analysis\r\ncashflow = econ.generate_cashflow()\r\necon.generate_indicators()\r\n\r\n# Access detailed results\r\nprint(\"Top performing wells by IRR:\")\r\ntop_wells = econ.indicators.nlargest(5, 'IRR')\r\nprint(top_wells[['UID', 'IRR', 'DCF', 'PAYOUT']])\r\n```\r\n\r\n## Export Functionality\r\n\r\nThe `decline_curve` class includes integrated export capabilities for major economic software platforms.\r\n\r\n### ARIES Export\r\n\r\nGenerate ARIES-compatible economic forecast files:\r\n\r\n```python\r\nfrom resaid.dca import decline_curve\r\n\r\n# Initialize and run DCA\r\ndca = decline_curve()\r\ndca.dataframe = production_df\r\ndca.date_col = 'DATE'\r\ndca.uid_col = 'WELL_ID'\r\ndca.oil_col = 'OIL'\r\ndca.gas_col = 'GAS'\r\ndca.water_col = 'WATER'\r\ndca.phase_col = 'PHASE'\r\n\r\n# Run DCA analysis first\r\ndca.run_DCA()\r\ndca.generate_oneline(denormalize=True)\r\n\r\n# Generate ARIES export with error handling\r\ntry:\r\n dca.generate_aries_export(\r\n file_path=\"outputs/aries_forecast.txt\",\r\n scenario=\"RSC425\",\r\n dmin=6,\r\n write_water=True\r\n )\r\n print(\"\u2713 ARIES export completed\")\r\nexcept Exception as e:\r\n print(f\"\u2717 ARIES export failed: {e}\")\r\n```\r\n\r\n### Mosaic Export\r\n\r\nGenerate Mosaic-compatible Excel exports with all phases:\r\n\r\n```python\r\n# Generate Mosaic export with error handling\r\ntry:\r\n dca.generate_mosaic_export(\r\n file_path=\"outputs/mosaic_forecast.xlsx\",\r\n reserve_category=\"USON ARO\",\r\n dmin=8\r\n )\r\n print(\"\u2713 Mosaic export completed\")\r\nexcept Exception as e:\r\n print(f\"\u2717 Mosaic export failed: {e}\")\r\n```\r\n\r\n### PhdWin Export\r\n\r\nGenerate PhdWin-compatible CSV exports:\r\n\r\n```python\r\n# Generate PhdWin export with error handling\r\ntry:\r\n dca.generate_phdwin_export(\r\n file_path=\"outputs/phdwin_forecast.csv\",\r\n dmin=6\r\n )\r\n print(\"\u2713 PhdWin export completed\")\r\nexcept Exception as e:\r\n print(f\"\u2717 PhdWin export failed: {e}\")\r\n```\r\n\r\n### Utility Functions\r\n\r\n#### 3-Month Average Production Calculation\r\n\r\nCalculate 3-month average production rates for initial rate estimation:\r\n\r\n```python\r\n# Calculate 3-month averages\r\nl3m_df = dca.qi_overwrite()\r\nprint(l3m_df.head())\r\n```\r\n\r\n#### Ratio Analysis\r\n\r\nCreate ratio dataframes for specialized analysis:\r\n\r\n```python\r\n# Generate ratio dataframes (GOR, yield, WOR, WGR)\r\nratio_df = dca.make_ratio_dfs(l3m_df)\r\nprint(ratio_df.head())\r\n```\r\n\r\n### Export Features\r\n\r\n- **Multi-Phase Support**: All exports include OIL, GAS, and WATER phases\r\n- **Three-Phase Mode Integration**: When `three_phase_mode=True`, exports use the existing three-phase analysis instead of creating separate DCA objects\r\n- **Ratio Mode Integration**: When `three_phase_mode=False`, exports use ratio-based calculations (MINOR_RATIO and WATER_RATIO) for gas and water phases\r\n- **Automatic DCA Integration**: Exports automatically run DCA analysis if not already performed\r\n- **Flexible Configuration**: Customizable parameters for each export format\r\n- **Error Handling**: Robust error handling with default values for missing data\r\n- **Directory Creation**: Automatically creates output directories as needed\r\n\r\n## Performance Considerations\r\n\r\n- **Large Datasets**: The module uses vectorized operations for optimal performance\r\n- **Memory Usage**: For very large datasets, consider processing in batches\r\n- **Three-Phase Mode**: Requires more computation time but provides independent phase analysis\r\n- **Economic Analysis**: Cashflow generation is optimized for large well portfolios\r\n- **Progress Tracking**: Use `verbose=True` for progress bars on large datasets\r\n\r\n## Validation\r\n\r\nThe package includes comprehensive validation tests:\r\n\r\n```bash\r\n# Run validation tests\r\npython tests/dca_test.py\r\npython tests/test_econ.py\r\npython tests/test_decline_solver.py\r\npython tests/test_export_functions.py\r\npython tests/test_export_consistency.py\r\npython tests/test_export_date_logic.py\r\npython tests/three_phase_test.py\r\npython tests/validate_three_phase.py\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests for new functionality\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Comprehensive reservoir engineering tools for decline curve analysis and production forecasting",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/gregeasley/resaid/issues",
"Homepage": "https://github.com/gregeasley/resaid"
},
"split_keywords": [
"reservoir engineering",
" decline curve analysis",
" production forecasting",
" oil and gas",
" dca",
" arps"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "97792589c1d757903d276fafc7db40e7818b2981d0cb85380b587425105dfdb4",
"md5": "bcd8c7955d027171520f3dadf5db912b",
"sha256": "e1f4d3873dae994e49bfda0c8a188cdde29a2a998ba767b9f1253cc0f694ee10"
},
"downloads": -1,
"filename": "resaid-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcd8c7955d027171520f3dadf5db912b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30769,
"upload_time": "2025-09-02T16:33:22",
"upload_time_iso_8601": "2025-09-02T16:33:22.539411Z",
"url": "https://files.pythonhosted.org/packages/97/79/2589c1d757903d276fafc7db40e7818b2981d0cb85380b587425105dfdb4/resaid-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cced4dd7b6c2c38d22e556f76f4fe3053fb8f952bf01af046ddd5c274769d846",
"md5": "debd3f9db0206db956baa1b655731e94",
"sha256": "fc4cb2ff91c9dc0866ce86b5f8c8d6d7be50ccff50ed771d4dc754486eeaa1df"
},
"downloads": -1,
"filename": "resaid-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "debd3f9db0206db956baa1b655731e94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 46434,
"upload_time": "2025-09-02T16:33:23",
"upload_time_iso_8601": "2025-09-02T16:33:23.484911Z",
"url": "https://files.pythonhosted.org/packages/cc/ed/4dd7b6c2c38d22e556f76f4fe3053fb8f952bf01af046ddd5c274769d846/resaid-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 16:33:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gregeasley",
"github_project": "resaid",
"github_not_found": true,
"lcname": "resaid"
}
JSON
