grids

This package provides tools to define sampling grids. Currently, the code is restricted to orthogonal grids. This is not a limitation inherent to the proposed method, and it would not be very hard to generalize to non-orthogonal grids.

base

RectangularGrid(shape: tuple[int, ...], delta: tuple[float, ...] = None, mask: xp.ndarray = None, nvars: int = 1)

Generic class for hypercubic grids.

Attributes:

Name	Type	Description
n	tuple[int, ...]	spatial dimensions of the grid in number of points
delta	tuple[float, ...]	step sizes of the grid along all dimensions
nvars	(int, optional)	number of variates observed on the grid. Default is 1.
mask	ndarray	array of 0's (missing) and 1's (observed) indicating for each point of the grid whether the random field is observed at that location.
n_points	int	total number of points of the grid
ndim	int	number of spatial (or spatio-temporal) dimensions
extent	tuple[float, ...]	spatial extent of the grid, determined by the shape and the step sizes
imshow_extent	tuple[float, ...]	spatial extent for use as extent parameter of pyplot.imshow
lags_unique	ndarray	unique lags of the grid
grid_points	ndarray	array with the coordinates of the points of the grid
lag_matrix	ndarray	lags between points of the grid
fourier_frequencies	ndarray	array of the fourier frequencies of the grid
fourier_frequencies	ndarray	array of the fourier frequencies of the grid lags

Parameters:

Name	Type	Description	Default
shape	tuple[int, ...]	shape of the grid	required
delta	tuple[float, ...]	grid spacing in all dimensions. If None, set to 1 spatial unit in all dimensions.	None
mask	ndarray	mask of zero (missing) and ones (observed). If None, set to 1 everywhere.	None
nvars	int	number of variates of the random field sampled on this grid	1

Examples:

>>> grid_1d = RectangularGrid((64, ), (2., ))
>>> grid_2d = RectangularGrid((512, 128), (1.5, 2.8))
>>> grid = RectangularGrid((512, 512), nvars=2)

n: tuple[int, ...] property writable

size of the grid

ndim: int property

number of spatial dimensions of the grid

delta: tuple[float, ...] property writable

step sizes of the grid along all dimensions, in spatial units.

nvars: int property writable

number of variates. By default, 1, corresponding to a univariate random field.

mask: xp.ndarray property writable

array of 0's (missing) and 1's (observed) indicating for each point of the grid whether the random field is observed at that location. When nvars is 1 (univariate random field), mask should be an array with ndim dimensions. When nvars is greater than one, mask should have an extra dimension, the last one, with size nvars.

n_points: int property

total number of points of the grid, irrespective of the mask

extent: tuple[float, ...] property

spatial extent of the grid in spatial units

imshow_extent: list[float] property

extent parameter to pass to matplotlib.pyplot.imshow.

fourier_frequencies: xp.ndarray property

Grid of Fourier frequencies corresponding to the spatial grid. For instance, in dimension 1, for a grid with \(n\) points and a step size \(\delta\), $ \left( \frac{2k\pi}{\delta n} \right)_{k=0, \ldots, n - 1} . $

fourier_frequencies2: xp.ndarray property

Grid of Fourier frequencies corresponding to the grid of lags. For instance, in dimension 1, for a grid with \(n\) points and a step size \(\delta\), $ \left( \frac{2k\pi}{\delta (2n - 1)} \right)_{k=0, \ldots, 2n - 2} . $

lags_unique: xp.ndarray cached property

shape (2 * n1 + 1, ..., 2 * nd + 1), with d the number of dimensions of the grid.

grid_points: xp.ndarray property

list of grid ticks.

lag_matrix: xp.ndarray cached property

shape (n_points, n_points, n_dimensions), matrix of lags between the points of the grids ordered according to their coordinates. The matrix may be very large for large grid sizes.

spatial_kernel(taper_values: xp.ndarray = None) cached

Compute the spatial kernel from the grid's mask and the taper values.

Parameters:

Name	Type	Description	Default
taper_values	ndarray	Taper values applied to data on the grid	None

Returns:

Type	Description
spatial_kernel	Shape (2 * n1 - 1, ..., 2 * nd - 1)

covariance_matrix(model: CovarianceModel)

Compute the full covariance matrix under the provided covariance model, while accounting for the mask.

Parameters:

Name	Type	Description	Default
model	CovarianceModel	Covariance model	required

Returns:

Name	Type	Description
covmat	ndarray	shape (n_points, n_points), covariance matrix

autocov(model: CovarianceModel)

Compute the covariance function on the grid lags.

Parameters:

Name	Type	Description	Default
model	CovarianceModel	covariance model used	required

Returns:

Name	Type	Description
cov	ndarray	Shape (2 * n1 - 1, 2 * n2 - 1, ..., 2 * nd - 1) if the grid has shape (n1, ..., nd), see notes below. Covariance model evaluated on a grid of lags determined by the spatial rectangular grid.

Notes

For instance, in dimension 1, the covariance model is evaluated at lags 0, 1, ..., n - 1, - n + 1, ..., -1.

autocov_separable(model)

Compute the autocovariance, making use of separability of the model for increased computational efficiency.

Parameters:

Name	Type	Description	Default
model		covariance model. Should be separable.	required

Returns:

Name	Type	Description
cov	ndarray	Autocovariance for the grid's lags.

spatial_kernel

spatial_kernel(g: xp.ndarray, m: Tuple[int, int] = (0, 0), n_spatial_dim: int = None) -> xp.ndarray

Compute the spatial kernel, cg in the paper, via FFT for computational efficiency.

Parameters:

Name	Type	Description	Default
g	ndarray	mask of observations, or more generally pointwise modulation e.g. a taper or the product of a taper with an observation mask. Shape (n1, ..., nd) for univariate data in d-dimensional space Shape (n1, ..., nd, p) for p-variate data in d-dimensional space	required
n_spatial_dim	int	Number of dimensions that are spatial dimensions. In the multivariate case, the last dimension is used for the different variates.	None
m	Tuple[int, int]	offset in frequency indices	(0, 0)

Returns:

Type	Description
cg	Spatial kernel. Shape (2 * n1 + 1, ..., 2 * nd + 1) for univariate data Shape (2 * n1 + 1, ..., 2 * nd + 1, p, p) for p-variate data

Examples:

>>> g = xp.ones(10)
>>> spatial_kernel(g)
array([1. , 0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1, 0.1, 0.2, 0.3,
       0.4, 0.5, 0.6, 0.7, 0.8, 0.9])
>>> g = xp.ones((10, 2))
>>> spatial_kernel(g, n_spatial_dim=1).shape
(19, 2, 2)

Notes

The formula for the spatial kernel in dimension 1 is,

\[ c_g(\tau) = \sum_{s}{g_s g_{s + \tau}}, \quad \tau=0, \ldots, n - 1, - (n - 1), \ldots, -1. \]