Index
Covariance estimators for copula dependence structures.
CovarianceEstimator
Bases: ABC
Streaming covariance estimator for a copula group.
Attributes:
| Name | Type | Description |
|---|---|---|
regularized |
bool
|
Class attribute. |
n_features_ |
int
|
Number of features, set by :meth: |
n_samples_ |
int
|
Number of observations seen so far, modified by :meth: |
covariance_ |
ndarray or None
|
Estimated covariance of shape |
Source code in scdesigner/src/scdesigner/covariance/base.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
second_moment_
property
Uncentered second moment Z.T @ Z, or None if not retained.
clone()
Create a new copy of the estimator with the same hyperparameters.
Source code in scdesigner/src/scdesigner/covariance/base.py
92 93 94 95 96 | |
diagnostics()
Any extra, method-specific diagnostics
Source code in scdesigner/src/scdesigner/covariance/base.py
180 181 182 | |
finalize()
Compute :attr:covariance_ from the accumulators.
Returns:
| Type | Description |
|---|---|
CovarianceEstimator
|
|
Source code in scdesigner/src/scdesigner/covariance/base.py
132 133 134 135 136 137 138 139 140 141 142 143 | |
get_params()
Return the constructor arguments of this estimator.
Source code in scdesigner/src/scdesigner/covariance/base.py
88 89 90 | |
num_params(n_features)
Free parameters in the estimate, used for AIC and BIC.
The default counts every off-diagonal entry. This is actually an upper bound for regularized estimators, so those should implement their own parameter functions.
Source code in scdesigner/src/scdesigner/covariance/base.py
170 171 172 173 174 175 176 177 178 | |
release()
Drop accumulators no longer needed after :meth:finalize.
The copula calls this once it has consumed :attr:second_moment_. This
allows us to free up memory for large class definitions.
Source code in scdesigner/src/scdesigner/covariance/base.py
184 185 186 187 188 189 190 | |
start(n_features)
Prepare to stream covariance over n_features features.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_features
|
int
|
Number of genes the copula models for this group. |
required |
Source code in scdesigner/src/scdesigner/covariance/base.py
105 106 107 108 109 110 111 112 113 114 115 116 117 | |
update(z)
Substitute a new block of z-scores into the streaming estimate
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
z
|
ndarray
|
Array of shape |
required |
Source code in scdesigner/src/scdesigner/covariance/base.py
119 120 121 122 123 124 125 126 127 128 129 130 | |
LedoitWolf
Bases: _ShrinkageEstimator
Ledoit-Wolf shrinkage, matching sklearn.covariance.LedoitWolf.
Must track three extra moment matrices beyond the sample covariance,
so costs roughly 3X the memory of :class:OAS per group. OAS is hence
less resource hungryat least in this data setting.
Examples:
>>> import numpy as np
>>> from scdesigner.covariance import LedoitWolf
>>>
>>> rng = np.random.default_rng(0)
>>> estimator = LedoitWolf()
>>> estimator.start(30)
>>> estimator.update(rng.standard_normal((12, 30)))
>>> _ = estimator.finalize()
>>> estimator.diagnostics()["intensity"] > 0
True
Source code in scdesigner/src/scdesigner/covariance/shrinkage.py
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | |
OAS
Bases: _ShrinkageEstimator
Oracle Approximating Shrinkage (see also sklearn.covariance.OAS)
Examples:
>>> import numpy as np
>>> from scdesigner.covariance import OAS
>>>
>>> rng = np.random.default_rng(0)
>>> estimator = OAS()
>>> estimator.start(30)
>>> estimator.update(rng.standard_normal((12, 30)))
>>> _ = estimator.finalize()
>>> np.linalg.cholesky(estimator.covariance_).shape # positive definite
(30, 30)
Source code in scdesigner/src/scdesigner/covariance/shrinkage.py
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 | |
SampleCovariance
Bases: _MomentEstimator
Unregularized sample covariance.
Note that top_k must be smaller than the smallest within-group sample
size. :class:~scdesigner.covariance.LedoitWolf and
:class:~scdesigner.covariance.OAS can be applied in the more general
setting.
Examples:
>>> import numpy as np
>>> from scdesigner.covariance import SampleCovariance
>>>
>>> rng = np.random.default_rng(0)
>>> estimator = SampleCovariance()
>>> estimator.start(4)
>>> estimator.update(rng.standard_normal((50, 4)))
>>> estimator.finalize().covariance_.shape
(4, 4)
Source code in scdesigner/src/scdesigner/covariance/moments.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | |
as_covariance_estimator(covariance)
Convert a covariance string to an estimator object
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
covariance
|
CovarianceEstimator, str, or None
|
This can be an existing estimator, a registered name
e.g. |
required |
Returns:
| Type | Description |
|---|---|
CovarianceEstimator
|
The estimator to use as a prototype. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the name is not registered. |
Examples:
>>> from scdesigner.covariance import as_covariance_estimator
>>> as_covariance_estimator("oas")
OAS()
>>> as_covariance_estimator(None)
SampleCovariance()
Source code in scdesigner/src/scdesigner/covariance/base.py
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 | |
ledoit_wolf_intensity(cov, n_samples, mean, squared_sums, second_moments, third_moments, fourth_moments)
Ledoit-Wolf shrinkage from streaming statistics.
sklearn.covariance.ledoit_wolf_shrinkage needs three quantities of the
centered data X: trace(C), delta_ = ||X^T X||_F^2 / n^2 and
beta_ = sum_ij sum_k x_ki^2 x_kj^2. We center the data in a streaming
way. We take m = sum_z / n and sum_k z_ki = n m_i, then
(z_ki - m_i)^2 (z_kj - m_j)^2 collapses into-3 n m_i^2 m_j^2:
.. math::
M_{ij} = A_{ij} - 2 m_j B_{ij} - 2 m_i B_{ji}
+ m_i^2 q_j + q_i m_j^2 + 4 m_i m_j S_{ij}
- 3 n m_i^2 m_j^2
with beta_ = sum(M), and delta_ = ||C||_F^2 because X^T X = n C.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cov
|
ndarray
|
Biased centered covariance |
required |
n_samples
|
int
|
Number of observations. |
required |
mean
|
ndarray
|
Per-feature mean |
required |
squared_sums
|
ndarray
|
|
required |
second_moments
|
ndarray
|
|
required |
third_moments
|
ndarray
|
|
required |
fourth_moments
|
ndarray
|
|
required |
Returns:
| Type | Description |
|---|---|
float
|
Shrinkage intensity in |
Source code in scdesigner/src/scdesigner/covariance/shrinkage.py
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 | |
oas_intensity(cov, n_samples)
Oracle Approximating Shrinkage intensity
Based on sklearn.covariance.OAS (Chen et al. 2010, Eq. 23 and the
sklearn implementation).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cov
|
ndarray
|
Biased (divided by |
required |
n_samples
|
int
|
Number of observations the covariance was computed from. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Shrinkage intensity in |
Source code in scdesigner/src/scdesigner/covariance/shrinkage.py
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | |
register_estimator(name, estimator_class)
Make an estimator searchable by name.
This allows us to search for estimators in a YAML config file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Lowercase name, as accepted by :func: |
required |
estimator_class
|
type
|
A :class: |
required |
Source code in scdesigner/src/scdesigner/covariance/base.py
196 197 198 199 200 201 202 203 204 205 206 207 208 209 | |
shrink_covariance(cov, intensity)
Shrink a covariance matrix toward the (scaled) identity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cov
|
ndarray
|
Covariance matrix of shape |
required |
intensity
|
float
|
Shrinkage intensity in |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
|
Source code in scdesigner/src/scdesigner/covariance/shrinkage.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | |