# Spatial Statistics¶

## autocorrelate¶

pymks.stats.autocorrelate(X, basis, periodic_axes=[], n_jobs=1, confidence_index=None, autocorrelations=None)

Computes the autocorrelation from a microstructure function.

Parameters: X (ND array) – The microstructure, an (n_samples, n_x, ...) shaped array where n_samples is the number of samples and n_x is the spatial discretization. basis (class) – an instance of a bases class periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. n_jobs (int, optional) – number of parallel jobs to run, only used if pyfftw is installed. 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 autocorrelations to be computed corresponding to the states in basis.n_states. For example, if basis.n_states=[0, 2], then autocorrelations=[(0, 0), (2, 2)] computes the autocorrelations for the states 0 and 2. If no list is passed, all autocorrelations in basis.n_states are computed. Autocorrelations for a microstructure.

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_auto = autocorrelate(X, prim_basis, 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, basis, periodic_axes=None, n_jobs=1, confidence_index=None, crosscorrelations=None)

Computes the crosscorrelations from a microstructure function.

Parameters: X (ND array) – The microstructure, an (n_samples, n_x, ...) shaped array where n_samples is the number of samples and n_x is the spatial discretization.s. basis (class) – an instance of a bases class periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. n_jobs (int, optional) – number of parallel jobs to run, only used if pyfftw is installed. 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-correlations to be computed corresponding to the states in basis.n_states. For example if basis.n_states=[2, 4, 6] then crosscorrelations=[(2, 4), (2, 6)] computes the cross-correlations with local states 2 and 4 as well as 2 and 6. If no list is passed, all cross-correlations in basis.n_states are computed. Crosscorelations for a microstructure.

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_cross = crosscorrelate(X, prim_basis, 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)
>>> assert(crosscorrelate(X, prim_basis,
...        periodic_axes=[0, 1]).shape == (1, 3, 3, 3))


Test for 4 states

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


Test for 5 states

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


## correlate¶

pymks.stats.correlate(X, basis, periodic_axes=None, n_jobs=1, confidence_index=None, correlations=None)

Computes the autocorrelations and crosscorrelations from a microstructure function.

Parameters: X (ND array) – The microstructure, an (n_samples, n_x, ...) shaped array where n_samples is the number of samples and n_x is the spatial discretization. basis (class) – an instance of a bases class periodic_axes (list, optional) – axes that are periodic. (0, 2) would indicate that axes x and z are periodic in a 3D microstrucure. n_jobs (int, optional) – number of parallel jobs to run, only used if pyfftw is installed. 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 _check_shapes to be computed corresponding to the states in basis.n_states. For example, it n_states=[0, 2, 5] [(0, 0), (2, 2), (0, 5)] computes the autocorrelations with local states 0 and 2 as well as the cross-correlation between 0 and 5. If no list is passed, all spatial correlations are computed. Autocorrelations and crosscorrelations for a microstructure.

Example

>>> from pymks import PrimitiveBasis
>>> prim_basis = PrimitiveBasis(2, [0, 1])
>>>
>>> np.random.seed(0)
>>> X = np.random.randint(2, size=(1, 3))
>>> X_corr = correlate(X, prim_basis)
>>> 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)