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.
Files changed (76) hide show
  1. aim/__init__.py +47 -0
  2. aim/__main__.py +6 -0
  3. aim/adata_schema.py +80 -0
  4. aim/aggregation.py +118 -0
  5. aim/aim_config.py +76 -0
  6. aim/analysis/__init__.py +13 -0
  7. aim/analysis/analysis.py +72 -0
  8. aim/analysis/biology.py +205 -0
  9. aim/analysis/confidence.py +49 -0
  10. aim/analysis/ksweep.py +184 -0
  11. aim/analysis/loading.py +70 -0
  12. aim/analysis/onehot.py +41 -0
  13. aim/analysis/reconstruction.py +131 -0
  14. aim/analysis/topology.py +142 -0
  15. aim/analysis/utils.py +16 -0
  16. aim/cli.py +371 -0
  17. aim/clustering.py +242 -0
  18. aim/data/__init__.py +0 -0
  19. aim/data/prepare/__init__.py +0 -0
  20. aim/data/prepare/build_imaging_pairs.py +397 -0
  21. aim/data/prepare/build_xenium_breast_pair.py +310 -0
  22. aim/data/prepare/convertTsvToCsv.py +39 -0
  23. aim/data/prepare/convert_csv_to_h5ad.py +217 -0
  24. aim/data/prepare/createOnlyHVGDataset.py +69 -0
  25. aim/data/prepare/createSmallerDataset.py +102 -0
  26. aim/data/prepare/normalize_gene_names.py +56 -0
  27. aim/data/prepare/perturb_sc_noise.py +107 -0
  28. aim/data/prepare/register_st_patches.py +180 -0
  29. aim/data/prepare/split_st_into_islands.py +551 -0
  30. aim/data/prepare/split_st_into_patches.py +240 -0
  31. aim/data/prepare/subset_st_hvg.py +43 -0
  32. aim/data/validate/__init__.py +35 -0
  33. aim/data/validate/common.py +141 -0
  34. aim/data/validate/runner.py +335 -0
  35. aim/data/validate/validate_pair.py +53 -0
  36. aim/data/validate/validate_sc.py +103 -0
  37. aim/data/validate/validate_st.py +74 -0
  38. aim/gui/__init__.py +8 -0
  39. aim/gui/__main__.py +77 -0
  40. aim/gui/app.py +1784 -0
  41. aim/gui/compute.py +106 -0
  42. aim/gui/data_access.py +292 -0
  43. aim/gui/render.py +1679 -0
  44. aim/gui/scaffold.py +129 -0
  45. aim/gui/widgets.py +675 -0
  46. aim/io.py +196 -0
  47. aim/mapping/__init__.py +14 -0
  48. aim/mapping/base.py +67 -0
  49. aim/mapping/confidence.py +51 -0
  50. aim/mapping/nearest_centroid.py +33 -0
  51. aim/mapping/reference.py +156 -0
  52. aim/mapping/wann.py +208 -0
  53. aim/metrics/__init__.py +26 -0
  54. aim/metrics/biology.py +69 -0
  55. aim/metrics/cossim.py +127 -0
  56. aim/metrics/kselection.py +272 -0
  57. aim/metrics/onehot.py +54 -0
  58. aim/metrics/reconstruction.py +73 -0
  59. aim/metrics/topology.py +62 -0
  60. aim/reference_aligners/__init__.py +0 -0
  61. aim/reference_aligners/environment_dot.yml +23 -0
  62. aim/reference_aligners/environment_tacco.yml +28 -0
  63. aim/reference_aligners/environment_tangram.yml +16 -0
  64. aim/reference_aligners/registry.py +350 -0
  65. aim/reference_aligners/run_dot.R +172 -0
  66. aim/reference_aligners/run_dot.py +116 -0
  67. aim/reference_aligners/run_tacco.py +143 -0
  68. aim/reference_aligners/run_tangram.py +210 -0
  69. aim/sweep.py +261 -0
  70. aim/tree.py +86 -0
  71. spatial_aim-1.0.0.dist-info/METADATA +1005 -0
  72. spatial_aim-1.0.0.dist-info/RECORD +76 -0
  73. spatial_aim-1.0.0.dist-info/WHEEL +5 -0
  74. spatial_aim-1.0.0.dist-info/entry_points.txt +2 -0
  75. spatial_aim-1.0.0.dist-info/licenses/LICENSE +674 -0
  76. 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