# Spatial Statistics¶

## autocorrelate¶

pymks.stats.autocorrelate(X_, periodic_axes=[], confidence_index=None, autocorrelations=None)

Computes the autocorrelation from a microstructure function.

Parameters: X (ND array) – The discretized microstructure function, an (n_samples, n_x, ..., n_states) shaped array where n_samples is the number of samples, n_x is thes patial discretization, and n_states is the number of local states. periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. confidence_index (ND array, optional) – array with same shape as X used to assign a confidence value for each data point. autocorrelations (list, optional) – list of spatial autocorrelatiions to be computed. For example [(0, 0), (1, 1)] computes the autocorrelations with local states 0 and 1. If no list is passed, all autocorrelations are computed. Autocorrelations for microstructure function X_.

Non-periodic example

>>> n_states = 2
>>> X = np.array([[[0, 0, 0],
...                [0, 1, 0],
...                [0, 0, 0]]])
>>> from pymks.bases import PrimitiveBasis
>>> prim_basis = PrimitiveBasis(n_states=n_states)
>>> X_ = prim_basis.discretize(X)
>>> X_auto = autocorrelate(X_, periodic_axes=(0, 1))
>>> X_test = np.array([[[0., 0., 0.],
...                   [0., 1./9, 0.],
...                   [0., 0., 0.]]])
>>> assert(np.allclose(np.real_if_close(X_auto[0, ..., 1]), X_test[0]))


## crosscorrelate¶

pymks.stats.crosscorrelate(X_, periodic_axes=None, confidence_index=None, crosscorrelations=None)

Computes the crosscorrelations from a microstructure function.

Parameters: X (ND array) – The discretized microstructure function, an (n_samples, n_x, ..., n_states) shaped array where n_samples is the number of samples, n_x is thes patial discretization, and n_states is the number of local states. periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. confidence_index (ND array, optional) – array with same shape as X used to assign a confidence value for each data point. crosscorrelations (list, optional) – list of cross-correlatiions to be computed. For example [(0, 1), (0, 2)] computes the cross-correlations with local states 0 and 1 as well as 0 and 2. If no list is passed, all cross-correlations are computed. Crosscorelations for microstructure function X_.

Examples

Test for 2 states.

>>> n_states = 2
>>> X = np.array([[[0, 1, 0],
...                [0, 1, 0],
...                [0, 1, 0]]])
>>> from pymks.bases import PrimitiveBasis
>>> prim_basis = PrimitiveBasis(n_states=n_states)
>>> X_ = prim_basis.discretize(X)
>>> X_cross = crosscorrelate(X_, periodic_axes=[0, 1])
>>> X_test = np.array([[[[1/3.], [0.], [1/3.]],
...                     [[1/3.], [0.], [1/3.]],
...                     [[1/3.], [0.], [1/3.]]]])
>>> assert(np.allclose(X_cross, X_test))


Test for 3 states

>>> n_states = 3
>>> prim_basis = PrimitiveBasis(n_states=n_states)
>>> X_ = prim_basis.discretize(X)
>>> assert(crosscorrelate(X_, periodic_axes=[0, 1]).shape == (1, 3, 3, 3))


Test for 4 states

>>> n_states = 4
>>> prim_basis = PrimitiveBasis(n_states=n_states)
>>> X_ = prim_basis.discretize(X)
>>> assert(crosscorrelate(X_, periodic_axes=[0, 1]).shape == (1, 3, 3, 6))


Test for 5 states

>>> n_states = 5
>>> prim_basis = PrimitiveBasis(n_states=n_states)
>>> X_ = prim_basis.discretize(X)
>>> assert(crosscorrelate(X_, periodic_axes=[0, 1]).shape == (1, 3, 3, 10))


## correlate¶

pymks.stats.correlate(X_, periodic_axes=None, confidence_index=None, correlations=None)

Computes the autocorrelations and crosscorrelations from a microstructure function.

Parameters: X (ND array) – The discretized microstructure function, an (n_samples, n_x, ..., n_states) shaped array where n_samples is the number of samples, n_x is thes patial discretization, and n_states is the number of local states. periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. confidence_index (ND array, optional) – array with same shape as X used to assign a confidence value for each data point. correlations (list, optional) – list of spatial correlatiions to be computed. For example [(0, 0), (1, 1), (0, 2)] computes the autocorrelations with local states 0 and 1 as well as the cross-correlation between 0 and 2. If no list is passed, all spatial correlations are computed. Autocorrelations and crosscorrelations for microstructure funciton X_.

Example

>>> from pymks import PrimitiveBasis
>>> prim_basis = PrimitiveBasis(2, [0, 1])
>>>
>>> np.random.seed(0)
>>> X = np.random.randint(2, size=(1, 3))
>>> X_ = prim_basis.discretize(X)
>>> X_corr = correlate(X_)
>>> X_result = np.array([[0, 0.5, 0],
...                      [1 / 3., 2 / 3., 0],
...                      [0, 0.5, 0.5]])
>>> assert np.allclose(X_corr, X_result)