cellink-tools 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. cellink/__init__.py +8 -0
  2. cellink/_config.py +63 -0
  3. cellink/_core/__init__.py +4 -0
  4. cellink/_core/data_fields.py +48 -0
  5. cellink/_core/dummy_data.py +264 -0
  6. cellink/_core/schema.py +86 -0
  7. cellink/_extras.py +39 -0
  8. cellink/at/__init__.py +14 -0
  9. cellink/at/acat.py +129 -0
  10. cellink/at/base_model.py +116 -0
  11. cellink/at/fetch.py +185 -0
  12. cellink/at/formula.py +77 -0
  13. cellink/at/gwas.py +207 -0
  14. cellink/at/require.py +80 -0
  15. cellink/at/resolver.py +166 -0
  16. cellink/at/skat.py +230 -0
  17. cellink/at/structlmm.py +221 -0
  18. cellink/at/utils.py +176 -0
  19. cellink/cli/__init__.py +0 -0
  20. cellink/cli/pgen.md +119 -0
  21. cellink/cli/pgen.py +91 -0
  22. cellink/io/__init__.py +4 -0
  23. cellink/io/_codecs.py +98 -0
  24. cellink/io/_export.py +415 -0
  25. cellink/io/_genotype_array.py +135 -0
  26. cellink/io/_pgen.py +625 -0
  27. cellink/io/_plink.py +184 -0
  28. cellink/io/_readwrite.py +415 -0
  29. cellink/io/_sgkit.py +516 -0
  30. cellink/ml/__init__.py +38 -0
  31. cellink/ml/model.py +147 -0
  32. cellink/pl/__init__.py +3 -0
  33. cellink/pl/_at.py +576 -0
  34. cellink/pl/_expression.py +367 -0
  35. cellink/pl/_ldsc_magma.py +335 -0
  36. cellink/pp/__init__.py +4 -0
  37. cellink/pp/_basic.py +202 -0
  38. cellink/pp/_variant_qc.py +83 -0
  39. cellink/resources/__init__.py +24 -0
  40. cellink/resources/_datasets.py +680 -0
  41. cellink/resources/_datasets_utils.py +253 -0
  42. cellink/resources/_gwas_prs_qtl.py +1117 -0
  43. cellink/resources/_ld.py +706 -0
  44. cellink/resources/_utils.py +321 -0
  45. cellink/resources/config/1000genomes.yaml +167 -0
  46. cellink/resources/config/1000genomes_grch38.yaml +133 -0
  47. cellink/resources/config/dummy_onek1k.yaml +4 -0
  48. cellink/resources/config/favor.yaml +47 -0
  49. cellink/resources/config/magma.yaml +31 -0
  50. cellink/resources/config/onek1k.yaml +13 -0
  51. cellink/tl/__init__.py +15 -0
  52. cellink/tl/_annotate_snps_ensembl_rest.py +105 -0
  53. cellink/tl/_annotate_snps_genotype_data.py +726 -0
  54. cellink/tl/_coloc.py +250 -0
  55. cellink/tl/_gene_pair_effects.py +129 -0
  56. cellink/tl/_pca_informed_prior.py +134 -0
  57. cellink/tl/_runner.py +218 -0
  58. cellink/tl/_rvat.py +117 -0
  59. cellink/tl/_subset_region.py +86 -0
  60. cellink/tl/external/__init__.py +256 -0
  61. cellink/tl/external/_biomart.py +114 -0
  62. cellink/tl/external/_gsmap.py +299 -0
  63. cellink/tl/external/_jaxqtl.py +648 -0
  64. cellink/tl/external/_joint_nmf.py +259 -0
  65. cellink/tl/external/_ld.py +89 -0
  66. cellink/tl/external/_ldsc.py +2435 -0
  67. cellink/tl/external/_ldsc2magma.py +934 -0
  68. cellink/tl/external/_magma.py +835 -0
  69. cellink/tl/external/_mixmil.py +136 -0
  70. cellink/tl/external/_pc.py +71 -0
  71. cellink/tl/external/_preprocessing.py +118 -0
  72. cellink/tl/external/_saigeqtl.py +961 -0
  73. cellink/tl/external/_scdrs.py +355 -0
  74. cellink/tl/external/_sclinker.py +744 -0
  75. cellink/tl/external/_sclinker_utils.py +2038 -0
  76. cellink/tl/external/_scooby.py +1499 -0
  77. cellink/tl/external/_scprs.py +1213 -0
  78. cellink/tl/external/_seismic.py +326 -0
  79. cellink/tl/external/_seismic_torch.py +485 -0
  80. cellink/tl/external/_sldsc_utils.py +739 -0
  81. cellink/tl/external/_tensorqtl.py +1129 -0
  82. cellink/tl/external/_tensorqtl_main.py +51 -0
  83. cellink/tl/external/config/ldsc.yaml +6 -0
  84. cellink/tl/external/config/ldsc_docker.yaml +5 -0
  85. cellink/tl/external/config/ldsc_singularity.yaml +5 -0
  86. cellink/tl/external/config/saigeqtl.yaml +8 -0
  87. cellink/tl/external/config/saigeqtl_docker.yaml +7 -0
  88. cellink/tl/external/config/saigeqtl_singularity.yaml +7 -0
  89. cellink/tl/external/config/vep.yaml +20 -0
  90. cellink/tl/external/config/vep_offline.yaml +34 -0
  91. cellink/tl/external/config/vep_offline_local.yaml +34 -0
  92. cellink/tl/utils.py +17 -0
  93. cellink/utils/__init__.py +2 -0
  94. cellink/utils/_encode_genotype_data.py +130 -0
  95. cellink/utils/preprocess.py +33 -0
  96. cellink_tools-0.1.0.dist-info/METADATA +441 -0
  97. cellink_tools-0.1.0.dist-info/RECORD +100 -0
  98. cellink_tools-0.1.0.dist-info/WHEEL +4 -0
  99. cellink_tools-0.1.0.dist-info/entry_points.txt +5 -0
  100. cellink_tools-0.1.0.dist-info/licenses/LICENSE +201 -0
cellink/__init__.py ADDED
@@ -0,0 +1,8 @@
1
+ from importlib.metadata import version
2
+
3
+ from . import at, io, ml, pl, pp, resources, tl
4
+ from ._core import DonorData, DonorDataSchemaError, validate
5
+
6
+ __all__ = ["DonorData", "pl", "pp", "tl", "io", "at", "ml", "resources", "validate", "DonorDataSchemaError"]
7
+
8
+ __version__ = version("cellink-tools")
cellink/_config.py ADDED
@@ -0,0 +1,63 @@
1
+ """Find YAML configs, given either by the name of a config shipped with cellink or as a file path."""
2
+
3
+ from pathlib import Path
4
+
5
+ import yaml
6
+
7
+ PACKAGED_CONFIG_DIRS = (
8
+ Path(__file__).parent / "resources" / "config",
9
+ Path(__file__).parent / "tl" / "external" / "config",
10
+ )
11
+
12
+
13
+ def packaged_configs() -> dict[str, Path]:
14
+ """Map the name of every config shipped with cellink to its file, e.g. ``"ldsc_docker"``."""
15
+ return {path.stem: path for config_dir in PACKAGED_CONFIG_DIRS for path in sorted(config_dir.glob("*.yaml"))}
16
+
17
+
18
+ def resolve_config_path(config: str | Path) -> Path:
19
+ """
20
+ Return the YAML file a config argument refers to.
21
+
22
+ Parameters
23
+ ----------
24
+ config : str or pathlib.Path
25
+ Either the name of a config shipped with cellink (e.g. ``"1000genomes"``,
26
+ ``"ldsc_docker"``, ``"vep_offline"``; see :func:`packaged_configs`), or a path to a
27
+ YAML file. A bare name, i.e. one without a directory and without a ``.yaml`` suffix,
28
+ is looked up among the packaged configs first and then as ``<name>.yaml`` in the
29
+ working directory. Anything else is treated as a path.
30
+
31
+ Returns
32
+ -------
33
+ pathlib.Path
34
+ The config file.
35
+
36
+ Raises
37
+ ------
38
+ FileNotFoundError
39
+ If ``config`` names neither a packaged config nor an existing file.
40
+ """
41
+ path = Path(config)
42
+ if len(path.parts) == 1 and path.suffix not in (".yaml", ".yml"):
43
+ packaged = packaged_configs()
44
+ if path.name in packaged:
45
+ return packaged[path.name]
46
+ for candidate in (path.with_name(f"{path.name}.yaml"), path):
47
+ if candidate.is_file():
48
+ return candidate
49
+ raise FileNotFoundError(
50
+ f"{str(config)!r} is neither a config shipped with cellink nor a file in the working directory. "
51
+ f"Shipped configs: {', '.join(sorted(packaged))}"
52
+ )
53
+ if not path.is_file():
54
+ raise FileNotFoundError(f"Config file not found: {str(config)!r}")
55
+ return path
56
+
57
+
58
+ def load_config(config: str | Path | None = None, config_dict: dict | None = None) -> dict:
59
+ """Return ``config_dict`` if given, else load the YAML config ``config`` refers to (a shipped name or a path)."""
60
+ if config_dict is not None:
61
+ return config_dict
62
+ with open(resolve_config_path(config)) as f:
63
+ return yaml.safe_load(f)
@@ -0,0 +1,4 @@
1
+ from donordata import DonorData
2
+
3
+ from .data_fields import DAnn, GAnn, VAnn
4
+ from .schema import DONORDATA_ENCODING_TYPE, DONORDATA_ENCODING_VERSION, DonorDataSchemaError, validate
@@ -0,0 +1,48 @@
1
+ from dataclasses import dataclass
2
+
3
+ from donordata import CAnn, DAnn
4
+
5
+ __all__ = ["AAnn", "CAnn", "DAnn", "GAnn", "VAnn"]
6
+
7
+ DONOR_KEY = "donor_id"
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class GAnn:
12
+ """Gene annotation fields in AnnData.var"""
13
+
14
+ name: str = "name" # gene name, name of adata.var.index
15
+ start: str = "start"
16
+ end: str = "end"
17
+ chrom: str = "chrom"
18
+ strand: str = "strand"
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class VAnn:
23
+ """Variant annotation fields in GenoAnndata"""
24
+
25
+ chrom: str = GAnn.chrom
26
+ pos: str = "pos"
27
+ a0: str = "a0"
28
+ a1: str = "a1"
29
+ asymb: str = "asymb"
30
+ maf: str = "maf"
31
+ contig: str = "contig" # index for contig_id
32
+ index: str = "snp_id"
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class AAnn:
37
+ """Variant annotation fields in GenoAnndata Annotations"""
38
+
39
+ chrom: str = VAnn.chrom
40
+ pos: str = VAnn.pos
41
+ a0: str = VAnn.a0
42
+ a1: str = VAnn.a1
43
+ index: str = VAnn.index
44
+ gene_id: str = "gene_id"
45
+ feature_id: str = "transcript_id"
46
+ name_prefix: str = "variant_annotation"
47
+ vep: str = "vep"
48
+ snpeff: str = "snpeff"
@@ -0,0 +1,264 @@
1
+ from typing import Literal
2
+
3
+ import anndata as ad
4
+ import numpy as np
5
+ import pandas as pd
6
+ from anndata import AnnData
7
+ from muon import MuData
8
+
9
+ from cellink._core.data_fields import CAnn, DAnn, GAnn, VAnn
10
+
11
+ N_DONORS = 10
12
+ N_GENES = 20
13
+ N_PEAKS = 50
14
+ N_SNPS = 5
15
+
16
+
17
+ CELLTYPES = ["CD4", "CD8", "NK"]
18
+ MIN_N_CELLS = 10
19
+ MAX_N_CELLS = 100
20
+ MIN_GENE_LENGTH = 18_000
21
+ MAX_GENE_LENGTH = 30_000
22
+ EXAMPLE_CHROMOSOME = 1
23
+ DUMMY_COVARIATES = ["cov1", "cov2", "cov3"]
24
+ CELL_PREFIX = "C"
25
+ DONOR_PREFIX = "D"
26
+ GENE_PREFIX = "G"
27
+ SNP_PREFIX = "SNP"
28
+
29
+
30
+ def _sim_donor(
31
+ start_index: int = None,
32
+ n_cells: int = None,
33
+ n_genes: int = None,
34
+ has_all_celltypes: bool = False,
35
+ strategy: Literal["randn", "poisson", "negative_binomial", "binomial", "uniform"] = "randn",
36
+ mean_nb: int = 5,
37
+ dispersion_nb: int = 2,
38
+ p_binomial: float = 0.1,
39
+ ) -> AnnData:
40
+ """
41
+ Simulate a single donor's cell x gene expression matrix as an AnnData object.
42
+
43
+ Generates synthetic expression data for one donor using different statistical distributions,
44
+ attaches random covariates, and annotates genes with basic genomic features.
45
+
46
+ Parameters
47
+ ----------
48
+ start_index : int
49
+ Starting cell index (used to build unique cell IDs).
50
+ n_cells : int
51
+ Number of cells to simulate for the donor.
52
+ n_genes : int
53
+ Number of genes to simulate.
54
+ has_all_celltypes : bool
55
+ Whether to include all cell types in `CELLTYPES`. If False, the last cell type is excluded.
56
+ strategy : {'randn', 'poisson', 'negative_binomial', 'binomial', 'uniform'}, default='randn'
57
+ Distribution used to simulate expression counts:
58
+ - 'randn': standard normal
59
+ - 'poisson': Poisson with λ=5
60
+ - 'negative_binomial': Negative binomial with parameters (`mean_nb`, `dispersion_nb`)
61
+ - 'binomial': Binomial with n=1 and probability `p_binomial`
62
+ - 'uniform': Uniform(0,1)
63
+ mean_nb : int, default=5
64
+ Mean count for negative binomial distribution.
65
+ dispersion_nb : int, default=2
66
+ Dispersion parameter for negative binomial distribution.
67
+ p_binomial : float, default=0.1
68
+ Success probability for binomial distribution.
69
+
70
+ Returns
71
+ -------
72
+ AnnData
73
+ AnnData object with:
74
+ - `X` : simulated expression matrix (n_cells x n_genes)
75
+ - `obs` : DataFrame with columns:
76
+ - celltype
77
+ - dummy covariates (`cov1`, `cov2`, `cov3`)
78
+ - `var` : DataFrame with columns:
79
+ - gene name, chromosome, start, end, strand
80
+ """
81
+ if strategy == "randn":
82
+ X = np.random.randn(n_cells, n_genes)
83
+ elif strategy == "poisson":
84
+ X = np.random.poisson(lam=5, size=(n_cells, n_genes))
85
+ elif strategy == "negative_binomial":
86
+ r = 1 / dispersion_nb
87
+ p = mean_nb / (mean_nb + r)
88
+ X = np.random.negative_binomial(n=r, p=p, size=(n_cells, n_genes))
89
+ elif strategy == "binomial":
90
+ X = np.random.binomial(n=1, p=p_binomial, size=(n_cells, n_genes))
91
+ elif strategy == "uniform":
92
+ X = np.random.uniform(size=(n_cells, n_genes))
93
+ _celltypes = CELLTYPES if has_all_celltypes else CELLTYPES[:-1]
94
+ obs = pd.DataFrame({CAnn.celltype: np.random.choice(_celltypes, size=n_cells)})
95
+ obs.index = [f"{CELL_PREFIX}{i}" for i in range(start_index, start_index + n_cells)]
96
+ obs[DUMMY_COVARIATES] = np.random.randn(n_cells, len(DUMMY_COVARIATES))
97
+ gene_lengths = np.random.randint(MIN_GENE_LENGTH, MAX_GENE_LENGTH, size=n_genes)
98
+ var = pd.DataFrame(
99
+ {
100
+ GAnn.name: np.array([f"{GENE_PREFIX}{i}" for i in np.arange(n_genes)]),
101
+ GAnn.chrom: EXAMPLE_CHROMOSOME,
102
+ GAnn.start: np.concatenate([[0], np.cumsum(gene_lengths[:-1])]),
103
+ GAnn.end: np.cumsum(gene_lengths),
104
+ GAnn.strand: np.random.choice([1, -1], size=n_genes),
105
+ }
106
+ ).set_index(GAnn.name)
107
+ return AnnData(X=X, obs=obs, var=var)
108
+
109
+
110
+ def sim_mudata(
111
+ n_donors: int = N_DONORS,
112
+ n_genes: int = N_GENES,
113
+ n_peaks: int = N_PEAKS,
114
+ min_n_cells: int = MIN_N_CELLS,
115
+ max_n_cells: int = MAX_N_CELLS,
116
+ ) -> MuData:
117
+ """
118
+ Simulate a multi-modal `MuData` object with RNA and ATAC layers.
119
+
120
+ This function generates paired RNA-seq and ATAC-seq data across multiple donors,
121
+ combining them into a single `MuData` container. Cell-level metadata is harmonized
122
+ so that both modalities share the same donor and cell type assignments.
123
+
124
+ Parameters
125
+ ----------
126
+ n_donors : int, default=N_DONORS
127
+ Number of donors to simulate.
128
+ n_genes : int, default=N_GENES
129
+ Number of genes in the RNA modality.
130
+ n_peaks : int, default=N_PEAKS
131
+ Number of peaks in the ATAC modality.
132
+ min_n_cells : int, default=MIN_N_CELLS
133
+ Minimum number of cells per donor.
134
+ max_n_cells : int, default=MAX_N_CELLS
135
+ Maximum number of cells per donor.
136
+
137
+ Returns
138
+ -------
139
+ MuData
140
+ MuData object with modalities:
141
+ - 'rna': AnnData of simulated RNA counts (negative binomial)
142
+ - 'atac': AnnData of simulated ATAC accessibility (binomial)
143
+ Shared `obs` fields include:
144
+ - 'celltype'
145
+ - 'donor_id'
146
+ """
147
+ rna = sim_adata(
148
+ n_donors=n_donors,
149
+ n_genes=n_genes,
150
+ min_n_cells=min_n_cells,
151
+ max_n_cells=max_n_cells,
152
+ strategy="negative_binomial",
153
+ )
154
+ atac = sim_adata(
155
+ n_donors=n_donors, n_genes=n_peaks, min_n_cells=min_n_cells, max_n_cells=max_n_cells, strategy="binomial"
156
+ )
157
+ adata = MuData({"rna": rna, "atac": atac})
158
+ adata.obs["celltype"] = rna.obs["celltype"].reindex(adata.obs_names)
159
+ adata.obs["donor_id"] = rna.obs["donor_id"].reindex(adata.obs_names)
160
+ return adata
161
+
162
+
163
+ def sim_adata(
164
+ n_donors: int = N_DONORS,
165
+ n_genes: int = N_GENES,
166
+ min_n_cells: int = MIN_N_CELLS,
167
+ max_n_cells: int = MAX_N_CELLS,
168
+ strategy: Literal["randn", "poisson", "negative_binomial", "binomial", "uniform"] = "randn",
169
+ ) -> AnnData:
170
+ """
171
+ Simulate an AnnData object across multiple donors.
172
+
173
+ Each donor contributes a random number of cells (between `min_n_cells` and `max_n_cells`)
174
+ with expression values simulated according to the chosen distribution.
175
+ The first donor is intentionally missing one cell type, while all others include
176
+ the full set of cell types.
177
+
178
+ Parameters
179
+ ----------
180
+ n_donors : int, default=N_DONORS
181
+ Number of donors to simulate.
182
+ n_genes : int, default=N_GENES
183
+ Number of genes to simulate.
184
+ min_n_cells : int, default=MIN_N_CELLS
185
+ Minimum number of cells per donor.
186
+ max_n_cells : int, default=MAX_N_CELLS
187
+ Maximum number of cells per donor.
188
+ strategy : {'randn', 'poisson', 'negative_binomial', 'binomial', 'uniform'}, default='randn'
189
+ Distribution to use for simulating expression counts.
190
+
191
+ Returns
192
+ -------
193
+ AnnData
194
+ Concatenated AnnData object containing all donors with:
195
+ - `obs` : cell-level metadata including donor ID and celltype
196
+ - `var` : gene-level metadata including chromosome, start, end
197
+ """
198
+ adatas = []
199
+ has_all_celltypes = [True] * (n_donors - 1) + [False]
200
+ cum_n_cells = 0
201
+ for i in range(n_donors):
202
+ n_cells = np.random.randint(min_n_cells, max_n_cells)
203
+ has_all_celltypes = i != 0 # the first donor misses one celltype
204
+ adatas.append(_sim_donor(cum_n_cells, n_cells, n_genes, has_all_celltypes, strategy=strategy))
205
+ cum_n_cells += n_cells
206
+ donors = [f"{DONOR_PREFIX}{i}" for i in range(n_donors)]
207
+ adata = ad.concat(adatas, merge="first", keys=donors, label=DAnn.donor)
208
+ return adata
209
+
210
+
211
+ def sim_gdata(n_donors: int = N_DONORS, n_snps: int = N_SNPS, adata: AnnData | None = None) -> AnnData:
212
+ """
213
+ Simulate genotype data as an AnnData object.
214
+
215
+ Generates SNP genotypes for multiple donors using binomial sampling
216
+ according to randomly assigned minor allele frequencies (MAFs).
217
+ Optionally aligns SNP positions to overlap with gene coordinates from an RNA AnnData.
218
+
219
+ Parameters
220
+ ----------
221
+ n_donors : int, default=N_DONORS
222
+ Number of donors to simulate.
223
+ n_snps : int, default=N_SNPS
224
+ Number of SNPs to simulate if `adata` is None.
225
+ adata : AnnData, optional
226
+ If provided, SNP positions are aligned with the genes in `adata.var`
227
+ such that SNPs fall within gene intervals.
228
+
229
+ Returns
230
+ -------
231
+ AnnData
232
+ AnnData object with:
233
+ - `X` : genotype matrix (n_donors x n_snps), values in {0,1,2}
234
+ - `obs` : donor IDs
235
+ - `var` : SNP metadata including chromosome, position, alleles, and MAF
236
+ """
237
+ if adata is None:
238
+ pos = np.arange(1, n_snps + 1)
239
+ else:
240
+ # make sure the variants overlap with the genes
241
+ pos = []
242
+ for _, row in adata.var.iterrows():
243
+ _pos = np.arange(N_SNPS) - (N_SNPS // 2) + row[GAnn.start]
244
+ _pos = _pos[(_pos >= 0) & (_pos < row[GAnn.end])]
245
+ pos.append(_pos)
246
+ pos = np.concatenate(pos)
247
+ n_snps = len(pos)
248
+ mafs = np.random.rand(n_snps)
249
+ X = np.random.binomial(n=2, p=mafs, size=(n_donors, n_snps))
250
+ obs = pd.DataFrame(index="D" + pd.RangeIndex(n_donors, name=DAnn.donor).astype(str))
251
+
252
+ var = pd.DataFrame(
253
+ {
254
+ VAnn.chrom: EXAMPLE_CHROMOSOME,
255
+ VAnn.pos: pos,
256
+ VAnn.a0: np.random.choice(["A", "T"], size=n_snps),
257
+ VAnn.a1: np.random.choice(["C", "G"], size=n_snps),
258
+ VAnn.maf: mafs,
259
+ },
260
+ index=SNP_PREFIX + pd.RangeIndex(n_snps).astype(str),
261
+ )
262
+ var.index.name = VAnn.index
263
+ gdata = AnnData(X=X, obs=obs, var=var)
264
+ return gdata
@@ -0,0 +1,86 @@
1
+ from __future__ import annotations
2
+
3
+ import donordata
4
+ import pandas as pd
5
+ import pandera.pandas as pa
6
+ from donordata import DONORDATA_ENCODING_TYPE, DONORDATA_ENCODING_VERSION, DonorDataSchemaError
7
+ from pandera.pandas import Column, DataFrameSchema
8
+
9
+ from .data_fields import VAnn
10
+
11
+ __all__ = [
12
+ "DONORDATA_ENCODING_TYPE",
13
+ "DONORDATA_ENCODING_VERSION",
14
+ "GENO_VAR_SCHEMA",
15
+ "DonorDataSchemaError",
16
+ "require_genotypes",
17
+ "validate",
18
+ ]
19
+
20
+ GENO_VAR_SCHEMA = DataFrameSchema(
21
+ {
22
+ VAnn.chrom: Column(pa.Object, nullable=False, coerce=True),
23
+ VAnn.pos: Column(pa.Int64, nullable=False, coerce=True, checks=pa.Check.ge(0)),
24
+ VAnn.a0: Column(pa.Object, nullable=False, coerce=True),
25
+ VAnn.a1: Column(pa.Object, nullable=False, coerce=True),
26
+ },
27
+ strict=False,
28
+ ordered=False,
29
+ )
30
+
31
+
32
+ def validate(dd, check_var: bool = True) -> bool:
33
+ """Check a `DonorData` object against cellink's schema.
34
+
35
+ Runs :func:`donordata.validate`, which checks that the levels are consistent, and then
36
+ the variant annotations of the donor level.
37
+
38
+ Parameters
39
+ ----------
40
+ dd : DonorData
41
+ The object to check.
42
+ check_var : bool, default=True
43
+ Validate `dd.D.var` against `GENO_VAR_SCHEMA` (chrom/pos/a0/a1 present,
44
+ correctly typed). When `dd.D` is a MuData, the `var` of every modality with a
45
+ `chrom` column is validated.
46
+
47
+ Returns
48
+ -------
49
+ bool
50
+ `True` if every requested check passes.
51
+
52
+ Raises
53
+ ------
54
+ DonorDataSchemaError
55
+ If any check fails, with a message naming the field or level that failed.
56
+ """
57
+ donordata.validate(dd)
58
+ if check_var:
59
+ if dd.D_type == "table":
60
+ raise DonorDataSchemaError("dd.D is a donor table without variants; pass check_var=False to skip it.")
61
+ if hasattr(dd.D, "mod"):
62
+ tables = {f"dd.D['{name}'].var": mod.var for name, mod in dd.D.mod.items() if VAnn.chrom in mod.var}
63
+ if not tables:
64
+ raise DonorDataSchemaError(f"No modality of dd.D has a '{VAnn.chrom}' column in its var.")
65
+ else:
66
+ tables = {"dd.D.var": dd.D.var}
67
+ for name, var in tables.items():
68
+ try:
69
+ GENO_VAR_SCHEMA.validate(var)
70
+ except pa.errors.SchemaError as e:
71
+ raise DonorDataSchemaError(f"{name} failed schema validation: {e}") from e
72
+
73
+ return True
74
+
75
+
76
+ def require_genotypes(dd):
77
+ """Return the genotypes `dd.D` of a `DonorData`.
78
+
79
+ Raises
80
+ ------
81
+ ValueError
82
+ If `dd.D` is a donor table, which holds no genotypes.
83
+ """
84
+ if isinstance(dd.D, pd.DataFrame):
85
+ raise ValueError("This function needs genotypes in dd.D, but dd.D is a donor table without genotypes.")
86
+ return dd.D
cellink/_extras.py ADDED
@@ -0,0 +1,39 @@
1
+ from __future__ import annotations
2
+
3
+ import sys
4
+
5
+ # package -> (first Python version it is not available for, reason shown in the error message)
6
+ _PYTHON_LIMITS: dict[str, tuple[tuple[int, int], str]] = {
7
+ "scooby": ((3, 13), "scooby pins pybigtools==0.1.1, which has no builds for Python 3.13 or newer"),
8
+ "tensorqtl": (
9
+ (3, 14),
10
+ "tensorqtl needs pyBigWig, which has no wheels for Python 3.14 or newer",
11
+ ),
12
+ }
13
+
14
+
15
+ # packages that are not on PyPI -> the source pip installs them from
16
+ _SOURCES: dict[str, str] = {
17
+ "scooby": "git+https://github.com/gagneurlab/scooby.git@061b7a2275a5f8f5ffb53ae6f7f2d34e3622a7ee",
18
+ }
19
+
20
+
21
+ def install_hint(extra: str, package: str | None = None) -> str:
22
+ """Return the pip command that installs a cellink extra, and ``package`` if it is not on PyPI."""
23
+ command = f"pip install 'cellink-tools[{extra}]'"
24
+ if package in _SOURCES:
25
+ command += f" '{package} @ {_SOURCES[package]}'"
26
+ return command
27
+
28
+
29
+ def missing_dependency_message(package: str, extra: str, purpose: str = "this function") -> str:
30
+ """Explain how to install a missing optional dependency, or why this Python version cannot have it."""
31
+ limit = _PYTHON_LIMITS.get(package)
32
+ if limit is not None and sys.version_info[:2] >= limit[0]:
33
+ (major, minor), reason = limit
34
+ return (
35
+ f"{package} is required for {purpose}, but it is not available for Python "
36
+ f"{sys.version_info.major}.{sys.version_info.minor}: {reason}. "
37
+ f"Use Python < {major}.{minor} for {package}."
38
+ )
39
+ return f"{package} is required for {purpose}. Install it with:\n\n {install_hint(extra, package)}"
cellink/at/__init__.py ADDED
@@ -0,0 +1,14 @@
1
+ from cellink.at.acat import acat_test, compute_acat
2
+ from cellink.at.gwas import GWAS
3
+ from cellink.at.resolver import get_model_matrix
4
+ from cellink.at.skat import Skat
5
+ from cellink.at.structlmm import StructLMM
6
+
7
+ __all__ = [
8
+ "acat_test",
9
+ "compute_acat",
10
+ "get_model_matrix",
11
+ "GWAS",
12
+ "Skat",
13
+ "StructLMM",
14
+ ]
cellink/at/acat.py ADDED
@@ -0,0 +1,129 @@
1
+ import numpy as np
2
+ import scipy.stats as st
3
+
4
+ from cellink.at.utils import ensure_float64_array
5
+
6
+ __all__ = [
7
+ "acat_test",
8
+ "compute_acat",
9
+ ]
10
+
11
+
12
+ def acat_test(
13
+ pvalues: np.ndarray,
14
+ tolerance: float = 1e-16,
15
+ weights: np.ndarray = None,
16
+ ) -> float:
17
+ """
18
+ Perform the Aggregated Cauchy Association Test (ACAT) to combine p-values.
19
+
20
+ ACAT is a fast and robust method for combining possibly dependent p-values,
21
+ using properties of the Cauchy distribution. It is especially effective when
22
+ only a subset of the input p-values are small.
23
+ Inspired by: https://github.com/yaowuliu/ACAT/blob/master/R/ACAT.R
24
+
25
+ Parameters
26
+ ----------
27
+ pvalues : np.ndarray or list of float
28
+ The p-values to combine. Must be in the range [0, 1]. NaN values are ignored.
29
+
30
+ tolerance : float, optional
31
+ A lower bound for p-values to ensure numerical stability. Values below this threshold
32
+ are clipped to `tolerance`. Default is 1e-16.
33
+
34
+ weights : np.ndarray or list of float, optional
35
+ Positive weights for each p-value. If None, equal weights are used. The weights of
36
+ the p-values that are not NaN are rescaled to sum to 1, as in the ACAT R package.
37
+
38
+ Returns
39
+ -------
40
+ float
41
+ The ACAT-combined p-value, or NaN if every p-value is NaN.
42
+
43
+ """
44
+ pvalues = ensure_float64_array(pvalues)
45
+ if weights is not None:
46
+ weights = ensure_float64_array(weights)
47
+ assert len(weights) == len(pvalues), "Length of weights and p-values differs."
48
+ assert (weights > 0).all(), "All weights must be positive."
49
+
50
+ keep = ~np.isnan(pvalues)
51
+ if not keep.any():
52
+ return np.nan
53
+ pvalues = pvalues[keep]
54
+ weights = np.ones_like(pvalues) if weights is None else weights[keep]
55
+ weights = weights / weights.sum()
56
+
57
+ if not any(pvalues < tolerance):
58
+ cct_stat = sum(weights * np.tan((0.5 - pvalues) * np.pi))
59
+ else:
60
+ is_small = [i < (tolerance) for i in pvalues]
61
+ is_large = [i >= (tolerance) for i in pvalues]
62
+ cct_stat = sum((weights[is_small] / pvalues[is_small]) / np.pi)
63
+ cct_stat += sum(weights[is_large] * np.tan((0.5 - pvalues[is_large]) * np.pi))
64
+ if cct_stat > 1e15:
65
+ pval = (1 / cct_stat) / np.pi
66
+ else:
67
+ pval = 1 - st.cauchy.cdf(cct_stat)
68
+ return pval
69
+
70
+
71
+ def compute_acat(
72
+ pvs: np.ndarray,
73
+ tolerance: float = 1e-16,
74
+ weights: np.ndarray = None,
75
+ ) -> np.ndarray:
76
+ """
77
+ Aggregate p-values using the Cauchy combination method (ACAT).
78
+
79
+ This function performs p-value aggregation using the ACAT (Aggregated Cauchy Association Test) method,
80
+ which is particularly powerful and robust for combining dependent and sparse p-values. It supports
81
+ missing values (NaNs) and optional weighting.
82
+
83
+ Parameters
84
+ ----------
85
+ pvs : np.ndarray
86
+ A 2D array of shape (n_different_tests, n_tests_to_integrate), where each row contains
87
+ the p-values to be aggregated into a single meta p-value. Values must be in the range [0, 1].
88
+ NaNs are allowed and will be ignored during aggregation.
89
+
90
+ tolerance : float, optional
91
+ A small threshold to avoid issues with extremely small p-values. Values below `tolerance`
92
+ are capped at `tolerance` to maintain numerical stability. Default is 1e-16.
93
+
94
+ weights : np.ndarray, optional
95
+ A 1D array of non-negative weights with shape (n_tests_to_integrate,). If provided,
96
+ it should sum to 1 or will be internally normalized. If None, equal weights are used.
97
+
98
+ Returns
99
+ -------
100
+ np.ndarray
101
+ A 1D array of aggregated p-values, one for each row of the input `pvs`.
102
+
103
+ Notes
104
+ -----
105
+ The ACAT method transforms each p-value `p` using the tangent function:
106
+ T = sum_i w_i * tan[(0.5 - p_i) * pi]
107
+ Then the aggregated p-value is computed using the Cauchy distribution:
108
+ p_combined = 0.5 - arctan(T) / pi
109
+
110
+ References
111
+ ----------
112
+ Liu, et al (2019).
113
+ ACAT: A Fast and Powerful p Value Combination Method for Rare-Variant Analysis in Sequencing Studies
114
+ The American Journal of Human Genetics, 104(3), 410–421.
115
+ https://doi.org/10.1016/j.ajhg.2019.01.002
116
+ """
117
+ RV = np.ones(pvs.shape[0])
118
+ for i in range(pvs.shape[0]):
119
+ _pvs = pvs[i]
120
+ is_nan = np.isnan(_pvs)
121
+ if is_nan.all():
122
+ RV[i] = np.nan
123
+ else:
124
+ _pvs = _pvs[~is_nan]
125
+ _pvs[_pvs == 0] = tolerance
126
+ _pvs[_pvs == 1] = 1 - tolerance
127
+ _weights = None if weights is None else np.asarray(weights)[~is_nan]
128
+ RV[i] = acat_test(_pvs, tolerance=tolerance, weights=_weights)
129
+ return RV