qaqc_tools

Quality assurance of the forecast (QA) and of the analysis (QC).

Four diagnostics, driven by the scheme through its hooks: after the prior forecast and after every accepted iteration.

calc_coverage Is every observation inside the range the ensemble forecasts? Plots the forecast spread with the observations, marking those outside it, and logs how many fall outside per data type. Seismic (vector) data get the importance-scaled 2-D coverage maps of E. O. Lie (GeoCore). calc_mahalanobis The model-deficiency diagnostic of Oliver (2020), Diagnosing reservoir model deficiency for model improvement: Mahalanobis distances between the observations and the perturbed forecast, singly (level 1) or in pairs and triples, logged as a ranked list with cross-plots of the worst. calc_kg The ES-style Kalman gain each data type would apply to each parameter, ranked by size, so conflicting or dominant data can be spotted; field parameters can be written to the grid through the simulator. calc_da_stat How far the parameters moved from the prior, in units of the prior standard deviation, per parameter group.

Data enters as the ensemble's frames -- observations, variances and predictions indexed by report point with one column per data type, each cell an array ((1,) for point data, (n,) for vector data such as seismic) or None -- and is adapted once, per data type, into the arrays the diagnostics consume. Outputs go to a QAQC folder under the run's save folder. Multilevel ensembles are not supported.

Copyright © 2019-2022 NORCE, All Rights Reserved. 4DSEIS

QAQC

Quality assurance of the forecast (QA) and the analysis (QC); see the module docstring.

Parameters:

Name	Type	Description	Default
keys	dict	The dataassim config merged with the simulator's input_dict. Read: assimindex (which report points are assimilated), and optionally actnum (path to an .npz with an actnum mask) and scale (a divisor applied to seismic data before plotting).	required
data_df	PETDataFrame	Observations and their variances, indexed by report point, one column per data type.	required
data_var_df	PETDataFrame	Observations and their variances, indexed by report point, one column per data type.	required
logger	object	Anything with an info method. Defaults to logging.getLogger.	None
prior_info	dict	Per-parameter prior description (nx, ny, nz); needed by calc_kg and by grid output.	None
sim	object	Simulator; used only for an optional write_to_grid method.	None
ini_state	dict	The prior state, {parameter: (n, ne) array}, as state_layout.to_dict(enX) returns it; defines the parameter groups and the ensemble size.	None
localization	object	The scheme's localization. Only the auto-adaptive kind is used, by calc_kg; anything else is ignored.	None
folder	str or Path	Where plots and grid files go. Default QAQC in the working directory.	'QAQC'

calc_coverage(line=None, field_dim=None, uxl=None, uil=None, contours=None, uxl_c=None, uil_c=None)

Check whether the observations lie inside the ensemble's forecast range.

For each point data type: a plot of the forecast ensemble over the report points with the observations, red where an observation lies above or below every member, and a log line with the count. For the first seismic data type present: the importance-scaled 2-D coverage maps, per vintage.

Parameters:

Name	Type	Description	Default
line	int	Also plot the 1-D coverage along this line of the seismic maps.	None
field_dim	tuple	Grid dimensions of the seismic maps when no mask file is present.	None
uxl	array - like	Easting and northing coordinates of the map edges; default from a seglines.mat in the working directory, else grid indices.	None
uil	array - like	Easting and northing coordinates of the map edges; default from a seglines.mat in the working directory, else grid indices.	None
contours	array - like	A contour field and its coordinates to draw over the maps.	None
uxl_c	array - like	A contour field and its coordinates to draw over the maps.	None
uil_c	array - like	A contour field and its coordinates to draw over the maps.	None

calc_da_stat(options=None)

Log how far each parameter group moved from the prior.

Per group: the mean prior and current standard deviation, and the percentage of parameters whose mean moved by more than one, two and three prior standard deviations.

Parameters:

Name	Type	Description	Default
options	dict	write_to_file (False): also write a field of these flags (-3..3) to the grid through the simulator.	None

calc_kg(options=None)

Rank the ES-style Kalman gain each data type would apply to each parameter.

For every data type, the gain of the ensemble mean is computed in the subspace of the forecast anomalies with the scheme's damping parameter (the ES/LM-EnRML form), per parameter. The largest gains by maximum and by mean are logged, and optionally plotted or written to the grid through the simulator.

Parameters:

Name	Type	Description	Default
options	dict	num_store (10): how many gains to keep in the ranked lists. unique_time (False): one gain per report point instead of one per data type over all its report points. plot_all_kg (False): plot or write every field gain, not just the ranked ones. only_log (True): log only; no plots or grid files. auto_ada_loc (True): apply the scheme's auto-adaptive localization, when it has one, to field parameters. write_to_resinsight (False): pass a time index to the grid writer.	None

calc_mahalanobis(combi_list=(1, None))

Rank the Mahalanobis distance between observations and the perturbed forecast.

After Oliver (2020). The forecast is perturbed with the observation error (a fixed seed, so repeated calls agree), then each observation is scored against it alone (level 1), in pairs (2) or triples (3). The largest scores are logged; level 1 also draws cross-plots of the worst pairs.

Parameters:

Name	Type	Description	Default
combi_list	tuple	Pairs (level, combine). combine is None to score each observation, or a string containing 'time' or 'vector' to first project each data type's series onto its leading principal component and score the data types.	(1, None)

set(pred_data, state=None, lam=None)

Hand over the current predictions, state and damping parameter.

Parameters:

Name	Type	Description	Default
pred_data	PETDataFrame	Predictions aligned with the observation frame; each cell an array whose last axis is the ensemble.	required
state	dict	Current state, {parameter: (n, ne) array}.	None
lam	float	The scheme's damping parameter (0 for schemes without one).	None