Docs and IO

.gitignore

@@ -12,5 +12,7 @@ generated
 apidocs
 dist
 jupyter_execute
+.ipynb_checkpoints
+*.pickle
 
 settings.json

.pre-commit-config.yaml

@@ -21,6 +21,7 @@ repos:
     rev: v0.15.15
     hooks:
       - id: ruff-check
+        exclude: ^docs/source/.*/(?:tips|export)\.ipynb$
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v2.1.0

docs/source/conf.py

@@ -80,7 +80,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path: list[str] = []
+html_static_path = ["_static"]
 
 
 def skip_submodules(app, what, name, obj, skip, options):

docs/source/index.rst

@@ -1,30 +1,36 @@
 What is sainsc?
 ===================
 
-sainsc (pronounced /ˈsaiəns/) is a segmentation-free analysis tool for spatial
+.. |audio_science| raw:: html
+
+   <button onclick="new Audio('_static/science.mp3').play()"
+           style="border:none;background:none;cursor:pointer;padding:0;">
+     🔊
+   </button>
+
+sainsc (pronounced /ˈsaiəns/|audio_science|, i.e., 'science') is a segmentation-free analysis tool for spatial
 transcriptomics from in situ capture technologies (but also works for
 imaging-based technologies).
 
 It is easily integratable with the `scverse <https://github.com/scverse>`_
-(i.e. `scanpy` and `squidpy`) by exporting data in
+(i.e., `scanpy` and `squidpy`) by exporting data in
 `AnnData <https://anndata.readthedocs.io/>`_ or
 `SpatialData <https://spatialdata.scverse.org/>`_ format.
 
 Citations
 ---------
 
-If you are using `sainsc` for your research please cite
+If you are using `sainsc` for your research, please cite
 
 N. Müller-Bötticher, S. Tiesmeyer, R. Eils, N. Ishaque, "Sainsc: A Computational Tool
-for Segmentation-Free Analysis of In Situ Capture Data" *Small Methods* (2025)
-https://doi.org/10.1002/smtd.202401123
+for Segmentation-Free Analysis of In Situ Capture Data" *Small Methods* 9, 2401123 (2025)
+doi: `10.1002/smtd.202401123 <https://doi.org/10.1002/smtd.202401123>`_
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Contents:
 
    self
    quickstart
    installation
-   usage
    tutorials/index

docs/source/installation.rst

@@ -36,26 +36,41 @@ If you prefer the installation using
     to speed up the installation.
 
 
-From GitHub
+From Source
 -----------
 
+If you want to to build the package from source (either from GitHub or PyPI) you will need a Rust compiler.
+You can follow the `official Rust documentation <https://www.rust-lang.org/tools/install>`_ or,
+if you are using ``conda`` install it via ``conda install conda-forge::rust``.
+
+To build the package from PyPI use
+
+.. code-block:: bash
+
+    pip install --no-binary sainsc
+
+
+GitHub
+~~~~~~
+
 You can install the latest versions directly from
-`GitHub <https://github.com/HiDiHlabs/sainsc>`_. To do so clone the repository using the
-``git clone`` command. Navigate into the downloaded directory and install using
+`GitHub <https://github.com/HiDiHlabs/sainsc>`_.
+To do so clone the repository using the ``git clone`` command.
+Navigate into the downloaded directory and install using
 
 .. code-block:: bash
 
     pip install .
 
-.. note::
-    If you want to to install the package from source (either from GitHub or with
-    ``pip install --no-binary sainsc``) you will need a Rust compiler. You can follow
-    the `official Rust documentation <https://www.rust-lang.org/tools/install>`_ or,
-    if you are using ``conda`` install it via ``conda install conda-forge::rust``.
-
 If you want to install the development version you can install the additional optional
 dependencies with
 
 .. code-block:: bash
 
     pip install -e .[dev]
+
+
+.. warning::
+
+    If you install editable builds (``-e``) the Rust compiler will default to a debug build,
+    i.e., the code is not optimized and slow. Don't use this for analysis (only for development)!

docs/source/quickstart.ipynb

@@ -83,7 +83,7 @@
    ],
    "source": [
     "# location of the Stereo-seq data\n",
-    "data_path = Path(\"path/to/StereoSeq/data\")\n",
+    "data_path = Path(\"path/to/stereoseq_data\")\n",
     "\n",
     "brain = read_StereoSeq(\n",
     "    data_path / \"Mouse_brain_Adult_GEM_bin1.tsv.gz\", resolution=500, n_threads=8\n",
@@ -331,9 +331,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python [conda env:sainsc]",
    "language": "python",
-   "name": "python3"
+   "name": "conda-env-sainsc-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -345,7 +345,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.11.10"
   }
  },
  "nbformat": 4,

docs/source/tutorials/VisiumHD_CRC.ipynb

@@ -19,9 +19,9 @@
     "tags": []
    },
    "source": [
-    "In this tutorial we will look at a colorectal cancer (CRC) sample profiled using VisiumHD. The data is available from the 10X website (see [here](https://www.10xgenomics.com/datasets/visium-hd-cytassist-gene-expression-libraries-of-human-crc)).\n",
+    "In this tutorial, we will look at a colorectal cancer (CRC) sample profiled using VisiumHD. The data is available from the 10x Genomics website (see [here](https://www.10xgenomics.com/datasets/visium-hd-cytassist-gene-expression-libraries-of-human-crc)).\n",
     "\n",
-    "To follow along you will need to download the data and install some additional packages;\n",
+    "To follow along, you will need to download the data and install some additional packages;\n",
     "`scanpy` and `spatialdata_io`."
    ]
   },
@@ -116,9 +116,11 @@
     "tags": []
    },
    "source": [
-    "First we will generate cell type signature based on the 16 µm bins VisiumHD. Theoretically this should also work when using the 8 µm bins or segmentation-based cells. The signatures are then later used to map the cell types to the original 2 µm resolution.\n",
+    "First, we will generate cell-type signatures based on the 16 µm bins in VisiumHD.\n",
+    "Theoretically, this should also work when using the 8 µm bins or segmentation-based cells.\n",
+    "The signatures are then later used to map the cell types to the original 2 µm resolution.\n",
     "\n",
-    "This whole section can be replaced by your favorite single-cell workflow. We will follow a simple workflow here as this is not the main purpose of this tutorial."
+    "This whole section can be replaced by your favorite single-cell workflow. We will follow a simple workflow here, as this is not the main purpose of this tutorial."
    ]
   },
   {
@@ -230,7 +232,9 @@
     "tags": []
    },
    "source": [
-    "Now we apply our favorite workflow to find clusters/cell types. Remember that you can adjust the processing here to your liking! For example you could switch to spatially variable genes instead of highly variable."
+    "Now we apply our favorite workflow to find clusters/cell types.\n",
+    "Remember that you can adjust the processing here to your liking!\n",
+    "For example, you could switch to spatially variable genes instead of highly variable."
    ]
   },
   {
@@ -352,7 +356,9 @@
    "source": [
     "Now we are ready to generate the cell type signatures.\n",
     "\n",
-    "The only thing to keep in mind if you don't follow the workflow above is that the signatures should be non-negative i.e. they should not be generated from z-scores or Pearson residuals, etc. which does not mean that you can't use these methods to do the cell typing just make sure to use the log-transformed counts to calculate the signatures.\n",
+    "The only thing to keep in mind if you don't follow the workflow above is that the signatures should be non-negative, i.e., they should not be generated from z-scores or Pearson residuals, etc.\n",
+    "This does not mean that you can't use these methods to do the cell typing.\n",
+    "Just make sure to use the log-transformed counts to calculate the signatures.\n",
     "\n",
     "Here, we will only use the highly variable genes."
    ]
@@ -609,9 +615,9 @@
     "tags": []
    },
    "source": [
-    "To compare the cell typing we will plot the unbinned and binned data next to each other.\n",
+    "To compare the cell typing, we will plot the unbinned and binned data next to each other.\n",
     "\n",
-    "First lets get the images for the cell typing of the unbinned data. "
+    "First, let's get the images for the cell typing of the unbinned data. "
    ]
   },
   {
@@ -692,7 +698,8 @@
     "tags": []
    },
    "source": [
-    "Now we are ready to compare the results. We will also include the KDE as it gives us an orientation of what the tissue looks like. "
+    "Now we are ready to compare the results.\n",
+    "We will also include the KDE, as it gives us an orientation of what the tissue looks like. "
    ]
   },
   {