sopa-companion 0.7.0__tar.gz

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 (294) hide show
  1. sopa_companion-0.7.0/LICENSE +28 -0
  2. sopa_companion-0.7.0/PKG-INFO +564 -0
  3. sopa_companion-0.7.0/README.md +505 -0
  4. sopa_companion-0.7.0/__init__.py +46 -0
  5. sopa_companion-0.7.0/__main__.py +4 -0
  6. sopa_companion-0.7.0/analysis/__init__.py +2 -0
  7. sopa_companion-0.7.0/analysis/backend.py +31 -0
  8. sopa_companion-0.7.0/analysis/counts_file.py +399 -0
  9. sopa_companion-0.7.0/analysis/cpu.py +348 -0
  10. sopa_companion-0.7.0/analysis/cpu_kernels.py +36 -0
  11. sopa_companion-0.7.0/analysis/qc_probe.py +143 -0
  12. sopa_companion-0.7.0/analysis/qc_trainer.py +1940 -0
  13. sopa_companion-0.7.0/analysis/worker.py +4665 -0
  14. sopa_companion-0.7.0/api/__init__.py +8 -0
  15. sopa_companion-0.7.0/api/deliver.py +421 -0
  16. sopa_companion-0.7.0/api/folders.py +364 -0
  17. sopa_companion-0.7.0/api/handle.py +544 -0
  18. sopa_companion-0.7.0/api/launch.py +348 -0
  19. sopa_companion-0.7.0/api/mainthread.py +147 -0
  20. sopa_companion-0.7.0/api/protocol.py +396 -0
  21. sopa_companion-0.7.0/api/result.py +14 -0
  22. sopa_companion-0.7.0/api/window.py +224 -0
  23. sopa_companion-0.7.0/cli.py +233 -0
  24. sopa_companion-0.7.0/config.example.toml +155 -0
  25. sopa_companion-0.7.0/desktop/__init__.py +1 -0
  26. sopa_companion-0.7.0/desktop/browser.py +617 -0
  27. sopa_companion-0.7.0/desktop/chrome.py +67 -0
  28. sopa_companion-0.7.0/desktop/install.py +236 -0
  29. sopa_companion-0.7.0/desktop/launcher.py +573 -0
  30. sopa_companion-0.7.0/desktop/logs.py +121 -0
  31. sopa_companion-0.7.0/desktop/migrate.py +322 -0
  32. sopa_companion-0.7.0/desktop/processes.py +241 -0
  33. sopa_companion-0.7.0/desktop/sopa-companion.svg +68 -0
  34. sopa_companion-0.7.0/desktop/window.py +81 -0
  35. sopa_companion-0.7.0/dirs.py +80 -0
  36. sopa_companion-0.7.0/engine/analysis.py +3281 -0
  37. sopa_companion-0.7.0/engine/cellpose_settings.py +279 -0
  38. sopa_companion-0.7.0/engine/children.py +217 -0
  39. sopa_companion-0.7.0/engine/compare.py +1306 -0
  40. sopa_companion-0.7.0/engine/config.py +267 -0
  41. sopa_companion-0.7.0/engine/counts_spool.py +246 -0
  42. sopa_companion-0.7.0/engine/crashlog.py +869 -0
  43. sopa_companion-0.7.0/engine/deeper.py +863 -0
  44. sopa_companion-0.7.0/engine/deeper_where.py +988 -0
  45. sopa_companion-0.7.0/engine/held.py +358 -0
  46. sopa_companion-0.7.0/engine/leftovers.py +240 -0
  47. sopa_companion-0.7.0/engine/patch_folders.py +763 -0
  48. sopa_companion-0.7.0/engine/proseg_options.py +1496 -0
  49. sopa_companion-0.7.0/engine/qc.py +4327 -0
  50. sopa_companion-0.7.0/engine/qc_areas.py +961 -0
  51. sopa_companion-0.7.0/engine/qc_constants.py +105 -0
  52. sopa_companion-0.7.0/engine/qc_pool.py +2502 -0
  53. sopa_companion-0.7.0/engine/qc_readout.py +504 -0
  54. sopa_companion-0.7.0/engine/qc_rule.py +428 -0
  55. sopa_companion-0.7.0/engine/qc_rules.py +937 -0
  56. sopa_companion-0.7.0/engine/qc_scoring.py +947 -0
  57. sopa_companion-0.7.0/engine/qc_test.py +1889 -0
  58. sopa_companion-0.7.0/engine/runlog.py +1507 -0
  59. sopa_companion-0.7.0/engine/runs.py +3359 -0
  60. sopa_companion-0.7.0/engine/samples.py +332 -0
  61. sopa_companion-0.7.0/engine/session.py +453 -0
  62. sopa_companion-0.7.0/engine/shape_query.py +274 -0
  63. sopa_companion-0.7.0/engine/shipping.py +21 -0
  64. sopa_companion-0.7.0/engine/stain.py +654 -0
  65. sopa_companion-0.7.0/engine/stain_exclusions.py +409 -0
  66. sopa_companion-0.7.0/engine/stain_intensity.py +187 -0
  67. sopa_companion-0.7.0/engine/stain_levels.py +133 -0
  68. sopa_companion-0.7.0/engine/stain_patches.py +710 -0
  69. sopa_companion-0.7.0/engine/stain_rules.py +160 -0
  70. sopa_companion-0.7.0/engine/stain_worker.py +73 -0
  71. sopa_companion-0.7.0/engine/tiles.py +151 -0
  72. sopa_companion-0.7.0/engine/transcript_index.py +95 -0
  73. sopa_companion-0.7.0/engine/vectors.py +224 -0
  74. sopa_companion-0.7.0/engine/zarr_samples.py +1635 -0
  75. sopa_companion-0.7.0/frontend/demos/background-gaps.json +1 -0
  76. sopa_companion-0.7.0/frontend/demos/compactness.json +1 -0
  77. sopa_companion-0.7.0/frontend/demos/crowding-levels.json +1 -0
  78. sopa_companion-0.7.0/frontend/demos/depth-layers.json +1 -0
  79. sopa_companion-0.7.0/frontend/demos/drift.json +1 -0
  80. sopa_companion-0.7.0/frontend/demos/far-drift.json +1 -0
  81. sopa_companion-0.7.0/frontend/demos/hold.json +1 -0
  82. sopa_companion-0.7.0/frontend/demos/short-drift.json +1 -0
  83. sopa_companion-0.7.0/frontend/demos/starting-grid.json +1 -0
  84. sopa_companion-0.7.0/frontend/index.html +298 -0
  85. sopa_companion-0.7.0/frontend/src/analysis-helpers.mjs +44 -0
  86. sopa_companion-0.7.0/frontend/src/analysis-settings.mjs +236 -0
  87. sopa_companion-0.7.0/frontend/src/analysis.js +517 -0
  88. sopa_companion-0.7.0/frontend/src/api.js +375 -0
  89. sopa_companion-0.7.0/frontend/src/cellstats.mjs +157 -0
  90. sopa_companion-0.7.0/frontend/src/cluster-gpu.js +52 -0
  91. sopa_companion-0.7.0/frontend/src/clusters.js +110 -0
  92. sopa_companion-0.7.0/frontend/src/compare-copy.mjs +222 -0
  93. sopa_companion-0.7.0/frontend/src/compare.css +143 -0
  94. sopa_companion-0.7.0/frontend/src/compare.mjs +1649 -0
  95. sopa_companion-0.7.0/frontend/src/crash-report.mjs +225 -0
  96. sopa_companion-0.7.0/frontend/src/explain.css +7 -0
  97. sopa_companion-0.7.0/frontend/src/explain.mjs +123 -0
  98. sopa_companion-0.7.0/frontend/src/glow.mjs +234 -0
  99. sopa_companion-0.7.0/frontend/src/harness-hook.mjs +143 -0
  100. sopa_companion-0.7.0/frontend/src/image-layers.mjs +45 -0
  101. sopa_companion-0.7.0/frontend/src/lasso.mjs +169 -0
  102. sopa_companion-0.7.0/frontend/src/layer-panel.js +225 -0
  103. sopa_companion-0.7.0/frontend/src/log-export.mjs +444 -0
  104. sopa_companion-0.7.0/frontend/src/main.js +3733 -0
  105. sopa_companion-0.7.0/frontend/src/older-runs.mjs +405 -0
  106. sopa_companion-0.7.0/frontend/src/option-guide.mjs +75 -0
  107. sopa_companion-0.7.0/frontend/src/options.js +419 -0
  108. sopa_companion-0.7.0/frontend/src/page-key.mjs +155 -0
  109. sopa_companion-0.7.0/frontend/src/paint-batch.mjs +75 -0
  110. sopa_companion-0.7.0/frontend/src/patch-folder.mjs +275 -0
  111. sopa_companion-0.7.0/frontend/src/polygons.mjs +142 -0
  112. sopa_companion-0.7.0/frontend/src/prior-layers.js +487 -0
  113. sopa_companion-0.7.0/frontend/src/prior-options.mjs +46 -0
  114. sopa_companion-0.7.0/frontend/src/prior-paths.mjs +152 -0
  115. sopa_companion-0.7.0/frontend/src/prior-raster-worker.mjs +15 -0
  116. sopa_companion-0.7.0/frontend/src/prior-raster.mjs +39 -0
  117. sopa_companion-0.7.0/frontend/src/proceed.mjs +47 -0
  118. sopa_companion-0.7.0/frontend/src/qc-areas.mjs +36 -0
  119. sopa_companion-0.7.0/frontend/src/qc-chart.mjs +333 -0
  120. sopa_companion-0.7.0/frontend/src/qc-chip.mjs +106 -0
  121. sopa_companion-0.7.0/frontend/src/qc-client.mjs +880 -0
  122. sopa_companion-0.7.0/frontend/src/qc-copy.mjs +1324 -0
  123. sopa_companion-0.7.0/frontend/src/qc-deeper-copy.mjs +645 -0
  124. sopa_companion-0.7.0/frontend/src/qc-deeper.css +183 -0
  125. sopa_companion-0.7.0/frontend/src/qc-deeper.js +2707 -0
  126. sopa_companion-0.7.0/frontend/src/qc-overlay.mjs +662 -0
  127. sopa_companion-0.7.0/frontend/src/qc-panel.js +2173 -0
  128. sopa_companion-0.7.0/frontend/src/qc-test-corner-copy.mjs +128 -0
  129. sopa_companion-0.7.0/frontend/src/qc-test-corner.css +190 -0
  130. sopa_companion-0.7.0/frontend/src/qc-test-corner.mjs +1567 -0
  131. sopa_companion-0.7.0/frontend/src/qc.css +153 -0
  132. sopa_companion-0.7.0/frontend/src/range-chooser.mjs +206 -0
  133. sopa_companion-0.7.0/frontend/src/region.mjs +137 -0
  134. sopa_companion-0.7.0/frontend/src/robustness.mjs +17 -0
  135. sopa_companion-0.7.0/frontend/src/run-buttons.mjs +17 -0
  136. sopa_companion-0.7.0/frontend/src/sample-browser.js +145 -0
  137. sopa_companion-0.7.0/frontend/src/sample-notes.mjs +83 -0
  138. sopa_companion-0.7.0/frontend/src/scene3d.js +95 -0
  139. sopa_companion-0.7.0/frontend/src/seg-layers.mjs +324 -0
  140. sopa_companion-0.7.0/frontend/src/session.mjs +123 -0
  141. sopa_companion-0.7.0/frontend/src/setting-demo.css +43 -0
  142. sopa_companion-0.7.0/frontend/src/setting-demo.mjs +803 -0
  143. sopa_companion-0.7.0/frontend/src/shell.mjs +317 -0
  144. sopa_companion-0.7.0/frontend/src/stage.js +1479 -0
  145. sopa_companion-0.7.0/frontend/src/stain-cells.mjs +107 -0
  146. sopa_companion-0.7.0/frontend/src/stain-exclusions.css +32 -0
  147. sopa_companion-0.7.0/frontend/src/stain-exclusions.mjs +748 -0
  148. sopa_companion-0.7.0/frontend/src/stain-patches.css +28 -0
  149. sopa_companion-0.7.0/frontend/src/stain-patches.mjs +468 -0
  150. sopa_companion-0.7.0/frontend/src/stain-settings.mjs +115 -0
  151. sopa_companion-0.7.0/frontend/src/stain.mjs +445 -0
  152. sopa_companion-0.7.0/frontend/src/storage-boot.mjs +91 -0
  153. sopa_companion-0.7.0/frontend/src/telemetry.mjs +264 -0
  154. sopa_companion-0.7.0/frontend/src/tiled-loader.mjs +274 -0
  155. sopa_companion-0.7.0/frontend/src/tiled-view.mjs +131 -0
  156. sopa_companion-0.7.0/frontend/src/timeline.js +568 -0
  157. sopa_companion-0.7.0/frontend/src/transcripts.js +126 -0
  158. sopa_companion-0.7.0/frontend/src/umap.js +575 -0
  159. sopa_companion-0.7.0/frontend/src/vectors-decode.mjs +67 -0
  160. sopa_companion-0.7.0/frontend/src/volume-sanity.mjs +43 -0
  161. sopa_companion-0.7.0/frontend/src/volume.js +219 -0
  162. sopa_companion-0.7.0/frontend/src/xenium-helpers.mjs +13 -0
  163. sopa_companion-0.7.0/frontend/src/xenium-masks.js +61 -0
  164. sopa_companion-0.7.0/frontend/src/zarr-save-state.mjs +70 -0
  165. sopa_companion-0.7.0/frontend/src/zarr-save.js +205 -0
  166. sopa_companion-0.7.0/frontend/styles/app.css +341 -0
  167. sopa_companion-0.7.0/frontend/styles/tokens.css +2 -0
  168. sopa_companion-0.7.0/locate.py +252 -0
  169. sopa_companion-0.7.0/names.py +99 -0
  170. sopa_companion-0.7.0/portable.py +705 -0
  171. sopa_companion-0.7.0/private.py +75 -0
  172. sopa_companion-0.7.0/pyproject.toml +69 -0
  173. sopa_companion-0.7.0/server/__init__.py +5 -0
  174. sopa_companion-0.7.0/server/api_serve.py +387 -0
  175. sopa_companion-0.7.0/server/app.py +2001 -0
  176. sopa_companion-0.7.0/server/presence.py +235 -0
  177. sopa_companion-0.7.0/server/runtime_file.py +300 -0
  178. sopa_companion-0.7.0/server/security.py +278 -0
  179. sopa_companion-0.7.0/setup.cfg +4 -0
  180. sopa_companion-0.7.0/sopa_companion.egg-info/PKG-INFO +564 -0
  181. sopa_companion-0.7.0/sopa_companion.egg-info/SOURCES.txt +475 -0
  182. sopa_companion-0.7.0/sopa_companion.egg-info/dependency_links.txt +1 -0
  183. sopa_companion-0.7.0/sopa_companion.egg-info/entry_points.txt +2 -0
  184. sopa_companion-0.7.0/sopa_companion.egg-info/requires.txt +48 -0
  185. sopa_companion-0.7.0/sopa_companion.egg-info/top_level.txt +1 -0
  186. sopa_companion-0.7.0/tests/test_analysis.py +2985 -0
  187. sopa_companion-0.7.0/tests/test_analysis_counts.py +1947 -0
  188. sopa_companion-0.7.0/tests/test_api_runs.py +426 -0
  189. sopa_companion-0.7.0/tests/test_api_session.py +1131 -0
  190. sopa_companion-0.7.0/tests/test_browser.py +558 -0
  191. sopa_companion-0.7.0/tests/test_cellpose_settings.py +232 -0
  192. sopa_companion-0.7.0/tests/test_children.py +404 -0
  193. sopa_companion-0.7.0/tests/test_ci.py +371 -0
  194. sopa_companion-0.7.0/tests/test_cli_command.py +168 -0
  195. sopa_companion-0.7.0/tests/test_code_words.py +36 -0
  196. sopa_companion-0.7.0/tests/test_compare.py +1841 -0
  197. sopa_companion-0.7.0/tests/test_compare_engine_fixes.py +272 -0
  198. sopa_companion-0.7.0/tests/test_config.py +528 -0
  199. sopa_companion-0.7.0/tests/test_config_docs.py +307 -0
  200. sopa_companion-0.7.0/tests/test_config_native.py +454 -0
  201. sopa_companion-0.7.0/tests/test_config_portable.py +290 -0
  202. sopa_companion-0.7.0/tests/test_counts_file.py +468 -0
  203. sopa_companion-0.7.0/tests/test_counts_spool.py +373 -0
  204. sopa_companion-0.7.0/tests/test_crashlog.py +745 -0
  205. sopa_companion-0.7.0/tests/test_deeper_api.py +266 -0
  206. sopa_companion-0.7.0/tests/test_deeper_integration.py +156 -0
  207. sopa_companion-0.7.0/tests/test_deeper_manager.py +746 -0
  208. sopa_companion-0.7.0/tests/test_deeper_scheduler.py +664 -0
  209. sopa_companion-0.7.0/tests/test_deeper_where.py +1778 -0
  210. sopa_companion-0.7.0/tests/test_desktop.py +1081 -0
  211. sopa_companion-0.7.0/tests/test_dirs.py +116 -0
  212. sopa_companion-0.7.0/tests/test_engine.py +813 -0
  213. sopa_companion-0.7.0/tests/test_fake_proseg.py +897 -0
  214. sopa_companion-0.7.0/tests/test_held.py +426 -0
  215. sopa_companion-0.7.0/tests/test_helper_alpha.py +937 -0
  216. sopa_companion-0.7.0/tests/test_helper_staged.py +344 -0
  217. sopa_companion-0.7.0/tests/test_image_view.py +47 -0
  218. sopa_companion-0.7.0/tests/test_instanseg_dormant.py +156 -0
  219. sopa_companion-0.7.0/tests/test_leftovers.py +194 -0
  220. sopa_companion-0.7.0/tests/test_locate.py +358 -0
  221. sopa_companion-0.7.0/tests/test_lock_compat.py +258 -0
  222. sopa_companion-0.7.0/tests/test_names.py +62 -0
  223. sopa_companion-0.7.0/tests/test_older_runs.py +424 -0
  224. sopa_companion-0.7.0/tests/test_one_state_folder.py +384 -0
  225. sopa_companion-0.7.0/tests/test_packaging.py +433 -0
  226. sopa_companion-0.7.0/tests/test_patch_folders.py +682 -0
  227. sopa_companion-0.7.0/tests/test_portable.py +390 -0
  228. sopa_companion-0.7.0/tests/test_presence.py +558 -0
  229. sopa_companion-0.7.0/tests/test_private.py +77 -0
  230. sopa_companion-0.7.0/tests/test_proseg_live_package.py +268 -0
  231. sopa_companion-0.7.0/tests/test_proseg_options.py +199 -0
  232. sopa_companion-0.7.0/tests/test_qc_api.py +2344 -0
  233. sopa_companion-0.7.0/tests/test_qc_areas.py +565 -0
  234. sopa_companion-0.7.0/tests/test_qc_calibration.py +89 -0
  235. sopa_companion-0.7.0/tests/test_qc_models.py +2257 -0
  236. sopa_companion-0.7.0/tests/test_qc_pool.py +2950 -0
  237. sopa_companion-0.7.0/tests/test_qc_pool_tiled.py +921 -0
  238. sopa_companion-0.7.0/tests/test_qc_probe.py +268 -0
  239. sopa_companion-0.7.0/tests/test_qc_readout.py +384 -0
  240. sopa_companion-0.7.0/tests/test_qc_rule.py +766 -0
  241. sopa_companion-0.7.0/tests/test_qc_rules.py +1082 -0
  242. sopa_companion-0.7.0/tests/test_qc_scoring.py +507 -0
  243. sopa_companion-0.7.0/tests/test_qc_test.py +1147 -0
  244. sopa_companion-0.7.0/tests/test_qc_test_engine.py +2563 -0
  245. sopa_companion-0.7.0/tests/test_qc_test_settings.py +143 -0
  246. sopa_companion-0.7.0/tests/test_qc_trainer.py +1215 -0
  247. sopa_companion-0.7.0/tests/test_qc_trainer_smoke.py +131 -0
  248. sopa_companion-0.7.0/tests/test_qc_trials.py +892 -0
  249. sopa_companion-0.7.0/tests/test_robustness.py +756 -0
  250. sopa_companion-0.7.0/tests/test_runlog.py +680 -0
  251. sopa_companion-0.7.0/tests/test_runs_api_mode.py +95 -0
  252. sopa_companion-0.7.0/tests/test_runs_counts.py +660 -0
  253. sopa_companion-0.7.0/tests/test_runs_inputs.py +157 -0
  254. sopa_companion-0.7.0/tests/test_runs_save.py +762 -0
  255. sopa_companion-0.7.0/tests/test_samples_alpha.py +672 -0
  256. sopa_companion-0.7.0/tests/test_samples_boundaries.py +107 -0
  257. sopa_companion-0.7.0/tests/test_security.py +374 -0
  258. sopa_companion-0.7.0/tests/test_server.py +2009 -0
  259. sopa_companion-0.7.0/tests/test_session_events.py +208 -0
  260. sopa_companion-0.7.0/tests/test_stain.py +769 -0
  261. sopa_companion-0.7.0/tests/test_stain_cellpose.py +76 -0
  262. sopa_companion-0.7.0/tests/test_stain_covered.py +20 -0
  263. sopa_companion-0.7.0/tests/test_stain_helper.py +301 -0
  264. sopa_companion-0.7.0/tests/test_stain_instanseg.py +332 -0
  265. sopa_companion-0.7.0/tests/test_stain_instanseg_smoke.py +84 -0
  266. sopa_companion-0.7.0/tests/test_stain_intensity.py +129 -0
  267. sopa_companion-0.7.0/tests/test_stain_levels.py +105 -0
  268. sopa_companion-0.7.0/tests/test_stain_models.py +258 -0
  269. sopa_companion-0.7.0/tests/test_stain_patches.py +951 -0
  270. sopa_companion-0.7.0/tests/test_stain_proceed.py +33 -0
  271. sopa_companion-0.7.0/tests/test_stain_ranges.py +198 -0
  272. sopa_companion-0.7.0/tests/test_stain_tissue_exclusions.py +470 -0
  273. sopa_companion-0.7.0/tests/test_stain_worker.py +160 -0
  274. sopa_companion-0.7.0/tests/test_stain_zarr.py +244 -0
  275. sopa_companion-0.7.0/tests/test_state_migration.py +416 -0
  276. sopa_companion-0.7.0/tests/test_stitch.py +67 -0
  277. sopa_companion-0.7.0/tests/test_telemetry.py +65 -0
  278. sopa_companion-0.7.0/tests/test_tests_portable.py +132 -0
  279. sopa_companion-0.7.0/tests/test_tissue.py +78 -0
  280. sopa_companion-0.7.0/tests/test_vectors.py +322 -0
  281. sopa_companion-0.7.0/tests/test_worker_backend.py +294 -0
  282. sopa_companion-0.7.0/tests/test_worker_compare.py +964 -0
  283. sopa_companion-0.7.0/tests/test_worker_cpu.py +614 -0
  284. sopa_companion-0.7.0/tests/test_worker_deeper.py +1704 -0
  285. sopa_companion-0.7.0/tests/test_zarr.py +1294 -0
  286. sopa_companion-0.7.0/zarr_bridge/__init__.py +1 -0
  287. sopa_companion-0.7.0/zarr_bridge/devices.py +110 -0
  288. sopa_companion-0.7.0/zarr_bridge/helper.py +2329 -0
  289. sopa_companion-0.7.0/zarr_bridge/stain.py +752 -0
  290. sopa_companion-0.7.0/zarr_bridge/stain_gui.py +41 -0
  291. sopa_companion-0.7.0/zarr_bridge/stain_instanseg.py +246 -0
  292. sopa_companion-0.7.0/zarr_bridge/stain_patches.py +547 -0
  293. sopa_companion-0.7.0/zarr_bridge/stitch.py +143 -0
  294. sopa_companion-0.7.0/zarr_bridge/tissue.py +94 -0
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Jacky Tam
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,564 @@
1
+ Metadata-Version: 2.4
2
+ Name: sopa-companion
3
+ Version: 0.7.0
4
+ Summary: SoPA companion: stain segmentation and live proseg for SpatialData, from a notebook or the desktop
5
+ License-Expression: BSD-3-Clause
6
+ Project-URL: Homepage, https://github.com/jackytamkc/sopa-companion
7
+ Project-URL: Issues, https://github.com/jackytamkc/sopa-companion/issues
8
+ Project-URL: Archive, https://doi.org/10.5281/zenodo.24116670
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Requires-Python: >=3.12
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: sopa>=2.2.10
21
+ Requires-Dist: proseg-live==3.2.0.*,>=3.2.0.1
22
+ Requires-Dist: platformdirs>=4
23
+ Requires-Dist: fastapi>=0.143.2
24
+ Requires-Dist: uvicorn[standard]>=0.54.0
25
+ Requires-Dist: orjson>=3.13.0
26
+ Requires-Dist: zstandard>=0.25.0
27
+ Requires-Dist: httpx>=0.28.1
28
+ Requires-Dist: psutil>=7.2.2
29
+ Requires-Dist: numpy>=2.4.6
30
+ Requires-Dist: pyarrow>=26.0.0
31
+ Requires-Dist: zarr>=3.4.1
32
+ Requires-Dist: tifffile>=2026.9.20
33
+ Requires-Dist: imagecodecs>=2026.10.10
34
+ Requires-Dist: pillow>=12.3.0
35
+ Provides-Extra: api
36
+ Requires-Dist: fastapi>=0.143.2; extra == "api"
37
+ Requires-Dist: uvicorn[standard]>=0.54.0; extra == "api"
38
+ Requires-Dist: orjson>=3.13.0; extra == "api"
39
+ Requires-Dist: zstandard>=0.25.0; extra == "api"
40
+ Provides-Extra: sopa
41
+ Requires-Dist: sopa>=2.2.10; extra == "sopa"
42
+ Requires-Dist: spatialdata>=0.8.0; extra == "sopa"
43
+ Provides-Extra: stain
44
+ Requires-Dist: cellpose>=4; extra == "stain"
45
+ Requires-Dist: torch<2.15,>=2.14; (sys_platform == "darwin" and platform_machine == "arm64" and "23." in platform_release) and extra == "stain"
46
+ Provides-Extra: qc
47
+ Requires-Dist: scvi-tools>=1.5; extra == "qc"
48
+ Requires-Dist: scviva-tools>=0.1.7; extra == "qc"
49
+ Requires-Dist: torch>=2.1.1; extra == "qc"
50
+ Requires-Dist: torch<2.15,>=2.14; (sys_platform == "darwin" and platform_machine == "arm64" and "23." in platform_release) and extra == "qc"
51
+ Provides-Extra: all
52
+ Requires-Dist: sopa-companion[qc,sopa,stain]>=0.1; extra == "all"
53
+ Provides-Extra: test
54
+ Requires-Dist: pytest>=8; extra == "test"
55
+ Requires-Dist: packaging>=24; extra == "test"
56
+ Requires-Dist: jupyter_client>=8; extra == "test"
57
+ Requires-Dist: ipykernel>=6.31; extra == "test"
58
+ Dynamic: license-file
59
+
60
+ # SoPA companion
61
+
62
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24116670.svg)](https://doi.org/10.5281/zenodo.24116670)
63
+
64
+ A companion to [sopa](https://github.com/prism-oncology/sopa) for your Jupyter notebook: `sopa_companion.launch(sdata)`
65
+ opens a [SpatialData](https://spatialdata.scverse.org) sample written by sopa in your browser, and what you keep is
66
+ added back to that same object, as sopa's own functions add it. Currently only the sopa API is supported (the app
67
+ opens from a notebook, on the object you pass), and two tools are supported:
68
+
69
+ - **Stain segmentation**: find cells in the sample's images with Cellpose, tile by tile over a rectangle, a lasso or
70
+ the whole sample; remove cells by area, size or stain brightness; make training patches for the Cellpose GUI; add the
71
+ result to your SpatialData as a shapes layer, the way sopa does.
72
+ - **Proseg Live**: watch [proseg](https://github.com/dcjones/proseg) segment cells from the transcripts, one sampler
73
+ iteration at a time. Pause, step, scrub back to any earlier iteration, change proseg's settings while it runs, then
74
+ *Finish & save* proseg's own results from exactly the state on screen and add them to your SpatialData (shapes plus
75
+ their table, with sopa's own functions).
76
+
77
+ Around Proseg Live: live clusters and a UMAP of every iteration (on the CPU, or on an NVIDIA GPU with RAPIDS), a
78
+ **mixing check** that estimates how much of each cell's RNA looks like a neighbour's (a ResolVI model learned once per
79
+ sample on an NVIDIA GPU, or on a Mac's own GPU), **Go deeper** for one cell, a quick **test of a setting** on a small
80
+ square, other segmentations of the sample drawn on the tissue, and **Compare**, which reads several segmentations side
81
+ by side with the same model, each on its own UMAP and clusters (lined up with the run's) or all on one shared map.
82
+
83
+ How it is built: [docs/ARCHITECTURE.md](https://github.com/jackytamkc/sopa-companion/blob/main/docs/ARCHITECTURE.md). Working on the app itself:
84
+ [docs/DEVELOPING.md](https://github.com/jackytamkc/sopa-companion/blob/main/docs/DEVELOPING.md).
85
+
86
+ ## Quick start
87
+
88
+ After [Install](#install), in a notebook of that environment:
89
+
90
+ ```python
91
+ import sopa
92
+ import sopa_companion
93
+
94
+ sdata = sopa.io.toy_dataset(length=1000) # or your own sample: sdata = spatialdata.read_zarr("sample.zarr")
95
+ sdata.write("toy.zarr") # the app works on a SpatialData saved to a local .zarr
96
+ app = sopa_companion.launch(sdata) # opens the app in your browser; the notebook stays free
97
+ ```
98
+
99
+ The app opens in a new tab of your browser. On a remote computer (SSH, VS Code's Remote-SSH included) it prints a link
100
+ instead, with the `ssh -N -L` command for a tunnel; VS Code forwards the port by itself (keep the same port number on
101
+ your computer). **Close** in the app, or `app.close()`, ends the session. The rest is under
102
+ [Use it from a notebook](#use-it-from-a-notebook).
103
+
104
+ ## Requirements
105
+
106
+ - **Linux**, 64-bit (x86-64 or ARM64), with glibc 2.28 or newer (Ubuntu 20.04, Debian 10, RHEL 8 or later);
107
+ **macOS** 11 or newer on Apple silicon; or **Windows** 10 or 11, 64-bit (x64). macOS and Windows are new in this alpha
108
+ and are tested on GitHub's machines, which have no GPU. WSL2 on Windows takes the Linux install.
109
+ - **Python 3.12 or 3.13**, in the environment where you installed sopa
110
+ ([sopa's guide](https://prism-oncology.github.io/sopa/getting_started/)), or a new one: the install brings sopa.
111
+ - **A modern web browser with WebGL2** (Firefox 133 or newer, Chrome, Edge), on the computer you look at.
112
+ - On Linux, `setpriv` from util-linux, which every common Linux has: the app's helpers end with its session (macOS and
113
+ Windows end them in their own ways).
114
+ - **The mixing check requires a GPU: an NVIDIA GPU, or on a Mac with Apple silicon its own GPU.** It learns each sample
115
+ once on GPU 0 (PyTorch with CUDA, driver 580 or newer for the CUDA 13 packages; on Windows with PyTorch's CUDA build,
116
+ not tested yet), or on a Mac without one on Apple's GPU, where it passes a short test of PyTorch's operations first
117
+ (PyTorch 2.15 needs macOS 15 or later there; on macOS 14 the install brings PyTorch 2.14, which passes it). On an M2
118
+ Ultra it learns about 3.5 times as slowly as on a recent NVIDIA workstation GPU and gives equivalent results (not the
119
+ same cells' numbers: another random stream, as another seed gives), and a model learned there is kept apart from an
120
+ NVIDIA GPU's. The free memory a fit takes grows with the gene panel, hardly with the number of cells (on a Mac the
121
+ cells' counts too, in its own memory):
122
+
123
+ | Gene panel | Free GPU memory needed |
124
+ |---|---|
125
+ | 300 genes | about 1.4 GB |
126
+ | 1,000 genes | about 2.0 GB |
127
+ | 5,000 genes (Xenium Prime 5K) | about 4.8 GB |
128
+ | 10,000 genes | about 8.4 GB |
129
+
130
+ For larger panels, use a GPU with more memory. Its scores, Go deeper and Compare run on the GPU with RAPIDS, else on
131
+ the CPU (on a Mac, the CPU).
132
+ - **Everything else runs without a GPU.** Clusters and the UMAP run on the CPU with what sopa installs (about twice a
133
+ second for a region of a few thousand cells, every 3-5 s for a 40,000-cell sample), and faster on the GPU with RAPIDS
134
+ (Linux only). Stain segmentation uses CUDA, or Apple's GPU on a Mac, when it can and falls back to the CPU (Apple's
135
+ GPU with PyTorch 2.15 needs macOS 15 or later; on macOS 14 the install brings PyTorch 2.14).
136
+
137
+ ## Install
138
+
139
+ What every computer needs:
140
+
141
+ - **conda**, if you have none yet: [Miniforge](https://conda-forge.org/download/) (conda with conda-forge's packages).
142
+ Any environment with Python 3.12 or 3.13 does too, sopa's own included.
143
+
144
+ Then follow the steps for your computer. Each section is complete. To update later, in the same environment:
145
+ `pip install --upgrade "sopa-companion[all]"`.
146
+
147
+ ### macOS (Apple silicon: M1 or later)
148
+
149
+ `uname -m` in Terminal says `arm64` on Apple silicon. On an Intel Mac it says `x86_64`: read
150
+ [Another computer](#another-computer) before step 3.
151
+
152
+ 1. Miniforge, if you have no conda (in Terminal; answer yes when it offers to initialise conda, then open a new
153
+ Terminal window):
154
+
155
+ ```bash
156
+ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"
157
+ bash Miniforge3-MacOSX-arm64.sh
158
+ ```
159
+
160
+ 2. An environment with Python and JupyterLab:
161
+
162
+ ```bash
163
+ conda create --name sopa -c conda-forge python=3.12 jupyterlab
164
+ conda activate sopa
165
+ ```
166
+
167
+ 3. The app, from PyPI (with sopa, Cellpose, PyTorch and the rest; a few minutes):
168
+
169
+ ```bash
170
+ pip install "sopa-companion[all]"
171
+ ```
172
+
173
+ 4. Check it: `sopa-companion --version` says the app's version and where its proseg-live is.
174
+ 5. Try it: `jupyter lab`, open a new notebook, and run the [Quick start](#quick-start).
175
+
176
+ On a Mac, Cellpose and the mixing check use Apple's GPU where it passes a short test of PyTorch's operations; where it
177
+ does not, Cellpose runs on the CPU, the mixing check's panel says why, and the run's Log has the details. PyTorch 2.15
178
+ needs macOS 15 (Sequoia) or later for Apple's GPU (on macOS 14 every linear layer would stop the process), so step 3
179
+ installs PyTorch 2.14 on macOS 14, in place of a newer one already in the environment, and the newest PyTorch on
180
+ macOS 15 or later. On an M2 Ultra, Cellpose ran about 8 times as fast on Apple's GPU as on the CPU.
181
+
182
+ ### Windows (64-bit)
183
+
184
+ 1. Miniforge, if you have no conda: run the installer
185
+ [Miniforge3-Windows-x86_64.exe](https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe).
186
+ Then open **Miniforge Prompt** from the Start menu, run `conda init powershell`, and close it. The steps below run
187
+ in **PowerShell**; if it says running scripts is disabled, run
188
+ `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` there once and open a new PowerShell window.
189
+ 2. An environment with Python and JupyterLab:
190
+
191
+ ```powershell
192
+ conda create --name sopa -c conda-forge python=3.12 jupyterlab
193
+ conda activate sopa
194
+ ```
195
+
196
+ 3. The app, from PyPI (a few minutes):
197
+
198
+ ```powershell
199
+ pip install "sopa-companion[all]"
200
+ ```
201
+
202
+ 4. Check it: `sopa-companion --version`.
203
+ 5. Try it: `jupyter lab`, a new notebook, the [Quick start](#quick-start). On Windows the notebook shows the app's link
204
+ to click: the app does not open a browser by itself there yet.
205
+
206
+ On Windows, keep samples in folders with short paths (Windows refuses paths longer than 260 characters unless long paths
207
+ are switched on). Exporting training patches is not available on Windows yet. For the mixing check on an NVIDIA GPU,
208
+ PyTorch's CUDA build replaces the CPU one pip installs on Windows (`pip install torch torchvision --index-url
209
+ https://download.pytorch.org/whl/cu130`); the mixing check on a Windows GPU is not tested yet.
210
+
211
+ ### Linux (64-bit: x86-64 or ARM64)
212
+
213
+ 1. Miniforge, if you have no conda (open a new terminal after it):
214
+
215
+ ```bash
216
+ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
217
+ bash Miniforge3-$(uname)-$(uname -m).sh
218
+ ```
219
+
220
+ 2. An environment with Python and JupyterLab (or your sopa environment):
221
+
222
+ ```bash
223
+ conda create --name sopa -c conda-forge python=3.12 jupyterlab
224
+ conda activate sopa
225
+ ```
226
+
227
+ 3. The app, from PyPI:
228
+
229
+ ```bash
230
+ pip install "sopa-companion[all]"
231
+ ```
232
+
233
+ 4. Check it: `sopa-companion --version`.
234
+ 5. Try it: `jupyter lab` (or your own Jupyter, VS Code or PyCharm with this environment's Python), then the
235
+ [Quick start](#quick-start).
236
+
237
+ ### What the install line does
238
+
239
+ It installs two packages from [PyPI](https://pypi.org/project/sopa-companion/): the app, and `proseg-live` (proseg
240
+ 3.2.0 with live mode and proseg's own count of each cell, GPL v3) built for this computer, with everything they need:
241
+ sopa and spatialdata, Cellpose, PyTorch, and scvi-tools with scviva-tools for the mixing check. The same files, with
242
+ their checksums, are on each [release](https://github.com/jackytamkc/sopa-companion/releases) here.
243
+
244
+ ### Another computer
245
+
246
+ PyPI has proseg-live wheels for Linux x86-64 and ARM64 with glibc 2.28 or newer, macOS 11 or newer on Apple silicon,
247
+ and Windows x64. Elsewhere (an Intel Mac, say) pip builds proseg-live from its source, which needs Rust 1.88 or newer
248
+ ([rustup.rs](https://rustup.rs)) and a C compiler (on a Mac, `xcode-select --install`): install those first, then
249
+ step 3's line is the same.
250
+
251
+ ### Optional extras
252
+
253
+ **Optional: Clusters & UMAP on the GPU.** They need nothing more on the CPU. On Linux with an NVIDIA GPU they run
254
+ faster with RAPIDS, which for now goes into an environment of its own:
255
+
256
+ ```bash
257
+ conda create --name rapids python=3.12
258
+ conda activate rapids
259
+ pip install 'rapids-singlecell-cu13[rapids]' --extra-index-url=https://pypi.nvidia.com
260
+ python -c 'import sys; print(sys.executable)' # this environment's Python, for your settings file
261
+ conda activate sopa
262
+ ```
263
+
264
+ Then name that Python in your settings file. Your own settings file is `~/.config/sopa-companion/config.toml` (under
265
+ `$XDG_CONFIG_HOME` when that is set; on macOS `~/Library/Application Support/sopa-companion/config.toml`, on Windows
266
+ `%LOCALAPPDATA%\sopa-companion\config.toml`); put there only the lines you change ([Settings](#settings)):
267
+
268
+ ```toml
269
+ [analysis]
270
+ python = "~/miniforge3/envs/rapids/bin/python"
271
+ ```
272
+
273
+ With an older driver or GPU, use `rapids-singlecell-cu12[rapids]` together with PyTorch's CUDA 12 build (`pip
274
+ install torch --index-url https://download.pytorch.org/whl/cu126`) in the sopa environment.
275
+
276
+ **Optional: Cellpose's own window**, to train a model on exported patches where you have a desktop:
277
+ `pip install 'cellpose[gui]'` (sopa installs Cellpose without it).
278
+
279
+ ## Use it from a notebook
280
+
281
+ ```python
282
+ import sopa_companion
283
+ app = sopa_companion.launch(sdata) # sdata: a SpatialData written to a local .zarr
284
+ ```
285
+
286
+ - **What it does.** `launch` starts a private engine for this kernel alone, on the object's zarr (elements only in
287
+ memory are left out, and a warning names them), and opens the app where `[desktop] browser` says (a new tab of your
288
+ default browser, or with `"chrome"` a window of its own), or prints a link when there is no display or you are on
289
+ SSH. `app.open()` opens it again when its tab or window went away (a crash, a laptop closed); the session goes on
290
+ meanwhile. In a notebook it returns at once and you keep working; a script waits until the app closes. The sample
291
+ is read and saved with the kernel's own Python (its sopa and spatialdata); on Linux the app needs `setpriv`, and
292
+ everywhere a web browser (without one it prints the link). On Windows the notebook shows the link to open for now,
293
+ and the app's own Chrome window (`"chrome"`) is Linux's alone.
294
+ - **Its options.** `tool="proseg"` or `"stain"` opens that tool; `points_key` chooses the transcripts among several
295
+ points elements; `open` is `"auto"`, `"window"`, `"link"` or `"none"`; `gpu` is one GPU number or `{"analysis": …,
296
+ "stain": …, "qc": …}`; `mixing_check=True` switches the mixing check on; `timeout` limits the start (120 s).
297
+ - **Results go into your object.** *Add to your SpatialData* adds the result to the object you passed, under new
298
+ names, between notebook cells (never while one runs), as sopa's own functions add it.
299
+ With sopa's auto-save on it is written to the zarr too. `app.added` lists what was added.
300
+ - **The link** (`SoPA companion: http://127.0.0.1:<port>/?code=…`, printed when the app opens no window, and then in
301
+ `app.url`; on SSH with the `ssh -N -L` command for a tunnel) signs one browser in, once, within 10 minutes. Until it
302
+ is used, anyone who can read it can use it: keep it private (a saved notebook keeps the cell's output, so clear the
303
+ outputs before sharing a notebook within those 10 minutes). Once it has been used the notebook's output is replaced
304
+ by a line saying when, so a notebook saved afterwards keeps no code; so is a link no longer needed (a newer one shown
305
+ by `app.open()`, or the browser the app opened signing in after all), which says why. A browser the app opens takes a
306
+ code of its own that lives seconds (then in `app.url`, already used), never on a command line; one that shows no app
307
+ within 20 seconds gets the link printed too. A tunnel must keep the port's number: the app answers only on its own.
308
+ - **Closing.** The app's **Close** ends the session, asking first about a run not added yet (*Add to your SpatialData
309
+ and close*, *Discard and close*, *Keep working*). `app.close()` closes it from the notebook and discards a run not
310
+ added; `app.close(pending="add")` adds it first. A tab or window closed (its page says goodbye) without an answer, or
311
+ a kernel that stops, discards it too. A tab that crashed or lost its connection pauses its run instead, and the
312
+ session waits for `app.open()` or `app.close()`.
313
+ - **Its folders.** The session's private folder (`session.toml`, logs, the Chrome window's own profile) is
314
+ `$XDG_RUNTIME_DIR/sopa-companion/<id>/`, else `~/.cache/sopa-companion/sessions/<id>/` (on macOS
315
+ `~/Library/Caches/sopa-companion/sessions/<id>/`, on Windows `%LOCALAPPDATA%\sopa-companion\Cache\sessions\<id>\`);
316
+ its runs and caches go into
317
+ `<scratch_dir>/sopa-companion-<id>/`. Both are removed when the session ends, and a session left by a crash is removed
318
+ at the next `launch`. `model_cache=` keeps the mixing check's learned models for later sessions. Training patches
319
+ are exported into a folder you choose at each export, always outside the session's folders, so they stay; with
320
+ `patches_dir=` that choice starts there (a folder per sample and resolution in it). The Clusters & UMAP settings
321
+ that new runs start with last for the session only.
322
+ - **From sopa.** A sopa with `packaging/sopa-fork/sopa.patch` (sopa's optional `companion` extra, proposed) opens it
323
+ as `sopa.companionapp(sdata)` once the companion is installed.
324
+
325
+ ### Settings
326
+
327
+ `launch` reads the app's own settings (an installed copy's own `config.example.toml`), then your own
328
+ `~/.config/sopa-companion/config.toml` (under `$XDG_CONFIG_HOME` when that is set; macOS and Windows: as
329
+ [Install](#install) says). An installed copy's own files are
330
+ inside the Python environment, so your own file is the place for your settings. `launch` takes these from them, and
331
+ its own arguments win:
332
+
333
+ | Setting | What |
334
+ |---|---|
335
+ | `[api] engine_python` | the engine's Python; empty: the kernel's own, which then needs the engine's packages (the wheel brings them) |
336
+ | `[api] scratch_dir` | where each session's runs and caches go, removed at close; empty: the system's temporary folder |
337
+ | `[api] model_cache` | a folder that keeps the mixing check's learned models between sessions; empty: they go with the session |
338
+ | `[desktop] browser` | where the app opens: `"default"`, your default browser; `"chrome"`, a window of its own; or a browser's `.desktop` file |
339
+ | `[desktop] chrome_flags` | flags for the session's Chrome window (on a remote desktop, `"--use-angle=vulkan"` and `"--ignore-gpu-blocklist"` let it use the GPU) |
340
+ | `[proseg] binary` | the proseg-live program: `auto` (the default) finds the one installed with the app; or a path |
341
+ | `[analysis] python`, `gpu` | Clusters & UMAP's Python: `auto` (or empty), the kernel's own when it has scipy, scikit-learn, igraph, umap-learn and numba (sopa brings them; on the CPU); `off`; or another environment's Python (with RAPIDS: on the GPU) |
342
+ | `[stain] python`, `gpu` | Cellpose's Python: `auto` (or empty), the kernel's own when it has Cellpose; `off`; or another environment's. It also runs the Cellpose GUI, which needs `cellpose[gui]` there |
343
+ | `[qc] python`, `gpu` | the mixing check's Python: `auto` (or empty), the kernel's own when it has scvi-tools, scviva-tools and torch; `off`; or another environment's |
344
+
345
+ Other settings in your own file do not reach the session's engine, which reads the app's own files and what `launch`
346
+ hands it. GPU numbers count the GPUs the kernel sees (its `CUDA_VISIBLE_DEVICES`, else nvidia-smi's numbering); the
347
+ mixing check learns on GPU 0 only (a Mac's own GPU where it has no NVIDIA one).
348
+
349
+ ## Use it
350
+
351
+ ### The first screen
352
+
353
+ The app opens on your SpatialData: choose **Stain segmentation** or **Proseg Live**. The header names the sample on
354
+ every screen; **New run** stays in the tool, and a click on the app's name goes back to the two cards. Both leave the
355
+ open run first, asking about it when it is not added yet ([One run at a time](#one-run-at-a-time)). While the app
356
+ prepares a large SpatialData, the first screen shows how far it is, and a card pressed meanwhile opens by itself when
357
+ the sample is ready.
358
+
359
+ When the sample opens, the app says in one line each what it found that matters (details in an ⓘ): transcripts that
360
+ seem to be in pixels rather than micrometres, several transcript elements of which one is used, images left out, z
361
+ given as plane numbers, element names the app cannot use. A sample with images but no transcripts opens for Stain
362
+ segmentation only, and one with transcripts but no image it can show for Proseg Live only.
363
+
364
+ ### Stain segmentation
365
+
366
+ Choose the image and its nucleus channel; a cell body or membrane channel is optional, and Cellpose's model (`cpsam` by
367
+ default, or a model you trained under **Your models**). A built-in model not on the computer yet is downloaded by its
368
+ first run (`cpsam`: about 1.15 GB), once, into Cellpose's own model folder (`~/.cellpose/models`). **Resolution** is one of the image's own pyramid levels by its
369
+ SpatialData name: `scale0` is the image as stored, `scale1`, `scale2`, … the smaller copies the sample already holds.
370
+ **Auto** keeps the image at its own size; Cellpose's settings go by Cellpose's own names (`diameter`, in pixels of
371
+ `scale0`; `flow_threshold`; `cellprob_threshold`), each with its plain meaning in its tooltip; more Cellpose settings
372
+ fold under the method. *Tissue only* (on by default) segments only tiles that touch the tissue (the sample's
373
+ `region_of_interest`, else a tissue outline found on the image). Choose a rectangle, a lasso or the whole sample and press
374
+ **Start**: nothing runs before that. Images are segmented in tiles (`[stain] tile_pixels`, 1024 by default, overlapping
375
+ by at least `overlap_pixels`); only 2-D images are supported (extra axes of size one are fine), with the channel names
376
+ and coordinates SpatialData gives them.
377
+
378
+ Finished tiles appear as outlines over the image; the panel shows tile progress, cells and their sizes. Pause and Stop
379
+ act after the current tile; Resume continues from the finished tiles. Tiles are joined without seams: each tile keeps
380
+ the cells whose centre lies in its own part, and a cell only one tile found is never lost. **Remove cells** works on
381
+ the result without changing it: draw areas (click one on the image and press Delete to bring its cells back; Undo and
382
+ Redo go back and forth), or keep only the cells within a size range and a brightness range in a channel. **Add as
383
+ shapes** adds the result to your SpatialData (`cellpose_boundaries_1`, then the next free number; the dialog says when a
384
+ name would replace an element); the added layer then appears among Proseg Live's starting cells, and *Proceed to proseg*
385
+ opens the proseg setup on it, over the same region.
386
+
387
+ **Training patches.** From a paused or finished run, or straight from the sample (the *Training patches* section at the
388
+ top of the picker), the app proposes varied boxes with cells (8 boxes of 256 × 256 pixels by default; move, resize, drop
389
+ or add them). **Export patches** asks every time where to save: it suggests the folder this sample's patches at this
390
+ resolution went to last, else a new one named after the sample and its resolution under
391
+ `~/sopa-companion/training-patches` (`<sample>-scale0`, ...); **New folder** names one inside the folder shown. The image
392
+ crops and Cellpose masks go straight into the folder you choose, beside what is already there, under names of their own
393
+ (`<sample>-<date>-<time>-01.tif`, `…-01_seg.npy`), and never replace a file. Keep one folder per model: the Cellpose GUI
394
+ trains one model on every patch in the folder it has open, so a sample that needs a model of its own gets a folder of its
395
+ own (the dialog says when a folder already holds patches cut at another resolution or of other channels). The app's
396
+ records of each export are in the folder's hidden `.sopa-companion`. A folder in a zarr store, a hidden folder, the
397
+ app's own folders and Python environments, a notebook session's folders, `/`, your home folder itself and folders you
398
+ cannot write to are refused, in plain words. The Cellpose GUI loads the `_seg.npy` masks with Python's pickle, which
399
+ can run code: a mask someone else puts in a folder they can write to runs as you when the GUI opens it or trains on it.
400
+ Keep training folders where only you, or people you trust, can write. **Open in Cellpose GUI** opens the first crop
401
+ with its outlines where the notebook's computer has a desktop (elsewhere the panel gives the command to start it by
402
+ hand); correct them, save with Ctrl+S and train a model in the GUI. The panel notices corrected patches; a GUI-trained
403
+ model appears under **Your models** for new runs, with the resolution its patches were cut at.
404
+
405
+ ### Proseg Live
406
+
407
+ 1. **Start from**: the sample's cells and nuclei (the suggested pairing, as proseg uses Xenium's), or any one shapes
408
+ layer or cell-assignment column of the transcripts on its own (Cellpose cells, an earlier proseg result, ...). Shapes
409
+ are assigned to transcripts with sopa's point-in-polygon join.
410
+ 2. **Region**: a rectangle, a lasso, or the full sample. Regions up to 1.2 mm across run in full detail; anything larger
411
+ runs in **whole-sample mode**, where the view streams only the part on screen.
412
+ 3. Every run follows proseg's own schedule (burn-in at 2 µm voxels, sampling at 1 µm, then hill-climbing) and its
413
+ defaults; every option is under *Advanced proseg options*, and only values you change are passed.
414
+ 4. **Start segmenting** prepares the run and stops on proseg's starting point (frame 0). Press **Start** (or **Step**).
415
+ Pause (Space), Step (S) and the speed (Max, Fast, Slow) control proseg between iterations. **Live knobs**
416
+ (temperature, compactness, prior weight, diffusion, ...) apply from the next iteration and are marked on the
417
+ timeline. The timeline shows proseg's phases and log-likelihood: click or drag to look at any iteration; ←/→ step
418
+ through them, **Live** (L) follows new ones.
419
+ 5. At the end of proseg's standard run the run pauses and **Finish & save** is the main button: it writes proseg's own
420
+ results from that state into the run's `output/` folder. **Resume** samples on, open-ended, until you finish.
421
+ 6. **Add to your SpatialData** adds the result to your object: a shapes layer and its AnnData table (sopa's
422
+ `_read_proseg` and `add_parsed_table`, optionally `set_boundaries_attrs`, *Make it the default segmentation*). The
423
+ dialog's names are checked against your SpatialData's elements when it opens and says when one would be replaced.
424
+ The table's `uns["sopa_companion"]` records the run, iteration, starting cells, region and options.
425
+
426
+ **Display.** 2-D or 3-D (V); filled cells or outlines (1/2); transcripts (X) coloured by the cell or cluster they sit in;
427
+ changed voxels flashing (T); napari-style image layers (contrast, gamma, colormap, opacity, blending); proseg's own
428
+ voxel prior; hover a cell for its statistics (its count in proseg's count and what proseg sets aside as background),
429
+ click to follow it over the run.
430
+
431
+ **Clusters and UMAP.** Every run is clustered as it goes on the GPU, or on the CPU (its clusters start from the last
432
+ ones, so colours change little): proseg's own count of each cell (the iterations proseg counts as the run goes),
433
+ normalisation, PCA, kNN, Leiden, top genes, and a UMAP warm-started from the previous one so its dots fly to their new
434
+ places. A region with too few cells says so
435
+ instead. **Advanced settings**, under the UMAP pane's title: cluster resolution, neighbours per cell, dot spacing, the
436
+ fewest transcripts a cell needs and the genes used (how many of the panel's most variable genes; a smaller panel uses
437
+ all of its genes). **Apply** groups the run's cells again: the clusters shown stay until the new ones are ready, then
438
+ the dots fly to their new places. **Reset** goes back to the defaults, and new runs start with the settings last
439
+ applied. Compare keeps its own fixed recipe. On the CPU, genes used stops at 5,000 (10,000 on the GPU). Where they
440
+ cannot run (`[analysis] python` off, or a Python that lacks what they need) the pane stays shut and Layers > Cells says
441
+ what is missing, or where to set it.
442
+
443
+ **Mixing check** (off until you switch it on). For every cell, a model's estimate of how much of its RNA (proseg's own
444
+ count of it, averaged over proseg's random background draw) looks like it came from neighbouring cells: "18 in 100 cells
445
+ look mixed", the change since the start like for like (the cells proseg started with, their RNA kept as proseg keeps it
446
+ now, each cell against itself at the same depth), and a verdict only when the change is larger than repeat runs give. A
447
+ run started from nuclei, with their cells or without (Xenium's cells and nuclei, say), has no start to compare with:
448
+ proseg's first iteration holds only the nuclei. It is an estimate, not a count of boundary errors, and it cannot tell
449
+ RNA apart between cells of the same kind. The first time it is on for a sample it learns that sample once (a ResolVI
450
+ model on GPU 0, or a Mac's own GPU, a few minutes); later runs of the sample start at once. Learning starts once the
451
+ GPU has the free memory the sample's panel needs ([Requirements](#requirements)): until then the panel says how much it
452
+ needs and how much is free, and a GPU with less than that in all is told so at once (a Mac never waits: it learns at
453
+ once, unless it has too little memory in all). It may suggest a setting to try
454
+ (*Try it* watches the change; *New run with this setting* is the clear test).
455
+ `python -m sopa_companion.engine.qc learn <sample.zarr>...` learns samples ahead, with the app closed.
456
+
457
+ **Go deeper** (D, with a cell selected): how the model splits that cell's RNA (proseg's count of it) into its own, from
458
+ neighbours and loose RNA in the tissue, which genes, and which neighbours it seems to come from. The cells involved
459
+ stay lit while the rest greys out; **Show on the image** makes the transcripts proseg counts for the cell that likely
460
+ came from a neighbour glow pink (one just outside the outline is RNA proseg moved in), a rough guide (the model splits
461
+ RNA per gene, not per transcript). Paused, or following a cell while the run plays, the dots are proseg's exact share;
462
+ on an earlier iteration they are placed approximately, or not at all, and the tooltip says so.
463
+
464
+ **Test a setting here** (in Go deeper, or under the mixing check's row, with a cell selected) asks whether a value of
465
+ one of proseg's own settings (cell compactness, the hold to the starting cells, far drift, the starting grid,
466
+ background gaps, drift on or off, the short drift distance, crowding levels or depth layers) keeps the suspects (the
467
+ transcripts proseg counts for the cell that likely came from a neighbour: its pink dots) out of this cell and of nearby
468
+ cells with the same pattern. The "?" beside the setting plays what it does to a made-up cell, one panel per value.
469
+ Fresh runs of your region (or, when it is
470
+ over 500 µm, of a 500 µm square around the cell, cut to your region where it is narrower) go to the end of proseg's
471
+ schedule, all at once: 3 as now and 3 with your value (4 and 4 for a run started from cells only), about a minute
472
+ while your run waits at its end. A corner of the image shows one of them as now and one with your value, side by side.
473
+ The answer says whether proseg keeps the suspects in their cells, whether they are clearly fewer with your value than
474
+ their own RNA at the same spot, what it cost and where they went; then *New run with this*, *Keep my setting* or *Run
475
+ again*. It works on any run that reaches its last iteration, a whole sample too. A press before your run reaches its
476
+ last iteration waits for it, and one with the mixing check off switches it on first. Where the test was not measured,
477
+ it runs all the same and its answer says so in its tooltip. A cell that doesn't look mixed overall is tested on its
478
+ pink dots all the same. The form says why when a cell can't be tested (too few transcripts, no pink dots), or a run
479
+ (being saved, ended before its last iteration, or without proseg's own count). Every proseg
480
+ setting is global: the test shows what one value does to the area, not to one cell.
481
+
482
+ **Other masks and Compare.** *Layers > Load Other Mask* draws any other segmentation (mask) the sample holds beside the
483
+ run's cells (Xenium's, an imported one, a stain segmentation or proseg result added earlier). **Compare** reads the run's
484
+ frame and up to three of the sample's segmentations with the sample's mixing model, side by side: their UMAPs on one
485
+ shared layout, how mixed their cells look, at a common depth too, on the area all of them cover. Each column reads its
486
+ own count and says which: proseg's for the run and a saved proseg result, Xenium's for Xenium's cells, the transcripts
487
+ inside the outlines for a segmentation with no count of its own (Cellpose, a stain). Proseg sets background aside, so
488
+ its columns read less mixed for that reason too. It sets no verdict between columns.
489
+
490
+ **Log.** The Log button saves a plain-text log of the session and the open run (settings, schedule, what you did, the
491
+ numbers behind the mixing check's words, what went wrong). Nothing is saved without your click; the session's token is
492
+ never in it. When the app closed unexpectedly (the engine stopped, or its page crashed), the next start offers that
493
+ session's log once: *Save a copy…* or *Not now*.
494
+
495
+ ### One run at a time
496
+
497
+ The app holds one run (a proseg run, a stain run or a set of training patches) and keeps no runs between sessions.
498
+ Leaving it (the app's name, **New run**, *Proceed to proseg*, **Close**) asks first when it holds a result that is not
499
+ in your SpatialData yet: **Add to your SpatialData** finishes the run if it still samples (a stain run stops after its
500
+ current tile), adds its cells under new names and then removes the run; **Discard** removes it; **Stay** keeps it open.
501
+ A run with nothing to lose (not started, or added already) goes without a question.
502
+
503
+ ### What you are seeing
504
+
505
+ Proseg models cells as sets of voxels (2 µm during burn-in, then 1 µm; 4 layers in z by default) and samples boundary
506
+ changes with Metropolis–Hastings. "Voxels changed" counts 2-D columns whose label changed; the log-likelihood is
507
+ proseg's expression likelihood (not the full posterior). Every frame on screen is proseg's own state at that iteration, read
508
+ from the snapshots it writes; nothing is re-simulated in the page. The outlines are drawn from proseg's voxels, for
509
+ drawing and places only: every number about a cell's RNA (its readout, the clusters and the UMAP, the mixing check, Go
510
+ deeper, the test of a setting, Compare's run column) is proseg's own count of the cell, gene by gene, averaged over
511
+ proseg's random background draw, never a count of the transcripts inside its outline. Proseg counts the iterations
512
+ the app asks for as the run goes (and its first iteration, pauses and the end). On an iteration it did not count, the
513
+ clusters and the check are the newest counted iteration's before it, and say which; a cell's readout there shows that
514
+ iteration's own draw of proseg's count, its tooltip saying so.
515
+
516
+ ## Guarantees and limits
517
+
518
+ - **What you save is what you see.** Pause and *Finish & save* wait for proseg's own acknowledgement, written only once
519
+ every queued snapshot is on disk, so the confirmed iteration is exactly the saved state.
520
+ - **Bounded history.** A snapshot for every iteration up to 2,000, then every 5th to 10,000, every 25th to 50,000 and
521
+ every 100th after; the state at any pause, finish or end is always kept. Past iteration 2,000 the iterations the app
522
+ asks proseg to count are kept too, at most one between two kept snapshots, so at most as many again. A run pauses
523
+ itself when the data disk has less than 15 GB free (a test's runs stop instead, and the test says why).
524
+ - **Proseg's own count, bounded too.** The counts the app asks proseg for wait in a folder on the RAM disk (or the
525
+ temporary folder), at most `[analysis] counts_spool_mb` (1 GB) a run and twice that in all, and go with the run; those
526
+ of the first iteration, the switch to 1 µm voxels and the end stay in the run's folder. The app asks for them so that
527
+ counting takes about a tenth of proseg's time at most, and counting never changes what proseg samples (seeded, it
528
+ saves byte for byte what proseg saves without it).
529
+ - **Writing into the sample's zarr is all-or-nothing.** Names follow SpatialData's rules and never silently replace
530
+ anything; a replaced element is moved aside first and put back if anything fails, also after a crash. Every step is
531
+ written to a journal before it is taken; the next write into that zarr rolls back that zarr's own interrupted ones
532
+ only (never another zarr's whose name begins alike), and only once the process that wrote them has ended; a write that
533
+ finds another session's write into the same zarr under way refuses, touching nothing. A folder kept for a write that
534
+ could not be rolled back whole is left in `.proseg-live-backups` beside the zarr, never deleted. Writes into one zarr
535
+ never overlap, and the app waits for a running one before it closes. Apart from what you add, the app only reads
536
+ your sample.
537
+ - **Graphics memory.** If the GPU cannot hold an upload the page rebuilds its view; a second loss within a minute halves
538
+ the size of the images in use.
539
+ - **Diagnostics stay on this computer.** While a run is open the page sends the engine a performance report every 10 s
540
+ (how often it draws, long tasks, memory, the display and GPU renderer, what it downloaded; no cell, run or file name).
541
+ They are kept in `<state_dir>/logs/telemetry.jsonl` (at most 5 MB plus one older file). The page also keeps its own
542
+ log with the engine (`<state_dir>/logs/page-logs/`, the newest 6) for the crash reports in
543
+ `<state_dir>/crash-reports/` (the newest 10, with the session's secrets blanked).
544
+ - **Network use.** The engine and page talk over loopback only. Downloads happen only when needed: a Cellpose built-in
545
+ model missing from Cellpose's cache.
546
+
547
+ ## Licence
548
+
549
+ - **proseg** is Copyright (C) 2024 Daniel C. Jones and licensed under the GNU General Public License v3.
550
+ `proseg-live` is proseg 3.2.0 with this repository's `native/proseg-live.patch`; it is derived from proseg and
551
+ covered by the GPL v3, and whoever passes it on must do so under its terms, with the source. It is a package of its
552
+ own (`native/package/`): every release carries its complete source, `proseg_live-<version>.tar.gz` (proseg's crate
553
+ with the patch applied, its `Cargo.lock`, the patch itself and proseg's licence), beside its wheels, which carry the
554
+ licence too.
555
+ - The app runs `proseg-live` as a separate program and talks to it through files and a control file; the
556
+ `sopa-companion` package holds no GPL code. Its dependencies (FastAPI, uvicorn, numpy, zarr, sopa, spatialdata,
557
+ Cellpose, scvi-tools, RAPIDS and others) are installed separately, each under its own licence.
558
+ - **The app's own code** (everything outside `native/`) is under the BSD 3-Clause licence: see
559
+ [LICENSE](https://github.com/jackytamkc/sopa-companion/blob/main/LICENSE).
560
+
561
+ To cite the app, see [CITATION.cff](https://github.com/jackytamkc/sopa-companion/blob/main/CITATION.cff) (GitHub's
562
+ "Cite this repository"). Every release is archived on
563
+ Zenodo: [10.5281/zenodo.24116670](https://doi.org/10.5281/zenodo.24116670) names all versions and leads to each
564
+ version's own DOI.