spatial-aim 1.0.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.
- aim/__init__.py +47 -0
- aim/__main__.py +6 -0
- aim/adata_schema.py +80 -0
- aim/aggregation.py +118 -0
- aim/aim_config.py +76 -0
- aim/analysis/__init__.py +13 -0
- aim/analysis/analysis.py +72 -0
- aim/analysis/biology.py +205 -0
- aim/analysis/confidence.py +49 -0
- aim/analysis/ksweep.py +184 -0
- aim/analysis/loading.py +70 -0
- aim/analysis/onehot.py +41 -0
- aim/analysis/reconstruction.py +131 -0
- aim/analysis/topology.py +142 -0
- aim/analysis/utils.py +16 -0
- aim/cli.py +371 -0
- aim/clustering.py +242 -0
- aim/data/__init__.py +0 -0
- aim/data/prepare/__init__.py +0 -0
- aim/data/prepare/build_imaging_pairs.py +397 -0
- aim/data/prepare/build_xenium_breast_pair.py +310 -0
- aim/data/prepare/convertTsvToCsv.py +39 -0
- aim/data/prepare/convert_csv_to_h5ad.py +217 -0
- aim/data/prepare/createOnlyHVGDataset.py +69 -0
- aim/data/prepare/createSmallerDataset.py +102 -0
- aim/data/prepare/normalize_gene_names.py +56 -0
- aim/data/prepare/perturb_sc_noise.py +107 -0
- aim/data/prepare/register_st_patches.py +180 -0
- aim/data/prepare/split_st_into_islands.py +551 -0
- aim/data/prepare/split_st_into_patches.py +240 -0
- aim/data/prepare/subset_st_hvg.py +43 -0
- aim/data/validate/__init__.py +35 -0
- aim/data/validate/common.py +141 -0
- aim/data/validate/runner.py +335 -0
- aim/data/validate/validate_pair.py +53 -0
- aim/data/validate/validate_sc.py +103 -0
- aim/data/validate/validate_st.py +74 -0
- aim/gui/__init__.py +8 -0
- aim/gui/__main__.py +77 -0
- aim/gui/app.py +1784 -0
- aim/gui/compute.py +106 -0
- aim/gui/data_access.py +292 -0
- aim/gui/render.py +1679 -0
- aim/gui/scaffold.py +129 -0
- aim/gui/widgets.py +675 -0
- aim/io.py +196 -0
- aim/mapping/__init__.py +14 -0
- aim/mapping/base.py +67 -0
- aim/mapping/confidence.py +51 -0
- aim/mapping/nearest_centroid.py +33 -0
- aim/mapping/reference.py +156 -0
- aim/mapping/wann.py +208 -0
- aim/metrics/__init__.py +26 -0
- aim/metrics/biology.py +69 -0
- aim/metrics/cossim.py +127 -0
- aim/metrics/kselection.py +272 -0
- aim/metrics/onehot.py +54 -0
- aim/metrics/reconstruction.py +73 -0
- aim/metrics/topology.py +62 -0
- aim/reference_aligners/__init__.py +0 -0
- aim/reference_aligners/environment_dot.yml +23 -0
- aim/reference_aligners/environment_tacco.yml +28 -0
- aim/reference_aligners/environment_tangram.yml +16 -0
- aim/reference_aligners/registry.py +350 -0
- aim/reference_aligners/run_dot.R +172 -0
- aim/reference_aligners/run_dot.py +116 -0
- aim/reference_aligners/run_tacco.py +143 -0
- aim/reference_aligners/run_tangram.py +210 -0
- aim/sweep.py +261 -0
- aim/tree.py +86 -0
- spatial_aim-1.0.0.dist-info/METADATA +1005 -0
- spatial_aim-1.0.0.dist-info/RECORD +76 -0
- spatial_aim-1.0.0.dist-info/WHEEL +5 -0
- spatial_aim-1.0.0.dist-info/entry_points.txt +2 -0
- spatial_aim-1.0.0.dist-info/licenses/LICENSE +674 -0
- spatial_aim-1.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Split a spatial transcriptomics dataset into an n×n grid of spatial patches.
|
|
3
|
+
|
|
4
|
+
Each spot is assigned to exactly one patch based on its coordinates in
|
|
5
|
+
adata_st.obsm["spatial"]. The coordinate space is divided into n equal-width
|
|
6
|
+
bins along each axis, yielding up to n×n patches.
|
|
7
|
+
|
|
8
|
+
The sc dataset is NOT touched — use the original sc.h5ad with every patch.
|
|
9
|
+
|
|
10
|
+
Usage:
|
|
11
|
+
python -m src.data_preparation.split_st_into_patches -d <st_path> -n <grid_size>
|
|
12
|
+
|
|
13
|
+
# Custom output directory:
|
|
14
|
+
python -m src.data_preparation.split_st_into_patches -d <st_path> -n 3 -o <output_dir>
|
|
15
|
+
|
|
16
|
+
Output structure:
|
|
17
|
+
<output_dir>/
|
|
18
|
+
patch_0_0/st.h5ad
|
|
19
|
+
patch_0_1/st.h5ad
|
|
20
|
+
...
|
|
21
|
+
patch_{n-1}_{n-1}/st.h5ad
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
import argparse
|
|
25
|
+
import logging
|
|
26
|
+
import sys
|
|
27
|
+
from pathlib import Path
|
|
28
|
+
|
|
29
|
+
import csv
|
|
30
|
+
import numpy as np
|
|
31
|
+
import anndata as ad
|
|
32
|
+
import matplotlib.pyplot as plt
|
|
33
|
+
import matplotlib.colors as mcolors
|
|
34
|
+
|
|
35
|
+
logger = logging.getLogger(__name__)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def split_st_into_patches(st_path: Path, n: int, output_dir: Path) -> None:
|
|
39
|
+
"""
|
|
40
|
+
Load the given st.h5ad, split into an n×n spatial grid,
|
|
41
|
+
and write each patch as st.h5ad into a subdirectory of output_dir.
|
|
42
|
+
|
|
43
|
+
Every spot is guaranteed to appear in exactly one patch.
|
|
44
|
+
Empty patches (no spots) are skipped with a warning.
|
|
45
|
+
|
|
46
|
+
Args:
|
|
47
|
+
st_path: Full path to the ST h5ad file.
|
|
48
|
+
n: Grid dimension. Produces up to n×n patches.
|
|
49
|
+
output_dir: Root directory where patch subdirectories are written.
|
|
50
|
+
"""
|
|
51
|
+
if not st_path.exists():
|
|
52
|
+
raise FileNotFoundError(f"ST file not found: {st_path}")
|
|
53
|
+
|
|
54
|
+
logger.info("Loading ST data from %s", st_path)
|
|
55
|
+
adata_st = ad.read_h5ad(st_path)
|
|
56
|
+
|
|
57
|
+
if "spatial" not in adata_st.obsm:
|
|
58
|
+
raise ValueError(
|
|
59
|
+
"adata_st.obsm['spatial'] is missing — cannot split spatially. "
|
|
60
|
+
"Run convert_csv_to_h5ad first if working with legacy CSV data."
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
coords = adata_st.obsm["spatial"] # S x 2
|
|
64
|
+
x = coords[:, 0].astype(float)
|
|
65
|
+
y = coords[:, 1].astype(float)
|
|
66
|
+
|
|
67
|
+
logger.info(
|
|
68
|
+
"Loaded %d spots. Coordinate ranges: x=[%.4f, %.4f], y=[%.4f, %.4f]",
|
|
69
|
+
adata_st.n_obs,
|
|
70
|
+
x.min(),
|
|
71
|
+
x.max(),
|
|
72
|
+
y.min(),
|
|
73
|
+
y.max(),
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
# --- Bin assignment ---
|
|
77
|
+
# Build n+1 evenly spaced edges covering the full coordinate range.
|
|
78
|
+
# np.digitize returns 1-indexed bins; subtract 1 for 0-indexed.
|
|
79
|
+
# Spots exactly at the maximum edge get bin index n (out of [0, n-1]),
|
|
80
|
+
# so clip them to n-1. This puts boundary spots into the last bin and
|
|
81
|
+
# ensures every spot belongs to exactly one patch.
|
|
82
|
+
x_edges = np.linspace(x.min(), x.max(), n + 1)
|
|
83
|
+
y_edges = np.linspace(y.min(), y.max(), n + 1)
|
|
84
|
+
|
|
85
|
+
x_bins = np.clip(
|
|
86
|
+
np.digitize(x, x_edges) - 1, 0, n - 1
|
|
87
|
+
) # shape (S,), values in [0, n-1]
|
|
88
|
+
y_bins = np.clip(
|
|
89
|
+
np.digitize(y, y_edges) - 1, 0, n - 1
|
|
90
|
+
) # shape (S,), values in [0, n-1]
|
|
91
|
+
|
|
92
|
+
output_dir.mkdir(parents=True, exist_ok=True)
|
|
93
|
+
|
|
94
|
+
total_spots_written = 0
|
|
95
|
+
patches_written = 0
|
|
96
|
+
summary_rows = []
|
|
97
|
+
|
|
98
|
+
for row in range(n):
|
|
99
|
+
for col in range(n):
|
|
100
|
+
mask = (x_bins == row) & (y_bins == col)
|
|
101
|
+
n_spots = int(mask.sum())
|
|
102
|
+
|
|
103
|
+
if n_spots == 0:
|
|
104
|
+
logger.warning("Patch (%d, %d) contains no spots — skipping.", row, col)
|
|
105
|
+
summary_rows.append({"patch": f"patch_{row}_{col}", "spots": 0})
|
|
106
|
+
continue
|
|
107
|
+
|
|
108
|
+
patch_adata = adata_st[mask].copy()
|
|
109
|
+
patch_dir = output_dir / f"patch_{row}_{col}"
|
|
110
|
+
patch_dir.mkdir(parents=True, exist_ok=True)
|
|
111
|
+
out_path = patch_dir / "st.h5ad"
|
|
112
|
+
patch_adata.write_h5ad(out_path)
|
|
113
|
+
|
|
114
|
+
logger.info("Patch (%d, %d): %5d spots -> %s", row, col, n_spots, out_path)
|
|
115
|
+
|
|
116
|
+
total_spots_written += n_spots
|
|
117
|
+
patches_written += 1
|
|
118
|
+
summary_rows.append({"patch": f"patch_{row}_{col}", "spots": n_spots})
|
|
119
|
+
|
|
120
|
+
summary_path = output_dir / "summary.csv"
|
|
121
|
+
with open(summary_path, "w", newline="") as f:
|
|
122
|
+
writer = csv.DictWriter(f, fieldnames=["patch", "spots"])
|
|
123
|
+
writer.writeheader()
|
|
124
|
+
writer.writerows(summary_rows)
|
|
125
|
+
logger.info("Summary written to %s", summary_path)
|
|
126
|
+
|
|
127
|
+
# Sanity check: every spot must appear in exactly one patch
|
|
128
|
+
assert total_spots_written == adata_st.n_obs, (
|
|
129
|
+
f"Spot count mismatch after splitting: wrote {total_spots_written}, "
|
|
130
|
+
f"expected {adata_st.n_obs}. This is a bug."
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
logger.info(
|
|
134
|
+
"Done. %d / %d patches written, %d total spots.",
|
|
135
|
+
patches_written,
|
|
136
|
+
n * n,
|
|
137
|
+
total_spots_written,
|
|
138
|
+
)
|
|
139
|
+
print(f"Patch st.h5ad files: {output_dir}/patch_<row>_<col>/st.h5ad")
|
|
140
|
+
|
|
141
|
+
# --- Visualisation ---
|
|
142
|
+
# Assign each spot a flat patch index (row * n + col) for colouring.
|
|
143
|
+
patch_index = x_bins * n + y_bins # shape (S,), values in [0, n*n - 1]
|
|
144
|
+
n_patches = n * n
|
|
145
|
+
|
|
146
|
+
cmap = plt.get_cmap("tab20" if n_patches <= 20 else "turbo", n_patches)
|
|
147
|
+
colors = [cmap(i) for i in range(n_patches)]
|
|
148
|
+
|
|
149
|
+
fig, ax = plt.subplots(figsize=(7, 7))
|
|
150
|
+
for idx in range(n_patches):
|
|
151
|
+
mask = patch_index == idx
|
|
152
|
+
if not mask.any():
|
|
153
|
+
continue
|
|
154
|
+
row, col = divmod(idx, n)
|
|
155
|
+
ax.scatter(
|
|
156
|
+
x[mask],
|
|
157
|
+
y[mask],
|
|
158
|
+
s=1,
|
|
159
|
+
color=colors[idx],
|
|
160
|
+
label=f"patch_{row}_{col}",
|
|
161
|
+
linewidths=0,
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
ax.set_title(
|
|
165
|
+
f"ST spots coloured by {n}×{n} patch assignment ({adata_st.n_obs} spots)"
|
|
166
|
+
)
|
|
167
|
+
ax.set_xlabel("x (spatial coord 0)")
|
|
168
|
+
ax.set_ylabel("y (spatial coord 1)")
|
|
169
|
+
ax.legend(
|
|
170
|
+
markerscale=6,
|
|
171
|
+
bbox_to_anchor=(1.02, 1),
|
|
172
|
+
loc="upper left",
|
|
173
|
+
borderaxespad=0,
|
|
174
|
+
fontsize=8,
|
|
175
|
+
)
|
|
176
|
+
ax.set_aspect("equal")
|
|
177
|
+
|
|
178
|
+
plot_path = output_dir / "patch_overview.png"
|
|
179
|
+
fig.savefig(plot_path, dpi=150, bbox_inches="tight")
|
|
180
|
+
plt.close(fig)
|
|
181
|
+
logger.info("Patch overview plot saved to %s", plot_path)
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def main() -> None:
|
|
185
|
+
logging.basicConfig(
|
|
186
|
+
stream=sys.stdout,
|
|
187
|
+
level=logging.INFO,
|
|
188
|
+
format="%(asctime)s - %(levelname)s - %(message)s",
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
parser = argparse.ArgumentParser(
|
|
192
|
+
description=(
|
|
193
|
+
"Split an ST dataset into an n×n grid of spatial patches. "
|
|
194
|
+
"Each spot is assigned to exactly one patch. "
|
|
195
|
+
"Use the original sc.h5ad together with each patch's st.h5ad."
|
|
196
|
+
)
|
|
197
|
+
)
|
|
198
|
+
parser.add_argument(
|
|
199
|
+
"-d",
|
|
200
|
+
"--dataset",
|
|
201
|
+
type=Path,
|
|
202
|
+
required=True,
|
|
203
|
+
help="Full path to the ST h5ad file (e.g. .../ST/01_mouse-ssp.h5ad)",
|
|
204
|
+
)
|
|
205
|
+
parser.add_argument(
|
|
206
|
+
"-n",
|
|
207
|
+
"--grid",
|
|
208
|
+
type=int,
|
|
209
|
+
required=True,
|
|
210
|
+
help="Grid size n: splits the coordinate space into n×n patches (e.g. 3 → up to 9 patches)",
|
|
211
|
+
)
|
|
212
|
+
parser.add_argument(
|
|
213
|
+
"-o",
|
|
214
|
+
"--output",
|
|
215
|
+
type=Path,
|
|
216
|
+
required=False,
|
|
217
|
+
default=None,
|
|
218
|
+
help=(
|
|
219
|
+
"Output directory for patch subfolders "
|
|
220
|
+
"(default: <dataset_folder>_patches_<n>x<n> next to the dataset)"
|
|
221
|
+
),
|
|
222
|
+
)
|
|
223
|
+
args = parser.parse_args()
|
|
224
|
+
|
|
225
|
+
if args.grid < 1:
|
|
226
|
+
print("ERROR: -n must be >= 1", file=sys.stderr)
|
|
227
|
+
sys.exit(1)
|
|
228
|
+
|
|
229
|
+
output_dir = (
|
|
230
|
+
args.output
|
|
231
|
+
if args.output is not None
|
|
232
|
+
else args.dataset.parent
|
|
233
|
+
/ f"{args.dataset.stem}_patches_{args.grid}x{args.grid}"
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
split_st_into_patches(args.dataset, args.grid, output_dir)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
if __name__ == "__main__":
|
|
240
|
+
main()
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Takes a st.h5ad file and selects the top N highly variable genes,
|
|
2
|
+
# then saves the filtered AnnData to a new h5ad file.
|
|
3
|
+
#
|
|
4
|
+
# Usage:
|
|
5
|
+
# python subset_st_hvg.py <path_to_st.h5ad> <N>
|
|
6
|
+
# Output:
|
|
7
|
+
# <path_to_st>_top<N>hvg.h5ad (same directory as input)
|
|
8
|
+
|
|
9
|
+
import sys
|
|
10
|
+
import os
|
|
11
|
+
import anndata as ad
|
|
12
|
+
import scanpy as sc
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def subset_st_to_top_hvg(input_path: str, n: int) -> None:
|
|
16
|
+
stData = ad.read_h5ad(input_path)
|
|
17
|
+
print(f"Loaded ST data: {stData.n_obs} spots x {stData.n_vars} genes")
|
|
18
|
+
|
|
19
|
+
stLog = stData.copy()
|
|
20
|
+
sc.pp.normalize_total(stLog)
|
|
21
|
+
sc.pp.log1p(stLog)
|
|
22
|
+
sc.pp.highly_variable_genes(stLog, n_top_genes=n, inplace=True)
|
|
23
|
+
|
|
24
|
+
hvgs = stLog.var_names[stLog.var["highly_variable"].values].tolist()
|
|
25
|
+
if len(hvgs) == 0:
|
|
26
|
+
raise RuntimeError("No HVGs selected — check input data and N value")
|
|
27
|
+
|
|
28
|
+
stSubset = stData[:, hvgs].copy()
|
|
29
|
+
|
|
30
|
+
base, ext = os.path.splitext(input_path)
|
|
31
|
+
output_path = f"{base}_top{n}hvg{ext}"
|
|
32
|
+
stSubset.write_h5ad(output_path)
|
|
33
|
+
print(f"Saved: {output_path} ({stSubset.n_obs} spots x {stSubset.n_vars} genes)")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
if __name__ == "__main__":
|
|
37
|
+
if len(sys.argv) != 3:
|
|
38
|
+
print("Usage: python subset_st_hvg.py <path_to_st.h5ad> <N>")
|
|
39
|
+
sys.exit(1)
|
|
40
|
+
|
|
41
|
+
input_path = sys.argv[1]
|
|
42
|
+
n = int(sys.argv[2])
|
|
43
|
+
subset_st_to_top_hvg(input_path, n)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Dataset validation - the checks behind ``aim validate``.
|
|
2
|
+
|
|
3
|
+
* :mod:`~aim.data.validate.validate_sc` - one scRNA reference h5ad
|
|
4
|
+
* :mod:`~aim.data.validate.validate_st` - one ST slice h5ad
|
|
5
|
+
* :mod:`~aim.data.validate.validate_pair` - the scRNA x ST shared-gene pair
|
|
6
|
+
* :mod:`~aim.data.validate.runner` - the two CLI modes (single pair / pairs.csv)
|
|
7
|
+
* :mod:`~aim.data.validate.common` - checks shared by the validators
|
|
8
|
+
|
|
9
|
+
The per-dataset validators take an optional ``index.csv`` row; without one they
|
|
10
|
+
run every intrinsic check and skip the bookkeeping cross-checks.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from .runner import (
|
|
16
|
+
PairFindings,
|
|
17
|
+
SubjectFindings,
|
|
18
|
+
check_pair,
|
|
19
|
+
validate_pairs_csv,
|
|
20
|
+
validate_single_pair,
|
|
21
|
+
)
|
|
22
|
+
from .validate_pair import validate_pair
|
|
23
|
+
from .validate_sc import validate_sc
|
|
24
|
+
from .validate_st import validate_st
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"validate_sc",
|
|
28
|
+
"validate_st",
|
|
29
|
+
"validate_pair",
|
|
30
|
+
"check_pair",
|
|
31
|
+
"PairFindings",
|
|
32
|
+
"SubjectFindings",
|
|
33
|
+
"validate_single_pair",
|
|
34
|
+
"validate_pairs_csv",
|
|
35
|
+
]
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""Shared helpers for the scRNA / ST / pair validators.
|
|
2
|
+
|
|
3
|
+
Every check returns ``(errors, warns)`` as plain string lists; the caller
|
|
4
|
+
(:mod:`aim.data.validate.runner`) collects and prints them. ``errors`` mean the
|
|
5
|
+
dataset violates the h5ad contract in ``CLAUDE.md`` and AIM will fail on it;
|
|
6
|
+
``warns`` are index.csv mismatches or count-matrix suspicions.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import anndata as ad
|
|
12
|
+
import numpy as np
|
|
13
|
+
import pandas as pd
|
|
14
|
+
from scipy.sparse import issparse
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"colored",
|
|
18
|
+
"status_of",
|
|
19
|
+
"is_intable",
|
|
20
|
+
"to_int_safe",
|
|
21
|
+
"load_X",
|
|
22
|
+
"raw_count_sanity",
|
|
23
|
+
"check_gene_names_uppercase",
|
|
24
|
+
"check_gene_names_unique",
|
|
25
|
+
"check_count_matrix",
|
|
26
|
+
"check_index_counts",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def colored(text: str, status: str) -> str:
|
|
31
|
+
codes = {"OK": "\033[92m", "WARN": "\033[93m", "ERROR": "\033[91m"}
|
|
32
|
+
reset = "\033[0m"
|
|
33
|
+
code = codes.get(status, "")
|
|
34
|
+
return f"{code}{text}{reset}"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def status_of(errors: list[str], warns: list[str]) -> str:
|
|
38
|
+
if errors:
|
|
39
|
+
return "ERROR"
|
|
40
|
+
return "WARN" if warns else "OK"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def is_intable(x) -> bool:
|
|
44
|
+
try:
|
|
45
|
+
if isinstance(x, (int, np.integer)):
|
|
46
|
+
return True
|
|
47
|
+
if isinstance(x, str):
|
|
48
|
+
int(x)
|
|
49
|
+
return True
|
|
50
|
+
except Exception:
|
|
51
|
+
return False
|
|
52
|
+
return False
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def to_int_safe(x) -> int:
|
|
56
|
+
if is_intable(x):
|
|
57
|
+
return int(x)
|
|
58
|
+
raise ValueError("not intable")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def load_X(adata: ad.AnnData) -> np.ndarray:
|
|
62
|
+
X = adata.X
|
|
63
|
+
if issparse(X):
|
|
64
|
+
return X.toarray()
|
|
65
|
+
return np.asarray(X)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def raw_count_sanity(X: np.ndarray, label: str) -> list[str]:
|
|
69
|
+
"""Warn if X looks normalized / log-transformed / partly empty."""
|
|
70
|
+
warns: list[str] = []
|
|
71
|
+
row_sums = X.sum(axis=1)
|
|
72
|
+
if row_sums.mean() > 0:
|
|
73
|
+
cv = row_sums.std() / row_sums.mean()
|
|
74
|
+
if cv < 0.01:
|
|
75
|
+
warns.append(
|
|
76
|
+
f"{label}: X appears library-size normalized (row-sum CV={cv:.4f})"
|
|
77
|
+
)
|
|
78
|
+
if X.max() < 20:
|
|
79
|
+
warns.append(f"{label}: X max={X.max():.3f} - may be log1p-transformed")
|
|
80
|
+
sample = X.flatten()[:1000]
|
|
81
|
+
if (np.abs(sample - np.round(sample)) > 1e-4).any():
|
|
82
|
+
warns.append(f"{label}: X contains non-integer values - expected raw counts")
|
|
83
|
+
n_zero = (row_sums == 0).sum()
|
|
84
|
+
if n_zero > 0:
|
|
85
|
+
warns.append(f"{label}: {n_zero} observation(s) with all-zero counts")
|
|
86
|
+
return warns
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def check_gene_names_uppercase(adata: ad.AnnData, label: str) -> list[str]:
|
|
90
|
+
non_upper = [g for g in adata.var_names if g != g.upper()]
|
|
91
|
+
if non_upper:
|
|
92
|
+
return [
|
|
93
|
+
f"{label}: {len(non_upper)} gene names are not uppercase "
|
|
94
|
+
f"(e.g. {non_upper[:3]}) - run "
|
|
95
|
+
f"`python -m aim.data.prepare.normalize_gene_names`"
|
|
96
|
+
]
|
|
97
|
+
return []
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def check_gene_names_unique(adata: ad.AnnData, label: str) -> list[str]:
|
|
101
|
+
counts = pd.Series(adata.var_names.tolist()).value_counts()
|
|
102
|
+
dups = counts[counts > 1]
|
|
103
|
+
if not dups.empty:
|
|
104
|
+
examples = dups.index.tolist()[:3]
|
|
105
|
+
return [
|
|
106
|
+
f"{label}: {len(dups)} duplicate gene name(s) "
|
|
107
|
+
f"(e.g. {examples}) - rename or remove duplicates"
|
|
108
|
+
]
|
|
109
|
+
return []
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def check_count_matrix(X: np.ndarray, label: str) -> tuple[list[str], list[str]]:
|
|
113
|
+
"""NaN / negative values are errors, the raw-count heuristics are warnings."""
|
|
114
|
+
errors: list[str] = []
|
|
115
|
+
if np.isnan(X).any():
|
|
116
|
+
errors.append(f"{label}: NaN values in X")
|
|
117
|
+
elif (X < 0).any():
|
|
118
|
+
errors.append(f"{label}: negative values in X")
|
|
119
|
+
return errors, raw_count_sanity(X, label)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def check_index_counts(
|
|
123
|
+
index_row: "pd.Series | None",
|
|
124
|
+
label: str,
|
|
125
|
+
expectations: list[tuple[str, str, int]],
|
|
126
|
+
) -> list[str]:
|
|
127
|
+
"""Cross-check index.csv count columns against the loaded h5ad.
|
|
128
|
+
|
|
129
|
+
``expectations`` is a list of ``(index.csv column, human label, actual value)``.
|
|
130
|
+
Missing / non-integer cells are ignored - the index is hand-maintained.
|
|
131
|
+
"""
|
|
132
|
+
if index_row is None:
|
|
133
|
+
return []
|
|
134
|
+
warns: list[str] = []
|
|
135
|
+
for idx_col, what, actual in expectations:
|
|
136
|
+
val = index_row.get(idx_col, "")
|
|
137
|
+
if is_intable(val) and to_int_safe(val) != actual:
|
|
138
|
+
warns.append(
|
|
139
|
+
f"{label}: index.csv {idx_col}={val} != actual {what}={actual}"
|
|
140
|
+
)
|
|
141
|
+
return warns
|