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 onconfig (
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

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}\] 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 Parameters
gather – Function gathering leaf’s noise realisation, defaults to num.median.
 Returns
Array of noise level at each quadtree leaf.
 Return type

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.

plot_syntheticNoise
¶  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

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 \(cov^{1}\).
 Type
numpy.ndarray
, size (nleaves
xnleaves
)

weight_matrix_L2
¶  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 \(cov_{focal}^{1}\).
 Type
numpy.ndarray
, size (nleaves
xnleaves
)

weight_vector
¶  Getter
(Cached) Weight vector from full covariance \(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
)
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.
modelCovarianceExponential
(distance, a, b)[source]¶ Exponential function model to approximate a positivedefinite covariance
We assume the following simple covariance model to describe the empirical noise observations:
\[cov(d) = c \cdot e^{\frac{d}{b}}\] Parameters
distance (float or
numpy.ndarray
) – Distance betweena (float) – Linear model coefficient
b (float) – Exponential model coefficient
 Returns
Covariance at
distance
 Return type

kite.covariance.
modelCovarianceExponentialCosine
(distance, a, b, c, d)[source]¶ Exponential function model to approximate a positivedefinite covariance
We assume the following simple covariance model to describe the empirical noise observations:
\[\begin{split}cov(d) = c \\cdot e^{\\frac{d}{b}} \\cdot \cos{\\frac{dc}{d}}\end{split}\] Parameters
distance (float or
numpy.ndarray
) – Distance betweena (float) – Linear model coefficient
b (float) – Exponential model coefficient
c (float) – Cosinus distance correction
c – Cosinus coefficient
 Returns
Covariance at
distance
 Return type

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
) – Wavenumbera (float) – Exponential model factor
b (float) – Fractional model factor