SNESIM

SNESIM (Strebelle, 2002): categories, or classes of values, simulated from the patterns of a training image.

The patterns around each cell of the image are counted once into search trees, one per multigrid level and template class, on simulate. A node reads the categories at the template_size cells nearest to it and draws its own from the image's counts of that data event. Patterns are read in cell index space, so the targets' cells match the image's cells one to one, unless simulate turns or stretches them with local anisotropy.

Parameters:

Name	Type	Description	Default
ti	BlockModel or dict	Regular or masked training image; null and masked-out cells are not patterns. A dict {domain: (model, column)} gives each domain its own image, picked by domains or domain_column in simulate; the images share one code set, 0 to the largest code of any of them.	required
column	str	Column of ti holding category codes, integers 0 to 254; required with one image, left out with a dict.	required
template_size	int	Cells every node reads, nearest first.	40
n_levels	int	Coarse grids above the finest, at spacings 2^L; half of the template of a coarse level stays next to the node, where it sees hard data, the rest spreads over the level's grid. 0 uses the finest grid only.	3
min_replicates	int	Fewest replicates of a data event in the image; the farthest informed cells are dropped until enough remain, down to the image's proportions.	10
target_proportions	sequence of float	Proportion of each code 0..k, summing to 1, that a servosystem steers each realization towards.	required
servo	float	Servosystem strength in [0, 1): a node draws from P(c) + servo / (1 - servo) * (target(c) - current(c)); 0 switches it off.	0.5
angle_step	float	Degrees the local angles of simulate's anisotropy are rounded to; the logarithm of each affinity is rounded to angle_step in radians (factors about 1.19 apart at 10), so that either rounding moves a template cell at distance r by about r * angle_step. Each distinct rounded (image, angles, affinity) is a template class with search trees of its own; a wider step makes fewer.	10.0
categorical	bool	Whether column holds codes or continuous values. By default it is categorical when every value is an integer from 0 to 254.	required
cutoffs	sequence of float	Strictly ascending values cutting a continuous image into classes, which SNESIM simulates as categories. Each simulated cell then takes the value of a cell of its image in its class: of 32 drawn at random, the one whose 8 nearest neighbors best match the values already simulated around it. By default the quartiles of the image's values; few classes keep the patterns frequent enough to count. Ignored for a categorical image.	required

Examples:

>>> grid = bt.BlockModel((0, 0), (1, 1), (80, 80))
>>> ti = bt.object_training_image(
...     grid,
...     [{"shape": "channel", "code": 1, "proportion": 0.3, "width": 6,
...       "azimuth": (80, 100), "amplitude": 6, "wavelength": 50}],
... )
>>> summary = bt.SNESIM(ti, "facies", template_size=24).simulate(grid, n=4)

categorical property

categorical

Whether the training images hold codes rather than continuous values.

n_classes property

n_classes

Template classes whose search trees the last simulate used: one per training image in use, times the distinct rounded local anisotropies.

fit method descriptor

fit(coords, values)

Takes hard data: codes 0..k of a categorical training image, or values of a continuous one, at coords. Each goes to the target cell holding it, several in one cell to their most frequent category or class (a cell keeps the mean of the values in that class), and every realization reproduces it; data outside the targets are ignored. Without fit, realizations are unconditional.

Parameters:

Name	Type	Description	Default
coords	(array_like, PointSet or BlockModel)	Data locations, (n, 2) or (n, 3).	required
values	array_like or str	Code or value of each datum, or the column of coords holding them.	required

Returns:

Type	Description
SNESIM	This simulator.

from_parquet staticmethod

from_parquet(path)

Reads to_parquet output; raises InvalidInput on another class's file or a newer format.

simulate method descriptor

simulate(
    targets,
    *,
    n=100,
    seed=0,
    keep=None,
    soft=None,
    anisotropy=None,
    domains=None,
    domain_column=None,
)

Summary of n realizations, each seeded from seed and its index, the same for any number of threads.

Parameters:

Name	Type	Description	Default
targets	BlockModel	Regular or masked grid; one category per row.	required
n	int	Realizations.	100
seed	int	Seed of the realizations.	0
keep	bool or sequence of int	Realizations to return beside the summary.	None
soft	sequence of str or array_like	Soft probabilities: one column of targets per category, in code order, or an (n_targets, k) array. Each row is rescaled to sum 1; a row of nulls or NaN leaves its target without soft information. They combine with the image's probabilities by permanence of ratios, P(c) ∝ P_ti(c) * P_soft(c) / P0(c) (Journel, 2002), where P0 is the image's proportions, or the target proportions while the servosystem is on, so soft probabilities equal to P0 change nothing. Where the image and the soft probabilities share no category, shorter data events are tried. Hard data override them.	None
anisotropy	LocalAnisotropy	Turns and stretches the patterns at each target, taken from its nearest location. At angles 0 the image's y axis runs north, along the major axis, its x axis east, against the semi-major axis, and its z axis up, along the minor axis; the angles (azimuth clockwise from north, dip positive down, rake; azimuth only on a grid one cell thick) turn them as they turn a variogram. The image's structures grow by scale along its y axis, scale * semi_ratio along x and scale * minor_ratio along z: ratios and scales of 1 turn the patterns only. The image's cells are taken to have the size of the targets' cells. Angles and affinities are rounded by angle_step, and a template cell at grid offset g, on every multigrid level, reads the image at round(M g) for the matrix M of the target's class.	None
domains	array_like or label	Domain of each target, picking its training image when ti was a dict; every domain needs an image.	None
domain_column	str	Column of targets holding the domains, instead of domains.	None

Returns:

Type	Description
CategoricalSummary or SimulationSummary	Probabilities, most likely category and entropy per target for a categorical training image; mean and variance per target for a continuous one.

Raises:

Type	Description
InvalidInput	If targets is not a regular or masked BlockModel, the search trees would not fit in memory (widen angle_step, lower template_size), soft is given with a continuous image or is not (n_targets, k) of non-negative values, some row mixing numbers and NaN or holding only zeros, or the domains do not match the training images.

to_parquet method descriptor

to_parquet(path)

Writes arrays as Parquet columns and parameters as JSON in the file metadata; from_parquet reads it back.

used in

• SNESIM and its multigrid
• conditioning SNESIM
• continuous SNESIM
• rotation and affinity
• several training images
• soft data in SNESIM
• continuous image quilting