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,102 @@
1
+ import os
2
+ import anndata as ad
3
+ import numpy as np
4
+ from scipy.sparse import issparse
5
+
6
+ if __name__ == "__main__":
7
+ """
8
+ Creates a smaller subset dataset from a full scRNA-seq + ST dataset.
9
+ Subsets cells, genes, and spots to configurable target counts, ensuring that
10
+ selected cells and spots each express at least one shared gene.
11
+ Reads from sc.h5ad + st.h5ad and writes sc.h5ad + st.h5ad.
12
+ """
13
+
14
+ dataset_from = "/Users/domi/Dev/MPA_Workspace/MPA_DATA/01_Datasets/03_MouseSSP"
15
+ dataset_to = "/Users/domi/Dev/MPA_Workspace/MPA_DATA/01_Datasets/03_MouseSSP_Large"
16
+
17
+ # Config for mini
18
+ # target_nr_sc_cells = 15
19
+ # target_nr_sc_genes = 30
20
+ # target_nr_st_spots = 10
21
+ # target_nr_st_genes = 20
22
+ # target_nr_shared_genes = 5
23
+
24
+ # Config for midi
25
+ # target_nr_sc_cells = 100
26
+ # target_nr_sc_genes = 300
27
+ # target_nr_st_spots = 80
28
+ # target_nr_st_genes = 240
29
+ # target_nr_shared_genes = 15
30
+
31
+ # Config for large
32
+ target_nr_sc_cells = 1000
33
+ target_nr_sc_genes = 5000
34
+ target_nr_st_spots = 800
35
+ target_nr_st_genes = 33
36
+ target_nr_shared_genes = 33
37
+
38
+ rng: np.random.Generator = (
39
+ np.random.default_rng()
40
+ ) # no fixed seed — sampling is non-deterministic across runs
41
+
42
+ """ Load datasets """
43
+
44
+ scData = ad.read_h5ad(os.path.join(dataset_from, "sc.h5ad")) # C x G
45
+ stData = ad.read_h5ad(os.path.join(dataset_from, "st.h5ad")) # S x G
46
+
47
+ """ Subset genes """
48
+
49
+ # Split genes into shared and non-shared genes
50
+ sharedGenes = scData.var_names.intersection(stData.var_names)
51
+ scNonSharedGenes = scData.var_names.difference(sharedGenes)
52
+ stNonSharedGenes = stData.var_names.difference(sharedGenes)
53
+
54
+ # Create list of genes to keep (target_nr, half shared, half non-shared)
55
+ scGenesToKeep = list(sharedGenes[:target_nr_shared_genes]) + list(
56
+ scNonSharedGenes[: target_nr_sc_genes - target_nr_shared_genes]
57
+ )
58
+ if len(stNonSharedGenes) >= target_nr_shared_genes:
59
+ stGenesToKeep = list(sharedGenes[:target_nr_shared_genes]) + list(
60
+ stNonSharedGenes[: target_nr_st_genes - target_nr_shared_genes]
61
+ )
62
+ else:
63
+ stGenesToKeep = list(sharedGenes[:target_nr_st_genes])
64
+
65
+ """ Subset cells """
66
+
67
+ # Select cells that express at least one shared gene
68
+ sc_mat = scData[:, sharedGenes[:target_nr_shared_genes]].X
69
+ if issparse(sc_mat):
70
+ sc_mask = np.asarray(sc_mat.getnnz(axis=1) > 0).reshape(-1)
71
+ else:
72
+ sc_mask = np.any(sc_mat != 0, axis=1).reshape(-1)
73
+ available_sc = scData.obs_names[sc_mask].tolist()
74
+ n_sc = min(len(available_sc), target_nr_sc_cells)
75
+ scCellsToKeep = rng.choice(available_sc, size=n_sc, replace=False).tolist()
76
+
77
+ """ Subset spots """
78
+
79
+ # Select spots that express at least one shared gene
80
+ st_mat = stData[:, sharedGenes].X
81
+ if issparse(st_mat):
82
+ st_mask = np.asarray(st_mat.getnnz(axis=1) > 0).reshape(-1)
83
+ else:
84
+ st_mask = np.any(st_mat != 0, axis=1).reshape(-1)
85
+ available_st = stData.obs_names[st_mask].tolist()
86
+ n_st = min(len(available_st), target_nr_st_spots)
87
+ stSpotsToKeep = rng.choice(available_st, size=n_st, replace=False).tolist()
88
+
89
+ """ Create subsets """
90
+
91
+ scData_mini = scData[scCellsToKeep, scGenesToKeep].copy()
92
+ stData_mini = stData[stSpotsToKeep, stGenesToKeep].copy()
93
+
94
+ """ Save to disk """
95
+
96
+ os.makedirs(dataset_to, exist_ok=True)
97
+ scData_mini.write_h5ad(os.path.join(dataset_to, "sc.h5ad"))
98
+ stData_mini.write_h5ad(os.path.join(dataset_to, "st.h5ad"))
99
+
100
+ print(f"Saved subset dataset to {dataset_to}")
101
+ print(f" scRNA: {scData_mini.n_obs} cells x {scData_mini.n_vars} genes")
102
+ print(f" ST: {stData_mini.n_obs} spots x {stData_mini.n_vars} genes")
@@ -0,0 +1,56 @@
1
+ """
2
+ Uppercases var_names in all h5ad files under scRNA/ and ST/ subdirectories.
3
+ Run once after adding new datasets to ensure consistent gene name casing.
4
+
5
+ Usage:
6
+ python -m src.data_preparation.normalize_gene_names
7
+ python -m src.data_preparation.normalize_gene_names -d /path/to/01_Datasets
8
+ """
9
+
10
+ import argparse
11
+ from pathlib import Path
12
+ import anndata as ad
13
+
14
+
15
+ def normalize_file(path: Path) -> None:
16
+ adata = ad.read_h5ad(path)
17
+ original = adata.var_names.tolist()
18
+ uppercased = [g.upper() for g in original]
19
+
20
+ if original == uppercased:
21
+ print(f" {path.name}: already uppercase, skipped")
22
+ return
23
+
24
+ changed = sum(1 for a, b in zip(original, uppercased) if a != b)
25
+ adata.var_names = uppercased
26
+ adata.write_h5ad(path)
27
+ print(f" {path.name}: uppercased {changed} gene names")
28
+
29
+
30
+ def main() -> None:
31
+ parser = argparse.ArgumentParser(
32
+ description="Uppercase var_names in all h5ad files"
33
+ )
34
+ parser.add_argument(
35
+ "--data-root",
36
+ "-d",
37
+ type=Path,
38
+ default=Path(r"/01_Datasets"),
39
+ )
40
+ args = parser.parse_args()
41
+
42
+ root: Path = args.data_root
43
+ for subdir in ["scRNA", "ST"]:
44
+ folder = root / subdir
45
+ h5ads = sorted(folder.glob("*.h5ad"))
46
+ if not h5ads:
47
+ continue
48
+ print(f"\n{subdir}/")
49
+ for path in h5ads:
50
+ normalize_file(path)
51
+
52
+ print("\nDone.")
53
+
54
+
55
+ if __name__ == "__main__":
56
+ main()
@@ -0,0 +1,107 @@
1
+ # Generates noise-perturbed versions of an SC dataset for metric validation.
2
+ #
3
+ # For each noise level alpha, adds isotropic Gaussian noise scaled to the
4
+ # global expression standard deviation:
5
+ # X_perturbed = clip(X + N(0, alpha * X.std()), min=0)
6
+ #
7
+ # alpha=0 → identity, alpha=1 → noise std equals the data std,
8
+ # higher alpha → progressively destroys cell-state structure.
9
+ # Values are clipped at 0 to preserve non-negativity.
10
+ #
11
+ # Usage:
12
+ # python -m src.data_preparation.perturb_sc_noise \
13
+ # --scdata <path/to/sc.h5ad> \
14
+ # --noise_levels 0.5 1.0 2.0 5.0 \
15
+ # [--output_dir <dir>] # default: same directory as input
16
+ # [--seed 42]
17
+
18
+ import argparse
19
+ import logging
20
+ from pathlib import Path
21
+
22
+ import anndata as ad
23
+ import numpy as np
24
+ import scipy.sparse as sp
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+
29
+ def perturb_sc(
30
+ sc_adata: ad.AnnData,
31
+ noise_level: float,
32
+ seed: int = 42,
33
+ ) -> ad.AnnData:
34
+ """
35
+ Return a copy of sc_adata with Gaussian noise added to the expression matrix.
36
+ Noise std = noise_level * global expression std. Values clipped at 0.
37
+ """
38
+ X = (
39
+ sc_adata.X.toarray()
40
+ if sp.issparse(sc_adata.X)
41
+ else np.asarray(sc_adata.X, dtype=float)
42
+ )
43
+
44
+ if noise_level == 0.0:
45
+ return sc_adata.copy()
46
+
47
+ rng = np.random.default_rng(seed)
48
+ sigma = noise_level * X.std()
49
+ noise = rng.normal(0.0, sigma, size=X.shape)
50
+ X_perturbed = np.clip(X + noise, a_min=0.0, a_max=None)
51
+
52
+ result = sc_adata.copy()
53
+ result.X = X_perturbed.astype(np.float32)
54
+ result.uns["perturbation"] = {
55
+ "type": "gaussian_noise",
56
+ "noise_level": noise_level,
57
+ "seed": seed,
58
+ }
59
+ return result
60
+
61
+
62
+ def main(sc_path: Path, noise_levels: list[float], output_dir: Path, seed: int) -> None:
63
+ logger.info(f"Loading {sc_path} ...")
64
+ sc_adata = ad.read_h5ad(sc_path)
65
+ logger.info(f" {sc_adata.n_obs} cells x {sc_adata.n_vars} genes")
66
+
67
+ output_dir.mkdir(parents=True, exist_ok=True)
68
+ stem = sc_path.stem # e.g. "sc"
69
+
70
+ for alpha in noise_levels:
71
+ perturbed = perturb_sc(sc_adata, alpha, seed=seed)
72
+ label = f"{alpha:.2f}".replace(".", "p") # e.g. 0.50 → "0p50"
73
+ out_path = output_dir / f"{stem}_noise{label}.h5ad"
74
+ perturbed.write_h5ad(out_path)
75
+ logger.info(f" Saved noise_level={alpha}: {out_path}")
76
+
77
+ logger.info("Done.")
78
+
79
+
80
+ if __name__ == "__main__":
81
+ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
82
+
83
+ parser = argparse.ArgumentParser(
84
+ description="Generate noise-perturbed SC datasets for metric validation."
85
+ )
86
+ parser.add_argument("--scdata", required=True, type=Path, help="Path to sc.h5ad")
87
+ parser.add_argument(
88
+ "--noise_levels",
89
+ required=True,
90
+ type=float,
91
+ nargs="+",
92
+ help="One or more noise level multipliers (e.g. 0.5 1.0 2.0 5.0)",
93
+ )
94
+ parser.add_argument(
95
+ "--output_dir",
96
+ default=None,
97
+ type=Path,
98
+ help="Output directory (default: same directory as input)",
99
+ )
100
+ parser.add_argument(
101
+ "--seed", default=42, type=int, help="Random seed (default: 42)"
102
+ )
103
+ args = parser.parse_args()
104
+
105
+ output_dir = args.output_dir if args.output_dir is not None else args.scdata.parent
106
+
107
+ main(args.scdata, args.noise_levels, output_dir, args.seed)
@@ -0,0 +1,180 @@
1
+ """
2
+ Register the output of split_st_into_patches.py into the database.
3
+
4
+ split_st_into_patches.py writes <base>_patches_NxN/patch_<r>_<c>/st.h5ad but does
5
+ NOT touch the database. This script copies those patch files into ST/ under the
6
+ slice naming convention {nn}_{i}_{tissue}.h5ad (as used by datasets 05/09/10) and
7
+ replaces the monolithic ST entry with one row per patch in ST/index.csv and pairs.csv.
8
+
9
+ Patches are numbered 1..N in row-major order over the non-empty patches. The
10
+ monolithic scRNA reference is reused for every patch (scName unchanged). The
11
+ monolithic ST h5ad is left on disk but removed from index.csv/pairs.csv (delete it
12
+ yourself once you are happy with the split).
13
+
14
+ Usage:
15
+ python -m data_preparation.register_st_patches \
16
+ --patches-dir "C:/Users/zi69hebi/Dev/10_Alignment/Data/01_Datasets/ST/11_human-breast-cancer_patches_5x5" \
17
+ [--data-root "C:/Users/zi69hebi/Dev/10_Alignment/Data/01_Datasets"] \
18
+ [--dry-run]
19
+ """
20
+
21
+ import argparse
22
+ import csv
23
+ import logging
24
+ import re
25
+ import shutil
26
+ import sys
27
+ from pathlib import Path
28
+
29
+ import anndata as ad
30
+
31
+ logger = logging.getLogger(__name__)
32
+
33
+ DEFAULT_DATA_ROOT = Path(r"/01_Datasets")
34
+ _PATCH_RE = re.compile(r"^patch_(\d+)_(\d+)$")
35
+
36
+
37
+ def _st_sort_key(name: str) -> tuple[int, int, int]:
38
+ m = re.match(r"^(\d+)_(\d+)_(\d+)_", name)
39
+ if m:
40
+ return int(m.group(1)), int(m.group(2)), int(m.group(3))
41
+ m = re.match(r"^(\d+)_(\d+)_", name)
42
+ if m:
43
+ return int(m.group(1)), int(m.group(2)), 0
44
+ m = re.match(r"^(\d+)_", name)
45
+ if m:
46
+ return int(m.group(1)), 0, 0
47
+ return 999, 999, 999
48
+
49
+
50
+ def _ordered_patches(patches_dir: Path) -> list[tuple[Path, int]]:
51
+ """Return [(patch_st_h5ad, n_spots), ...] in row-major (r, c) order, non-empty only."""
52
+ dirs = []
53
+ for d in patches_dir.glob("patch_*"):
54
+ m = _PATCH_RE.match(d.name)
55
+ if m and (d / "st.h5ad").exists():
56
+ dirs.append((int(m.group(1)), int(m.group(2)), d / "st.h5ad"))
57
+ dirs.sort()
58
+ out = []
59
+ for _, _, h5 in dirs:
60
+ n = ad.read_h5ad(h5).n_obs
61
+ out.append((h5, n))
62
+ return out
63
+
64
+
65
+ def main() -> None:
66
+ logging.basicConfig(
67
+ stream=sys.stdout,
68
+ level=logging.INFO,
69
+ format="%(asctime)s %(levelname)s %(message)s",
70
+ )
71
+ p = argparse.ArgumentParser(
72
+ description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
73
+ )
74
+ p.add_argument("--patches-dir", type=Path, required=True)
75
+ p.add_argument("--data-root", type=Path, default=DEFAULT_DATA_ROOT)
76
+ p.add_argument("--dry-run", action="store_true")
77
+ args = p.parse_args()
78
+
79
+ st_dir = args.data_root / "ST"
80
+ st_index_path = st_dir / "index.csv"
81
+ pairs_path = args.data_root / "pairs.csv"
82
+
83
+ # Base ST name = patches dir name minus the "_patches_NxN" suffix
84
+ base_name = re.sub(r"_patches_\d+x\d+$", "", args.patches_dir.name)
85
+ m = re.match(r"^(\d+)_(.+)$", base_name)
86
+ if not m:
87
+ logger.error("Cannot parse dataset id from base name %r", base_name)
88
+ sys.exit(1)
89
+ dataset_id, tissue = m.group(1), m.group(2)
90
+ logger.info(
91
+ "Base ST dataset: %s (id=%s, tissue=%s)", base_name, dataset_id, tissue
92
+ )
93
+
94
+ patches = _ordered_patches(args.patches_dir)
95
+ if not patches:
96
+ logger.error(
97
+ "No non-empty patch st.h5ad files found under %s", args.patches_dir
98
+ )
99
+ sys.exit(1)
100
+ total = sum(n for _, n in patches)
101
+ logger.info("%d non-empty patches, %d spots total", len(patches), total)
102
+
103
+ # --- Load DB tables ---
104
+ with open(st_index_path, newline="") as f:
105
+ st_reader = csv.DictReader(f)
106
+ st_fields = list(st_reader.fieldnames or [])
107
+ st_rows = list(st_reader)
108
+ with open(pairs_path, newline="") as f:
109
+ pairs_reader = csv.DictReader(f)
110
+ pairs_fields = list(pairs_reader.fieldnames or [])
111
+ pairs_rows = list(pairs_reader)
112
+
113
+ st_template = next((r for r in st_rows if r.get("Name") == base_name), None)
114
+ if st_template is None:
115
+ logger.error("ST/index.csv has no row named %r", base_name)
116
+ sys.exit(1)
117
+ base_pairs = [r for r in pairs_rows if r.get("stName") == base_name]
118
+ if not base_pairs:
119
+ logger.error("pairs.csv has no pair with stName %r", base_name)
120
+ sys.exit(1)
121
+
122
+ # --- Build new slice rows / pairs / file copies ---
123
+ new_st_rows, new_pairs, copies = [], [], []
124
+ for i, (h5, n_spots) in enumerate(patches, start=1):
125
+ new_name = f"{dataset_id}_{i}_{tissue}"
126
+ copies.append((h5, st_dir / f"{new_name}.h5ad"))
127
+ new_st_rows.append({**st_template, "Name": new_name, "SpotCount": str(n_spots)})
128
+ for bp in base_pairs:
129
+ new_pairs.append({**bp, "stName": new_name})
130
+
131
+ # Replace monolith with slices
132
+ st_rows = [r for r in st_rows if r.get("Name") != base_name] + new_st_rows
133
+ pairs_rows = [r for r in pairs_rows if r.get("stName") != base_name] + new_pairs
134
+ st_rows.sort(key=lambda r: _st_sort_key(r["Name"]))
135
+ for new_id, r in enumerate(pairs_rows):
136
+ r["PairID"] = str(new_id)
137
+
138
+ if args.dry_run:
139
+ logger.info("[dry-run] would copy %d files, e.g.:", len(copies))
140
+ for src, dst in copies[:3]:
141
+ logger.info(" %s -> %s", src, dst.name)
142
+ logger.info("[dry-run] ST/index.csv: -1 monolith, +%d slices", len(new_st_rows))
143
+ logger.info(
144
+ "[dry-run] pairs.csv: -%d monolith pair(s), +%d, renumber to 0..%d",
145
+ len(base_pairs),
146
+ len(new_pairs),
147
+ len(pairs_rows) - 1,
148
+ )
149
+ return
150
+
151
+ for src, dst in copies:
152
+ shutil.copyfile(src, dst)
153
+ logger.info("Copied %d patch files into %s", len(copies), st_dir)
154
+
155
+ shutil.copyfile(st_index_path, st_index_path.with_suffix(".csv.bak"))
156
+ with open(st_index_path, "w", newline="") as f:
157
+ w = csv.DictWriter(f, fieldnames=st_fields)
158
+ w.writeheader()
159
+ w.writerows(st_rows)
160
+ logger.info("Updated %s (backup .bak): %d rows", st_index_path.name, len(st_rows))
161
+
162
+ shutil.copyfile(pairs_path, pairs_path.with_suffix(".csv.bak"))
163
+ with open(pairs_path, "w", newline="") as f:
164
+ w = csv.DictWriter(f, fieldnames=pairs_fields)
165
+ w.writeheader()
166
+ w.writerows(pairs_rows)
167
+ logger.info("Updated %s (backup .bak): %d pairs", pairs_path.name, len(pairs_rows))
168
+
169
+ logger.info(
170
+ "Monolith %s.h5ad left on disk (now unregistered); delete it when ready.",
171
+ base_name,
172
+ )
173
+ logger.info(
174
+ "Done. Validate with: aim validate --pairs_csv %s",
175
+ Path(args.data_root) / "pairs.csv",
176
+ )
177
+
178
+
179
+ if __name__ == "__main__":
180
+ main()