API reference

This page lists the full public API of welltest_pta, generated from the source docstrings.

Top-level public API

The following names are re-exported from the top-level package and each has its own auto-generated reference page:

`WellTest`	Top-level handle for one well-test interpretation.
`Event`	A single PTA event (drawdown or buildup) with its data slice and methods.
`EventCollection`	An ordered, indexable container of `Event` objects.
`EventDetector`	V8.1 robust event detector — see module docstring for the pipeline.
`EventDetectorConfig`	Configuration for the V8.1 event detector.
`detect_events`	Detect drawdown / buildup events on a parsed gauge DataFrame.
`parse`	Parse a well-test ASCII gauge file into a clean DataFrame.
`WellTestParser`	Stateful parser that exposes detected metadata and column mapping after a successful `.parse(...)` call.
`bourdet_derivative`	Compute the Bourdet logarithmic pressure derivative.
`horner_extrapolation`	Linear regression of \(p_{ws}\) vs Horner time on the IARF window.
`mdh_extrapolation`	Linear regression of \(p_{ws}\) vs \(\log_{10}(\Delta t)\) on the IARF window.
`identify_flow_regimes`	Segment the Bourdet derivative into flow-regime intervals.
`reservoir_parameters`	Compute \(kh\), \(k\), \(S\), and (optionally) \(C\).
`deconvolve`	Recover the unit-rate constant-rate response from multi-rate data.
`DeconvolutionResult`	Output of `deconvolve()`.
`cross_validate_detector`	Run all three CV checks and return a `DetectorCVResult`.
`DetectorCVResult`	Cross-validation report from `cross_validate_detector()`.

Submodules

Parser

welltest_pta.parser

Robust multi-format ASCII reader for well-test gauge data.

Handles arbitrary delimiters (tab, semicolon, comma, pipe, whitespace), mixed encodings, comma-decimal European format, and various date formats (DD/MM/YYYY HH:MM:SS, MM/DD/YY HH:MM, etc.).

Refactored from the original EnhancedWellTestParser (Harkat 2025) into a stateless function plus a stateful class for advanced use cases.

Detection

welltest_pta.detection.detector

Automatic PTA event detection (drawdown / buildup / non-PTA).

Algorithm — V8.1 “Spike-Boundary + Tail-Trim”

Phase 0 Hampel-filter despike → Savitzky–Golay smoothing → noise-floor σ̂ Phase 1 Reservoir-pressure plateau detection Phase 2 RIH / POOH edge masking Phase 3 Spike-boundary + turning-point detection (with validation) Phase 4 Zone classification using net-ΔP signed logic Phase 5 Pause absorption → same-type merge → edge trimming

→ V8.1 post-plateau tail trim (H→I→J spike before POOH)

Adapted from the original WellTestEventDetector V8.1 (Harkat 2025) into a stateless detect_events() function plus the stateful EventDetector class for advanced use cases.

Events

welltest_pta.events

First-class Event objects + the EventCollection container.

After event detection (or manual splitting) every drawdown / buildup is exposed as a self-contained Event carrying its slice of the gauge data plus all PTA methods relevant to that single event:

WellTest orchestrator

welltest_pta.welltest

Top-level WellTest orchestrator — the user-facing entry point.

Workflow (matches the original V8.1 pipeline + analytics):

>>> from welltest_pta import WellTest
>>>
>>> # 1) Load + auto-detect (with optional CV scores)
>>> wt = WellTest.from_file("DST.txt", cross_validate=True)
>>>
>>> # 2) Inspect detected events
>>> wt.events.print()
>>> wt.events["BU-2"].print()
>>>
>>> # 3) Manual override (if CV score was low)
>>> wt.split_manual([
...     ("DD",  "2025-01-15 10:00", "2025-01-15 12:30"),
...     ("BU",  "2025-01-15 12:30", "2025-01-15 18:00"),
... ])
>>>
>>> # 4) Per-event analysis
>>> bu = wt.events["BU-2"]
>>> bu.plot_loglog()
>>> params = bu.reservoir_params(q=850, mu=0.45, B=1.18, h=18,
...                              phi=0.12, ct=1.2e-5, rw=0.108)
>>>
>>> # 5) Multi-event deconvolution
>>> from welltest_pta import deconvolve
>>> recon = deconvolve(wt.events, default_q=850)
>>> recon.plot()
>>>
>>> # 6) Composite report
>>> wt.plot_composite(out_path="report.pdf")
>>> wt.export_all("output_dir/")

Analysis primitives

Bourdet derivative

welltest_pta.analysis.bourdet

Bourdet (1989) logarithmic pressure derivative for log–log diagnostic plots.

The derivative of pressure with respect to natural log of elapsed time is the diagnostic backbone of modern PTA. Constant slopes in the log–log plot reveal flow regimes:

Unit slope (m=1) at early time → wellbore storage
Zero slope (flat plateau) → infinite-acting radial flow (IARF)
Half slope (m=½) → linear flow (channel / hydraulic fracture)
Quarter slope (m=¼) → bilinear flow (finite-conductivity fracture)
Unit slope at late time → closed boundary (pseudo-steady state)
Slope of −½ → constant-pressure boundary

Horner extrapolation

welltest_pta.analysis.horner

Horner (1951) semi-log extrapolation for buildups.

The Horner plot of \(p_{ws}\) vs \(\log_{10}\big[(t_p+\Delta t)/\Delta t\big]\) is linear during infinite-acting radial flow, with slope

\[m = \frac{162.6\, q\, \mu\, B}{k\, h}\quad\text{(field units)}\]

Extrapolating the IARF straight line to \((t_p+\Delta t)/\Delta t = 1\) (i.e. infinite shut-in) gives the false reservoir pressure \(P^*\). For an infinite-acting reservoir \(P^* = \bar{p}\); for bounded systems use Matthews–Brons–Hazebroek (MBH) correction.

welltest_pta.analysis.horner.horner_diagnostic_line(tp_hr, dt_min, dt_max, n=100)[source]

Return (horner_x, dt_grid) for plotting the IARF line of slope m.

Parameters:

tp_hr (float)
dt_min (float)
dt_max (float)
n (int)

Return type:

tuple[ndarray, ndarray]

Miller–Dyes–Hutchinson (MDH)

welltest_pta.analysis.mdh

Miller–Dyes–Hutchinson (1950) semi-log buildup analysis.

The MDH plot is \(p_{ws}\) vs \(\log_{10}(\Delta t)\). It is the short-shut-in approximation of the Horner method, valid when \(\Delta t \ll t_p\) (i.e. when \(\log\big[(t_p+\Delta t)/\Delta t\big] \approx \log(t_p) - \log(\Delta t)\)).

The MDH slope is identical in magnitude to the Horner slope and is used for permeability and skin calculation. MDH is preferred when \(t_p\) is ill-defined (multiple drawdown periods) and the user wishes to avoid Horner- time bias.

Flow-regime identification

welltest_pta.analysis.flow_regimes

Automatic identification of flow regimes from the Bourdet derivative.

The log–log slope of the derivative is the diagnostic signature:

Regime	Slope	Physical interpretation
Wellbore storage (WBS)	+1	Compressibility of fluid in tubing/annulus
Bilinear flow	+¼	Finite-conductivity hydraulic fracture
Linear flow	+½	Infinite-conductivity fracture / channel
Infinite-acting radial (IARF)	0	Cylindrical radial flow in homogeneous media
Spherical flow	−½	Limited-entry / partially-penetrating well
Pseudo-steady (closed bndry)	+1	All boundaries reached
Constant-pressure boundary	Sharp drop	Aquifer support / gas cap

This module fits piece-wise log–log slopes to the derivative curve and reports the dominant regime in each segment, along with goodness-of-fit and the time-window covered.

Reservoir parameters

welltest_pta.analysis.reservoir

Reservoir parameter calculation from PTA results — field oilfield units.

All formulae use field oilfield units:

Quantity	Symbol	Units
Flow rate	q	STB/D (oil) or Mscf/D (gas)
Viscosity	µ	cp
FVF	B	RB/STB (oil) or RB/Mscf
Permeability	k	mD
Net pay	h	ft
Slope (semilog)	m	psi / log-cycle
Wellbore radius	rw	ft
Total compress.	ct	psi⁻¹
Porosity	φ	fraction
Wellbore storage	C	bbl/psi

Standard radial-flow equations (oil):

\[k\,h = \frac{162.6\, q\, \mu\, B}{|m|}\]

\[k = \frac{k\,h}{h}\]

\[S = 1.151 \left[ \frac{p_{1\text{hr}} - p_{wf}(\Delta t = 0)}{|m|} - \log_{10}\!\left(\frac{k}{\phi\, \mu\, c_t\, r_w^2}\right) + 3.23 \right]\]

For drawdowns, replace \(p_{1\text{hr}} - p_{wf}(\Delta t = 0)\) with \(p_i - p_{1\text{hr}}\) and switch sign convention. Wellbore storage constant from a unit-slope early-time line:

\[C = \frac{q\, B}{24\, m_{\text{slope-1}}} \quad\text{[bbl/psi]}\]

where \(m_{\text{slope-1}}\) is the early-time linear slope of \(\Delta p\) vs \(\Delta t\) (psi/hr).

welltest_pta.analysis.reservoir.dimensionless_storage(C, h, phi, ct, rw)[source]

Dimensionless wellbore storage \(C_D = 0.8936\, C / (\phi\, h\, c_t\, r_w^2)\)

Parameters:

C (float)
h (float)
phi (float)
ct (float)
rw (float)

Return type:

float

welltest_pta.analysis.reservoir.radius_of_investigation(k, t_hr, phi, mu, ct)[source]

Radius of investigation (Lee 1982): \(r_i = 0.0325 \sqrt{k\,t/(\phi\,\mu\,c_t)}\) in feet (oilfield units).

Parameters:

k (float)
t_hr (float)
phi (float)
mu (float)
ct (float)

Return type:

float

Deconvolution

welltest_pta.analysis.deconvolution

Multi-rate pressure-transient deconvolution.

The convolution problem for a variable-rate well test is

\[p_i - p_{wf}(t) = \int_0^t q(\tau)\, p_u'(t-\tau)\, d\tau\]

where \(p_u(t)\) is the unit-rate constant-rate drawdown response and \(p_u'(t) = dp_u/dt\). Deconvolution recovers \(p_u(t)\) from the measured \(p_{wf}(t)\) and known rate history \(q(t)\). The result is a single equivalent buildup that effectively merges all buildups (and drawdowns) in the test, dramatically extending the radius of investigation and revealing late-time boundaries that no individual buildup is long enough to see.

Algorithm — von Schroeter–Hollaender–Gringarten (vSH04)

Direct deconvolution is ill-posed (Hadamard-unstable to noise). vSH04 solve the regularised non-linear problem in the encoded variable

\[z(\sigma) \;=\; \ln\!\left[t\, \frac{dp_u}{dt}\right] \;=\; \ln\!\left[\frac{dp_u}{d\ln t}\right], \qquad \sigma = \ln t\]

so that \(p_u'(t) = e^{z(\ln t)}/t \ge 0\) automatically (positivity of the derivative enforced by construction). The objective is

\[J(z, p_i) \;=\; \|y - C(q,z) - p_i\|^2 \,+\, \nu \,\|D\,z\|^2\]

with \(D\) a second-difference (curvature) operator and \(\nu\) the regularisation weight. The user specifies only \(\nu\) (typically \(10^{-3}\!-\!10^{-1}\)); both \(z\) and \(p_i\) are recovered.

References

von Schroeter, T., Hollaender, F., & Gringarten, A. C. (2004). Deconvolution of well-test data as a nonlinear total least-squares problem. SPE Journal 9 (4), 375–390.
Levitan, M. M. (2005). Practical application of pressure/rate deconvolution to analysis of real well tests. SPE 84290.

Cross-validation

welltest_pta.validation.cross_validation

Cross-validation scores for the auto event-detector.

Three complementary scores are computed and printed when the user calls WellTest.from_file(..., cross_validate=True) or directly via cross_validate_detector():

Bootstrap event-count stability

Re-run the detector on \(K\) random resamples of the data (each downsampled to a fraction \(f\) of the original gauge rate) and report the standard deviation of the number of detected DDs and BUs. Low σ ⇒ stable detection.
Parameter sensitivity sweep

Vary each detector parameter (hampel_sigma, spike_percentile, min_pta_dp_psi) by ±20 % and report how many events change. Few changes ⇒ robust to parameter choice.
Edge-position consistency

For each detected event, compare the start/end indices across bootstrap replicas. Report the median ± IQR positional drift in samples and the “Jaccard overlap” of the masked time axis.

The combined score is a 0–100 confidence index:

80 – 100	Highly robust — manual review optional
60 – 80	Reasonable — spot-check critical events
40 – 60	Marginal — recommend manual splitting
0 – 40	Unstable — manual splitting strongly advised

welltest_pta.validation.cross_validation.bootstrap_score(df, cfg=None, n_bootstrap=10, downsample_frac=0.85, rng=None)[source]

Down-sample bootstrap of detector event counts.

Parameters:

df (DataFrame)
cfg (Optional[EventDetectorConfig])
n_bootstrap (int)
downsample_frac (float)
rng (Optional[Generator])

Return type:

dict[str, float]

welltest_pta.validation.cross_validation.parameter_sensitivity(df, cfg=None, perturbation=0.20)[source]

Sweep ±perturbation around each detector parameter.

Parameters:

df (DataFrame)
cfg (Optional[EventDetectorConfig])
perturbation (float)

Return type:

dict[str, dict[str, int]]

Visualization

welltest_pta.visualization.composite

Publication-quality multi-panel figures.

plot_overview() — single panel, p(t) with event shading
plot_composite_report()— 4-panel composite:
1. Pressure timeline with events + P_res lines
2. Temperature overlay (if available)
3. Log–log diagnostic of the longest buildup
4. Buildup-pressure histogram + KDE mode

welltest_pta.visualization.composite.apply_publication_style()[source]

Apply publication-quality matplotlib defaults (serif, 150 dpi).

Return type:: None

welltest_pta.visualization.composite.plot_overview(wt, ax=None, show_events=True, show_p_res=True)[source]

Single-panel pressure-vs-time overview.

Parameters:

wt (WellTest)
show_events (bool)
show_p_res (bool)

welltest_pta.visualization.composite.plot_composite_report(wt, out_path=None, figsize=(14, 12))[source]

Four-panel composite report:

[0] Pressure timeline with event shading [1] Temperature (if available) [2] Log–log diagnostic of the longest buildup [3] Buildup-pressure histogram with KDE mode

Parameters:

wt (WellTest)
out_path (Union[str, Path, None])
figsize (tuple[float, float])

Utilities

welltest_pta.utils.synthetic

Synthetic DST gauge data — useful for testing and tutorials.

The generator builds a multi-rate test consisting of an initial flow, flow-and-shut-in cycles (FFSI), and a final extended buildup. Pressure honours an exponential approach to a target value within each event, plus optional Gaussian noise.

welltest_pta.utils.synthetic.generate_synthetic_dst(p_reservoir=4500.0, n_samples=18_000, sample_period_s=5.0, start_time=None, sequence=None, noise_psi=1.0, seed=42, include_temperature=True)[source]

Build a synthetic DST gauge DataFrame.

Parameters:

p_reservoir (float) – Static reservoir pressure (psi). Buildups asymptote to this.
n_samples (int) – Total number of samples to generate. The duration is n_samples × sample_period_s.
sample_period_s (float) – Sampling period in seconds (default 5 s — typical electronic gauge).
start_time (Union[str, datetime, None]) – Test start; defaults to now.
sequence (Optional[Sequence[tuple[str, float, float]]]) –
List of (type, duration_hr, target_p) tuples that define the test programme. type is "DD" (drawdown) or "BU" (buildup). The default mimics a typical multi-rate DST:
```
[
    ("DD", 0.5,  3300),  # initial flow
    ("BU", 1.0,  4490),  # short BU
    ("DD", 1.0,  3000),  # main DD
    ("BU", 6.0,  4495),  # final BU
]
```
plus padding non-PTA segments at start and end.
noise_psi (float) – Standard deviation of additive Gaussian noise.
seed (int) – RNG seed.
include_temperature (bool) – If True, also generate a smoothly varying temperature column.

Return type:

DataFrame

Returns:

DataFrame with columns timestamp, pressure, temperature
(optional), plus a true_event ground-truth label column.

Command-line interface

welltest_pta.cli

Command-line interface for the welltest-pta package.

After installation, a welltest-pta command becomes available:

$ welltest-pta DST_file.txt --output ./results --plot --cv

Sub-commands

analyze Full pipeline: parse → detect → CV → plot → export detect Detection only — print event catalogue deconvolve Run multi-event deconvolution on a previously analysed test synthetic Generate a synthetic DST file (for testing / demos)

welltest_pta.cli.cmd_analyze(args)[source]

Parameters:: args (Namespace)
Return type:: int

welltest_pta.cli.cmd_detect(args)[source]

Parameters:: args (Namespace)
Return type:: int

welltest_pta.cli.cmd_deconvolve(args)[source]

Parameters:: args (Namespace)
Return type:: int

welltest_pta.cli.cmd_synthetic(args)[source]

Parameters:: args (Namespace)
Return type:: int

welltest_pta.cli.main(argv=None)[source]

Parameters:: argv (list[str] | None)
Return type:: int