Migration guide to sopa>=2.0.0

[quentinblampey]

We decompose the migration guide into three migration guides (Snakemake / API / CLI). Most changes concern the API.

If you experience issues related to sopa==2.0.0 that are not listed below, please add a comment below, it can help other users.

New requirements

We dropped support for python==3.9, but we now support python 3.10 to 3.12 (included).

In any case, we recommend creating a new fresh environment to install the new version of Sopa.

👨‍💻 API

Refer to the new API tutorial to see the new recommended usage of the API. The main features/changes are described below.

API new features

• Dask parallelization backend for faster segmentation (useful for API users). This can be done via sopa.settings.parallelization_backend = 'dask'. More details in the FAQ.
• Support for one-line segmentation, e.g. sopa.segmentation.cellpose(sdata, ...) or sopa.segmentation.baysor(sdata, ...). This will implicitly use the selected parallelization backend. See the documentation here.
• Spatial elements keys are saved in sdata.attrs so that Sopa knows automatically which element should be used in which function. It is still possible to precise image_key / points_key / shapes_key if needed. More details in the FAQ.
• Allows changing the auto-save settings (i.e. decide if spatial elements are saved on-disk automatically or not). This can be done via sopa.settings.auto_save_on_disk = False. See here.
• Can recover a failed/stopped segmentation when using the API (and also force a segmentation, for Baysor). See here.
• Better cache handling (invisible to API users). For advanced users, cache information can be found using these functions.
• New tissue segmentation for non-H&E data (sopa.segmentation.tissue)
• Bins aggregation (for VisiumHD-like data). See the corresponding tutorial and the aggregate_bins function.
• Support Stardist segmentation via sopa.segmentation.stardist

API migration guide

• sopa.segmentation.Patches2D is deprecated. Instead, use the functions sopa.make_image_patches or sopa.make_transcript_patches. See here.
• Optional arguments of sopa.segmentation.tissue are now more explicit (e.g., blur_kernel_size instead of blur_k).
• The image patches are now called sdata["image_patches"] instead of sdata["sopa_patches"]
• Use sopa.overlay_segmentation instead of sopa.segmentation.overlay_segmentation
• The Aggregator class has been replaced by a simple function wrapper: sopa.aggregate
• The annotations methods are moved to the utils. For instance, use sopa.utils.higher_z_score instead of sopa.annotation.higher_z_score

🐍 Snakemake pipeline

Refer to the new Snakemake usage tutorial to see the new recommended usage of Snakemake. The main features/changes are described below.

Snakemake pipeline new features

• Tissue segmentation has been added. This can be used by adding a tissue section inside the segmentation section. Inside it, use mode: "saturation" for H&E based tissue segmentation, or mode: "staining" for staining based tissue segmentation.

Snakemake pipeline migration guide

• We recommend using snakemake>=8.0.0, as detailed in the getting started, and having it in a separate environment (a snakemake env separated from the sopa environment).
• For Slurm users: the slurm profile has been updated for snakemake>=8.0.0. Refer to our new Snakemake tutorial to see what changed and how to use it. In particular, you'll need a Slurm plugin: pip install snakemake-executor-plugin-slurm. Also, the logs are now located in sopa/workflow/.snakemake/slurm_logs/rule_<name>/<job-id>.log.
• All the configs should be backward compatible.
• For baysor, we now recommend having a baysor alias, or having the executable at ~/.julia/bin/baysor, instead of setting the executable path in the config under config['executables']['baysor'].

⚙️ CLI

Refer to the new CLI usage tutorial to see the new recommended usage of the CLI. The main features/changes are described below.

CLI new features

• Each segmentation method can be run with a parallelization backend, for instance via exporting the following env variable: export SOPA_PARALLELIZATION_BACKEND=dask.
• If you don't pass --patch-index, it will run automatically on all patches with the selected parallelization backend, making the CLI usage much more simple.
• sopa segmentation tissue has been added.
• sopa segmentation baysor has been added (simplifying the usage of Baysor).
• The cache handling is now totally invisible to the user.
• Support for Visium HD (the commands are the same)

CLI migration guide

• sopa read has been renamed sopa convert to avoid confusion.
• During segmentation, use --cache-dir-name instead of --patch-dir