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)

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 [HGBLachiezeR22], (Section 3.1).

See also

• allowed_k_scattering_intensity()

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

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.

See also

• scattering_intensity()

structure_factor.tapered_estimators.select_tapered_estimator(debiased, direct)

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

• tapered_estimator_debiased_direct()

• tapered_estimator_debiased_undirect()

• tapered_estimator_core()

Return type

callable

structure_factor.tapered_estimators.tapered_estimator_core(k, point_pattern, taper)

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)

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)

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)

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)

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