协方差#

class astropy.nddata.Covariance(array=None, data_shape=None, assume_symmetric=False, unit=None)[源代码]#

基类：NDUncertainty

用于存储、操作和协方差矩阵I/O的通用实用程序。

协方差矩阵是对称的， \(\Sigma_{ij} = \Sigma_{ji}\) . 因此，该对象仅使用 scipy.sparse.csr_matrix . 默认情况下，实例化将检查对称性，并在矩阵不对称时发出警告。可以使用 assume_symmetric 关键字然而，由于数据是如何存储的，对称性 always imposed 在矩阵上。也就是说，如果使用非对称矩阵来实例化 Covariance 对象时，存储的数据将产生与原始输入不同的矩阵。

高维数组的协方差矩阵总是假设存储在行优先索引之后。例如，协方差值 \(\Sigma_{ij}\) 对于大小的图像 \((N_x,N_y)\) 是图像像素之间的协方差 \(I_{x_i,y_i}\) 和 \(I_{x_j,y_j}\) ，在哪里 \(i = x_i + N_x y_i\) 同样， \(j = x_j + N_x y_j\) .

看到协方差以获取更多文档和示例。

参数:

array : array_like , csr_matrixnumpy：数组_ike，csr_matrix: 要存储的协方差矩阵。如果数组不是 csr_matrix 例如，它必须可以转换为一个。要匹配的调用序列 NDUncertainty , array 默认值为无，但数组 must 用于此 Covariance object.
data_shape : tuple ，可选tuple，可选: 协方差数据适用于具有此形状的更高维度阵列。例如，如果协方差数据针对具有形状的2D图像 (nx,ny) ，设置 data_shape=(nx,ny) ;那么协方差数组的形状必须是 (nx*ny, nx*ny) . 如果无，则忽略任何更高维度。
assume_symmetric : bool ，可选可选的布尔: 假设矩阵是对称的。这意味着不会执行对称性检查，并且如果矩阵不对称，用户也不会收到警告。
unit : astropy:unit-like ，可选AstPy：单元式，可选: 协方差值的单位。

加薪:

TypeError: 如果输入数组不是 csr_matrix 对象，并且无法转换为对象。
ValueError: 如果 data_shape 并且输入协方差矩阵 array 不具有预期的形状或如果 array 没有。

属性摘要

`data_index_map`	将协方差矩阵每个轴上的索引映射到相关数据阵列的形状的数组。
`data_shape`	与此协方差数组关联的数据数组的预期形状。
`nnz`	完整协方差矩阵中非零（NNZ）元素的数量， including 上下三角形。
`quantity`	协方差矩阵作为密集的 `Quantity` object.
`shape`	具有协方差矩阵形状的二元组
`stored_nnz`	对象存储的非零元素的数量，仅计算上三角形中的非零元素。
`uncertainty_type`	`"cov"` : `Covariance` 实现协方差矩阵。
`variance`	协方差矩阵的对角线。

方法总结

`apply_new_variance` （var）	使用相同的相关系数，返回新的 `Covariance` 具有所提供方差的对象。
`coordinate_data`([reshape])	以坐标格式构建具有非零协方差分量的数据数组。
`copy` ()	返回此Covariance对象的副本。
`covariance_to_data_indices`(i, j)	给定协方差矩阵两个轴上的索引，返回数据数组中的相关索引。
`data_to_covariance_indices`(i, j)	给定源数据数组中元素的索引，返回具有相关协方差的矩阵坐标。
`find`([correlation])	中查找非零值 full 协方差矩阵（不仅仅是上三角形）。
`from_array`(covar[, cov_tol, rho_tol])	从数组定义协方差对象。
`from_matrix_multiplication`(T, covar, **kwargs)	构造矩阵相乘产生的协方差矩阵。
`from_samples`(samples[, cov_tol, rho_tol])	使用离散样本构建协方差对象。
`from_table`(triu_covar)	从一个表格中构造协方差矩阵，该表格中包含协方差矩阵上三角形的非零元素（坐标格式）。
`from_variance`(variance, **kwargs)	使用提供的方差构建对角协方差矩阵。
`match_to_data_slice`(data_slice)	返回一个新 `Covariance` 与其父数据数组的切片匹配的实例。
`revert_correlation`(var, rho[, assume_symmetric])	将方差矩阵和相关矩阵恢复为协方差矩阵。
`to_correlation`(cov[, assume_symmetric])	通过将每个元素除以方差，将协方差矩阵转换为相关矩阵。
`to_dense`([correlation])	将完整的协方差矩阵返回为 `numpy.ndarray` 对象（“密集”数组）。
`to_sparse`([correlation])	将完整的协方差矩阵返回为 `csr_matrix` object.
`to_table` ()	返回协方差数据 `Table` 使用坐标格式。

属性文档

data_index_map#: 将协方差矩阵每个轴上的索引映射到相关数据阵列的形状的数组。

data_shape#: 与此协方差数组关联的数据数组的预期形状。

nnz#: 完整协方差矩阵中非零（NNZ）元素的数量， including 上下三角形。

quantity#: 协方差矩阵作为密集的 Quantity object.

shape#: 具有协方差矩阵形状的二元组

stored_nnz#: 对象存储的非零元素的数量，仅计算上三角形中的非零元素。

uncertainty_type#: "cov" : Covariance 实现协方差矩阵。

variance#: 协方差矩阵的对角线。

方法文件

apply_new_variance(var)[源代码]#

使用相同的相关系数，返回新的 Covariance 具有所提供方差的对象。

参数:

var : array_likeNumpy：ARRAY_LIKE: 方差载体。必须有与此匹配的长度 Covariance 实例;例如，如果此实例是 cov ，的长度 var 必须 cov.shape[0] ). 请注意，如果协方差针对更高维度的数据，则此方差数组 must 被压缩到1D。

返回:

Covariance: 形状和相关系数与该对象相同，但具有提供的方差的协方差矩阵。

加薪:

ValueError: 如果方差向量的长度不正确，则引发。

coordinate_data(reshape=False)[源代码]#

以坐标格式构建具有非零协方差分量的数据数组。

坐标格式意味着协方差矩阵数据以三列形式提供， \(\Sigma_{ij}\) 以及（0-索引）矩阵坐标 \(i,j\) .

此过程主要用于构建存储的数据阵列时。与类约定相匹配，返回的数据仅包括上三角形。

参数:

reshape : bool ，可选可选的布尔: 如果 reshape 是 True 和 data_shape 定义了， \(i,j\) 索引转换为预期的数据数组索引;请参阅 covariance_to_data_indices() . 这些可以使用以下方式恢复到协方差矩阵中的坐标 data_to_covariance_indices() .

返回:

i, j : tuple , numpy.ndarrayPython：tuple，numpy. ndray: 行和列索引， \(i,j\) ：协方差矩阵的。如果进行重塑，这些都是沿着每个重塑轴具有索引数组的二元组。
cij : numpy.ndarraynumpy.ndarray: 协方差， \(\Sigma_{ij}\) ，在索引处的数组元素之间 \(i\) 和 \(j\) .

加薪:

ValueError: 如果 reshape 是真的，但 data_shape 未定义。

copy()[源代码]#

返回此Covariance对象的副本。

返回:

Covariance: 当前协方差矩阵的副本。

covariance_to_data_indices(i, j)[源代码]#

给定协方差矩阵两个轴上的索引，返回数据数组中的相关索引。这是相反的 data_to_covariance_indices() .

参数:

i : ndarray恩达雷: 1D阵列，索引沿着协方差矩阵的第一轴。必须位于范围 \(0...n-1\) ，在哪里 \(n\) 是协方差矩阵轴的长度。
j : ndarray恩达雷: 1D阵列，索引沿着协方差矩阵的第二个轴。必须位于范围 \(0...n-1\) ，在哪里 \(n\) 是协方差矩阵轴的长度。

返回:

i_data, i_data : tuple , numpy.ndarrayPython：tuple，numpy. ndray: 如果 data_shape 未定义，则输入数组将简单返回（而不是复制）。否则，代码使用 unravel_index 来计算相关的数据数组索引;二元组中的每个元素本身就是一个 \(N_{\rm dim}\) 数组，数据数组的每个维度一个数组。

加薪:

ValueError: 如果提供的索引超出协方差矩阵的范围，则引发。

data_to_covariance_indices(i, j)[源代码]#

给定源数据数组中元素的索引，返回具有相关协方差的矩阵坐标。这是相反的 covariance_to_data_indices() .

参数:

i : array_like , tuplenumpy：Array_ike，pPython：tuple: 的元组 \(N_{\rm dim}\) 类数组对象，提供N维数据数组中元素的索引。如果 data_shape 未定义，在这种情况下，值必须在 \(0...n-1\) ，在哪里 \(n\) 是数据数组的长度。
j : array_like , tuplenumpy：Array_ike，pPython：tuple: 相同 i ，但提供访问协方差的第二组坐标。

返回:

i_covar, j_covar : numpy.ndarraynumpy.ndarray: 数组，提供与所提供的数据数组坐标相关的协方差矩阵中的索引。如果 data_shape 未定义，则输入数组将简单返回（而不是复制）。否则，代码使用 ravel_multi_index 计算相关的协方差指数。

加薪:

ValueError: 如果提供的索引超出数据数组的范围，或者如果 i 或 j 二元组不是 \(N_{\rm dim}\) .

find(correlation=False)[源代码]#

中查找非零值 full 协方差矩阵（不仅仅是上三角形）。

这是一个简单的包装 to_sparse 和 find .

参数:

correlation : bool ，可选可选的布尔: 返回相关数据而不是协方差数据的标志。请注意，将此设置为 True 并 not 还返回方差载体。

返回:

i, j : numpy.ndarraynumpy.ndarray: 包含协方差（或相关性）矩阵中非零值的索引坐标的数组。
c : numpy.ndarraynumpy.ndarray: 位于提供的非零协方差（或相关性）矩阵值 i,j 坐标

classmethod from_array(covar, cov_tol=None, rho_tol=None, **kwargs)[源代码]#

从数组定义协方差对象。

备注

该方法与直接实例化方法之间的唯一区别（即， Covariance(array=covar) ）是它可以用于对协方差值和/或相关系数施加容差。

参数:

covar : array_likeNumpy：ARRAY_LIKE: 包含协方差数据的数组。对象必须是 csr_matrix 或者可以转换为对象的对象。它还必须是二维的和方形的。
cov_tol : float ，可选浮动，可选: 任何的绝对价值 covariance 小于此的矩阵条目被假设等于（并设置为）0。
rho_tol : float ，可选浮动，可选: 任何的绝对价值 correlation coefficient 小于此假设等于（并设置为）0。
**kwargs : dict ，可选Python：Dict，可选: 直接传递到主实例化方法。

返回:

Covariance: 使用提供的数组构建的协方差矩阵。

classmethod from_matrix_multiplication(T, covar, **kwargs)[源代码]#

构造矩阵相乘产生的协方差矩阵。

对数据集的线性操作（例如，合并或平滑）可以写成形式的矩阵相乘

\[{\mathbf y} = {\mathbf T}\ {\mathbf x},\]

where \({\mathbf T}\) is a transfer matrix of size \(N_y\times N_x\), \({\mathbf x}\) is a vector of size \(N_x\), and \({\mathbf y}\) is a vector of length \({N_y}\) that results from the multiplication. If \({\mathbf \Sigma}_x\) is the covariance matrix for \({\mathbf x}\), then the covariance matrix for \({\mathbf Y}\) is

\[{\mathbf \Sigma}_y = {\mathbf T}\ {\mathbf \Sigma}_x\ {\mathbf T}^\top.\]

如果 covar 作为长度载体提供 \(N_x\) ，假设的元素 \({\mathbf X}\) 是独立的，并且提供的载体给出 variance 在每个元素中;即，提供的数据代表的对角线 \({\mathbf \Sigma}\) .

参数:

T : csr_matrix , ndarraycsr_matrix，ndarray: 转移矩阵。见上文。
covar : csr_matrix , ndarraycsr_matrix，ndarray: 协方差矩阵见上文。
**kwargs : dict ，可选Python：Dict，可选: 直接传递到主实例化方法。

返回:

Covariance: 矩阵相乘产生的协方差矩阵。

加薪:

ValueError: 如果提供的数组不是二维的或者存在形状不匹配，则引发。

classmethod from_samples(samples, cov_tol=None, rho_tol=None, **kwargs)[源代码]#

使用离散样本构建协方差对象。

协方差使用以下公式生成： cov 对于一组离散采样数据 \(N\) - 维参数空间。

参数:

samples : ndarray恩达雷: 数组，其中的样本是从 \(N\) - 维参数空间。输入数组的形状必须是 \(N_{\rm par}\times N_{\rm samples}\) .
cov_tol : float ，可选浮动，可选: 任何的绝对价值 covariance matrix 小于此值的条目被假设等于（并设置为）0。
rho_tol : float ，可选浮动，可选: 任何的绝对价值 correlation coefficient 小于此假设等于（并设置为）0。
**kwargs : dict ，可选Python：Dict，可选: 直接传递到主实例化方法。

返回:

Covariance: 一个 \(N_{\rm par}\times N_{\rm par}\) 使用提供的样本构建协方差矩阵。

加薪:

ValueError: 如果输入数组不是2D或样本数（第二轴的长度）小于2，则引发。

classmethod from_table(triu_covar)[源代码]#

从一个表格中构造协方差矩阵，该表格中包含协方差矩阵上三角形的非零元素（坐标格式）。

这是的逆操作 to_table() . 该类可以读取其他程序编写的协方差数据 as long as they have a commensurate format ;看到 to_table() .

参数:

triu_covar : Table表: 坐标格式的协方差矩阵上三角形的非零元素;请参阅 to_table() .

返回:

Covariance: 根据列表数据构建的协方差矩阵。

加薪:

ValueError: 如果 triu_covar.meta 是 None ，如果提供的方差数组没有正确的大小，或者如果数据是多维的并且表列没有正确的形状。

classmethod from_variance(variance, **kwargs)[源代码]#

使用提供的方差构建对角协方差矩阵。

参数:

variance : ndarray恩达雷: 方差向量。
**kwargs : dict ，可选Python：Dict，可选: 直接传递到主实例化方法。

返回:

Covariance: 对角线协方差矩阵。

match_to_data_slice(data_slice)[源代码]#

返回一个新 Covariance 与其父数据数组的切片匹配的实例。

参数:

data_slice : slice , array_like切片，numpy：数组_类似: 任何可以用来切割 numpy.ndarray . 要使用模仿访问numpy数组元素的语法生成切片，请使用 numpy.s_ ;参见示例 here .

返回:

Covariance: 切片数据数组的新协方差对象。

static revert_correlation(var, rho, assume_symmetric=False)[源代码]#

将方差矩阵和相关矩阵恢复为协方差矩阵。

这是的反向操作 to_correlation .

参数:

var : ndarray恩达雷: 方差载体。长度必须与对角线匹配 rho .
rho : ndarray , csr_matrixndray，csr_matrix: 相关矩阵。对角线的长度必须与 var .
assume_symmetric : bool ，可选可选的布尔: 假设矩阵是对称的。这意味着不会执行对称性检查，并且如果矩阵不对称，用户也不会收到警告。

返回:

csr_matrix: 协方差矩阵

static to_correlation(cov, assume_symmetric=False)[源代码]#

通过将每个元素除以方差，将协方差矩阵转换为相关矩阵。

Specifically, extract var (\(V_i = C_{ii} \equiv \sigma^2_i\)) and convert cov from a covariance matrix with elements \(C_{ij}\) to a correlation matrix with \(\rho_{ij}\) such that

\[C_{ij} \equiv \rho_{ij} \sigma_i \sigma_j.\]

要将方差矩阵和相关矩阵恢复回协方差矩阵，请使用 revert_correlation() .

参数:

cov : array_likeNumpy：ARRAY_LIKE: 要转换的协方差矩阵。必须是 csr_matrix 实例或可转换为一个。
assume_symmetric : bool ，可选可选的布尔: 假设矩阵是对称的。这意味着不会执行对称性检查，并且如果矩阵不对称，用户也不会收到警告。

返回:

var : numpy.ndarraynumpy.ndarray: 变差矢量
rho : csr_matrixcsr_matrix: 相关矩阵

加薪:

ValueError: 如果输入数组不是2D且方形，则引发。

to_dense(correlation=False)[源代码]#

将完整的协方差矩阵返回为 numpy.ndarray 对象（“密集”数组）。

参数:

correlation : bool ，可选可选的布尔: 返回相关矩阵而不是协方差矩阵的标志。请注意，将此设置为 True 并 not 还返回方差载体。

返回:

ndarray: 具有完整协方差矩阵的密集阵列。

to_sparse(correlation=False)[源代码]#

将完整的协方差矩阵返回为 csr_matrix object.

这种方法本质上相当于 to_dense 只是它返回一个稀疏数组。

参数:

correlation : bool ，可选可选的布尔: 返回 correlation 矩阵如果为假，则返回协方差矩阵。

返回:

csr_matrix: 上三角形和下三角形都被填充（具有对称信息）的稀疏矩阵。

to_table()[源代码]#

返回协方差数据 Table 使用坐标格式。

坐标格式意味着协方差矩阵数据以三列形式提供， \(\Sigma_{ij}\) 以及（0-索引）矩阵坐标 \(i,j\) .

输出表有三列：

'INDXI' ：协方差矩阵中的行索引。
'INDXJ' ：协方差矩阵中的列索引。
'COVARIJ' ：相关协方差 \(i,j\) 坐标系

该表还包含以下元数据：

'COVSHAPE' ：协方差矩阵的形状
'BUNIT' ：（如果 unit 已定义）协方差单位的字符串表示。
'COVDSHP' ：（如果 data_shape 已定义）关联数据数组的形状。

如果 data_shape 设置，协方差矩阵索引被重新格式化以匹配N维数组中的坐标。

警告

回想一下，高维数据的协方差矩阵的存储总是假设行优先的存储顺序。

此方法实例化的对象可用于重新实例化 Covariance 对象使用 from_table .

返回:

Table: 包含坐标格式的Covoariance矩阵和相关元数据的表格。