Skip to content

gaussian_copula_helpers

Sampling and likelihood helpers for the Gaussian copula

The copula loglikelihood of an entry is the joint normal log-density minus the independent one,

.. math:: \ell(z) = \log \phi_\Sigma(z) - \sum_j \log \phi(z_j),

For each entry, we use :func:batch_log_likelihood to compute the difference directly, then form the group total (:func:group_log_likelihood) using a trace formula documented in that function's docstring. Also includes helpers for computing a Cholesky factorization, which can be shared for both likelihood calculation and sampling.

batch_log_likelihood(z, cov_struct)

Per-entry copula log-likelihood for a batch of gaussianized scores.

Unlike :func:group_log_likelihood, this keeps the cells separate, so it needs the scores themselves.

Parameters:

Name Type Description Default
z ndarray

Normal scores, shape (n_cells, n_genes).

required
cov_struct CovarianceStructure

Fitted structure for the group these cells belong to.

required

Returns:

Type Description
ndarray

Log-likelihood per cell, shape (n_cells,).

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
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
def batch_log_likelihood(
    z: np.ndarray, cov_struct: CovarianceStructure
) -> np.ndarray:
    """
    Per-entry copula log-likelihood for a batch of gaussianized scores.

    Unlike :func:`group_log_likelihood`, this keeps the cells separate, so it
    needs the scores themselves.

    Parameters
    ----------
    z : np.ndarray
        Normal scores, shape ``(n_cells, n_genes)``.
    cov_struct : CovarianceStructure
        Fitted structure for the group these cells belong to.

    Returns
    -------
    np.ndarray
        Log-likelihood per cell, shape ``(n_cells,)``.
    """
    z_modeled = z[:, cov_struct.modeled_indices]
    joint = multivariate_normal.logpdf(
        z_modeled,
        np.zeros(cov_struct.num_modeled_genes),
        cov_struct.cov.values,
        allow_singular=False,
    )
    return joint - norm.logpdf(z_modeled).sum(axis=1)

cholesky_factor(corr, group)

Cholesky factor of a correlation matrix

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
42
43
44
45
46
47
48
49
50
51
52
53
def cholesky_factor(corr: np.ndarray, group: Union[str, int]) -> np.ndarray:
    """
    Cholesky factor of a correlation matrix
    """
    try:
        return np.linalg.cholesky(corr)
    except np.linalg.LinAlgError as exc:
        raise ValueError(
            f"The copula correlation matrix for group '{group}' is not positive "
            f"definite ({corr.shape[0]} x {corr.shape[1]}). Consider reducing top_k, "
            "or choosing a regularized covariance estimator."
        ) from exc

covariance_to_correlation(cov)

Rescale a covariance matrix to unit diagonal.

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
31
32
33
34
35
36
37
38
39
def covariance_to_correlation(cov: np.ndarray) -> np.ndarray:
    """
    Rescale a covariance matrix to unit diagonal.
    """
    std = np.sqrt(np.clip(np.diag(cov), a_min=np.finfo(float).eps, a_max=None))
    corr = cov / np.outer(std, std)
    corr = 0.5 * (corr + corr.T)
    np.fill_diagonal(corr, 1.0)
    return corr

factorize_correlation(corr, group, jitter=False)

Factorize a correlation matrix

Parameters:

Name Type Description Default
corr ndarray

Correlation matrix, shape (p, p).

required
group str or int

Group label, used in messages.

required
jitter bool

Add jitter to the diagonal of the original input isn't PSD.

False

Returns:

Name Type Description
corr ndarray

The matrix used after applying potential ridge

factor ndarray

Its lower Cholesky factor.

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
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
def factorize_correlation(
    corr: np.ndarray, group: Union[str, int], jitter: bool = False
) -> Tuple[np.ndarray, np.ndarray]:
    """
    Factorize a correlation matrix

    Parameters
    ----------
    corr : np.ndarray
        Correlation matrix, shape ``(p, p)``.
    group : str or int
        Group label, used in messages.
    jitter : bool, optional
        Add jitter to the diagonal of the original input isn't PSD.

    Returns
    -------
    corr : np.ndarray
        The matrix used after applying potential ridge
    factor : np.ndarray
        Its lower Cholesky factor.
    """
    if not jitter:
        return corr, cholesky_factor(corr, group)

    try:
        return corr, np.linalg.cholesky(corr)
    except np.linalg.LinAlgError:
        pass

    candidate = corr.copy()
    candidate.flat[:: corr.shape[0] + 1] += JITTER
    candidate = covariance_to_correlation(candidate)
    try:
        factor = np.linalg.cholesky(candidate)
    except np.linalg.LinAlgError:
        return corr, cholesky_factor(corr, group)

    warnings.warn(
        f"The correlation matrix for group '{group}' needed a ridge of "
        f"{JITTER:g} to factorize."
    )
    return candidate, factor

group_log_likelihood(factor, second_moment, n_samples)

Copula log-likelihood for a group

Adding :math:\ell(z_i) over the group gives

.. math::

\sum_i \ell(z_i) = -\tfrac{1}{2}\left( n \log|\Sigma|
    + \operatorname{tr}(\Sigma^{-1} S) - \operatorname{tr}(S) \right),

where :math:S = \sum_i z_i z_i^\top. Note that we assume the mean is zero, matching the copula assumptions. So, we only ever need S in our inputs.

Parameters:

Name Type Description Default
factor ndarray

Lower Cholesky factor of the group's correlation matrix.

required
second_moment ndarray

Uncentered second moment :math:S.

required
n_samples int

Cells in the group.

required

Returns:

Type Description
float

Total log-likelihood.

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
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
def group_log_likelihood(
    factor: np.ndarray, second_moment: np.ndarray, n_samples: int
) -> float:
    r"""
    Copula log-likelihood for a group

    Adding :math:`\ell(z_i)` over the group gives

    .. math::

        \sum_i \ell(z_i) = -\tfrac{1}{2}\left( n \log|\Sigma|
            + \operatorname{tr}(\Sigma^{-1} S) - \operatorname{tr}(S) \right),

    where :math:`S = \sum_i z_i z_i^\top`. Note that we assume the mean is zero,
    matching the copula assumptions. So, we only ever need S in our inputs.

    Parameters
    ----------
    factor : np.ndarray
        Lower Cholesky factor of the group's correlation matrix.
    second_moment : np.ndarray
        Uncentered second moment :math:`S`.
    n_samples : int
        Cells in the group.

    Returns
    -------
    float
        Total log-likelihood.
    """
    log_det = 2.0 * np.log(np.diag(factor)).sum()
    quadratic = np.trace(cho_solve((factor, True), second_moment))
    return -0.5 * (n_samples * log_det + quadratic - np.trace(second_moment))

sample_pseudo_obs(n_samples, cov_struct, rng=None)

Draw dependent uniform pseudoobservations from a CovarianceStructure

Genes outside the CovarianceStructure's top_k block are drawn independently.

Parameters:

Name Type Description Default
n_samples int

Entries to generate.

required
cov_struct CovarianceStructure

Jointly modeled block plus remaining independent genes.

required
rng Generator

Optional random number generator.

None

Returns:

Type Description
ndarray

Uniform values, shape (n_samples, total_genes).

Source code in scdesigner/src/scdesigner/copulas/gaussian_copula_helpers.py
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def sample_pseudo_obs(
    n_samples: int,
    cov_struct: CovarianceStructure,
    rng: Optional[np.random.Generator] = None,
) -> np.ndarray:
    """
    Draw dependent uniform pseudoobservations from a CovarianceStructure

    Genes outside the CovarianceStructure's top_k block are drawn independently.

    Parameters
    ----------
    n_samples : int
        Entries to generate.
    cov_struct : CovarianceStructure
        Jointly modeled block plus remaining independent genes.
    rng : np.random.Generator, optional
        Optional random number generator.

    Returns
    -------
    np.ndarray
        Uniform values, shape ``(n_samples, total_genes)``.
    """
    draw = np.random if rng is None else rng

    # jointly correlated block
    u = np.zeros((n_samples, cov_struct.total_genes))
    z_modeled = draw.multivariate_normal(
        mean=np.zeros(cov_struct.num_modeled_genes),
        cov=cov_struct.cov.values,
        size=n_samples,
    )
    u[:, cov_struct.modeled_indices] = norm.cdf(z_modeled)

    # remaining independent genes
    if cov_struct.num_remaining_genes > 0:
        z_remaining = draw.normal(
            loc=0, scale=1, size=(n_samples, cov_struct.num_remaining_genes)
        )
        u[:, cov_struct.remaining_indices] = norm.cdf(z_remaining)

    return u