Reconstruction cost

The estimated wall time and peak memory of a reconstruction, before it runs.

A front end that reconstructs a mask (the napari plugin, foambryo view MASK) tells its user, before the run, how long it should take and how much memory it should need; on a large tissue it can be minutes and tens of GiB. This module is the one place the estimate is made, so every front end gives the same one.

The estimate is a power law of the voxels handed to delaunay-watershed-3d: the mask's voxels times the anisotropy, because an anisotropic mask is resampled to cubic voxels of its finest spacing before meshing (voxels_handed_to_dw3d). Its constants (RECONSTRUCTION_COST_FIT) were fitted by least squares in log-log to the median wall time and peak memory of delaunay-watershed-3d's default reconstruction (min_distance 3, junction relocation on) at seven anchors (RECONSTRUCTION_COST_ANCHORS): two medians over the benchmark's simulated tissues of 2 to 10 cells, and five reconstructions of single tissues of 90 to 1 866 cells, on one machine (Apple M3 Max, 16 cores, 128 GiB; timings mostly on a shared, loaded machine, so provisional; peak memory reliable).

Each estimate is a central value and a band: the band factor is the largest in-sample ratio between an anchor and the fit, not a validated prediction interval. Time and memory also depend on the number of cells and on the tissue's shape, which the estimate does not see.

ReconstructionCostEstimate dataclass

ReconstructionCostEstimate(voxels: float, seconds: tuple[float, float, float], peak_gib: tuple[float, float, float])

A reconstruction's estimated wall time and peak memory, each (low, central, high).

Attributes:

Name	Type	Description
voxels	float	the voxels handed to delaunay-watershed-3d.
seconds	tuple[float, float, float]	wall time, in seconds.
peak_gib	tuple[float, float, float]	peak memory, in GiB (2**30 bytes).

text

text(dash: str = '-') -> str

In words, for example about 13 min (8 min-20 min) and 39 GiB (26 GiB-58 GiB).

A quantity whose band reads the same at both ends and in the middle is said once, without a band: a tiny tissue reads under 1 s and under 1 MiB, not about under 1 s (under 1 s-under 1 s). A central value under 1 s whose high end is not reads up to 2 s.

Parameters:

Name	Type	Description	Default
dash	str	the range's dash: a hyphen for an ASCII-only font such as the Polyscope panel's, an en dash (U+2013) elsewhere. Defaults to a hyphen.	'-'

Returns:

Name	Type	Description
str	str	the central time and memory, each with its band; a time in s, min or h, a memory in MiB or GiB.

voxels_handed_to_dw3d

voxels_handed_to_dw3d(shape: tuple[int, ...], spacing: tuple[float, float, float]) -> float

The voxels a reconstruction meets: the mask's (its last three axes), times the anisotropy.

An anisotropic mask is resampled to cubic voxels of its finest spacing before meshing, so its voxel count grows by max(spacing) / min(spacing).

Parameters:

Name	Type	Description	Default
shape	tuple[int, ...]	the mask's shape (nz, ny, nx); only the last three axes are counted.	required
spacing	tuple[float, float, float]	the voxel size (dz, dy, dx), positive, in any one unit (it is not checked).	required

Returns:

Name	Type	Description
float	float	the number of voxels handed to delaunay-watershed-3d.

estimate_reconstruction_cost

estimate_reconstruction_cost(voxels: float) -> ReconstructionCostEstimate

The estimated wall time and peak memory of reconstructing this many voxels (voxels_handed_to_dw3d).

Parameters:

Name	Type	Description	Default
voxels	float	the voxels handed to delaunay-watershed-3d (after resampling to cubic voxels).	required

Returns:

Name	Type	Description
ReconstructionCostEstimate	ReconstructionCostEstimate	seconds and peak_gib, each `(central / band_factor, central,
	ReconstructionCostEstimate	central * band_factor)withcentral = prefactor * voxels ** exponent(RECONSTRUCTION_COST_FIT`).