stLearn 1.5.0

CONTRIBUTING.rst

@@ -15,7 +15,7 @@ Types of Contributions
 Report Bugs
 ~~~~~~~~~~~
 
-Report bugs at https://github.com/BiomedicalMachineLearning/stLearn/issues
+Report bugs at https://github.com/GenomicsMachineLearning/stLearn2/issues
 
 If you are reporting a bug, please include:
 

HISTORY.rst

@@ -2,6 +2,123 @@
 History
 =======
 
+1.5.0 (2026-11-01)
+------------------
+This release contains changes in cell-cell interaction (CCI) mainly
+improvements in runtime and memory usage and requires code to be updated.
+
+* Memory usage is reduced through chunking (~256MB) in ```st.cci.run```
+  scoring and permutation testing ~5,000,000 bins @ 20GB in ~20 minutes.
+* SpatialData support added with a new ``st.io`` package. Supporting:
+  ``atera``, ``xenium``, ``visium_hd`` and ``visium``. Start of
+  spatial data native plotting with ``st.pl.sdata_plot`` and
+  ``st.pp.highly_variable_genes``.
+* New datasets available to download via ``visium_hd_sge`` and ``atera_sge``
+  and return SpatialData objects.
+* Upgraded ligand-receptor databases to connectomeDB2025 (human and mouse).
+* Ligand-receptor are an ``LRPairs`` object instead of an array of
+  'L_R' strings. It tracks the species and where each pair came from.
+  Pairs can be filtered and combined (``lrs.filter(...)``, ``lrs1 | lrs2``).
+  * ``st.tl.cci.run`` takes only ``LRPairs``; an array of 'L_R' names raises
+    ``TypeError``. Wrap strings with
+    ``st.tl.cci.LRPairs.from_names(names, species="human")``.
+  * ``st.tl.cci.lr_pairs(database, species)`` loads a database shipped with
+    stLearn: ``"connectomeDB2025"`` (default; human or mouse) or
+    ``"connectomeDB2020"`` (human).
+  * ``st.tl.cci.read_lr_pairs(path, species=...)``
+    reads your own csv/tsv of ligand and receptor columns.
+  * ``st.tl.cci.load_lrs`` is deprecated; use ``lr_pairs``, or
+    ``lr_pairs(...).names()`` for the old array. Note that ``lr_pairs()``
+    defaults to connectomeDB2025, where ``load_lrs()`` defaults to
+    connectomeDB2020.
+  * ``st.add.lr`` is removed; use ``read_lr_pairs`` or ``LRPairs.from_names``.
+  * The LR table from ``run`` stores each pair's source in ``var["source"]``
+    and the species in ``uns["lr_species"]``, which ``run_lr_go`` uses as its
+    default species.
+* Spatial trajectory and other APIs use cluster labels strings
+  (``cluster="6"``).
+* AnnData backwards compatibility available through ``st.io.attach_spatial``.
+* CCI results are now a LR table (AnnData) returned by ``st.tl.cci.run``.
+  A spots x LR pairs with summaries, scores and p-values in ``var``.
+  Downstream functions and plots now take ``lr_results``.
+* Support for microns through ``microns_per_pixel``,
+  ``st.utils.microns_to_pixels``, ``pixels_to_microns`` and
+  ``create_grid(bin_um=)``.
+* SME computes weights only between nearby spots and data is kept sparse
+  where possible.
+* ``extract_feature`` supports ConvNeXt and takes ``weights=``.
+* Upgrade libraries: pillow>=13.0.0,<14.0, numba>=0.64.0,
+  scikit-image>=0.25.0, torch>=2.5.0, matplotlib>=3.11,<4.0.
+
+API and Bug Fixes:
+
+* Fixed double application of scaling, adding instructions and warning for
+  image alignment in create_stlearn Bug #303.
+* A pair listed twice is now tested once - fixed Bug #305.
+* Incorrect labelling in CCI Plot - rows labelled "Senders", columns labelled
+  "Receivers" - should be the other way around Bugs #309, #363.
+* Input matrices with NaN are no longer processed in weighting matrix - fixed
+  Bug #310.
+* ``st.tl.cci.run(use_label=...)`` never applied cell heterogeneity weighting:
+  it read the cell-type data from the wrong key, found nothing, and weighted
+  every spot 1, so results were identical with and without ``use_label``. It
+  now weights by heterogeneity from cell-type proportions in ``uns[use_label]``
+  or per-cell labels in ``obs[use_label]``, and takes ``cell_prop_cutoff``.
+  CCI scores and significance change for any run that used ``use_label``.
+* ``run_cci`` changes: p-values calculated via permutation calculation
+  via  are ``(k+1)/(N+1)`` and can nolonger be 0, cutoff is now
+  ``p < p_cutoff``, and permutations are seeded through ``random_state``.
+* ``spot_mixtures`` matches cell types by exact name.
+* ``n_spots`` in the LR summary counted spots with a score above ``min_expr``,
+  while the ``min_spots`` filter counted spots with a score above 0, so the
+  reported count was not the one the filter used. Both now use score > 0;
+  ``n_spots`` goes up for weakly scoring pairs.
+* ``st.tl.cci.grid`` dropped cells that fell on the last row or column of the
+  grid or exactly on a square boundary. Every cell now lands in exactly one
+  square, so cell counts, summed expression and label proportions change,
+  mostly in edge squares.
+* ``lr_plot`` always drew ``lr_sig_scores`` whatever ``use_label`` asked for,
+  so a plot labelled ``p_adjs`` or ``neg_log10_p_adjs`` showed the masked
+  score instead. It now draws the statistic requested. ``lr_plot`` and
+  ``ccinet_plot`` also draw on a ``fig`` or ``ax`` you pass in rather than
+  opening a new figure, so they can go in subplots.
+* ``lr_plot`` / ``ccinet_plot`` use the ``fig`` / ``ax`` passed in rather
+  than creating their own.
+* Images in ``uns["spatial"]`` are now uint8 (0-255), not floats in [0, 1].
+* ``extract_feature`` tiles were fed as floats between 0-255 instead of 0-1.
+  Tiles are now read as uint8, so ``X_tile_feature`` and ``X_morphology``
+  change.
+* ``concatenate_spatial_adata``: the x and y offsets added to ``obsm["spatial"]``
+  for each tile were swapped, so spots landed on the wrong tile unless the tile
+  grid was symmetric. Tiles also keep their aspect ratio instead of being
+  stretched to ``fixed_size``, each sample is scaled by its own scale factor
+  rather than the first sample's, and ``fixed_size`` is (height, width) like a
+  NumPy shape.
+* ``read_merfish`` works again with new notebook.
+* ``read_10x`` reads 16-bit / signed PNGs and reports missing images clearly.
+* ``add.labels`` / ``add_loupe_clusters`` match by barcode
+* ``add.positions`` reads Space Ranger 2.0+ files
+* ``add.parsing`` assigned spots the wrong coordinates (they were written in a
+  different order from the spots in ``obs``), so every plot and anything using
+  ``obsm["spatial"]`` (neighbours, SME, CCI) was wrong. Each spot now gets its
+  own position.
+* SME fits each axis separately when finding neighbours.
+* Spatial trajectory: ``pseudotime`` orients by median pseudotime (paths may
+  differ), ``shortest_path_spatial_paga`` returns labels, plus fixes to
+  ``local_level``, ``weight_optimizing_local``, ``de_transition_plot`` and the
+  trajectory plots.
+* ``qc_plot`` no longer makes a dense copy.
+* ``stlearn.wrapper`` removed.
+* ``cci.grid`` vectorised and nolonger takes ``n_cpus``.
+* ``obsm["spatial"]`` is in full-resolution pixels (was image pixels), matching
+  the rest of stLearn.
+* SME outputs are sparse when ``X`` is sparse; no weight matrices in ``uns``.
+* Removed: ``extract_feature(cnn_base="xception")``,
+  ``deconvolution_plot(data_alpha=)``, ``local_plot(cluster=)``,
+  ``Spatial(basis=)``.
+* New defaults: trajectory ``node_size=60`` (area);
+  ``check_trajectory(size_spatial=7, img_key=None)``.
+
 1.4.1 (2026-06-16)
 ------------------
 * Improved speed of random spot generation used in permutation testing.

MANIFEST.in

@@ -8,5 +8,5 @@ recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 
 recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
-recursive-include stlearn/tl/cci/databases *.txt
+recursive-include stlearn/tl/cci/databases *.csv *.tsv
 recursive-include stlearn *.R

README.md

@@ -42,7 +42,7 @@
       <b>License</b>
     </td>
     <td>
-      <a href="https://github.com/BiomedicalMachineLearning/stLearn/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-BSD-blue.svg"
+      <a href="https://github.com/GenomicsMachineLearning/stLearn2/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-BSD-blue.svg"
         alt="LICENSE"></a>
     </td>
   </tr>

docs/api.rst

@@ -18,14 +18,43 @@ Wrapper functions: `wrapper`
 .. autosummary::
    :toctree: api/
 
-   read_10x
-   read_old_st
-   read_slide_seq
-   read_merfish
-   read_seq_fish
-   read_xenium
-   create_stlearn
    convert_scanpy
+   concatenate_spatial_adata
+
+
+Reading and writing: `io`
+------------------------------
+
+.. module:: stlearn.io
+.. currentmodule:: stlearn
+
+.. autosummary::
+   :toctree: api/
+
+   io.read_10x
+   io.read_xenium
+   io.read_old_st
+   io.read_slide_seq
+   io.read_merfish
+   io.read_seq_fish
+   io.create_stlearn
+
+.. autosummary::
+   :toctree: api/
+
+   io.visium
+   io.visium_hd
+   io.xenium
+   io.attach_spatial
+   io.attach_spatial_sdata
+   io.visium_scalefactors
+   io.xenium_pixel_size
+   io.crop_to_cells
+   io.crop_visium_hd
+   io.crop_xenium
+   io.save_table
+   io.checkpoint
+   io.store_checkpoint
 
 
 Add: `add`
@@ -39,9 +68,10 @@ Add: `add`
    add.image
    add.positions
    add.parsing
-   add.lr
    add.labels
    add.annotation
+   add.row_annotations
+   add.polygon_annotations
    add.add_loupe_clusters
    add.add_mask
    add.apply_mask
@@ -58,8 +88,10 @@ Preprocessing: `pp`
    :toctree: api/
 
    pp.filter_genes
+   pp.filter_cells
    pp.log1p
    pp.normalize_total
+   pp.highly_variable_genes
    pp.scale
    pp.neighbors
    pp.tiling
@@ -136,12 +168,25 @@ Tools: `tl`
 
    tl.clustering.kmeans
    tl.clustering.leiden
-   tl.cci.load_lrs
-   tl.cci.grid
+   tl.clustering.annotate_interactive
+   tl.label.run_label_transfer
+   tl.label.run_rctd
+   tl.label.run_single_r
+
+.. autosummary::
+   :toctree: api/
+
+   tl.cci.lr_pairs
+   tl.cci.read_lr_pairs
+   tl.cci.LRPairs
    tl.cci.run
    tl.cci.adj_pvals
+   tl.cci.lr_result
    tl.cci.run_lr_go
    tl.cci.run_cci
+   tl.cci.grid
+   tl.cci.create_grid
+   tl.cci.load_lrs
 
 Plot: `pl`
 -------------------
@@ -154,10 +199,13 @@ Plot: `pl`
    pl.qc_plot
    pl.gene_plot
    pl.gene_plot_interactive
+   pl.feat_plot
    pl.cluster_plot
    pl.cluster_plot_interactive
    pl.subcluster_plot
    pl.non_spatial_plot
+   pl.stack_3d_plot
+   pl.sdata_plot
    pl.deconvolution_plot
    pl.plot_mask
    pl.lr_summary
@@ -166,6 +214,8 @@ Plot: `pl`
    pl.lr_go
    pl.lr_result_plot
    pl.lr_plot
+   pl.het_plot
+   pl.grid_plot
    pl.cci_check
    pl.ccinet_plot
    pl.lr_chord_plot
@@ -184,6 +234,7 @@ Plot: `pl`
    pl.trajectory.tree_plot
    pl.trajectory.transition_markers_plot
    pl.trajectory.de_transition_plot
+   pl.trajectory.check_trajectory
 
 Datasets: `datasets`
 ---------------------------
@@ -194,4 +245,6 @@ Datasets: `datasets`
    :toctree: api/
 
    datasets.visium_sge
+   datasets.visium_hd_sge
    datasets.xenium_sge
+   datasets.atera_sge

docs/conf.py

@@ -1,6 +1,6 @@
 import os
-import zipfile
 import urllib.request
+import zipfile
 
 # -- Project information -----------------------------------------------------
 project = 'stLearn'
@@ -46,13 +46,13 @@ def setup(app):
 html_static_path = ['_static']
 html_css_files = ['css/custom.css']
 html_theme_options = {
-    "source_repository": "https://github.com/BiomedicalMachineLearning/stLearn/",
+    "source_repository": "https://github.com/GenomicsMachineLearning/stLearn2/",
     "source_branch": "master",
     "source_directory": "docs/",
     "footer_icons": [
         {
             "name": "GitHub",
-            "url": "https://github.com/BiomedicalMachineLearning/stLearn/",
+            "url": "https://github.com/GenomicsMachineLearning/stLearn2/",
             "html": """
             <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
                 <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.5.0.rst
+
 .. include:: release_notes/1.4.1.rst
 
 .. include:: release_notes/1.4.0.rst

docs/release_notes/1.4.1.rst

@@ -3,9 +3,9 @@
 
 .. rubric:: Features
 * Improved speed of random spot generation used in permutation testing.
+* Upgrade libraries: pillow>=12.0.0,<13.0
 
 .. rubric:: Bugs
 
 * Fixed up docstring and types for various CCI methods.
 * Fixes for issues #350 and #300 with incorrect types.
-* Upgrade libraries: pillow>=12.0.0,<13.0