gaussian_random_field.grf_module.grf_module
Gaussian Random Field (GRF) module.
Classes
GRF module for running INLA models on spatial data. |
Exceptions
A field with no spatial variation, which the SPDE model cannot be fitted to. |
- exception ConstantFieldError
Bases:
ValueErrorA field with no spatial variation, which the SPDE model cannot be fitted to.
- class GrfModule
Bases:
objectGRF module for running INLA models on spatial data.
- static constant_field(ds: Dataset, spde_mesh: SpdeMesh) Dataset
Build the output for a timestep with no spatial variation, without fitting it.
A field that takes one value everywhere has no spatial covariance to estimate, so
run_inla_model()refuses it. The fitted field of such an observation is the constant itself, though, so a caller that needs a complete record can write that rather than dropping the timestep - supraglacial lake cover in September sits at the detection floor across the catchment, and dropping those months leaves the melt seasons downstream unequal in length.The uncertainty is NaN rather than zero. No posterior was sampled, so the spread of the fitted value is not known here; claiming zero would assert that a constant observation is known exactly.
- Parameters:
ds (xr.Dataset) – A single-timestep point cloud, as
run_inla_model()takes.spde_mesh (SpdeMesh) – The mesh the record is being fitted onto, which sets the output vertices.
- Returns:
The same variables and dimensions
run_inla_model()returns, with the constant at every vertex and NaN for both uncertainties.- Return type:
xr.Dataset
- Raises:
ValueError – If the dataset does not have exactly one time step, or if a variable has no values at all or does vary across its points. A varying field has something to fit, so filling it in as a constant would discard a result.
- est_gp_inla_path = PosixPath('/app/src/gaussian_random_field/grf_module/est.GP.INLA.R')
- static flat_variables(ds: Dataset) list[str]
Names of the spatial variables that take one value everywhere at this timestep.
A dataset can hold several spatial variables, and they need not be flat together: supraglacial lake cover can sit at the detection floor across the catchment in a month when runoff still varies.
run_inla_model()refuses the whole timestep as soon as one of them is flat, so a caller that wants to fill those in needs to know which ones they are.A variable with no values at all is not reported here. There is no constant to fill it with, and
run_inla_model()is left to raise on it as before.- Parameters:
ds (xr.Dataset) – A single-timestep point cloud, as
run_inla_model()takes.- Returns:
The names of the spatial variables with no spatial variation, in the order they appear in the dataset.
- Return type:
list[str]
- run_inla_model(ds: Dataset, spde_mesh: SpdeMesh, reproducible: bool = False) Dataset
Run the INLA model on the specified mesh and point data.
- Parameters:
ds (xr.Dataset) –
The xarray dataset containing the point data to be modeled. This must have the following dimensions:
time (must be of length 1)
point_id (flattened spatial coordinates)
The dataset must also contain the following variables:
x
y
Any number of spatial variables, with dimensions (“time”, “point_id”)
spde_mesh (SpdeMesh) – The SPDE mesh object containing the mesh and SPDE model
reproducible (bool, optional) – If True, run INLA single-threaded in classic mode and seed the posterior sampling, so that repeated runs give identical results, e.g. for tests. Slower, and classic mode differs slightly from the default mode. Default False.
- Returns:
A dataset containing the model results, with dimensions:
time (length 1)
vertex_id (length equal to the number of vertices in the mesh)
The dataset will contain the following variables for each input spatial variable:
{name}: Output values of dimensions (“time”, “vertex_id”)
{name}_mean: Output mean of dimensions (“time”)
{name}_uncertainty: posterior sd of the fitted value at each vertex, dimensions (“time”, “vertex_id”)
{name}_uncertainty_mean: posterior sd of the spatial mean of the fitted field, dimensions (“time”)
- Return type:
xr.Dataset
- Raises:
ValueError – If the dataset does not have exactly one time step.
ConstantFieldError – If a variable takes the same value at every point. There is no spatial covariance to estimate, so the precision matrix is singular and INLA aborts the process rather than returning an error.