# Tapered estimators

Collection of functions that compute tapered estimates of the structure factor $$S(k)$$ of a stationary point process given one realization.

Some tapers (tapering function) are available in Tapers.

structure_factor.tapered_estimators.scattering_intensity(k, point_pattern, debiased=False, direct=True)[source]

Compute the scattering intensity estimator $$\widehat{S}_{\mathrm{SI}}$$ of the structure factor evaluated at at k, from one realization of a stationary point process encapsulated in point_pattern.

Parameters
• k (numpy.ndarray) – Array of size $$n \times d$$, where $$d$$ is the ambient dimension and $$n$$ the number of points where the estimator is evaluated.

• point_pattern (PointPattern) – Realization of the underlying stationary point process.

• debiased (bool, optional) – trigger the use of debiased tapered estimators. Defaults to False.

• direct (bool, optional) – if debiased is True, trigger the use of the tapered direct/undirect debiased tapered estimators. Defaults to True.

Returns

Vector of size $$n$$ containing the evaluation of scattering intensity estimator $$\widehat{S}_{\mathrm{SI}}(k)$$.

Return type

numpy.ndarray

Definition

The scattering intensity estimator $$\widehat{S}_{\mathrm{SI}}, constructed from a realization :math:$${x_1, dots, x_N} subset mathbb{R}^d, is defined by,

$\widehat{S}_{\mathrm{SI}}(\mathbf{k}) = \frac{1}{N}\left\lvert \sum_{j=1}^N \exp(- i \left\langle \mathbf{k}, \mathbf{x_j} \right\rangle) \right\rvert^2 .$

For more details we refer to , (Section 3.1).

structure_factor.tapered_estimators.allowed_k_scattering_intensity(d, L, k_max=5, meshgrid_shape=None)[source]

Return a subset of the d-dimensional allowed wavevectors corresponding to a cubic window of length L.

Parameters
• d (int) – Dimension of the space containing the point process.

• L (numpy.ndarray) – 1d array of size d, where each element correspond to the length of a side of the BoxWindow containing the point process realization.

• k_max (float, optional) – Supremum of the components of the allowed wavevectors on which the scattering intensity to be evaluated; i.e., for any allowed wavevector $$\mathbf{k}=(k_1,...,k_d)$$, $$k_i \leq k\_max$$ for all i. This implies that the maximum of the output vector k_norm will be approximately equal to the norm of the vector $$(k\_max, ... k\_max)$$. Defaults to 5.

• meshgrid_shape (tuple, optional) – Tuple of length d, where each element specifies the number of components over an axis. These axes are crossed to form a subset of $$\mathbb{Z}^d$$ used to construct a set of allowed wavevectors. i.g., if d=2, setting meshgid_shape=(2,3) will construct a meshgrid of allowed wavevectors formed by a vector of 2 values over the x-axis and a vector of 3 values over the y-axis. Defaults to None, which will run the calculation over all the allowed wavevectors. Defaults to None.

Returns

• k : np.array with d columns where each row is an allowed wavevector.

Return type

tuple (numpy.ndarray, list)

Definition

The set of the allowed wavevectors $$\{\mathbf{k}_i\}_i$$ is defined by

$\{\mathbf{k}_i\}_i = \{\frac{2 \pi}{L} \mathbf{n} ~ ; ~ \mathbf{n} \in (\mathbb{Z}^d)^\ast \}.$

Note that the maximum n and the number of output allowed wavevectors returned by allowed_k_scattering_intensity(), are specified by the input parameters k_max and meshgrid_shape.

structure_factor.tapered_estimators.select_tapered_estimator(debiased, direct)[source]

Select the tapered estimator of the structure factor.

Parameters
• debiased (bool) – Trigger the use of a debiased tapered estimator.

• direct (bool) – If debiased is True, trigger the use of the direct/undirect debiased tapered estimator.

Returns

According to debiased and direct return

Return type

callable

structure_factor.tapered_estimators.tapered_estimator_core(k, point_pattern, taper)[source]

Compute the tapered estimator $$S_{TP}(t, k)$$ of the structure factor $$S(k)$$ evaluated at k w.r.t. the taper $$t$$ and the realization point_pattern of the underlying stationary point process.

Parameters
• k (numpy.ndarray) – Array of size $$n \times d$$, where $$d$$ is the ambient dimension and $$n$$ the number of points where the estimator is evaluated.

• point_pattern (PointPattern) – Realization of the underlying stationary point process.

• taper (object) – Class with static method or instance with method .taper(x, window) corresponding to $$t(x, W)$$.

Returns

Evaluation of the tapered estimator $$S_{TP}(t, k)$$ at k.

Return type

numpy.ndarray

Definition

The tapered estimator $$S_{TP}(t, k)$$, constructed from a realization $$\{x_1, \dots, x_N\} \subset \mathbb{R}^d$$, is defined by,

$S_{TP}(t, k) = \frac{1}{\rho} \left\lvert \sum_{j=1}^N t(x_j, W) \exp(- i \left\langle k, x_j \right\rangle) \right\rvert^2,$

for $$k \in \mathbb{R}^d$$.

structure_factor.tapered_estimators.tapered_estimator_debiased_direct(k, point_pattern, taper)[source]

Compute the direct debiased tapered estimator $$S_{DDTP}(t, k)$$ of the structure factor $$S(k)$$ evaluated at k w.r.t. the taper $$t$$ and the realization point_pattern of the underlying stationary point process.

$S_{DDTP}(t, k) = \frac{1}{\rho} \left\lvert \sum_{j=1}^N t(x_j, W) \exp(- i \left\langle k, x_j \right\rangle) - \rho F[t(\cdot, W)](k) \right\rvert^2$

where $$x_{1}, \dots, x_{N}$$ corresponds to point_pattern.points, $$W$$ corresponds to the window point_pattern.window and $$\rho$$ is the intensity of the underlying stationary point process.

The direct debiased estimator $$S_{DDTP}(t, k)$$ is positive and asymptotically unbiased as the observation window $$W$$ grows to $$\mathbb{R}^d$$.

Parameters
• k (numpy.ndarray) – Array of size $$n \times d$$, where $$d$$ is the ambient dimension and $$n$$ the number of points where the estimator is evaluated.

• point_pattern (PointPattern) – Realization of the underlying stationary point process.

• taper (object) –

class instance with two methods:

• .taper(x, window) corresponding to the taper function $$t(x, W)$$ such that $$\|t(\cdot, W)\|_2 = 1$$.

• .ft_taper(k, window) corresponding to the Fourier transform $$\mathcal{F}[t(\cdot, W)](k)$$ of the taper function.

Returns

Vector of size $$n$$ containing the evaluation of the direct debiased estimator $$S_{DDTP}(t, k)$$.

Return type

numpy.ndarray

structure_factor.tapered_estimators.tapered_estimator_debiased_undirect(k, point_pattern, taper)[source]

Compute the undirect debiased tapered estimator $$S_{UDTP}(t, k)$$ of the structure factor $$S(k)$$ evaluated at k w.r.t. the taper $$t$$ and the realization point_pattern of the underlying stationary point process.

$S_{UDTP}(t, k) = \frac{1}{\rho} \left\lvert \sum_{j=1}^N t(x_j, W) \exp(- i \left\langle k, x_j \right\rangle) \right\rvert^2 - \rho \left\lvert F[t(\cdot, W)](k)) \right\rvert^2$

where $$x_{1}, \dots, x_{N}$$ corresponds to point_pattern.points, $$W$$ corresponds to the window point_pattern.window and $$\rho$$ is the intensity of the underlying stationary point process.

The undirect debiased estimator $$S_{UDTP}(t, k)$$ is not guaranteed to be positive but is asymptotically unbiased as the observation window $$W$$ grows to $$\mathbb{R}^d$$.

Parameters
• k (numpy.ndarray) – Array of size $$n \times d$$, where $$d$$ is the ambient dimension and $$n$$ the number of points where the estimator is evaluated.

• point_pattern (PointPattern) – Realization of the underlying stationary point process.

• taper (object) –

class instance with two methods:

• .taper(x, window) corresponding to the taper function $$t(x, W)$$ such that $$\|t(\cdot, W)\|_2 = 1$$.

• .ft_taper(k, window) corresponding to the Fourier transform $$\mathcal{F}[t(\cdot, W)](k)$$ of the taper function.

Returns

Vector of size $$n$$ containing the evaluation of the direct debiased estimator $$S_{UDTP}(t, k)$$.

Return type

numpy.ndarray

structure_factor.tapered_estimators.tapered_dft(k, point_pattern, taper)[source]

Compute the tapered discrete Fourier transform (tapered DFT) associated with point_pattern evaluated at k, using taper $$t$$.

$\sum_{j=1}^N t(x_j, W) \exp(- i \langle k, x_j \rangle),$

where $$x_{1}, \dots, x_{N}$$ corresponds to point_pattern.points and $$W$$ corresponds to the window point_pattern.window.

Parameters
• k (numpy.ndarray) – Array of size $$n \times d$$, where $$d$$ is the ambient dimension and $$n$$ the number of points where the tapered DFT is evaluated.

• point_pattern (PointPattern) – Realization of the underlying stationary point process.

• taper (object) – class with static method or instance with method .taper(x, window) corresponding to $$t(x, W)$$ such that $$\|t(\cdot, W)\|_2 = 1$$.

Returns

Evaluation of the DFT of the taper h

Return type

numpy.ndarray

structure_factor.tapered_estimators.periodogram_from_dft(dft)[source]

Compute the square absolute value abs(dft)**2 of the discrete Fourier transform dft.

$\left\lvert \sum_{j=1}^N t(x_j) \exp(- i \langle k, x_j \rangle) \right\rvert ^ 2,$
Parameters

dft (numpy.ndarray) – Discrete Fourier transform computed via tapered_dft().

Returns

abs(dft)**2`.

Return type

numpy.ndarray