Migrating from scimap¶

SCIMAP Pro is a deliberate API break. Nothing is aliased, nothing is deprecated in place — an old script will not run unchanged, and it will tell you so with a TypeError rather than doing the wrong thing quietly.

Three rules cover most of the work:

adata is now data, and it is always the first argument. It also accepts an .h5ad path, a SpatialData, or a .zarr store.
Parameters are camelCase. imageid → imageId, random_state → randomState, n_pcs → nPcs.
Namespaces are short. scimap.preprocessing → scimappro.pp, scimap.tools → scimappro.tl, scimap.plotting → scimappro.pl. Helpers live in scimappro.pp, scimappro.tl, or scimappro.helpers depending on what they do.

# scimap
import scimap as sm
sm.tl.spatial_interaction(adata, imageid="imageid", subset_phenotype=["Treg"])

# scimappro
import scimappro as sp
sp.tl.spatialCooccurrence(adata, imageId="imageid")

Function names¶

Several functions were renamed to say what they measure rather than how they are implemented.

Preprocessing¶

scimap	SCIMAP Pro
`sm.pp.mcmicro_to_scimap`	`sp.pp.mcmicro_to_scimap`
`sm.pp.log1p(layer=…)`	`sp.pp.log1p(targetLayer=…)`
`sm.pp.rescale`	`sp.pp.rescale`
`sm.pp.combat`	`sp.pp.combat`

Tools¶

scimap	SCIMAP Pro
`sm.tl.phenotype_cells`	`sp.tl.phenotype`
`sm.tl.cluster`	`sp.tl.cluster`
`sm.tl.spatial_cluster(df_name=…)`	`sp.tl.cluster(mode="spatial", layer=…)`
`sm.tl.umap`	`sp.tl.umap`
`sm.tl.foldchange`	`sp.tl.foldChange`
`sm.tl.spatial_distance`	`sp.tl.spatialDistance`
`sm.tl.spatial_interaction`	`sp.tl.spatialCooccurrence`
`sm.tl.spatial_count`	`sp.tl.neighCount`
`sm.tl.spatial_expression`	`sp.tl.neighExp`
`sm.tl.spatial_lda`	`sp.tl.neighLDA`
— (new)	`sp.tl.neighNMF`
`sm.tl.spatial_pscore`	`sp.tl.spatialProximityScore`
`sm.tl.spatial_aggregate`	`sp.tl.spatialAggregate`
`sm.tl.spatial_similarity_search`	`sp.tl.spatialSimilarityLookup`

Plotting¶

scimap	SCIMAP Pro
`sm.pl.stacked_barplot`	`sp.pl.barplot`
`sm.pl.heatmap`	`sp.pl.heatmap`
`sm.pl.spatial_scatterPlot`	`sp.pl.spatialScatterPlot`
`sm.pl.spatial_distance`	`sp.pl.spatialDistanceHeatmap` / `spatialDistanceDistribution`
`sm.pl.spatial_interaction`	`sp.pl.spatialCooccurrence`
`sm.pl.spatialInteractionNetwork`	`sp.pl.spatialInteractionNetwork`
`sm.pl.spatial_pscore`	`sp.pl.spatialProximityScore`
`sm.pl.cluster_plots`	`sp.pl.clusterPlots`
`sm.pl.addROI_image`	`sp.pl.addRoiScatter` / `addRoiImage`
`sm.pl.image_viewer`	`sp.pl.image_viewer`
`sm.pl.pie`, `voronoi`, `distPlot`, `densityPlot2D`, `foldchange`, `markerCorrelation`, `groupCorrelation`, `umap`	same names in `sp.pl` (`foldchange` → `foldChange`)

Helpers¶

scimap	SCIMAP Pro
`sm.hl.classify`	`sp.tl.classify`
`sm.hl.rename`	`sp.tl.rename`
`sm.hl.dropFeatures`	`sp.pp.dropFeatures`
`sm.hl.merge_adata_obs`	`sp.pp.mergeAdataObs`
`sm.hl.scimap_to_csv`	`sp.pp.scimapToCsv`
`sm.hl.addROI_omero`	`sp.helpers.addROI_omero`

Parameter names¶

scimap	SCIMAP Pro
`adata`	`data`
`imageid`	`imageId`
`x_coordinate`, `y_coordinate`	`xCoordinate`, `yCoordinate`
`from_group`, `to_group`	`fromGroup`, `toGroup`
`subset_phenotype`	`subsetPhenotype`
`subset_genes`	`subsetMarkers`
`n_pcs`	`nPcs`
`random_state`	`randomState`
`gmm_components`	`gmmComponents`
`nearest_neighbors`	`leidenNearestNeighbors` (or the method-specific neighbour parameter)
`n_neighbors`, `n_components`, `min_dist`	`nNeighbors`, `nComponents`, `minDist`
`pheno_threshold_percent`, `pheno_threshold_abs`	`phenoThresholdPercent`, `phenoThresholdAbs`
`x_axis`, `y_axis`	`xAxis`, `yAxis`
`saveDir` + `fileName`	`outputDir` (+ `fileName` where the function still takes one)

groupBy, standardScale, subsetMarkers, and other already-camelCase names are unchanged.

Things with no direct equivalent¶

scimap	Status in SCIMAP Pro
`sm.tl.spatial_cluster`	Folded into `tl.cluster(mode="spatial", layer=<uns key>)` rather than re-exported as `spatialCluster`.
`sm.hl.animate`	Not ported.
`sm.pl.gate_finder`, `sm.pl.napariGater`	Not ported. Compute gates with `pp.rescale` (which fits a GMM per marker when no `gate` is given), or supply a `manual_gates.csv`.

New in SCIMAP Pro¶

These have no scimap counterpart at all:

Function / parameter	What it does
`pp.toSpatialData`	Convert a scimap-style `AnnData` into a scverse `SpatialData` store.
`sdataTable=`	Names the `SpatialData` table to work on. Always the last named parameter. See SpatialData.
`streamData=`	Runs the function out of core against an `.h5ad` on disk. See Streaming.
`maxWorkers=`	Caps parallelism over images/permutations.
`tl.neighNMF`	Non-negative matrix factorisation of neighbourhood composition.

Output keys¶

Result keys mostly kept their scimap spelling so existing downstream code that reads adata.uns keeps working, but the label default is worth checking:

Function	Default `label`	Written to
`tl.phenotype`	`phenotype`	`obs[label]`
`tl.cluster`	method name (`kmeans`, …)	`obs[label]`
`tl.umap`	`umap`	`obsm[label]`
`tl.classify`	`classify`	`obs[label]`
`tl.rename`	— (`toColumn`)	`obs[toColumn]`
`tl.spatialDistance`	`spatial_distance`	`uns[label]`
`tl.spatialCooccurrence`	`spatialCooccurrence`	`uns[label]`
`tl.spatialProximityScore`	`spatial_pscore`	`uns[label]` and `obs[label]`
`tl.spatialAggregate`	`spatialAggregate`	`obs[label]`
`tl.neighCount`	`neighCount`	`uns[label]`
`tl.neighExp`	`neighExp`	`uns[label]`
`tl.neighLDA`	`neighLDA`	`uns[label]`, `uns[label + "_probability"]`
`tl.neighNMF`	`neighNMF`	`uns[label]`, `uns[label + "_nmf_components"]`
`tl.foldChange`	`foldchange`	`uns[label + "_fc"]`, `uns[label + "_pval"]`
`tl.spatialSimilarityLookup`	`spatialSimilarityLookup`	`layers[label]` and `obs[label + "_<roi>"]`

pl.spatialCooccurrence and pl.spatialInteractionNetwork also accept the legacy key spatial_interaction when spatialCooccurrence is absent, so results carried over from an old analysis still plot.

Installing both side by side¶

scimappro does not import or depend on scimap, so the two can live in one environment:

pip install scimap scimappro

import scimap as sm
import scimappro as sp

They share the AnnData format, so an object produced by one can be read by the other.