spacing_study ¶

spacing_study(
    simulator: SGS | DSS | TurningBands,
    targets: BlockModel,
    *,
    spacings: Sequence[float | tuple[float, float]]
    | None = None,
    plans: Mapping[str, Drillholes] | None = None,
    rotation: float = 0.0,
    azimuth: float = 0.0,
    dip: float = 90.0,
    topography: Mesh | None = None,
    truths: int | Sequence[int] = 10,
    n: int = 50,
    seed: int = 0,
    blocks: BlockModel | None = None,
    window: Sequence[float] | None = None,
    groups: ArrayLike | str | None = None,
    sampling_error: float = 0.0,
    existing: bool = False,
    composite_length: float | None = None,
    quantiles: tuple[float, float] = (0.05, 0.95),
    tolerances: Sequence[float] = (0.15,),
) -> _boitata.Table

Uncertainty of the summary rows after drilling each plan, on simulated truths (virtual drilling).

Each truth is a realization of the fitted simulator at targets, so it is conditioned to the current data. For each plan and truth, the plan's composites read the truth at the target holding their centre, optionally with a sampling error z * (1 + Y * sampling_error), Y standard normal. A copy of simulator is refitted on those virtual samples, without declustering weights (and with the existing data too when existing), simulates n realizations at targets, and its summary is checked against the truth averaged to the same rows, as SimulationSummary.validate does.

Parameters:

Name	Type	Description	Default
`simulator`	`(SGS, DSS or TurningBands)`	Fitted, without trend, domains or secondary; its variogram and search serve every refit.	required
`targets`	`BlockModel`	Nodes the truths and the realizations are simulated at; planned holes cover them and composites read the truth of the block holding their centre.	required
`spacings`	`sequence of float or (float, float)`	Collar spacings, each one value or `(along, across)`; the holes come from `planned_drillholes` with `rotation`, `azimuth`, `dip` and `topography`. Give one of `spacings` or `plans`.	`None`
`plans`	`dict of str to Drillholes`	Named drilling plans with intervals, such as an irregular infill pattern or a plan from another tool.	`None`
`rotation`	`float`	Collar grid rotation and hole direction, in degrees, as in `planned_drillholes`; only with `spacings`.	`0.0`
`azimuth`	`float`	Collar grid rotation and hole direction, in degrees, as in `planned_drillholes`; only with `spacings`.	`0.0`
`dip`	`float`	Collar grid rotation and hole direction, in degrees, as in `planned_drillholes`; only with `spacings`.	`0.0`
`topography`	`Mesh`	Ground the collars of `spacings` sit on.	`None`
`truths`	`int or sequence of int`	Number of truths, realizations `0 .. truths - 1`, or their indices, such as from `select_realizations`. Index `k` is realization `k` of `simulator.simulate(targets, seed=seed)` whatever `n`, so indices picked from a summary simulated with `seed` name the same realizations.	`10`
`n`	`int`	Realizations per plan and truth.	`50`
`seed`	`int`	Seeds the truths; plan `i` on truth `k` simulates (and draws its sampling error) with seed `s(s(seed, k), i + 1)`, where `s(seed, k)` is the seed of realization `k` of a run.	`0`
`blocks`	`optional`	Summary rows, as in `SGS.simulate`; by default the targets.	`None`
`window`	`optional`	Summary rows, as in `SGS.simulate`; by default the targets.	`None`
`groups`	`optional`	Summary rows, as in `SGS.simulate`; by default the targets.	`None`
`sampling_error`	`float`	Relative standard deviation of the sampling error, 0 for exact samples.	`0.0`
`existing`	`bool`	Refit on the existing data plus the virtual samples (infill); otherwise on the virtual samples alone (greenfield).	`False`
`composite_length`	`float`	Composite length of the planned holes; by default the median distance between consecutive samples of a hole in the fitted data, which needs `holes` at fit. `numpy.inf` gives one composite per hole, as for a 2D model.	`None`
`quantiles`	`(float, float)`	Symmetric quantiles whose half-width over the mean is the MEE; (0.05, 0.95) gives 90 % confidence.	`(0.05, 0.95)`
`tolerances`	`sequence of float`	Relative tolerances of the precision columns.	`(0.15,)`

Returns:

Type Description

Table

One row per plan, truth and summary row: plan (the name, or the spacing as "10" or "10x20"), spacing (sqrt(along * across), the side of the square with the same area per hole; NaN for plans), realization (the truth's index), row (the row index, or the label of groups), truth, mean, mee (SimulationSummary.relative_error), cv, precision_<r> per tolerance, error and covered (as in SimulationSummary.validate).

Raises:

Type	Description
`InvalidInput`	If neither or both of `spacings` and `plans` are given, the geometry arguments come with `plans`, the simulator is not fitted or carries a trend, domains or a secondary, `targets` is not a BlockModel, `quantiles` is not a symmetric pair, `composite_length` is missing without fitted holes, or a plan has no composite inside the targets.

Notes

The realizations of each simulation run in parallel; plans and truths run one after the other, so the result does not depend on the thread count.

Examples:

>>> study = bt.spacing_study(sim, nodes, spacings=[10, 20], truths=3, window=(40, 40))
>>> curve = bt.uncertainty_curve("spacing", "mee", data=study)

used in