training_image_consistency builtin

training_image_consistency(
    ti,
    column,
    coords,
    values,
    *,
    grid=None,
    categorical=True,
    axis=None,
    pattern_length=4,
    n_classes=4,
    n_samples=200,
    seed=0,
)

How often the patterns of the hard data occur in a training image, after Boisvert, Pyrcz and Deutsch (2007); run it to reject an image before simulating with it.

The data are placed in the cells of grid, one per cell. Along axis, runs of consecutive informed cells (the holes) are cut into data events of pattern_length cells, and the frequencies of their patterns are compared with those of every run of pattern_length cells along the same axis of the image, by their Jensen-Shannon divergence: 0 for the same frequencies, 1 when no pattern is shared. Holes of the data's lengths are then drilled n_samples times through the image at random columns and depths and compared with it the same way; the p-value is the share of these reference divergences at least as large as the data's.

Parameters:

Name	Type	Description	Default
ti	BlockModel	The training image, regular or masked; read one image cell per grid cell, as in a simulation.	required
column	str	Column of ti holding the image: integer codes 0 to 254 when categorical, else values.	required
coords	PointSet or array_like	The hard data, or their (n, 2) or (n, 3) coordinates, sampled at about the grid's cell size along axis.	required
values	array_like or str	Codes of the image (categorical) or values of the hard data, or their column in coords. Data without a value or outside grid are left out.	required
grid	BlockModel	The simulation grid; by default the geometry of ti.	None
categorical	bool	Compare codes; otherwise cut the values into n_classes classes.	True
axis	(x, y, z)	Axis the holes follow; by default "z" on a 3D grid, "y" on a 2D one.	"x"
pattern_length	int	Cells in a data event, at least 2. Longer patterns tell images apart better but need longer runs of data.	4
n_classes	int	Continuous images only: classes cut at the quantiles of the hard data, 2 to 254.	4
n_samples	int	Reference draws; the smallest p-value is 1 / (n_samples + 1).	200
seed	int	The same seed gives the same result on any number of threads.	0

Returns:

Type

Description

dict

distance (the data's divergence from the image, 0 to 1), p_value (below 0.05, holes like the data seldom come from the image), reference (the reference divergences, ascending), unseen (share of the data events whose pattern the image lacks), n_events, n_cells (grid cells with data), and for categorical images proportions and data_proportions (share of each code in the image and in the data cells; None for continuous images).

Raises:

Type	Description
InvalidInput	If a data code is not a code of the image, an option is out of range, the grid or image is shorter than pattern_length along axis, or no hole has pattern_length consecutive informed cells.

Notes

Only one axis is compared: vertical holes test the thickness, order and proportions of the units, not the width or orientation of bodies.

Examples:

>>> check = bt.training_image_consistency(ti, "facies", holes, "facies", seed=0)
>>> check["p_value"]

used in

• training images and their consistency