fusionlab.nn.utils.format_pihalnet_predictions

fusionlab.nn.utils.format_pihalnet_predictions(pihalnet_outputs=None, model=None, model_inputs=None, y_true_dict=None, target_mapping=None, include_gwl=True, include_coords=True, quantiles=None, forecast_horizon=None, output_dims=None, ids_data_array=None, ids_cols=None, ids_cols_indices=None, scaler_info=None, coord_scaler=None, evaluate_coverage=False, coverage_quantile_indices=(0, -1), savefile=None, verbose=0, _logger=None, **kwargs)[source]

Formats PIHALNet predictions into a structured pandas DataFrame.

This function processes the output dictionary from PIHALNet (or generates predictions if a model and inputs are provided) and transforms them into a long-format DataFrame. It handles dual targets (subsidence, GWL), point or quantile forecasts, and can optionally include true target values, coordinate information, additional identifiers, perform inverse scaling, and evaluate quantile coverage.

Structure PIHALNet predictions, targets, coordinates, and user metadata into a long‑format :pyclass:`pandas.DataFrame` ready for post‑processing, plotting, or export.

The routine accepts either a pre‑computed output dictionary from PIHALNet or a compiled model and its inputs. It supports single‑point as well as quantile forecasts, dual‑target learning (subsidence / ground‑water level), optional inverse scaling, coordinate recovery, quantile‑coverage diagnostics, and the injection of arbitrary static ID columns.

pihalnet_outputsdict[str, Tensor] or None, default=None

Dictionary returned by PIHALNet.predict. Keys should include 'subs_pred' and/or 'gwl_pred'; a 'pde_residual' key is silently ignored. If None, predictions are generated from model and model_inputs.

modelkeras.Model or None, default=None

A compiled PIHALNet instance used to generate predictions when pihalnet_outputs is None.

model_inputsdict[str, Tensor] or None, default=None

Input dictionary matching the signature of :pymeth:`PIHALNet.call`. Required with model.

y_true_dictdict[str, ndarray | Tensor] or None, default=None

Ground‑truth arrays keyed by 'subsidence' / 'gwl' or by their prediction keys. Shapes must match (N, H, O).

target_mappingdict[str, str] or None, default=None

Custom mapping between network output keys and column base names. Example: {'subs_pred': 'subs', 'gwl_pred': 'gwl'}.

include_gwl, include_coords_in_dfbool, default=True

Toggles the export of GWL predictions and coordinate columns.

quantileslist[float] or None, default=None

Sorted quantile levels q such that \(0 < q_1 < \dots < q_Q < 1\).

forecast_horizonint or None, default=None

Overrides the horizon inferred from prediction shape.

output_dimsdict[str, int] or None, default=None

Explicit feature dimension per target. If None, each target’s last axis defines \(O\).

ids_data_arrayndarray | DataFrame | Tensor or None, default=None

Static identifiers (e.g. well ID, lithology) of shape (N, P).

ids_colslist[str] or None, default=None

Column names for ids_data_array (DataFrame or ndarray).

ids_cols_indiceslist[int] or None, default=None

Subset of columns to retain from an ids_data_array ndarray.

scaler_infodict[str, dict] or None, default=None

Per‑target inverse‑scaling metadata. Each sub‑dict must contain 'scaler', 'all_features', and 'idx'.

coord_scalerobject or None, default=None

Scikit‑learn‑compatible scaler used to denormalize the coordinate triplet (t, x, y).

evaluate_coveragebool, default=False

Compute unconditional coverage of the central quantile band defined by coverage_quantile_indices.

coverage_quantile_indicestuple[int, int], default=(0, -1)

Indices (L, U) pointing to the lower and upper quantile columns used in the coverage test.

\[ext{Coverage} \;=\;\]
rac{1}{n}sum_{i=1}^{n}
mathbb{1}!igl[
y_i in igl[hat{y}^{(L)}_i,

hat{y}^{(U)}_iigr]

igr]

savefilestr or None, default=None

If given, final_df.to_csv(savefile, index=False) is called.

verboseint, default=0

Verbosity from 0 (silent) to 5 (trace every step).

pandas.DataFrame

Long‑format frame with one row per sample–step pair and columns

  • sample_idx – original sample index \(n\).

  • forecast_step – lead time \(h\;(\ge 1)\).

  • coord_t, coord_x, coord_y – coordinates (optional).

  • Prediction columns <base>[_<k>] or <base>_q<q%>.

  • <base>_actual – ground‑truth targets (optional).

  • Extra ID columns supplied via ids_data_array.

ValueError

Missing mandatory inputs or shape mismatches.

RuntimeError

Model prediction failures.

TypeError

Unsupported tensor type in pihalnet_outputs.

Warning

Non‑fatal issues are logged when verbose > 0.

  • The exported DataFrame is column‑aligned across targets, enabling straightforward melt/merge operations.

  • If quantiles is provided and predictions are shape (N, H, Q, O), columns are named <base>_q{int(q*100)}.

  • Inverse transforms are applied after concatenation to avoid duplicate scaler calls.

>>> from fusionlab.nn.pinn.utils import format_pihalnet_predictions
>>> df = format_pihalnet_predictions(
...     model=pihalnet,
...     model_inputs=batch,
...     y_true_dict={'subsidence': y_true},
...     quantiles=[0.05, 0.50, 0.95],
...     ids_data_array=meta_df[['well_id', 'region']],
...     ids_cols=['well_id', 'region'],
...     verbose=3,
... )
>>> df.head()
   sample_idx  forecast_step  subs_q5  subs_q50  subs_q95  subs_actual
0           0              1    -2.11     -1.34     -0.54        -1.20
1           0              2    -2.35     -1.62     -0.80        -1.58
2           0              3    -2.58     -1.91     -1.01        -1.85
3           1              1    -3.05     -2.40     -1.72        -2.55
4           1              2    -3.29     -2.67     -1.99        -2.81

fusionlab.metrics.coverage_score fusionlab.nn.pinn.PIHALNet.predict fusionlab.nn.pinn.utils._format_target_predictions

Parameters:

  • pihalnet_outputs (Dict[str, Tensor] | None)

  • model (Model | None)

  • model_inputs (Dict[str, Tensor] | None)

  • y_true_dict (Dict[str, ndarray | Tensor] | None)

  • target_mapping (Dict[str, str] | None)

  • include_gwl (bool)

  • include_coords (bool)

  • quantiles (List[float] | None)

  • forecast_horizon (int | None)

  • output_dims (Dict[str, int] | None)

  • ids_data_array (ndarray | DataFrame | None)

  • ids_cols (List[str] | None)

  • ids_cols_indices (List[int] | None)

  • scaler_info (Dict[str, Dict[str, Any]] | None)

  • coord_scaler (Any | None)

  • evaluate_coverage (bool)

  • coverage_quantile_indices (Tuple[int, int])

  • savefile (str)

  • verbose (int)

  • _logger (Logger | Callable[[str], None] | None)

Return type:

DataFrame