welltest_pta.WellTest

class welltest_pta.WellTest

Bases: object

Top-level handle for one well-test interpretation.

A WellTest keeps three things in lock-step:

• self.df — the parsed + annotated gauge DataFrame

• self.events — the EventCollection derived from self.df

• self.metadata — file-level metadata + detector / CV results

Re-running event detection (via detect() or split_manual()) rebuilds self.events and updates self.df["event"] in place.

Parameters:

• df_raw (DataFrame)

• metadata (Optional[dict[str, Any]])

__init__(df_raw, metadata=None)

Parameters:

• df_raw (DataFrame)

• metadata (Optional[dict[str, Any]])

Methods

__init__(df_raw[, metadata])
cross_validate([cfg, n_bootstrap, print_report])	Run the bootstrap + sensitivity + Jaccard CV on the current data.
detect([cfg])	Run (or re-run) automatic V8.1 event detection.
export_all(out_dir[, prefix, per_event, ...])	Export everything to a directory:
from_dataframe(df[, cfg, auto_detect])	Build from an already-parsed DataFrame.
from_file(filepath[, cfg, cross_validate, ...])	Parse an ASCII gauge file, run the V8.1 detector, optionally cross-validate, and return a populated WellTest.
plot_composite([out_path, figsize])	Composite 4-panel report (uses welltest_pta.visualization.composite).
plot_overview([ax, show_events, show_p_res])	Single-panel pressure-vs-time overview with event shading.
print_summary()	Print the high-level summary + the event catalogue.
split_manual(spec[, ...])	Override the auto-detected events with a manual list.
summary()	Return a dict with file-, detector-, and event-level info.

Attributes

buildups
drawdowns
p_reservoir

__init__(df_raw, metadata=None)

Parameters:

• df_raw (DataFrame)

• metadata (Optional[dict[str, Any]])

classmethod from_file(filepath, cfg=None, cross_validate=False, cv_n_bootstrap=8, cv_print=True, auto_detect=True)

Parse an ASCII gauge file, run the V8.1 detector, optionally cross-validate, and return a populated WellTest.

Parameters:

• filepath (str | Path)

• cfg (Optional[EventDetectorConfig])

• cross_validate (bool)

• cv_n_bootstrap (int)

• cv_print (bool)

• auto_detect (bool)

Return type:

WellTest

classmethod from_dataframe(df, cfg=None, auto_detect=True)

Build from an already-parsed DataFrame.

Parameters:

• df (DataFrame)

• cfg (Optional[EventDetectorConfig])

• auto_detect (bool)

Return type:

WellTest

detect(cfg=None)

Run (or re-run) automatic V8.1 event detection.

Parameters:

cfg (Optional[EventDetectorConfig])

Return type:

WellTest

cross_validate(cfg=None, n_bootstrap=8, print_report=True)

Run the bootstrap + sensitivity + Jaccard CV on the current data.

Parameters:

• cfg (Optional[EventDetectorConfig])

• n_bootstrap (int)

• print_report (bool)

Return type:

DetectorCVResult

split_manual(spec, keep_existing_classifications=False)

Override the auto-detected events with a manual list.

Parameters:

• spec (list[tuple[str, Any, Any]]) –

  List of (type, t_start, t_end) tuples where:

  • type is one of "DD", "BU", "drawdown", "buildup"

  • t_start, t_end are timestamps (str or pd.Timestamp)

  Example:

  wt.split_manual([
      ("DD", "2025-01-15 10:00:00", "2025-01-15 12:30:00"),
      ("BU", "2025-01-15 12:30:00", "2025-01-15 18:00:00"),
  ])
  

• keep_existing_classifications (bool) – If True, gaps between manual events keep their auto labels. If False (default), they are reset to non_pta.

Return type:

WellTest

Notes

Calling this method requires that detect() has already been run at least once, since it relies on the p_smooth / elapsed_hr columns built in Phase 0.

property drawdowns: EventCollection

property buildups: EventCollection

property p_reservoir: float | None

summary()

Return a dict with file-, detector-, and event-level info.

Return type:

dict[str, Any]

print_summary()

Print the high-level summary + the event catalogue.

Return type:

None

plot_composite(out_path=None, figsize=(14, 10))

Composite 4-panel report (uses welltest_pta.visualization.composite).

Parameters:

• out_path (Union[str, Path, None])

• figsize (tuple[float, float])

plot_overview(ax=None, show_events=True, show_p_res=True)

Single-panel pressure-vs-time overview with event shading.

Parameters:

• show_events (bool)

• show_p_res (bool)

export_all(out_dir, prefix='welltest', per_event=True, catalogue_format='csv')

Export everything to a directory:

• {prefix}_full_data.csv — the full annotated DataFrame

• {prefix}_catalogue.csv — one row per event

• {prefix}_metadata.json — file metadata + detector info

• {prefix}_events/{id}.csv — one CSV per event (if per_event)

Returns a dict of label → Path.

Parameters:

• out_dir (str | Path)

• prefix (str)

• per_event (bool)

• catalogue_format (str)

Return type:

dict[str, Path]