Covariance
Module¶

class
kite.
Covariance
(scene, config=<kite.covariance.CovarianceConfig object>)[source]¶ Construct the variancecovariance matrix of quadtree subsampled data.
Variance and covariance estimates are used to construct the weighting matrix to be used later in an optimization.
Two different methods exist to propagate fullresolution data variances and covariances of
kite.Scene.displacement
to the covariance matrix of the subsampled dataset: The distance between
kite.quadtree.QuadNode
leaf focal points,kite.covariance.Covariance.matrix_focal
defines the approximate covariance of the quadtree leaf pair.  The _accurate_ propagation of covariances by taking the mean of
every node pair pixel covariances. This process is computational
very expensive and can take a few minutes.
kite.covariance.Covariance.matrix_focal
Parameters:  quadtree (
Quadtree
) – Quadtree to work on  config (
CovarianceConfig
) – Config object

covariance_matrix
¶ Getter: (Cached) Covariance matrix calculated from mean of all pixel pairs inside the node pairs (full and accurate propagation). Type: numpy.ndarray
, size (nleaves
xnleaves
)

covariance_matrix_focal
¶ Getter: (Cached) Approximate Covariance matrix from quadtree leaf pair distance only. Fast, use for intermediate steps only and finallly use approach covariance_matrix
.Type: numpy.ndarray
, size (nleaves
xnleaves
)

covariance_model
¶  Covariance model parameters for
modelCovariance()
retrieved fromgetCovarianceFunction
.
Note
using this function implies several model fits: (1) fit of the spectrum and (2) the cosine transform. Not sure about the consequences, if this is useful and/or meaningful.
Getter: Get the parameters. Type: tuple, a
andb

covariance_model_rms
¶ Getter: RMS missfit between covariance_model
andgetCovarianceFunction
Type: float

covariance_spatial
¶ Getter: (Cached) Undocumented

covariance_spectral
¶ Getter: (Cached) Covariance function estimated directly from the power spectrum of displacement noise patch using the cosine transform. Type: tuple, numpy.ndarray
(covariance, distance)

export_weight_matrix
(filename)[source]¶  Export the full
weight_matrix
to an ASCII  file. The data can be loaded through
numpy.loadtxt()
.
Parameters: filename (str) – path to export to  Export the full

getCovariance
()[source]¶ Calculate the covariance function
Returns: The covariance and distance Return type: tuple

getLeafCovariance
(leaf1, leaf2)[source]¶  Get the covariance between
leaf1
andleaf2
from  distances.
Parameters: Returns: Covariance between
leaf1
andleaf2
Return type: float
 Get the covariance between

getLeafWeight
(leaf, model='focal')[source]¶  Get the total weight of
leaf
, which is the summation of  all single pair weights of
kite.Covariance.weight_matrix
.
\[w_{x} = \sum_i W_{x,i}\]Parameters: Returns: Weight of the leaf
Return type: float
 Get the total weight of

getQuadtreeNoise
(rstate=None, gather=<function nanmedian>)[source]¶ Create noise for a
Quadtree
Use
getSyntheticNoise()
to create datadriven noise on each quadtree leaf, summarized by :param gather:. :param gather: Function gathering leaf’s noise realisation,defaults to num.median.Returns: Array of noise level at each quadtree leaf. Return type: numpy.ndarray

getStructure
(method=None)[source]¶ Get the structure function
Parameters: method (str (optional)) – Either spatial or spectral, if None the method is taken from config Returns: (variance, distance) Return type: tuple

noise_coord
¶ Coordinates of the noise patch in local coordinates.
Setter: Set the noise coordinates Getter: Get the noise coordinates Type: numpy.ndarray
,[llE, llN, sizeE, sizeN]

noise_patch_size_km2
¶ Getter: Noise patch size in \(km^2\). Type: float

nthreads
¶  Number of threads (CPU cores) to use for full covariance
 calculation
Setting
nthreads
to0
uses all available cores (default).Setter: Sets the number of threads Type: int

plot
¶ Getter: (Cached) Simple overview plot to summarize the covariance estimations.

selectNoiseNode
()[source]¶ Choose noise node from quadtree the biggest
QuadNode
fromQuadtree
.Returns: A quadnode with the least signal. Return type: QuadNode

setConfig
(config=None)[source]¶ Sets and updated the config of the instance
Parameters: config ( CovarianceConfig
, optional) – New config instance, defaults to configuration provided by parentScene

structure_spatial
¶ Getter: (Cached) Undocumented

structure_spectral
¶ Getter: (Cached) Structure function derived from noise_patch
:type: tuple,numpy.ndarray
(structure_spectral, distance)Adapted from http://clouds.eos.ubc.ca/~phil/courses/atsc500/docs/strfun.pdf

syntheticNoise
(shape=(1024, 1024), dEdN=None, anisotropic=False, rstate=None)[source]¶ Create random synthetic noise from data noise power spectrum.
This function uses the power spectrum of the data noise (
noise_data
) (powerspecNoise()
) to create synthetic noise, e.g. to use it for data pertubation in optinmizations. The default sampling distances are taken fromkite.scene.Frame.dE
andkite.scene.Frame.dN
. They can be overwritten.Parameters:  shape (tuple, optional) – shape of the desired noise patch. Pixels in northing and easting (nE, nN), defaults to (1024, 1024).
 dEdN – The sampling distance in easting, defaults to
(
kite.scene.Frame.dE
,kite.scene.Frame.dN
).
Returns: synthetic noise patch
Return type:

weight_matrix
¶ Getter: (Cached) Weight matrix from full covariance \(\sqrt{cov^{1}}\). Type: numpy.ndarray
, size (nleaves
xnleaves
)

weight_matrix_focal
¶ Getter: (Cached) Approximated weight matrix from fast focal method \(\sqrt{cov_{focal}^{1}}\). Type: numpy.ndarray
, size (nleaves
xnleaves
)

weight_vector
¶ Getter: (Cached) Weight vector from full covariance \(\sqrt{cov^{1}}\). Type: numpy.ndarray
, size (nleaves
)

weight_vector_focal
¶ Getter: (Cached) Weight vector from fast focal method \(\sqrt{cov_{focal}^{1}}\). Type: numpy.ndarray
, size (nleaves
)
 The distance between
CovarianceConfig¶

class
kite.covariance.
CovarianceConfig
(*args, **kwargs)[source]¶ Undocumented.

♦
noise_coord
¶ numpy.ndarray
(pyrocko.guts_array.Array
), optionalNoise patch coordinates and size,

♦
model_coefficients
¶ tuple
ofpyrocko.guts.Any
objects, optionalCovariance model coefficients. Either two (exponential) or three (exponential and cosine term) coefficients.See also
modelCovariance()
.

♦
model_function
¶ builtins.str
(pyrocko.guts.StringChoice
), default:'exponential'
Covariance approximation function.

♦
sampling_method
¶ builtins.str
(pyrocko.guts.StringChoice
), default:'spatial'
Method for estimating the covariance and structure function.

♦
spatial_bins
¶ int
, default:75
Number of distance bins for spatial covariance sampling.

♦
spatial_pairs
¶ int
, default:200000
Number of random pairs for spatial covariance sampling.

♦
variance
¶ float
, optionalVariance of the model.

♦
adaptive_subsampling
¶ bool
, default:True
Adaptive subsampling flag for full covariance calculation.

♦
covariance_matrix
¶ numpy.ndarray
(pyrocko.guts_array.Array
), optionalCached covariance matrix, see
covariance_matrix
.

♦
Model Assumptions¶

kite.covariance.
modelPowerspec
(k, beta, D)[source]¶ Exponential linear model to estimate a loglinear power spectrum
We assume the following loglinear model for a measured power spectrum:
\[pow(k) = \frac{k^\beta}{D}\]Parameters:  k (float or
numpy.ndarray
) – Wavenumber  a (float) – Exponential model factor
 b (float) – Fractional model factor
 k (float or